Core
Nominal descriptor constructors for schema authoring.
Descriptors are the stable typed identities behind every public ECS surface: schema entries, query slots, system specs, runtime provisioning, long-lived handle intents, and relationships.
If Schema answers "what world can exist?", descriptors answer "what is each named thing in that world?" They are the vocabulary the rest of the ECS system reuses everywhere else.
The normal authoring flow is:
Reach for this module first whenever you introduce a new component, resource, event, state, or service to the game.
// Components describe per-entity state that queries can match.
const Position = Descriptor.Component<{ x: number; y: number }>()("Position")
// Resources describe singleton world data shared across systems.
const DeltaTime = Descriptor.Resource<number>()("DeltaTime")
// Events describe staged cross-system messages.
const DamageTaken = Descriptor.Event<{ amount: number }>()("DamageTaken")
// Services describe host capabilities that live outside ECS storage.
const Logger = Descriptor.Service<{ log: (message: string) => void }>()("Logger")Defines a component descriptor.
ConstructedComponentDefines a component descriptor that also knows how to validate raw values.
ResourceDefines a resource descriptor.
ConstructedResourceDefines a resource descriptor that also knows how to validate raw values.
EventDefines an event descriptor.
StateDefines a state descriptor.
ConstructedStateDefines a state descriptor that also knows how to validate raw values.
ServiceDefines a service descriptor.
hasConstructorChecks whether one descriptor carries raw-construction metadata.
constructorOfReturns the raw constructor carried by one descriptor when present.
Authoring helpers for declaring components, resources, services, events, and states.
Defines a component descriptor.
Use this when declaring per-entity data that should participate in queries and typed entity proofs.
Components are the only descriptor kind that can be queried directly with Game.Query.read(...), write(...), or optional(...).
const Position = Descriptor.Component<{ x: number; y: number }>()("Position")Defines a component descriptor that also knows how to validate raw values.
Use this when the component should never exist in the world in an unvalidated shape, for example vectors, sizes, collider bounds, or other branded domain values.
// Route raw component input through a constructor once at the boundary.
const Position = Descriptor.ConstructedComponent(Vector2)("Position")Defines a resource descriptor.
Resources represent unique world-level values accessed through explicit system specs.
Use resources for singleton world data such as counters, configuration, global timers, camera summaries, or transient per-frame aggregates that should not be duplicated across entities.
// Store shared world state once and request it explicitly from systems.
const Score = Descriptor.Resource<number>()("Score")Defines a resource descriptor that also knows how to validate raw values.
Defines an event descriptor.
Use event descriptors to model append-only messages flowing between systems without exposing untyped channels.
Writers emit into a pending buffer. Readers observe only the committed readable buffer after an explicit Game.Schedule.updateEvents() boundary.
const Hit = Descriptor.Event<{ target: number; amount: number }>()("Hit")Defines a state descriptor.
States are singleton schema values with no queued transition semantics.
Use this when you need one current world-level value and the boundary of changing that value is not itself meaningful. If gameplay logic depends on queued transitions, enter/exit handling, or inState(...) gating, prefer Game.StateMachine(...) instead.
const ActiveLocale = Descriptor.State<"en" | "it">()("ActiveLocale")Defines a state descriptor that also knows how to validate raw values.
Defines a service descriptor.
Services are the dependency-injection side of the system model, similar to Effect environment entries.
Use them for capabilities owned by the host instead of the ECS world: clocks, random sources, render/audio bridges, storage, or network clients. Systems request them explicitly with Game.System.service(...), and the runtime provides them through Game.Runtime.services(...).
// Describe one host capability the runtime must provide.
const Logger = Descriptor.Service<{ log: (message: string) => void }>()("Logger")Checks whether one descriptor carries raw-construction metadata.
Returns the raw constructor carried by one descriptor when present.
Plain descriptors return undefined.
Stable runtime markers used to brand descriptor kinds and constructor-aware variants.
Defines the canonical parent/children relationship pair.
The returned relation is the source-of-truth edge component, while related is the reverse collection maintained by the runtime.
Use hierarchy when the relationship must support ordered children, ancestor/descendant traversal, and linked recursive despawn.
Defines a general relationship pair with direct edges and reverse lookups.
Use a general relation when you need direct source -> target edges plus reverse lookup, but not hierarchy-only behavior such as tree traversal or child reordering.