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, possibly C++.

This script takes your data selection eg.{table,unit,item,tile,etc.} then recursively iterates through it, outputting names and values of what it finds.

As it iterates you can have it do other things, like search for a specific structure pattern (see lua patterns) or set the value of fields matching the selection and any search pattern specified.

Note

This is a recursive search function. The data structures are also recursive. So there are a few things that must be considered (in order):

  • Is the search depth too high? (Default: 7)
  • Is the data capable of being iterated, or does it only have a value?
  • How can the data be iterated?
  • Is the iteration count for the data too high? (Default: 257)
  • Does the user want to exclude the data’s type?
  • Is the data recursively indexing (eg. A.B.C.A.*)?
  • Does the data match the search pattern?

Warning

This is a recursive script that’s primary use is to search recursive data structures. You can, fairly easily, cause an infinite loop. You can even more easily run a query that simply requires an inordinate amount of time to complete.

Tip

Should the need arise, you can kill the command from another shell with kill-lua, e.g. by running it with dfhack-run from another terminal.

Usage examples:

devel/query -unit -getfield id
devel/query -unit -search STRENGTH
devel/query -unit -search physical_attrs -maxdepth 2
devel/query -tile -search dig
devel/query -tile -search "occup.*carv"
devel/query -table df -maxdepth 2
devel/query -table df -maxdepth 2 -excludekinds s -excludetypes fsu -oneline
devel/query -table df.profession -findvalue FISH
devel/query -table df.global.ui.main -maxdepth 0
devel/query -table df.global.ui.main -maxdepth 0 -oneline
devel/query -table df.global.ui.main -maxdepth 0 -1

Selection options:

-tile
Selects the highlighted tile’s block, and then uses the tile’s local position to index the 2D data.
-block
Selects the highlighted tile’s block.
-unit
Selects the highlighted unit
-item
Selects the highlighted item.
-plant
Selects the highlighted plant.
-building
Selects the highlighted building.
-job
Selects the highlighted job.
-script <script name>
Selects the specified script (which must support being included with reqscript()).
-json <file>

Loads the specified json file as a table to query.

Note

The path starts at the DF root directory. eg. -json /hack/scripts/dwarf_profiles.json

-table <identifier>

Selects the specified table (ie. ‘value’).

Note

You must use dot notation to denote sub-tables. eg. df.global.world

-getfield <name>

Gets the specified field from the selection.

Must use in conjunction with one of the above selection options. Must use dot notation to denote sub-fields.

Query options:

-search <pattern>

Searches the selection for field names with substrings matching the specified value.

Usage:

devel/query -table dfhack -search pattern
devel/query -table dfhack -search [ pattern1 pattern2 ]
-findvalue <value>
Searches the selection for field values matching the specified value.
-maxdepth <value>
Limits the field recursion depth (default: 7)
-maxlength <value>
Limits the table sizes that will be walked (default: 257)
-excludetypes [a|bfnstu0]
Excludes native Lua data types. Single letters correspond to (in order): All types listed here, Boolean, Function, Number, String, Table, Userdata, nil
-excludekinds [a|bces]
Excludes DF data types. Single letters correspond to (in order): All types listed here, Bitfield-type, Class-type, Enum-type, Struct-type
-dumb
Disables intelligent checking for recursive data structures (loops) and increases the -maxdepth to 25 if a value is not already present

General options:

-showpaths
Displays the full path of a field instead of indenting.
-setvalue <value>
Attempts to set the values of any printed fields. Supported types: boolean, string, integer
-oneline, -1
Reduces output to one line, except with -debugdata
-alignto <value>
Specifies the alignment column.
-nopointers
Disables printing values which contain memory addresses.
-disableprint
Disables printing. 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.
-debug <value>
Enables debug log lines equal to or less than the value provided.
-debugdata
Enables debugging data. Prints type information under each field.
-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