Development Scripts

devel/* scripts are intended for developer use, but many may be of interest to anyone investigating odd phenomema 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
interval X:Sets the delay between checks for new announcements to X frames

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

devel/lua-example

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

devel/modstate-monitor

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

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

For killing bugged out gui script screens.

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/save-version

Display DF version information about the current save

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

Usage:

devel/send-key KEY_NAME:
 Send KEY_NAME
devel/send-key KEY_NAME X:
 Send KEY_NAME to the screen X screens above the current screen

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/watch-minecarts

Logs minecart coordinates and speeds to console.

Usage: devel/watch-minecarts start|stop