New plugin: dig-now

docs/Lua API.rst

@@ -4043,6 +4043,16 @@ Lua plugin classes
 - ``shuffle()``: shuffles the sequence of numbers
 - ``next()``: returns next number in the sequence
 
+dig-now
+=======
+
+The dig-now plugin exposes the following functions to Lua:
+
+* ``dig_now_tile(pos)`` or ``dig_now_tile(x,y,z)``: Runs dig-now for the
+    specified tile coordinate. Default options apply, as if you were running the
+    command ``dig-now <pos> <pos>``. See the `dig-now` documentation for details
+    on default settings.
+
 .. _eventful:
 
 eventful

docs/Plugins.rst

@@ -2835,6 +2835,70 @@ Options:
 :building:  Subsequent items will become part of the currently selected building.
             Good for loading traps; do not use with workshops (or deconstruct to use the item).
 
+.. _dig-now:
+
+dig-now
+=======
+
+Instantly completes non-marker dig designations, modifying tile shapes and
+creating boulders, ores, and gems as if a miner were doing the mining or
+engraving. By default, the entire map is processed and boulder generation
+follows standard game rules, but the behavior is configurable.
+
+Note that no units will get mining or engraving experience for the dug/engraved
+tiles.
+
+Trees and roots are not currently handled by this plugin and will be skipped.
+Requests for engravings are also skipped since they would depend on the skill
+and creative choices of individual engravers. Other types of engraving (i.e.
+smoothing and track carving) are handled.
+
+Usage::
+
+    dig-now [<pos> [<pos>]] [<options>]
+
+Where the optional ``<pos>`` pair can be used to specify the coordinate bounds
+within which ``dig-now`` will operate. If they are not specified, ``dig-now``
+will scan the entire map. If only one ``<pos>`` is specified, only the tile at
+that coordinate is processed.
+
+Any ``<pos>`` parameters can either be an ``<x>,<y>,<z>`` triple (e.g.
+``35,12,150``) or the string ``here``, which means the position of the active
+game cursor should be used.
+
+Examples:
+
+``dig-now``
+    Dig designated tiles according to standard game rules.
+
+``dig-now --clean``
+    Dig designated tiles, but don't generate any boulders, ores, or gems.
+
+``dig-now --dump here``
+    Dig tiles and dump all generated boulders, ores, and gems at the tile under
+    the game cursor.
+
+Options:
+
+:``-c``, ``--clean``:
+    Don't generate any boulders, ores, or gems. Equivalent to
+    ``--percentages 0,0,0,0``.
+:``-d``, ``--dump <pos>``:
+    Dump any generated items at the specified coordinates. If the tile at those
+    coordinates is open space or is a wall, items will be generated on the
+    closest walkable tile below.
+:``-e``, ``--everywhere``:
+    Generate a boulder, ore, or gem for every tile that can produce one.
+    Equivalent to ``--percentages 100,100,100,100``.
+:``-h``, ``--help``:
+    Show quick usage help text.
+:``-p``, ``--percentages <layer>,<vein>,<small cluster>,<deep>``:
+    Set item generation percentages for each of the tile categories. The
+    ``vein`` category includes both the large oval clusters and the long stringy
+    mineral veins. Default is ``25,33,100,100``.
+:``-z``, ``--cur-zlevel``:
+    Restricts the bounds to the currently visible z-level.
+
 .. _diggingInvaders:
 
 diggingInvaders

docs/changelog.txt

@@ -33,6 +33,9 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 
 # Future
 
+## New Plugins
+- `dig-now`: instantly completes dig designations (including smoothing and carving tracks)
+
 ## Misc Improvements
 - `tiletypes-here`, `tiletypes-here-point`: add --cursor and --quiet options to support non-interactive use cases
 

library/include/modules/Maps.h

@@ -260,8 +260,10 @@ extern DFHACK_EXPORT bool GetGlobalFeature(t_feature &feature, int32_t index);
  * BLOCK DATA
  */
 
-/// get size of the map in tiles
+/// get size of the map in blocks
 extern DFHACK_EXPORT void getSize(uint32_t& x, uint32_t& y, uint32_t& z);
+/// get size of the map in tiles
+extern DFHACK_EXPORT void getTileSize(uint32_t& x, uint32_t& y, uint32_t& z);
 /// get the position of the map on world map
 extern DFHACK_EXPORT void getPosition(int32_t& x, int32_t& y, int32_t& z);
 

library/modules/Maps.cpp

@@ -106,7 +106,7 @@ bool Maps::IsValid ()
     return (world->map.block_index != NULL);
 }
 
-// getter for map size
+// getter for map size in blocks
 void Maps::getSize (uint32_t& x, uint32_t& y, uint32_t& z)
 {
     if (!IsValid())
@@ -119,6 +119,14 @@ void Maps::getSize (uint32_t& x, uint32_t& y, uint32_t& z)
     z = world->map.z_count_block;
 }
 
+// getter for map size in tiles
+void Maps::getTileSize (uint32_t& x, uint32_t& y, uint32_t& z)
+{
+    getSize(x, y, z);
+    x *= 16;
+    y *= 16;
+}
+
 // getter for map position
 void Maps::getPosition (int32_t& x, int32_t& y, int32_t& z)
 {

plugins/CMakeLists.txt

@@ -111,6 +111,7 @@ if(BUILD_SUPPORTED)
     dfhack_plugin(deramp deramp.cpp)
     dfhack_plugin(debug debug.cpp LINK_LIBRARIES jsoncpp_lib_static)
     dfhack_plugin(dig dig.cpp)
+    dfhack_plugin(dig-now dig-now.cpp LINK_LIBRARIES lua)
     dfhack_plugin(digFlood digFlood.cpp)
     add_subdirectory(diggingInvaders)
     dfhack_plugin(dwarfvet dwarfvet.cpp)