MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update docs

develop
Myk Taylor 2023-10-28 00:37:02 -07:00
parent 73dbd6de65
commit 89a649c790
No known key found for this signature in database
1 changed files with 79 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
docs/plugins/burrow.rst
Unescape Escape View File

@ -1,46 +1,36 @@
burrows burrow
======= ======
.. dfhack-tool:: .. dfhack-tool::
:summary: Auto-expand burrows as you dig. :summary: Quickly adjust burrow tiles and units.
:tags: unavailable :tags: fort auto design productivity units
:no-command:
.. dfhack-command:: burrow This tool has two modes. When enabled, it monitors burrows with names that end
:summary: Quickly add units/tiles to burrows. 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.
When a wall inside a burrow with a name ending in ``+`` is dug out, the burrow When run as a command, it can quickly adjust which tiles and/or units are
will be extended to newly-revealed adjacent walls. associated with the burrow.
Usage Usage
----- -----
``burrow enable auto-grow`` ::
When a wall inside a burrow with a name ending in '+' is dug out, the burrow
will be extended to newly-revealed adjacent walls. This final '+' may be enable burrow
omitted in burrow name args of other ``burrow`` commands. Note that digging burrow tiles|units clear <target burrow> [<target burrow> ...] [<options>]
1-wide corridors with the miner inside the burrow is SLOW. burrow tiles|units set|add|remove <target burrow> <burrow> [...] [<options>]
``burrow disable auto-grow`` burrow tiles box-add|box-remove <target burrow> <pos> [<pos>] [<options>]
Disables auto-grow processing. burrow tiles flood-add|flood-remove <target burrow> [<options>]
``burrow clear-unit <burrow> [<burrow> ...]``
Remove all units from the named burrows. The burrows can be referenced by name or by the internal numeric burrow ID. If
``burrow clear-tiles <burrow> [<burrow> ...]`` referenced by name, all burrows that match the name (case sensitive) will be
Remove all tiles from the named burrows. included. If a burrow name ends in ``+`` (to indicate that it should be
``burrow set-units target-burrow <burrow> [<burrow> ...]`` auto-expanded), the final ``+`` does not need to be specified on the
Clear all units from the target burrow, then add units from the named source commandline.
burrows.
``burrow add-units target-burrow <burrow> [<burrow> ...]`` For ``set``, ``add``, or ``remove`` commands, instead of a burrow, you can
Add units from the source burrows to the target. specify one of the following all-caps keywords:
``burrow remove-units target-burrow <burrow> [<burrow> ...]``
Remove units in source burrows from the target.
``burrow set-tiles target-burrow <burrow> [<burrow> ...]``
Clear target burrow tiles and add tiles from the names source burrows.
``burrow add-tiles target-burrow <burrow> [<burrow> ...]``
Add tiles from the source burrows to the target.
``burrow remove-tiles target-burrow <burrow> [<burrow> ...]``
Remove tiles in source burrows from the target.
In place of a source burrow, you can use one of the following keywords:
- ``ABOVE_GROUND`` - ``ABOVE_GROUND``
- ``SUBTERRANEAN`` - ``SUBTERRANEAN``
@ -51,4 +41,57 @@ In place of a source burrow, you can use one of the following keywords:
- ``HIDDEN`` - ``HIDDEN``
- ``REVEALED`` - ``REVEALED``
to add tiles with the given properties. to add or remove tiles with the corresponding properties.
For flood fill, all tiles that match the properties (from the list above) of
the specified start tile will be included. 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.
``-d``, ``--dry-run``
Report what would be done, but don't actually change anything.
``-z``, ``--cur-zlevel``
Restricts the 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.