Gessa AI Context (Full, v1)

This is the expanded, single-file orientation an AI agent can load wholesale before building in Gessa. It pins engine version v1. It is concise and operational — it tells you what to call, what not to call, and what proof you owe before claiming a result. For canonical tables, follow the links into the generated reference; this page never restates them.

If you only read one thing: build through canonical actions and MCP tools, author behavior through Script Semantic Patch, and never claim a world is playable without proof receipts.

What Gessa is

Gessa builds worlds — persistent, stateful spatial-and-operational environments, not throwaway renderable scenes. The product surfaces are Spawn (describe what you want; the AI proposes a reviewable scene-graph diff), Build (edit the world directly), Play (run it in an ephemeral preview session), and Generate (produce assets). The frontend is a non-authoritative projection over backend authority: backend acceptance and proof receipts are the truth, not local UI state.

The engine has never launched. Everything here is v1, aligned to packages/engine-version (ENGINE_VERSION currently reads v1.0.106). The v1 readiness ledger has zero accepted rows, so this page describes the canonical flow whose end-to-end runnable status tracks that ledger — it does not promise the flow runs unattended today.

The three-tier source-of-truth model

1. Tier 1 — Code / registry (truth). Canonical contracts live in code:
   • packages/ecs — ECS components.
   • packages/action-catalog — verbs.
   • packages/capability-catalog + runtime packs — capabilities.
   • server/src/modules/mcp/server.ts — MCP tools.
   • packages/script-semantic-patch — semantic authoring.
   • packages/script-nodes + packages/script-codegen — Script IR.
   • packages/script-sdk — the script SDK.
   • packages/world-build-contract — the World Build Contract.
   • packages/platform-catalog — the Platform Catalog.
   • packages/engine-version — the version manifest.
2. Tier 2 — Generated reference (derived projection). Machine-citeable, header-marked GENERATED FILE: do not edit by hand., produced by scripts/gen-*-docs.ts via npm run gen-docs and verified by npm run gen-docs:check. It lives under docs/spec/generated/ and docs/creator/mcp/, and carries catalog versions and sha256 hashes. Cite this for any contract fact.
3. Tier 3 — Hand-authored prose (this folder + product docs). Orientation and instruction that links to Tier 2 and never duplicates it.

When you need a contract fact, prefer the live tool (engine_list_*, engine_get_*) or the generated reference over your own memory. Nothing edits a higher tier from a lower one.

How to build a world (the canonical path)

1. Discover, don't guess. Start with read-only discovery to learn the real contract surface:

   • agent_get_project_context — compact handles/selectors for the current Project Graph (use this instead of dumping a full snapshot into context).
   • agent_get_semantic_operation_catalog — the operation algebra that lowers into Gessa services.
   • engine_list_component_types / engine_get_component_schema — the ECS contract.
   • engine_list_script_nodes / engine_list_script_patterns — the script surface.
   • engine_get_engine_spec / engine_get_capability_graph — the engine and capability surface.

   See the MCP Tool Reference for the full list; it is grouped by surface (agent, asset, engine, generation, model, project, qa, runtime, script, simulation, spatial, warehouse, workspace, world).

2. Prefer prompt-to-world build for whole worlds. world.build.from_prompt is the canonical action for prompt-to-world execution, and world.build.from_spatial_asset turns imported or generated spatial assets into executable worlds. MCP exposes world_build_compile_semantic_operations, world_build_from_spatial_asset, and world_build_get_operation_catalog. See the World Build Contract.

3. Make targeted edits through canonical actions. Create and modify Project Graph resources via the cataloged verbs — for example project.world.create, project.entity.create, and project.entity.component.set — surfaced as MCP project_* tools. See the Action Catalog.

4. Author behavior through Script Semantic Patch. Apply project.script.patch.apply (MCP project_apply_script_semantic_patch). The backend compiler projects semantic operations into canonical Script IR and persists through the normal script update path. project_create_script only yields an empty IR shell; behavior comes from the patch, never from hand-written IR. See Script Semantic Patch.

5. Generate assets through the generation actions. generation.job.quote then generation.job.create (MCP generation_quote_job, generation_create_job); poll generation_get_job and cancel with generation_cancel_job. Import or generate spatial captures through the spatial_* tools, then feed them to world_build_from_spatial_asset.

6. Prove it. Capture observer/renderer frames and run the simulation before claiming the world is done (see The proof requirement).

Discovering ECS components

There are 24 built-in atomic ECS components at v1; the canonical inventory and field contract live in the generated Component Types reference (catalog contract hash and field-contract version are pinned there). Representative built-ins include TransformComponent, RigidBodyComponent, ColliderComponent, CameraComponent, RenderableComponent, LightComponent, and ScriptComponent.

