Dungeon Mind (DM)
What is Dungeon Mind?
Dungeon Mind is an AI game mechanics agent you can attach to your storylines. It handles dice rolls, stat tracking, inventory, skills, and rule enforcement — so your story AI focuses purely on narrative while the DM handles all the game logic behind the scenes.
You configure three things:
- Game Rules — Your custom ruleset (combat, leveling, death, etc.)
- Instruction — Tells the story AI when to call the DM
- Stat Schema — The stats every character has
Everything else (the dice system, tool mechanics, stat tracking) works automatically.
How It Works
When a player does something that needs a dice roll or stat change, the story AI calls the Dungeon Mind. The DM then rolls dice, applies your rules, updates stats, and returns results. The story AI writes narrative — the UI shows the mechanics.
Flow Diagram
Player sends message
│
▼
┌─────────┐
│ Story AI │ ── reads situation, decides if DM is needed
└────┬─────┘
│ calls engage_dungeon_mind({ situation: "..." })
▼
┌──────────────────────────────────────────────────────┐
│ DUNGEON MIND (DM) │
│ │
│ Step 0: Check & Prepare │
│ ┌─────────────────────────────────────────────┐ │
│ │ Invalid action? → reject_action (stop) │ │
│ │ Need input? → ask_player (stop) │ │
│ │ New character? → auto_create_character │ │
│ │ + create_stats + set_skills│ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ Step 1: Roll Dice ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ roll_d20(Player, "STR attack vs Goblin") │ │
│ │ roll_d20(Goblin, "DEX dodge") │ │
│ │ roll_d20(Healer, "WIS heal spell") │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ │ sees actual roll numbers │
│ ▼ │
│ Step 2: Apply Results & Submit │
│ ┌─────────────────────────────────────────────┐ │
│ │ set_inventory(Player, +Goblin's Gold) │ │
│ │ set_skills(Player, +New Ability) │ │
│ │ submit_results([ │ │
│ │ { Player rolled 18 ✓, stat_changes: [ │ │
│ │ Goblin HP -8 ] }, │ │
│ │ { Goblin rolled 5 ✗, stat_changes: [] }, │ │
│ │ { Healer rolled 14 ✓, stat_changes: [ │ │
│ │ Player HP +6, Healer MP -10 ] } │ │
│ │ ]) │ │
│ └─────────────────────────────────────────────┘ │
│ │
└───────────────────────┬───────────────────────────────┘
│ returns rolls, stat changes,
│ skill/inventory changes, summary
▼
┌─────────┐
│ Story AI │ ── writes narrative based on results
└────┬─────┘ (does NOT mention numbers)
│
▼
┌──────────────────────────────────────────┐
│ PLAYER SEES │
│ │
│ ┌─ Story text (narrative only) ────────┐ │
│ │ "Your blade cuts through the goblin's│ │
│ │ guard. It staggers back, wounded..." │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌─ Roll bars (auto-displayed) ─────────┐ │
│ │ [Avatar] 18 ✓ Player │ │
│ │ STR attack. Roll 18+2=20 vs DEF 12. │ │
│ │ Goblin HP: 40 → 32 │ │
│ │ │ │
│ │ [Avatar] 5 ✗ Goblin │ │
│ │ DEX dodge. Roll 5+1=6 vs 14. Fail. │ │
│ │ │ │
│ │ [Avatar] 14 ✓ Healer │ │
│ │ WIS heal. Roll 14+3=17 vs DC 12. │ │
│ │ Player HP: 28 → 34, + New Ability │ │
│ └───────────────────────────────────────┘ │
│ │
│ ┌─ Character sheet (tap to view) ──────┐ │
│ │ HP ████████░░ 34/50 │ │
│ │ MP ██████████ 20/20 │ │
│ └───────────────────────────────────────┘ │
└───────────────────────────────────────────┘
Question / Rejection Flow
┌──────────────────────────────────────┐
│ DUNGEON MIND │
│ │
│ Step 0: Player tries to resurrect │
│ a dead character │
│ │
│ ┌────────────────────────────────┐ │
│ │ reject_action( │ │
│ │ "Death is permanent. │ │
│ │ Cannot resurrect." │ │
│ │ ) │ │
│ └────────────────────────────────┘ │
│ │
└───────────────┬───────────────────────┘
│
▼ story AI STOPS
┌───────────────────────────────────────┐
│ [Dungeon Mind (DM) Rejected] │
│ "Death is permanent. Cannot resurrect."│
└───────────────────────────────────────┘
┌──────────────────────────────────────┐
│ DUNGEON MIND │
│ │
│ Step 0: Player levels up, │
│ needs to choose stats │
│ │
│ ┌────────────────────────────────┐ │
│ │ ask_player( │ │
│ │ "Level up! Choose 2 stats │ │
│ │ to increase: STR, DEX, │ │
│ │ or INT?" │ │
│ │ ) │ │
│ └────────────────────────────────┘ │
│ │
└───────────────┬───────────────────────┘
│
▼ story AI STOPS
┌───────────────────────────────────────┐
│ [Dungeon Mind (DM) Asks] │
│ "Level up! Choose 2 stats to │
│ increase: STR, DEX, or INT?" │
└───────────────────────────────────────┘
│
│ player answers "STR and INT"
▼
DM called again → applies level up
Available Tools
These are the tools the DM can use. You don't need to build these — they're built into the system. Your game rules tell the DM when and how to use them.
roll_d20
Rolls a 20-sided die for a character. This is the core randomization tool.
- character — who is rolling
- reason — what the roll is for (e.g. "STR attack vs goblin")
- advantage — roll 2d20, take the higher (optional)
- disadvantage — roll 2d20, take the lower (optional)
The actual roll is server-side and cannot be manipulated. Your game rules define what the roll means (attack vs defense, skill check vs DC, saving throw, etc.).
create_stats
Sets up ALL stats for a new character. Called once when a character first appears.
The parameters are generated from your stat schema. If your schema has HP, STR, and Status — the tool will have HP_value, STR_value, and Status_value fields.
set_stats
Updates a character's stats. Only the changed stats need to be included.
Each stat has two fields:
- value — the permanent base number (e.g. STR goes from 14 to 15 on level up)
- modifier — a temporary change that stacks (e.g. -8 for damage, +5 for a buff)
How modifiers work:
The modifier is a delta — the system adds it to whatever the current modifier already is. You don't need to track the total. Just say "take 8 damage" as -8 and the system handles accumulation.
| What the DM sends | Current modifier | New modifier | Meaning |
|---|---|---|---|
| HP_modifier: -8 | -10 | -18 | Took 8 more damage |
| HP_modifier: +5 | -18 | -13 | Healed 5 |
| HP_modifier: 0 | -13 | 0 | Full heal (reset) |
set_inventory
Adds, removes, or updates items. Each item has a name, quantity, description, and equipped status.
set_skills
Adds or removes abilities. Each skill has a name and description.
submit_results
The final tool called after dice rolls. Contains:
- One result per roll with success/fail, detail text, and stat changes
- A mechanical summary
Stat changes go inside each result — this links them to the correct roll in the UI. For example, if Character A attacks Character B, the damage to B goes inside A's result entry.
ask_player
Asks the player a question before continuing. Use when the DM needs player input (e.g. "Which stats do you want to increase?"). The story stops and waits for the player to answer.
reject_action
Rejects an invalid action. Use when something violates your game rules (e.g. acting while dead, impossible stats). The story stops and explains why.
auto_create_character
Creates a new character with an AI-generated portrait. Only used for genuinely new characters — not for transformations or form changes of existing characters.
Writing Game Rules
The game rules prompt is the heart of your DM configuration. This is where you define how your game works.
What to include
Combat mechanics — How do attacks work? What stats are involved?
Attacker rolls: d20 + STR bonus vs Defender's DEX defense (10 + DEX bonus)
Damage = STR bonus + floor(roll / 4). Minimum 1.
Difficulty checks — How hard are skill checks?
d20 + stat bonus vs difficulty:
- 8 easy, 12 medium, 16 hard, 20 very hard
Critical rolls — What happens on natural 20 or natural 1?
Natural 20 = ALWAYS SUCCESS. Double damage. Describe an epic moment.
Natural 1 = ALWAYS FAILURE. Describe a dramatic failure.
Advantage & disadvantage — When should the DM roll 2d20?
Advantage: ally help, surprise, creative actions
Disadvantage: blinded, exhausted, untrained
Resources — How do HP, MP, or your custom resources work?
Effective HP = base + modifier. HP <= 0 = dead.
Spells cost MP. Deduct from modifier.
Conditions — Status effects with duration
Format: "Poisoned (3t)" where 3t = 3 turns remaining
Each turn, decrement by 1. Remove at 0.
Progression — Leveling, XP, stat growth
XP Thresholds: Level 2=100, Level 3=300, Level 4=600...
Level Up: +1 to two stats, increase base HP, reset all modifiers
Healing & rest — How do characters recover?
Short rest: 25% HP recovery
Full rest: full heal, clear conditions
Healing ONLY from: rest, potions, or healer spells
Death — What happens when HP reaches 0?
Death is PERMANENT. No resurrection. Dead characters cannot act.
Anti-cheat — What should the DM reject vs allow?
Reject: impossible stats, acting while dead, free self-healing
Allow: all combat actions, risky decisions, creative solutions
Key: resolve actions with consequences, don't prevent player choices
Tips for good game rules
- Be specific with formulas. Show the math. "Damage = stat bonus + floor(roll/4)" is better than "calculate damage."
- Use examples. "Roll 16 + 3 STR bonus = 19 vs DC 15. Hit! Damage: 3 + 4 = 7."
- State absolute rules. "Natural 20 = ALWAYS SUCCESS. No exceptions." The DM follows what you write.
- Define what to reject clearly. List specific cheating scenarios.
- Don't restrict player choices. "NEVER reject combat actions — resolve with dice and apply consequences." Let players make bad decisions and face the results.
- Keep it organized. Use headers (## and ###) to separate sections. The DM reads this as a reference.
Writing the Instruction
The instruction tells the story AI (not the DM) when and how to call the Dungeon Mind. This goes into the story agent's system prompt.
What to include
- When to call the DM — List every situation that needs game mechanics
- How to describe situations — Narrative only, no stat numbers
- How to handle results:
- Resolved → write the story, don't mention numbers (the UI shows them)
- Question → ask the player directly, wait for answer
- Rejected → narrate why the character can't do it
Example instruction
This story has a Dungeon Mind (DM) that manages ALL game mechanics.
Call engage_dungeon_mind whenever:
- Combat, attacks, damage
- Skill checks, saving throws
- Magic or ability use
- Resting, healing
- Level ups, stat changes
- Inventory changes
- Death
- Any uncertain outcome
Describe ONLY the situation — no stat numbers or mechanics.
After receiving results:
- Resolved: write the narrative. Don't mention numbers — the UI shows them.
- Question: ask the player directly and wait for their answer.
- Rejected: narrate why it's not possible.
Tips
- Adapt the trigger list to your game. A social intrigue game might trigger on "persuasion, deception, investigation" instead of "combat, damage, saves."
- Always tell the story AI not to mention numbers — the frontend displays all mechanical data separately.
Designing Your Stat Schema
The stat schema defines what stats every character has. The DM's tools are generated dynamically from this schema.
Stat types
| Type | Use for | Examples |
|---|---|---|
| number | Anything quantitative | HP, Strength, Gold, Level, XP |
| text | States and labels | Status ("Alive"/"Dead"), Condition ("Poisoned (3t)") |
Design tips
- 5-15 stats is ideal. Fewer = faster, simpler. More = richer but slower tool calls.
- Descriptions matter. The DM reads them to understand what each stat does and how to use it.
- Number stats have base + modifier. The modifier is for temporary changes (damage, buffs). The base is permanent.
- Text stats are direct values. Set them to whatever string makes sense.
- Stat names become tool parameters. A stat named "HP" creates
HP_valueandHP_modifierin the tools. Keep names simple — letters, numbers, and spaces only. - You can't use "character" or "roll_index" as stat names — these are reserved.
Special stat names (optional, but the UI recognizes them)
These stat names are completely optional — your game works fine without them. But if you use them, the frontend will display extra UI automatically:
| Stat Name | What the UI does |
|---|---|
| HP | Shows a health bar (green/yellow/red) on the character card. Color changes based on percentage remaining. |
| MP | Shows a thin blue mana bar below the HP bar on the character card. |
| Status | Shows a colored dot on the character card — green when value is anything other than "Dead", red when "Dead". Usually reserved for "Alive" / "Dead". If Status is "Dead", the HP bar shows 0. |
| Condition | Shown next to the status dot as secondary text (e.g. "Poisoned (3t)"). |
If your game doesn't have HP, MP, Status, or Condition — no bars or indicators will appear. The character card simply won't show them. Everything still works mechanically through the stat sheet.
Example schemas
Classic RPG (13 stats):
| Stat | Type | Description |
|---|---|---|
| Status | text | "Alive" or "Dead" |
| Condition | text | Active conditions with turns (e.g. "Poisoned (3t)") |
| HP | number | Hit points |
| MP | number | Mana points |
| STR | number | Strength — melee attacks |
| DEX | number | Dexterity — ranged, dodge |
| CON | number | Constitution — health, endurance |
| INT | number | Intelligence — magic, knowledge |
| WIS | number | Wisdom — perception, willpower |
| CHA | number | Charisma — persuasion, deception |
| Level | number | Character level |
| XP | number | Experience points |
| Gold | number | Currency |
Minimal Combat (4 stats):
| Stat | Type | Description |
|---|---|---|
| Status | text | Alive or Dead |
| HP | number | Hit points |
| Attack | number | Attack power |
| Defense | number | Defense rating |
| Stat | Type | Description |
|---|---|---|
| Status | text | Active, Imprisoned, Exiled, Dead |
| Charm | number | Persuasion and seduction |
| Wit | number | Cleverness and deception |
| Influence | number | Political power |
| Reputation | number | Public standing (can go negative) |
| Gold | number | Wealth |
Survival Horror (6 stats):
| Stat | Type | Description |
|---|---|---|
| Status | text | Alive, Dead, or Infected |
| Condition | text | Conditions like "Bleeding (3t)", "Terrified" |
| Health | number | Physical health |
| Sanity | number | Mental health — drops on horror events |
| Stamina | number | Physical energy — running, fighting depletes it |
| Supplies | number | General resource count |
Card Game (5 stats):
| Stat | Type | Description |
|---|---|---|
| Status | text | Playing or Eliminated |
| Life Points | number | Lose all = eliminated |
| Mana Crystals | number | Spend to play cards |
| Hand Size | number | Cards in hand |
| Turn | number | Current turn number |
How the DM Handles Different Situations
Combat
Your game rules define attack/defense formulas. The DM:
- Rolls d20 for each combatant
- Applies your damage formula
- Updates HP via stat_changes in submit_results
- NPCs always fight back — they don't just stand there
Skill checks
Your game rules define DCs (difficulty classes). The DM:
- Rolls d20 + relevant stat bonus
- Compares against the DC you defined
- Determines success or failure
Level ups
Your game rules define XP thresholds and what happens on level up. The DM:
- Checks if XP meets the threshold
- For player characters: uses ask_player to let them choose
- For NPCs: auto-distributes based on role
- Updates stats, grants new skills
Rest & healing
Your game rules define what rest does. The DM:
- Applies healing (modifier changes)
- Clears conditions if your rules say so
- Checks for level ups during rest (if your rules say to)
Death
Your game rules define death conditions. The DM:
- Detects when the death condition is met (e.g. HP <= 0)
- Updates status
- Enforces permanence (if your rules say death is permanent)
Questions
When the DM needs player input (e.g. "Which stat do you want to increase?"):
- DM calls ask_player with the question
- Story AI stops and relays the question to the player
- Player answers
- Next message, the story AI calls the DM again with the answer
Rejections
When an action violates your game rules:
- DM calls reject_action with the reason
- Story AI stops and narrates why it's not possible
- Player can try something else
What Players See
Dice overlay
A fullscreen overlay with 3D animated dice. Shows:
- Character portrait
- Roll result (1-20) with color coding
- Advantage/disadvantage with both roll numbers
- Nat 20 gold glow, Nat 1 red glow
- Tap to advance, X to dismiss
Roll result bars
Compact bars below the story text showing:
- Character avatar with colored border
- Roll number with success/fail icon
- Detail text explaining the math
- Stat changes (green for gains, red for losses)
- Skill gains (purple)
- Inventory changes (gold)
- Tap to replay the dice animation
Character sheet
In chat settings, each character card shows:
- HP bar (green/yellow/red based on percentage)
- MP bar (blue, thin)
- Status indicator dot (green=alive, red=dead)
- SHEET badge to view full stats, skills, and inventory
DM questions and rejections
Styled message bars that appear inline:
- "Dungeon Mind (DM) Asks" — with the question text
- "Dungeon Mind (DM) Rejected" — with the reason
Quick Start
- Go to Creation tab → Dungeon Minds
- Tap + to create a new config
- Give it a name
- Tap Use Example on Game Rules to start with the default d20 RPG rules — then customize
- Tap Use Example on Instruction to start with the default — adjust triggers for your game
- Tap Use Example on Stat Schema to start with default RPG stats — or build your own
- Save
- Go to your storyline editor → select your DM config in the Dungeon Mind picker
- Start a new chat — the DM is now active