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 (its ENGINE_VERSION constant carries the exact pin). 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:

   • project_get_entity, project_get_component_definition, project_get_script: read one Project Graph resource by handle (there is no compact-packet tool; pull narrowly instead of dumping a full snapshot into context, and reach for project_get_graph_snapshot only for broad planning).
   • world_build_get_operation_catalog: the intent-level world-build 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 prefix.

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. For source syntax and language-view editing rules, use the generated Script source and language views.

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

The v1 engine ships a fixed set of built-in atomic ECS components; the current count, the canonical inventory, and the 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 alphabet is the generated Script Semantic Patch reference, with the effect and typed-state contracts from engine_get_script_effect_contract_catalog; that is the algebra you express edits in.
• Apply edits with project_apply_script_semantic_patch; it checks the intent-level operations against your latest read (pass the current irFingerprint) and rejects a stale or invalid patch with a diagnostic. Typecheck the result with script_typecheck after 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:

{
  "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.