Quickstart
v1.0.111 · docs-public.v0The shortest real path from an empty workspace to a world (a persistent, stateful environment) you can enter. This page is the fast index; the deeper, narrated walkthroughs are the tutorials.
Every step here grounds in real surfaces: the Action Catalog verbs, the MCP tool reference, the built-in ECS components, and Script Semantic Patch. You can perform each step through the workbench UI or through an MCP client — both funnel into the same canonical actions, because the backend owns authority and the frontend is a projection over it.
This page is verified against the v1 docs export and generated references. Runtime-sensitive claims still require their own receipts; seeing a scene render is not the same as proving playability.
Media placeholder: add a 60-second capture that starts from an empty project, creates a world, adds a camera/light/floor, opens Play, and shows the docs reference links used along the way.
Before you start
You need a workspace and a project. A project (called a game in the control plane) is the container; a world lives inside it as persistent state. If you are driving from an MCP client, point it at the Gessa MCP server first — see the MCP quickstart and security guide.
The recipe
1. Discover the contract before you author
Never invent component fields or node ids. Ask the engine what exists first.
- List the built-in ECS component types and their field contracts with
engine_list_component_typesengine_list_component_types. - Fetch a single component's schema with
engine_get_component_schemaengine_get_component_schemabefore you set its fields.
The canonical inventory is the generated ECS component reference — 24 built-in components such as TransformComponent TransformComponent, CameraComponent CameraComponent, LightComponent LightComponent, RenderableComponent RenderableComponent, and ColliderComponent ColliderComponent. The full MCP surface is the tool reference.
2. Create the workspace and project
Use the control-plane actions workspace.create workspace.create and game.create game.create (MCP: project_create_game project_create_game). Note the returned project id — every subsequent call carries it as game_id.
3. Create a world
Create a world inside the project with project.world.create project.world.create (MCP: project_create_world project_create_world). Give it a stable key such as world.main; later calls can reference the world by key instead of by uuid.
4. Add the minimum to see something
A world that draws needs a viewpoint, light, and a surface. Create entities with project.entity.create project.entity.create (MCP: project_create_entity project_create_entity), attaching components by their default keys at creation:
- A camera entity:
component.transformpluscomponent.camera. The highest-priority activeCameraComponentis what Play looks through. - A light entity:
component.transformpluscomponent.light. - A floor entity:
component.transform,component.renderable, andcomponent.colliderso things can stand on it.
To change a component on an existing entity afterwards, use project.entity.component.set project.entity.component.set — not a raw write to the model.
5. Attach behavior with Script Semantic Patch
Author behavior through semantic operations, never raw graph node ids. Create a script shell with project.script.create project.script.create (MCP: project_create_script project_create_script), then apply intent with project.script.patch.apply project.script.patch.apply (MCP: project_apply_script_semantic_patch project_apply_script_semantic_patch).
The MCP path accepts the mcp_safe operation pack — for example addTickHandler, addTriggerHandler, attachComponentWithValidatedDefaults, and incrementNumericState. The compiler lowers these to canonical Script IR. See the semantic-patch reference.
6. (Optional) Generate assets
To produce a model, texture, or audio asset, quote and create a generation job with generation.job.quote generation.job.quote and generation.job.create generation.job.create (MCP: generation_quote_job generation_quote_job, generation_create_job generation_create_job). Generation is asynchronous; place the finished asset on a RenderableComponent once it lands.
7. Open Play
Open Play in the workbench to run the world in an ephemeral preview session against the live Project Graph. Play is a workbench surface, not an MCP tool — there is no "play" verb in the MCP inventory. This is where playability is demonstrated, not asserted.
A note on raw mutations
Every step above uses a canonical action or a semantic operation. Do not bypass them with raw Project Graph writes or hand-built Script IR node ids — those skip authority and validation. Raw project_create_entity-style writes exist for privileged/internal paths; normal authoring uses the actions and semantic patches named here. See The Project Graph.
What "running" does and does not mean
Opening Play and seeing the scene draw proves renderability, not playability. A Play proof in v1 additionally requires camera, spawn, and possession demonstrated under a live runtime session. Treat "I can see it" and "it is playable" as different claims with different evidence.
Next steps
- Build the full first world step by step: Tutorial: Create a World.
- Reach a real Play proof: Tutorial: Create a Playable Game.
- Understand why proof gates exist: Explanation: Playability Proofs.
- Drive everything from an agent: How-To: Use MCP Tools.