ASCII game authoring and color contract
LocalGPT keeps game state, plain ASCII text, and presentation styling separate. This is intentional: a game frame remains copyable/searchable plain text while the shared terminal may render safe color metadata on top of it.
Evidence order for local models
For game work, especially with 0.8B, 1B and 2B local models, use this narrow order instead of guessing from broad repository context:
- Read the selected Project requirements, Game profile and compiled build facts.
- Read
localgpt.ascii.surface.getfor the current terminal capability andlocalgpt.game.display.palette.getfor exact palette rules. - Retrieve only the narrow LocalGPT Knowledge entry needed for the task.
- Use database-backed
localgpt.regex.list,localgpt.regex.getandlocalgpt.regex.testonly when a concrete parse/extraction task exists. Prefer an existing tested expression over inventing one. - Mutate the smallest sufficient display area; do not regenerate a complete frame when one text, fill or blit operation is enough.
This keeps small models supplied with LocalGPT-specific facts while avoiding irrelevant context that can pull them toward unrelated project conventions.
Color modes
TerminalDefault preserves LocalGPT's established black/green terminal for unstyled cells. Explicit style runs may still use indexed colors. Ansi16 uses indexes 0-15 and defaults to bright green 10 on black 0. Indexed256 uses xterm-compatible indexes 0-255 and defaults to green 46 on black 0.
Never place raw ANSI escape sequences or HTML in canonical frame text. Use CouncilAsciiTextStyle metadata or the matching DXFunction JSON style object with optional foreground/background indexes plus bold, dim and invert flags.
A complete frame may carry bounded horizontal styleRuns with y, x, length and style. Animations may carry matching per-frame runs and a subtitle style. LocalGPT clips/normalizes runs to the live session dimensions and browser rendering creates only text nodes and safe spans.
Choosing display operations
Use localgpt.game.display.get for current dimensions/content and localgpt.game.display.palette.get for palette indexes. Prefer:
localgpt.game.display.cell.setfor one cell.localgpt.game.display.text.writefor a short styled line or label.localgpt.game.display.region.fillfor panels, clears and repeated textures.localgpt.game.display.region.blitfor a multiline sprite or ASCII art block; this is usually the most efficient choice for small models.localgpt.game.frame.submitonly for a complete still frame.localgpt.game.animation.submitfor one pregenerated 2-12 frame sequence; never call the model once per animation frame.
Human, Shared and AI control modes all use the same authoritative game/session contracts. Presentation functions never own HP, collision, bracket progression, inventory, rules or winners.
Existing and custom games
The same presentation contract applies to the seeded corridor/DOOM, arena, Green Dragon and Kernel Creature Tournament game projects, to hot-seat experiences and to Project-built/custom prompted ASCII games. A Project Game profile persists its color mode and default foreground/background values; the compiled ProjectGameDefinition carries them into the runtime session. No game needs a renderer-specific state model to gain color.
Games as declarative content (7.0.0)
Since 7.0.0 the engine contains no game. ASCII DOOM, the ASCII arena, Green Dragon and the Kernel Creature Tournament are
ordinary Game projects whose rules live in database tables. One generic engine (IGameEngineRuntimeService) interprets
them; no rule row contains code. A user-authored game uses exactly the same tables, services and controller.
A Game project profile names the engine primitives it uses and their JSON parameters:
| Profile field | Meaning |
|---|---|
ViewKey + ViewParametersJson |
Renderer primitive: first-person-raycast, text-template or duel-stage. |
TurnModelKey |
actions (every control is a turn) or council (Council role answers drive the game). |
MapGeneratorKey + MapParametersJson |
Grid map primitive (rooms-and-corridors, fixed-rooms-arena); empty for no map. |
AutoplayKey + AutoplayParametersJson |
AI control primitive (hunt-and-extract, action-cycle); empty for none. |
PlayerArchetypeKey |
Archetype of the directly controlled actor. |
RulesetTemplateKey |
Game key whose rows this game inherits while a table of its own is empty. |
Seven child tables hold the rules: stats (key, range, initial value), archetypes (role, glyph, behaviour, parameters; actors, enemies, rigs), actions (keyboard and gamepad labels, action primitive, parameters, AI-selectable flag), rules (trigger, primitive, parameters, enabled), levels (size, difficulty, parameters), texts (every player-visible line, caption and prompt) and aliases (action, axis, game and runtime-class aliases).
Rule triggers:
- Action games:
start,before-action,after-action,world-step,goalandstyle. - Advisory GameDirector subdirectors:
director.prediction. - Council-driven games:
council.progression(the progression primitive, for examplesingle-elimination-team-duel),council.lineup(which Council role answers seed the entrants) andstoryboard.initialize,storyboard.exchange,storyboard.exchange-resolved,storyboard.complete(one presentation frame per row).
Text templates use {token} and {token,align:format}; unknown tokens stay literal and {{ escapes a brace. Value
specifications in parameters may be a template string or an object with when/then/else, firstOf,
join + values, value, clean and max. Conditions support ==, !=, >=, <=, >, <, !, && and ||.
The council roles of a team configuration make every AI decision: a workflow step marked GameEngineInitializes
starts the game, LimitToActiveGameEntrants limits a round to the active pair, and the Context* step settings
bound the transcript each role sees. The engine only resolves the consequences of the answers.
The four system games are seeded from the embedded documents in src/LocalGPT/GameTemplates/Seeds/*.json by
GameProjectSeedService. A seeded game the user has edited is never overwritten. The Projects page edits the profile
primitives, their JSON parameters and the complete rule rows; the same data is available through the REST API:
GET api/games/catalog: every game project with its launcher data.GET api/games/primitives: the engine primitive keys by kind.GET api/games/{projectId}/rulesandPUT api/games/{projectId}/rules: the own rule rows of one game (saving requiresuserConfirmed).
Game Studio scene revisions in Chat (5.5.8)
The Game Studio revisions DevExpress list in the regular Chat game console is populated by IGameProjectService.ListPlayableRevisionsAsync from approved LocalGptProjectRevision business objects. It includes earlier completed revisions, not only the current project version. Play revision passes the selected project and exact revision IDs to LaunchRevisionAsync, then opens the ordinary shared Chat game screen. No example scene JSON is loaded into this workflow. Scene data comes from the selected revision's ProjectStructureJson.scene; an empty, unapproved, malformed or rejected scene cannot be played.
The same CouncilGameSessionService runs the session and obtains approval from CouncilGameDirectorService before each human/AI control. The GameSceneEngine then advances the authored world clock at its configured fixed tick rate; ASCII comes from the engine's scene preview and Pixel mode draws the very same scene, sprites, palette, parallax, actors and HUD using the existing Game Studio canvas renderer. One authored GameSceneActor may have playerControlled: true in the scene's business-object JSON: controls then move this actor through collision-checked world tiles while the camera follows. Other scenes keep free-camera navigation. The curator rejects more than one directly controlled actor; no game-specific character type is hardcoded. The director.prediction rule rows of engine-run games are excluded from this scene-driven path.
src/LocalGPT/GameTemplates/GodotSceneRuntime.cs.txt is not a C# application source file to compile into the LocalGPT server: it is an embedded C# script template for a separate Godot .NET project. GameGodotWorkspaceService reads the embedded resource when initializing a Godot worktree and writes its contents as src/LocalGptSceneRuntime.cs, referenced by scenes/Main.tscn. That generated .cs is compiled by Godot's C# project on the user's machine. LocalGPT's live Chat runtime instead compiles and executes GameSceneEngine.cs without requiring Godot assemblies. The sample in docs/examples/game-studio-parallax-scene.json is documentation only and never a runtime seed.