DFHack Scripts

DFHack Scripts

Commands

storyteller-begin              # First-time fortress setup
storyteller-begin --yes        # Setup + export legends
storyteller-begin --snapshot-only  # Just take a snapshot
storyteller-snapshot           # Take a snapshot (alias)
storyteller-events start       # Start event monitoring
storyteller-events stop        # Stop event monitoring
storyteller-events status      # Check monitoring status
storyteller-events debug       # Manual poll + show all dwarf state

How It Works

storyteller-begin.lua

• Takes an initial snapshot of all fortress citizens with full data (personality, skills, relationships, equipment, etc.)
• Starts event monitoring via storyteller-events
• Optionally triggers legends export

storyteller-events.lua

• Polls DFHack every ~2 seconds of game time for changes
• Detects: profession changes, noble appointments, military changes, stress shifts, migrant arrivals, season changes, deaths
• Writes JSON event files to storyteller_events/{world}/
• Auto-starts when a fortress loads via onMapLoad.init

Data Captured Per Dwarf

• Name, profession, age, race
• 50 personality facets with values
• Beliefs and values
• Physical and mental attributes
• Skills with experience levels
• Noble positions and military squad
• Relationships via histfig_links (spouse, family, friends, grudges, deity worship)
• Equipment, wounds, stress category

Relationship Extraction

Uses the DF Premium compatible histfig_links API on historical figures, not the deprecated unit.relations fields. Maps link class names (histfig_hf_link_spousest, histfig_hf_link_childst, etc.) to readable relationship types. Also resolves off-map historical figures by name.