Packages
recs
Readme

@latticexyz/recs

@latticexyz/recs

Table of contents

Enumerations

Interfaces

Type Aliases

Variables

Functions

Type Aliases

AnyComponent

Ƭ AnyComponent: Component<Schema>

Defined in

types.ts:105 (opens in a new tab)


AnyComponentValue

Ƭ AnyComponentValue: ComponentValue

Defined in

types.ts:103 (opens in a new tab)


ArrayType

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

Defined in

types.ts:225 (opens in a new tab)


ComponentUpdate

Ƭ ComponentUpdate<S, T>: Object

Type of a component update corresponding to a given Schema.

Type parameters

NameType
Sextends Schema = Schema
Tundefined

Type declaration

NameType
componentComponent<S, Metadata, T>
entityEntityIndex
value[ComponentValue<S, T> | undefined, ComponentValue | undefined]

Defined in

types.ts:68 (opens in a new tab)


ComponentValue

Ƭ 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.

Type parameters

NameType
Sextends Schema = Schema
Tundefined

Defined in

types.ts:61 (opens in a new tab)


Components

Ƭ Components: Object

Index signature

▪ [key: string]: Component

Defined in

types.ts:95 (opens in a new tab)


EntityID

Ƭ EntityID: Opaque<string, "EntityID">

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

Defined in

types.ts:13 (opens in a new tab)


EntityIndex

Ƭ EntityIndex: Opaque<number, "EntityIndex">

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

Defined in

types.ts:8 (opens in a new tab)


EntityQueryFragment

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

Type parameters

NameType
Textends Schema = Schema

Defined in

types.ts:173 (opens in a new tab)


EntityType

Ƭ EntityType: Entity | OptionalEntity

Defined in

types.ts:253 (opens in a new tab)


HasQueryFragment

Ƭ HasQueryFragment<T>: Object

Type parameters

NameType
Textends Schema

Type declaration

NameType
componentComponent<T>
typeHas

Defined in

types.ts:131 (opens in a new tab)


HasValueQueryFragment

Ƭ HasValueQueryFragment<T>: Object

Type parameters

NameType
Textends Schema

Type declaration

NameType
componentComponent<T>
typeHasValue
valuePartial<ComponentValue

Defined in

types.ts:136 (opens in a new tab)


Indexer

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

Type of indexer returned by createIndexer.

Type parameters

NameType
Sextends Schema
Mextends Metadata = Metadata
Tundefined

Defined in

types.ts:91 (opens in a new tab)


Layer

Ƭ Layer: Object

Type declaration

NameType
componentsRecord<string, Component<Schema>>
worldWorld

Defined in

types.ts:258 (opens in a new tab)


Layers

Ƭ Layers: Record<string, Layer>

Defined in

types.ts:263 (opens in a new tab)


Metadata

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

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

Defined in

types.ts:27 (opens in a new tab)


NotQueryFragment

Ƭ NotQueryFragment<T>: Object

Type parameters

NameType
Textends Schema

Type declaration

NameType
componentComponent<T>
typeNot

Defined in

types.ts:142 (opens in a new tab)


NotValueQueryFragment

Ƭ NotValueQueryFragment<T>: Object

Type parameters

NameType
Textends Schema

Type declaration

NameType
componentComponent<T>
typeNotValue
valuePartial<ComponentValue

Defined in

types.ts:147 (opens in a new tab)


NumberType

Ƭ NumberType: Number | OptionalNumber

Defined in

types.ts:248 (opens in a new tab)


OptionalType

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

Defined in

types.ts:202 (opens in a new tab)


OverridableComponent

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

Type of overridable component returned by overridableComponent.

Type parameters

NameType
Sextends Schema = Schema
Mextends Metadata = Metadata
Tundefined

Defined in

types.ts:193 (opens in a new tab)


Override

Ƭ Override<S, T>: Object

Type parameters

NameType
Sextends Schema
Tundefined

Type declaration

NameType
entityEntityIndex
valuePartial<ComponentValue | null

Defined in

types.ts:185 (opens in a new tab)


ProxyExpandQueryFragment

Ƭ ProxyExpandQueryFragment: Object

Type declaration

NameType
componentComponent<{ value: Entity }>
depthnumber
typeProxyExpand

