Quickstart: your first world in 15 minutes

engine v1.0.232

Last verified 2026-09-03 against engine v1.0.232.

The shortest real path from an empty workspace to a world (a persistent, stateful environment) you can open in Play. Every step names the canonical action the workbench runs and the MCP tool an agent calls to run the same action, then states exactly what you should see before you move on. If a term is unfamiliar, the Glossary defines it in one sentence; when you want the same path narrated in depth, follow Tutorial: Create a World.

Two framings carry through every step:

The backend owns the truth and the frontend is a projection of it, so the workbench and an MCP client funnel into the same canonical actions. See Explanation: Backend Authority.
You ask the engine what exists before you name a field or a node; you never invent one. See The Project Graph.

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 rather than the workbench, point it at the Gessa MCP server first, following the MCP quickstart and security guide.

Recipe · From an empty workspace, create a world with a camera, a light, and a floor, attach behavior, and open it in Play

both

1. Discover the component contract

Ask the engine what exists before you set a field. List the built-in ECS component types with MCP toolengine_list_component_typesName, input schema and auth scope in the tool reference engine_list_component_types, then read one schema with MCP toolengine_get_component_schemaName, input schema and auth scope in the tool reference engine_get_component_schema. The canonical inventory these tools project is the generated ECS component reference.

You should see: the built-in component types listed back, among them componentTransformComponent TransformComponent, componentCameraComponent CameraComponent, componentLightComponent LightComponent, componentRenderableComponent RenderableComponent, and componentColliderComponent ColliderComponent, and the field contract of the one schema you fetched.

2. Create the workspace and project

Create the workspace with actionworkspace.create workspace.create, then the project with actiongame.create game.create (MCP: MCP toolproject_create_gameName, input schema and auth scope in the tool reference project_create_game).

You should see: a project id returned. Every later call in this quickstart carries it as game_id; note it now.

3. Create a world

Create a world inside the project with actionproject.world.create project.world.create (MCP: MCP toolproject_create_worldName, input schema and auth scope in the tool reference project_create_world). Give it a stable key such as main so later calls can reference the world by key instead of by uuid.

You should see: a new, empty world under your project, addressable by its key. Nothing draws yet because the world has no entities.

4. Add a camera

A world that draws needs a viewpoint. Create an entity with actionproject.entity.create project.entity.create (MCP: MCP toolproject_create_entityName, input schema and auth scope in the tool reference project_create_entity), attaching component.transform and component.camera at creation. The highest-priority active componentCameraComponent CameraComponent is what Play looks through.

You should see: a camera entity in the world outliner. The scene is still dark, but Play now has something to look through.

5. Add a light

Create a second entity with actionproject.entity.create project.entity.create, attaching component.transform and component.light.

You should see: the world is now lit, so whatever you place next will be visible rather than black.

6. Add a floor

Create a third entity with actionproject.entity.create project.entity.create, attaching component.transform, component.renderable, and component.collider. The floor is solid because of its componentColliderComponent ColliderComponent, not because it is drawn; rendering and collision are separate contracts. To change any component on an existing entity afterwards, use actionproject.entity.component.set project.entity.component.set, never a raw write to the model.

You should see: a lit surface in the viewport that draws and that something could rest on. You now have the minimum world that renders.

7. Attach behavior with Script Semantic Patch

Author behavior through typed, intent-level operations, never raw graph node ids. Create a script shell with actionproject.script.create project.script.create (MCP: MCP toolproject_create_scriptName, input schema and auth scope in the tool reference project_create_script) and attach it to an entity, then apply your intent with actionproject.script.patch.apply project.script.patch.apply (MCP: MCP toolproject_apply_script_semantic_patchName, input schema and auth scope in the tool reference 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 into canonical Script IR; the generated source and the visual graph re-project from it. Read the generated Script Semantic Patch reference for the operation surface.

You should see: a script attached to the entity, with its source and node graph re-projected from the IR you never hand-wrote.

8. Generate an asset (optional)

To populate the world with a model, texture, or audio clip you did not build by hand, quote and create a generation job with actiongeneration.job.quote generation.job.quote and actiongeneration.job.create generation.job.create (MCP: MCP toolgeneration_quote_jobName, input schema and auth scope in the tool reference generation_quote_job, MCP toolgeneration_create_jobName, input schema and auth scope in the tool reference generation_create_job). Generation is asynchronous.

You should see: a job accepted and running. When the asset lands, reference it from an entity's componentRenderableComponent RenderableComponent.

9. Open Play

Open Play in the workbench to run the world in a live session against authoritative state. Play is a workbench surface, not an MCP verb; there is no play tool in the MCP inventory.

You should see: the scene draw through your camera. That proves the world renders. It does not yet prove the world is playable.

Do not mutate the model directly

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 session, as Explanation: Playability Proofs makes precise. The engine is pre-launch: every row of the v1 readiness ledger is currently unaccepted, so treat this page as the intended contract, not a guarantee that a given world runs end to end today.

Next steps

Build the full first world step by step: Tutorial: Create a World.
Reach a real Play proof: Tutorial: Create a Playable Game.
Follow the reader spine in order from here: Journey: Get Started.
Drive everything from an agent: How-To: Use MCP Tools.