---
title: "Gessa Product Documentation (v1)"
description: "Gessa documentation for game creation, assets, multiplayer, engine concepts and MCP tools, with versioned tutorials and reference material."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/
---

# Gessa Product Documentation (v1)

{% version engineVersion="v1.0.232" coordinate="docs-public.v0" /%}

Gessa is a free browser platform to make and play games with friends and AI. Create models, textures, images and audio, edit your game in the workbench, and publish it for others to play. These docs explain the engine, authoring tools and versioned contracts behind that workflow.

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](explanation/versioning-policy.md).

New here? Go straight to the [Quickstart](start/quickstart.md).

{% proof class="docs.public_scaffold" registry="docs/cycles/v1-engine-readiness-loop/PROOF_REGISTRY.json" status="pending" %}
This public docs scaffold is generated from the engine repo and pinned to an export manifest with page hashes. Capability pages link to generated references and proof language where claims depend on runtime behavior.
{% /proof %}

For a practical starting point, follow the [game creation guide](https://gessa.ai/guides/make-a-game-with-ai/) or [multiplayer guide](https://gessa.ai/guides/make-a-multiplayer-game-with-ai/). To connect an external agent, use the [MCP quickstart](../../creator/mcp/quickstart.md).

## What a Gessa world is

A **world** brings authored entities, components, scripts and assets together with a runtime that executes game behavior. Saved project resources and live session state have different lifecycles: saving a project does not by itself guarantee that every runtime value survives a reload. Multiplayer authority, persistence and rejoin behavior are explained in the [Netcode Model](explanation/netcode-model.md). Test the game rules and player experience as well as the rendered scene.

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](explanation/backend-authority.md).
- **Edits flow through canonical actions.** Every change (create a world, add an entity, attach a component, author behavior) is applied through the [Action Catalog](reference/action-catalog.md) or semantic authoring, never through raw writes to the underlying model. See [The Project Graph](explanation/project-graph.md).

## 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 a starting world in natural language or build from a spatial asset, then inspect and refine the result. The Action Catalog lists the world-build workflow entries {% action name="world.build.from_prompt" /%} `world.build.from_prompt` and {% action name="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, images, 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.

{% warning severity="caution" title="Capability claims require evidence" %}
These pages describe the v1 contract and canonical authoring flow. Runtime-sensitive claims point to generated references, proof receipts, or readiness ledgers; prose alone is not evidence that a capability works in a live session.
{% /warning %}

## How these docs are organized

Product documentation follows the four [Diataxis](https://diataxis.fr) modes. Pick the mode that matches what you are trying to do.

### Journeys (task spine, start here)

The build-and-ship path in order, each routing to the page that owns each step.

- [Get Started](journeys/get-started.md): from nothing to a first world open in Play.
- [Build a World](journeys/build-a-world.md): author the scene, entities, components, and assets.
- [Add Behavior](journeys/add-behavior.md): give the world logic through Script Semantic Patch.
- [Make It Multiplayer](journeys/make-it-multiplayer.md): replicate it into server-authoritative rooms and queues.
- [Publish](journeys/publish.md): promote it to a deployment and reach a playability proof.

### Tutorials (learning-oriented)

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

- [Create a World](tutorials/create-a-world.md): build a first spatial world: a camera, a light, a floor, and a couple of interactable props.
- [Create a Playable Game](tutorials/create-a-playable-game.md): 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](how-to/use-mcp-tools.md): drive Gessa from an MCP client.
- [Edit Components](how-to/edit-components.md): edit ECS components through canonical authoring, not raw graph writes.
- [Write GessaScript](how-to/write-gessascript.md): author behavior via Script Semantic Patch.
- [Publish and Play](how-to/publish-and-play.md): 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](reference/ecs-components.md) → [`component-types.md`](../../spec/generated/component-types.md)
- [Action Catalog](reference/action-catalog.md) → [`action-catalog.md`](../../spec/generated/action-catalog.md)
- [MCP Tools](reference/mcp-tools.md) → [`tool-reference.md`](../../creator/mcp/tool-reference.md)
- [Script Nodes](reference/script-nodes.md) → [`script-node-catalog.md`](../../spec/generated/script-node-catalog.md), [`script-sdk.md`](../../spec/generated/script-sdk.md)
- [Runtime Playability](reference/runtime-playability.md) → the runtime modules and the [v1 readiness registries](../../cycles/v1-engine-readiness-loop/)
- [Physics Contract](reference/physics-contract.md) → [`component-types.md`](../../spec/generated/component-types.md)
- [Netcode Contract](reference/netcode-contract.md) → the runtime netcode modules and the contract fixture-hash test

### Explanation (understanding-oriented)

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

- [Backend Authority](explanation/backend-authority.md): the frontend as a non-authoritative projection; one mutation authority.
- [The Project Graph](explanation/project-graph.md): the authoritative world and resource model.
- [Script IR and GessaScript](explanation/script-ir-and-gessascript.md): Script IR as canonical behavior; source and visual graph as projections.
- [Playability Proofs](explanation/playability-proofs.md): why proof gates exist and what "playable" formally requires.
- [Versioning Policy](explanation/versioning-policy.md): how public docs, generated references, and proof receipts stay pinned to explicit versions.
- [Physics Simulation](explanation/physics-simulation.md) - physics as an integration contract over Rapier 3D plus the shared character controller, and which character motor is actually live.
- [Netcode Model](explanation/netcode-model.md): the room clock, authority, prediction admission, replication, load ladders, durability, and rejoin.

### Compare (evaluation-oriented)

Comparison pages held to a machine-checked honesty contract: every Gessa cell binds to a live engine surface and every competitor cell is dated and attributed. See [how to read them](compare/index.md).

- [Compare Gessa to Unity and Unreal](compare/index.md): the honesty contract and the five comparison axes.
- [Browser-native 3D engine, no install](compare/browser-native-engine.md)
- [Server-authoritative multiplayer without a netcode plugin](compare/server-authoritative-multiplayer.md)
- [Agent-native authoring over MCP](compare/agent-native-authoring.md)
- [Deterministic, replay-verified physics](compare/deterministic-physics.md)
- [Instant multiplayer worlds vs open-world streaming](compare/instant-worlds-vs-open-world-streaming.md)

## 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/`](../../spec/generated/) and [`docs/creator/mcp/`](../../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`](../../spec/generated/component-types.md) {% generated-reference file="docs/spec/generated/component-types.md" /%}: the built-in ECS component types.
- [`docs/spec/generated/action-catalog.md`](../../spec/generated/action-catalog.md) {% generated-reference file="docs/spec/generated/action-catalog.md" /%}: the canonical action verbs and their surface mappings.
- [`docs/creator/mcp/tool-reference.md`](../../creator/mcp/tool-reference.md) {% generated-reference file="docs/creator/mcp/tool-reference.md" /%}: the MCP tool inventory.
- [`docs/spec/generated/script-semantic-patch.md`](../../spec/generated/script-semantic-patch.md) {% generated-reference file="docs/spec/generated/script-semantic-patch.md" /%}: the Script Semantic Patch operations.
- [`docs/spec/generated/world-build-contract.md`](../../spec/generated/world-build-contract.md) {% generated-reference file="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/`](../../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](explanation/versioning-policy.md).

## 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)](../../ai-context/v1/README.md). 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.

- [Glossary](glossary.md): every load-bearing term in one sentence, linked to the page that owns it.
- [Trust Center](trust/index.md): security, data handling, availability, and what is not offered, each page bound to a generated or checked source.