DFHack Contributions

My DFHack work brought together C++ gameplay plugins, Lua interfaces, game-event handling, and build and test integration. These were contributions to the community project for Dwarf Fortress. This page focuses on selected upstream contributions from 2017–2023, including cxxrandom, Spectate, and fixes to digging tools.

Random engines that Lua scripts can control

cxxrandom exposes C++ random engines and distributions to Lua. Scripts can create independently identified mt19937_64 engines and managed number sequences, then use those handles for subsequent operations. That gives a script explicit state to work with when it needs more than a single random roll.

The interface developed beyond its initial implementation. Later changes widen identifiers, separate engine and sequence ID ranges, correct shuffle argument handling, and validate Bernoulli probabilities. Seeded API sanity tests exercise the interface’s intended behavior. The boundary is between C++ objects with a lifetime and Lua values that refer to them; both sides have to agree about what an identifier represents.

Following activity with Spectate

Spectate follows citizens and jobs through game events. Its selection logic developed into weighted choices among visible units, working citizens, citizens more generally, and optional animals, hostiles, or visitors. Settings are saved per world.

Following a unit also interacts with the player’s control of the game. Spectate includes auto-unpause and disengage controls, along with pause-state handling. Selection, persistence, and pause behavior are related concerns: changing the camera’s target should follow the configured rules without losing track of the player’s settings.

Advancing the job list before early exits

My dig-now changes stage job and designation information before mutating map tiles, validate job coordinates, and correct track-direction bit extraction. A later fix addresses the linked-list traversal itself: advance the iterator before any early continue. Otherwise, rejecting an invalid job or position leaves the loop looking at the same node. This functional fix, committed in March 2023, is the endpoint of the contribution period shown here.

Shared interfaces and build work

• EventManager and eventful: job-started and newly active-unit notifications, lifecycle corrections, and enum-driven handler dispatch in the native event manager and Lua bridge.
• Utility interfaces: animal classification, visitor and danger predicates, Lua-facing helpers, and signed Maps interfaces alongside compatibility overloads.
• Build, tests, and CI: shared CTest/GoogleTest target construction, separate core and script test controls, scoped include paths, test-binary exit handling, ccache, external-plugin discovery, and nested-build paths.

The linked upstream revision lists cxxrandom and Spectate in its default build configuration. Build inclusion, enabling a plugin, and exercising it in a matching game installation are separate steps. The native plugins have not been exercised in a matching Dwarf Fortress runtime for this portfolio review.

The DFHack Lua scripts page covers my separate script and maintenance contributions.