@latticexyz/recs

• QueryFragmentType
• Type
• UpdateType

• Component
• ComponentWithStream

• AnyComponent
• AnyComponentValue
• ArrayType
• ComponentUpdate
• ComponentValue
• Components
• EntityID
• EntityIndex
• EntityQueryFragment
• EntityType
• HasQueryFragment
• HasValueQueryFragment
• Indexer
• Layer
• Layers
• Metadata
• NotQueryFragment
• NotValueQueryFragment
• NumberType
• OptionalType
• OverridableComponent
• Override
• ProxyExpandQueryFragment
• ProxyReadQueryFragment
• QueryFragment
• QueryFragments
• Schema
• SchemaOf
• SettingQueryFragment
• ValueType
• World

• OptionalTypes

• Has
• HasValue
• Not
• NotValue
• ProxyExpand
• ProxyRead
• clearLocalCache
• componentValueEquals
• createEntity
• createIndexer
• createLocalCache
• createWorld
• defineComponent
• defineComponentSystem
• defineEnterQuery
• defineEnterSystem
• defineExitQuery
• defineExitSystem
• defineQuery
• defineRxSystem
• defineSyncSystem
• defineSystem
• defineUpdateQuery
• defineUpdateSystem
• getChildEntities
• getComponentEntities
• getComponentValue
• getComponentValueStrict
• getEntitiesWithValue
• getEntityComponents
• hasComponent
• isArrayType
• isComponentUpdate
• isEntityType
• isFullComponentValue
• isIndexer
• isNumberType
• isOptionalType
• namespaceWorld
• overridableComponent
• removeComponent
• runQuery
• setComponent
• toUpdate
• toUpdateStream
• updateComponent
• withValue

Ƭ AnyComponent: Component<Schema>

types.ts:105

Ƭ AnyComponentValue: ComponentValue<Schema>

types.ts:103

Ƭ ArrayType: NumberArray | OptionalNumberArray | BigIntArray | OptionalBigIntArray | StringArray | OptionalStringArray | EntityArray | OptionalEntityArray

types.ts:225

Ƭ ComponentUpdate<S, T>: Object

Type of a component update corresponding to a given Schema.

types.ts:68

Ƭ ComponentValue<S, T>: { [key in keyof S]: ValueType<T>[S[key]] }

Used to infer the TypeScript type of a component value corresponding to a given Schema.

types.ts:61

Ƭ Components: Object

▪ [key: string]: Component

types.ts:95

Ƭ EntityID: Opaque<string, "EntityID">

Used to refer to the string id of an entity (independent from a World).

types.ts:13

Ƭ EntityIndex: Opaque<number, "EntityIndex">

Used to refer to the index of an entity in a World.

types.ts:8

Ƭ EntityQueryFragment<T>: HasQueryFragment<T> | HasValueQueryFragment<T> | NotQueryFragment<T> | NotValueQueryFragment<T>

types.ts:173

Ƭ EntityType: Entity | OptionalEntity

types.ts:253

Ƭ HasQueryFragment<T>: Object

types.ts:131

Ƭ HasValueQueryFragment<T>: Object

types.ts:136

Ƭ Indexer<S, M, T>: Component<S, M, T> & { getEntitiesWithValue: (value: ComponentValue<S, T>) => Set<EntityIndex> }

Type of indexer returned by createIndexer.

types.ts:91

Ƭ Layer: Object

types.ts:258

Ƭ Layers: Record<string, Layer>

types.ts:263

Ƭ Metadata: { [key: string]: unknown; } | undefined

Used to add arbitrary metadata to components. (Eg contractId for components that have a corresponding solecs component contract.)

types.ts:27

Ƭ NotQueryFragment<T>: Object

types.ts:142

Ƭ NotValueQueryFragment<T>: Object

types.ts:147

Ƭ NumberType: Number | OptionalNumber

types.ts:248

Ƭ OptionalType: OptionalNumber | OptionalBigInt | OptionalString | OptionalEntity | OptionalNumberArray | OptionalBigIntArray | OptionalStringArray | OptionalEntityArray

types.ts:202

