df-storyteller 0.2.1

Dwarf Fortress storytelling assistant — turns game events into narrative stories

df-storyteller

A storytelling companion for Dwarf Fortress. Captures game events, dwarf personalities, and world history through DFHack, then generates AI-written narratives grounded in your actual gameplay.

Full Documentation on the Wiki

Features

Narrative Generation

• Fortress Chronicles — Seasonal narratives tracking what's changing in your fortress
• Dwarf Diaries — First-person journal entries shaped by personality, beliefs, and stress
• Character Biographies — Dated entries that evolve as dwarves change over time
• Death Eulogies — Memorial narratives for fallen dwarves
• Battle Reports — Dramatic combat accounts written by survivors or the fortress chronicler
• Epic Sagas — World history narratives from legends data
• Fortress Gazette — A dwarven newspaper with five sections, written by the fortress's best writer

Quest System

• AI-Generated Quests — Based on your actual fortress state, grounded in real DF mechanics
• Narrative-Driven — Quests that drive the story (character arcs, threats, faith, ambition)
• Difficulty Tiers — Easy, Medium, Hard, Legendary
• Completion Narratives — AI writes how the quest was fulfilled, feeds into future chronicles

Visualization & Data

• Relationship Web — Interactive force-directed graph of fortress connections
• Pantheon — Deity worship chart with sphere descriptions from legends
• Combat Log — Blow-by-blow fight details with siege grouping
• Chat Log — Dwarf conversations with AI social summaries
• Lore Browser — Searchable world history with hover tooltips (kill counts, battle forces, relationships)
• Live Event Feed — Real-time game events via WebSocket

Screenshots

Chronicle

Dwarves

Relationship Web

Pantheon

Events

Lore

Quests

Gazette

Quick Start

Install and run:

pip install df-storyteller
python -m df_storyteller init
python -m df_storyteller serve

In DFHack console (first time per fortress):

storyteller-begin

Or install from source:

git clone https://github.com/Been012/df-storyteller.git
cd df-storyteller
pip install -e .
python -m df_storyteller init
python -m df_storyteller serve

Requirements

• Dwarf Fortress v50.x (Steam / DF Premium) — tested with v50.14
• DFHack v50.14-r1+ (Steam Workshop or dfhack.org)
• Python 3.11+
• An LLM provider (one of):
  • Ollama — free, runs locally, no API key needed (supports thinking models)
  • Anthropic Claude — API key required
  • OpenAI — API key required

Note: This tool uses DF Premium (Steam) APIs. Classic DF (pre-Steam) is not supported — some DFHack fields like unit.relations don't exist in the Steam version. We use histfig_links on historical figures instead.

Tech Stack

• Backend: Python 3.11+, FastAPI, Pydantic v2
• Frontend: Jinja2 templates, vanilla CSS/JS (no build step)
• Game integration: DFHack Lua scripts
• LLM: Anthropic SDK, OpenAI SDK, Ollama REST API (with thinking model support)
• All narratives grounded in DF mechanics — the AI knows squad sizes, siege thresholds, temple values, what players can and cannot control

Documentation

See the Wiki for:

• Installation & Setup
• Architecture
• Configuration
• LLM Integration
• Feature guides for every tab

Notes

• This tool is designed to run locally on your machine (localhost). It is not intended to be exposed to the internet or run on a public server.
• Developed and tested on Windows with DF Premium (Steam). Should work on Mac and Linux — all code uses cross-platform libraries (pathlib, FastAPI) and DFHack APIs are platform-independent — but these platforms are untested. If you run into issues, please open a bug report.
• Config and stories are stored at ~/.df-storyteller/. API keys are in config.toml.

License

MIT