@latticexyz/recs
@latticexyz/recs
Table of contents
Enumerations
Interfaces
Type Aliases
- 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
Variables
Functions
- 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
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
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 | 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
Name | Type |
---|---|
S | extends Schema = Schema |
T | undefined |
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
Name | Type |
---|---|
T | extends 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
Name | Type |
---|---|
T | extends Schema |
Type declaration
Name | Type |
---|---|
component | Component <T > |
type | Has |
Defined in
types.ts:131 (opens in a new tab)
HasValueQueryFragment
Ƭ HasValueQueryFragment<T
>: Object
Type parameters
Name | Type |
---|---|
T | extends Schema |
Type declaration
Name | Type |
---|---|
component | Component <T > |
type | HasValue |
value | Partial <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
Name | Type |
---|---|
S | extends Schema |
M | extends Metadata = Metadata |
T | undefined |
Defined in
types.ts:91 (opens in a new tab)
Layer
Ƭ Layer: Object
Type declaration
Name | Type |
---|---|
components | Record <string , Component <Schema >> |
world | World |
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
Name | Type |
---|---|
T | extends Schema |
Type declaration
Name | Type |
---|---|
component | Component <T > |
type | Not |
Defined in
types.ts:142 (opens in a new tab)
NotValueQueryFragment
Ƭ NotValueQueryFragment<T
>: Object
Type parameters
Name | Type |
---|---|
T | extends Schema |
Type declaration
Name | Type |
---|---|
component | Component <T > |
type | NotValue |
value | Partial <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
Name | Type |
---|---|
S | extends Schema = Schema |
M | extends Metadata = Metadata |
T | undefined |
Defined in
types.ts:193 (opens in a new tab)
Override
Ƭ Override<S
, T
>: Object
Type parameters
Name | Type |
---|---|
S | extends Schema |
T | undefined |
Type declaration
Name | Type |
---|---|
entity | EntityIndex |
value | Partial <ComponentValue | null |
Defined in
types.ts:185 (opens in a new tab)
ProxyExpandQueryFragment
Ƭ ProxyExpandQueryFragment: Object
Type declaration
Name | Type |
---|---|
component | Component <{ value : Entity }> |
depth | number |
type | ProxyExpand |
Defined in
types.ts:159 (opens in a new tab)
ProxyReadQueryFragment
Ƭ ProxyReadQueryFragment: Object
Type declaration
Name | Type |
---|---|
component | Component <{ value : Entity }> |
depth | number |
type | ProxyRead |
Defined in
types.ts:153 (opens in a new tab)
QueryFragment
Ƭ QueryFragment<T
>: HasQueryFragment
<T
> | HasValueQueryFragment
<T
> | NotQueryFragment
<T
> | NotValueQueryFragment
| ProxyReadQueryFragment
| ProxyExpandQueryFragment
Type parameters
Name | Type |
---|---|
T | extends 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
Name | Type |
---|---|
C | extends 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
Name | Type |
---|---|
T | undefined |
Type declaration
Name | Type |
---|---|
0 | boolean |
1 | number |
10 | bigint [] | undefined |
11 | string [] |
12 | string [] | undefined |
13 | EntityID |
14 | EntityID | undefined |
15 | EntityID [] |
16 | EntityID [] | undefined |
17 | T |
18 | T | undefined |
2 | number | undefined |
3 | bigint |
4 | bigint | undefined |
5 | string |
6 | string | undefined |
7 | number [] |
8 | number [] | undefined |
9 | bigint [] |
Defined in
types.ts:36 (opens in a new tab)
World
Ƭ World: Object
Type of World returned by createWorld.
Type declaration
Name | Type |
---|---|
components | Component [] |
dispose | () => void |
entities | EntityID [] |
entityToIndex | Map <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
Name | Type |
---|---|
T | extends Schema |
Parameters
Name | Type | Description |
---|---|---|
component | Component <T , Metadata , undefined > | Component this query fragment refers to. |
Returns
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
Name | Type |
---|---|
T | extends Schema |
Parameters
Name | Type | Description |
---|---|---|
component | Component <T , Metadata , undefined > | Component this query fragment refers to. |
value | Partial <ComponentValue | Only include entities with this (partial) component value from the result. |
Returns
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
Name | Type |
---|---|
T | extends Schema |
Parameters
Name | Type | Description |
---|---|---|
component | Component <T , Metadata , undefined > | Component this query fragment refers to. |
Returns
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
Name | Type |
---|---|
T | extends Schema |
Parameters
Name | Type | Description |
---|---|---|
component | Component <T , Metadata , undefined > | Component this query fragment refers to. |
value | Partial <ComponentValue | Exclude entities with this (partial) component value from the result. |
Returns
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
Name | Type | Description |
---|---|---|
component | Component <{ value : Entity }, Metadata , undefined > | Component to apply this query fragment to. |
depth | number | Max depth in the relationship chain to traverse. |
Returns
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
Name | Type | Description |
---|---|---|
component | Component <{ value : Entity }, Metadata , undefined > | Component this query fragment refers to. |
depth | number | Max depth in the relationship chain to traverse. |
Returns
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
Name | Type |
---|---|
component | Component <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
Name | Type |
---|---|
S | extends Schema |
T | undefined |
Parameters
Name | Type | Description |
---|---|---|
a? | Partial <ComponentValue | Partial ComponentValue to compare to b |
b? | ComponentValue | 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: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
Name | Type | Description |
---|---|---|
world | World | World 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
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
Name | Type |
---|---|
S | extends Schema |
M | extends Metadata |
T | undefined |
Parameters
Name | Type | Description |
---|---|---|
component | Component <S , M , T > | Component to index. |
Returns
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
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: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
Name | Type |
---|---|
components | Component <Schema , Metadata , undefined >[] |
dispose | (namespace? : string ) => void |
entities | EntityID [] |
entityToIndex | Map <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
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 (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
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 | (update : ComponentUpdate void | 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 (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
Name | Type | Description |
---|---|---|
fragments | QueryFragment [] | 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
Name | Type | Description |
---|---|---|
world | World | World object this system should be registered in. |
query | QueryFragment [] | Enter query to react to. |
system | (update : ComponentUpdate void | 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 (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
Name | Type | Description |
---|---|---|
fragments | QueryFragment [] | 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
Name | Type | Description |
---|---|---|
world | World | World object this system should be registered in. |
query | QueryFragment [] | Exit query to react to. |
system | (update : ComponentUpdate void | 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 (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
Name | Type | Description |
---|---|---|
fragments | QueryFragment [] | 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 & { 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
Name | Type | Description |
---|---|---|
world | World | World object this system should be registered in. |
observable$ | Observable <T > | Observable to react to. |
system | (event : T ) => void | 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 (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
Name | Type |
---|---|
T | extends Schema |
Parameters
Name | Type | Description |
---|---|---|
world | World | World object this system should be registered in. |
query | QueryFragment [] | Result of component is added to all entites matching this query. |
component | (entity : EntityIndex ) => Component | Function returning the component to be added to all entities matching the given query. |
value | (entity : EntityIndex ) => ComponentValue | 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 (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
Name | Type | Description |
---|---|---|
world | World | World object this system should be registered in. |
query | QueryFragment [] | Query to react to. |
system | (update : ComponentUpdate void | 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 (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
Name | Type | Description |
---|---|---|
fragments | QueryFragment [] | 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
Name | Type | Description |
---|---|---|
world | World | World object this system should be registered in. |
query | QueryFragment [] | Update query to react to. |
system | (update : ComponentUpdate void | 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 (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
Name | Type | Description |
---|---|---|
entity | EntityIndex | Entity to get all child entities for up to the specified depth |
component | Component <{ value : Entity }, 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 (opens in a new tab)
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: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
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
| 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
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
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
Name | Type |
---|---|
S | extends Schema |
Parameters
Name | Type | Description |
---|---|---|
component | Component <S , Metadata , undefined > | Indexer | Component to get entities with the given value from. |
value | Partial <ComponentValue | look 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
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
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
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:162 (opens in a new tab)
isArrayType
▸ isArrayType(t
): t is ArrayType
Parameters
Name | Type |
---|---|
t | Type |
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
Name | Type |
---|---|
S | extends Schema |
Parameters
Name | Type | Description |
---|---|---|
update | ComponentUpdate | 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 (opens in a new tab)
isEntityType
▸ isEntityType(t
): t is EntityType
Parameters
Name | Type |
---|---|
t | Type |
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
Name | Type |
---|---|
S | extends Schema |
Parameters
Name | Type |
---|---|
component | Component <S , Metadata , undefined > |
value | Partial <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
Name | Type |
---|---|
S | extends Schema |
Parameters
Name | Type |
---|---|
c | Component <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
Name | Type |
---|---|
t | Type |
Returns
t is NumberType
Defined in
types.ts:249 (opens in a new tab)
isOptionalType
▸ isOptionalType(t
): t is OptionalType
Parameters
Name | Type |
---|---|
t | Type |
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
Name | Type | Description |
---|---|---|
world | Object | World to create a new namespace for. |
world.components | Component <Schema , Metadata , undefined >[] | - |
world.dispose | (namespace? : string ) => void | - |
world.entities | EntityID [] | - |
world.entityToIndex | Map <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 | - |
namespace | string | String descriptor of the new namespace. |
Returns
Object
World with a new namespace.
Name | Type |
---|---|
components | Component <Schema , Metadata , undefined >[] |
dispose | () => void |
entities | EntityID [] |
entityToIndex | Map <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
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
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
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: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
Name | Type | Description |
---|---|---|
fragments | QueryFragment [] | 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
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 | Value 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
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
& { 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
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
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
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 | Partial 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
Name | Type |
---|---|
S | extends Schema |
T | undefined |
Parameters
Name | Type | Description |
---|---|---|
component | Component <S , Metadata , T > | Component with ComponentSchema S |
value | ComponentValue | ComponentValue with ComponentSchema S |
Returns
[Component
<S
, Metadata
, T
>, ComponentValue
]
Tuple [component, value]