Overhaul cleaners plugin; Add Maps::isPlantInBox

docs/changelog.txt

@@ -57,6 +57,7 @@ Template for new versions:
 ## New Tools
 
 ## New Features
+- `clean`: positional options to limit cleaning to a cuboid area. Options to remove grass or skip blood spatter removal.
 
 ## Fixes
 
@@ -65,8 +66,10 @@ Template for new versions:
 ## Documentation
 
 ## API
+- ``Maps::isPlantInBox``: function to determine if a plant is present in a cuboid.
 
 ## Lua
+- ``dfhack.maps.isPlantInBox``: function to determine if a plant is present in a cuboid.
 
 ## Removed
 
@@ -651,7 +654,7 @@ Template for new versions:
 ## Lua
 - ``dfhack.units.setAutomaticProfessions``: sets unit labors according to current work detail settings
 - ``dfhack.military.removeFromSquad``: Lua API for ``Military::removeFromSquad``
-- ``gui.dwarfmode``: adventure mode cursor now supported in ``getCursorPos``, ``setCursorPos``, and ``clearCursorPos`` funcitons
+- ``gui.dwarfmode``: adventure mode cursor now supported in ``getCursorPos``, ``setCursorPos``, and ``clearCursorPos`` functions
 - ``dfhack.buildings.checkFreeTiles``: now takes a building pointer instead of an extents parameter
 - ``overlay.isOverlayEnabled``: new API for querying whether a given overlay is enabled
 - ``overlay``: widgets can now declare ``overlay_onenable`` and ``overlay_ondisable`` functions to hook enable/disable

docs/dev/Lua API.rst

@@ -2431,6 +2431,13 @@ Maps module
 
  Returns the plant struct that owns the tile at the specified position.
 
+* ``dfhack.maps.isPlantInBox(plant, pos1, pos2)``
+* ``dfhack.maps.isPlantInBox(plant,x1,y1,z1,x2,y2,z2)``
+
+ Returns true if the plant is within a box defined by the specified
+ coordinates. For trees, returns true if any part of the tree is within
+ the box.
+
 * ``dfhack.maps.getWalkableGroup(pos)``
 
  Returns the walkability group for the given tile position. A return value

docs/plugins/cleaners.rst

@@ -5,57 +5,142 @@ cleaners
 ========
 
 .. dfhack-tool::
- :summary: Provides commands for cleaning spatter from the map.
- :tags: adventure fort armok fps items map units
+ :summary: Cleans spatter and/or grass from map tiles.
+ :tags: adventure fort armok fps items map plants units
  :no-command:
 
 .. dfhack-command:: clean
  :summary: Removes contaminants.
 
 .. dfhack-command:: spotclean
- :summary: Remove all contaminants from the tile under the cursor.
+ :summary: Remove contaminants from the tile under the cursor.
 
-This plugin provides commands that clean the splatter that get scattered all
+This plugin provides commands that clean the spatter that gets scattered all
 over the map and that clings to your items and units. In an old fortress,
-cleaning with this tool can significantly reduce FPS lag! It can also spoil your
-!!FUN!!, so think before you use it.
+cleaning with this tool can significantly reduce FPS lag! It can also spoil
+your !!FUN!!, so think before you use it.
+
+This plugin can also be used to remove grass in an area you don't want it
+(including those hard to reach areas like stairs and under buildings).
+Use it if you messed up with the `regrass` tool, or grass grew in your
+dining hall after a flooding mishap. Grass may eventually regrow if the tile
+remains soil, so `gui/tiletypes` may come in handy to change it to an
+appropriate stone type.
 
 Usage
 -----
 
 ::
 
- clean all|map|items|units|plants [<options>]
+ clean [<pos> [<pos>]] [<options>]
  spotclean
 
-By default, cleaning the map leaves mud and snow alone. Note that cleaning units
-includes hostiles, and that cleaning items removes poisons from weapons.
+By default, cleaning the map leaves mud, snow, and item spatter (e.g., tree
+droppings) alone. Note that cleaning units includes hostiles, and that
+cleaning items removes poisons from weapons.
+
+Mud will not be cleaned out from under farm plots unless the tile is furrowed
+soil, since that would render the plot inoperable.
+
+Operates on the entire map unless otherwise specified. Supplying a ``pos``
+argument can limit operation to a single tile. Supplying both can operate on
+a cuboid region. ``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. The ``--zlevel`` option uses
+the ``pos`` values differently.
 
