Improve plants/plant plugin

docs/Tags.rst

@@ -42,7 +42,7 @@ for the tag assignment spreadsheet.
 - `labors <labors-tag-index>`: Tools that deal with labor assignment.
 - `map <map-tag-index>`: Tools that interact with the game map.
 - `military <military-tag-index>`: Tools that interact with the military.
-- `plants <plants-tag-index>`: Tools that interact with trees, shrubs, and crops.
+- `plants <plants-tag-index>`: Tools that interact with grass, trees, shrubs, and crops.
 - `stockpiles <stockpiles-tag-index>`: Tools that interact with stockpiles.
 - `units <units-tag-index>`: Tools that interact with units.
 - `workorders <workorders-tag-index>`: Tools that interact with workorders.

docs/about/Removed.rst

@@ -247,6 +247,12 @@ petcapRemover
 =============
 Renamed to `pet-uncapper`.
 
+.. _plants:
+
+plants
+======
+Renamed to `plant`.
+
 .. _resume:
 
 resume

docs/changelog.txt

@@ -52,18 +52,22 @@ Template for new versions:
 # Future
 
 ## New Tools
+- `plant` (formerly `plants`): (reinstated) tool for creating/growing/removing plants
 
 ## New Features
 - `tweak`: ``named-codices``: display book titles instead of a material description in the stocks/trade screens
+- `plant` (formerly `plants`): can now ``remove`` shrubs and saplings; ``list`` all valid shrub/sapling raw IDs; ``grow`` can make mature trees older; many new command options
 
 ## Fixes
 - `suspendmanager`: stop suspending single tile stair constructions
 - ``Gui::makeAnnouncement``, ``Gui::autoDFAnnouncement``: fix skipping index 0 when iterating reports vector
+- `regrass`: don't remove mud on regrass, consistent with vanilla behavior
 
 ## Misc Improvements
 - `blueprint`: capture track carving designations in addition to already-carved tracks
 - `changevein`: affect connected veins even outside of the selected map block
 - `logistics`: new ability to automatically forbid or claim items brought to a stockpile (or a dump within a stockpile)
+- `regrass`: now accepts numerical IDs for grass raws; ``regrass --list`` replaces ``regrass --plant ""``
 
 ## Documentation
 - `installing`: add instructions for how to use Steam DFHack with non-Steam DF (for DFHack auto-updates and cloud backups)
@@ -83,6 +87,7 @@ Template for new versions:
 - ``widgets.FilteredList``: don't restrict the player from inputting multiple successive space characters
 
 ## Removed
+- `plants`: renamed to `plant`
 
 # 50.13-r2
 

docs/plugins/plant.rst