Two rules keep you grounded:

• Atomic only. Under ADR 0020, gameplay patterns such as health, damage, spawn pools, collectors, and motion helpers are script patterns, not ECS atomics. If a name is not in the built-in inventory, it is not a built-in component — treat it as a script pattern or project-defined data, or it does not exist.
• Read the schema before you set it. Use engine_get_component_schema (or the generated reference) to learn a component's fields before project.entity.component.set. Do not invent fields.

Authoring behavior semantically

Script behavior is canonical Script IR, but IR is generated output, not a hand-authoring surface. You author by applying semantic operations that the backend compiler lowers into IR:

• The semantic operation catalog (agent_get_semantic_operation_catalog, or the generated Script Semantic Patch) is the algebra you express edits in.
• Apply edits with project_apply_script_semantic_patch. Where a preflight is offered (agent_preflight_semantic_operations), run it before applying.
• The Script Node Catalog and Script SDK Surface document the IR nodes and the TypeScript ScriptContext your script runs against — read them to understand the target, not to write IR by hand.

A semantic patch is a small, intent-level request — name the operation and its parameters, not raw IR:

<!-- example:conceptual -->

{
  "operations": [
    { "op": "<operation-id from the semantic patch catalog>", "params": { } }
  ]
}

The real operation ids and parameters come from the catalog; the shape above is illustrative only.

Do / Don't

Do

• Discover the live contract with read-only tools before mutating.
• Build worlds with world.build.from_prompt / world.build.from_spatial_asset.
• Make graph edits through cataloged project.* actions.
• Author behavior through Script Semantic Patch.
• Treat backend acceptance and proof receipts as the source of truth.
• Cite the generated reference (Tier 2) for any contract claim.

Don't

• Don't hand-write full Script IR. project_create_script only yields an empty IR shell; behavior must come from Script Semantic Patch.
• Don't invent component, action, or MCP tool names. If it isn't in the generated reference or returned by a discovery tool, it doesn't exist at v1.
• Don't write raw shader/pass fields (shaderSource, fragmentShader, wgsl, glsl, customPassSource, …). Renderer/material choices must reference cataloged capability ids.
• Don't claim "playable" from a render alone — renderability is not playability.
• Don't forward your MCP bearer token to any downstream tool or service.

The proof requirement

Renderability is not playability. Per the World Build Contract acceptance policy:

• Playable spatial-world acceptance requires a collision proxy, a nav/query proxy, a semantic anchor, and playability.accepted receipts. Renderability alone is not playable proof.
• Accepted build proof additionally requires semantic-contract proof, Project Graph validation, visible unsupported requirements, passing QA receipts, and a timeline receipt.
• Generated assets may iterate through placeholders, but accepted final proof only permits terminal_success, substituted, or degraded asset receipts.
• Missing proof is not_run, not pass. Never synthesize a receipt.

Proof tooling you can call: qa_capture_observer_frame, qa_capture_renderer_viewport, and simulation_run. If a capture is degraded, report it as degraded — do not fabricate a passing receipt. The authoritative readiness registries live under docs/cycles/v1-engine-readiness-loop/ (FEATURE_LEDGER.json, PROOF_REGISTRY.json, GUARDRAIL_REGISTRY.json, MUTATION_AUTHORITY_REGISTRY.json, VERSION_REGISTRY.json).

Handling renderer and runtime failures

Failures are expected mid-build; the rule is to repair through a canonical surface, never to paper over backend authority.

• Degraded or failed capture. qa_capture_* may return a degraded frame. Report it as degraded, re-run, or escalate — do not synthesize a passing receipt.
• Accepted locally but not by the backend. The frontend is a non-authoritative projection. Confirm acceptance and receipts from the backend before reporting success.
• Raw-graph or raw-shader rejection. Route the change through the matching project.* action or a cataloged renderer/material capability id.
• Unknown name rejected. Re-discover with engine_list_component_types, engine_get_component_schema, or the MCP Tool Reference and use only names that appear there.

The Common failures and repairs runbook expands each class with its canonical repair.

Versioning

Docs version == engine version; today there is exactly v1, aligned to packages/engine-version. A page pins the contract snapshot it documents (catalog versions + sha256 hashes), Stripe-style. The engine has never launched; everything is version 1. Never write second-attempt version spellings.

Where to go next

• AI Context README — folder index and the five ground rules.
• Codex guide and Claude Code guide — per-client operating loops.
• MCP tool use — safe MCP usage and token rules.
• Common failures and repairs — the runbook.
• Documentation Contract Architecture — the full model.

Status: stable — single-file v1 orientation, pinned to engine v1.