-``spotclean`` works like ``clean map snow mud``, removing all contaminants from
-the tile under the keyboard cursor. This is ideal if you just want to clean a
-specific tile but don't want the `clean <cleaners>` command to remove all the
-glorious blood from your entranceway.
+``spotclean`` works like ``clean here --map --mud --snow``, removing all
+contaminants from a specific tile quickly. Intended as a hotkey command.
 
-Mud will not be cleaned out from under farm plots, since that would render the
-plot inoperable.
 
 Examples
 --------
 
-``clean all``
- Clean everything that can be cleaned (except mud and snow).
-``clean map mud item snow``
- Removes all spatter, including mud, leaves, and snow from map tiles. Farm
- plots will retain their mud.
+``clean --all``
+ Clean most spatter from all map tiles (excluding mud, snow, and item
+ spatter), as well as all contaminants from units and items.
+
+``clean --map --mud --snow --item``
+ Removes all spatter, including mud, snow, and tree droppings from map
+ tiles. Farm plots will retain their mud as needed.
+
+``clean --map --item --only --items``
+ Remove only tree droppings from the map (leaving blood and other
+ contaminants untouched). Clean all items of their contaminants.
+
+``clean here -mdstu``
+ Clean any sort of contaminant from the map tile under the keyboard cursor,
+ as well as any contaminant found on a unit there, but don't touch contaminants
+ on any item (e.g., the unit's poisoned weapon).
+
+``clean 0,0,90 0,0,120 -uiz``
+ Clean all contaminants from units and items on z-levels 90 through 120.
+ Don't touch map spatter at all.
+
+``clean -mgxoz``
+ Reduce all grass on the current z-level to barren soil. Don't touch
+ any contaminants.
+
+``clean 0,0,100 19,19,119 -adstg``
+ Remove all contaminants of any type from the 20 x 20 x 20 cube defined
+ by the coords, including on any units, items, and ground spatter
+ (excluding mud for farms). Also remove any unused grass type events from
+ the affected map blocks, but don't remove any grass present.
 
 Options
 -------
 
-When cleaning the map, you can specify extra options for extra cleaning:
-
-``mud``
- Also remove mud.
-``item``
- Also remove item spatter, like fallen leaves and flowers.
-``snow``
- Also remove snow coverings.
+``-a``, ``--all``
+ Equivalent to ``--map --units --items``.
+``-m``, ``--map``
+ Clean selected map tiles. Cleans most spatter by default, but not mud,
+ snow, or item spatter.
+``-d``, ``--mud``
+ Also remove mud from map tiles. Excludes mud required for farm plots.
+``-s``, ``--snow``
+ Also remove snow coverings from map tiles.
+``-t``, ``--item``
+ Also remove item spatter (e.g., fallen leaves, flowers, and gatherable
+ tree fruit) from map tiles. Not to be confused with ``--items``, which
+ cleans contaminants *off* of items.
+``-g``, ``--grass``
+ Remove unused (entirely depleted) grass events from map blocks. DF will
+ create a grass event for each type of grass that grows in a block, but
+ doesn't remove them if you pave over the block or if the grass got
+ depleted and entirely replaced with a different type. Could possibly
+ improve FPS if you had a ton of unused grass events everywhere (a likely
+ outcome of using ``regrass --new``). Requires ``--map`` option to be
+ specified.
+
+``-x``, ``--desolate``
+ Use with caution! Remove grass from the selected area. You probably don't
+ want to use this on the entire map, so make sure to use ``pos`` arguments.
+ Requires ``--map`` and ``--grass`` options to be specified.
+``-o``, ``--only``
+ Ignore most spatter (e.g., blood, vomit, and ooze) and focus only on the
+ other specified options. Requires ``--map`` and at least one of: ``--mud``,
+ ``--snow``, ``--item``, or ``--grass``.
+``-u``, ``--units``
+ Clean all contaminants off of units in the selected area. Not affected by
+ map options that specify spatter types (e.g., snow). Units will always be
+ completely cleaned.
+``-i``, ``--items``
+ Clean all contaminants off of items in the selected area (including those
+ held by units). Not affected by map options that specify spatter types.
+ Not to be confused with ``--item``, which removes tree droppings found on
+ the ground.
+``-z``, ``--zlevel``
+ Select entire z-levels. Will do all z-levels between ``pos`` arguments if
+ both are given, z-level of first ``pos`` if one is given, else z-level of
+ current view if no ``pos`` is given.
+
+Troubleshooting
+---------------
+
+Use ``debugfilter set Debug cleaners log`` (or
+``debugfilter set Trace cleaners log`` for more detail) to help diagnose
+issues. (Avoid cleaning large parts of the map using many options with
+Trace enabled, as it could make the game unresponsive and flood the console
+for a good minute.)
+
+Disable with ``debugfilter set Info cleaners log``.

docs/plugins/regrass.rst

@@ -9,6 +9,10 @@ This command can refresh the grass (and subterranean moss) growing on your map.
 Operates on floors, stairs, and ramps. Also works underneath shrubs, saplings,
 and tree trunks. Ignores furrowed soil and wet sand (beaches).
 
+The `cleaners` tool can help remove grass if you messed up and suddenly there
+are staring eyeballs growing all over your fort. `gui/tiletypes` can then be used
+to change the soil back to stone.
+
 Usage
 -----
 
@@ -74,7 +78,10 @@ Options
 ``-n``, ``--new``
  Adds all biome-compatible grass types that were not originally present in
  the map block. Allows regrass to work in blocks that never had any grass to
- begin with. Will still fail in incompatible biomes.
+ begin with. Will still fail in incompatible biomes. Note: This can add an
+ excessive number of grass events to your map, so it may be desirable to run
+ ``clean --map --grass --only`` (see: `cleaners`) afterwards to clean up any
+ unused events.
 ``-f``, ``--force``
  Force a grass type on tiles with no compatible grass types. Unsets the
  ``no_grow`` flag on all tiles. The ``--new`` option takes precedence for

library/LuaApi.cpp

@@ -2725,6 +2725,29 @@ static int maps_getPlantAtTile(lua_State *L)
  return 1;
 }
 