@@ -0,0 +1,164 @@
+plant
+=====
+
+.. dfhack-tool::
+    :summary: Grow and remove shrubs or trees.
+    :tags: adventure fort armok map plants
+
+Grow and remove shrubs or trees. Modes are ``list``, ``create``, ``grow``,
+and ``remove``. ``list`` prints a list of all valid shrub and sapling raw IDs.
+``create`` allows the creation of new shrubs and saplings. ``grow`` adjusts
+the age of saplings and trees, allowing them to grow instantly. ``remove`` can
+remove existing shrubs and saplings.
+
+Usage
+-----
+
+Provide a mode (including a ``plant_id`` for ``create``) followed by optional
+``pos`` arguments and options. The ``pos`` arguments can limit operation of
+``grow`` or ``remove`` to a single tile or a cuboid. ``pos`` should normally be
+in the form ``0,0,0``, without spaces. The string ``here`` can be used in place
+of numeric coordinates to use the position of the keyboard cursor, if active.
+
+::
+
+    plant list
+
+Prints a list of all shrub and sapling raw IDs for use with the other modes.
+Both numerical and string IDs are provided.
+
+::
+
+    plant create <plant_id> [<pos>] [<options>]
+
+Creates a new plant of the specified type at ``pos`` or the cursor position.
+The target must be a floor tile, consisting of soil, grass, ashes, or
+non-smooth muddy (layer, obsidian, or ore) stone. ``plant_id`` is not
+case-sensitive, but must be enclosed in quotes if spaces exist. (No unmodded
+shrub or sapling raw IDs have spaces.) A numerical ID can be used in place of a
+string. Use ``plant list`` for a list of valid IDs.
+
+::
+
+    plant grow [<pos> [<pos>]] [<options>]
+
+Grows saplings (including dead ones) into trees. Will default to all saplings
+on the map if no ``pos`` arguments are used. Saplings will die and fail to grow
+if they are blocked by another tree.
+
+::
+
+    plant remove [<pos> [<pos>]] [<options>]
+
+Remove plants from the map (or area defined by ``pos`` arguments.) By default,
+only removes invalid plants that exist on non-plant tiles (due to `Bug 12868
+<https://dwarffortressbugtracker.com/view.php?id=12868>`_.) The ``--shrubs``
+and ``--saplings`` options allow normal plants to be targeted instead. Removal
+of fully-grown trees isn't currently supported.
+
+Examples
+--------
+
+``plant list``
+    List all valid shrub and sapling raw IDs.
+``plant create tower_cap``
+    Create a Tower Cap sapling at the cursor.
+``plant create 203 -c -a tree``
+    Create a Willow sapling at the cursor, even away from water features,
+    ready to mature into a tree.
+``plant create single-grain_wheat 70,70,140``
+    Create a Single-grain Wheat shrub at (70, 70, 140.)
+``plant grow``
+    Attempt to grow all saplings on the map into trees.
+``plant grow -z -f maple,200,sand_pear``
+    Attempt to grow all Maple, Acacia, and Sand Pear saplings on the current
+    z-level into trees.
+``plant grow 0,0,100 19,19,119 -a 10``
+    Set the age of all saplings and trees (with their original sapling tile)
+    in the defined 20 x 20 x 20 cube to at least 10 years.
+``plant remove``
+    Remove all invalid plants from the map.
+``plant remove here -sp``
+    Remove the shrub or sapling at the cursor.
+``plant remove -spd``
+    Remove all dead shrubs and saplings from the map.
+``plant remove 0,0,49 0,0,51 -pz -e nether_cap``
+    Remove all saplings on z-levels 49 to 51, excluding Nether Cap.
+
+Create Options
+--------------
+
+``-c``, ``--force``
+    Create plant even on tiles flagged ``no_grow`` and unset the flag. This
+    flag is set on tiles that were originally boulders or pebbles, as well
+    as on some tiles found in deserts, etc. Also allow non-``[DRY]`` plants
+    (e.g., willow) to grow away (3+ tiles) from water features (i.e., pools,
+    brooks, and rivers,) and non-``[WET]`` plants (e.g., prickle berry) to
+    grow near them.
+``-a``, ``--age <value>``
+    Set the created plant to a specific age (in years.) ``value`` can be a
+    non-negative integer, or one of the strings ``tree``/``1x1`` (3 years,)
+    ``2x2`` (201 years,) or ``3x3`` (401 years.) ``value`` will be capped at
+    1250. Defaults to 0 if option is unused. Only a few tree types grow wider
+    than 1x1, but many may grow taller. (Going directly to higher years will
+    stunt height. It may be more desirable to instead use ``plant grow`` in
+    stages, or just spawn full trees using `gui/sandbox`.)
+
+Grow Options
+------------
+
+``-a``, ``--age <value>``
+    Define the age (in years) to set saplings to. ``value`` can be a
+    non-negative integer, or one of the strings ``tree``/``1x1`` (3 years,)
+    ``2x2`` (201 years,) or ``3x3`` (401 years.) ``value`` will be capped at
+    1250. Defaults to 3 if option is unused. If a ``value`` larger than 3 is
+    used, it will make sure even fully-grown trees have an age of at least the
+    given value, allowing them to grow larger. (Going directly to higher years
+    will stunt tree height. It may be more desirable to grow in stages rather
+    than all at once. Trees grow taller every 10 years.)
+``-f``, ``--filter <plant_id>[,<plant_id>...]``
+    Define a filter list of plant raw IDs to target, ignoring all other tree
+    types. ``plant_id`` is not case-sensitive, but must be enclosed in quotes
+    if spaces exist. (No unmodded tree raw IDs have spaces.) A numerical ID
+    can be used in place of a string. Use ``plant list`` and check under
+    ``Saplings`` for a list of valid IDs.
+``-e``, ``--exclude <plant_id>[,<plant_id>...]``
+    Same as ``--filter``, but target everything except these. Cannot be used
+    with ``--filter``.
+``-z``, ``--zlevel``
+    Operate on a range of z-levels instead of default targeting. Will do all
+    z-levels between ``pos`` arguments if both are given (instead of cuboid,)
+    z-level of first ``pos`` if one is given (instead of single tile,) else
+    z-level of current view if no ``pos`` is given (instead of entire map.)
+``-n``, ``--dryrun``
+    Don't actually grow plants. Just print the total number of plants that
+    would be grown.
+
+Remove Options
+--------------
+
+``-s``, ``--shrubs``
+    Target shrubs for removal.
+``-p``, ``--saplings``
+    Target saplings for removal.
+``-d``, ``--dead``
+    Only target dead plants for removal. Can't be used without ``--shrubs``
+    or ``--saplings``.
+``-f``, ``--filter <plant_id>[,<plant_id>...]``
+    Define a filter list of plant raw IDs to target, ignoring all other plant
+    types. This applies after ``--shrubs`` and ``--saplings`` are targeted,
+    and can't be used without one of those options. ``plant_id`` is not
+    case-sensitive, but must be enclosed in quotes if spaces exist. (No
+    unmodded shrub or sapling raw IDs have spaces.) A numerical ID can be
+    used in place of a string. Use ``plant list`` for a list of valid IDs.
+``-e``, ``--exclude <plant_id>[,<plant_id>...]``
+    Same as ``--filter``, but target everything except these. Cannot be used
+    with ``--filter``.
+``-z``, ``--zlevel``
+    Operate on a range of z-levels instead of default targeting. Will do all
+    z-levels between ``pos`` arguments if both are given (instead of cuboid,)
+    z-level of first ``pos`` if one is given (instead of single tile,) else
+    z-level of current view if no ``pos`` is given (instead of entire map.)
+``-n``, ``--dryrun``
+    Don't actually remove plants. Just print the total number of plants that
+    would be removed.

