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

The set of built-in ECS components in v1 is fixed by code. 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

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_add_component (add or replace a complete component; project_remove_component to 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 (and project.entity.component.delete to remove). This is exposed on the ui, mcp, ai, and sdk surfaces: 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.

The authoring recipe

Why project_apply_transaction is an escape hatch, not the path

There is a privileged low-level tool, project_apply_transaction (action project.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_add_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.