AI D&D

What makes it more than a chat wrapper

Four things a plain "talk to a model" app doesn't do.

The story is a tree

Any turn can hold more than one take. Stepping between them is free — the story below simply empties, and the server is told nothing. Writing below a take that isn't the live one is what makes a branch, and a branch stores no turns of its own: it records where it left its parent and borrows everything above that. Twenty forks cost 1.007× the page load of the same story flat. Switch lines and the world state, the script scoreboard and the cooldown clocks all come back to what that line left.

The AI proposes, Python referees

A scenario declares stats, flags, milestones and a named cast. Each turn the model appends the changes it thinks happened — and the engine clamps them to range, enforces per-turn caps and cooldowns, keeps counters monotonic and milestones sticky, then strips the machine-readable block out of the prose. Word-labelled bands (40–60: minor damage) are what make the model reliable at it. No dice, no scripting required.

You can see the entire prompt

Every turn stores exactly what was sent to the model. Open Insights on any action to see each context component, what it cost in tokens, and why it was there — including which trigger word pulled in each story card and the similarity score behind each retrieved memory.

Real AI Dungeon scripts run

The three familiar hooks — onInput, onModelContext, onOutput — with shared persistent state and a worldEntries API, executed in an embedded quickjs sandbox. Scripts written for AI Dungeon import and work, and there's a CodeMirror editor in the app.

Memory that survives a long story

The modern AI Dungeon memory system: AI-generated memories every few actions, a running story summary, and embedding-based retrieval that pulls an old-but-relevant fact back into context when it matters. Undo and retry roll the world state back to a per-action snapshot rather than only rewriting the text. Every story stays where you left it, and the home page opens on its most recent line.

How a turn works

Player input goes through the script pipeline, into a token-budgeted context, out to whichever model you configured, and back through the referee.

player input
  → onInput script modifier
  → assemble context:  [narrator prompt] + [world state + stat guide] + [AI instructions]
                       + [plot essentials] + [story summary] + [retrieved memories]
                       + [triggered story cards] + [history along this branch, token-budgeted]
                       + [author's note] + [player action]
  → onModelContext script modifier
  → snapshot context (Insights)
  → provider adapter → AI (streamed)
  → extract + referee the world-state delta block, strip it from the prose
  → onOutput script modifier
  → store & render

Engineering notes

The parts that were measured rather than guessed at.

• Database egress, cut ~189×. Every adventure load was pulling the entire assembled prompt — about 74 KB per turn — just to read two small fields off it. Moving those into their own columns and deferring the heavy ones took one load from 38.5 MB to 0.20 MB. A test hooks into SQLAlchemy's cursor events and fails if a bulk load ever names those columns again.
• Turn cost, made flat. Assembling a turn walked the whole story, so it grew with story length — 839 KB of reads by turn 200. History is now served as tails and slices from SQL: the same turn costs 129 KB and stops growing at around turn 50.
• Branching that costs 103 bytes. A branch stores where it left its parent and borrows every turn above that, so nothing is copied on a fork. A 40-turn story forked twenty times loads in 31,652 B against 31,433 B for the same story flat — 1.007×. Reads stay cheap because the ancestry is windowed the way the history is: the number of SQL clauses is bounded by the context window, not by how many times the story has forked.
• A shared demo key that can't be drained. The hosted demo funds a model for visitors, so model selection is pinned server-side with a structural backstop that raises if any code path tries to resolve a model outside the allowed set — plus a daily per-visitor turn cap.