@latticexyz/recs

# @latticexyz/recs

# Table of contents

# Enumerations

# Interfaces

# Type Aliases

# Variables

# Functions

# Enumerations

# QueryFragmentType

QueryFragmentType: Enum QueryFragmentType

# Defined in

types.ts:118


# Type

Type: Enum Type

Type enum is used to specify value types in ComponentSchema to be able to access type values in JavaScript in addition to TypeScript type checks.

# Defined in

constants.ts:5


# UpdateType

UpdateType: Enum UpdateType

Used to specify type of ComponentUpdate.

  • Enter: Update added a value to an entity that did not have a value before
  • Exit: Update removed a value from an entity that had a value before
  • Update: Update changed a value of an entity that already had a value before. Note: the value doesn't need to be different from the previous value.
  • Noop: Update did nothing (removed a value from an entity that did not have a value)

# Defined in

constants.ts:30

# Interfaces

# Component

Component: Interface Component<S, M, T>

Type of component returned by defineComponent.

# Type parameters

Name Type
S extends Schema = Schema
M extends Metadata = Metadata
T undefined

# Defined in

types.ts:73


# ComponentWithStream

ComponentWithStream: Interface ComponentWithStream<S, T>

Type of component returned by defineComponent.

# Type parameters

Name Type
S extends Schema
T undefined

# Defined in

types.ts:95

# Type Aliases

# AnyComponent

Ƭ AnyComponent: Component<Schema>

# Defined in

types.ts:101


# AnyComponentValue

Ƭ AnyComponentValue: ComponentValue<Schema>

# Defined in

types.ts:99


# ArrayType

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

# Defined in

types.ts:217


# ComponentUpdate

Ƭ ComponentUpdate: Object

Type of a component update corresponding to a given Schema.

# Type parameters

Name Type
S extends Schema = Schema
T undefined

# Type declaration

Name Type
component Component<S, Metadata, T>
entity EntityIndex
value [ComponentValue<S, T> | undefined, ComponentValue<S, T> | undefined]

# Defined in

types.ts:64


# ComponentValue

