Reference: ECS Components

The ECS component catalog is the canonical inventory of Gessa's built-in entity component types for engine v1. This page is a thin pointer: it tells you where the catalog lives, how to read it, what contract it enforces, and how it is version-pinned. It does not restate the catalog — copying a generated table into prose would create a second, un-versioned source of truth that silently rots.

Media placeholder: add a short capture showing a component card in the Inspector next to the generated field contract for the same component.

Canonical source

The catalog is a Tier-2 generated artifact. Read it directly; do not hand-edit it.

• docs/spec/generated/component-types.md — the generated inventory and per-component field contracts.
• docs/spec/COMPONENT_TYPE_DEFINITIONS.md — the companion definitions surface.

The Tier-1 source of truth is code: COMPONENT_TYPE_DEFINITIONS and ComponentSchema in packages/ecs/src/index.ts. The generated reference is produced by the scripts/gen-component-docs.ts generator (run via npm run gen-docs) and verified by npm run gen-docs:check, which fails the build if the committed file drifts from the code. See Versioning Policy for the public source-of-truth model.

What the file contains

The generated file opens with catalog-level counts and hashes, then an Inventory table, then one detail section per component.

• Inventory table. One row per built-in component. Columns: Component (the type name), Category, Class, Palette visibility, Palette notes, Default key, Contract version, Packs (the capability packs that own it), Runtime systems (the runtime systems that consume it), Runtime consumer / Renderer consumer (whether the component is consumed, projected, internal, or not_applicable on each side), and Replication (the replication policy, e.g. public/medium or owner/high/reliable).
• Per-component sections. Each component has its own section with the same metadata plus its Canonical Field Contract — the exact field list, types, and the field contract hash. This is where you confirm the precise shape a component accepts.
• Lifecycle sections. Removed Component Contracts records contracts that were retired and their replacement and migration class; Recently Stripped Pattern Components lists names that are no longer ECS atomics; Roadmap Components lists names that are not current components and may appear only in explicit roadmap prose.

The current catalog declares 24 built-in components. Representative entries (verified names from the file): TransformComponent TransformComponent (spatial primitive), RigidBodyComponent RigidBodyComponent and ColliderComponent ColliderComponent (physics, consumed by runtime.physicsSystem and runtime.collisionSystem), CameraComponent CameraComponent (rendering, replication public/medium), ScriptComponent ScriptComponent (behavior attachment), and TimerComponent TimerComponent (a runtime event source consumed by runtime.timerSystem). For the full list and every field, read the generated file.

The field contract

Built-in components are atomic engine contracts under ADR 0020: each is a small, fixed-shape primitive, not a gameplay bundle. Gameplay patterns — health, damage, spawn pools, collectors, motion helpers — are script patterns, not ECS atomics; the generated file lists the names that were deliberately stripped to keep the atomic set clean.

The catalog enforces a canonical field contract: every component declares a typed field set validated by ComponentSchema, and the generated file pins the field shape with a Field contract hash. Component payloads are mutated only through authorized Entity host operations; the Runtime validates payloads against ComponentSchema rather than trusting callers. Each component also declares an exposure model — its palette visibility (whether it surfaces in the Build palette), its replication policy (who sees it and at what fidelity), and its runtime/renderer consumer status (whether the simulation consumes it, projects it, or treats it as internal).

Version pinning

A citation should name an immutable coordinate, not "latest." The generated file carries the pinning data:

• Component catalog contract hash — a sha256 over the whole catalog.
• Component field contract version — ecs.component-field-contract.v1.
• Component field contract hash — a sha256 over the field contract.
• Per-component contract version and hashes — each component's Contract version (for example component.transform.contract.v1) plus its contract and field hashes.

These coordinates trace back to packages/engine-version and the docs export manifest, which records the exact engineVersionFull for this generated site. Cite the hash for an exact contract snapshot; see Versioning Policy.

How components are edited

You never write component payloads onto the Project Graph directly. Mutations flow through the Action Catalog verbs that own component writes — for example project.entity.component.set project.entity.component.set and project.entity.component.delete project.entity.component.delete — or through the script SDK's authorized ctx.entity.*Component(...) accessors. This keeps one mutation authority over component state. See How-To: Edit Components.

Related

• How-To: Edit Components — the canonical editing flow.
• Reference: Action Catalog — the verbs that mutate component state.
• Explanation: Backend Authority — why the frontend is a non-authoritative projection.

Status: stable orientation page. The catalog itself is generated and version-pinned; trust the generated file over any prose here.