Merge branch 'develop' into add_library_time_class

Author: dhthwy

conf.py

@@ -78,8 +78,7 @@ def write_tool_docs():
         os.makedirs(os.path.join('docs/tools', os.path.dirname(k[0])),
                     mode=0o755, exist_ok=True)
         with write_file_if_changed('docs/tools/{}.rst'.format(k[0])) as outfile:
-            if k[0] != 'search':
-                outfile.write(label)
+            outfile.write(label)
             outfile.write(include)
 
 

data/init/dfhack.tools.init

@@ -80,6 +80,7 @@
 
 # Enable system services
 enable buildingplan
+enable burrow
 enable confirm
 enable logistics
 enable overlay

docs/about/Removed.rst

@@ -191,6 +191,12 @@ gui/hack-wish
 =============
 Replaced by `gui/create-item`.
 
+.. _gui/mechanisms:
+
+gui/mechanisms
+==============
+Linked building interface has been added to the vanilla UI.
+
 .. _gui/no-dfhack-init:
 
 gui/no-dfhack-init
@@ -220,6 +226,12 @@ ruby
 Support for the Ruby language in DFHack scripts was removed due to the issues
 the Ruby library causes when used as an embedded language.
 
+.. _search-plugin:
+
+search
+======
+Functionality was merged into `sort`.
+
 .. _show-unit-syndromes:
 
 show-unit-syndromes

docs/changelog.txt

@@ -52,9 +52,11 @@ Template for new versions:
 # Future
 
 ## New Tools
+- `burrow`: (reinstated) automatically expand burrows as you dig
 
 ## New Features
 - `prospect`: can now give you an estimate of resources from the embark screen. hover the mouse over a potential embark area and run `prospect`.
+- `burrow`: integrated 3d box fill and 2d/3d flood fill extensions for burrow painting mode
 
 ## Fixes
 - `stockpiles`: hide configure and help buttons when the overlay panel is minimized
@@ -68,9 +70,12 @@ Template for new versions:
 
 ## API
 - ``Gui::revealInDwarfmodeMap``: gained ``highlight`` parameter to control setting the tile highlight on the zoom target
+- ``Maps::getWalkableGroup``: get the walkability group of a tile
 
 ## Lua
 - ``dfhack.gui.revealInDwarfmodeMap``: gained ``highlight`` parameter to control setting the tile highlight on the zoom target
+- ``dfhack.maps.getWalkableGroup``: get the walkability group of a tile
+- ``gui.FRAME_THIN``: a panel frame suitable for floating tooltips
 
 ## Removed
 

docs/dev/Lua API.rst

@@ -1912,10 +1912,11 @@ Maps module
 
   Returns the plant struct that owns the tile at the specified position.
 
-* ``dfhack.maps.canWalkBetween(pos1, pos2)``
+* ``dfhack.maps.getWalkableGroup(pos)``
 
-  Checks if a dwarf may be able to walk between the two tiles,
-  using a pathfinding cache maintained by the game.
+  Returns the walkability group for the given tile position. A return value of
+  ``0`` indicates that the tile is not walkable. The data comes from a
+  pathfinding cache maintained by DF.
 
   .. note::
     This cache is only updated when the game is unpaused, and thus
@@ -1924,6 +1925,10 @@ Maps module
     take into account anything that depends on the actual units, like
     burrows, or the presence of invaders.
 
+* ``dfhack.maps.canWalkBetween(pos1, pos2)``
+
+  Checks if both positions are walkable and also share a walkability group.
+
 * ``dfhack.maps.hasTileAssignment(tilemask)``
 
   Checks if the tile_bitmask object is not *nil* and contains any set bits; returns *true* or *false*.
@@ -1944,9 +1949,11 @@ Maps module
 Burrows module
 --------------
 
-* ``dfhack.burrows.findByName(name)``
+* ``dfhack.burrows.findByName(name[, ignore_final_plus])``
 
-  Returns the burrow pointer or *nil*.
+  Returns the burrow pointer or *nil*. if ``ignore_final_plus`` is ``true``,
+  then ``+`` characters at the end of the names are ignored, both for the
+  specified ``name`` and the names of the burrows that it matches against.
 
 * ``dfhack.burrows.clearUnits(burrow)``
 
@@ -4578,6 +4585,10 @@ There are the following predefined frame style tables:
 
   A frame suitable for overlay widget panels.
 
+* ``FRAME_THIN``
+
+  A frame suitable for floating tooltip panels that need the DFHack signature.
+
 * ``FRAME_BOLD``
 
   A frame suitable for a non-draggable panel meant to capture the user's focus,
@@ -5603,51 +5614,6 @@ Native functions provided by the `buildingplan` plugin:
 * ``void doCycle()`` runs a check for whether buildings in the monitor list can be assigned items and unsuspended. This method runs automatically twice a game day, so you only need to call it directly if you want buildingplan to do a check right now.
 * ``void scheduleCycle()`` schedules a cycle to be run during the next non-paused game frame. Can be called multiple times while the game is paused and only one cycle will be scheduled.
 
