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
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.mdindex 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 onlylocal inputs — but it treats the solver pose as local unconditionally, whichis 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 entityspawned at the origin is not in it — its composed output equals what its fieldsalready held — and a despawned entity is never in it. A consumer that maintainsdiff --git a/bench/transform-composition/arm.mjs b/bench/transform-composition/arm.mjsindex 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.cppindex 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, JSValueConsJSValue 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 eshostdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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: () => numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: () => numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: () => numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: () => numberdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 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) => voidtilemap_setTiles: ((entity: number, tilesPtr: number, count: number) => void) | undefinedtrail_clear: ((registry: CppRegistry, entity: number) => void) | undefinedtrail_update: ((registry: CppRegistry, dt: number) => void) | undefined-transform_composeCollecting: ((registry: CppRegistry) => { ran: boolean; visited: number; changed: number; ptr: number; }) | undefinedtransform_ensureComposed: ((registry: CppRegistry) => void) | undefinedtransform_epochAddress: (() => number) | undefined+transform_lastComposition: (() => { serial: number; tracking: boolean; count: number; visited: number; ptr: number; }) | undefined+transform_setChangeTracking: ((on: boolean) => void) | undefinedtransform_update: (registry: CppRegistry) => voiduiHitTest_getHitEntity: () => numberuiHitTest_pick: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: () => numberdiff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.tsindex 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.tsindex 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.tsindex 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.tsindex 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 } froimport { 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.tsindex 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.tsindex 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.cppindex 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_PARTICLESdiff --git a/src/esengine/ecs/TransformSystem.hpp b/src/esengine/ecs/TransformSystem.hppindex 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;