A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file world.ts
* @brief ECS World with C++ Registry integration
*/
import { WasmModuleAborted } from '../wasm/moduleHealth';
import { Entity, entityGeneration, entityIndex, makeEntity, INVALID_ENTITY } from '../types';
import { AnyComponentDef, ComponentDef, ComponentData, BuiltinComponentDef, isBuiltinComponent, mergeIntoDefaults, builtinComponentRegistry, extraBuiltinComponentRegistry, getUserComponents, getComponent, Disabled, Name, Parent, Children, type ParentData, type ChildrenData } from './component';
import type { CppRegistry, ESEngineModule } from '../wasm';
import { handleWasmError } from '../wasm/wasmError';
import { BuiltinBridge, builtinFromWasm, numberListFieldsOf, convertForWasm, type BridgeConnectOptions,
type BuiltinMethods, type CompositionDelta } from './bridge/BuiltinBridge';
import { ScriptStorage } from './ScriptStorage';
import type { PoolMemory, ScriptPool } from './ScriptPool';
import { NameIndex } from './NameIndex';
import { ChangeTracker } from './ChangeTracker';
import { QueryCache, type QueryCacheStats } from './QueryCache';
import { rankByOrder, reorderMapByRank } from './entityOrder';
import { worldEngineApi } from './bridge/engineApi';
import { registerEngineStampFlush } from './engineStamps';
import { withScratch } from '../wasm/wasmScratch';
import { log } from '../util/logger';
import { hasOwn } from '../util/ownProperties';
import { getDefaultContext, type EditorBridge } from './context';
/** The slice of a core {@link World.applyEntityOrder} needs: the entry point plus
* the heap it marshals the entity list through (wasm memory on the web, the
* host's arena on a device — the writes are identical either way). */
interface EntityOrderCore {
renderer_setEntityDrawOrder?(registry: CppRegistry, entitiesPtr: number, count: number): void;
_malloc?(bytes: number): number;
_free?(ptr: number): void;
HEAPU32?: Uint32Array;
}
function editorBridge(): EditorBridge | null {
return getDefaultContext().editorBridge;
}
function notifyBridge<K extends keyof EditorBridge>(
method: K,
...args: Parameters<NonNullable<EditorBridge[K]>>
): void {
const bridge = editorBridge();
if (!bridge) return;
const fn = bridge[method] as ((...a: unknown[]) => void) | undefined;
if (typeof fn !== 'function') return;
try {
fn.apply(bridge, args as unknown[]);
} catch (e) {
log.warn('world', `EditorBridge.${String(method)} threw`, e);
}
}
export { PTR_LAYOUTS } from '../wasm/ptrLayouts.generated';
export { BuiltinBridge } from './bridge/BuiltinBridge';
export type { BuiltinMethods } from './bridge/BuiltinBridge';
// =============================================================================
// Numeric Component IDs for Cache Keys
// =============================================================================
let nextCompNumId_ = 1;
const compNumIds_ = new WeakMap<object, number>();
function getCompNumId(comp: AnyComponentDef): number {
let id = compNumIds_.get(comp);
if (id === undefined) {
id = nextCompNumId_++;
compNumIds_.set(comp, id);
}
return id;
}
const _keyIds: number[] = [];
export function computeQueryCacheKey(
components: AnyComponentDef[],
withFilters: AnyComponentDef[] = [],
withoutFilters: AnyComponentDef[] = [],
filterKey?: string,
): string {
_keyIds.length = 0;
for (const c of components) _keyIds.push(getCompNumId(c));
_keyIds.sort((a, b) => a - b);
let key = _keyIds.join(',');
if (withFilters.length > 0) {
_keyIds.length = 0;
for (const c of withFilters) _keyIds.push(getCompNumId(c));
_keyIds.sort((a, b) => a - b);
key += '|+' + _keyIds.join(',');
}
if (withoutFilters.length > 0) {
_keyIds.length = 0;
for (const c of withoutFilters) _keyIds.push(getCompNumId(c));
_keyIds.sort((a, b) => a - b);
key += '|-' + _keyIds.join(',');
}
if (filterKey) {
key += '|F=' + filterKey;
}
return key;
}
/**
* Predicate-based filter applied after the positive/negative component
* checks. Callers (typically `QueryInstance`) compile an expression tree
* into a `match` closure plus a list of components the tree reads so the
* query cache can invalidate on structural changes to any of them.
*/
export interface QueryFilter {
readonly match: (entity: Entity) => boolean;
readonly deps: readonly AnyComponentDef[];
}
// =============================================================================
// World
// =============================================================================
/** Components whose value feeds the world-transform composition. Hierarchy is
* in here too: a reparent moves a subtree without touching its transforms. */
const COMPOSITION_INPUTS = new Set(['Transform', 'Parent', 'Children']);
/**
* The cache dependencies of a query, Disabled included: switching one entity off
* changes what EVERY query answers. Shared because QueryInstance and the AOT
* plan precompute this set once and would each have to remember.
*/
export function queryDepIds(
components: readonly AnyComponentDef[],
withFilters: readonly AnyComponentDef[],
withoutFilters: readonly AnyComponentDef[],
filterDeps: readonly AnyComponentDef[] = [],
): symbol[] {
const ids: symbol[] = [Disabled._id];
for (const c of components) ids.push(c._id);
for (const c of withFilters) ids.push(c._id);
for (const c of withoutFilters) ids.push(c._id);
for (const c of filterDeps) ids.push(c._id);
return ids;
}
/** @internal Loads the asset paths an engine-backed component was handed; see World.setAssetFieldResolver. */
export type AssetFieldResolver = (entity: Entity, component: AnyComponentDef, authored: Record<string, unknown>) => void;
/**
* 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`.
*
* @public
*/
export class World {
private readonly builtin_ = new BuiltinBridge();
private readonly scripts_ = new ScriptStorage();
private readonly names_ = new NameIndex();
/** @internal */
readonly changes_ = new ChangeTracker();
/** @internal */
readonly queries_ = new QueryCache();
/** @see inactiveEntities_ */
private inactive_: { set: Set<Entity> } | null = null;
private inactiveVersion_ = -1;
private coreActivityEpoch_ = -1;
private readonly coreDisconnect_ = new Set<() => void>();
private entities_ = new Map<Entity, number>();
private indexGeneration_ = new Map<number, number>(); // index -> current generation (for isStale detection)
private iterationDepth_ = 0;
private queryCostEnabled_ = false;
private nextEntityIndex_ = 0; // pure-JS fallback: monotonic index counter
private nextGeneration_ = 0;
private spawnCallbacks_: Array<(entity: Entity) => void> = [];
private despawnCallbacks_: Array<(entity: Entity) => void> = [];
private assetFieldResolver_: AssetFieldResolver | null = null;
private despawning_: Set<Entity> | null = null;
/** @internal */
get builtin(): BuiltinBridge {
return this.builtin_;
}
/**
* Bind this world to an engine core. The embedding contract, not the game
* one: a host instantiates the module and calls this, and everything below
* reaches the same registry through {@link getCppRegistry}.
*
* @internal
*/
connectCpp(
cppRegistry: CppRegistry,
module?: ESEngineModule,
options?: BridgeConnectOptions,
): void {
if (this.getCppRegistry()) this.notifyCoreDisconnect_();
this.addressOf_.clear();
this.builtin_.connect(cppRegistry, module, options);
for (const e of this.scripts_.getStorageById(Disabled._id)?.keys() ?? []) cppRegistry.setEntityEnabled?.(e, false);
this.coreActivityEpoch_ = cppRegistry.activityEpoch?.() ?? -1;
this.queries_.markComponentDirty(Disabled._id);
}
/** @internal */
disconnectCpp(): void {
// What a script wrote is the engine's to know before the engine goes; and the buffer it is handed over in is its heap's.
this.flushEngineStamps();
this.releaseStampBuffer_();
this.notifyCoreDisconnect_();
this.addressOf_.clear();
this.builtin_.disconnect();
this.coreActivityEpoch_ = -1;
this.queries_.markComponentDirty(Disabled._id);
}
/** @internal Whether an engine core is bound — false in a pure-JS world. */
get hasCpp(): boolean {
return this.builtin_.hasCpp;
}
/** @internal */
getCppRegistry(): CppRegistry | null {
return this.builtin_.getCppRegistry();
}
/** @internal Release native leases before the owning core is disconnected. */
onCoreDisconnect(dispose: () => void): () => void {
this.coreDisconnect_.add(dispose);
return () => { this.coreDisconnect_.delete(dispose); };
}
private notifyCoreDisconnect_(): void {
for (const dispose of [...this.coreDisconnect_]) {
try { dispose(); } catch (error) { log.warn('world', 'Core disconnect callback error', error); }
}
}
/** @internal Refresh membership mirrors after an observed native mutation. */
refreshBuiltinMembership(entity: Entity, component: AnyComponentDef): void {
if (!isBuiltinComponent(component) || !this.valid(entity)) return;
const set = this.builtin_.getEntitySet(component._cppName);
const present = this.builtin_.getBuiltinMethods(component._cppName).has(entity);
if (set && set.has(entity) !== present) {
if (present) set.add(entity); else set.delete(entity);
this.queries_.markStructuralChange();
}
this.queries_.markComponentDirty(component._id);
}
/** @internal */
getWasmModule(): ESEngineModule | null {
return this.builtin_.getWasmModule();
}
// =========================================================================
// Entity Management
// =========================================================================
/**
* Create an entity with no components. Throws during query iteration —
* mutating the set a query is walking is what `Commands` exists to defer.
*/
spawn(name?: string): Entity {
if (this.speculation_) {
throw new Error(
'Cannot spawn entity inside a speculation. ' +
'Use its Commands, which allocate no identity until the step commits.'
);
}
if (this.isIterating()) {
throw new Error(
'Cannot spawn entity during query iteration. ' +
'Use Commands to defer entity creation until after iteration completes.'
);
}
const entity = this.allocateEntity_();
this.commitSpawn_(entity, name);
return entity;
}
/**
* @internal An identity for a spawn {@link Commands} will apply later — what
* `cmds.spawn(...).id()` answers while a query is running. Allowed mid-iteration
* because it touches no component storage: a bare id is in no query. The spawn
* itself (name, components, spawn callbacks) happens at
* {@link commitReservedSpawn}, when the commands flush.
*/
reserveEntity(): Entity {
if (this.speculation_) {
throw new Error('Cannot reserve an entity inside a speculation.');
}
return this.allocateEntity_();
}
/** @internal Finish a spawn begun by {@link reserveEntity}. */
commitReservedSpawn(entity: Entity, name?: string): void {
this.commitSpawn_(entity, name);
}
private allocateEntity_(): Entity {
let entity: Entity;
const cppRegistry = this.builtin_.getCppRegistry();
if (cppRegistry) {
try {
entity = cppRegistry.create();
} catch (e) {
handleWasmError(e, 'spawn');
throw e;
}
} else {
// Pure-JS fallback: pack into the same {generation(12) | index(20)}
// layout as C++ so Entity helpers (entityIndex/entityGeneration)
// give consistent results whether or not WASM is connected.
const idx = ++this.nextEntityIndex_;
const gen = (this.indexGeneration_.get(idx) ?? 0);
entity = makeEntity(idx, gen);
}
let generation = 0;
const module = this.builtin_.getWasmModule();
if (module && cppRegistry) {
try {
generation = module.registry_getGeneration(cppRegistry, entity);
} catch { /* fallback to 0 */ }
} else {
generation = ++this.nextGeneration_;
}
this.entities_.set(entity, generation);
this.indexGeneration_.set(entityIndex(entity), entityGeneration(entity));
return entity;
}
private commitSpawn_(entity: Entity, name?: string): void {
this.queries_.markStructuralChange();
if (name !== undefined) {
this.insert(entity, Name, { value: name });
}
for (const cb of this.spawnCallbacks_) {
try { cb(entity); } catch (e) { log.warn('world', 'Spawn callback error', e); }
}
notifyBridge('onEntitySpawned', entity, name);
}
/**
* 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 {@link spawn} this throws during query iteration.
*/
despawn(entity: Entity): void {
if (this.speculation_) {
throw new Error(
'Cannot despawn entity inside a speculation. ' +
'Use its Commands, which apply only if the step commits.'
);
}
if (this.isIterating()) {
throw new Error(
'Cannot despawn entity during query iteration. ' +
'Use Commands to defer entity destruction until after iteration completes.'
);
}
if (!this.valid(entity) || this.despawning_?.has(entity)) return;
const cppRegistry = this.builtin_.getCppRegistry();
if (cppRegistry?.destructionPending?.(entity)) return;
this.despawnSubtree_(entity, cppRegistry);
}
/** Depth-first teardown of `entity` and its descendants (children before parent). */
private despawnSubtree_(entity: Entity, cppRegistry: CppRegistry | null): void {
const reserved = this.despawning_ ??= new Set<Entity>();
const owned: Entity[] = [], nativeOwned: Entity[] = [], postorder: Entity[] = [];
const stack: Array<{ entity: Entity; children: Entity[] | null; next: number }> = [
{ entity, children: null, next: 0 },
];
try {
// Reserve the whole subtree before callbacks run. It cannot escape
// through reparenting, receive new children, or be torn down twice
// by a re-entrant callback. Snapshot each child list just once.
while (stack.length) {
const frame = stack[stack.length - 1];
if (frame.children === null) {
if (!this.valid(frame.entity) || reserved.has(frame.entity)
|| cppRegistry?.destructionPending?.(frame.entity)) { stack.pop(); continue; }
reserved.add(frame.entity); owned.push(frame.entity);
frame.children = this.childEntitiesOf_(frame.entity, true);
}
if (frame.next < frame.children.length) {
stack.push({ entity: frame.children[frame.next++], children: null, next: 0 });
} else {
postorder.push(frame.entity); stack.pop();
}
}
if (cppRegistry && cppRegistry.hasParent(entity)) {
try { cppRegistry.setParent(entity, INVALID_ENTITY); }
catch (e) { handleWasmError(e, `despawn(detach ${entity})`); }
}
// Detach before taking native ownership: setParent also rejects
// reserved entities. The same core guard then protects raw registry
// calls and native teardown invoked from an SDK callback.
if (cppRegistry) {
for (const current of owned) {
if (cppRegistry.reserveDestruction(current)) nativeOwned.push(current);
}
}
for (const current of postorder) if (this.valid(current)) this.despawnOne_(current, cppRegistry);
} finally {
for (const current of nativeOwned) cppRegistry!.releaseDestruction(current);
for (const current of owned) reserved.delete(current);
if (reserved.size === 0) this.despawning_ = null;
}
}
private abortedReported_ = false;
private despawnOne_(entity: Entity, cppRegistry: CppRegistry | null): void {
notifyBridge('onEntityDespawned', entity);
for (const cb of this.despawnCallbacks_) {
try { cb(entity); } catch (e) {
// A module that has aborted fails every callback the same way, and one report says so for all of them.
if (e instanceof WasmModuleAborted) { if (!this.abortedReported_) { this.abortedReported_ = true; log.warn('world', 'Despawn callbacks stopped: the engine module has aborted', e); } continue; }
log.warn('world', 'Despawn callback error', e);
}
}
this.names_.remove(entity);
if (cppRegistry) {
try {
cppRegistry.destroy(entity);
} catch (e) {
handleWasmError(e, `despawn(entity=${entity})`);
}
}
this.entities_.delete(entity);
this.queries_.markStructuralChange();
// Dirty exactly the component versions this entity carried so its
// membership leaves the relevant cached queries — unrelated queries stay
// valid (the query cache no longer honors the global structural version).
for (const cppName of this.builtin_.deleteFromEntitySets(entity)) {
const def = getComponent(cppName);
if (def) {
// Record the removal (no-op unless a Removed query tracks it) so
// Removed(BuiltinComp) fires on despawn, not only on explicit
// remove() — matching the script-component path below.
this.changes_.recordRemoved(def, entity);
this.queries_.markComponentDirty(def._id);
}
}
this.queries_.markComponentDirty(Parent._id);
this.queries_.markComponentDirty(Children._id);
const removedIds = this.scripts_.removeEntity(entity);
for (const id of removedIds) {
this.changes_.recordRemovedById(id, entity);
this.queries_.markComponentDirty(id);
}
}
/**
* 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.
*/
onSpawn(callback: (entity: Entity) => void): () => void {
this.spawnCallbacks_.push(callback);
return () => {
const idx = this.spawnCallbacks_.indexOf(callback);
if (idx !== -1) this.spawnCallbacks_.splice(idx, 1);
};
}
/**
* 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.
*/
onDespawn(callback: (entity: Entity) => void): () => void {
// Copy on subscription changes, so self-unsubscription during a
// notification cannot skip the next observer. Dispatch allocates nothing.
this.despawnCallbacks_ = [...this.despawnCallbacks_, callback];
return () => {
const idx = this.despawnCallbacks_.indexOf(callback);
if (idx !== -1) this.despawnCallbacks_ = this.despawnCallbacks_.filter((_, i) => i !== idx);
};
}
/** Whether `entity` currently exists. False for one never spawned and for a
* despawned one alike — {@link isStale} tells the two apart. */
valid(entity: Entity): boolean {
return this.entities_.has(entity);
}
/** @internal True throughout subtree teardown, including queued ancestors. */
isDestructionPending(entity: Entity): boolean {
return !!this.despawning_?.has(entity)
|| !!this.builtin_.getCppRegistry()?.destructionPending?.(entity);
}
/** Effective activity, including ancestors; unlike valid(), an inactive
* entity remains available for inspection, cleanup and serialization. */
isEntityActive(entity: Entity): boolean {
return this.valid(entity) && !this.inactiveEntities_()?.has(entity);
}
/**
* 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.
*/
isStale(entity: Entity): boolean {
if (this.entities_.has(entity)) return false;
const idx = entityIndex(entity);
const currentGen = this.indexGeneration_.get(idx);
return currentGen !== undefined && currentGen !== entityGeneration(entity);
}
/** How many entities exist. */
entityCount(): number {
return this.entities_.size;
}
/**
* @internal Live sizes of every map the world keeps, for the resource census.
*
* `indexSlots` never shrinks by design — it is keyed by entity INDEX, which
* the registry recycles, so it settles at the session's peak. One that keeps
* climbing means indices are not being reused, which entityCount() cannot show.
*/
getStorageSizes(): {
entities: number;
indexSlots: number;
spawnCallbacks: number;
despawnCallbacks: number;
coreDisconnectCallbacks: number;
names: ReturnType<NameIndex['sizes']>;
scripts: ReturnType<ScriptStorage['sizes']>;
changes: ReturnType<ChangeTracker['sizes']>;
queryCacheEntries: number;
} {
return {
entities: this.entities_.size,
indexSlots: this.indexGeneration_.size,
spawnCallbacks: this.spawnCallbacks_.length,
despawnCallbacks: this.despawnCallbacks_.length,
coreDisconnectCallbacks: this.coreDisconnect_.size,
names: this.names_.sizes(),
scripts: this.scripts_.sizes(),
changes: this.changes_.sizes(),
queryCacheEntries: this.queries_.getStats().size,
};
}
/** @internal Structural version the query cache invalidates against. */
getWorldVersion(): number {
this.syncActivityEpoch_();
return this.queries_.structuralVersion;
}
/** @internal Cumulative query-cache counters (hits, misses, invalidation causes). */
getQueryCacheStats(): QueryCacheStats {
return this.queries_.getStats();
}
/** @internal Reset the query-cache counters. Entries themselves are kept. */
resetQueryCacheStats(): void {
this.queries_.resetStats();
}
/**
* @internal Whether queries count what they scan. Per-World rather than a
* module flag: the editor realm and the play realm are separate Apps in one
* process, and a shared switch would have each turn the other's accounting on.
*/
setQueryCostEnabled(enabled: boolean): void {
this.queryCostEnabled_ = enabled;
}
/** @internal */
get queryCostEnabled(): boolean {
return this.queryCostEnabled_;
}
/** @internal Iteration depth is what makes spawn/despawn refuse mid-query. */
beginIteration(): void {
this.iterationDepth_++;
}
/** @internal */
endIteration(): void {
this.iterationDepth_--;
if (this.iterationDepth_ < 0) {
log.warn('world', 'World.endIteration: mismatched begin/end calls');
this.iterationDepth_ = 0;
}
}
/** @internal Depth is reset rather than unwound when a frame aborts. */
resetIterationDepth(): void {
this.iterationDepth_ = 0;
}
/**
* @internal Set the guard aside for a system suspended at an `await`, and
* give it back when that system resumes.
*
* The depth is the WORLD's, and a system parked mid-query would otherwise
* lend its iteration to whoever runs next: their spawn is refused for an
* iteration that is not theirs, and their reset frees a query still walking.
*/
suspendIteration(): number {
const depth = this.iterationDepth_;
this.iterationDepth_ = 0;
return depth;
}
/** @internal Pairs with {@link suspendIteration}. */
resumeIteration(depth: number): void {
this.iterationDepth_ = depth;
}
/** @internal */
isIterating(): boolean {
return this.iterationDepth_ > 0;
}
/** Every entity, in storage order — which is the order queries walk and,
* within a sorting layer, the order the renderer draws. A fresh array. */
getAllEntities(): Entity[] {
return Array.from(this.entities_.keys());
}
/**
* Reorder the world's storage so every iteration follows `entities`.
*
* Within a sorting layer the renderer draws in the order it walks the ECS —
* so an entity that iterates later lands on top. That order is storage order,
* which a scene gets for free by spawning in its authored order and which this
* re-establishes on a world that is already populated: the picture a reload
* would give, without respawning anything (entity ids, component values and
* every subsystem keyed on them survive untouched).
*
* Entities left out of `entities` keep their relative order after the listed
* ones. Both halves of the world move together — the engine's component pools
* and the JS-side storages the SDK's own queries walk — so an editor's outliner
* drag and a game's "bring this card to the front" mean one thing.
*
* @param entities the desired iteration order (first iterates first, draws first)
*/
/** @internal */
applyEntityOrder(entities: readonly Entity[]): void {
if (entities.length === 0) return;
if (this.isIterating()) {
log.warn('world', 'applyEntityOrder ignored during query iteration');
return;
}
const rankOf = rankByOrder(entities);
// The engine's pools first: it owns the draw path, and its call is the one
// that can fail (no core, or a core built before this entry point existed).
this.pushEntityOrderToCore_(entities);
reorderMapByRank(this.entities_, rankOf);
this.builtin_.reorderEntitySets(rankOf);
this.scripts_.reorderStorages(rankOf);
// Cached query results are entity ARRAYS — their order is now wrong, and no
// component version moved, so drop them wholesale.
this.queries_.invalidateAll();
}
/** Marshal the order to whichever core is connected (see applyEntityOrder). */
private pushEntityOrderToCore_(entities: readonly Entity[]): void {
const cppRegistry = this.builtin_.getCppRegistry();
if (!cppRegistry) return;
const core = worldEngineApi(this) as EntityOrderCore | null;
const push = core?.renderer_setEntityDrawOrder;
if (!core || !push || !core._malloc || !core._free || !core.HEAPU32) return;
try {
withScratch({ _malloc: core._malloc, _free: core._free }, (alloc) => {
const ptr = alloc(entities.length * 4);
// HEAPU32 is re-read here (not captured above): emscripten swaps the
// views out when the heap grows, and _malloc can grow it.
core.HEAPU32!.set(entities as ArrayLike<number>, ptr >> 2);
push.call(core, cppRegistry, ptr, entities.length);
});
} catch (e) {
handleWasmError(e, `applyEntityOrder(count=${entities.length})`);
}
}
/** Keep {@link Parent} and {@link Children} consistent when reparenting. */
setParent(child: Entity, parent: Entity): void {
this.trySetParent(child, parent);
}
/** Reject invalid relationships without changing hierarchy or notifications. */
trySetParent(child: Entity, parent: Entity): boolean {
if (parent === (0xFFFFFFFF as Entity)) parent = INVALID_ENTITY;
if (this.despawning_?.has(child) || this.despawning_?.has(parent)) return false;
if (!this.valid(child) || (parent !== INVALID_ENTITY && !this.valid(parent))) return false;
const cppRegistry = this.builtin_.getCppRegistry();
if (cppRegistry) {
try {
const previous = cppRegistry.hasParent(child) ? cppRegistry.getParent(child).entity : INVALID_ENTITY;
if (previous === parent) {
return !cppRegistry.destructionPending?.(child) && !cppRegistry.destructionPending?.(parent);
}
// New cores return acceptance. A legacy void host remains
// compatible; only an explicit rejection prevents bookkeeping.
if (cppRegistry.setParent(child, parent) === false) return false;
} catch (e) {
handleWasmError(e, `setParent(child=${child}, parent=${parent})`);
return false;
}
}
const linkedParent = parent === INVALID_ENTITY ? null : parent;
this.trackHierarchyWrite_(child, linkedParent);
notifyBridge('onParentChanged', child, linkedParent);
return true;
}
/** Detach `entity` from its parent, leaving its own children attached to it. */
removeParent(entity: Entity): void {
if (this.despawning_?.has(entity)) return;
if (!this.valid(entity)) return;
const cppRegistry = this.builtin_.getCppRegistry();
if (cppRegistry?.destructionPending?.(entity)) return;
if (cppRegistry) {
try {
cppRegistry.removeParent(entity);
} catch (e) {
handleWasmError(e, `removeParent(entity=${entity})`);
}
}
this.trackHierarchyWrite_(entity, null);
notifyBridge('onParentChanged', entity, null);
}
/** `entity`'s children, snapshotted out of the wasm vector that holds them. */
private childEntitiesOf_(entity: Entity, strict = false): Entity[] {
const cppRegistry = this.builtin_.getCppRegistry();
if (!cppRegistry || !cppRegistry.hasChildren(entity)) return [];
const children: Entity[] = [];
try {
// Snapshot then free the wasm VectorEntity (it leaks if left alive).
const vec = cppRegistry.getChildren(entity).entities;
try {
const count = vec.size();
for (let i = 0; i < count; i++) children.push(vec.get(i) as Entity);
} finally { vec.delete(); }
} catch (e) {
handleWasmError(e, `getChildren(entity=${entity})`);
// A partial snapshot is unsafe for deletion: it would remove the
// parent while leaving unread children alive with dangling links.
if (strict) throw e;
}
return children;
}
// Parent/Children are one relationship with two halves, and setParent is the
// only writer that keeps both. Writing either as a component lands here.
private insertHierarchy_(entity: Entity, component: AnyComponentDef, data?: unknown): unknown {
if (component._id === Parent._id) {
const parent = (data as Partial<ParentData> | undefined)?.entity;
if (parent === undefined || parent === INVALID_ENTITY) {
this.removeParent(entity);
return { entity: INVALID_ENTITY };
}
this.setParent(entity, parent);
return this.has(entity, Parent) ? this.get(entity, Parent) : { entity: INVALID_ENTITY };
}
const listed = (data as Partial<ChildrenData> | undefined)?.entities ?? [];
for (const child of listed) this.setParent(child as Entity, entity);
return { entities: this.builtin_.hasCpp ? this.childEntitiesOf_(entity) : [...listed] };
}
private isHierarchyComponent_(component: AnyComponentDef): boolean {
return component._id === Parent._id || component._id === Children._id;
}
// The C++ side owns both halves of the link; these are the JS mirrors that
// has() and the query cache read, so they move with it or the two disagree.
private trackHierarchyWrite_(child: Entity, parent: Entity | null): void {
const parents = this.builtin_.getOrCreateEntitySet(Parent._cppName);
const children = this.builtin_.getOrCreateEntitySet(Children._cppName);
// Re-parenting moves the switched-off closure, so every query's answer can
// change — but ONLY in a world that has something switched off. Charged
// against the tag rather than the hierarchy, which moves on every despawn.
if (this.scripts_.getStorageById(Disabled._id)?.size) {
this.queries_.markComponentDirty(Disabled._id);
}
if (parent === null) {
if (parents.delete(child)) this.changes_.recordRemoved(Parent, child);
} else {
if (!parents.has(child)) {
parents.add(child);
this.changes_.recordAdded(Parent, child);
}
this.recordComponentWrite_(child, Parent);
if (!children.has(parent)) {
children.add(parent);
this.changes_.recordAdded(Children, parent);
}
this.recordComponentWrite_(parent, Children);
}
this.queries_.markStructuralChange();
this.queries_.markComponentDirty(Parent._id);
this.queries_.markComponentDirty(Children._id);
}
// =========================================================================
// Component Management
// =========================================================================
/**
* 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.
*/
insert<C extends AnyComponentDef>(entity: Entity, component: C, data?: Partial<ComponentData<C>>): ComponentData<C> {
this.speculation_?.record(this, entity, component);
if (this.isHierarchyComponent_(component)) {
return this.insertHierarchy_(entity, component, data) as ComponentData<C>;
}
if (isBuiltinComponent(component)) {
const refs = this.takeAssetRefs_(component, data as Record<string, unknown> | undefined);
const merged = this.insertBuiltin_(entity, component, (refs?.clean ?? data) as Partial<ComponentData<C>>) as ComponentData<C>;
if (refs?.authored) this.resolveAssetRefs_(entity, component, refs.authored);
return merged;
}
return this.insertScript_(entity, component as ComponentDef<any>, data) as ComponentData<C>;
}
/**
* 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.
*/
set<C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>): void {
this.speculation_?.record(this, entity, component);
if (this.isHierarchyComponent_(component)) {
this.insertHierarchy_(entity, component, data);
return;
}
if (isBuiltinComponent(component)) {
const refs = this.takeAssetRefs_(component, data as Record<string, unknown>);
if (refs) {
this.set(entity, component, refs.clean as ComponentData<C>);
if (refs.authored) this.resolveAssetRefs_(entity, component, refs.authored);
return;
}
// `set` is insert-or-replace: adding a builtin the entity LACKS must run
// the full structural bookkeeping (entity set + query dirty + recordAdded),
// or the C++ side holds it while queries / has() (entity-set fast path)
// never see it. Route the new case through insert.
if (this.builtin_.hasCpp && !this.has(entity, component)) {
this.insert(entity, component, data as Partial<ComponentData<C>>);
return;
}
if (this.builtin_.hasCpp) {
try {
const defaults = component._default as Record<string, unknown>;
const raw = data as Record<string, unknown>;
let wasmData = raw;
for (const k of Object.keys(raw)) {
if (!hasOwn(defaults, k)) {
if (wasmData === raw) wasmData = { ...raw };
delete wasmData[k];
}
}
// Merged into the defaults one level in, as an add is: a field
// that grew an axis (ParticleEmitter.gravity went vec2 -> vec3)
// still reads the {x, y} a document wrote before it did, where
// embind refused the whole value for its missing `z`.
wasmData = mergeIntoDefaults(defaults, wasmData);
// Through the bridge's own write, so a replace marshals the
// way an add does: a list field crosses as the vector embind
// registered, never as the JS array a document holds.
this.builtin_.replace(entity, component._cppName,
convertForWasm(wasmData, component.colorKeys),
component.entityFields ?? []);
} catch (e) {
handleWasmError(e, `set(${component._name}, entity=${entity})`);
}
}
this.recordComponentWrite_(entity, component);
notifyBridge('onComponentChanged', entity, component._name);
return;
}
// Insert-or-replace means the ADD case owes the same bookkeeping insert
// does, or a warmed query never learns the entity matched. The builtin
// branch above says so; this one did not.
const { isNew } = this.scripts_.set(entity, component as ComponentDef<any>, data);
if (isNew) {
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
this.changes_.recordAdded(component, entity);
notifyBridge('onComponentAdded', entity, component._name);
}
this.recordComponentWrite_(entity, component);
if ((component as ComponentDef<any>)._id === Name._id) {
this.names_.update(entity, (data as { value: string }).value);
}
notifyBridge('onComponentChanged', entity, component._name);
}
/**
* @internal What turns an asset path written into an engine-backed
* component's handle field (`Sprite.texture = 'assets/hero.png'`,
* `MeshRenderer.mesh = 'builtin:cube'`) into the handle. Installed by the
* asset layer on every core; see bindAssetReferenceTracking.
*/
setAssetFieldResolver(resolver: AssetFieldResolver | null): void {
this.assetFieldResolver_ = resolver;
}
/**
* An engine-backed component's asset fields hold handles, and the engine
* cannot store a string there: written straight through, `texture` read
* back as the path while the engine held 0, and nothing drew. A string in
* one is a path to load — the same ref a scene file carries — so it leaves
* the data here (the field takes its default until the load lands) and goes
* to the resolver. An empty string is no path: it names nothing, so it is the
* default and nobody is asked to load it (`authored` is null when that is all
* there was). Sent to the resolver it came back unresolved, was written again
* as a string, and asked for itself for good.
*/
private takeAssetRefs_(
component: AnyComponentDef, data: Record<string, unknown> | undefined,
): { clean: Record<string, unknown>; authored: Record<string, unknown> | null } | null {
const fields = (component as { assetFields?: readonly { field: string }[] }).assetFields;
if (!data || !fields || fields.length === 0) return null;
let clean: Record<string, unknown> | null = null;
let paths = false;
for (const { field } of fields) {
const value = data[field];
if (typeof value !== 'string') continue;
clean ??= { ...data };
clean[field] = (component._default as Record<string, unknown>)[field] ?? 0;
if (value !== '') paths = true;
}
if (!clean) return null;
if (!paths) return { clean, authored: null };
// The resolver is handed the paths only: an empty one beside a real one is already the default above.
const authored: Record<string, unknown> = { ...data };
for (const { field } of fields) if (authored[field] === '') authored[field] = clean[field];
return { clean, authored };
}
private resolveAssetRefs_(entity: Entity, component: AnyComponentDef, authored: Record<string, unknown>): void {
if (this.assetFieldResolver_) {
this.assetFieldResolver_(entity, component, authored);
return;
}
log.warn('world', `${component._name} on entity ${entity} was given an asset path, but this world has no asset layer `
+ 'to load it: the field holds no handle. Load it first (await assets.loadTexture(path)) and write the handle.');
}
/**
* 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.
*
* @throws if `entity` does not carry `component`.
*/
update<C extends AnyComponentDef>(
entity: Entity,
component: C,
edit: (draft: ComponentData<C>) => void,
): void {
if (!this.has(entity, component)) {
throw new Error(
`update(${component._name}, entity=${entity}): the entity does not carry it. `
+ 'Use insert() or set() to add a component.'
);
}
if (isBuiltinComponent(component)) {
// A projection, so the write-back is what stores it; `set` owns that
// for every builtin shape, hierarchy included, and records the change.
const draft = this.builtin_.get(entity, component) as ComponentData<C>;
try {
edit(draft);
} finally {
this.set(entity, component, draft);
}
return;
}
const draft = this.scripts_.get(entity, component as ComponentDef<any>) as ComponentData<C>;
try {
edit(draft);
} finally {
// A throwing `edit` has already written to the live object, so the
// change is reported before the error escapes.
this.recordComponentWrite_(entity, component);
if ((component as ComponentDef<any>)._id === Name._id) {
this.names_.update(entity, (draft as { value: string }).value);
}
notifyBridge('onComponentChanged', entity, component._name);
}
}
/**
* 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 {@link update}, {@link set} or `Mut()`.
* Asking for a component the entity lacks throws; {@link tryGet} allows it.
*/
get<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C> {
this.speculation_?.record(this, entity, component);
if (isBuiltinComponent(component)) {
return this.builtin_.get(entity, component) as ComponentData<C>;
}
return this.scripts_.get(entity, component as ComponentDef<any>) as ComponentData<C>;
}
/** Whether `entity` carries `component`. */
has(entity: Entity, component: AnyComponentDef): boolean {
if (component._builtin) {
if (!this.builtin_.hasCpp) return false;
const cppName = (component as BuiltinComponentDef<any>)._cppName;
const bset = this.builtin_.getEntitySet(cppName);
if (bset) return bset.has(entity);
return this.builtin_.getBuiltinMethods(cppName).has(entity);
}
return this.scripts_.has(entity, component as ComponentDef<any>);
}
/** {@link get}, answering null instead of throwing when the component is
* absent. Reading only, on the same terms — writing to the result is
* deprecated; {@link update} is the edit. */
tryGet<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C> | null {
this.speculation_?.record(this, entity, component);
if (isBuiltinComponent(component)) {
if (!this.builtin_.hasCpp) return null;
const bset = this.builtin_.getEntitySet(component._cppName);
if (bset && !bset.has(entity)) return null;
try {
const methods = this.builtin_.getBuiltinMethods(component._cppName);
if (!bset && !methods.has(entity)) return null;
return builtinFromWasm(methods.get(entity), component) as ComponentData<C>;
} catch (e) {
handleWasmError(e, `tryGet(${component._name}, entity=${entity})`);
return null;
}
}
const storage = this.scripts_.getStorageById(component._id as symbol);
if (!storage) return null;
const val = storage.get(entity);
return val !== undefined ? val as ComponentData<C> : null;
}
/** Take `component` off `entity`. Throws during query iteration, as
* {@link spawn} does. */
remove(entity: Entity, component: AnyComponentDef): void {
this.speculation_?.record(this, entity, component);
if (this.isIterating()) {
throw new Error(
'Cannot remove component during query iteration. ' +
'Use Commands to defer component removal until after iteration completes.'
);
}
if (component._id === Parent._id) {
this.removeParent(entity);
return;
}
if (component._id === Children._id) {
for (const child of this.childEntitiesOf_(entity)) this.removeParent(child);
return;
}
if (isBuiltinComponent(component)) {
this.builtin_.remove(entity, component);
this.changes_.recordRemoved(component, entity);
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
notifyBridge('onComponentRemoved', entity, component._name);
} else {
this.removeScript_(entity, component as ComponentDef<any>);
}
}
// =========================================================================
// Builtin Component Insert (delegates to BuiltinBridge)
// =========================================================================
private insertBuiltin_<T>(entity: Entity, component: BuiltinComponentDef<T>, data?: Partial<T>): T {
const { merged, isNew } = this.builtin_.insert(entity, component, data);
if (isNew) {
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
this.changes_.recordAdded(component, entity);
notifyBridge('onComponentAdded', entity, component._name);
}
this.recordComponentWrite_(entity, component);
notifyBridge('onComponentChanged', entity, component._name);
return merged;
}
// =========================================================================
// Script Component Operations (delegates to ScriptStorage)
// =========================================================================
private insertScript_<T>(entity: Entity, component: ComponentDef<T>, data?: unknown): T {
const { value, isNew } = this.scripts_.insert(entity, component, data);
if (isNew) {
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
this.changes_.recordAdded(component, entity);
notifyBridge('onComponentAdded', entity, component._name);
}
this.recordComponentWrite_(entity, component);
if (component._id === Name._id) {
this.names_.update(entity, (value as { value: string }).value);
}
notifyBridge('onComponentChanged', entity, component._name);
return value;
}
private removeScript_<T>(entity: Entity, component: ComponentDef<T>): void {
if (component._id === Name._id) {
this.names_.remove(entity);
}
this.scripts_.remove(entity, component);
if (component._id === Disabled._id) this.builtin_.getCppRegistry()?.setEntityEnabled?.(entity, true);
this.changes_.recordRemoved(component, entity);
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
notifyBridge('onComponentRemoved', entity, component._name);
}
// =========================================================================
// Name Index
// =========================================================================
/** The entity with this {@link Name}, or null. Names are not identities —
* with two matches, which one comes back is not defined. */
findEntityByName(name: string): Entity | null {
return this.names_.findByName(name);
}
/** @internal Pre-resolve a component to its direct storage/getter for fast iteration. */
resolveGetter(component: AnyComponentDef, mode: 'borrowed' | 'retained' = 'borrowed'):
((entity: Entity) => unknown) | null {
if (isBuiltinComponent(component)) {
if (!this.builtin_.hasCpp) return null;
if (this.builtin_.getWasmModule()) {
const ptrGetter = this.builtin_.resolvePtrGetter(component._cppName, mode);
if (ptrGetter) return ptrGetter;
}
const methods = this.builtin_.getBuiltinMethods(component._cppName);
const plain = component.colorKeys.length === 0 && component.entityFields.length === 0
&& numberListFieldsOf(component._cppName).length === 0;
if (plain) return (e) => methods.get(e);
return (e) => builtinFromWasm(methods.get(e), component);
}
const storage = this.scripts_.getStorageById(component._id);
if (!storage) return null;
return (e) => storage.get(e);
}
/** @internal Pre-resolve a component to a direct has-check for fast query matching. */
resolveHas(component: AnyComponentDef): ((entity: Entity) => boolean) | null {
if (isBuiltinComponent(component)) {
if (!this.builtin_.hasCpp) return null;
const methods = this.builtin_.getBuiltinMethods(component._cppName);
return (e) => methods.has(e);
}
const storage = this.scripts_.getStorageById(component._id);
if (!storage) return null;
return (e) => storage.has(e);
}
/** @internal Pre-resolve a component to a direct setter for fast Mut write-back. */
resolveSetter(component: AnyComponentDef): ((entity: Entity, data: unknown) => void) | null {
if (isBuiltinComponent(component)) {
if (!this.builtin_.hasCpp) return null;
if (this.builtin_.getWasmModule()) {
const ptrSetter = this.builtin_.resolvePtrSetter(component._cppName);
if (ptrSetter) return ptrSetter;
}
const name = component._cppName;
const { colorKeys, entityFields } = component;
if (colorKeys.length === 0 && entityFields.length === 0 && numberListFieldsOf(name).length === 0) {
const methods = this.builtin_.getBuiltinMethods(name);
return (e, d) => methods.add(e, d);
}
// The one marshalled write, as world.set and insert take it: a list field crosses as the vector embind
// registered, never as the JS array a row holds.
return (e, d) => this.builtin_.replace(e, name, convertForWasm(d as Record<string, unknown>, colorKeys), entityFields);
}
// Through ScriptStorage, not into the map: a pooled component's stored
// value is a live view onto its row, and replacing it with a plain
// object would leave the row behind.
const storage = this.scripts_.getStorageById(component._id);
if (!storage) return null;
return (e, d) => { this.scripts_.set(e, component as ComponentDef<any>, d); };
}
// =========================================================================
// Query Support
// =========================================================================
/** @internal Per-frame reuse of the query instance pool. */
resetQueryPool(): void {
// No-op: query pool removed, results stored directly in cache
}
/** The names of every component on `entity` — for inspectors and diagnostics;
* a system asks {@link has} about the definitions it knows. */
getComponentTypes(entity: Entity): string[] {
return this.componentTypes_(entity);
}
/** @internal Inspect a group with one script catalogue index, preserving input order. */
getComponentTypesBatch(entities: readonly Entity[]): string[][] {
if (entities.length === 0) return [];
const scriptNames = new Map<symbol, string>();
for (const [name, def] of getUserComponents()) {
// Match the scalar lookup's first registered name for an id.
if (!scriptNames.has(def._id)) scriptNames.set(def._id, name);
}
return entities.map(entity => this.componentTypes_(entity, scriptNames));
}
private componentTypes_(entity: Entity, scriptNames?: ReadonlyMap<symbol, string>): string[] {
const names = this.builtin_.componentNames(entity);
const types = new Set<string>(names ?? []);
const methods = this.builtin_.getMethodCache();
for (const [name, binding] of names === null ? methods : this.builtin_.getExtraMethodCache()) {
try { if (binding.has(entity)) types.add(name); } catch (e) { log.warn('world', `Component check failed for ${name}`, e); }
}
if (this.builtin_.hasCpp) {
for (const [name, comp] of names === null ? builtinComponentRegistry() : extraBuiltinComponentRegistry()) {
if (isBuiltinComponent(comp) && !methods.has(name)) {
try {
const m = this.builtin_.getBuiltinMethods(comp._cppName);
if (m.has(entity)) types.add(name);
} catch (e) { log.warn('world', `Builtin check failed for ${name}`, e); }
}
}
}
const ids = this.scripts_.getEntityComponentIds(entity);
if (ids) {
const registry = scriptNames ? null : getUserComponents();
for (const id of ids) {
if (scriptNames) {
const name = scriptNames.get(id);
if (name !== undefined) types.add(name);
continue;
}
for (const [name, def] of registry!) {
if (def._id === id) {
types.add(name);
break;
}
}
}
}
return Array.from(types);
}
/**
* Every entity switched off, ITSELF or by an ancestor.
*
* Derived, not tagged down the tree: a scene that wrote the tag on each
* descendant would lose which of them the author switched off. Recomputed
* when the tag or the hierarchy moves; free when nothing is switched off.
*/
private inactiveEntities_(): { has(entity: Entity): boolean } | null {
const core = this.builtin_.getCppRegistry();
if (core?.isEntityActive && core.hasInactiveEntities) {
return core.hasInactiveEntities() ? { has: e => !core.isEntityActive!(e) } : null;
}
const storage = this.scripts_.getStorageById(Disabled._id);
if (!storage || storage.size === 0) return null;
// One version covers both halves: a re-parent in a world that has anything
// switched off bumps the tag's version too (see trackHierarchyWrite_).
const version = this.queries_.componentVersion(Disabled._id);
if (this.inactive_ && this.inactiveVersion_ === version) return this.inactive_.set;
const set = new Set<Entity>();
const walk = (entity: Entity): void => {
if (set.has(entity)) return;
set.add(entity);
if (!this.has(entity, Children)) return;
for (const child of (this.get(entity, Children) as ChildrenData).entities) {
walk(child as Entity);
}
};
for (const entity of storage.keys()) walk(entity as Entity);
this.inactive_ = { set };
this.inactiveVersion_ = version;
return set;
}
private resolveStorages_(
comps: AnyComponentDef[],
scriptOut: Map<Entity, unknown>[],
builtinOut: BuiltinMethods[],
): boolean {
for (const comp of comps) {
if (isBuiltinComponent(comp)) {
if (!this.builtin_.hasCpp) return false;
builtinOut.push(this.builtin_.getBuiltinMethods(comp._cppName));
} else {
const storage = this.scripts_.getStorageById(comp._id);
if (!storage) return false;
scriptOut.push(storage);
}
}
return true;
}
private collectComponentIds_(
components: AnyComponentDef[],
withFilters: AnyComponentDef[],
withoutFilters: AnyComponentDef[],
): symbol[] {
return queryDepIds(components, withFilters, withoutFilters);
}
/**
* 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.
*
* @public
*/
getEntitiesWithComponents(
components: AnyComponentDef[],
withFilters: AnyComponentDef[] = [],
withoutFilters: AnyComponentDef[] = [],
): readonly Entity[] {
return this.queryEntities(components, withFilters, withoutFilters);
}
/**
* @internal The same walk, with the cache key, dependency ids and predicate
* filter supplied by the caller. `QueryInstance` computes those once per
* query so a cache hit allocates nothing — which is why they are not
* parameters of the frozen door above: they are the cache's shape, and
* freezing them would freeze it.
*/
queryEntities(
components: AnyComponentDef[],
withFilters: AnyComponentDef[] = [],
withoutFilters: AnyComponentDef[] = [],
precomputedKey?: string,
filter?: QueryFilter,
precomputedDepIds?: symbol[],
): readonly Entity[] {
this.syncActivityEpoch_();
const cacheKey = precomputedKey ?? computeQueryCacheKey(components, withFilters, withoutFilters);
// The dep-id set is static per query; QueryInstance precomputes it (incl.
// filter deps) so cache-hit iteration allocates nothing here.
let depIds: symbol[];
if (precomputedDepIds) {
depIds = precomputedDepIds;
} else {
depIds = this.collectComponentIds_(components, withFilters, withoutFilters);
if (filter) {
for (const c of filter.deps) depIds.push(c._id);
}
}
// `Disabled`'s whole contract is that the systems skip it, answered once
// here rather than remembered at 78 call sites. A query that NAMES the
// tag is the exception: managing the switch means seeing it.
const namesDisabled = components.includes(Disabled)
|| withFilters.includes(Disabled) || withoutFilters.includes(Disabled);
return this.queries_.getOrCompute(cacheKey, depIds, () => {
const entities: Entity[] = [];
const off = namesDisabled ? null : this.inactiveEntities_();
const reqScript: Map<Entity, unknown>[] = [];
const reqBuiltin: BuiltinMethods[] = [];
if (!this.resolveStorages_(components, reqScript, reqBuiltin)) {
return [];
}
let withScript: Map<Entity, unknown>[] | null = null;
let withBuiltin: BuiltinMethods[] | null = null;
if (withFilters.length > 0) {
withScript = [];
withBuiltin = [];
if (!this.resolveStorages_(withFilters, withScript, withBuiltin)) {
return [];
}
}
let woScript: Map<Entity, unknown>[] | null = null;
let woBuiltin: BuiltinMethods[] | null = null;
if (withoutFilters.length > 0) {
woScript = [];
woBuiltin = [];
this.resolveStorages_(withoutFilters, woScript, woBuiltin);
}
let smallestSet: { keys(): IterableIterator<Entity>; size: number } | null = null;
let smallestSize = Infinity;
for (let i = 0; i < reqScript.length; i++) {
const size = reqScript[i].size;
if (size < smallestSize) {
smallestSize = size;
smallestSet = reqScript[i];
}
}
for (const comp of components) {
if (isBuiltinComponent(comp)) {
const bset = this.builtin_.getEntitySet(comp._cppName);
if (bset && bset.size < smallestSize) {
smallestSize = bset.size;
smallestSet = bset;
}
}
}
const candidates = smallestSet ? smallestSet.keys() : this.entities_.keys();
const rsLen = reqScript.length;
const rbLen = reqBuiltin.length;
for (const entity of candidates) {
if (off?.has(entity)) continue;
let match = true;
for (let i = 0; i < rsLen; i++) {
if (!reqScript[i].has(entity)) { match = false; break; }
}
if (match) {
for (let i = 0; i < rbLen; i++) {
if (!reqBuiltin[i].has(entity)) { match = false; break; }
}
}
if (match && withScript) {
for (let i = 0; i < withScript.length; i++) {
if (!withScript[i].has(entity)) { match = false; break; }
}
if (match) {
for (let i = 0; i < withBuiltin!.length; i++) {
if (!withBuiltin![i].has(entity)) { match = false; break; }
}
}
}
if (match && woScript) {
for (let i = 0; i < woScript.length; i++) {
if (woScript[i].has(entity)) { match = false; break; }
}
if (match) {
for (let i = 0; i < woBuiltin!.length; i++) {
if (woBuiltin![i].has(entity)) { match = false; break; }
}
}
}
if (match && filter && !filter.match(entity)) {
match = false;
}
if (match) {
entities.push(entity);
}
}
return entities;
});
}
// =========================================================================
// Change Detection (delegates to ChangeTracker)
// =========================================================================
/** @internal The frame runner's clock for change detection. */
advanceTick(): void {
this.changes_.advanceTick();
this.flushEngineStamps();
// Once a frame, while the audit is on: the engine compares its components with the copy it kept and counts each one
// whose bytes changed without a change stamp (Registry::auditChanges).
if (this.changeAudit_) this.builtin_.getCppRegistry()?.auditChanges?.();
}
private changeAudit_ = false;
/** Engine type id by component, -1 where the engine has none; dropped when the engine's registry is replaced. */
private readonly engineTypeIds_ = new Map<AnyComponentDef, number>();
private engineTypeIdsFor_: unknown = null;
/** The engine-heap block stamps are handed over in, its room in pairs, and whose heap it is in. */
private stampBuffer_ = 0;
private stampBufferPairs_ = 0;
private stampBufferApi_: ReturnType<typeof worldEngineApi> = null;
private releaseStampBuffer_(): void {
if (this.stampBuffer_ !== 0) this.stampBufferApi_?._free?.(this.stampBuffer_);
this.stampBuffer_ = 0;
this.stampBufferPairs_ = 0;
this.stampBufferApi_ = null;
}
/** (engine type id, entity) pairs waiting to be stamped in the engine; see flushEngineStamps. */
private stampPairs_ = new Uint32Array(2 * 256);
private stampCount_ = 0;
private static readonly STAMP_BATCH = 8192;
/**
* @internal Stamps an engine component as written, in the engine, without telling this world's Changed() queries: what a
* write path deliberately outside them (physics moving bodies) still owes the engine's own readers of changes. Every write
* through set/insert/update/markChanged comes here too. Batched, and handed over by flushEngineStamps.
*/
stampEngineWrite(entity: Entity, component: AnyComponentDef): void {
if (!isBuiltinComponent(component)) return;
const registry = this.builtin_.getCppRegistry();
if (!registry?.componentTypeId) return;
if (this.engineTypeIdsFor_ !== registry) {
this.flushEngineStamps();
this.engineTypeIds_.clear();
this.engineTypeIdsFor_ = registry;
registerEngineStampFlush(registry, () => this.flushEngineStamps());
}
let id = this.engineTypeIds_.get(component);
if (id === undefined) {
id = registry.componentTypeId(component._cppName);
this.engineTypeIds_.set(component, id);
}
if (id < 0) return;
if (this.stampCount_ * 2 >= this.stampPairs_.length) {
const grown = new Uint32Array(this.stampPairs_.length * 2);
grown.set(this.stampPairs_);
this.stampPairs_ = grown;
}
this.stampPairs_[this.stampCount_ * 2] = id;
this.stampPairs_[this.stampCount_ * 2 + 1] = entity as number;
if (++this.stampCount_ >= World.STAMP_BATCH) this.flushEngineStamps();
}
/**
* @internal Hands the batched stamps to the engine: one call where it takes a list (registry_markComponentsChanged), one each
* where it does not. The render pipeline calls it before the frame's transforms are composed, and the frame's tick before the
* audit; anything else in the engine that reads changes has to come after one of the two.
*/
flushEngineStamps(): void {
const count = this.stampCount_;
if (count === 0) return;
this.stampCount_ = 0;
const registry = this.builtin_.getCppRegistry();
if (!registry || registry !== this.engineTypeIdsFor_) return;
const api = worldEngineApi(this);
if (api?.registry_markComponentsChanged && api._malloc && api._free && api.HEAPU32) {
// One block in the engine's heap, kept and grown: a hand-over a frame allocates nothing.
if (this.stampBuffer_ === 0 || this.stampBufferPairs_ < count || this.stampBufferApi_ !== api) {
this.releaseStampBuffer_();
this.stampBufferPairs_ = Math.max(count, 1024);
this.stampBuffer_ = api._malloc(this.stampBufferPairs_ * 8);
this.stampBufferApi_ = api;
}
if (this.stampBuffer_ !== 0) {
// The view is asked for after the allocation: a heap that grew detached the one from before.
api.HEAPU32.set(this.stampPairs_.subarray(0, count * 2), this.stampBuffer_ >>> 2);
api.registry_markComponentsChanged(registry, this.stampBuffer_, count);
return;
}
}
if (!registry.markComponentChanged) return;
for (let i = 0; i < count; i++) registry.markComponentChanged(this.stampPairs_[i * 2]!, this.stampPairs_[i * 2 + 1]!);
}
/**
* @internal Turns on the engine's change audit, for tests and gates: every frame from here on, a component written without
* a change stamp is counted, and its type named in the log the first time. It copies every component once a frame.
*/
setChangeAudit(enabled: boolean): void {
const registry = this.builtin_.getCppRegistry();
registry?.setChangeAudit?.(enabled);
this.changeAudit_ = enabled && typeof registry?.auditChanges === 'function';
}
/** @internal Component writes the audit has found without a change stamp since it was turned on. */
changeAuditTotal(): number {
return this.builtin_.getCppRegistry()?.changeAuditTotal?.() ?? 0;
}
/** @internal */
getWorldTick(): number {
return this.changes_.getWorldTick();
}
/** @internal Opted into by a query that declares an Added/Changed filter;
* tracking every component would cost every write. */
enableChangeTracking(component: AnyComponentDef): void {
this.changes_.enableChangeTracking(component);
}
/** @internal Opt a system query into precise change boundaries, separately from tick sampling. */
enableChangeSequenceTracking(component: AnyComponentDef, added: boolean): void {
this.changes_.enableChangeSequenceTracking(component, added);
}
/** @internal Latest opted-in component mutation sequence. */
getChangeSequence(): number { return this.changes_.getChangeSequence(); }
/** @internal Bind a live sequence index once for a system query's entity loop. */
resolveChangeSequenceMatcher(component: AnyComponentDef, added: boolean): (entity: Entity, after: number) => boolean {
return this.changes_.resolveChangeSequenceMatcher(component, added);
}
/** @internal Live additions after a completed system boundary. */
isAddedAfterSequence(entity: Entity, component: AnyComponentDef, after: number): boolean {
return this.changes_.isAddedAfterSequence(entity, component, after);
}
/** @internal Live changes after a completed system boundary. */
isChangedAfterSequence(entity: Entity, component: AnyComponentDef, after: number): boolean {
return this.changes_.isChangedAfterSequence(entity, component, after);
}
/** @internal O(1) empty-window checks before enumerating system query candidates. */
anyAddedAfterSequence(component: AnyComponentDef, after: number): boolean {
return this.changes_.anyAddedAfterSequence(component, after);
}
/** @internal O(1) empty-window checks before enumerating system query candidates. */
anyChangedAfterSequence(component: AnyComponentDef, after: number): boolean {
return this.changes_.anyChangedAfterSequence(component, after);
}
/** @internal Opt in to live component identities, independent of frame ticks. */
enableIncarnationTracking(component: AnyComponentDef): void {
this.changes_.enableIncarnationTracking(component);
}
/** @internal Changes on remove/reinsert, including multiple edits in one tick.
* Components present before tracking was enabled share the initial identity 0. */
getComponentIncarnation(entity: Entity, component: AnyComponentDef): number {
return this.changes_.getComponentIncarnation(entity, component);
}
/** @internal What `Added`/`Changed` filters are implemented in terms of. */
isAddedSince(entity: Entity, component: AnyComponentDef, sinceTick: number): boolean {
return this.changes_.isAddedSince(entity, component, sinceTick);
}
/** @internal */
isChangedSince(entity: Entity, component: AnyComponentDef, sinceTick: number): boolean {
return this.changes_.isChangedSince(entity, component, sinceTick);
}
/** @internal True if ANY entity changed `component` after `sinceTick` (O(1) gate). */
anyChangedSince(component: AnyComponentDef, sinceTick: number): boolean {
return this.changes_.anyChangedSince(component, sinceTick);
}
/** @internal What a `Removed` query reads. */
getRemovedEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {
return this.changes_.getRemovedEntitiesSince(component, sinceTick);
}
/** @internal A tick-based removal lease for samples after the current tick. */
registerRemovedReader(component: AnyComponentDef): number {
return this.changes_.registerRemovedReader(component);
}
/** @internal A removal lease starting at the current event sequence. */
registerRemovedCursorReader(component: AnyComponentDef): number {
return this.changes_.registerRemovedCursorReader(component);
}
/** @internal Latest removal sequence, independent of frame ticks. */
getRemovalSequence(): number { return this.changes_.getRemovalSequence(); }
/** @internal Unacknowledged removals belonging to this cursor reader. */
getRemovedEntitiesForReader(component: AnyComponentDef, readerId: number): Entity[] {
return this.changes_.getRemovedEntitiesForReader(component, readerId);
}
/** @internal Release only events this run observed, preserving later removals. */
advanceRemovedCursorReader(component: AnyComponentDef, readerId: number, through: number): void {
this.changes_.advanceRemovedCursorReader(component, readerId, through);
}
/** @internal A claim from an explicit tick, for a reader that reads with an
* overlap rather than "since I last ran". */
registerRemovedReaderFrom(component: AnyComponentDef, retainFromTick: number): number {
return this.changes_.registerRemovedReaderFrom(component, retainFromTick);
}
/** @internal That reader is done with everything up to `lastRunTick`. */
advanceRemovedReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {
this.changes_.advanceRemovedReader(component, readerId, lastRunTick);
}
/** @internal The reader is gone; its share of the watermark goes with it. */
disposeRemovedReader(component: AnyComponentDef, readerId: number): void {
this.changes_.disposeRemovedReader(component, readerId);
}
/** @internal How many readers hold `component`'s removal history. */
removedReaderCount(component: AnyComponentDef): number {
return this.changes_.removedReaderCount(component);
}
/** @internal A claim on `component`'s MEMBERSHIP journal — who gained or
* lost it — independent of ordinary change tracking. */
registerTopologyReaderFrom(component: AnyComponentDef, retainFromTick: number): number {
return this.changes_.registerTopologyReaderFrom(component, retainFromTick);
}
/** @internal A mutation cursor distinguishes writes within one world tick. */
registerMutationCursor(component: AnyComponentDef, kind: 'write' | 'topology'): number {
return this.changes_.registerMutationCursor(component, kind);
}
/** @internal Current boundary to acknowledge after a successful read. */
mutationSequence(kind: 'write' | 'topology'): number { return this.changes_.mutationSequence(kind); }
/** @internal Component stamps survive released mutation-history readers. */
mutationRevision(component: AnyComponentDef, kind: 'write' | 'topology'): number {
return this.changes_.mutationRevision(component, kind);
}
/** @internal Unacknowledged component mutations for this reader. */
mutationsForCursor(component: AnyComponentDef, kind: 'write' | 'topology', reader: number): Entity[] {
return this.changes_.mutationsForCursor(component, kind, reader);
}
/** @internal Preserve mutations that arrived after the read's boundary. */
advanceMutationCursor(component: AnyComponentDef, kind: 'write' | 'topology', reader: number, through: number): void {
this.changes_.advanceMutationCursor(component, kind, reader, through);
}
/** @internal Release this reader's history claim. */
disposeMutationCursor(component: AnyComponentDef, kind: 'write' | 'topology', reader: number): void {
this.changes_.disposeMutationCursor(component, kind, reader);
}
/** @internal Entities worth re-reading because their membership moved. */
getTopologyChangedEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {
return this.changes_.getTopologyChangedEntitiesSince(component, sinceTick);
}
/** @internal That reader is done with everything up to `lastRunTick`. */
advanceTopologyReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {
this.changes_.advanceTopologyReader(component, readerId, lastRunTick);
}
/** @internal The reader is gone; its share of the watermark goes with it. */
disposeTopologyReader(component: AnyComponentDef, readerId: number): void {
this.changes_.disposeTopologyReader(component, readerId);
}
/** @internal How many readers hold `component`'s membership journal. */
topologyReaderCount(component: AnyComponentDef): number {
return this.changes_.topologyReaderCount(component);
}
/** @internal A claim on `component`'s WRITE journal — which entities had it
* written, enumerable sparsely, unlike the per-entity changed map. */
registerWriteReaderFrom(component: AnyComponentDef, retainFromTick: number): number {
return this.changes_.registerWriteReaderFrom(component, retainFromTick);
}
/** @internal Entities whose `component` was written after `sinceTick`. */
getWrittenEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {
return this.changes_.getWrittenEntitiesSince(component, sinceTick);
}
/** @internal An O(1) upper bound on what `getWrittenEntitiesSince` returns,
* for a caller choosing between reading the journal and a scan. */
bufferedWriteRows(component: AnyComponentDef): number {
return this.changes_.bufferedWriteRows(component);
}
/** @internal That reader is done with everything up to `lastRunTick`. */
advanceWriteReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {
this.changes_.advanceWriteReader(component, readerId, lastRunTick);
}
/** @internal The reader is gone; its share of the watermark goes with it. */
disposeWriteReader(component: AnyComponentDef, readerId: number): void {
this.changes_.disposeWriteReader(component, readerId);
}
/** @internal How many readers hold `component`'s write journal. */
writeReaderCount(component: AnyComponentDef): number {
return this.changes_.writeReaderCount(component);
}
/**
* @internal One place for "this component was written".
*
* The composition epoch hangs off the LOGICAL mutation contract, not off the
* storage path: `set`, `insert`, `update` and a `Mut` write-back all arrive
* here whether or not the fast pointer setter moved the bytes.
*/
private recordComponentWrite_(entity: Entity, component: AnyComponentDef): void {
if (component._id === Disabled._id) this.builtin_.getCppRegistry()?.setEntityEnabled?.(entity, false);
// An engine component's write is stamped where the engine keeps it, beside the component: the engine's own readers
// (the renderer) ask there what changed, whoever wrote it.
if (isBuiltinComponent(component)) this.stampEngineWrite(entity, component);
if (COMPOSITION_INPUTS.has(component._name)) {
this.builtin_.invalidateTransformComposition();
}
this.changes_.recordChanged(component, entity);
}
private syncActivityEpoch_(): void {
const epoch = this.builtin_.getCppRegistry()?.activityEpoch?.();
if (epoch === undefined || epoch === this.coreActivityEpoch_) return;
if (this.coreActivityEpoch_ === -1) { this.coreActivityEpoch_ = epoch; return; }
this.coreActivityEpoch_ = epoch;
this.queries_.markComponentDirty(Disabled._id);
this.queries_.markStructuralChange();
}
/** @internal Say composed world transforms are stale, for a producer that
* wrote the bytes without going through the mutation seam. */
invalidateTransformComposition(): void {
this.builtin_.invalidateTransformComposition();
}
/** @internal Compose world transforms if a producer invalidated them. */
ensureTransformsComposed(): void {
this.builtin_.ensureTransformsComposed();
}
/** @internal What the composition staleness counter reads. */
transformEpoch(): number {
return this.builtin_.transformEpoch();
}
/** @internal Ask composition to record which entities' output changed.
* Answers whether this core can report it at all. */
setTransformChangeTracking(on: boolean): boolean {
return this.builtin_.setTransformChangeTracking(on);
}
/** @internal What every composition since the last acknowledgement changed;
* null from a core that cannot say. The ids view engine memory, so a
* consumer reads, applies and acknowledges within one turn. */
compositionChanges(): CompositionDelta | null {
return this.builtin_.compositionChanges();
}
/** @internal Acknowledge that set: it starts again. */
takeCompositionChanges(): void {
this.builtin_.takeCompositionChanges();
}
/** @internal Mark component as changed without writing data (for in-place Mut query) */
markChanged(entity: Entity, component: AnyComponentDef): void {
this.recordComponentWrite_(entity, component);
}
/**
* @internal The open speculation's undo log, or null.
*
* The pre-image is taken where the HANDLE leaves, not where the write
* arrives: script storage hands out the stored object itself, so by `set`
* the old value is gone (docs/MUTATION_CONTRACT.md). Hence `get`/`tryGet`
* ask here too, and only a component's first touch is kept.
*/
private speculation_: { record(world: World, entity: Entity, component: AnyComponentDef): void } | null = null;
/** @internal */
openSpeculation(log: { record(world: World, entity: Entity, component: AnyComponentDef): void }): void {
if (this.speculation_) throw new Error('A speculation is already open on this World — nesting is not supported.');
this.speculation_ = log;
}
/** @internal */
closeSpeculation(): void {
this.speculation_ = null;
}
/** @internal Whether a step that can be taken back is running. */
get speculating(): boolean {
return this.speculation_ !== null;
}
/** @internal Whether any query is asking about `component`'s changes. */
isChangeTracked(component: AnyComponentDef): boolean {
return this.changes_.isTracked(component);
}
/**
* @internal Where script-component rows are allocated from. A wasm runtime
* installs linear memory here BEFORE any component is added, because
* compiled code cannot reach a JS-heap array.
*/
useScriptPoolMemory(memory: PoolMemory, validateOnly = false): void {
this.scripts_.usePoolMemory(memory, validateOnly);
}
/**
* @internal `component`'s bytes for `entity`, in the memory compiled code
* reads: an engine component through the bridge, a script one through its
* pool. Undefined where there are no flat bytes. The resolver is cached per
* component — finding it walks a generated table, and this is asked once per
* entity per frame.
*/
addressOfComponent(component: AnyComponentDef, entity: Entity): number | undefined {
return this.addressResolver(component)(entity);
}
/**
* @internal One number for "could any component have moved since you last
* asked": the engine's pools (`Registry::layoutEpoch`) plus this SDK's own (a
* claimed, released or grown script row). Null where the engine cannot be
* asked, which means re-resolve. It says nothing about which entities MATCH;
* that is the query cache's answer, and a caller needing both asks both.
*/
layoutEpoch(): number | null {
const engine = this.builtin_.layoutEpoch();
if (engine === null && this.builtin_.hasCpp) return null;
return (engine ?? 0) + this.scripts_.layoutEpoch;
}
/**
* @internal The script pools' half of {@link layoutEpoch}, on its own.
*
* A host that reads the engine's half itself needs only this one, and must
* have it: a row added to or deleted from a script pool moves nothing the
* registry's version numbers can see.
*/
scriptLayoutEpoch(): number {
return this.scripts_.layoutEpoch;
}
/**
* @internal Where a SCRIPT component's whole column is, for a host that
* walks it in its own address space. Undefined for an engine component,
* whose column belongs to the registry and is reached by its own door.
*/
scriptSpanOf(component: AnyComponentDef): {
rows: number; stride: number; sparse: number; sparseCount: number;
owners: number; ownerCount: number;
} | undefined {
if (isBuiltinComponent(component)) return undefined;
return this.scripts_.poolFor(component._id as symbol)?.span();
}
/** @internal Whether script rows still carry a portable asset reference. */
hasPortableScriptAssetRefs(component: AnyComponentDef): boolean {
return this.scripts_.hasPortableAssetRefs(component._id as symbol);
}
/** @internal Release script memory after its application stops using it. */
releaseScriptPools(): void {
this.addressOf_.clear();
this.scripts_.releasePools();
}
/**
* @internal The same answer as a function, for a caller with a whole column
* to walk: the lookup above is per entity, and a loop that pays it per row is
* paying to be told the same thing every time.
*/
addressResolver(component: AnyComponentDef): (entity: Entity) => number | undefined {
let at = this.addressOf_.get(component._id as symbol);
if (at === undefined) {
at = isBuiltinComponent(component)
? (this.builtin_.resolveComponentAddress(component._cppName) ?? NO_ADDRESS)
: scriptAddress(this.scripts_, component._id as symbol);
this.addressOf_.set(component._id as symbol, at);
}
return at;
}
/** Cleared with the bridge, because a reconnect may serve other memory. */
private readonly addressOf_ = new Map<symbol, (entity: Entity) => number | undefined>();
}
/** A component whose backend serves no flat memory: never has an address. */
const NO_ADDRESS = (): undefined => undefined;
/**
* A script component's address, with the pool looked up once rather than per
* entity. Sound because a pool is never dropped once made, and because the pool
* re-views itself after a growth — the block moving is its business, not this
* closure's.
*/
function scriptAddress(scripts: ScriptStorage, id: symbol): (entity: Entity) => number | undefined {
let pool: ScriptPool | undefined;
return (entity: Entity) => {
if (pool?.disposed) pool = undefined;
pool ??= scripts.poolFor(id);
return pool?.address(entity);
};
}