Entities · class

World

Explained in Entities.

class World implements CursorHost
import { World } from '@driftengine/entities';

Constructor

new

constructor(options?: EntityAllocatorOptions)
ParameterTypeDescription
options?EntityAllocatorOptions

Accessors

NameTypeDescription
liveCountgetnumber
cursorsInUsegetnumberHow many cursors are inside a loop. For a consumer looking at a leak rather than inferring one.

Methods

create

create(): Entity

alive

alive(entity: Entity): boolean
ParameterTypeDescription
entityEntity

destroy

destroy(entity: Entity): boolean

Destroy an entity and sweep it out of every store.

ParameterTypeDescription
entityEntity
More

Every store, not the ones it is known to be in: a world keeps no per-entity list of its components, because that list is a second description of what the stores already know and it would be the thing that goes stale. The sweep is one remove per registered type, which is a number of component types rather than of entities.

count

count(type: ComponentType): number

How many entities carry a component.

ParameterTypeDescription
typeComponentType

at

at(type: ComponentType, index: number): Entity

The entity at index among those carrying a component, or -1 past the end.

ParameterTypeDescription
typeComponentType
indexnumber
More

The order is the store's: insertion, modified by swap-removal, so it is a walk and not an identity, and an index held across a removal names a different entity.

store

store(type: ComponentType): ComponentStore

The store for a component type, made on first ask.

ParameterTypeDescription
typeComponentType

view

view(type: ComponentType): ComponentView

The live columns of a component, for a caller indexing them directly.

ParameterTypeDescription
typeComponentType
More

Unenforced, and that is not an oversight: a world outside a system has no declarations to enforce against. Inside one, go through SystemView.view, which checks first — see the note there for what happens if anything routes around it.

add

add(entity: Entity, type: ComponentType, values?: Readonly<Record<string, unknown>>): void
ParameterTypeDescription
entityEntity
typeComponentType
values?Readonly<Record<string, unknown>>

remove

remove(entity: Entity, type: ComponentType): boolean
ParameterTypeDescription
entityEntity
typeComponentType

has

has(entity: Entity, type: ComponentType): boolean
ParameterTypeDescription
entityEntity
typeComponentType

read

read(entity: Entity, type: ComponentType, field: string): unknown
ParameterTypeDescription
entityEntity
typeComponentType
fieldstring

write

write(entity: Entity, type: ComponentType, field: string, value: unknown): void
ParameterTypeDescription
entityEntity
typeComponentType
fieldstring
valueunknown

query

query(a: ComponentType, b?: ComponentType, c?: ComponentType, d?: ComponentType): QueryCursor

Everything that has all of these components.

ParameterTypeDescription
aComponentType
b?ComponentType
c?ComponentType
d?ComponentType
More

The cursor is borrowed and is given back when the loop ends — including when it breaks, which for…of reports through the iterator's return. A caller that keeps the result past its loop gets whatever the next query writes into it; see query.ts.

releaseCursor

releaseCursor(cursor: QueryCursor): void

Called by a cursor when its loop ends, including when the loop breaks. Not for a consumer.

ParameterTypeDescription
cursorQueryCursor

saveInto

saveInto(slot: WorldSnapshot): void

Write this world's whole state into a slot. See WorldSnapshot for why this is not a save.

ParameterTypeDescription
slotWorldSnapshot
More

Every store, and the slot keeps one for each. A store is never removed from a world, so a later restore always finds the stores this save described still present — which is why nothing here has to record a component type, only its id.

loadFrom

loadFrom(slot: WorldSnapshot): void

Put this world back to a saved slot.

ParameterTypeDescription
slotWorldSnapshot
More

A store the slot does not mention is emptied rather than skipped. Such a store was created after the save — by a query, or by something adding a component the world had never seen — and leaving its contents alone would leave components attached to entities the restored allocator says do not exist. Emptying it is what the snapshot actually claims.

The cursor pool is untouched: a borrowed cursor belongs to a loop that is running, and a rewind happens between ticks.