DFHack Lua Scripts

My DFHack Lua work ranges from inspecting game structures to configuring dwarves and managing animals. These are contributions within DFHack’s community script collection. The useful unit of discussion is an individual tool and its changes, including earlier names and separate refactor branches.

Querying the structures behind the game

query.lua, later devel/query.lua, provides a way to inspect structures and select the data to work with. Its development includes depth and output limits, metadata and type filtering, alternative field patterns, linked-list traversal, JSON selection, and typed assignment.

The entry points also became more convenient for inspecting a live situation: tile selection, highlighted-job or cursor lookup, and expression-based lookup. Those routes feed the same broader inspection problem. Finding the right object and deciding how to traverse it are separate operations, and the tool needs controls for both.

Configurable dwarf allocation

The allocation work evolved through pimp-it, dwopit, and dwarf-op. Job-distribution tables describe the desired mix of work, while profession requirements and attribute archetypes describe how an individual dwarf should be configured. Persistent per-fort JSON data carries allocation counts between invocations.

Selection and reset behavior are part of that design. The scripts include protected selections, names and migration-related selection, plus reset, reroll, and cleanup controls. The tables and state are more substantial than a single command that assigns every dwarf the same settings. dwarf-op2.lua is a separate refactor foundation, not a replacement to silently combine with the published-name script.

Tools and supporting work

• Animal listing and control: listanimals evolved into animalcontrol, with explicit marking/unmarking, filters, active-unit selection, and race-name matching.
• Migration waves: getwaves lists and selects migration waves, giving another way to identify groups of dwarves.
• Gelding helpers: changes to geld and ungeld include wound/gelding-state handling and help documentation.
• Tile inspection: the historical tile.lua/tile-query.lua work includes naming and help changes; the redundant script was later removed.
• Allocation data and checks: dorf_tables.lua, its later internal path, and the dwarf-op table-check script support the allocation tools.
• Help and integration: changes include tame, dig, settile, changelogs, and the historical install-script.sh.

Animalcontrol’s historical help explains a specific use case: working around stale geld status in Dwarf Therapist that caused animals to be queued again. That belongs to the tool’s history and affected setup; it is not a claim about every later version of either application.

Credits and the execution boundary

Query’s helper credits include outside examples and lethosor’s safe_pairs work. The historical installer credits djcj for convert_path. The wider collection also contains imported upstream scripts; a file appearing in the fork does not make its original functionality my contribution.

All 307 Lua files at the linked default revision parse under Lua 5.4. Fourteen query-helper cases passed at each of two revisions using mocked game APIs. Those checks cover the listed helper behavior; they do not exercise Dwarf Fortress memory, saved-game mutations, native containers, or the allocation scripts in a running fort.

The DFHack contributions page covers the native plugins, Lua interfaces, and infrastructure work alongside these scripts.