---
title: "Reference: ECS Components"
description: "Thin pointer to the generated, canonical ECS component catalog, how to read it, the field contract it enforces, and how it is version-pinned."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/reference/components/
---

# Reference: ECS Components

{% version engineVersion="v1.0.232" coordinate="docs-public.v0" /%}

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.

{% proof class="docs.ecs_components" registry="docs/cycles/v1-engine-readiness-loop/PROOF_REGISTRY.json" status="pending" %}
This page is verified against the generated component-type reference. Exact field shapes, hashes, palette visibility, runtime consumers, and replication policies live in that generated file.
{% /proof %}

> 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`](../../../spec/generated/component-types.md): the generated inventory and per-component field contracts.
- [`docs/spec/COMPONENT_TYPE_DEFINITIONS.md`](../../../spec/COMPONENT_TYPE_DEFINITIONS.md): the companion definitions surface.

{% generated-reference file="docs/spec/generated/component-types.md" label="ECS component inventory" /%}

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](../explanation/versioning-policy.md) 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 is the canonical list of **built-in components**. Representative entries (verified names from the file): {% component name="TransformComponent" /%} `TransformComponent` (spatial primitive), {% component name="RigidBodyComponent" /%} `RigidBodyComponent` and {% component name="ColliderComponent" /%} `ColliderComponent` (physics, consumed by `runtime.physicsSystem` and `runtime.collisionSystem`), {% component name="CameraComponent" /%} `CameraComponent` (rendering, replication `public/medium`), {% component name="ScriptComponent" /%} `ScriptComponent` (behavior attachment), and {% component name="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).

{% warning severity="caution" title="Do not invent component names" %}
Only the names in the Inventory table are current built-in components. Names in the `Recently Stripped Pattern Components` and `Roadmap Components` sections are not authorable atomics today, express those behaviors as script patterns or project-defined data instead.
{% /warning %}

## 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](../explanation/versioning-policy.md).

## 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 {% action name="project.entity.component.set" /%} `project.entity.component.set` and {% action name="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](../how-to/edit-components.md).

## Related

- [How-To: Edit Components](../how-to/edit-components.md): the canonical editing flow.
- [Reference: Action Catalog](./action-catalog.md): the verbs that mutate component state.
- [Explanation: Backend Authority](../explanation/backend-authority.md): 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.