Ƭ OverridableComponent<S, M, T>: Component<S, M, T> & { addOverride: (overrideId: string, update: Override<S, T>) => void ; removeOverride: (overrideId: string) => void }

Type of overridable component returned by overridableComponent.

types.ts:193

Ƭ Override<S, T>: Object

types.ts:185

Ƭ ProxyExpandQueryFragment: Object

types.ts:159

Ƭ ProxyReadQueryFragment: Object

types.ts:153

Ƭ QueryFragment<T>: HasQueryFragment<T> | HasValueQueryFragment<T> | NotQueryFragment<T> | NotValueQueryFragment<T> | ProxyReadQueryFragment | ProxyExpandQueryFragment

types.ts:165

Ƭ QueryFragments: QueryFragment<Schema>[]

types.ts:181

Ƭ Schema: Object

Used to define the schema of a Component. Uses Type enum to be able to access the component type in JavaScript as well as have TypeScript type checks.

▪ [key: string]: Type

types.ts:19

Ƭ SchemaOf<C>: C extends Component<infer S> ? S : never

types.ts:183

Ƭ SettingQueryFragment: ProxyReadQueryFragment | ProxyExpandQueryFragment

types.ts:179

Ƭ ValueType<T>: Object

Mapping between JavaScript Type enum and corresponding TypeScript type.

types.ts:36

Ƭ World: Object

Type of World returned by createWorld.

types.ts:110

• Const OptionalTypes: Type[]

Helper constant with all optional Types.

constants.ts:44

▸ Has<T>(component): HasQueryFragment<T>

Create a HasQueryFragment.

Remarks

The HasQueryFragment filters for entities that have the given component, independent from the component value.

Example

Query for all entities with a Position.

runQuery([Has(Position)]);

HasQueryFragment<T>

query fragment to be used in runQuery or defineQuery.

Query.ts:47

▸ HasValue<T>(component, value): HasValueQueryFragment<T>

Create a HasValueQueryFragment.

Remarks

The HasValueQueryFragment filters for entities that have the given component with the given component value.

Example

Query for all entities at Position (0,0).

runQuery([HasValue(Position, { x: 0, y: 0 })]);

HasValueQueryFragment<T>

query fragment to be used in runQuery or defineQuery.

Query.ts:88

▸ Not<T>(component): NotQueryFragment<T>

Create a NotQueryFragment.

Remarks

The NotQueryFragment filters for entities that don't have the given component, independent from the component value.

Example

Query for all entities with a Position that are not Movable.

runQuery([Has(Position), Not(Movable)]);

NotQueryFragment<T>

query fragment to be used in runQuery or defineQuery.

Query.ts:67

▸ NotValue<T>(component, value): NotValueQueryFragment<T>

Create a NotValueQueryFragment.

Remarks

The NotValueQueryFragment filters for entities that don't have the given component with the given component value.

Example

Query for all entities that have a Position, except for those at Position (0,0).

runQuery([Has(Position), NotValue(Position, { x: 0, y: 0 })]);

NotValueQueryFragment<T>

query fragment to be used in runQuery or defineQuery.

Query.ts:112

▸ ProxyExpand(component, depth): ProxyExpandQueryFragment

Create a ProxyExpandQueryFragment.

Remarks

The ProxyExpandQueryFragment activates the "proxy expand mode" for the rest of the query. This means that for all remaining fragments in the query not only the matching entities themselves are included in the intermediate set, but also all their "children" down to the given depth on the relationship chain defined by the given component.

Example

Query for all entities (directly or indirectly) owned by an entity with Name "Alice".

runQuery([ProxyExpand(OwnedByEntity, Number.MAX_SAFE_INTEGER), HasValue(Name, { name: "Alice" })]);

ProxyExpandQueryFragment

query fragment to be used in runQuery or defineQuery.

Query.ts:159

▸ ProxyRead(component, depth): ProxyReadQueryFragment

Create a ProxyReadQueryFragment.

Remarks

The ProxyReadQueryFragment activates the "proxy read mode" for the rest of the query. This means that for all remaining fragments in the query not only the entities themselves are checked, but also their "ancestors" up to the given depth on the relationship chain defined by the given component.

