Skip to content

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.

feat(ecs): a composition says which one it was, and what it changed

esengine7ba5e8a51227
diff --git a/bench/transform-composition/README.md b/bench/transform-composition/README.md
index 42b1869db..c54c83ef8 100644
--- a/bench/transform-composition/README.md
+++ b/bench/transform-composition/README.md
@@ -98,9 +98,9 @@ never move their probe, so the check is live where movement is.
entities arrive in this set like any other. 3D physics already wrote only
local inputs — but it treats the solver pose as local unconditionally, which
is a parented-body bug of its own and not an authorship one.
-- Nothing ships. `composeCollecting` has one caller and it is this bench; the
- shipped `ensureComposed` path collects nothing and pays one predictable branch
- per entity, which the A column is what says is affordable.
+- Change tracking is OFF by default, and the A column is what says that matters:
+ a compose that records nothing pays one predictable branch per entity, and a
+ consumer that wants the set turns it on and pays the B column.
- **The set is a value-change journal, not a membership one.** A new entity
spawned at the origin is not in it — its composed output equals what its fields
already held — and a despawned entity is never in it. A consumer that maintains
diff --git a/bench/transform-composition/arm.mjs b/bench/transform-composition/arm.mjs
index 06096a45b..dfe7c1ef3 100644
--- a/bench/transform-composition/arm.mjs
+++ b/bench/transform-composition/arm.mjs
@@ -102,21 +102,33 @@ function mutate(tick) {
world.invalidateTransformComposition();
}
-const collecting = module.transform_composeCollecting;
+const setTracking = module.transform_setChangeTracking;
+const lastComposition = module.transform_lastComposition;
let visitedSum = 0;
let changedSum = 0;
let ran = 0;
+let seenSerial = -1;
// Both arms in one process, alternating passes. Run apart they disagreed by more
-// than the thing being measured — two node processes differ by more than a
-// hundred microseconds of compose, and B came out FASTER than A on the tree.
-function composeA() { world.ensureTransformsComposed(); }
-function composeB() {
- const r = collecting(registry);
- if (r.ran) { ran++; visitedSum += r.visited; changedSum += r.changed; }
+// than the thing being measured — B came out FASTER than A on the tree. Switching
+// the mode and READING the set are the consumer's work, not the composition's, so
+// both sit outside the timer.
+function compose(collect) {
+ setTracking(collect);
+ const t0 = process.hrtime.bigint();
+ world.ensureTransformsComposed();
+ const dt = Number(process.hrtime.bigint() - t0);
+ if (collect) {
+ const r = lastComposition();
+ if (r.serial !== seenSerial) {
+ seenSerial = r.serial;
+ ran++; visitedSum += r.visited; changedSum += r.count;
+ }
+ }
+ return dt;
}
-for (let t = 0; t < WARMUP; t++) { mutate(t); (t % 2 ? composeB : composeA)(); }
+for (let t = 0; t < WARMUP; t++) { mutate(t); compose(t % 2 === 1); }
ran = 0; visitedSum = 0; changedSum = 0;
let nsA = 0;
let nsB = 0;
@@ -125,9 +137,7 @@ let passesB = 0;
for (let t = 0; t < MEASURE; t++) {
mutate(t);
const collect = t % 2 === 1;
- const t0 = process.hrtime.bigint();
- if (collect) composeB(); else composeA();
- const dt = Number(process.hrtime.bigint() - t0);
+ const dt = compose(collect);
if (collect) { nsB += dt; passesB++; } else { nsA += dt; passesA++; }
}
diff --git a/native/host/bindings/EcsBindings.cpp b/native/host/bindings/EcsBindings.cpp
index 4e127b6cc..37fbc39a0 100644
--- a/native/host/bindings/EcsBindings.cpp
+++ b/native/host/bindings/EcsBindings.cpp
@@ -115,6 +115,34 @@ JSValue js_setMeshSkinJoints(JSContext* ctx, JSValueConst, int argc, JSValueCons
JSValue js_transformEpochBuffer(JSContext* ctx, JSValueConst, int, JSValueConst*) {
return esn_arraybuffer(ctx, &ecs::transformMutationEpoch(), sizeof(u32));
}
+/** Whether composition also records which entities' output moved. Off by default;
+ * only a consumer maintaining an incremental structure pays for it. */
+JSValue js_transformSetChangeTracking(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {
+ if (argc >= 1 && host().ctx) {
+ if (auto* ts = host().ctx->tryGet<ecs::TransformSystem>()) {
+ ts->setChangeTracking(JS_ToBool(ctx, argv[0]) != 0);
+ }
+ }
+ return JS_UNDEFINED;
+}
+/**
+ * The last composition: its serial, and the entities it changed. The buffer is a
+ * view over the system's own vector — valid until the next composition, which is
+ * what the serial is for.
+ */
+JSValue js_transformLastComposition(JSContext* ctx, JSValueConst, int, JSValueConst*) {
+ static_assert(sizeof(Entity) == sizeof(u32), "the changed set is read as raw ids");
+ auto* ts = host().ctx ? host().ctx->tryGet<ecs::TransformSystem>() : nullptr;
+ JSValue out = JS_NewObject(ctx);
+ JS_SetPropertyStr(ctx, out, "serial", JS_NewUint32(ctx, ts ? ts->compositionSerial() : 0));
+ JS_SetPropertyStr(ctx, out, "tracking", JS_NewBool(ctx, ts && ts->changeTracking()));
+ const size_t count = ts ? ts->lastChanged().size() : 0;
+ JS_SetPropertyStr(ctx, out, "count", JS_NewUint32(ctx, static_cast<uint32_t>(count)));
+ JS_SetPropertyStr(ctx, out, "visited", JS_NewUint32(ctx, ts ? ts->visited() : 0));
+ JS_SetPropertyStr(ctx, out, "changed", count == 0 ? JS_NULL
+ : esn_arraybuffer(ctx, const_cast<Entity*>(ts->lastChanged().data()), count * sizeof(Entity)));
+ return out;
+}
/** The consumer half: compose if a producer said the inputs moved. A headless
* host installs no renderer, and nothing else would ever schedule it. */
JSValue js_transformEnsureComposed(JSContext* ctx, JSValueConst, int, JSValueConst*) {
@@ -140,6 +168,8 @@ void registerEcsBindings(HostState& h, JSValue global) {
bindGlobal(h, global, "es_registryLayoutEpoch", js_layoutEpoch, 0);
bindGlobal(h, global, "es_transformEpochBuffer", js_transformEpochBuffer, 0);
bindGlobal(h, global, "es_transformEnsureComposed", js_transformEnsureComposed, 0);
+ bindGlobal(h, global, "es_transformSetChangeTracking", js_transformSetChangeTracking, 1);
+ bindGlobal(h, global, "es_transformLastComposition", js_transformLastComposition, 0);
}
} // namespace eshost
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 69f2604ac..d54a23c45 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -9529,6 +9529,7 @@ tabIndex: number | undefined
@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
+@internal lastComposition: () => CompositionDelta | null
@internal layoutEpoch: () => number | null
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@internal queries_: QueryCache
@@ -9549,6 +9550,7 @@ tabIndex: number | undefined
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
+@internal setTransformChangeTracking: (on: boolean) => boolean
@internal suspendIteration: () => number
@internal topologyReaderCount: (component: AnyComponentDef) => number
@internal transformEpoch: () => number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 9552c7358..defeda45c 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -9722,6 +9722,7 @@ tabIndex: number | undefined
@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
+@internal lastComposition: () => CompositionDelta | null
@internal layoutEpoch: () => number | null
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@internal queries_: QueryCache
@@ -9742,6 +9743,7 @@ tabIndex: number | undefined
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
+@internal setTransformChangeTracking: (on: boolean) => boolean
@internal suspendIteration: () => number
@internal topologyReaderCount: (component: AnyComponentDef) => number
@internal transformEpoch: () => number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 302563a7c..ec75ec021 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -9524,6 +9524,7 @@ tabIndex: number | undefined
@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
+@internal lastComposition: () => CompositionDelta | null
@internal layoutEpoch: () => number | null
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@internal queries_: QueryCache
@@ -9544,6 +9545,7 @@ tabIndex: number | undefined
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
+@internal setTransformChangeTracking: (on: boolean) => boolean
@internal suspendIteration: () => number
@internal topologyReaderCount: (component: AnyComponentDef) => number
@internal transformEpoch: () => number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 9cf4031ee..d696531b7 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -9776,6 +9776,7 @@ tabIndex: number | undefined
@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
+@internal lastComposition: () => CompositionDelta | null
@internal layoutEpoch: () => number | null
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@internal queries_: QueryCache
@@ -9796,6 +9797,7 @@ tabIndex: number | undefined
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
+@internal setTransformChangeTracking: (on: boolean) => boolean
@internal suspendIteration: () => number
@internal topologyReaderCount: (component: AnyComponentDef) => number
@internal transformEpoch: () => number
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 33bb67279..6caa9afe1 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -423,9 +423,10 @@ tilemap_setTile: ((entity: number, x: number, y: number, tileId: number) => void
tilemap_setTiles: ((entity: number, tilesPtr: number, count: number) => void) | undefined
trail_clear: ((registry: CppRegistry, entity: number) => void) | undefined
trail_update: ((registry: CppRegistry, dt: number) => void) | undefined
-transform_composeCollecting: ((registry: CppRegistry) => { ran: boolean; visited: number; changed: number; ptr: number; }) | undefined
transform_ensureComposed: ((registry: CppRegistry) => void) | undefined
transform_epochAddress: (() => number) | undefined
+transform_lastComposition: (() => { serial: number; tracking: boolean; count: number; visited: number; ptr: number; }) | undefined
+transform_setChangeTracking: ((on: boolean) => void) | undefined
transform_update: (registry: CppRegistry) => void
uiHitTest_getHitEntity: () => number
uiHitTest_pick: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f2b10b1c9..93b389080 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -9552,6 +9552,7 @@ tabIndex: number | undefined
@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
+@internal lastComposition: () => CompositionDelta | null
@internal layoutEpoch: () => number | null
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@internal queries_: QueryCache
@@ -9572,6 +9573,7 @@ tabIndex: number | undefined
@internal scriptLayoutEpoch: () => number
@internal scriptSpanOf: (component: AnyComponentDef) => { rows: number; stride: number; sparse: number; sparseCount: number; owners: number; ownerCount: number; } | undefined
@internal setQueryCostEnabled: (enabled: boolean) => void
+@internal setTransformChangeTracking: (on: boolean) => boolean
@internal suspendIteration: () => number
@internal topologyReaderCount: (component: AnyComponentDef) => number
@internal transformEpoch: () => number
diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.ts
index 794f45f18..488ce83e9 100644
--- a/sdk/src/ecs/bridge/BuiltinBridge.ts
+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts
@@ -315,8 +315,33 @@ export interface BridgeConnectOptions {
export interface TransformComposition {
readonly epoch: Uint32Array;
ensure(): void;
+ /** Optional third: what the last composition changed. A core that cannot
+ * report it leaves every consumer to rebuild, which is a capability
+ * difference and not a failure. */
+ setChangeTracking?(on: boolean): void;
+ lastComposition?(): NativeComposition;
}
+/** What a core answers about its last composition. */
+export interface NativeComposition {
+ readonly serial: number;
+ readonly tracking: boolean;
+ readonly count: number;
+ readonly visited: number;
+ readonly changed: ArrayBuffer | null;
+}
+
+/** The last composition, as a consumer reads it: an empty set and the serial it
+ * belongs to, or null from a core that cannot say. */
+export interface CompositionDelta {
+ readonly serial: number;
+ readonly changed: Uint32Array;
+ readonly visited: number;
+}
+
+/** One allocation for every core's empty answer. */
+const EMPTY_CHANGED = new Uint32Array(0);
+
const METHOD_PREFIXES = ['add', 'get', 'has', 'remove'] as const;
function formatBridgeDiagnostic(v: BridgeVerification): string {
@@ -454,6 +479,52 @@ export class BuiltinBridge {
this.module_?.transform_ensureComposed?.(this.cppRegistry_);
}
+ /**
+ * Ask composition to record which entities' output changed. Answers whether
+ * this core can: one that cannot leaves a consumer to rebuild every time.
+ */
+ setTransformChangeTracking(on: boolean): boolean {
+ const injected = this.transformComposition_;
+ if (injected) {
+ if (!injected.setChangeTracking || !injected.lastComposition) return false;
+ injected.setChangeTracking(on);
+ return true;
+ }
+ const set = this.module_?.transform_setChangeTracking;
+ if (!set || !this.module_?.transform_lastComposition) return false;
+ set.call(this.module_, on);
+ return true;
+ }
+
+ /**
+ * The last composition's serial and the entities it changed, or null from a
+ * core that cannot report one. The ids VIEW engine memory and the next
+ * composition overwrites them, so a consumer reads them before composing
+ * again — the serial is how it knows which composition they describe.
+ */
+ lastComposition(): CompositionDelta | null {
+ const injected = this.transformComposition_;
+ if (injected?.lastComposition) {
+ const raw = injected.lastComposition();
+ return {
+ serial: raw.serial,
+ visited: raw.visited,
+ changed: raw.changed ? new Uint32Array(raw.changed, 0, raw.count) : EMPTY_CHANGED,
+ };
+ }
+ const read = this.module_?.transform_lastComposition;
+ if (!read || !this.module_) return null;
+ const raw = read.call(this.module_);
+ return {
+ serial: raw.serial,
+ visited: raw.visited,
+ // Rebuilt every call: growing the heap detaches the previous view.
+ changed: raw.count > 0
+ ? new Uint32Array(this.module_.HEAPU32.buffer, raw.ptr, raw.count)
+ : EMPTY_CHANGED,
+ };
+ }
+
/** @internal What the staleness counter reads, for the fixtures that assert
* a producer notified. */
transformEpoch(): number {
diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.ts
index ba6b5927c..8a789e069 100644
--- a/sdk/src/ecs/bridge/nativeBindings.ts
+++ b/sdk/src/ecs/bridge/nativeBindings.ts
@@ -47,6 +47,16 @@ export const REGISTRY_BINDINGS = {
ensureComposed: 'es_transformEnsureComposed',
} as const;
+/**
+ * The composition's change REPORT, which not every host has to answer: a core
+ * that does not leaves consumers rebuilding rather than updating, so these are
+ * outside {@link assertNativeBindings}' required set.
+ */
+export const COMPOSITION_BINDINGS = {
+ setChangeTracking: 'es_transformSetChangeTracking',
+ lastComposition: 'es_transformLastComposition',
+} as const;
+
/**
* The native ResourceManager surface the asset pipeline uploads through.
*
diff --git a/sdk/src/ecs/bridge/nativeRuntime.ts b/sdk/src/ecs/bridge/nativeRuntime.ts
index a47491979..851dbb47c 100644
--- a/sdk/src/ecs/bridge/nativeRuntime.ts
+++ b/sdk/src/ecs/bridge/nativeRuntime.ts
@@ -21,8 +21,9 @@ import { ensureBuiltinComponentsRegistered } from '../component';
import { installNativePlatform, type NativeBridge } from '../../platform/native';
import { createNativeRegistry } from './nativeRegistry';
import { NativeMemoryProvider } from './memoryProvider';
+import type { NativeComposition } from './BuiltinBridge';
import { createNativeResourceManager } from './nativeResourceManager';
-import { HOST_FLAGS, REGISTRY_BINDINGS, TEXT_BINDINGS, hasTextBindings, hasRendererBindings } from './nativeBindings';
+import { COMPOSITION_BINDINGS, HOST_FLAGS, REGISTRY_BINDINGS, TEXT_BINDINGS, hasTextBindings, hasRendererBindings } from './nativeBindings';
import { createNativeRendererBackend, nativeSurfaceSize } from './nativeRenderer';
import { createNativeEngineApi } from './nativeEngineApi.generated';
import { setNativeEngineApi, engineApi } from './engineApi';
@@ -70,7 +71,17 @@ function nativeTransformComposition(scope: Record<string, unknown>) {
if (!bytes) return undefined;
// The arena never moves, unlike a growable wasm heap, so one view lasts.
const epoch = new Uint32Array(bytes, 0, 1);
- return { epoch, ensure: () => { (ensure as () => void)(); } };
+ const track = scope[COMPOSITION_BINDINGS.setChangeTracking];
+ const last = scope[COMPOSITION_BINDINGS.lastComposition];
+ const reports = typeof track === 'function' && typeof last === 'function';
+ return {
+ epoch,
+ ensure: () => { (ensure as () => void)(); },
+ // A host too old to report the delta simply has no third half, and every
+ // consumer of it rebuilds instead.
+ setChangeTracking: reports ? (on: boolean) => { (track as (v: boolean) => void)(on); } : undefined,
+ lastComposition: reports ? () => (last as () => NativeComposition)() : undefined,
+ };
}
export function createNativeWorld(
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index 6c7cc2956..477983a87 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -9,7 +9,7 @@ import { Entity, entityGeneration, entityIndex, makeEntity, INVALID_ENTITY } fro
import { AnyComponentDef, ComponentDef, ComponentData, BuiltinComponentDef, isBuiltinComponent, getComponentRegistry, getUserComponents, getComponent, Name, Parent, Children, type ParentData, type ChildrenData } from './component';
import type { CppRegistry, ESEngineModule } from '../wasm';
import { handleWasmError } from '../wasm/wasmError';
-import { BuiltinBridge, convertFromWasm, convertForWasm, type BridgeConnectOptions, type BuiltinMethods } from './bridge/BuiltinBridge';
+import { BuiltinBridge, convertFromWasm, convertForWasm, type BridgeConnectOptions, type BuiltinMethods, type CompositionDelta } from './bridge/BuiltinBridge';
import { ScriptStorage } from './ScriptStorage';
import type { PoolMemory, ScriptPool } from './ScriptPool';
import { NameIndex } from './NameIndex';
@@ -1309,6 +1309,19 @@ export class World {
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 The last composition's serial and the entities it changed; null
+ * from a core that cannot say. The ids view engine memory until the next
+ * composition, and the serial says which composition they describe. */
+ lastComposition(): CompositionDelta | null {
+ return this.builtin_.lastComposition();
+ }
+
/** @internal Mark component as changed without writing data (for in-place Mut query) */
markChanged(entity: Entity, component: AnyComponentDef): void {
this.recordComponentWrite_(entity, component);
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index ca20695ce..ad82c8fd4 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -428,11 +428,13 @@ export interface ESEngineModule {
transform_epochAddress?(): number;
/** Compose world transforms if a producer said the inputs moved; O(1) if not. */
transform_ensureComposed?(registry: CppRegistry): void;
- /** The same composition, also answering WHICH entities' composed output moved.
- * `ptr` addresses `changed` raw entity ids; the buffer is reused every call.
- * Measured by bench/transform-composition; no shipped path calls it. */
- transform_composeCollecting?(registry: CppRegistry): {
- ran: boolean; visited: number; changed: number; ptr: number;
+ /** Whether composition also records which entities' output moved. Off by
+ * default: only a consumer maintaining an incremental structure needs it. */
+ transform_setChangeTracking?(on: boolean): void;
+ /** The last composition: its serial, and `count` raw entity ids at `ptr`.
+ * Valid until the next composition, which is what the serial is for. */
+ transform_lastComposition?(): {
+ serial: number; tracking: boolean; count: number; visited: number; ptr: number;
};
/** Permute component storage to the given entity order — see World.applyEntityOrder.
* Optional: an older core still answers every other renderer entry point. */
diff --git a/sdk/tests/world-transform-authority.test.ts b/sdk/tests/world-transform-authority.test.ts
index 1c78944b4..cb5f67f2c 100644
--- a/sdk/tests/world-transform-authority.test.ts
+++ b/sdk/tests/world-transform-authority.test.ts
@@ -314,3 +314,112 @@ describe.skipIf(!HAS_WASM)('a core that hands the composition seam over', () =>
world.disconnectCpp();
});
});
+
+/**
+ * What a consumer maintaining an incremental structure reads: a serial saying
+ * WHICH composition it is looking at, and the entities that one changed. The
+ * pair is the whole contract — a set without a serial cannot tell "nothing
+ * moved" from "you missed three compositions".
+ */
+describe.skipIf(!HAS_WASM)('the composition reports what it changed', () => {
+ let module: ESEngineModule;
+ beforeAll(async () => { module = await loadWasmModule(); });
+
+ function scene() {
+ const app = App.new();
+ const registry = new module.Registry() as unknown as CppRegistry;
+ app.connectCpp(registry, module);
+ const world = app.world;
+ const a = world.spawn('a');
+ world.insert(a, Transform, { position: { x: 1, y: 0, z: 0 } });
+ const b = world.spawn('b');
+ world.insert(b, Transform, { position: { x: 2, y: 0, z: 0 } });
+ return { app, world, a, b };
+ }
+ const ids = (world: App['world']) => [...(world.lastComposition()!.changed)];
+
+ it('names the entities whose output moved, and only those', () => {
+ const { world, a, b } = scene();
+ expect(world.setTransformChangeTracking(true)).toBe(true);
+ world.ensureTransformsComposed();
+
+ world.update(b, Transform, (t) => { (t as { position: { x: number } }).position.x = 40; });
+ world.ensureTransformsComposed();
+ expect(ids(world)).toEqual([b as number]);
+
+ // A write that moves nothing: the epoch cannot tell it from movement and
+ // the comparison can, which is the whole reason the set is worth having.
+ world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 1; });
+ world.ensureTransformsComposed();
+ expect(ids(world)).toEqual([]);
+ world.setTransformChangeTracking(false);
+ world.disconnectCpp();
+ });
+
+ it('advances the serial once per composition and not at all without one', () => {
+ const { world, a } = scene();
+ world.setTransformChangeTracking(true);
+ world.ensureTransformsComposed();
+ const first = world.lastComposition()!.serial;
+
+ // Nothing was invalidated, so nothing composed.
+ world.ensureTransformsComposed();
+ world.ensureTransformsComposed();
+ expect(world.lastComposition()!.serial).toBe(first);
+
+ world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 9; });
+ world.ensureTransformsComposed();
+ expect(world.lastComposition()!.serial).toBe(first + 1);
+ world.setTransformChangeTracking(false);
+ world.disconnectCpp();
+ });
+
+ it('reports nothing while tracking is off, and the serial still moves', () => {
+ const { world, a } = scene();
+ world.setTransformChangeTracking(false);
+ world.ensureTransformsComposed();
+ const before = world.lastComposition()!.serial;
+
+ world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 3; });
+ world.ensureTransformsComposed();
+ const after = world.lastComposition()!;
+ expect(after.serial).toBe(before + 1);
+ expect(after.changed.length).toBe(0);
+ world.disconnectCpp();
+ });
+
+ it('a second world composing in between shows up as a gap', () => {
+ const first = scene();
+ first.world.setTransformChangeTracking(true);
+ first.world.ensureTransformsComposed();
+ const seen = first.world.lastComposition()!.serial;
+
+ // Another world composes; the serial is the engine's, not this world's,
+ // so a consumer that missed compositions has to be able to see that.
+ const other = scene();
+ other.world.ensureTransformsComposed();
+ other.world.disconnectCpp();
+
+ first.world.update(first.a, Transform,
+ (t) => { (t as { position: { x: number } }).position.x = 50; });
+ first.world.ensureTransformsComposed();
+ expect(first.world.lastComposition()!.serial).toBeGreaterThan(seen + 1);
+ first.world.setTransformChangeTracking(false);
+ first.world.disconnectCpp();
+ });
+
+ it('a core that cannot report says so instead of answering nothing', () => {
+ const app = App.new();
+ const registry = new module.Registry() as unknown as CppRegistry;
+ // The seam without its optional third half — a host too old to report.
+ app.connectCpp(registry, undefined, {
+ transformComposition: {
+ epoch: new Uint32Array(module.HEAPU32.buffer, module.transform_epochAddress!(), 1),
+ ensure: () => module.transform_ensureComposed!(registry),
+ },
+ });
+ expect(app.world.setTransformChangeTracking(true)).toBe(false);
+ expect(app.world.lastComposition()).toBeNull();
+ app.world.disconnectCpp();
+ });
+});
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 2edfafc20..05597f1be 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -648,27 +648,31 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
ts->ensureComposed(registry);
}
}), emscripten::allow_raw_pointers());
- // The same composition, asked to also say WHICH entities' output moved — the
- // set an incremental spatial index would maintain itself from. Costed in
- // bench/transform-composition; no shipped path calls it.
- emscripten::function("transform_composeCollecting", emscripten::optional_override(
- [](esengine::ecs::Registry& registry) -> emscripten::val {
- static std::vector<esengine::Entity> changed;
- auto* ts = esengine::ctx().tryGet<esengine::ecs::TransformSystem>();
- auto out = emscripten::val::object();
- const bool ran = ts && ts->composeCollecting(registry, changed);
- out.set("ran", ran);
- out.set("visited", ts ? ts->visited() : 0u);
- out.set("changed", static_cast<esengine::u32>(ran ? changed.size() : 0));
- // The ids themselves, as an address into linear memory: a JS array of
- // a hundred thousand handles would cost more than the walk that found
- // them. Valid until the next call, which reuses the vector.
+ // Whether composition also records WHICH entities' output moved. Off by
+ // default: only a consumer maintaining an incremental structure needs it.
+ emscripten::function("transform_setChangeTracking", emscripten::optional_override(
+ [](bool on) {
+ if (auto* ts = esengine::ctx().tryGet<esengine::ecs::TransformSystem>()) {
+ ts->setChangeTracking(on);
+ }
+ }));
+ // What the LAST composition was: its serial, and the entities it changed as
+ // an address into linear memory. A JS array of a hundred thousand handles
+ // would cost more than the walk that found them.
+ emscripten::function("transform_lastComposition", emscripten::optional_override(
+ []() -> emscripten::val {
static_assert(sizeof(esengine::Entity) == sizeof(esengine::u32),
"the changed set is read as a Uint32Array of raw ids");
- out.set("ptr", static_cast<esengine::u32>(
- reinterpret_cast<uintptr_t>(changed.data())));
+ auto out = emscripten::val::object();
+ auto* ts = esengine::ctx().tryGet<esengine::ecs::TransformSystem>();
+ out.set("serial", ts ? ts->compositionSerial() : 0u);
+ out.set("tracking", ts && ts->changeTracking());
+ out.set("count", ts ? static_cast<esengine::u32>(ts->lastChanged().size()) : 0u);
+ out.set("visited", ts ? ts->visited() : 0u);
+ out.set("ptr", ts ? static_cast<esengine::u32>(
+ reinterpret_cast<uintptr_t>(ts->lastChanged().data())) : 0u);
return out;
- }), emscripten::allow_raw_pointers());
+ }));
emscripten::function("renderer_setEntityDrawOrder", &esengine::renderer_setEntityDrawOrder);
emscripten::function("renderer_submitAll", &esengine::renderer_submitAll);
#ifdef ES_ENABLE_PARTICLES
diff --git a/src/esengine/ecs/TransformSystem.hpp b/src/esengine/ecs/TransformSystem.hpp
index 313510aec..c0ba2fd22 100644
--- a/src/esengine/ecs/TransformSystem.hpp
+++ b/src/esengine/ecs/TransformSystem.hpp
@@ -55,10 +55,7 @@ public:
(void)registry;
}
- void update(World& world) override {
- updateDirtyTransforms(world.registry);
- markComposed(world.registry);
- }
+ void update(World& world) override { compose(world.registry); }
/**
* @brief Compose if anything changed since the last one; O(1) if not
@@ -70,34 +67,33 @@ public:
void ensureComposed(Registry& registry) {
if (registry.instanceId() == composedRegistry_
&& transformMutationEpoch() == composedEpoch_) return;
- updateDirtyTransforms(registry);
- markComposed(registry);
+ compose(registry);
}
u32 composedEpoch() const { return composedEpoch_; }
/**
- * @brief Compose, and answer which entities' composed OUTPUT actually moved
- * @param changed Receives those entities; cleared first
- * @return Whether it composed at all (false = nothing was stale)
- * @details Not the set the walk VISITED: a non-static root is recomposed
- * unconditionally. Costed in bench/transform-composition.
- * @note A root publishes decomposed world TRS and a child publishes
- * `cachedMatrix_`, so each is compared against the one it publishes.
+ * @brief How many compositions have RUN
+ * @details A consumer maintaining a structure from {@link lastChanged} reads
+ * this to know what it is holding: the same number means nothing
+ * composed, one more means that set is the whole difference, and any
+ * other gap means it missed compositions and has to rebuild.
*/
- bool composeCollecting(Registry& registry, std::vector<Entity>& changed) {
- changed.clear();
- visited_ = 0;
- if (registry.instanceId() == composedRegistry_
- && transformMutationEpoch() == composedEpoch_) return false;
- changed_ = &changed;
- updateDirtyTransforms(registry);
- changed_ = nullptr;
- markComposed(registry);
- return true;
- }
+ u32 compositionSerial() const { return serial_; }
- /** How many entities the last collecting compose actually wrote. */
+ /**
+ * @brief Collect which entities' composed OUTPUT changed, from now on
+ * @details Off by default: comparing costs about a third of a compose
+ * (bench/transform-composition) and only a consumer maintaining an
+ * incremental structure needs it. Turning it on does not compose.
+ */
+ void setChangeTracking(bool on) { tracking_ = on; if (!on) changed_.clear(); }
+ bool changeTracking() const { return tracking_; }
+
+ /** @brief The entities the LAST composition changed; empty unless tracking. */
+ const std::vector<Entity>& lastChanged() const { return changed_; }
+
+ /** @brief How many entities that composition wrote, changed or not. */
u32 visited() const { return visited_; }
private:
@@ -113,10 +109,29 @@ private:
std::vector<Entity> dirty_to_clear_;
- // Null on the shipped path: composition answers "are they stale", and only a
+ // Off on the shipped path: composition answers "are they stale", and only a
// caller building an incremental structure pays for "which ones moved".
- std::vector<Entity>* changed_ = nullptr;
+ bool tracking_ = false;
+ std::vector<Entity>* changedOut_ = nullptr;
+ std::vector<Entity> changed_;
u32 visited_ = 0;
+ u32 serial_ = 0;
+
+ /**
+ * @brief One composition, whoever asked for it
+ * @details The serial advances here and nowhere else, so "a composition ran"
+ * and "the changed set describes it" cannot come apart — a caller
+ * that composed through update() would otherwise move the serial
+ * past a set nobody collected.
+ */
+ void compose(Registry& registry) {
+ visited_ = 0;
+ if (tracking_) { changed_.clear(); changedOut_ = &changed_; }
+ updateDirtyTransforms(registry);
+ changedOut_ = nullptr;
+ ++serial_;
+ markComposed(registry);
+ }
void updateDirtyTransforms(Registry& registry) {
dirty_to_clear_.clear();
@@ -156,13 +171,13 @@ private:
}
void updateRootTransform(Registry& registry, Entity entity, Transform& transform) {
- if (changed_) {
+ if (changedOut_) {
++visited_;
if (!transform.decomposed_
|| transform.worldPosition != transform.position
|| transform.worldRotation != transform.rotation
|| transform.worldScale != transform.scale) {
- changed_->push_back(entity);
+ changedOut_->push_back(entity);
}
}
transform.worldPosition = transform.position;
@@ -221,12 +236,12 @@ private:
glm::mat4 localMatrix = math::compose(transform.position, transform.rotation, transform.scale);
glm::mat4 worldMatrix = parentWorldMatrix * localMatrix;
- if (changed_) {
+ if (changedOut_) {
++visited_;
// `decomposed_` is not part of the output: a READ flips it (the ptr
// accessor decomposes on the way out), so testing it here reports
// every child anyone looked at as having moved.
- if (worldMatrix != transform.cachedMatrix_) changed_->push_back(entity);
+ if (worldMatrix != transform.cachedMatrix_) changedOut_->push_back(entity);
}
transform.cachedMatrix_ = worldMatrix;
transform.decomposed_ = false;