df-storyteller 0.2.0

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
git clone https://github.com/Been012/df-storyteller.git
cd df-storyteller
pip install -e .

# Configure (one time)
python -m df_storyteller init

# In DFHack console (first time per fortress)
storyteller-begin

# Launch web UI
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

Note

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. API keys are stored in your local config file at ~/.df-storyteller/config.toml.

License

MIT