docs/plugins/regrass.rst

@@ -3,7 +3,7 @@ regrass
 
 .. dfhack-tool::
     :summary: Regrow surface grass and cavern moss.
-    :tags: adventure fort armok animals map
+    :tags: adventure fort armok animals map plants
 
 This command can refresh the grass (and subterranean moss) growing on your map.
 Operates on floors, stairs, and ramps. Also works underneath shrubs, saplings,
@@ -24,9 +24,45 @@ can be used in place of numeric coordinates to use the position of the keyboard
 cursor, if active. The ``--block`` and ``--zlevel`` options use the ``pos``
 values differently.
 
+Examples
+--------
+
+``regrass``
+    Regrass the entire map, refilling existing and depleted grass.
+``regrass here``
+    Regrass the selected tile, refilling existing and depleted grass.
+``regrass here 0,0,90 --zlevel``
+    Regrass all z-levels including the selected tile's z-level through z-level
+    90, refilling existing and depleted grass.
+``regrass 0,0,100 19,19,119 --ashes --mud``
+    Regrass tiles in the 20 x 20 x 20 cube defined by the coords, refilling
+    existing and depleted grass, and converting ashes and muddy stone (if
+    respective blocks ever had grass.)
+``regrass 10,10,100 -baudnm``
+    Regrass the block that contains the given coord; converting ashes, muddy
+    stone, and tiles under buildings; adding all compatible grass types, and
+    filling each grass type to max.
+``regrass -f``
+    Regrass the entire map, refilling existing and depleted grass, else filling
+    with a randomly selected grass type if non-existent.
+``regrass -l``
+    Print all valid grass raw IDs for use with ``--plant``. Both numerical and
+    string IDs are provided. This ignores all other options and skips regrass.
+``regrass -zf -p 128``
+    Regrass the current z-level, refilling existing and depleted grass, else
+    filling with ``underlichen`` if non-existent.
+``regrass here -bnf -p "dog's tooth grass"``
+    Regrass the selected block, adding all compatible grass types to block data,
+    ``dog's tooth grass`` if no compatible types exist. Refill existing grass
+    on each tile, else select one of the block's types if depleted or
+    previously non-existent.
+
 Options
 -------
 
