new tool: fix/occupancy

changelog.txt

@@ -31,6 +31,7 @@ Template for new versions:
 - `gui/sitemap`: list and zoom to nearby people, locations, and artifacts
 - `devel/tree-info`: print a visualization of tree_info data
 - `fix/population-cap`: fixes the situation where you continue to get migrant waves even when you are above your configured population cap
+- `fix/occupancy`: fixes issues where you can't build somewhere because the game tells you an item/unit/building is in the way but there's nothing there
 
 ## New Features
 - `buildingplan`: dimension tooltip is now displayed for constructions and buildings that are designated over an area
@@ -49,6 +50,7 @@ Template for new versions:
 ## Removed
 - `max-wave`: merged into `pop-control`
 - `devel/find-offsets`, `devel/find-twbt`, `devel/prepare-save`: remove development scripts that are no longer useful
+- `fix/item-occupancy`, `fix/tile-occupancy`: merged into `fix/occupancy`
 
 # 50.13-r2
 

docs/fix/occupancy.rst

@@ -0,0 +1,36 @@
+fix/occupancy
+=============
+
+.. dfhack-tool::
+    :summary: Fix phantom occupancy issues.
+    :tags: fort bugfix map
+
+If you see "unit blocking tile", "building present", or "items occupying site"
+messages that you can't account for (:bug:`3499`), this tool can help.
+
+Usage
+-----
+
+::
+
+    fix/occupancy [<pos>] [<options>]
+
+The optional position can be map coordinates in the form ``0,0,0``, without
+spaces, or the string ``here`` to use the position of the keyboard cursor, if
+active.
+
+Examples
+--------
+
+``fix/occupancy``
+    Fix all occupancy issues on the map.
+``fix/occupancy here``
+    Fix all occupancy issues on the tile selected by the keyboard cursor.
+``fix-unit-occupancy -n``
+    Report on, but do not fix, all occupancy issues on the map.
+
+Options
+-------
+
+``-n``, ``--dry-run``
+    Report issues, but do not write any changes to the map.

fix/occupancy.lua

@@ -0,0 +1,22 @@
+local argparse = require('argparse')
+local plugin = require('plugins.fix-occupancy')
+
+local opts = {
+    dry_run=false,
+}
+
+local positionals = argparse.processArgsGetopt({...}, {
+    { 'h', 'help', handler = function() opts.help = true end },
+    { 'n', 'dry-run', handler = function() opts.dry_run = true end },
+})
+
+if positionals[1] == 'help' or opts.help then
+    print(dfhack.script_help())
+    return
+end
+
+if not positionals[1] then
+    plugin.fix_map(opts.dry_run)
+else
+    plugin.fix_tile(argparse.coords(positionals[1], 'pos'), opts.dry_run)
+end