Defined in

types.ts:159 (opens in a new tab)


ProxyReadQueryFragment

Ƭ ProxyReadQueryFragment: Object

Type declaration

NameType
componentComponent<{ value: Entity }>
depthnumber
typeProxyRead

Defined in

types.ts:153 (opens in a new tab)


QueryFragment

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

Type parameters

NameType
Textends Schema = Schema

Defined in

types.ts:165 (opens in a new tab)


QueryFragments

Ƭ QueryFragments: QueryFragment[]

Defined in

types.ts:181 (opens in a new tab)


Schema

Ƭ 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.

Index signature

▪ [key: string]: Type

Defined in

types.ts:19 (opens in a new tab)


SchemaOf

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

Type parameters

NameType
Cextends Component<Schema>

Defined in

types.ts:183 (opens in a new tab)


SettingQueryFragment

Ƭ SettingQueryFragment: ProxyReadQueryFragment | ProxyExpandQueryFragment

Defined in

types.ts:179 (opens in a new tab)


ValueType

Ƭ ValueType<T>: Object

Mapping between JavaScript Type enum and corresponding TypeScript type.

Type parameters

NameType
Tundefined

Type declaration

NameType
0boolean
1number
10bigint[] | undefined
11string[]
12string[] | undefined
13EntityID
14EntityID | undefined
15EntityID[]
16EntityID[] | undefined
17T
18T | undefined
2number | undefined
3bigint
4bigint | undefined
5string
6string | undefined
7number[]
8number[] | undefined
9bigint[]

Defined in

types.ts:36 (opens in a new tab)


World

Ƭ World: Object

Type of World returned by createWorld.

Type declaration

NameType
componentsComponent[]
dispose() => void
entitiesEntityID[]
entityToIndexMap<EntityID, EntityIndex>
getEntityIndexStrict(entity: EntityID) => EntityIndex
hasEntity(entity: EntityID) => boolean
registerComponent(component: Component) => void
registerDisposer(disposer: () => void) => void
registerEntity(options?: { id?: EntityID ; idSuffix?: string }) => EntityIndex

Defined in

types.ts:110 (opens in a new tab)

Variables

OptionalTypes

Const OptionalTypes: Type[]

Helper constant with all optional Types.

Defined in

constants.ts:44 (opens in a new tab)

Functions

Has

Has<T>(component): HasQueryFragment

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)]);

Type parameters

NameType
Textends Schema

Parameters

NameTypeDescription
componentComponent<T, Metadata, undefined>Component this query fragment refers to.

Returns

HasQueryFragment

query fragment to be used in runQuery or defineQuery.

Defined in

Query.ts:47 (opens in a new tab)


HasValue

HasValue<T>(component, value): HasValueQueryFragment

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 })]);

Type parameters

NameType
Textends Schema

Parameters

NameTypeDescription
componentComponent<T, Metadata, undefined>Component this query fragment refers to.
valuePartial<ComponentValueOnly include entities with this (partial) component value from the result.

Returns

HasValueQueryFragment

query fragment to be used in runQuery or defineQuery.

Defined in

Query.ts:88 (opens in a new tab)


Not

Not<T>(component): NotQueryFragment

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)]);

Type parameters

NameType
Textends Schema

Parameters

NameTypeDescription
componentComponent<T, Metadata, undefined>Component this query fragment refers to.

Returns

NotQueryFragment

query fragment to be used in runQuery or defineQuery.

Defined in

Query.ts:67 (opens in a new tab)


NotValue

NotValue<T>(component, value): NotValueQueryFragment

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 })]);

Type parameters

NameType
Textends Schema

Parameters

NameTypeDescription
componentComponent<T, Metadata, undefined>Component this query fragment refers to.
valuePartial<ComponentValueExclude entities with this (partial) component value from the result.

Returns

NotValueQueryFragment

query fragment to be used in runQuery or defineQuery.

Defined in

Query.ts:112 (opens in a new tab)


ProxyExpand

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" })]);

Parameters

NameTypeDescription
componentComponent<{ value: Entity }, Metadata, undefined>Component to apply this query fragment to.
depthnumberMax depth in the relationship chain to traverse.

Returns

ProxyExpandQueryFragment

query fragment to be used in runQuery or defineQuery.

