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.
Contents
- devel/all-bob
- devel/annc-monitor
- devel/block-borders
- devel/check-other-ids
- devel/check-release
- devel/clear-script-env
- devel/click-monitor
- devel/cmptiles
- devel/dump-offsets
- devel/export-dt-ini
- devel/find-offsets
- devel/find-primitive
- devel/find-twbt
- devel/inject-raws
- devel/inspect-screen
- devel/kill-hf
- devel/light
- devel/list-filters
- devel/lsmem
- devel/lua-example
- devel/luacov
- devel/modstate-monitor
- devel/nuke-items
- devel/pop-screen
- devel/prepare-save
- devel/print-args
- devel/print-args2
- devel/print-event
- devel/query
- devel/save-version
- devel/sc
- devel/scanitemother
- devel/send-key
- devel/spawn-unit-helper
- devel/test-perlin
- devel/unforbidall
- devel/unit-path
- devel/visualize-structure
- devel/watch-minecarts
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 globalsnofeed
to block automated fake input searchesnozoom
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 aninterface_key
- a full list of valid names can be obtained by runninglua @df.interface_key
, looking indata/init/interface.txt
, or by checkingdf.keybindings.xml
in the df-structures repository.X
(optional) - if specified, the key is sent to the screenX
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