World

Defined in: ecs/world.ts:131

The entity store, as GetWorld() hands it to a system — the escape hatch for work the declared parameters cannot express. Prefer Query/Res/Commands: those declare their access, so the scheduler can see it and the cache can serve them. The frozen surface here is what a game does with entities; what the frame runner, the query cache and the editor’s projection need is @internal.

Constructors

Constructor

new World(): World

Returns

World

Methods

despawn()

despawn(entity): void

Defined in: ecs/world.ts:256

Destroy entity and its whole subtree — children before parents, so none is left orphaned and still drawing. Already-gone entities are ignored, and as with spawn this throws during query iteration.

Parameters

entity

number

Returns

void

entityCount()

entityCount(): number

Defined in: ecs/world.ts:368

How many entities exist.

Returns

number

findEntityByName()

findEntityByName(name): number | null

Defined in: ecs/world.ts:887

The entity with this Name, or null. Names are not identities — with two matches, which one comes back is not defined.

Parameters

name

string

Returns

number | null

get()

get<C>(entity, component): ComponentData<C>

Defined in: ecs/world.ts:758

The component’s value, to READ. Writing to the result is deprecated: it stores nothing for an engine-backed component and changes a script one with nothing observing it — use update, set or Mut(). Asking for a component the entity lacks throws; tryGet allows it.

Type Parameters

C

C extends AnyComponentDef

Parameters

entity

number

component

C

Returns

ComponentData<C>

getAllEntities()

getAllEntities(): number[]

Defined in: ecs/world.ts:475

Every entity, in storage order — which is the order queries walk and, within a sorting layer, the order the renderer draws. A fresh array.

Returns

number[]

getComponentTypes()

getComponentTypes(entity): string[]

Defined in: ecs/world.ts:962

The names of every component on entity — for inspectors and diagnostics; a system asks has about the definitions it knows.

Parameters

entity

number

Returns

string[]

getEntitiesWithComponents()

getEntitiesWithComponents(components, withFilters?, withoutFilters?): readonly number[]

Defined in: ecs/world.ts:1029

Entities carrying every component in components, narrowed by with and without. Answered from the query cache, so calling it every frame is the intended use; the array is the cache’s own and must not be mutated.

Parameters

Returns

readonly number[]

has()

has(entity, component): boolean

Defined in: ecs/world.ts:766

Whether entity carries component.

Parameters

entity

number

component

AnyComponentDef

Returns

boolean

insert()

insert<C>(entity, component, data?): ComponentData<C>

Defined in: ecs/world.ts:640

Add component to entity, with data merged over the component’s defaults, and answer the stored value. Adding one that is already there replaces it.

Type Parameters

C

C extends AnyComponentDef

Parameters

entity

number

component

C

data?

Partial<ComponentData<C>>

Returns

ComponentData<C>

isStale()

isStale(entity): boolean

Defined in: ecs/world.ts:360

True if entity refers to a slot that has been recycled — its index is currently live, but held by a different generation. Useful for diagnostic logs: valid() alone can’t distinguish “never existed” from “was despawned and its slot reassigned” since both return false.

Parameters

entity

number

Returns

boolean

onDespawn()

onDespawn(callback): () => void

Defined in: ecs/world.ts:340

Run callback whenever an entity is destroyed, once per entity in a subtree teardown; the returned function unsubscribes. This is the hook a per-entity side table is cleaned up from.

Parameters

callback

(entity) => void

Returns

() => void

onSpawn()

onSpawn(callback): () => void

Defined in: ecs/world.ts:327

Run callback whenever an entity is created; the returned function unsubscribes. A throw is logged and swallowed, so one bad listener cannot stop the others or the spawn itself.

Parameters

callback

(entity) => void

Returns

() => void

remove()

remove(entity, component): void

Defined in: ecs/world.ts:805

Take component off entity. Throws during query iteration, as spawn does.

Parameters

entity

number

component

AnyComponentDef

Returns

void

removeParent()

removeParent(entity): void

Defined in: ecs/world.ts:556

Detach entity from its parent, leaving its own children attached to it.

Parameters

entity

number

Returns

void

set()

set<C>(entity, component, data): void

Defined in: ecs/world.ts:654

Store a whole component value and stamp the change tick a Changed filter reads. Insert-or-replace: an entity that lacks the component gets it.

Type Parameters

C

C extends AnyComponentDef

Parameters

entity

number

component

C

data

ComponentData<C>

Returns

void

setParent()

setParent(child, parent): void

Defined in: ecs/world.ts:542

Make child a child of parent. This is the side to write — the engine keeps Parent and Children in step from here, and a transform composes against whatever this names.

Parameters

child

number

parent

number

Returns

void

spawn()

spawn(name?): number

Defined in: ecs/world.ts:198

Create an entity with no components. Throws during query iteration — mutating the set a query is walking is what Commands exists to defer.

Parameters

name?

string

Returns

number

tryGet()

tryGet<C>(entity, component): ComponentData<C> | null

Defined in: ecs/world.ts:780

get, answering null instead of throwing when the component is absent. Reading only, on the same terms — writing to the result is deprecated; update is the edit.

Type Parameters

C

C extends AnyComponentDef

Parameters

entity

number

component

C

Returns

ComponentData<C> | null

update()

update<C>(entity, component, edit): void

Defined in: ecs/world.ts:716

Edit a component in place and report the change — the write path for “read it, adjust a field, keep the rest”. The draft is BORROWED for the call, and for a script component it IS the stored object, so nothing may keep it. Reporting is unconditional; a false positive costs one look.

Type Parameters

C

C extends AnyComponentDef

Parameters

entity

number

component

C

edit

(draft) => void

Returns

void

Throws

if entity does not carry component.

valid()

valid(entity): boolean

Defined in: ecs/world.ts:350

Whether entity currently exists. False for one never spawned and for a despawned one alike — isStale tells the two apart.

Parameters

entity

number

Returns

boolean