Defined in

Query.ts:159 (opens in a new tab)


ProxyRead

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" })]);

Parameters

NameTypeDescription
componentComponent<{ value: Entity }, Metadata, undefined>Component this query fragment refers to.
depthnumberMax depth in the relationship chain to traverse.

Returns

ProxyReadQueryFragment

query fragment to be used in runQuery or defineQuery.

Defined in

Query.ts:137 (opens in a new tab)


clearLocalCache

clearLocalCache(component, uniqueWorldIdentifier?): void

Parameters

NameType
componentComponent<Schema, Metadata, undefined>
uniqueWorldIdentifier?string

Returns

void

Defined in

Component.ts:439 (opens in a new tab)


componentValueEquals

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

Type parameters

NameType
Sextends Schema
Tundefined

Parameters

NameTypeDescription
a?Partial<ComponentValuePartial ComponentValue to compare to b
b?ComponentValueComponent value to compare a to.

Returns

boolean

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

Defined in

Component.ts:229 (opens in a new tab)


createEntity

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

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

Parameters

NameTypeDescription
worldWorldWorld object this entity should be registered in.
components?[Component<Schema, Metadata, undefined>, ComponentValue][]Array of [Component, ComponentValue] tuples to be added to this entity. (Use withValue to generate these tuples with type safety.)
options?{ id?: EntityID } | { idSuffix?: string }Optional: { id: EntityID for this entity. Use this for entities that were created outside of recs, eg. in the corresponding solecs contracts. idSuffix: string to be appended to the auto-generated id. Use this for improved readability. Do not use this if the id option is provided. }

Returns

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.)

Defined in

Entity.ts:17 (opens in a new tab)


createIndexer

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

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.

Type parameters

NameType
Sextends Schema
Mextends Metadata
Tundefined

Parameters

NameTypeDescription
componentComponent<S, M, T>Component to index.

Returns

Indexer

Indexed version of the component.

Defined in

Indexer.ts:18 (opens in a new tab)


createLocalCache

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

Type parameters

NameType
Sextends Schema
Mextends Metadata
Tundefined

Parameters

NameType
componentComponent<S, M, T>
uniqueWorldIdentifier?string

Returns

Component<S, M, T>

Defined in

Component.ts:444 (opens in a new tab)


createWorld

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.

Returns

Object

A new World

NameType
componentsComponent<Schema, Metadata, undefined>[]
dispose(namespace?: string) => void
entitiesEntityID[]
entityToIndexMap<EntityID, EntityIndex>
getEntityIndexStrict(entity: EntityID) => EntityIndex
hasEntity(entity: EntityID) => boolean
registerComponent(component: Component<Schema, Metadata, undefined>) => void
registerDisposer(disposer: () => void, namespace: string) => void
registerEntity(__namedParameters: { id?: EntityID ; idSuffix?: string }) => EntityIndex

Defined in

World.ts:13 (opens in a new tab)


defineComponent

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" });

Type parameters

NameType
Sextends Schema
Mextends Metadata
Tundefined

Parameters

NameTypeDescription
worldWorldWorld object this component should be registered onto.
schemaSSchema of component values. Uses Type enum as bridge between typescript types and javascript accessible values.
options?ObjectOptional: { id: descriptive id for this component (otherwise an autogenerated id is used), metadata: arbitrary metadata (eg. contractId for solecs mapped components), indexed: if this flag is set, an indexer is applied to this component (see createIndexer) }
options.id?string-
options.indexed?boolean-
options.metadata?M-

Returns

Component<S, M, T>

Component object linked to the provided World

Defined in

Component.ts:42 (opens in a new tab)


defineComponentSystem

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

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

Type parameters

NameType
Sextends Schema

Parameters

