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.


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


Displays announcements and reports in the console.

enable|start:Begins monitoring
disable|stop:Stops monitoring
interval X:Sets the delay between checks for new announcements to X frames


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.


Basic checks for release readiness


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


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

Usage: devel/click-monitor start|stop


Lists and/or compares two tiletype material groups.

Usage: devel/cmptiles material1 [material2]




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.


Exports an ini file containing memory addresses for Dwarf Therapist.




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’.


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


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).


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.


Finds some TWBT-related offsets - currently just twbt_render_map.



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:



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


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


devel/kill-hf [-p|--pregnancy] [-n|--dry-run] 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


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.


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


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


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


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


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


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


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).


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)




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.


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


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


Prints the description of an event by ID or index.


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?


devel/query -table df -query dead
devel/query -table -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

-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.


Display DF version information about the current save


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


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.


  • scan world:

  • scan all globals:

    devel/sc -all
  • scan result of expression:

    devel/sc [expr]


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


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.


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)


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


Generates an image using multiple octaves of perlin noise.


Unforbid all items.


Show the internal path a unit is currently following.


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


Logs minecart coordinates and speeds to console.

Usage: devel/watch-minecarts start|stop