+``-l``, ``--list``
+    Print all available grass raw IDs and skip regrass. For use with
+    ``--plant``.
 ``-m``, ``--max``
     Maxes out every grass type in the tile, giving extra grazing time.
     Not normal DF behavior. Tile will appear to be the first type of grass
@@ -44,12 +80,13 @@ Options
     forced instead. By default, a single random grass type is selected from
     the world's raws. The ``--plant`` option allows a specific grass type to be
     specified.
-``-p <grass_id>``, ``--plant <grass_id>``
+``-p``, ``--plant <grass_id>``
     Specify a grass type for the ``--force`` option. ``grass_id`` is not
-    case-sensitive, but must be enclosed in quotes if spaces exist. Providing
-    an empty string with "" will print all available IDs and skip regrass.
+    case-sensitive, but must be enclosed in quotes if spaces exist. A numerical
+    ID can also be used.
 ``-a``, ``--ashes``
-    Regrass tiles that've been burnt to ash.
+    Regrass tiles that've been burnt to ash. Usually ash must revert to soil
+    first before grass can grow.
 ``-d``, ``--buildings``
     Regrass tiles under certain passable building tiles including stockpiles,
     planned buildings, workshops, and farms. (Farms will convert grass tiles to
@@ -65,40 +102,8 @@ Options
     `devel/block-borders` can be used to visualize map blocks.
 ``-z``, ``--zlevel``
     Regrass entire z-levels. Will do all z-levels between ``pos`` arguments if
-    both given, z-level of first ``pos`` if one given, else z-level of
-    viewscreen if no ``pos`` given.
-
-Examples
---------
-
-``regrass``
-    Regrass the entire map, refilling existing and depleted grass.
-``regrass here``
-    Regrass the selected tile, refilling existing and depleted grass.
-``regrass here 0,0,90 --zlevel``
-    Regrass all z-levels including the selected tile's z-level through z-level
-    90, refilling existing and depleted grass.
-``regrass 0,0,100 19,19,119 --ashes --mud``
-    Regrass tiles in the 20x20x20 cube defined by the coords, refilling
-    existing and depleted grass, and converting ashes and muddy stone (if
-    respective blocks ever had grass.)
-``regrass 10,10,100 -baudnm``
-    Regrass the block that contains the given coord; converting ashes, muddy
-    stone, and tiles under buildings; adding all compatible grass types, and
-    filling each grass type to max.
-``regrass -f``
-    Regrass the entire map, refilling existing and depleted grass, else filling
-    with a randomly selected grass type if non-existent.
-``regrass -p ""``
-    Print all valid grass raw ids. Don't regrass.
-``regrass -zf -p underlichen``
-    Regrass the current z-level, refilling existing and depleted grass, else
-    filling with ``underlichen`` if non-existent.
-``regrass here -bnf -p "dog's tooth grass"``
-    Regrass the selected block, adding all compatible grass types to block data,
-    ``dog's tooth grass`` if no compatible types exist. Refill existing grass
-    on each tile, else select one of the block's types if depleted or
-    previously non-existent.
+    both are given, z-level of first ``pos`` if one is given, else z-level of
+    current view if no ``pos`` is given.
 
 Troubleshooting
 ---------------

plugins/CMakeLists.txt

@@ -141,7 +141,7 @@ if(BUILD_SUPPORTED)
     dfhack_plugin(overlay overlay.cpp LINK_LIBRARIES lua)
     dfhack_plugin(pathable pathable.cpp LINK_LIBRARIES lua)
     dfhack_plugin(pet-uncapper pet-uncapper.cpp)
-    #dfhack_plugin(plants plants.cpp)
+    dfhack_plugin(plant plant.cpp LINK_LIBRARIES lua)
     dfhack_plugin(preserve-tombs preserve-tombs.cpp)
     dfhack_plugin(probe probe.cpp LINK_LIBRARIES lua)
     dfhack_plugin(prospector prospector.cpp LINK_LIBRARIES lua)