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): the change set is what happened since you last acknowledged
esenginee933eebbf87c
diff --git a/bench/transform-composition/arm.mjs b/bench/transform-composition/arm.mjsindex dfe7c1ef3..9edf0ba79 100644--- a/bench/transform-composition/arm.mjs+++ b/bench/transform-composition/arm.mjs@@ -103,7 +103,8 @@ function mutate(tick) {}const setTracking = module.transform_setChangeTracking;-const lastComposition = module.transform_lastComposition;+const compositionChanges = module.transform_compositionChanges;+const takeChanges = module.transform_takeChanges;let visitedSum = 0;let changedSum = 0;let ran = 0;@@ -119,11 +120,12 @@ function compose(collect) {world.ensureTransformsComposed();const dt = Number(process.hrtime.bigint() - t0);if (collect) {- const r = lastComposition();+ const r = compositionChanges();if (r.serial !== seenSerial) {seenSerial = r.serial;ran++; visitedSum += r.visited; changedSum += r.count;}+ takeChanges();}return dt;}diff --git a/native/host/bindings/EcsBindings.cpp b/native/host/bindings/EcsBindings.cppindex 37fbc39a0..0718b9e71 100644--- a/native/host/bindings/EcsBindings.cpp+++ b/native/host/bindings/EcsBindings.cpp@@ -126,23 +126,33 @@ JSValue js_transformSetChangeTracking(JSContext* ctx, JSValueConst, int argc, JSreturn 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.+ * What every composition since the last acknowledgement changed. The buffer views+ * the system's own vector and the next composition may move it, so a consumer+ * reads, applies, and acknowledges within one turn.*/-JSValue js_transformLastComposition(JSContext* ctx, JSValueConst, int, JSValueConst*) {+JSValue js_transformCompositionChanges(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, "overflowed", JS_NewBool(ctx, ts && ts->changesOverflowed()));+ const size_t count = ts ? ts->pendingChanges().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)));+ : esn_arraybuffer(ctx, const_cast<Entity*>(ts->pendingChanges().data()), count * sizeof(Entity)));return out;}+/** Applied: the set starts again. Separate from the read, so a consumer that+ * throws half way through has not acknowledged and gets it again. */+JSValue js_transformTakeChanges(JSContext* ctx, JSValueConst, int, JSValueConst*) {+ (void)ctx;+ if (host().ctx) {+ if (auto* ts = host().ctx->tryGet<ecs::TransformSystem>()) ts->takeChanges();+ }+ return JS_UNDEFINED;+}/** 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*) {@@ -169,7 +179,8 @@ void registerEcsBindings(HostState& h, JSValue global) {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);+ bindGlobal(h, global, "es_transformCompositionChanges", js_transformCompositionChanges, 0);+ bindGlobal(h, global, "es_transformTakeChanges", js_transformTakeChanges, 0);}} // namespace eshostdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex d54a23c45..fcf317668 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -9506,6 +9506,7 @@ tabIndex: number | undefined@internal beginIteration: () => void@internal builtin: BuiltinBridge@internal changes_: ChangeTracker+@internal compositionChanges: () => CompositionDelta | null@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void@@ -9529,7 +9530,6 @@ 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@@ -9552,6 +9552,7 @@ tabIndex: number | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal setTransformChangeTracking: (on: boolean) => boolean@internal suspendIteration: () => number+@internal takeCompositionChanges: () => void@internal topologyReaderCount: (component: AnyComponentDef) => number@internal transformEpoch: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex defeda45c..497a37758 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -9699,6 +9699,7 @@ tabIndex: number | undefined@internal beginIteration: () => void@internal builtin: BuiltinBridge@internal changes_: ChangeTracker+@internal compositionChanges: () => CompositionDelta | null@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void@@ -9722,7 +9723,6 @@ 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@@ -9745,6 +9745,7 @@ tabIndex: number | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal setTransformChangeTracking: (on: boolean) => boolean@internal suspendIteration: () => number+@internal takeCompositionChanges: () => void@internal topologyReaderCount: (component: AnyComponentDef) => number@internal transformEpoch: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex ec75ec021..7b5fce1c6 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -9501,6 +9501,7 @@ tabIndex: number | undefined@internal beginIteration: () => void@internal builtin: BuiltinBridge@internal changes_: ChangeTracker+@internal compositionChanges: () => CompositionDelta | null@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void@@ -9524,7 +9525,6 @@ 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@@ -9547,6 +9547,7 @@ tabIndex: number | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal setTransformChangeTracking: (on: boolean) => boolean@internal suspendIteration: () => number+@internal takeCompositionChanges: () => void@internal topologyReaderCount: (component: AnyComponentDef) => number@internal transformEpoch: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex d696531b7..5c1a60978 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -9753,6 +9753,7 @@ tabIndex: number | undefined@internal beginIteration: () => void@internal builtin: BuiltinBridge@internal changes_: ChangeTracker+@internal compositionChanges: () => CompositionDelta | null@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void@@ -9776,7 +9777,6 @@ 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@@ -9799,6 +9799,7 @@ tabIndex: number | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal setTransformChangeTracking: (on: boolean) => boolean@internal suspendIteration: () => number+@internal takeCompositionChanges: () => void@internal topologyReaderCount: (component: AnyComponentDef) => number@internal transformEpoch: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 6caa9afe1..c0c749d6a 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -423,10 +423,11 @@ 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_compositionChanges: (() => { serial: number; tracking: boolean; overflowed: boolean; count: number; visited: number; ptr: number; }) | undefinedtransform_ensureComposed: ((registry: CppRegistry) => void) | undefinedtransform_epochAddress: (() => number) | undefined-transform_lastComposition: (() => { serial: number; tracking: boolean; count: number; visited: number; ptr: number; }) | undefinedtransform_setChangeTracking: ((on: boolean) => void) | undefined+transform_takeChanges: (() => 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 93b389080..d4086f446 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -9529,6 +9529,7 @@ tabIndex: number | undefined@internal beginIteration: () => void@internal builtin: BuiltinBridge@internal changes_: ChangeTracker+@internal compositionChanges: () => CompositionDelta | null@internal connectCpp: (cppRegistry: CppRegistry, module?: ESEngineModule, options?: BridgeConnectOptions) => void@internal disconnectCpp: () => void@internal disposeRemovedReader: (component: AnyComponentDef, readerId: number) => void@@ -9552,7 +9553,6 @@ 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@@ -9575,6 +9575,7 @@ tabIndex: number | undefined@internal setQueryCostEnabled: (enabled: boolean) => void@internal setTransformChangeTracking: (on: boolean) => boolean@internal suspendIteration: () => number+@internal takeCompositionChanges: () => void@internal topologyReaderCount: (component: AnyComponentDef) => number@internal transformEpoch: () => number@internal useScriptPoolMemory: (memory: PoolMemory) => voiddiff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.tsindex 488ce83e9..56f39d2b2 100644--- a/sdk/src/ecs/bridge/BuiltinBridge.ts+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts@@ -319,24 +319,30 @@ export interface TransformComposition {* report it leaves every consumer to rebuild, which is a capability* difference and not a failure. */setChangeTracking?(on: boolean): void;- lastComposition?(): NativeComposition;+ compositionChanges?(): NativeComposition;+ takeChanges?(): void;}-/** What a core answers about its last composition. */+/** What a core answers about the compositions since the last acknowledgement. */export interface NativeComposition {readonly serial: number;readonly tracking: boolean;+ readonly overflowed: 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. */+/**+ * The pending change set, as a consumer reads it. `overflowed` means it grew+ * past the point where reading the world again is cheaper, so it was dropped —+ * rebuild rather than apply.+ */export interface CompositionDelta {readonly serial: number;readonly changed: Uint32Array;readonly visited: number;+ readonly overflowed: boolean;}/** One allocation for every core's empty answer. */@@ -486,38 +492,40 @@ export class BuiltinBridge {setTransformChangeTracking(on: boolean): boolean {const injected = this.transformComposition_;if (injected) {- if (!injected.setChangeTracking || !injected.lastComposition) return false;+ if (!injected.setChangeTracking || !injected.compositionChanges) return false;injected.setChangeTracking(on);return true;}const set = this.module_?.transform_setChangeTracking;- if (!set || !this.module_?.transform_lastComposition) return false;+ if (!set || !this.module_?.transform_compositionChanges) 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.+ * What every composition since the last acknowledgement changed, or null from+ * a core that cannot report. The ids VIEW engine memory and the next+ * composition may move it, so a consumer reads, applies and acknowledges+ * within one turn.*/- lastComposition(): CompositionDelta | null {+ compositionChanges(): CompositionDelta | null {const injected = this.transformComposition_;- if (injected?.lastComposition) {- const raw = injected.lastComposition();+ if (injected?.compositionChanges) {+ const raw = injected.compositionChanges();return {serial: raw.serial,visited: raw.visited,+ overflowed: raw.overflowed,changed: raw.changed ? new Uint32Array(raw.changed, 0, raw.count) : EMPTY_CHANGED,};}- const read = this.module_?.transform_lastComposition;+ const read = this.module_?.transform_compositionChanges;if (!read || !this.module_) return null;const raw = read.call(this.module_);return {serial: raw.serial,visited: raw.visited,+ overflowed: raw.overflowed,// Rebuilt every call: growing the heap detaches the previous view.changed: raw.count > 0? new Uint32Array(this.module_.HEAPU32.buffer, raw.ptr, raw.count)@@ -525,6 +533,13 @@ export class BuiltinBridge {};}+ /** Acknowledge the pending set: it starts again. */+ takeCompositionChanges(): void {+ const injected = this.transformComposition_;+ if (injected?.takeChanges) { injected.takeChanges(); return; }+ this.module_?.transform_takeChanges?.();+ }+/** @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 8a789e069..9cd5222be 100644--- a/sdk/src/ecs/bridge/nativeBindings.ts+++ b/sdk/src/ecs/bridge/nativeBindings.ts@@ -54,7 +54,8 @@ export const REGISTRY_BINDINGS = {*/export const COMPOSITION_BINDINGS = {setChangeTracking: 'es_transformSetChangeTracking',- lastComposition: 'es_transformLastComposition',+ compositionChanges: 'es_transformCompositionChanges',+ takeChanges: 'es_transformTakeChanges',} as const;/**diff --git a/sdk/src/ecs/bridge/nativeRuntime.ts b/sdk/src/ecs/bridge/nativeRuntime.tsindex 851dbb47c..8dfeb5354 100644--- a/sdk/src/ecs/bridge/nativeRuntime.ts+++ b/sdk/src/ecs/bridge/nativeRuntime.ts@@ -72,15 +72,17 @@ function nativeTransformComposition(scope: Record<string, unknown>) {// The arena never moves, unlike a growable wasm heap, so one view lasts.const epoch = new Uint32Array(bytes, 0, 1);const track = scope[COMPOSITION_BINDINGS.setChangeTracking];- const last = scope[COMPOSITION_BINDINGS.lastComposition];- const reports = typeof track === 'function' && typeof last === 'function';+ const last = scope[COMPOSITION_BINDINGS.compositionChanges];+ const reports = typeof track === 'function' && typeof last === 'function'+ && typeof scope[COMPOSITION_BINDINGS.takeChanges] === '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,+ compositionChanges: reports ? () => (last as () => NativeComposition)() : undefined,+ takeChanges: reports ? () => { (scope[COMPOSITION_BINDINGS.takeChanges] as () => void)(); } : undefined,};}diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex 477983a87..8d0596ae3 100644--- a/sdk/src/ecs/world.ts+++ b/sdk/src/ecs/world.ts@@ -1315,11 +1315,16 @@ export class World {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 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) */diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex ad82c8fd4..232fed99e 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -431,11 +431,14 @@ export interface ESEngineModule {/** 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;+ /** What every composition since the last acknowledgement changed: `count`+ * raw entity ids at `ptr`, valid until the next composition. */+ transform_compositionChanges?(): {+ serial: number; tracking: boolean; overflowed: boolean;+ count: number; visited: number; ptr: number;};+ /** Acknowledge that set: it starts again. */+ transform_takeChanges?(): void;/** Permute component storage to the given entity order — see World.applyEntityOrder.* Optional: an older core still answers every other renderer entry point. */renderer_setEntityDrawOrder?(registry: CppRegistry, entitiesPtr: number, count: number): void;diff --git a/sdk/tests/world-transform-authority.test.ts b/sdk/tests/world-transform-authority.test.tsindex cb5f67f2c..c9f6c20bd 100644--- a/sdk/tests/world-transform-authority.test.ts+++ b/sdk/tests/world-transform-authority.test.ts@@ -336,19 +336,21 @@ describe.skipIf(!HAS_WASM)('the composition reports what it changed', () => {world.insert(b, Transform, { position: { x: 2, y: 0, z: 0 } });return { app, world, a, b };}- const ids = (world: App['world']) => [...(world.lastComposition()!.changed)];+ const ids = (world: App['world']) => [...(world.compositionChanges()!.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.takeCompositionChanges();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.takeCompositionChanges();world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 1; });world.ensureTransformsComposed();expect(ids(world)).toEqual([]);@@ -360,16 +362,16 @@ describe.skipIf(!HAS_WASM)('the composition reports what it changed', () => {const { world, a } = scene();world.setTransformChangeTracking(true);world.ensureTransformsComposed();- const first = world.lastComposition()!.serial;+ const first = world.compositionChanges()!.serial;// Nothing was invalidated, so nothing composed.world.ensureTransformsComposed();world.ensureTransformsComposed();- expect(world.lastComposition()!.serial).toBe(first);+ expect(world.compositionChanges()!.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);+ expect(world.compositionChanges()!.serial).toBe(first + 1);world.setTransformChangeTracking(false);world.disconnectCpp();});@@ -378,11 +380,11 @@ describe.skipIf(!HAS_WASM)('the composition reports what it changed', () => {const { world, a } = scene();world.setTransformChangeTracking(false);world.ensureTransformsComposed();- const before = world.lastComposition()!.serial;+ const before = world.compositionChanges()!.serial;world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 3; });world.ensureTransformsComposed();- const after = world.lastComposition()!;+ const after = world.compositionChanges()!;expect(after.serial).toBe(before + 1);expect(after.changed.length).toBe(0);world.disconnectCpp();@@ -392,7 +394,7 @@ describe.skipIf(!HAS_WASM)('the composition reports what it changed', () => {const first = scene();first.world.setTransformChangeTracking(true);first.world.ensureTransformsComposed();- const seen = first.world.lastComposition()!.serial;+ const seen = first.world.compositionChanges()!.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.@@ -403,11 +405,74 @@ describe.skipIf(!HAS_WASM)('the composition reports what it changed', () => {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);+ expect(first.world.compositionChanges()!.serial).toBeGreaterThan(seen + 1);first.world.setTransformChangeTracking(false);first.world.disconnectCpp();});+ it('accumulates across compositions, because a renderer composes every frame', () => {+ const { world, a, b } = scene();+ world.setTransformChangeTracking(true);+ world.ensureTransformsComposed();+ world.takeCompositionChanges();++ // Three compositions between one consumer's reads is the ordinary case:+ // a listen server composes each frame and samples every few. Reporting+ // only the last one would drop the first two.+ world.update(a, Transform, (t) => { (t as { position: { x: number } }).position.x = 11; });+ world.ensureTransformsComposed();+ world.update(b, Transform, (t) => { (t as { position: { x: number } }).position.x = 22; });+ world.ensureTransformsComposed();++ expect([...ids(world)].sort()).toEqual([a as number, b as number].sort());+ // Reading does not consume: a consumer that throws half way through has+ // not acknowledged, and is handed the same work again.+ expect(ids(world).length).toBe(2);+ world.takeCompositionChanges();+ expect(ids(world)).toEqual([]);+ world.setTransformChangeTracking(false);+ world.disconnectCpp();+ });++ it('drops a set that grew past the rebuild it would save', () => {+ const app = App.new();+ const registry = new module.Registry() as unknown as CppRegistry;+ app.connectCpp(registry, module);+ const world = app.world;+ const all = [];+ for (let i = 0; i < 8; i++) {+ const e = world.spawn();+ world.insert(e, Transform, { position: { x: i + 1, y: 0, z: 0 } });+ all.push(e);+ }+ world.setTransformChangeTracking(true);+ world.ensureTransformsComposed();+ world.takeCompositionChanges();++ // Every entity, twice, with nothing acknowledged in between: more pending+ // changes than a composition writes, so replaying them costs more than+ // reading the world again.+ for (let pass = 1; pass <= 2; pass++) {+ for (const e of all) {+ world.update(e, Transform,+ (t) => { (t as { position: { x: number } }).position.x += 10 * pass; });+ }+ world.ensureTransformsComposed();+ }+ const pending = world.compositionChanges()!;+ expect(pending.overflowed).toBe(true);+ expect(pending.changed.length).toBe(0);++ // And it stays dropped until acknowledged, rather than half-filling again.+ world.update(all[0]!, Transform, (t) => { (t as { position: { x: number } }).position.x = 900; });+ world.ensureTransformsComposed();+ expect(world.compositionChanges()!.overflowed).toBe(true);+ world.takeCompositionChanges();+ expect(world.compositionChanges()!.overflowed).toBe(false);+ world.setTransformChangeTracking(false);+ 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;@@ -419,7 +484,7 @@ describe.skipIf(!HAS_WASM)('the composition reports what it changed', () => {},});expect(app.world.setTransformChangeTracking(true)).toBe(false);- expect(app.world.lastComposition()).toBeNull();+ expect(app.world.compositionChanges()).toBeNull();app.world.disconnectCpp();});});diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 05597f1be..da3244680 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -656,10 +656,10 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {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(+ // What every composition since the last acknowledgement changed: the entities+ // as an address into linear memory, because a JS array of a hundred thousand+ // handles would cost more than the walk that found them.+ emscripten::function("transform_compositionChanges", emscripten::optional_override([]() -> emscripten::val {static_assert(sizeof(esengine::Entity) == sizeof(esengine::u32),"the changed set is read as a Uint32Array of raw ids");@@ -667,12 +667,18 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {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("overflowed", ts && ts->changesOverflowed());+ out.set("count", ts ? static_cast<esengine::u32>(ts->pendingChanges().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);+ reinterpret_cast<uintptr_t>(ts->pendingChanges().data())) : 0u);return out;}));+ // Applied: the set starts again. Separate from the read so a consumer that+ // throws half way through has not acknowledged, and gets it again.+ emscripten::function("transform_takeChanges", emscripten::optional_override([]() {+ if (auto* ts = esengine::ctx().tryGet<esengine::ecs::TransformSystem>()) ts->takeChanges();+ }));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 c0ba2fd22..904ad561a 100644--- a/src/esengine/ecs/TransformSystem.hpp+++ b/src/esengine/ecs/TransformSystem.hpp@@ -74,10 +74,8 @@ public:/*** @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.+ * @details A consumer compares it with the serial at its last acknowledgement+ * to answer "has anything composed since?" without looking at a set.*/u32 compositionSerial() const { return serial_; }@@ -86,14 +84,36 @@ public:* @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.+ * @note One consumer. The pending set is a mailbox, not a per-reader journal:+ * whoever acknowledges empties it for everyone.*/- void setChangeTracking(bool on) { tracking_ = on; if (!on) changed_.clear(); }+ void setChangeTracking(bool on) {+ tracking_ = on;+ if (!on) takeChanges();+ }bool changeTracking() const { return tracking_; }- /** @brief The entities the LAST composition changed; empty unless tracking. */- const std::vector<Entity>& lastChanged() const { return changed_; }+ /**+ * @brief What every composition since the last acknowledgement changed+ * @details ACCUMULATED, not per-composition: a renderer composes each frame+ * and a consumer samples every few. Duplicates are kept, because+ * applying an entity twice is idempotent for every consumer.+ */+ const std::vector<Entity>& pendingChanges() const { return changed_; }++ /**+ * @brief Whether the pending set was dropped for being bigger than a rebuild+ * @details Once more entities have changed than a composition writes, reading+ * them all again is cheaper than replaying the list — so it is+ * dropped and the consumer is told to rebuild instead of handed a+ * set that costs more than the thing it saves.+ */+ bool changesOverflowed() const { return overflowed_; }- /** @brief How many entities that composition wrote, changed or not. */+ /** @brief Acknowledge the pending set: it is applied, and starts again. */+ void takeChanges() { changed_.clear(); overflowed_ = false; }++ /** @brief How many entities the last composition wrote, changed or not. */u32 visited() const { return visited_; }private:@@ -116,6 +136,7 @@ private:std::vector<Entity> changed_;u32 visited_ = 0;u32 serial_ = 0;+ bool overflowed_ = false;/*** @brief One composition, whoever asked for it@@ -126,9 +147,14 @@ private:*/void compose(Registry& registry) {visited_ = 0;- if (tracking_) { changed_.clear(); changedOut_ = &changed_; }+ if (tracking_ && !overflowed_) changedOut_ = &changed_;updateDirtyTransforms(registry);changedOut_ = nullptr;+ // Past the point where replaying the list beats re-reading the world.+ if (changed_.size() > visited_) {+ changed_.clear();+ overflowed_ = true;+ }++serial_;markComposed(registry);}