Development Scripts

devel/* scripts are intended for developer use, but many may be of interest to anyone investigating odd phenomena or just messing around. They are documented to encourage such inquiry.

Some can PERMANENTLY DAMAGE YOUR SAVE if misused, so please be careful. The warnings are real; if in doubt make backups before running the command.

devel/all-bob

Changes the first name of all units to “Bob”. Useful for testing modtools/interaction-trigger events.

devel/annc-monitor

Displays announcements and reports in the console.

enable|start:Begins monitoring
disable|stop:Stops monitoring
report enable:Show combat reports
report disable:Only show announcements

devel/block-borders

An overlay that draws borders of map blocks. Must be run from the main fortress mode screen. See Maps API for details on map blocks.

devel/check-other-ids

This script runs through all world.items.other and world.buildings.other vectors and verifies that the items contained in them have the expected types.

devel/check-release

Basic checks for release readiness

devel/clear-script-env

Clears the environment of the specified lua script(s).

devel/click-monitor

Displays the grid coordinates of mouse clicks in the console. Useful for plugin/script development.

Usage: devel/click-monitor start|stop

devel/cmptiles

Lists and/or compares two tiletype material groups.

Usage: devel/cmptiles material1 [material2]

devel/dump-offsets

Warning

THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS.

Running this script on a new DF version will NOT MAKE IT RUN CORRECTLY if any data structures changed, thus possibly leading to CRASHES AND/OR PERMANENT SAVE CORRUPTION.

This dumps the contents of the table of global addresses (new in 0.44.01).

Passing global names as arguments calls setAddress() to set those globals’ addresses in-game. Passing “all” does this for all globals.

devel/export-dt-ini

Exports an ini file containing memory addresses for Dwarf Therapist.

devel/find-offsets

Warning

THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS.

Running this script on a new DF version will NOT MAKE IT RUN CORRECTLY if any data structures changed, thus possibly leading to CRASHES AND/OR PERMANENT SAVE CORRUPTION.

Finding the first few globals requires this script to be started immediately after loading the game, WITHOUT first loading a world. The rest expect a loaded save, not a fresh embark. Finding current_weather requires a special save previously processed with devel/prepare-save on a DF version with working dfhack.

The script expects vanilla game configuration, without any custom tilesets or init file changes. Never unpause the game unless instructed. When done, quit the game without saving using ‘die’.

Arguments:

  • global names to force finding them
  • all to force all globals
  • nofeed to block automated fake input searches
  • nozoom to disable neighboring object heuristics

devel/find-primitive

Finds a primitive variable in DF’s data section, relying on the user to change its value. This is similar to devel/find-offsets, but useful for new variables whose locations are unknown (i.e. they could be part of an existing global).

Usage:

devel/find-primitive data-type val1 val2 [val3...]

where data-type is a primitive type (int32_t, uint8_t, long, etc.) and each val is a valid value for that type.

Use devel/find-primitive help for a list of valid data types.

devel/find-twbt

Finds some TWBT-related offsets - currently just twbt_render_map.

devel/inject-raws

WARNING: THIS SCRIPT CAN PERMANENLY DAMAGE YOUR SAVE.

This script attempts to inject new raw objects into your world. If the injected references do not match the actual edited raws, your save will refuse to load, or load but crash.

This script can handle reaction, item and building definitions.

The savegame contains a list of the relevant definition tokens in the right order, but all details are read from raws every time. This allows just adding stub definitions, and simply saving and reloading the game.

This is useful enough for modders and some users to justify the danger.

Usage example:

devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER

devel/inspect-screen

Read the tiles from the screen and display info about them.

devel/kill-hf

Kills the specified historical figure, even if off-site, or terminates a pregnancy. Useful for working around Bug 11549.

Usage:

devel/kill-hf [-p|--pregnancy] [-n|--dry-run] HISTFIG_ID

Arguments:

histfig_id:
the ID of the historical figure to target
-p, --pregnancy:
if specified, and if the historical figure is pregnant, terminate the pregnancy instead of killing the historical figure
-n, --dry-run:
if specified, only print the name of the historical figure

devel/light

An experimental lighting engine for DF, using the rendermax plugin.

Call devel/light static to not recalculate lighting when in game. Press ~ to recalculate lighting. Press ` to exit.

devel/list-filters

List input items for the building currently being built. This is where the filters in lua/dfhack/buildings.lua come from.

devel/lsmem

Prints memory ranges of the DF process. Useful for checking whether a pointer is valid, whether a certain library/plugin is loaded, etc.

devel/lua-example

An example Lua script which reports the number of times it has been called. Useful for testing environment persistence.

devel/luacov

Lua script coverage report generator

Usage:

luacov [options] [pattern…]

This script generates a coverage report from collected statistics. By default it reports on every Lua file in all of DFHack. To filter filenames, specify one or more Lua patterns matching files or directories to be included. Alternately, you can configure reporting parameters in the .luacov file in your DF directory. See https://keplerproject.github.io/luacov/doc/modules/luacov.defaults.html for details.

Statistics are cumulative across reports. That is, if you run a report, run a lua script, and then run another report, the report will include all activity from the first report plus the recently run lua script. Restarting DFHack will clear the statistics. You can also clear statistics after running a report by passing the –clear flag to this script.

Note that the coverage report will be empty unless you have started DFHack with the “DFHACK_ENABLE_LUACOV=1” environment variable defined, which enables the coverage monitoring.

Also note that enabling both coverage monitoring and lua profiling via the “profiler” module can produce strange results. Their interceptor hooks override each other. Usage of the “kill-lua” command will likewise override the luacov interceptor hook and may prevent coverage statistics from being collected.

Options:

-c, --clear Remove accumulated metrics after generating the report, ensuring the next report starts from a clean slate.
-h, --help Show this help message and exit.

Examples:

devel/luacov
Report on all DFHack lua scripts.
devel/luacov -c quickfort
Report only on quickfort source files and clear stats.
devel/luacov quickfort hack/lua
Report only on quickfort and DFHack library lua source files.

devel/modstate-monitor

Display changes in key modifier state, i.e. Ctrl/Alt/Shift.

Arguments:

enable|start:Begin monitoring
disable|stop:End monitoring

devel/nuke-items

Deletes ALL items not held by units, buildings or jobs. Intended solely for lag investigation.

devel/pop-screen

Forcibly closes the current screen. This is usually equivalent to pressing Esc (LEAVESCREEN), but will bypass the screen’s input handling. This is intended primarily for development, if you have created a screen whose input handling throws an error before it handles Esc (or if you have forgotten to handle Esc entirely).

Warning

If you run this script when the current screen does not have a parent, this will cause DF to exit immediately. These screens include:

  • The main fortress mode screen (viewscreen_dwarfmodest)
  • The main adventure mode screen (viewscreen_dungeonmodest)
  • The main legends mode screen (viewscreen_legendsst)
  • The title screen (viewscreen_titlest)

devel/prepare-save

Warning

THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS.

This script prepares the current savegame to be used with devel/find-offsets. It CHANGES THE GAME STATE to predefined values, and initiates an immediate quicksave, thus PERMANENTLY MODIFYING the save.

devel/print-args

Prints all the arguments you supply to the script on their own line. Useful for debugging other scripts.

devel/print-args2

Prints all the arguments you supply to the script on their own line with quotes around them.

devel/print-event

Prints the description of an event by ID or index.

devel/query

Query is a script useful for finding and reading values of data structure fields. Purposes will likely be exclusive to writing lua script code.

Fields: contents of tables Keys: contents below non-table containers

Keys and fields are essentially the same thing. The real difference is what code checks need to be in place for queries on keys vs fields. This is why they are differentiated.

This is a recursive script which takes your selected data {table,unit,item,tile} and then iterates through it, then iterates through anything it finds. It does this recursively until it has walked over everything it is allowed. Everything it walks over it checks against any (optional) string/value queries, and if it finds a match it then prints it to the console.

You can control most aspects of this process, the script is fairly flexible. So much so that you can easily create an infinitely recursing query and/or potentially crash Dwarf Fortress and DFHack. In previous iterations memory bloat was even a concern, where RAM would be used up in mere minutes or seconds; you can probably get this to happen as well if you are careless with the depth settings and don’t print everything walked over (i.e. have a search term). The kill-lua command may be able to stop this script if it gets out of control.

Before recursing or printing things to the console the script checks several things. A few important ones:

  • Is the data structure capable of being iterated?
  • Is the data structure pointing to a parent data structure?
  • Is the current level of recursion too high, and do we need to unwind it first?
  • Is the number of entries too high (eg. 70,000 table entries that would be printed)?
  • Is the data going to be usefully readable?
  • Does the field or key match the field or key query or queries?
  • Is printing fields allowed?
  • Is printing keys allowed?

Examples:

devel/query -table df -query dead
devel/query -table df.global.ui.main -depth 0
devel/query -table df.profession -querykeys WAR
devel/query -unit -query STRENGTH
devel/query -unit -query physical_attrs -listkeys
devel/query -unit -getfield id

Selection options:

These options are used to specify where the query will run, or specifically what key to print inside a unit.

-unit: Selects the highlighted unit

-item: Selects the highlighted item.

-tile: Selects the highlighted tile’s block and then attempts to find the tile, and perform your queries on it.

-table <value>: Selects the specified table (ie. ‘value’).

Must use dot notation to denote sub-tables. (eg. -table df.global.world)

-getfield <value>: Gets the specified field from the selected unit.

Must use dot notation to denote sub-fields. Useful if there would be several matching fields with the input as a substring (eg. ‘id’, ‘gui’)

Query options:

-query <value>: Searches the selection for fields with substrings matching the specified value.

-querykeys <value>: Lists only keys matching the specified value.

-listall: Lists both fields and keys, useful if you aren’t running a search.

-listfields: Lists fields. Useful if you aren’t running a search.

-listkeys: Lists keys. Useful. Ya, period.

-depth <value>: Limits the field recursion depth (default: 10)

-keydepth <value>: Limits the key recursion depth (default: 4)

-maxtablelength <value>: Limits the table sizes that will be walked (default: 257)

-includeitall: Removes blacklist filtering, and disregards readability of output.

-safer: Disables walking struct data.

Unlike native Lua types, struct data can sometimes be misaligned, which can cause crashes when accessing it. This option may be useful if you’re running an alpha or beta build of DFHack.

-dumb: Disables intelligent checks for things such as reasonable recursion depth (i.e. depth maximums are increased, not removed) and also checks for recursive data structures (i.e. to avoid walking a child that goes to a parent)

Command options:

-debug <value>: Enables debug log lines equal to or less than the value provided. Some lines are commented out entirely, and you probably won’t even use this.. but hey, now you know it exists.

-disableprint: Disables printing fields and keys. Might be useful if you are debugging this script. Or to see if a query will crash (faster) but not sure what else you could use it for.

-help: Prints this help information.

devel/save-version

Display DF version information about the current save

devel/sc

Size Check: scans structures for invalid vectors, misaligned structures, and unidentified enum values.

Note

This script can take a very long time to complete, and DF may be unresponsive while it is running. You can use kill-lua to interrupt this script.

Examples:

  • scan world:

    devel/sc
    
  • scan all globals:

    devel/sc -all
    
  • scan result of expression:

    devel/sc [expr]
    

devel/scanitemother

List indices in world.item.other[] where current selected item appears.

devel/send-key

Send a key to the current screen or a parent. If you are trying to dismiss a screen, devel/pop-screen may be more useful, particularly if the screen is unresponsive to Esc.

Usage:

devel/send-key KEY_NAME [X]
  • KEY_NAME is the name of an interface_key - a full list of valid names can be obtained by running lua @df.interface_key, looking in data/init/interface.txt, or by checking df.keybindings.xml in the df-structures repository.
  • X (optional) - if specified, the key is sent to the screen X screens above the current screen in the screen stack (e.g. 1 corresponds to the current screen’s parent)

devel/spawn-unit-helper

Setup stuff to allow arena creature spawn after a mode change.

With Arena spawn data initialized:

  • enter the k menu and change mode using rb_eval df.gametype = :DWARF_ARENA
  • spawn creatures (c ingame)
  • revert to game mode using rb_eval df.gametype = #{df.gametype.inspect}
  • To convert spawned creatures to livestock, select each one with the v menu, and enter rb_eval df.unit_find.civ_id = df.ui.civ_id

devel/test-perlin

Generates an image using multiple octaves of perlin noise.

devel/unforbidall

Unforbid all items.

devel/unit-path

Show the internal path a unit is currently following.

devel/visualize-structure

Displays the raw memory of a structure, separated by field. Useful for checking if structures are aligned.

devel/watch-minecarts

Logs minecart coordinates and speeds to console.

Usage: devel/watch-minecarts start|stop