Have you ever wondered if an LLM could actually make a capable Gamemaster? If you have ever tried to play or build a text adventure with a standard AI model, you know the architectural frustration. The AI acts like a hyperactive improv partner. If you type 'I jump over the moon and slay the dragon with a spoon', the model simply hallucinates: 'Yes, you do that.' There is no state management, no constraints, and zero real game mechanics. But what if you combined a deterministic, rule-based RPG engine with an omniscient generative AI Gamemaster?
I wanted a genuine RPG experience with a strict Gamemaster, so I built TaleWeaver. It is an open-source, self-hosted RPG engine that generates dynamic worlds on the fly.
Here is how I solved the "LLM Amnesia" and enforced strict game mechanics using a 2-Pass Architecture.
The Problem: Mixing Mechanics and Narrative
LLMs are fantastic at writing atmospheric prose, but they are terrible at tracking state, hitpoints, and inventory items. If you force a single prompt to manage complex math and write a cinematic story simultaneously, the model will hallucinate.
The Solution: The 2-Pass Engine
I split the workload into two distinct processes to keep the game state intact:
1. Pass 1: The Rule Engine
When a user submits an action, a fast, highly logical model evaluates the input against the current game state. It performs hidden D20 stat rolls, checks the inventory, and calculates damage.
- Output: A strict JSON
GameEventthat mutates the database (e.g., updating HP, moving an NPC to a new scene, or adding loot).
2. Pass 2: The Gamemaster
Once the database state is safely updated, a creative narrative model takes the raw JSON outcome and translates it into an immersive, atmospheric response.
The Tech Stack
I built this engine to be completely self-hosted and robust:
- Backend: Python and FastAPI. The database is SQLite, fully tenant-ready with UUID-based primary keys.
- Frontend: Vue.js for a snappy, app-like experience.
- Dynamic Cartography: The engine automatically renders a live directed graph map of the discovered scenes using Rough.js.
- TTS Audio: Integrated Gemini 3.1 Flash TTS and ElevenLabs. The engine parses director notes to build dramatic tension directly into the audio output.
Bring Your Own Key (BYOK) & Local Execution
The entire stack is containerized with Docker for a frictionless 1-click setup. It uses the LiteLLM adapter under the hood. You simply plug in your API key for top-tier models, which are highly recommended to handle the complex JSON reasoning.
I also added experimental support for local Ollama execution. It is tough to get smaller local models to consistently output complex nested JSON, but it is a fun challenge to push the boundaries of offline play.
Check out the code
You can find the repository, the complete JSON manifest specifications, and the setup scripts here:
https://github.com/jschm42/taleweaver
Top comments (0)