How It Works

The turn cycle

Every player action follows the same five-step cycle:

1. Player input — the player types what they want to do or say.
2. Context assembly — MGPT loads the saved universe, uses its frozen generation contract, applies the block-aligned conversation window, and includes the player's new input.
3. Generation — MGPT calls the model; MDL receives structured JSON (`assistantRaw`) and applies it to the universe.
4. State merge — the output is merged into the universe state and persisted.
5. Render — the UI displays the new beat: resolved stock or generated scene art, character sprites, dialogue, music, and effects.

Structured output

The AI doesn't return raw text. It returns a JSON object with specific fields that the renderer understands. This is what makes visual presentation possible.

Context window

The AI only sees a block-aligned slice of the stored conversation (assistant state turns on the current branch). The MGPT backend applies that window using the same rules as lib/prompt-block-window.ts:

• First 64 assistant turns — the full branch is included in the model prompt (plus your new player input for the request).
• Beyond 64 turns — the window snaps to 64-turn blocks. When a new block starts, the prompt keeps the last 16 assistant turns from the previous block and everything in the current block (so long stories retain a bounded overlap instead of a hard cut).
• Older beats fall out of the prompt automatically. The universe save still stores the fullhistory for the player timeline.
• The client never sends raw instruction text. Generation uses the server-side universe contract and stored conversation.

Continuity beyond the visible window must live in presentation state (background, foreground, dialogue, time, etc.) and in the beats that remain in context.

Universe state

Each player's save is called a universe. It contains:

• Current presentation state (background, foreground sprites, optional generated visuals, music, etc.).
• Full turn history with player inputs and AI outputs.
• Generation uses the stored conversation and block-aligned prompt window.

Universes auto-save after every turn. Players can close the browser and return later — their story picks up from the last state. Players can also have multiple save slots.

Generation contract

Each universe carries a frozen generation contract derived from the hosted game workspace. That contract keeps gameplay stable for an existing save while still allowing package pushes to refresh affected universes through the explicit hosted sync path.

• Runtime instructions — game-owned instruction text frozen from the hosted workspace.
• Structured output contract — the schema snapshot MGPT uses for provider structured-output assembly.
• Additional instructions — optional addendum text frozen with the universe and enabled per request.
• Runtime context — protagonist, language, visual descriptions, and saved presentation state read from the universe.

You author the hosted instructions, schema, and assets. MDL does not accept a client-supplied instruction string for text generation, and provider details stay inside the backend.

Runtime config and boot

When a player loads your game, the client fetches /api/runtime-config, which returns:

• Runtime UI configuration (title screen, presentation settings).
• Optional gameId / gameSlug for hosted games (checkout and telemetry).
• The hosted runtime asset catalog (URLs for all sprites, backgrounds, music, and effects).

Generation is server-owned: the client posts universe, statePointer, userInput, and optional requestId to /api/generate. The pointer is a client cursor, not a persisted universe field. MDL loads the stored timeline, truncates any future branch from the supplied pointer, ensures the frozen generation contract exists, forwards identifiers plus output/instruction flags to MGPT, then applies and persists the returned assistant output.

Next