Gessa Product Documentation (v1)

Gessa is an AI-native, cloud-authoritative, browser-native world engine. You describe what you want, the engine proposes a reviewable change to a shared world model, and you refine it in a workbench and enter it in a browser — no install, no client build.

This is the hand-authored product documentation (Tier 3) for engine version v1. It teaches and orients; it links down to the generated Tier-2 reference for every canonical table and never restates one. For the public source-of-truth model, see Versioning Policy.

New here? Go straight to the Quickstart.

Media placeholder: add a short product walkthrough clip showing Create, Build, Script Editor, Play, and MCP docs side by side.

What a Gessa world is

A world is a persistent, stateful environment — not merely a renderable scene. It has authoritative server-side state (entities, components, scripts, typed data) that survives reloads, admits multiple players, and runs under a server-driven runtime. A scene that draws on screen is not yet a world you can play; the engine treats "renders" and "playable" as distinct, separately-proven properties.

Two framings recur across every page and are load-bearing:

• The backend owns authority. The frontend is a non-authoritative projection of authoritative state. You never see "the world" directly; you see a rendered view of what the server holds. See Backend Authority.
• Edits flow through canonical actions. Every change — create a world, add an entity, attach a component, author behavior — is applied through the Action Catalog or semantic authoring, never through raw writes to the underlying model. See The Project Graph.

The four verbs

Gessa's creation loop is built on four load-bearing verbs. Every task-oriented page is anchored to one of them.

• Spawn — describe what you want in natural language; the AI proposes a reviewable change to the world (a scene-graph diff) rather than editing blindly. The canonical build actions behind Spawn are world.build.from_prompt world.build.from_prompt and world.build.from_spatial_asset world.build.from_spatial_asset.
• Build — open the workbench and edit the world directly: entities, ECS components, scripts, and the scene graph, through canonical project.* actions.
• Generate — produce assets (models, textures, audio) through the generation service and place them in the world.
• Play — run the world in an ephemeral preview session against the live Project Graph, then iterate. "Play" is where playability is demonstrated, not merely asserted.

How these docs are organized

Product documentation follows the four Diataxis modes. Pick the mode that matches what you are trying to do.

Tutorials (learning-oriented)

End-to-end lessons for a newcomer, taken step by step.

• Create a World — build a first spatial world: a camera, a light, a floor, and a couple of interactable props.
• Create a Playable Game — extend that world into a playable game with possession, input, a win/score loop, and a HUD, ending on the playability proof obligation.

How-to guides (task-oriented)

Recipes for a reader who knows the basics and has a specific goal.

• Use MCP Tools — drive Gessa from an MCP client.
• Edit Components — edit ECS components through canonical authoring, not raw graph writes.
• Write GessaScript — author behavior via Script Semantic Patch.
• Publish and Play — publish a world, then Play, reconnect, and reload.

Reference (information-oriented)

Thin orientation pages that point at the Tier-2 generated reference. They explain how to read a generated file and link to it; they never paste its tables.

• ECS Components → component-types.md
• Action Catalog → action-catalog.md
• MCP Tools → tool-reference.md
• Script Nodes → script-node-catalog.md, script-sdk.md
• Runtime Playability → the runtime modules and the v1 readiness registries

Explanation (understanding-oriented)

Conceptual pages on why the contracts are shaped the way they are.

• Backend Authority — the frontend as a non-authoritative projection; one mutation authority.
• The Project Graph — the authoritative world and resource model.
• Script IR and GessaScript — Script IR as canonical behavior; source and visual graph as projections.
• Playability Proofs — why proof gates exist and what "playable" formally requires.
• Versioning Policy — how public docs, generated references, and proof receipts stay pinned to explicit versions.

Source of truth

These hand-authored pages are downstream of code. Canonical contracts live in the engine repository and are projected into machine-owned Tier-2 generated reference under docs/spec/generated/ and docs/creator/mcp/. Generated files carry the header GENERATED FILE: do not edit by hand., name their Tier-1 sources, and pin catalog versions and sha256 hashes. When you need a canonical fact — the built-in ECS component list, the Action Catalog verbs, the MCP tool inventory, the semantic-patch operations — read it there, not here:

• docs/spec/generated/component-types.md Canonical reference: docs/spec/generated/component-types.md — the 24 built-in ECS component types.
• docs/spec/generated/action-catalog.md Canonical reference: docs/spec/generated/action-catalog.md — the 64 canonical action verbs and their surface mappings.
• docs/creator/mcp/tool-reference.md Canonical reference: docs/creator/mcp/tool-reference.md — the MCP tool inventory.
• docs/spec/generated/script-semantic-patch.md Canonical reference: docs/spec/generated/script-semantic-patch.md — the Script Semantic Patch operations.
• docs/spec/generated/world-build-contract.md Canonical reference: docs/spec/generated/world-build-contract.md — the World Build Contract and its acceptance policy.

The readiness authority — which capabilities are accepted versus modeled — is the set of registries under docs/cycles/v1-engine-readiness-loop/ (FEATURE_LEDGER.json, PROOF_REGISTRY.json, GUARDRAIL_REGISTRY.json).

Pinned to engine v1

This docs version pins the v1 engine contract snapshot. The catalog versions and sha256 hashes a page documents come from packages/engine-version; the generated public export also records an engine version, a generation timestamp, and page hashes. Per-version URLs (docs/product/v1/...) stay stable so a citation keeps its meaning when a future major opens. Pinned content is not silently reinterpreted — contract-changing behavior opens through versioned engine changes and regenerated references. See Versioning Policy.

AI agents

If you are an AI agent (Codex, Claude Code, an MCP client, or an internal Gessa agent), use the dedicated AI-context axis instead of these human pages: Gessa AI Context (v1). It is concise and operational — what to call, what not to call, how to discover ECS components, and what proof is required before claiming a world is playable.

Status

This landing page is part of the v1 Gessa docs contract system. Its structure, links, and version pin are generated from the engine repo. When a page describes a capability, it describes the contract and the canonical flow; runtime status is backed by proof receipts and generated references, not by prose alone.