+static int maps_isPlantInBox(lua_State *L)
+{
+ auto plant = Lua::CheckDFObject<df::plant>(L, 1);
+ if (lua_gettop(L) > 3)
+ {
+ int x1 = luaL_checkint(L, 2);
+ int y1 = luaL_checkint(L, 3);
+ int z1 = luaL_checkint(L, 4);
+ int x2 = luaL_checkint(L, 5);
+ int y2 = luaL_checkint(L, 6);
+ int z2 = luaL_checkint(L, 7);
+ lua_pushboolean(L, Maps::isPlantInBox(plant, x1, y1, z1, x2, y2, z2));
+ }
+ else
+ {
+ df::coord pos1, pos2;
+ Lua::CheckDFAssign(L, &pos1, 2);
+ Lua::CheckDFAssign(L, &pos2, 3);
+ lua_pushboolean(L, Maps::isPlantInBox(plant, pos1, pos2));
+ }
+ return 1;
+}
+
 static int maps_getBiomeType(lua_State *L)
 {
  auto pos = CheckCoordXY(L, 1, true);
@@ -2791,6 +2814,7 @@ static const luaL_Reg dfhack_maps_funcs[] = {
  { "getRegionBiome", maps_getRegionBiome },
  { "getTileBiomeRgn", maps_getTileBiomeRgn },
  { "getPlantAtTile", maps_getPlantAtTile },
+ { "isPlantInBox", maps_isPlantInBox },
  { "getBiomeType", maps_getBiomeType },
  { "isTileAquifer", maps_isTileAquifer },
  { "isTileHeavyAquifer", maps_isTileHeavyAquifer },

library/include/modules/Maps.h

@@ -383,6 +383,11 @@ DFHACK_EXPORT bool canStepBetween(df::coord pos1, df::coord pos2);
 // Get the plant that owns the tile at the specified position.
 extern DFHACK_EXPORT df::plant *getPlantAtTile(int32_t x, int32_t y, int32_t z);
 inline df::plant *getPlantAtTile(df::coord pos) { return getPlantAtTile(pos.x, pos.y, pos.z); }
+// Returns true if the plant is within a box defined by the specified coordinates, accounting for trees.
+DFHACK_EXPORT bool isPlantInBox(df::plant *plant, const cuboid &bounds);
+inline bool isPlantInBox(df::plant *plant, int16_t x1, int16_t y1, int16_t z1,
+ int16_t x2, int16_t y2, int16_t z2) { return isPlantInBox(plant, cuboid(x1, y1, z1, x2, y2, z2)); }
+inline bool isPlantInBox(df::plant *plant, df::coord pos1, df::coord pos2) { return isPlantInBox(plant, cuboid(pos1, pos2)); }
 
 // Get the biome type at the given region coordinates.
 DFHACK_EXPORT df::enums::biome_type::biome_type getBiomeTypeWithRef(int16_t region_x, int16_t region_y, int16_t region_ref_y);

library/lua/tile-material.lua

@@ -172,33 +172,10 @@ end
 
 -- GetTreeMat returns the material of the tree at the given tile or nil if the tile does not have a
 -- tree or giant mushroom.
--- Currently roots are ignored.
 function GetTreeMat(x, y, z)
  local pos = prepPos(x, y, z)
-
- local function coordInTree(pos, tree)
- local x1 = tree.pos.x - math.floor(tree.tree_info.dim_x / 2)
- local x2 = tree.pos.x + math.floor(tree.tree_info.dim_x / 2)
- local y1 = tree.pos.y - math.floor(tree.tree_info.dim_y / 2)
- local y2 = tree.pos.y + math.floor(tree.tree_info.dim_y / 2)
- local z1 = tree.pos.z
- local z2 = tree.pos.z + tree.tree_info.body_height
-
- if not ((pos.x >= x1 and pos.x <= x2) and (pos.y >= y1 and pos.y <= y2) and (pos.z >= z1 and pos.z <= z2)) then
- return false
- end
-
- return not tree.tree_info.body[pos.z - tree.pos.z]:_displace((pos.y - y1) * tree.tree_info.dim_x + (pos.x - x1)).blocked
- end
-
- for _, tree in ipairs(df.global.world.plants.all) do
- if tree.tree_info ~= nil then
- if coordInTree(pos, tree) then
- return dfhack.matinfo.decode(419, tree.material)
- end
- end
- end
- return nil
+ local plant = dfhack.maps.getPlantAtTile(pos)
+ return plant and plant.tree_info and dfhack.matinfo.decode(419, plant.material) or nil
 end
 
 -- GetShrubMat returns the material of the shrub at the given tile or nil if the tile does not
@@ -289,7 +266,7 @@ BasicMats = {
  [df.tiletype_material.DRIFTWOOD] = GetLayerMat,
  [df.tiletype_material.POOL] = GetLayerMat,
  [df.tiletype_material.BROOK] = GetLayerMat,
- [df.tiletype_material.ROOT] = GetLayerMat,
+ [df.tiletype_material.ROOT] = GetTreeMat,
  [df.tiletype_material.TREE] = GetTreeMat,
  [df.tiletype_material.MUSHROOM] = GetTreeMat,
  [df.tiletype_material.UNDERWORLD_GATE] = nil, -- I guess this is for the gates found in vaults?
@@ -327,6 +304,7 @@ OnlyPlantMats = {
  [df.tiletype_material.GRASS_DRY] = GetGrassMat,
  [df.tiletype_material.GRASS_DEAD] = GetGrassMat,
  [df.tiletype_material.PLANT] = GetShrubMat,
+ [df.tiletype_material.ROOT] = GetTreeMat,
  [df.tiletype_material.TREE] = GetTreeMat,
  [df.tiletype_material.MUSHROOM] = GetTreeMat,
 }