Example

Query for all entities that have a Position and are (directly or indirectly) owned by an entity with Name "Alice".

runQuery([Has(Position), ProxyRead(OwnedByEntity, Number.MAX_SAFE_INTEGER), HasValue(Name, { name: "Alice" })]);

ProxyReadQueryFragment

query fragment to be used in runQuery or defineQuery.

Query.ts:137

▸ clearLocalCache(component, uniqueWorldIdentifier?): void

void

Component.ts:439

▸ componentValueEquals<S, T>(a?, b?): boolean

Compare two ComponentValues. a can be a partial component value, in which case only the keys present in a are compared to the corresponding keys in b.

Example

componentValueEquals({ x: 1, y: 2 }, { x: 1, y: 3 }) // returns false because value of y doesn't match
componentValueEquals({ x: 1 }, { x: 1, y: 3 }) // returns true because x is equal and y is not present in a

boolean

True if a equals b in the keys present in a or neither a nor b are defined, else false.

Component.ts:229

▸ createEntity(world, components?, options?): EntityIndex

Register a new entity in the given World and initialize it with the given ComponentValues.

EntityIndex

index of this entity in the World. This EntityIndex is used to refer to this entity in other recs methods (eg setComponent). (This is to avoid having to store strings in every component.)

Entity.ts:17

▸ createIndexer<S, M, T>(component): Indexer<S, M, T>

Create an indexed component from a given component.

Remarks