NameTypeDescription
worldWorldWorld object this system should be registered in.
componentComponent<S, Metadata, undefined>Component to whose updates to react.
system(update: ComponentUpdate voidSystem function to run when the given component is updated.
optionsObjectOptional: { runOnInit: if true, run this system for all entities in the component when the system is created. Else only run on updates after the system is created. Default true. }
options.runOnInit?boolean-

Returns

void

Defined in

System.ts:115 (opens in a new tab)


defineEnterQuery

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.

Parameters

NameTypeDescription
fragmentsQueryFragment[]Query fragments
options?Object-
options.runOnInit?boolean-

Returns

Observable<ComponentUpdate>

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

Defined in

Query.ts:550 (opens in a new tab)


defineEnterSystem

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

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

Parameters

NameTypeDescription
worldWorldWorld object this system should be registered in.
queryQueryFragment[]Enter query to react to.
system(update: ComponentUpdate voidSystem function to run when the result of the given enter query changes.
optionsObjectOptional: { runOnInit: if true, run this system for all entities matching the query when the system is created. Else only run on updates after the system is created. Default true. }
options.runOnInit?boolean-

Returns

void

Defined in

System.ts:55 (opens in a new tab)


defineExitQuery

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.

Parameters

NameTypeDescription
fragmentsQueryFragment[]Query fragments
options?Object-
options.runOnInit?boolean-

Returns

Observable<ComponentUpdate>

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

Defined in

Query.ts:564 (opens in a new tab)


defineExitSystem

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

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

Parameters

NameTypeDescription
worldWorldWorld object this system should be registered in.
queryQueryFragment[]Exit query to react to.
system(update: ComponentUpdate voidSystem function to run when the result of the given exit query changes.
optionsObjectOptional: { runOnInit: if true, run this system for all entities matching the query when the system is created. Else only run on updates after the system is created. Default true. }
options.runOnInit?boolean-

Returns

void

Defined in

System.ts:75 (opens in a new tab)


defineQuery

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.

Parameters

NameTypeDescription
fragmentsQueryFragment[]Query fragments to execute.
options?ObjectOptional: { runOnInit: if true, the query is executed once with runQuery to build an iniital Set of matching entities. If false only updates after the query was created are considered. initialSet: if given, this set is passed to runOnInit when building the initial Set of matching entities. }
options.initialSet?Set<EntityIndex>-
options.runOnInit?boolean-

Returns

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. }.

NameType
matchingObservableSet<EntityIndex>
update$Observable<ComponentUpdate & { type: UpdateType }>

Defined in

Query.ts:418 (opens in a new tab)


defineRxSystem

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).

Type parameters

Name
T

Parameters

NameTypeDescription
worldWorldWorld object this system should be registered in.
observable$Observable<T>Observable to react to.
system(event: T) => voidSystem function to run on updates of the observable$. System function gets passed the update events from the observable$.

Returns

void

Defined in

System.ts:19 (opens in a new tab)


defineSyncSystem

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

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

Type parameters

NameType
Textends Schema

Parameters

NameTypeDescription
worldWorldWorld object this system should be registered in.
queryQueryFragment[]Result of component is added to all entites matching this query.
component(entity: EntityIndex) => ComponentFunction returning the component to be added to all entities matching the given query.
value(entity: EntityIndex) => ComponentValueFunction returning the component value to be added to all entities matching the given query.
optionsObject-
options.runOnInit?boolean-
options.update?boolean-

Returns

void

Defined in

System.ts:133 (opens in a new tab)


defineSystem

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

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

Parameters

NameTypeDescription
worldWorldWorld object this system should be registered in.
queryQueryFragment[]Query to react to.
system(update: ComponentUpdate voidSystem function to run when the result of the given query changes.
optionsObjectOptional: { runOnInit: if true, run this system for all entities matching the query when the system is created. Else only run on updates after the system is created. Default true. }
options.runOnInit?boolean-

Returns

void

Defined in

System.ts:95 (opens in a new tab)


defineUpdateQuery

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.

Parameters

NameTypeDescription
fragmentsQueryFragment[]Query fragments
options?Object-
options.runOnInit?boolean-

Returns

Observable<ComponentUpdate & { type: UpdateType }>

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

Defined in

Query.ts:536 (opens in a new tab)


defineUpdateSystem

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

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

Parameters

NameTypeDescription
worldWorldWorld object this system should be registered in.
queryQueryFragment[]Update query to react to.
system(update: ComponentUpdate voidSystem function to run when the result of the given update query changes.
optionsObjectOptional: { runOnInit: if true, run this system for all entities matching the query when the system is created. Else only run on updates after the system is created. Default true. }
options.runOnInit?boolean-

Returns

void

Defined in

System.ts:35 (opens in a new tab)


getChildEntities

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.

Parameters

NameTypeDescription
entityEntityIndexEntity to get all child entities for up to the specified depth
componentComponent<{ value: Entity }, Metadata, undefined>Component to use for the relationship chain.
depthnumberDepth up to which the recursion should be applied.

Returns

Set<EntityIndex>

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

Defined in

Query.ts:288 (opens in a new tab)


getComponentEntities

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

Get a set of all entities of the given component.

Type parameters

NameType
Sextends Schema
Tundefined

Parameters

NameTypeDescription
componentComponent<S, Metadata, T>Component to get all entities from

Returns

IterableIterator<EntityIndex>

Set of all entities in the given component.

Defined in

Component.ts:292 (opens in a new tab)


getComponentValue

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

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

Type parameters

NameType
Sextends Schema
Tundefined

Parameters

NameTypeDescription
componentComponent<S, Metadata, T>Component to get the value from for the given entity.
entityEntityIndexEntityIndex of the entity to get the value for from the given component.

Returns

ComponentValue | undefined

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

Defined in

Component.ts:178 (opens in a new tab)


getComponentValueStrict

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

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.

Type parameters

NameType
Sextends Schema
Tundefined

Parameters

NameTypeDescription
componentComponent<S, Metadata, T>Component to get the value from for the given entity.
entityEntityIndexEntityIndex of the entity to get the value for from the given component.

Returns

ComponentValue

Value of the given entity in the given component.

Defined in

Component.ts:206 (opens in a new tab)


getEntitiesWithValue

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

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

Type parameters

NameType
Sextends Schema

Parameters

NameTypeDescription
componentComponent<S, Metadata, undefined> | IndexerComponent to get entities with the given value from.
valuePartial<ComponentValuelook for entities with this ComponentValue.

Returns

Set<EntityIndex>

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

Defined in

Component.ts:266 (opens in a new tab)


getEntityComponents

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.

Parameters

NameTypeDescription
worldWorldWorld object the given entity is registered on.
entityEntityIndexEntityIndex of the entity to get the list of components for.

Returns

Component[]

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

Defined in

World.ts:96 (opens in a new tab)


hasComponent

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

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

Type parameters

NameType
Sextends Schema
Tundefined

Parameters

NameTypeDescription
componentComponent<S, Metadata, T>Component to check whether it has a value for the given entity.
entityEntityIndexEntityIndex of the entity to check whether it has a value in the given component.

Returns

boolean

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

Defined in

Component.ts:162 (opens in a new tab)


isArrayType

isArrayType(t): t is ArrayType

Parameters

NameType
tType

Returns

t is ArrayType

Defined in

types.ts:235 (opens in a new tab)


isComponentUpdate

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

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

Type parameters

NameType
Sextends Schema

Parameters

NameTypeDescription
updateComponentUpdateComponent update to infer the type of.
componentComponent<S, Metadata, undefined>Component to check whether the given update corresponds to it.

Returns

update is ComponentUpdate<S, undefined>

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

Defined in

utils.ts:13 (opens in a new tab)


isEntityType

isEntityType(t): t is EntityType

Parameters

NameType
tType

Returns

t is EntityType

Defined in

types.ts:254 (opens in a new tab)


isFullComponentValue

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

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

Type parameters

NameType
Sextends Schema

Parameters

NameType
componentComponent<S, Metadata, undefined>
valuePartial<ComponentValue

Returns

value is ComponentValue<S, undefined>

Defined in

utils.ts:63 (opens in a new tab)


isIndexer

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

Helper function to check whether a given component is indexed.

Type parameters

NameType
Sextends Schema

Parameters

NameType
cComponent<S, Metadata, undefined> | Indexer

Returns

c is Indexer<S, Metadata, undefined>

Defined in

utils.ts:53 (opens in a new tab)


isNumberType

isNumberType(t): t is NumberType

Parameters

NameType
tType

Returns

t is NumberType

Defined in

types.ts:249 (opens in a new tab)


isOptionalType

isOptionalType(t): t is OptionalType

Parameters

NameType
tType

Returns

t is OptionalType

Defined in

types.ts:212 (opens in a new tab)


namespaceWorld

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.

Parameters

NameTypeDescription
worldObjectWorld to create a new namespace for.
world.componentsComponent<Schema, Metadata, undefined>[]-
world.dispose(namespace?: string) => void-
world.entitiesEntityID[]-
world.entityToIndexMap<EntityID, EntityIndex>-
world.getEntityIndexStrict(entity: EntityID) => EntityIndex-
world.hasEntity(entity: EntityID) => boolean-
world.registerComponent(component: Component<Schema, Metadata, undefined>) => void-
world.registerDisposer(disposer: () => void, namespace: string) => void-
world.registerEntity(__namedParameters: { id?: EntityID ; idSuffix?: string }) => EntityIndex-
namespacestringString descriptor of the new namespace.

Returns

Object

World with a new namespace.

NameType
componentsComponent<Schema, Metadata, undefined>[]
dispose() => void
entitiesEntityID[]
entityToIndexMap<EntityID, EntityIndex>
getEntityIndexStrict(entity: EntityID) => EntityIndex
hasEntity(entity: EntityID) => boolean
registerComponent(component: Component<Schema, Metadata, undefined>) => void
registerDisposer(disposer: () => void) => void
registerEntity(__namedParameters: { id?: EntityID ; idSuffix?: string }) => EntityIndex

Defined in

World.ts:78 (opens in a new tab)


overridableComponent

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

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.

Type parameters

NameType
Sextends Schema
Mextends Metadata
Tundefined

Parameters

NameTypeDescription
componentComponent<S, M, T>Component to use as underlying source for the overridable component

Returns

OverridableComponent

overridable component

Defined in

Component.ts:312 (opens in a new tab)


removeComponent

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

Remove a given entity from a given component.

Type parameters

NameType
Sextends Schema
Mextends Metadata
TT

Parameters

NameTypeDescription
componentComponent<S, M, T>Component to be updated.
entityEntityIndexEntityIndex of the entity whose value should be removed from this component.

Returns

void

Defined in

Component.ts:144 (opens in a new tab)


runQuery

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.

Parameters

NameTypeDescription
fragmentsQueryFragment[]Query fragments to execute.
initialSet?Set<EntityIndex>Optional: provide a Set of entities to execute the query on. If none is given, all existing entities are used for the query.

Returns

Set<EntityIndex>

Set of entities matching the query fragments.

Defined in

Query.ts:321 (opens in a new tab)


setComponent

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 });

Type parameters

NameType
Sextends Schema
Tundefined

Parameters

NameTypeDescription
componentComponent<S, Metadata, T>Component to be updated.
entityEntityIndexEntityIndex of the entity whose value in the given component should be set.
valueComponentValueValue to set, schema must match the component schema.

Returns

void

Defined in

Component.ts:71 (opens in a new tab)


toUpdate

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

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

Type parameters

NameType
Sextends Schema

Parameters

NameTypeDescription
entityEntityIndexEntity to create the component update for.
componentComponent<S, Metadata, undefined>Component to create the component update for.

Returns

ComponentUpdate & { type: UpdateType }

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

Defined in

utils.ts:27 (opens in a new tab)


toUpdateStream

toUpdateStream<S>(component): UnaryFunction<Observable<EntityIndex>, Observable<ComponentUpdate

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

Type parameters

NameType
Sextends Schema

Parameters

NameTypeDescription
componentComponent<S, Metadata, undefined>Component to create update stream for.

Returns

UnaryFunction<Observable<EntityIndex>, Observable<ComponentUpdate

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

Defined in

utils.ts:44 (opens in a new tab)


updateComponent

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 });

Type parameters

NameType
Sextends Schema
Tundefined

Parameters

NameTypeDescription
componentComponent<S, Metadata, T>Component to be updated.
entityEntityIndexEntityIndex of the entity whose value in the given component should be updated.
valuePartial<ComponentValuePartial value to be set, remaining keys will be taken from the existing component value.
initialValue?ComponentValue-

Returns

void

Defined in

Component.ts:121 (opens in a new tab)


withValue

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

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

Type parameters

NameType
Sextends Schema
Tundefined

Parameters

NameTypeDescription
componentComponent<S, Metadata, T>Component with ComponentSchema S
valueComponentValueComponentValue with ComponentSchema S

Returns

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

Tuple [component, value]

Defined in

Component.ts:252 (opens in a new tab)