-burrows
-=======
-
-The `burrows` plugin implements extended burrow manipulations.
-
-Events:
-
-* ``onBurrowRename.foo = function(burrow)``
-
-  Emitted when a burrow might have been renamed either through
-  the game UI, or ``renameBurrow()``.
-
-* ``onDigComplete.foo = function(job_type,pos,old_tiletype,new_tiletype,worker)``
-
-  Emitted when a tile might have been dug out. Only tracked if the
-  auto-growing burrows feature is enabled.
-
-Native functions:
-
-* ``renameBurrow(burrow,name)``
-
-  Renames the burrow, emitting ``onBurrowRename`` and updating auto-grow state properly.
-
-* ``findByName(burrow,name)``
-
-  Finds a burrow by name, using the same rules as the plugin command line interface.
-  Namely, trailing ``'+'`` characters marking auto-grow burrows are ignored.
-
-* ``copyUnits(target,source,enable)``
-
-  Applies units from ``source`` burrow to ``target``. The ``enable``
-  parameter specifies if they are to be added or removed.
-
-* ``copyTiles(target,source,enable)``
-
-  Applies tiles from ``source`` burrow to ``target``. The ``enable``
-  parameter specifies if they are to be added or removed.
-
-* ``setTilesByKeyword(target,keyword,enable)``
-
-  Adds or removes tiles matching a predefined keyword. The keyword
-  set is the same as used by the command line.
-
-The lua module file also re-exports functions from ``dfhack.burrows``.
-
 .. _cxxrandom-api:
 
 cxxrandom

docs/images/search-stockpile.png

@@ -0,0 +1,115 @@
+burrow
+======
+
+.. dfhack-tool::
+    :summary: Quickly adjust burrow tiles and units.
+    :tags: fort auto design productivity units
+
+This tool has two modes. When enabled, it monitors burrows with names that end
+in ``+``. If a wall at the edge of such a burrow is dug out, the burrow will be
+automatically extended to include the newly-revealed adjacent walls. If a miner
+digs into an open space, such as a cavern, the open space will *not* be
+included in the burrow.
+
+When run as a command, it can quickly adjust which tiles and/or units are
+associated with the burrow.
+
+Usage
+-----
+
+::
+
+    enable burrow
+    burrow tiles|units clear <target burrow> [<target burrow> ...] [<options>]
+    burrow tiles|units set|add|remove <target burrow> <burrow> [...] [<options>]
+    burrow tiles box-add|box-remove <target burrow> [<pos>] [<pos>] [<options>]
+    burrow tiles flood-add|flood-remove <target burrow> [<options>]
+
+The burrows can be referenced by name or by the internal numeric burrow ID. If
+referenced by name, the first burrow that matches the name (case sensitive)
+will be targeted. If a burrow name ends in ``+`` (to indicate that it should be
+auto-expanded), the final ``+`` does not need to be specified on the
+commandline.
+
+For ``set``, ``add``, or ``remove`` commands, instead of a burrow, you can
+specify one of the following all-caps keywords:
+
+- ``ABOVE_GROUND``
+- ``SUBTERRANEAN``
+- ``INSIDE``
+- ``OUTSIDE``
+- ``LIGHT``
+- ``DARK``
+- ``HIDDEN``
+- ``REVEALED``
+
+to add or remove tiles with the corresponding properties.
+
+Flood fill selects tiles spreading out from a starting tile if they:
+
+- match the inside/outside and hidden/revealed properties of the starting tile
+- match the walkability group of the starting tile OR (if the starting tile is
+  walkable) is adjacent to a tile with the same walkability group as the
+  starting tile
+
+When flood adding, the flood fill will also stop at any tiles that have already
+been added to the burrow. Similarly for flood removing, the flood will also
+stop at tiles that are not in the burrow.
+
+Examples
+--------
+
+``enable burrow``
+    Start monitoring burrows that have names ending in '+' and automatically
+    expand them when walls that border the burrows are dug out.
+``burrow tiles clear Safety``
+    Remove all tiles from the burrow named ``Safety`` (in preparation for
+    adding new tiles elsewhere, presumably).
+``burrow units clear Farmhouse Workshops``
+    Remove all units from the burrows named ``Farmhouse`` and ``Workshops``.
+``multicmd burrow tiles set Inside INSIDE; burrow tiles remove Inside HIDDEN``
+    Reset the burrow named ``Inside`` to include all the currently revealed,
+    interior tiles.
+``burrow units set "Core Fort" Peasants Skilled``
+    Clear all units from the burrow named ``Core Fort``, then add units
+    currently assigned to the ``Peasants`` and ``Skilled`` burrows.
+``burrow tiles box-add Safety 0,0,0``
+    Add all tiles to the burrow named ``Safety`` that are within the volume of
+    the box starting at coordinate 0, 0, 0 (the upper left corner of the bottom
+    level) and ending at the current location of the keyboard cursor.
+``burrow tiles flood-add Safety --cur-zlevel``
+    Flood-add the tiles on the current z-level with the same properties as the
+    tile under the keyboard cursor to the burrow named ``Safety``.
+
+Options
+-------
+
+``-c``, ``--cursor <pos>``
+    Indicate the starting position of the box or flood fill. If not specified,
+    the position of the keyboard cursor is used.
+``-z``, ``--cur-zlevel``
+    Restricts a flood fill operation to the currently visible z-level.
+
+Note
+----
+
+If you are auto-expanding a burrow (whose name ends in a ``+``) and the miner
+who is digging to expand the burrow is assigned to that burrow, then 1-wide
+corridors that expand the burrow will have very slow progress. This is because
+the burrow is expanded to include the next dig job only after the miner has
+chosen a next tile to dig, which may be far away. 2-wide cooridors are much
+more efficient when expanding a burrow since the "next" tile to dig will still
+be nearby.
+
+Overlay
+-------
+
+When painting burrows in the vanilla UI, a few extra mouse operations are
+supported. If you box select across multiple z-levels, you will be able to
+select the entire volume instead of just the selected area on the z-level that
+you are currently looking at.
+
+In addition, double-clicking will start a flood fill from the target tile.
+
+The box and flood fill actions respect the UI setting for whether the burrow is
+being added to or erased.