Building a Real-Time AI Bridge for a Tabletop RPG

Sat, 25 Apr 2026 00:00:00 +0000

I play Dungeons and Dragons. Specifically, I run it: I’m the Dungeon Master, which means I’m responsible for the world, the story, the non-player characters, the rules, the pacing, and the improvised dialogue of every person in that world who isn’t one of my players. It’s a lot to carry, and preparation time is always under pressure.

I’ve been using AI heavily for prep: developing characters, writing scene descriptions, planning encounters. But during sessions I kept running into the same problem. The AI was in a separate browser window. The game was happening somewhere else. Keeping the AI contextually aware of a live session, while simultaneously running that session, is genuinely difficult. I was either neglecting the AI because I was too busy, or breaking the flow of the game to type updates.

The obvious solution was to connect them directly.

What is a Virtual Tabletop?

A Virtual Tabletop (VTT) is software that replicates the tabletop RPG experience online: shared maps, character sheets, dice rolling, fog of war, initiative tracking, and a shared chat window where the game’s narrative plays out. It’s the online equivalent of sitting around a physical table.

Fantasy Grounds Unity (FGU) is one of the leading VTTs. It’s a desktop application with a rich extension system, a large library of officially licensed content, and a dedicated community. I run all my games through the FGU chat window: we play online, and keep a Discord open purely for out of game chat and clarification.

The Problem, Precisely Stated

FGU has no native AI integration. To use AI during a session you have to:

Watch what’s happening in FGU
Manually summarise it in a separate AI chat window
Ask your question
Copy the response back into FGU

At a live table, with players waiting, that workflow falls apart quickly. What I needed was for the AI to be watching the session alongside me, building its own awareness of events as they happened, so that when I needed something I could ask with minimal friction and get an answer that was already grounded in the current situation.

The Architecture

The solution has three components.

A Lua extension inside FGU. FGU supports custom extensions written in Lua. This extension registers a set of GM-only slash commands in the chat window. When a GM types a command, the extension writes a small JSON request to FGU’s console log.

A Python server running locally. This is the middleware. It does two things simultaneously: it monitors FGU’s chatlog.html file for new entries, and it monitors the console log for GM commands. The chatlog monitor feeds session events continuously into a conversation history buffer held in memory. When a GM command arrives, that buffer is sent to the Anthropic API along with the GM’s request and a system prompt containing the campaign notes.

The Anthropic API (Claude). Receives the full context, generates the response, returns it. The Python server copies the response to the system clipboard. The GM switches to FGU, pastes into the chat box, edits if needed, and sends.

FGU chatlog.html → Python monitors continuously
Session events accumulate in memory (no API call, no cost)
GM types /npctalk → console.log → Python detects it
Full context sent to Anthropic API
Response copied to clipboard
GM: Ctrl+V into FGU chat → Enter

How the Live Context Works

This is the part I find most interesting from a systems perspective.

FGU writes everything that happens in a session to chatlog.html: player dialogue, attack rolls, damage results, initiative order, turn markers. The Python server polls this file every 0.4 seconds. New lines are parsed, stripped of HTML, and appended to a Python list in memory. Mechanical lines (dice rolls, attack results) are prefixed with [ROLL] so Claude understands they are game events rather than speech.

Every few seconds, pending events are flushed into the conversation history as a [TABLE] message with a silent acknowledgment response. This maintains the alternating user/assistant structure the Anthropic API requires, without making any API call. Claude never responds to [TABLE] messages: the system prompt instructs it to absorb them silently and wait for a GM command.

When a command arrives, the pending events are flushed, the GM’s request is appended, and the entire conversation history is sent to the API in a single call. Claude has seen everything that happened at the table and can respond accordingly.

The conversation history persists in memory for the duration of the server session. Nothing is written to disk. The only persistent files are the campaign notes, which the GM maintains between sessions.

The Campaign Notes

Two markdown files provide Claude’s background knowledge.

campaign_history.md is the accumulated record of the campaign: the world, the player characters (race, class, personality, relationships, backstory), session recaps, established facts, and ongoing story threads. It grows over the course of a campaign and is updated after each session.

session_notes.md is the preparation for a specific session: scene descriptions for every location the party might visit, full NPC profiles (personality, voice, manner, combat behaviour), GM notes, and secrets Claude should know but never reveal.

Both files are loaded at server startup and injected into the system prompt of every API call. They are the static foundation. The chatlog is the live layer on top.

The GM Commands

All commands are slash commands typed in the FGU chat box. They are intercepted by the Lua extension before display: players never see them.

/describe — generates a sensory scene description and posts it to chat. Pure observation: what you see, hear, smell, feel. No inner states, no narrative closure.

/npctalk (Name) — generates the named NPC’s spoken dialogue only. No action, no mannerism. Ready to paste while talking as that character in FGU.

/npcaction (Name) — generates what the NPC physically does. No dialogue.

/combatsummary — reads the recent attack rolls and results from the chatlog and writes a narrative description of what just happened.

/claude — freeform private query, whispered to the GM only. Players never see the response.

/setscene — updates the current scene context in the config. Does not clear conversation history: NPCs travelling with the party retain their context across scene changes.

/claudereset — clears all conversation history. For use when you want a genuine fresh start.

Cost

API calls are the only cost. The chatlog monitoring and context accumulation between commands is free.

Each call sends the full system prompt (campaign notes) plus the accumulated conversation history. Cost per call increases gradually through a session as history grows. The model is configurable: Claude Haiku is the default, being the fastest and cheapest option. A full session will typically cost no more than a couple of dollars, often considerably less, depending on session length, note file size, and how many commands you send.

What It Produces

The quality of output depends directly on the quality of the notes files. A well-written NPC profile produces consistent, specific, in-character dialogue. A vague placeholder produces generic responses.

The system prompt enforces strict output rules: no inner states or emotional speculation, no concluding statements, no narrative padding. /npctalk returns only spoken words. /npcaction returns only physical behaviour. /describe returns only sensory observation. The discipline is deliberate: at a live table you need responses, not prose.

The Repo

The full project, including the Lua extension, Python server, and markdown templates for the notes files, is on GitHub:

https://github.com/heyjudeuk/fgu-claude-bridge

The README covers installation step by step. You’ll need Python, an Anthropic API key, and Fantasy Grounds Unity. The extension was built and tested against FGU 5.1.8.

One note for anyone who goes looking at the Lua code: FGU Unity 5.x uses Comm.registerSlashHandler for custom slash commands. Older tutorials and documentation reference ChatManager.registerSlashCommand, which no longer exists. That cost a few debugging rounds to establish.

The broader pattern here is one I find myself returning to repeatedly: most useful AI integrations are not about replacing a workflow but about removing the friction in an existing one. The game was already happening in FGU. The AI was already capable of generating what I needed. The problem was the gap between them, and the gap turned out to be a 200-line Python file and a Lua extension.

Python on echo3.co