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): the change set is what happened since you last acknowledged

esenginee933eebbf87c
diff --git a/bench/transform-composition/arm.mjs b/bench/transform-composition/arm.mjs
index 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.cpp
index 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, JS
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.
+ * 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 eshost
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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) => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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) => void
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 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) => 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_compositionChanges: (() => { serial: number; tracking: boolean; overflowed: boolean; count: number; visited: 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_takeChanges: (() => 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 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) => void
diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.cpp
index 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_PARTICLES
diff --git a/src/esengine/ecs/TransformSystem.hpp b/src/esengine/ecs/TransformSystem.hpp
index 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);
}