An indexed component keeps a "reverse mapping" from ComponentValue to the Set of Entities with this value. This adds a performance overhead to modifying component values and a memory overhead since in the worst case there is one Set per entity (if every entity has a different component value). In return the performance for querying for entities with a given component value is close to O(1) (instead of O(#entities) in a regular non-indexed component). As a rule of thumb only components that are added to many entities and are queried with HasValue a lot should be indexed (eg. the Position component).

Dev

This could be made more (memory) efficient by using a hash of the component value as key, but would require handling hash collisions.

Indexer<S, M, T>

Indexed version of the component.

Indexer.ts:18

▸ createLocalCache<S, M, T>(component, uniqueWorldIdentifier?): Component<S, M, T>

Component<S, M, T>

Component.ts:444

▸ createWorld(): Object

Create a new World.

Remarks

A World is the central object of an ECS application, where all Components, registerEntity Entities and Systems are registerd.

Object

A new World

World.ts:13

▸ defineComponent<S, M, T>(world, schema, options?): Component<S, M, T>

Components contain state indexed by entities and are one of the fundamental building blocks in ECS. Besides containing the state, components expose an rxjs update$ stream, that emits an event any time the value of an entity in this component is updated.

Remarks

Components work with EntityIndex, not EntityID. Get the EntityID from a given EntityIndex via World.entities[EntityIndex].

Example

const Position = defineComponent(world, { x: Type.Number, y: Type.Number }, { id: "Position" });

Component<S, M, T>

Component object linked to the provided World

Component.ts:42

▸ defineComponentSystem<S>(world, component, system, options?): void

Create a system that is called every time the given component is updated.

void

System.ts:115

▸ defineEnterQuery(fragments, options?): Observable<ComponentUpdate>

Define a query object that only passes update events of type UpdateType.Enter to the update$ stream. See defineQuery for details.

Observable<ComponentUpdate>

Stream of component updates of entities matching the query for the first time

Query.ts:550

▸ defineEnterSystem(world, query, system, options?): void

Create a system that is called on every event of the given enter query.

void

System.ts:55

▸ defineExitQuery(fragments, options?): Observable<ComponentUpdate>

Define a query object that only passes update events of type UpdateType.Exit to the update$ stream. See defineQuery for details.

Observable<ComponentUpdate>

Stream of component updates of entities not matching the query anymore for the first time

Query.ts:564

▸ defineExitSystem(world, query, system, options?): void

Create a system that is called on every event of the given exit query.

void

System.ts:75

▸ defineQuery(fragments, options?): Object

Create a query object including an update$ stream and a Set of entities currently matching the query.

Remarks

update$ stream needs to be subscribed to in order for the logic inside the stream to be executed and therefore in order for the matching set to be updated.

defineQuery should be strongly preferred over runQuery if the query is used for systems or other use cases that repeatedly require the query result or updates to the query result. defineQuery does not reevaluate the entire query if an accessed component changes, but only performs the minimal set of checks on the updated entity to evaluate wether the entity still matches the query, resulting in significant performance advantages over runQuery.

The query fragments are executed from left to right and are concatenated with a logical AND. For performance reasons, the most restrictive query fragment should be first in the list of query fragments, in order to reduce the number of entities the next query fragment needs to be checked for. If no proxy fragments are used, every entity in the resulting set passes every query fragment. If setting fragments are used, the order of the query fragments influences the result, since settings only apply to fragments after the setting fragment.

Object

Query object: { update$: RxJS stream of updates to the query result. The update contains the component update that caused the query update, as well as the update type. matching: Mobx observable set of entities currently matching the query. }.

Query.ts:418

▸ defineRxSystem<T>(world, observable$, system): void

Create a system that is called on every update of the given observable.

Remarks

Advantage of using this function over directly subscribing to the RxJS observable is that the system is registered in the world and disposed when the world is disposed (eg. during a hot reload in development).

void

System.ts:19

▸ defineSyncSystem<T>(world, query, component, value, options?): void

Create a system to synchronize updates to one component with another component.

void

System.ts:133

▸ defineSystem(world, query, system, options?): void

Create a system that is called on every event of the given query.

void

System.ts:95

▸ defineUpdateQuery(fragments, options?): Observable<ComponentUpdate & { type: UpdateType }>

Define a query object that only passes update events of type UpdateType.Update to the update$ stream. See defineQuery for details.

Observable<ComponentUpdate & { type: UpdateType }>

Stream of component updates of entities that had already matched the query

Query.ts:536

▸ defineUpdateSystem(world, query, system, options?): void

Create a system that is called on every event of the given update query.

void

System.ts:35

▸ getChildEntities(entity, component, depth): Set<EntityIndex>

Recursively compute all direct and indirect child entities up to the specified depth down the relationship chain defined by the given component.

Set<EntityIndex>

Set of entities that are child entities of the given entity via the given component.

Query.ts:288

▸ getComponentEntities<S, T>(component): IterableIterator<EntityIndex>

Get a set of all entities of the given component.

IterableIterator<EntityIndex>

Set of all entities in the given component.

Component.ts:292

▸ getComponentValue<S, T>(component, entity): ComponentValue<S, T> | undefined

Get the value of a given entity in the given component. Returns undefined if no value or only a partial value is found.

ComponentValue<S, T> | undefined

Value of the given entity in the given component or undefined if no value exists.

Component.ts:178

▸ getComponentValueStrict<S, T>(component, entity): ComponentValue<S, T>

Get the value of a given entity in the given component. Throws an error if no value exists for the given entity in the given component.

Remarks

Throws an error if no value exists in the component for the given entity.

ComponentValue<S, T>

Value of the given entity in the given component.

Component.ts:206

▸ getEntitiesWithValue<S>(component, value): Set<EntityIndex>

Get a set of entities that have the given component value in the given component.

Set<EntityIndex>

Set with EntityIndices of the entities with the given component value.

Component.ts:266

▸ getEntityComponents(world, entity): Component[]

Get all components that have a value for the given entity.

Dev

Design decision: don't store a list of components for each entity but compute it dynamically when needed because there are less components than entities and maintaining a list of components per entity is a large overhead.

Component[]

Array of components that have a value for the given entity.

World.ts:96

▸ hasComponent<S, T>(component, entity): boolean

Check whether a component contains a value for a given entity.

boolean

true if the component contains a value for the given entity, else false.

Component.ts:162

▸ isArrayType(t): t is ArrayType

t is ArrayType

types.ts:235

▸ isComponentUpdate<S>(update, component): update is ComponentUpdate<S, undefined>

Type guard to infer the TypeScript type of a given component update

update is ComponentUpdate<S, undefined>

True (+ infered type for update) if update belongs to component. Else false.

utils.ts:13

▸ isEntityType(t): t is EntityType

t is EntityType

types.ts:254

▸ isFullComponentValue<S>(component, value): value is ComponentValue<S, undefined>

Helper function to check whether a given component value is partial or full.

value is ComponentValue<S, undefined>

utils.ts:63

▸ isIndexer<S>(c): c is Indexer<S, Metadata, undefined>

Helper function to check whether a given component is indexed.

c is Indexer<S, Metadata, undefined>

utils.ts:53

▸ isNumberType(t): t is NumberType

t is NumberType

types.ts:249

▸ isOptionalType(t): t is OptionalType

t is OptionalType

types.ts:212

▸ namespaceWorld(world, namespace): Object

Create a new namespace from an existing World. The dispose method of a namespaced World only calls disposers registered on this namespace.

Object

World with a new namespace.

World.ts:78

▸ overridableComponent<S, M, T>(component): OverridableComponent<S, M, T>

An overridable component is a mirror of the source component, with functions to lazily override specific entity values. Lazily override means the values are not actually set to the source component, but the override is only returned if the value is read.

• When an override for an entity is added to the component, the override is propagated via the component's update$ stream.
• While an override is set for a specific entity, no updates to the source component for this entity will be propagated to the update$ stream.
• When an override is removed for a specific entity and there are more overrides targeting this entity, the override with the highest nonce will be propagated to the update$ stream.
• When an override is removed for a specific entity and there are no more overrides targeting this entity, the non-overridden underlying component value of this entity will be propagated to the update$ stream.

OverridableComponent<S, M, T>

overridable component

Component.ts:312

▸ removeComponent<S, M, T>(component, entity): void

Remove a given entity from a given component.

void

Component.ts:144

▸ runQuery(fragments, initialSet?): Set<EntityIndex>

Execute a list of query fragments to receive a Set of matching entities.

Remarks

The query fragments are executed from left to right and are concatenated with a logical AND. For performance reasons, the most restrictive query fragment should be first in the list of query fragments, in order to reduce the number of entities the next query fragment needs to be checked for. If no proxy fragments are used, every entity in the resulting set passes every query fragment. If setting fragments are used, the order of the query fragments influences the result, since settings only apply to fragments after the setting fragment.

Set<EntityIndex>

Set of entities matching the query fragments.

Query.ts:321

▸ setComponent<S, T>(component, entity, value): void

Set the value for a given entity in a given component.

Example

setComponent(Position, entity, { x: 1, y: 2 });

void

Component.ts:71

▸ toUpdate<S>(entity, component): ComponentUpdate<S, undefined> & { type: UpdateType }

Helper function to create a component update for the current component value of a given entity.

ComponentUpdate<S, undefined> & { type: UpdateType }

Component update corresponding to the given entity, the given component and the entity's current component value.

utils.ts:27

▸ toUpdateStream<S>(component): UnaryFunction<Observable<EntityIndex>, Observable<ComponentUpdate<S, undefined> & { type: UpdateType }>>

Helper function to turn a stream of EntityIndices into a stream of component updates of the given component.

UnaryFunction<Observable<EntityIndex>, Observable<ComponentUpdate<S, undefined> & { type: UpdateType }>>

Unary function to be used with RxJS that turns stream of EntityIndices into stream of component updates.

utils.ts:44

▸ updateComponent<S, T>(component, entity, value, initialValue?): void

Update the value for a given entity in a given component while keeping the old value of keys not included in the update.

Remarks

This function fails silently during runtime if a partial value is set for an entity that does not have a component value yet, since then a partial value will be set in the component for this entity.

Example

updateComponent(Position, entity, { x: 1 });

void

Component.ts:121

▸ withValue<S, T>(component, value): [Component<S, Metadata, T>, ComponentValue<S, T>]

Util to create a tuple of a component and value with matching schema. (Used to enforce Typescript type safety.)

[Component<S, Metadata, T>, ComponentValue<S, T>]

Tuple [component, value]

Component.ts:252