Exploring AI-controlled Dwarf Fortress with a controller that can work with different models and agent harnesses: Claude, Codex, Gemini, local models, or a custom runner.
Status: early playable prototype. The DF_AI game server in src/dfai (docs/server.md) lets an MCP-capable AI play a running fort. Validation of the wider plan continues. It is pinned to DF v0.53.16 with DFHack 53.16-r3 on Linux. Code snippets in the older design documents are sketches; the server docs are the installation guide.
The initial target is fortress mode on Linux, starting from a prepared save. The proposed approach uses structured game state and actions through DFHack. Models would choose goals and priorities; ordinary code would validate plans, execute actions, and handle time-sensitive conditions.
External agent harness Optional autonomous runner
| (loop, memory, budgets, recovery)
| MCP or direct interface |
+---------------------+------------------+
|
Shared game controller
observations, validated actions,
planning, pause/step, outcome tracking
|
DFHack integration
|
Dwarf Fortress
Model independence and harness independence are separate goals. The game controller should expose the same typed operations through a direct interface and an MCP adapter. Each client needs its own integration and compatibility check. An optional runner would own unattended execution and use replaceable model adapters; connecting an MCP client alone does not provide that runner.
The design should support one active writer, bounded game advancement, interrupts, and structured action results. A queued building or work order is not a completed task. The controller must track progress and explain blocked work before the agent can plan reliably.
- Validate the environment. Record one exact DF/DFHack version pair, confirm the control channel, and use a disposable test save.
- Evaluate existing integrations. Try a read-only advisor and compare its summaries with the game. Decide what to reuse, extend, or build from the evidence.
- Prove control and feedback. Pause, observe, issue a small validated action, advance a bounded interval, and verify its outcome. Exercise interrupts, retries, missing materials, and restart recovery.
- Run a small autonomous scenario. Complete specified construction and production goals on a prepared fortress, then attempt thirty in-game days before expanding scope.
- Compare approaches. Use the same saved starts and permitted automation for each model and a rules-only baseline. Record survival, reserves, completed work, failures, latency, and compute or API cost.
Success in the early experiments means accurate observations, no overlapping steps or duplicate orders, explicit blocked-task feedback, and recovery without silently losing pending work. Fresh embark automation, combat, and general fortress autonomy come later.
- DFHack: the proposed game integration foundation.
- Quickfort documentation: blueprint tooling; investigate Dreamfort for reusable layouts.
- BenLubar/df-ai: prior work on autonomous fortress management.
- dfhack-mcp: an integration candidate to inspect before duplicating work.
These are research references, not claims of current compatibility with this project.
- Original concept: initial proposal and illustrative code.
- Evaluation and plan: analysis, candidate approaches, and assumptions to test.
- Design record: decision log, open questions, proposals and research, with explicit statuses.
- Contributing: how to propose experiments and report findings.
- Feasibility and approaches discussion: feasibility, architecture alternatives, and results.
The older design documents contain unvalidated claims and estimates. Treat them as starting points for investigation; this README describes the project's current status.