Gamehost Guide: Turn-Based Multiplayer With an AI Game Master
What the Gamehost Actually Manages
Running a multiplayer game on top of a raw LLM chat quickly runs into three problems. Players need secrets, a hidden role, a hand of cards, a private objective, but a shared conversation shows everyone everything. Turns need order, but a chat has none. And the rules need to be enforced consistently across the whole session, not re-explained by every client.
The gamehost type handles all three inside the server. Secret setup data is collected per player before the game begins and is never revealed in the shared narration. The current turn is tracked numerically, advancing only when all active players have submitted. And your game's rules ride along as text that the host applies every turn. The result is that a browser game, a Unity client, or even a group chat integration can run a structured game with nothing more than HTTP calls.
The Game Flow, Step by Step
Step 1: Player 1 Starts the Game
The first message of a new game declares the game's shape: send numPlayers (1 to 10), player: 1, and that player's startData, their secret setup info. Include your gameRules text and any actionsList definitions here too. Save the returned convoID and share it with the other players' clients, it is the session handle everyone will use.
Step 2: The Other Players Check In
Each remaining player sends the same convoID, their own player number, and their own startData. During this pre-game phase the response's currentTurn stays at -1. The moment everyone has submitted, currentTurn becomes 0 and the game begins, your clients can watch that field to flip from a lobby screen to the game screen.
Step 3: Playing a Turn
During a turn, players chat freely with the host, asking questions, talking in character, probing the situation, without advancing anything. A player commits their move by including playerData with their submission. The response's playerData field shows which submissions are in for the current turn, and when all active players have submitted, currentTurn advances and the host narrates the outcome.
Step 4: Players Leaving
A player whose playerData contains "quit" or "lose" is removed from the active player list, and future turns stop waiting for them. This keeps a game moving when someone drops or gets eliminated, no stuck sessions waiting on a ghost.
Step 5: Rules and Custom Actions
Send your game's mechanics in gameRules, written as plainly as you would explain them to a human game master: what players do each turn, how conflicts resolve, what ends the game. Define the signals your client cares about in actionsList as an object of {"actionName": "when to fire it"} pairs, then watch the response's action field for them. A card game might define roundWon and gameOver, a social deduction game might define playerAccused and voteCalled.
Design Tips That Save Pain
Write rules like a rulebook, not code. The host applies your gameRules the way a human reads them. Short declarative rules with concrete examples beat long conditional prose. If a rule keeps being misapplied, rewrite it more plainly rather than adding exceptions.
Drive the UI from actions, not text parsing. The narration is for players to read. Your client logic should key off currentTurn, playerData, and your custom actions, never off matching phrases in the prose, which will change from response to response.
Use the knowledge base for content-heavy games. If your game has a big card list, a bestiary, or scenario content, load it into the knowledge base instead of stuffing it into gameRules. Retrieval brings in the relevant pieces per turn and keeps token costs sane.
Solo games are gamehost games too. A single-player roguelike narrator with structured turns works the same way with numPlayers: 1, and you still get turn tracking and custom actions. For free-flowing narrative without turn structure, a storyteller bot is the better fit.
Where the Networking Fits
The gamehost tracks game state, but delivering updates to the other players' screens is still your client architecture's job: each client can poll with its own chat calls, or your game server can relay. For browser games, the patterns in our multiplayer web games pillar, especially websockets for pushing updates, pair naturally with a gamehost session.
The gamehost turns one shared conversation into a structured game: secret per-player setup, chat-freely-then-submit turns via playerData, automatic turn advancement when everyone is in, plain-text rules, and custom action signals for your UI. Watch currentTurn and action, and let the host do the refereeing.