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

Contents

- Development Scripts
  - devel/all-bob
  - devel/annc-monitor
  - 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/light
  - devel/list-filters
  - devel/lsmem
  - devel/lua-example
  - devel/modstate-monitor
  - devel/nuke-items
  - devel/pop-screen
  - devel/prepare-save
  - devel/print-args
  - devel/print-args2
  - 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
interval X: | Sets the delay between checks for new announcements to `X` frames

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

This script will recursively search an input for fields matching your query. Matching fields will be printed along with their values. When a match is a table the entire table will not be printed, only the reference to it.

When performing table queries, use dot notation to denote sub-tables. The script has to parse the input string and separate each table.

example: “query -unit -query profession” will print all fields matching ‘profession’ inside the highlighted unit.

The values input to -unit or -table must be global identifiers (ie. _G[identifier] must exist).

Usage: `query -unit <global_value> -query <query>` or `query -table <global_value> -query <query>`

## devel/save-version

Display DF version information about the current save

## devel/sc

Size Check

devel/sc scan world devel/sc -all scan all globals devel/sc [expr] scan result of expression

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

## 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/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`