Gessa Context for Codex

Operational guide for OpenAI Codex and CLI-style agents building in Gessa at engine version v1. Keep it tight: discover, build through canonical surfaces, prove before you claim done. For canonical tables, follow the links into the generated reference, do not rely on memory.

Read llms-full.md once for the full model. This page is the short operational checklist.

Operating loop

1. Discover first (read-only). Before any mutation, learn the live contract:
   • 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 use project_get_graph_snapshot only for broad planning).
   • world_build_get_operation_catalog: the intent-level world-build operations that lower into services.
   • engine_list_component_types, engine_get_component_schema: the ECS contract; read a component's fields before you set them.
   • engine_list_script_nodes, engine_list_script_patterns: the script surface.
   • The full tool list is in the MCP Tool Reference.
2. Prefer MCP + canonical actions. Build whole worlds with world.build.from_prompt / world.build.from_spatial_asset. Make targeted edits through cataloged project.* actions, for example project.world.create, project.entity.create, project.entity.component.set (see the Action Catalog). Generate assets with generation_quote_job then generation_create_job, polling generation_get_job.
3. Never hand-write full Script IR. Author behavior with Script Semantic Patch (project_apply_script_semantic_patch). project_create_script only yields an empty IR shell; the semantic compiler lowers operations into canonical IR. See Script Semantic Patch.
4. Require proof before claiming done. Renderability is not playability. Use qa_capture_observer_frame, qa_capture_renderer_viewport, and simulation_run. Accepting a playable world needs a collision proxy, a nav/query proxy, a semantic anchor, and playability.accepted receipts (see the World Build Contract). Missing proof is not_run, not pass.

Hard rules

• Do not invent names. Components, actions, and MCP tools that are not in the generated reference or returned by a discovery tool do not exist at v1. The built-in ECS components are enumerated in the generated component reference; gameplay concepts such as health or damage are script patterns, not components.
• Do not mutate the raw Project Graph in normal paths. project_apply_transaction is a low-level escape hatch, not the authoring path.
• Do not write raw shader/pass fields. Reference cataloged renderer/material capability ids only; never send shaderSource, fragmentShader, wgsl, glsl, or customPassSource.
• Do not forward your MCP bearer token to any downstream tool or service.
• Do not synthesize proof receipts. If a capture is degraded, report it as degraded; missing proof is not_run, not pass.

When you are unsure

Ask the engine, not your memory. engine_get_engine_spec, engine_get_component_schema, and engine_get_script_node return the live v1 contract; the MCP Tool Reference (Tier 2) carries each tool's canonical input schema. Cite the generated reference for any fact you state, and prefer a discovery call over a guess.

See also: Claude Code guide, MCP tool use, Common failures and repairs.

Status: stable, v1 Codex operating guide, pinned to engine v1.