How-To: Edit Components
Add and edit ECS components on entities the right way — through canonical authoring actions, so backend authority stays the single source of truth. ECS components are the engine's atomic contracts (under ADR 0020): they replicate, they are validated against a versioned schema, and they are consumed by the runtime and renderer. You edit a component by invoking an action, never by hand-writing the Project Graph.
This page describes the canonical authoring flow for v1. The engine is pre-launch and its readiness rows are unaccepted, so treat this as the intended contract surface rather than a guarantee of a finished end-to-end run; status tracks the v1 readiness ledger.
The component set is generated and fixed
There are 24 built-in ECS components in v1. The inventory — categories, field contracts, contract versions, packs, and runtime/renderer consumers — is Tier-2 generated from packages/ecs/src/index.ts (COMPONENT_TYPE_DEFINITIONS) by scripts/gen-component-docs.ts. Read the field tables there; never restate them:
docs/spec/generated/component-types.md— the canonical inventory.docs/spec/COMPONENT_TYPE_DEFINITIONS.md— the companion definitions surface.- Reference: ECS Components — the thin pointer page.
Built-in components are atomic engine contracts. Gameplay patterns — health, damage, spawn pools, inventories — are script patterns, not ECS atomics; you author those with GessaScript, not by inventing a component. A few representative built-ins you will edit often: TransformComponent (placement), RenderableComponent (visual presence), ColliderComponent and RigidBodyComponent (physics), and CameraComponent (viewpoint). Confirm the exact field contract for any component in the generated inventory before authoring it.
The rule: no raw graph writes
Edit components only through the canonical authoring path — the workbench Build surface, the documented Action Catalog verb, or the semantic MCP tool. Raw Project Graph writes bypass schema validation, replication, and the single mutation-authority model, creating a second unvalidated source of truth. They are forbidden.
The canonical authoring path has one entry per surface, all lowering to the same action:
- In the workbench: the Build surface and the component inspector. The editor validates field edits against the canonical schema before they are applied.
- From an agent or MCP client: the semantic tool
project_set_component(andproject_remove_componentto drop one). See How-To: Use MCP Tools. - The underlying verb: all of the above lower to the Action Catalog action
project.entity.component.set(andproject.entity.component.deleteto remove). This is exposed on theui,mcp,ai, andsdksurfaces — one verb, every caller. See the Action Catalog.
Because there is exactly one mutation authority, "editing a component" means "invoking project.entity.component.set" regardless of who you are. See Explanation: Backend Authority.
Discover the schema first
A component is a typed contract, so author it against its schema rather than guessing field names. For agents, the discovery tool is engine_get_component_schema, which returns one built-in component's field contract plus a UI control-hint projection.
Treat fieldContracts as authoritative; the control-hint schema is only a UI projection. Call engine_list_component_types to see what exists, engine_get_component_schema to read one component's contract, then project_set_component to author the value. Do not invent component names — only the 24 built-ins are real ECS atomics; everything else is a script pattern or project-defined metadata.
The authoring recipe
- Select the entity you want to edit (in the workbench) or resolve its handle (via
agent_get_project_context). - Discover the component contract. Read its field table in
component-types.md, or callengine_get_component_schemafor the live contract and control hints. - Set fields within the contract. In the workbench, edit the component in the inspector; the editor validates against the canonical schema. From an agent, call
project_set_componentwith values that satisfy the field contract. - Let the authority validate. The action
project.entity.component.setvalidates, applies, and replicates. An invalid value is rejected by the authority, not silently accepted. - Confirm the change persisted. Re-read the entity (
project_get_entity) or the graph snapshot; what you see is a projection of authoritative state, so trust the receipt rather than your local copy.
Why project_apply_transaction is an escape hatch, not the path
There is a privileged low-level tool, project_apply_transaction (action project.graph.transaction.apply), that applies raw Project Graph transactions. It requires a privileged_authoring_reason precisely so that agents cannot accidentally choose it for normal authoring. It exists for import and test-only paths. For component editing it is the wrong tool: it skips the typed component authoring contract that project_set_component enforces. If a semantic authoring tool exists for your edit — and for components it does — use it.
Related
- Reference: ECS Components — the generated field tables.
- How-To: Use MCP Tools — discovery-first authoring from an agent.
- Explanation: The Project Graph — why direct writes are forbidden.
- Explanation: Backend Authority — the one-mutation-authority model these actions enforce.
Status: this page documents the canonical component-authoring flow for v1. End-to-end runnable status tracks the v1 readiness ledger; the engine is pre-launch.