Ƭ ComponentValue: { [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

Name Type
S extends Schema = Schema
T undefined

# Defined in

types.ts:57


# Components

Ƭ Components: Object

# Index signature

▪ [key: string]: Component

# Defined in

types.ts:91


# EntityID

Ƭ EntityID: Opaque<string, "EntityID">

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

# Defined in

types.ts:13


# EntityIndex

Ƭ EntityIndex: Opaque<number, "EntityIndex">

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

# Defined in

types.ts:8


# EntityQueryFragment

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

# Type parameters

Name Type
T extends Schema = Schema

# Defined in

types.ts:169


# EntityType

Ƭ EntityType: Entity | OptionalEntity

# Defined in

types.ts:241


# HasQueryFragment

Ƭ HasQueryFragment: Object

# Type parameters

Name Type
T extends Schema

# Type declaration

Name Type
component Component<T>
type Has

# Defined in

types.ts:127


# HasValueQueryFragment

Ƭ HasValueQueryFragment: Object

# Type parameters

Name Type
T extends Schema

# Type declaration

Name Type
component Component<T>
type HasValue
value Partial<ComponentValue<T>>

# Defined in

types.ts:132


# Indexer

Ƭ Indexer: Component<S, M, T> & Object

Type of indexer returned by createIndexer.

# Type parameters

Name Type
S extends Schema
M extends Metadata = Metadata
T undefined

# Defined in

types.ts:87


# Layer

Ƭ Layer: Object

# Type declaration

Name Type
components Record<string, Component<Schema>>
world World

# Defined in

types.ts:246


# Layers

Ƭ Layers: Record<string, Layer>

# Defined in

types.ts:251


# Metadata

Ƭ Metadata: Object | undefined

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

# Defined in

types.ts:27


# NotQueryFragment

Ƭ NotQueryFragment: Object

# Type parameters

Name Type
T extends Schema

# Type declaration

Name Type
component Component<T>
type Not

# Defined in

types.ts:138


# NotValueQueryFragment

Ƭ NotValueQueryFragment: Object

# Type parameters

Name Type
T extends Schema

# Type declaration

Name Type
component Component<T>
type NotValue
value Partial<ComponentValue<T>>

# Defined in

types.ts:143


# NumberType

Ƭ NumberType: Number | OptionalNumber

# Defined in

types.ts:236


# OptionalType

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

# Defined in

types.ts:198


# OverridableComponent

Ƭ OverridableComponent: Component<S, M, T> & Object

Type of overridable component returned by overridableComponent.

# Type parameters

Name Type
S extends Schema = Schema
M extends Metadata = Metadata
T undefined

# Defined in

types.ts:189


# Override

Ƭ Override: Object

# Type parameters

Name Type
S extends Schema
T undefined

# Type declaration

Name Type
entity EntityIndex
value Partial<ComponentValue<S, T>> | null

# Defined in

types.ts:181


# ProxyExpandQueryFragment

Ƭ ProxyExpandQueryFragment: Object

# Type declaration

Name Type
component Component<Object>
depth number
type ProxyExpand

# Defined in

types.ts:155


# ProxyReadQueryFragment

Ƭ ProxyReadQueryFragment: Object

# Type declaration

Name Type
component Component<Object>
depth number
type ProxyRead

# Defined in

types.ts:149


# QueryFragment

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

# Type parameters

Name Type
T extends Schema = Schema

# Defined in

types.ts:161


# QueryFragments

Ƭ QueryFragments: QueryFragment<Schema>[]

# Defined in

types.ts:177


# 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


# SchemaOf

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

# Type parameters

Name Type
C extends Component<Schema>

# Defined in

types.ts:179


# SettingQueryFragment

Ƭ SettingQueryFragment: ProxyReadQueryFragment | ProxyExpandQueryFragment

# Defined in

types.ts:175


# ValueType

Ƭ ValueType: Object

Mapping between JavaScript Type enum and corresponding TypeScript type.

# Type parameters

Name Type
T undefined

# Type declaration

Name Type
0 boolean
1 number
10 EntityID | undefined
11 EntityID[]
12 EntityID[] | undefined
13 T
14 T | undefined
2 number | undefined
3 string
4 string | undefined
5 number[]
6 number[] | undefined
7 string[]
8 string[] | undefined
9 EntityID

# Defined in

types.ts:36


# World

Ƭ World: Object

Type of World returned by createWorld.

# Type declaration

Name Type
components Component[]
dispose Function
entities EntityID[]
entityToIndex Map<EntityID, EntityIndex>
getEntityIndexStrict Function
hasEntity Function
registerComponent Function
registerDisposer Function
registerEntity Function

# Defined in

types.ts:106

# Variables

# OptionalTypes

Const OptionalTypes: Type[]

Helper constant with all optional Types.

# Defined in

constants.ts:40

# Functions

# Has

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

# Type parameters

Name Type
T extends Schema

# Parameters

Name Type Description
component Component<T, Metadata, undefined> Component this query fragment refers to.

# Returns

HasQueryFragment<T>

query fragment to be used in runQuery or defineQuery.

# Defined in

Query.ts:47


# HasValue

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

# Type parameters

Name Type
T extends Schema

# Parameters

Name Type Description
component Component<T, Metadata, undefined> Component this query fragment refers to.
value Partial<ComponentValue<T, undefined>> Only include entities with this (partial) component value from the result.

# Returns

HasValueQueryFragment<T>

query fragment to be used in runQuery or defineQuery.

# Defined in

Query.ts:88


# Not

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

# Type parameters

Name Type
T extends Schema

# Parameters

Name Type Description
component Component<T, Metadata, undefined> Component this query fragment refers to.

# Returns

NotQueryFragment<T>

query fragment to be used in runQuery or defineQuery.

# Defined in

Query.ts:67


# NotValue

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

# Type parameters

Name Type
T extends Schema

# Parameters

Name Type Description
component Component<T, Metadata, undefined> Component this query fragment refers to.
value Partial<ComponentValue<T, undefined>> Exclude entities with this (partial) component value from the result.

# Returns

NotValueQueryFragment<T>

query fragment to be used in runQuery or defineQuery.

# Defined in

Query.ts:112


# 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

Name Type Description
component Component<Object, Metadata, undefined> Component to apply this query fragment to.
depth number Max depth in the relationship chain to traverse.

# Returns

ProxyExpandQueryFragment

query fragment to be used in runQuery or defineQuery.

# Defined in

Query.ts:159


# 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

Name Type Description
component Component<Object, Metadata, undefined> Component this query fragment refers to.
depth number Max depth in the relationship chain to traverse.

# Returns

ProxyReadQueryFragment

query fragment to be used in runQuery or defineQuery.

# Defined in

Query.ts:137


# clearLocalCache

clearLocalCache(component, uniqueWorldIdentifier?): void

# Parameters

Name Type
component Component<Schema, Metadata, undefined>
uniqueWorldIdentifier? string

# Returns

void

# Defined in

Component.ts:403


# 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

Name Type
S extends Schema
T undefined

# Parameters

Name Type Description
a? Partial<ComponentValue<S, T>> Partial ComponentValue to compare to b
b? ComponentValue<S, T> Component 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:199


# createEntity

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

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

# Parameters

Name Type Description
world World World object this entity should be registered in.
components? [Component<Schema, Metadata, undefined>, ComponentValue<Schema, undefined>][] Array of [Component, ComponentValue] tuples to be added to this entity. (Use withValue to generate these tuples with type safety.)
options? Object | Object 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


# createIndexer

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.

# Type parameters

Name Type
S extends Schema
M extends Metadata
T undefined

# Parameters

Name Type Description
component Component<S, M, T> Component to index.

# Returns

Indexer<S, M, T>

Indexed version of the component.

# Defined in

Indexer.ts:18


# createLocalCache

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

# Type parameters

Name Type
S extends Schema
M extends Metadata
T undefined

# Parameters

Name Type
component Component<S, M, T>
uniqueWorldIdentifier? string

# Returns

Component<S, M, T>

# Defined in

Component.ts:408


# 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

Name Type
components Component<Schema, Metadata, undefined>[]
dispose Function
entities EntityID[]
entityToIndex Map<EntityID, EntityIndex>
getEntityIndexStrict Function
hasEntity Function
registerComponent Function
registerDisposer Function
registerEntity Function

# Defined in

World.ts:13


# 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

Name Type
S extends Schema
M extends Metadata
T undefined

# Parameters

Name Type Description
world World World object this component should be registered onto.
schema S Schema of component values. Uses Type enum as bridge between typescript types and javascript accessible values.
options? Object Optional: { 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


# defineComponentSystem

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

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

# Type parameters

Name Type
S extends Schema

# Parameters

Name Type Description
world World World object this system should be registered in.
component Component<S, Metadata, undefined> Component to whose updates to react.
system Function System function to run when the given component is updated.
options Object Optional: { 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


# 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

Name Type Description
fragments QueryFragment<Schema>[] 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


# defineEnterSystem

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

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

# Parameters

Name Type Description
world World World object this system should be registered in.
query QueryFragment<Schema>[] Enter query to react to.
system Function System function to run when the result of the given enter query changes.
options Object Optional: { 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


# 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

Name Type Description
fragments QueryFragment<Schema>[] 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


# defineExitSystem

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

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

# Parameters

Name Type Description
world World World object this system should be registered in.
query QueryFragment<Schema>[] Exit query to react to.
system Function System function to run when the result of the given exit query changes.
options Object Optional: { 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


# 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

Name Type Description
fragments QueryFragment<Schema>[] Query fragments to execute.
options? Object Optional: { 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. }.

Name Type
matching ObservableSet<EntityIndex>
update$ Observable<ComponentUpdate & Object>

# Defined in

Query.ts:418


# 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

Name Type Description
world World World object this system should be registered in.
observable$ Observable<T> Observable to react to.
system Function System 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


# defineSyncSystem

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

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

# Type parameters

Name Type
T extends Schema

# Parameters

Name Type Description
world World World object this system should be registered in.
query QueryFragment<Schema>[] Result of component is added to all entites matching this query.
component Function Function returning the component to be added to all entities matching the given query.
value Function Function returning the component value to be added to all entities matching the given query.
options Object -
options.runOnInit? boolean -
options.update? boolean -

# Returns

void

# Defined in

System.ts:133


# defineSystem

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

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

# Parameters

Name Type Description
world World World object this system should be registered in.
query QueryFragment<Schema>[] Query to react to.
system Function System function to run when the result of the given query changes.
options Object Optional: { 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


# defineUpdateQuery

defineUpdateQuery(fragments, options?): Observable<ComponentUpdate & Object>

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

# Parameters

Name Type Description
fragments QueryFragment<Schema>[] Query fragments
options? Object -
options.runOnInit? boolean -

# Returns

Observable<ComponentUpdate & Object>

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

# Defined in

Query.ts:536


# defineUpdateSystem

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

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

# Parameters

Name Type Description
world World World object this system should be registered in.
query QueryFragment<Schema>[] Update query to react to.
system Function System function to run when the result of the given update query changes.
options Object Optional: { 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


# 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

Name Type Description
entity EntityIndex Entity to get all child entities for up to the specified depth
component Component<Object, Metadata, undefined> Component to use for the relationship chain.
depth number Depth 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


# getComponentEntities

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

Get a set of all entities of the given component.

# Type parameters

Name Type
S extends Schema
T undefined

# Parameters

Name Type Description
component Component<S, Metadata, T> Component to get all entities from

# Returns

IterableIterator<EntityIndex>

Set of all entities in the given component.

# Defined in

Component.ts:262


# getComponentValue

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.

# Type parameters

Name Type
S extends Schema
T undefined

# Parameters

Name Type Description
component Component<S, Metadata, T> Component to get the value from for the given entity.
entity EntityIndex EntityIndex of the entity to get the value for from the given component.

# Returns

ComponentValue<S, T> | undefined

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

# Defined in

Component.ts:148


# getComponentValueStrict

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.

# Type parameters

Name Type
S extends Schema
T undefined

# Parameters

Name Type Description
component Component<S, Metadata, T> Component to get the value from for the given entity.
entity EntityIndex EntityIndex of the entity to get the value for from the given component.

# Returns

ComponentValue<S, T>

Value of the given entity in the given component.

# Defined in

Component.ts:176


# getEntitiesWithValue

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

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

# Type parameters

Name Type
S extends Schema

# Parameters

Name Type Description
component Component<S, Metadata, undefined> | Indexer<S, Metadata, undefined> Component to get entities with the given value from.
value Partial<ComponentValue<S, undefined>> look for entities with this ComponentValue.

# Returns

Set<EntityIndex>

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

# Defined in

Component.ts:236


# 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

Name Type Description
world World World object the given entity is registered on.
entity EntityIndex EntityIndex 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


# hasComponent

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

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

# Type parameters

Name Type
S extends Schema
T undefined

# Parameters

Name Type Description
component Component<S, Metadata, T> Component to check whether it has a value for the given entity.
entity EntityIndex EntityIndex 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:132


# isArrayType

isArrayType(t): t is ArrayType

# Parameters

Name Type
t Type

# Returns

t is ArrayType

# Defined in

types.ts:225


# isComponentUpdate

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

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

# Type parameters

Name Type
S extends Schema

# Parameters

Name Type Description
update ComponentUpdate<Schema, undefined> Component update to infer the type of.
component Component<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


# isEntityType

isEntityType(t): t is EntityType

# Parameters

Name Type
t Type

# Returns

t is EntityType

# Defined in

types.ts:242


# 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

Name Type
S extends Schema

# Parameters

Name Type
component Component<S, Metadata, undefined>
value Partial<ComponentValue<S, undefined>>

# Returns

value is ComponentValue<S, undefined>

# Defined in

utils.ts:63


# isIndexer

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

Helper function to check whether a given component is indexed.

# Type parameters

Name Type
S extends Schema

# Parameters

Name Type
c Component<S, Metadata, undefined> | Indexer<S, Metadata, undefined>

# Returns

c is Indexer<S, Metadata, undefined>

# Defined in

utils.ts:53


# isNumberType

isNumberType(t): t is NumberType

# Parameters

Name Type
t Type

# Returns

t is NumberType

# Defined in

types.ts:237


# isOptionalType

isOptionalType(t): t is OptionalType

# Parameters

Name Type
t Type

# Returns

t is OptionalType

# Defined in

types.ts:206


# 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

Name Type Description
world Object World to create a new namespace for.
world.components Component<Schema, Metadata, undefined>[] -
world.dispose Function -
world.entities EntityID[] -
world.entityToIndex Map<EntityID, EntityIndex> -
world.getEntityIndexStrict Function -
world.hasEntity Function -
world.registerComponent Function -
world.registerDisposer Function -
world.registerEntity Function -
namespace string String descriptor of the new namespace.

# Returns

Object

World with a new namespace.

Name Type
components Component<Schema, Metadata, undefined>[]
dispose Function
entities EntityID[]
entityToIndex Map<EntityID, EntityIndex>
getEntityIndexStrict Function
hasEntity Function
registerComponent Function
registerDisposer Function
registerEntity Function

# Defined in

World.ts:78


# overridableComponent

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.

# Type parameters

Name Type
S extends Schema
M extends Metadata
T undefined

# Parameters

Name Type Description
component Component<S, M, T> Component to use as underlying source for the overridable component

# Returns

OverridableComponent<S, M, T>

overridable component

# Defined in

Component.ts:282


# removeComponent

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

Remove a given entity from a given component.

# Type parameters

Name Type
S extends Schema
M extends Metadata
T T

# Parameters

Name Type Description
component Component<S, M, T> Component to be updated.
entity EntityIndex EntityIndex of the entity whose value should be removed from this component.

# Returns

void

# Defined in

Component.ts:114


# 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

Name Type Description
fragments QueryFragment<Schema>[] 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


# 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

Name Type
S extends Schema
T undefined

# Parameters

Name Type Description
component Component<S, Metadata, T> Component to be updated.
entity EntityIndex EntityIndex of the entity whose value in the given component should be set.
value ComponentValue<S, T> Value to set, schema must match the component schema.

# Returns

void

# Defined in

Component.ts:71


# toUpdate

toUpdate<S>(entity, component): ComponentUpdate<S, undefined> & Object

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

# Type parameters

Name Type
S extends Schema

# Parameters

Name Type Description
entity EntityIndex Entity to create the component update for.
component Component<S, Metadata, undefined> Component to create the component update for.

# Returns

ComponentUpdate<S, undefined> & Object

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

# Defined in

utils.ts:27


# toUpdateStream

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

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

# Type parameters

Name Type
S extends Schema

# Parameters

Name Type Description
component Component<S, Metadata, undefined> Component to create update stream for.

# Returns

UnaryFunction<Observable<EntityIndex>, Observable<ComponentUpdate<S, undefined> & Object>>

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

# Defined in

utils.ts:44


# updateComponent

updateComponent<S, T>(component, entity, value): 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

Name Type
S extends Schema
T undefined

# Parameters

Name Type Description
component Component<S, Metadata, T> Component to be updated.
entity EntityIndex EntityIndex of the entity whose value in the given component should be updated.
value Partial<ComponentValue<S, T>> Partial value to be set, remaining keys will be taken from the existing component value.

# Returns

void

# Defined in

Component.ts:99


# withValue

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

# Type parameters

Name Type
S extends Schema
T undefined

# Parameters

Name Type Description
component Component<S, Metadata, T> Component with ComponentSchema S
value ComponentValue<S, T> ComponentValue with ComponentSchema S

# Returns

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

Tuple [component, value]

# Defined in

Component.ts:222