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.

refactor(ecs): expose bounded native entity change history

yhh4f559e1b4279
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 36254e0cc..bd5e61c3b 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 115 public · 91 beta · 1581 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"0c84aca932384575"
+"4a247e158faf0865"
```
## ANCHOR_AXES — const @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index f28111672..e088c073e 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 115 public · 96 beta · 1600 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"0c84aca932384575"
+"4a247e158faf0865"
```
## ANCHOR_AXES — const @experimental
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index cd5152dfb..7eb22f7e6 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -404,11 +404,15 @@ provideReplacementDevice: (() => boolean) | undefined
recoverDevice: (() => boolean) | undefined
registryLayoutEpoch: (registry: CppRegistry) => number
registry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => void
+registry_entityChangeSequence: ((registry: CppRegistry) => number) | undefined
registry_getCameraEntities: (registry: CppRegistry) => number[]
registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefined
registry_getCanvasEntity: (registry: CppRegistry) => number
registry_getGeneration: (registry: CppRegistry, entity: number) => number
+registry_readEntityChanges: ((registry: CppRegistry, after: number, outputPtr: number, capacity: number) => number) | undefined
registry_readWorldPoses2D: ((registry: CppRegistry, entitiesPtr: number, count: number, outputPtr: number) => number) | undefined
+registry_unwatchEntityChanges: ((registry: CppRegistry, reader: number) => void) | undefined
+registry_watchEntityChanges: ((registry: CppRegistry) => number) | undefined
renderer_begin: (matrixPtr: number, targetHandle: number, clearFlags: number, r: number, g: number, b: number, a: number, clearX: number, clearY: number, clearW: number, clearH: number) => void
renderer_beginFrame: (elapsedSec: number) => void
renderer_beginScreenOverlay: ((projectionPtr: number, vpX: number, vpY: number, vpW: number, vpH: number) => void) | undefined
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index b89c831e2..b102a3493 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -123,9 +123,13 @@ export interface NativeEngineApi {
probe_volume_create?(resX: number, resY: number, resZ: number, shPtr: number): number;
probe_volume_release?(volumeHandle: number): void;
registry_batchSyncPhysicsTransforms?(registry: unknown, bufferPtr: number, count: number, ppu: number): void;
+ registry_entityChangeSequence?(registry: unknown): number;
registry_getCanvasEntity?(registry: unknown): number;
registry_getGeneration?(registry: unknown, entity: number): number;
+ registry_readEntityChanges?(registry: unknown, after: number, outputPtr: number, capacity: number): number;
registry_readWorldPoses2D?(registry: unknown, entitiesPtr: number, count: number, outputPtr: number): number;
+ registry_unwatchEntityChanges?(registry: unknown, reader: number): void;
+ registry_watchEntityChanges?(registry: unknown): number;
renderer_begin?(matrixPtr: number, targetHandle: number, clearFlags: number, r: number, g: number, b: number, a: number, clearX: number, clearY: number, clearW: number, clearH: number): void;
renderer_beginFrame?(elapsedSec: number): void;
renderer_beginScreenOverlay?(projectionPtr: number, vpX: number, vpY: number, vpW: number, vpH: number): void;
@@ -415,9 +419,13 @@ export function createNativeEngineApi(
bind('probe_volume_create', 'es_probe_volume_create', false);
bind('probe_volume_release', 'es_probe_volume_release', false);
bind('registry_batchSyncPhysicsTransforms', 'es_registry_batchSyncPhysicsTransforms', true);
+ bind('registry_entityChangeSequence', 'es_registry_entityChangeSequence', true);
bind('registry_getCanvasEntity', 'es_registry_getCanvasEntity', true);
bind('registry_getGeneration', 'es_registry_getGeneration', true);
+ bind('registry_readEntityChanges', 'es_registry_readEntityChanges', true);
bind('registry_readWorldPoses2D', 'es_registry_readWorldPoses2D', true);
+ bind('registry_unwatchEntityChanges', 'es_registry_unwatchEntityChanges', true);
+ bind('registry_watchEntityChanges', 'es_registry_watchEntityChanges', true);
bind('renderer_begin', 'es_renderer_begin', false);
bind('renderer_beginFrame', 'es_renderer_beginFrame', false);
bind('renderer_beginScreenOverlay', 'es_renderer_beginScreenOverlay', false);
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 784dbca35..77116980b 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '0c84aca932384575';
+export const ABI_LAYOUT_HASH = '4a247e158faf0865';
/**
* One asset-valued field of a component: which field, and what kind of
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 82d87749a..7db46f0fe 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -685,6 +685,10 @@ export interface ESEngineModule {
registry_getCameraEntities(registry: CppRegistry): number[];
getChildEntities(registry: CppRegistry, entity: number): number[];
registry_getGeneration(registry: CppRegistry, entity: number): number;
+ registry_watchEntityChanges?(registry: CppRegistry): number;
+ registry_unwatchEntityChanges?(registry: CppRegistry, reader: number): void;
+ registry_entityChangeSequence?(registry: CppRegistry): number;
+ registry_readEntityChanges?(registry: CppRegistry, after: number, outputPtr: number, capacity: number): number;
registry_batchSyncPhysicsTransforms(registry: CppRegistry, bufferPtr: number, count: number, ppu: number): void;
registry_readWorldPoses2D?(registry: CppRegistry, entitiesPtr: number, count: number, outputPtr: number): number;
diff --git a/sdk/src/wasm/constants.generated.ts b/sdk/src/wasm/constants.generated.ts
index b5cbafe98..52986d92b 100644
--- a/sdk/src/wasm/constants.generated.ts
+++ b/sdk/src/wasm/constants.generated.ts
@@ -14,6 +14,24 @@
/** C++ `CHUNK_SIZE` in `src/esengine/tilemap/TilemapSystem.hpp`. */
export const CHUNK_SIZE = 16;
+/** C++ `ENTITY_CHANGE_CAPACITY` in `src/esengine/ecs/EntityChangeJournal.hpp`. */
+export const ENTITY_CHANGE_CAPACITY = 4096;
+
+/** C++ `ENTITY_CHANGE_NO_COMPONENT` in `src/esengine/ecs/EntityChangeJournal.hpp`. */
+export const ENTITY_CHANGE_NO_COMPONENT = 4294967295;
+
+/** C++ `ENTITY_CHANGE_REPLACED` in `src/esengine/ecs/EntityChangeJournal.hpp`. */
+export const ENTITY_CHANGE_REPLACED = 4;
+
+/** C++ `ENTITY_CHANGE_RESET` in `src/esengine/ecs/EntityChangeJournal.hpp`. */
+export const ENTITY_CHANGE_RESET = 2;
+
+/** C++ `ENTITY_CHANGE_SUBTREE` in `src/esengine/ecs/EntityChangeJournal.hpp`. */
+export const ENTITY_CHANGE_SUBTREE = 1;
+
+/** C++ `ENTITY_CHANGE_WORDS` in `src/esengine/ecs/EntityChangeJournal.hpp`. */
+export const ENTITY_CHANGE_WORDS = 3;
+
/** C++ `ENTITY_POSE_2D_WORDS` in `src/esengine/core/EntityPose2D.hpp`. */
export const ENTITY_POSE_2D_WORDS = 4;
diff --git a/sdk/tests/entity-change-journal-wasm.test.ts b/sdk/tests/entity-change-journal-wasm.test.ts
new file mode 100644
index 000000000..16dbca123
--- /dev/null
+++ b/sdk/tests/entity-change-journal-wasm.test.ts
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import type { CppRegistry, ESEngineModule } from '../src/wasm';
+import type { EngineApi } from '../src/ecs/bridge/engineApi';
+import { createNativeEngineApi } from '../src/ecs/bridge/nativeEngineApi.generated';
+import { withMalloc } from '../src/wasm/wasmScratch';
+import {
+ ENTITY_CHANGE_CAPACITY, ENTITY_CHANGE_WORDS, ENTITY_CHANGE_SUBTREE, ENTITY_CHANGE_RESET,
+ ENTITY_CHANGE_REPLACED, ENTITY_CHANGE_NO_COMPONENT,
+} from '../src/wasm/constants.generated';
+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
+
+let core: ESEngineModule, api: EngineApi, registry: CppRegistry;
+const leases: number[] = [];
+const watch = () => {
+ const lease = api.registry_watchEntityChanges!(registry);
+ leases.push(lease);
+ return lease;
+};
+const sequence = () => api.registry_entityChangeSequence!(registry);
+function read(after: number, capacity = ENTITY_CHANGE_CAPACITY) {
+ return withMalloc(core, Math.max(1, capacity) * ENTITY_CHANGE_WORDS * 4, ptr => {
+ const count = api.registry_readEntityChanges!(registry, after, ptr, capacity);
+ const rows: { entity: number; flags: number }[] = [];
+ const components: number[] = [];
+ for (let i = 0; i < count; ++i) {
+ const at = (ptr >>> 2) + i * ENTITY_CHANGE_WORDS;
+ rows.push({ entity: core.HEAPU32[at], flags: core.HEAPU32[at + 1] });
+ components.push(core.HEAPU32[at + 2]);
+ }
+ return { count, rows, components };
+ });
+}
+
+describe.skipIf(!HAS_WASM)('native registry entity change journal', () => {
+ beforeAll(async () => { core = await loadWasmModule(); api = core as EngineApi; });
+ afterEach(() => {
+ for (const lease of leases.splice(0)) api.registry_unwatchEntityChanges!(registry, lease);
+ registry?.delete();
+ });
+ const start = () => { registry = new core.Registry(); };
+
+ it('retains nothing without a reader and releases the final reader storage', () => {
+ start(); registry.create();
+ expect(read(0).count).toBe(-1);
+ watch(); expect(read(sequence(), 0).count).toBe(0);
+ registry.create(); expect(read(0).count).toBe(1);
+ api.registry_unwatchEntityChanges!(registry, leases.pop()!);
+ expect(read(0).count).toBe(-1);
+ watch(); expect(sequence()).toBe(0);
+ expect(read(0).count).toBe(0);
+ });
+
+ it('keeps readers independent and preserves generations across recycled entities', () => {
+ start(); const first = watch(), original = registry.create();
+ const cursor = sequence(); watch(); registry.destroy(original);
+ const replacement = registry.create();
+ expect(replacement).not.toBe(original);
+ expect(read(0).rows.map(row => row.entity)).toEqual([original, original, replacement]);
+ expect(read(cursor).rows.map(row => row.entity)).toEqual([original, replacement]);
+ api.registry_unwatchEntityChanges!(registry, first);
+ api.registry_unwatchEntityChanges!(registry, first);
+ expect(read(0).count).toBe(3);
+ });
+
+ it('requires a full refresh after overflow instead of returning a truncated delta', () => {
+ start(); watch();
+ for (let i = 0; i <= ENTITY_CHANGE_CAPACITY; ++i) registry.create();
+ expect(read(0).count).toBe(-1);
+ expect(read(1).count).toBe(ENTITY_CHANGE_CAPACITY);
+ expect(read(sequence() - 1).count).toBe(1);
+ expect(read(sequence() - 1, 0).count).toBe(-1);
+ });
+
+ it('rejects invalid cursors and output capacities', () => {
+ start(); watch(); registry.create();
+ for (const cursor of [-1, .5, NaN, Infinity, sequence() + 1]) expect(read(cursor).count).toBe(-1);
+ expect(api.registry_readEntityChanges!(registry, 0, 0, -1)).toBe(-1);
+ expect(api.registry_readEntityChanges!(registry, 0, 0, ENTITY_CHANGE_CAPACITY + 1)).toBe(-1);
+ expect(api.registry_readEntityChanges!(registry, 0, 1, 1)).toBe(-1);
+ });
+
+ it('marks native activity and hierarchy changes by subtree without invalidating unrelated entities', () => {
+ start();
+ const parent = registry.create(), child = registry.create(), unrelated = registry.create();
+ registry.setEntityEnabled!(unrelated, false); watch();
+ const added = registry.create();
+ registry.setParent(child, parent);
+ registry.setEntityEnabled!(parent, false);
+ const rows = read(0).rows;
+ expect(rows.some(row => row.flags & ENTITY_CHANGE_RESET)).toBe(false);
+ expect(rows).toContainEqual({ entity: added, flags: 0 });
+ expect(rows.some(row => row.entity === child && (row.flags & ENTITY_CHANGE_SUBTREE))).toBe(true);
+ expect(rows.some(row => row.entity === parent && (row.flags & ENTITY_CHANGE_SUBTREE))).toBe(true);
+ const cursor = sequence(); registry.destroy(parent);
+ expect(read(cursor).rows).toContainEqual({ entity: child, flags: ENTITY_CHANGE_SUBTREE });
+ });
+
+ it('records generated native component additions, replacements and removals', () => {
+ start(); const entity = registry.create(); watch();
+ const value = { linear: { x: 1, y: 2, z: 0 }, angular: { x: 0, y: 0, z: 0 } };
+ registry.addVelocity(entity, value);
+ registry.addVelocity(entity, { ...value, linear: { x: 4, y: 5, z: 0 } });
+ registry.removeVelocity(entity);
+ const result = read(0);
+ expect(result.rows).toEqual([
+ { entity, flags: 0 }, { entity, flags: ENTITY_CHANGE_REPLACED }, { entity, flags: 0 },
+ ]);
+ expect(result.components[0]).not.toBe(ENTITY_CHANGE_NO_COMPONENT);
+ expect(new Set(result.components).size).toBe(1);
+ });
+});
+
+it('routes the same journal API through the native host with its implicit registry', () => {
+ const calls: unknown[][] = [];
+ const api = createNativeEngineApi({
+ es_registry_watchEntityChanges: (...args: unknown[]) => { calls.push(args); return 11; },
+ es_registry_unwatchEntityChanges: (...args: unknown[]) => { calls.push(args); },
+ es_registry_entityChangeSequence: (...args: unknown[]) => { calls.push(args); return 2 ** 32 + 9; },
+ es_registry_readEntityChanges: (...args: unknown[]) => { calls.push(args); return 2; },
+ });
+ expect(api.registry_watchEntityChanges!({})).toBe(11);
+ expect(api.registry_entityChangeSequence!({})).toBe(2 ** 32 + 9);
+ expect(api.registry_readEntityChanges!({}, 2 ** 32 + 7, 16, 4)).toBe(2);
+ api.registry_unwatchEntityChanges!({}, 11);
+ expect(calls).toEqual([[], [], [2 ** 32 + 7, 16, 4], [11]]);
+});
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index a0e99ebfa..db6c14968 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -1215,6 +1215,17 @@ u32 registry_getGeneration(ecs::Registry& registry, u32 entity) {
return Entity::fromRaw(entity).generation();
}
+u32 registry_watchEntityChanges(ecs::Registry& registry) { return registry.watchEntityChanges(); }
+void registry_unwatchEntityChanges(ecs::Registry& registry, u32 reader) { registry.unwatchEntityChanges(reader); }
+double registry_entityChangeSequence(ecs::Registry& registry) { return registry.entityChangeSequence(); }
+int registry_readEntityChanges(ecs::Registry& registry, double after, uintptr_t outputPtr, int capacity) {
+ if (capacity < 0 || capacity > static_cast<int>(ecs::ENTITY_CHANGE_CAPACITY)
+ || outputPtr % alignof(ecs::EntityChangeRow)) return -1;
+ if (capacity == 0) return registry.readEntityChanges(after, {});
+ auto* rows = boundarySpanMut<ecs::EntityChangeRow>(outputPtr, static_cast<u64>(capacity), "registry_readEntityChanges");
+ return rows ? registry.readEntityChanges(after, {rows, static_cast<usize>(capacity)}) : -1;
+}
+
int registry_readWorldPoses2D(ecs::Registry& registry, uintptr_t entitiesPtr, int count, uintptr_t outputPtr) {
if (count <= 0 || entitiesPtr % alignof(u32) || outputPtr % alignof(EntityPose2D)) return 0;
const auto* ids = boundarySpan<u32>(entitiesPtr, static_cast<u64>(count), "registry_readWorldPoses2D.entities");
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index 6ba6ad041..9cf1f1d30 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -319,6 +319,12 @@ emscripten::val registry_getCameraEntities(ecs::Registry& registry);
emscripten::val getChildEntities(ecs::Registry& registry, u32 entity);
#endif
u32 registry_getGeneration(ecs::Registry& registry, u32 entity);
+u32 registry_watchEntityChanges(ecs::Registry& registry);
+void registry_unwatchEntityChanges(ecs::Registry& registry, u32 reader);
+double registry_entityChangeSequence(ecs::Registry& registry);
+// Output contains entity/flags/component-type rows. Returns -1 when the cursor or capacity
+// cannot cover the retained history; the caller must perform a full refresh.
+int registry_readEntityChanges(ecs::Registry& registry, double after, uintptr_t outputPtr, int capacity);
// Read composed world poses for valid, active entities with a Transform.
// Output has room for count EntityPose2D rows; returns the number written.
int registry_readWorldPoses2D(ecs::Registry& registry, uintptr_t entitiesPtr, int count, uintptr_t outputPtr);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 6bff22314..d4973a5e1 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -3674,7 +3674,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "0c84aca932384575";
+static const char* kEsAbiLayoutHash = "4a247e158faf0865";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index e1986ade3..8fb09fc44 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -782,6 +782,10 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("registry_getGeneration", &esengine::registry_getGeneration);
emscripten::function("registry_batchSyncPhysicsTransforms", &esengine::registry_batchSyncPhysicsTransforms);
emscripten::function("registry_readWorldPoses2D", &esengine::registry_readWorldPoses2D);
+ emscripten::function("registry_watchEntityChanges", &esengine::registry_watchEntityChanges);
+ emscripten::function("registry_unwatchEntityChanges", &esengine::registry_unwatchEntityChanges);
+ emscripten::function("registry_entityChangeSequence", &esengine::registry_entityChangeSequence);
+ emscripten::function("registry_readEntityChanges", &esengine::registry_readEntityChanges);
emscripten::function("gl_enableErrorCheck", &esengine::gl_enableErrorCheck);
emscripten::function("gl_checkErrors", &esengine::gl_checkErrors);
diff --git a/src/esengine/ecs/EntityChangeJournal.hpp b/src/esengine/ecs/EntityChangeJournal.hpp
new file mode 100644
index 000000000..0ec1b547b
--- /dev/null
+++ b/src/esengine/ecs/EntityChangeJournal.hpp
@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#pragma once
+#include "../core/Types.hpp"
+#include "../core/Reflection.hpp"
+#include <algorithm>
+#include <cmath>
+#include <span>
+#include <unordered_set>
+#include <vector>
+
+namespace esengine::ecs {
+ES_CONST()
+static constexpr u32 ENTITY_CHANGE_WORDS = 3;
+ES_CONST()
+static constexpr u32 ENTITY_CHANGE_NO_COMPONENT = 4294967295;
+ES_CONST()
+static constexpr u32 ENTITY_CHANGE_CAPACITY = 4096;
+ES_CONST()
+static constexpr u32 ENTITY_CHANGE_SUBTREE = 1;
+ES_CONST()
+static constexpr u32 ENTITY_CHANGE_RESET = 2;
+ES_CONST()
+static constexpr u32 ENTITY_CHANGE_REPLACED = 4;
+
+// Component IDs belong to this host's type domain, never to persisted data.
+// Entity-level events carry ENTITY_CHANGE_NO_COMPONENT.
+struct EntityChangeRow { u32 entity; u32 flags; u32 component; };
+static_assert(sizeof(EntityChangeRow) == ENTITY_CHANGE_WORDS * sizeof(u32));
+
+/** Independent cursors share bounded history. Exhausted or invalid cursors must
+ * rescan; reading never consumes another observer's rows. No readers means no
+ * retained storage or writes. Raw component references require an explicit record. */
+class EntityChangeJournal {
+public:
+ u32 watch() {
+ if (readers_.empty()) {
+ rows_.resize(ENTITY_CHANGE_CAPACITY);
+ sequence_ = 0;
+ exhausted_ = false;
+ }
+ do { ++next_reader_; } while (!next_reader_ || readers_.contains(next_reader_));
+ readers_.insert(next_reader_);
+ return next_reader_;
+ }
+ void unwatch(u32 reader) {
+ readers_.erase(reader);
+ if (readers_.empty()) std::vector<EntityChangeRow>().swap(rows_);
+ }
+ double sequence() const { return static_cast<double>(sequence_); }
+ usize readerCount() const { return readers_.size(); }
+ usize retainedRows() const { return rows_.empty() ? 0 : std::min<u64>(sequence_, ENTITY_CHANGE_CAPACITY); }
+
+ void record(u32 entity, u32 flags = 0, u32 component = ENTITY_CHANGE_NO_COMPONENT) {
+ if (readers_.empty()) return;
+ // Saturation preserves the JS number contract by requiring a rescan.
+ if (sequence_ == MAX_SEQUENCE) { exhausted_ = true; return; }
+ ++sequence_;
+ rows_[sequence_ % ENTITY_CHANGE_CAPACITY] = {entity, flags, component};
+ }
+
+ i32 read(double after, std::span<EntityChangeRow> output) const {
+ if (rows_.empty() || exhausted_ || !std::isfinite(after) || after < 0
+ || after > sequence() || std::floor(after) != after) return -1;
+ const auto cursor = static_cast<u64>(after);
+ const auto count = sequence_ - cursor;
+ if (count > ENTITY_CHANGE_CAPACITY || count > output.size()) return -1;
+ for (u64 i = 0; i < count; ++i) output[i] = rows_[(cursor + i + 1) % ENTITY_CHANGE_CAPACITY];
+ return static_cast<i32>(count);
+ }
+
+private:
+ static constexpr u64 MAX_SEQUENCE = (u64{1} << 53) - 1;
+ std::vector<EntityChangeRow> rows_;
+ std::unordered_set<u32> readers_;
+ u64 sequence_ = 0;
+ u32 next_reader_ = 0;
+ bool exhausted_ = false;
+};
+} // namespace esengine::ecs
diff --git a/src/esengine/ecs/Registry.hpp b/src/esengine/ecs/Registry.hpp
index 9e8b852cd..fecaa8898 100644
--- a/src/esengine/ecs/Registry.hpp
+++ b/src/esengine/ecs/Registry.hpp
@@ -27,6 +27,7 @@
#include "SparseSet.hpp"
#include "View.hpp"
#include "ActiveView.hpp"
+#include "EntityChangeJournal.hpp"
#include "components/Hierarchy.hpp"
#include "../events/Sink.hpp"
@@ -101,6 +102,7 @@ public:
disabled_[e.index()] = off;
if (off) ++disabled_count_; else --disabled_count_;
++activity_epoch_;
+ recordEntityChange(e, ENTITY_CHANGE_SUBTREE);
return true;
}
bool isEntityEnabled(Entity e) const {
@@ -115,7 +117,22 @@ public:
}
bool hasInactiveEntities() const { return disabled_count_ != 0; }
u32 activityEpoch() const { return activity_epoch_; }
- void invalidateActivityHierarchy() { if (disabled_count_) ++activity_epoch_; }
+ void invalidateActivityHierarchy(Entity root = INVALID_ENTITY) {
+ if (disabled_count_) ++activity_epoch_;
+ recordEntityChange(root, root == INVALID_ENTITY ? ENTITY_CHANGE_RESET : ENTITY_CHANGE_SUBTREE);
+ }
+
+ u32 watchEntityChanges() { return entity_changes_.watch(); }
+ void unwatchEntityChanges(u32 reader) { entity_changes_.unwatch(reader); }
+ double entityChangeSequence() const { return entity_changes_.sequence(); }
+ i32 readEntityChanges(double after, std::span<EntityChangeRow> output) const {
+ return entity_changes_.read(after, output);
+ }
+ // Raw component producers publish their logical mutation here; merely
+ // borrowing a mutable reference does not announce a write.
+ void recordEntityChange(Entity entity, u32 flags = 0, u32 component = ENTITY_CHANGE_NO_COMPONENT) {
+ entity_changes_.record(entity.id(), flags, component);
+ }
template<class... C> auto activeView() {
return ActiveView<View<C...>, Registry>(view<C...>(), *this);
@@ -214,6 +231,13 @@ public:
void destroy(Entity entity) {
if (!valid(entity)) return;
+ if (entity_changes_.readerCount()) {
+ recordEntityChange(entity);
+ if (const auto* children = tryGet<Children>(entity)) {
+ for (const auto child : children->entities) recordEntityChange(child, ENTITY_CHANGE_SUBTREE);
+ }
+ }
+
const u32 idx = entity.index();
// Mark invalid up-front so a re-entrant destroy(entity) from an onDestroy
@@ -327,7 +351,7 @@ public:
auto& pool = assurePool<T>();
auto& result = pool.emplace(entity, std::forward<Args>(args)...);
component_masks_[entity.index()].set(componentTypeId<T>());
- if constexpr (std::is_same_v<T, Parent> || std::is_same_v<T, Children>) invalidateActivityHierarchy();
+ recordComponentChange<T>(entity);
return result;
}
@@ -349,12 +373,12 @@ public:
if (pool.contains(entity)) {
auto& comp = pool.get(entity);
comp = T(std::forward<Args>(args)...);
- if constexpr (std::is_same_v<T, Parent> || std::is_same_v<T, Children>) invalidateActivityHierarchy();
+ recordComponentChange<T>(entity, ENTITY_CHANGE_REPLACED);
return comp;
}
auto& result = pool.emplace(entity, std::forward<Args>(args)...);
component_masks_[entity.index()].set(componentTypeId<T>());
- if constexpr (std::is_same_v<T, Parent> || std::is_same_v<T, Children>) invalidateActivityHierarchy();
+ recordComponentChange<T>(entity);
return result;
}
@@ -368,9 +392,9 @@ public:
template<typename T>
void remove(Entity entity) {
auto* pool = getPool<T>();
- if (pool) {
+ if (pool && pool->contains(entity)) {
pool->remove(entity);
- if constexpr (std::is_same_v<T, Parent> || std::is_same_v<T, Children>) invalidateActivityHierarchy();
+ recordComponentChange<T>(entity);
const u32 idx = entity.index();
if (idx < component_masks_.size()) {
component_masks_[idx].clear(componentTypeId<T>());
@@ -439,6 +463,7 @@ public:
ES_VERIFY_FATAL(valid(entity), invalidEntityMessage("getOrEmplace", entity));
auto& result = pool.emplace(entity, std::forward<Args>(args)...);
component_masks_[entity.index()].set(componentTypeId<T>());
+ recordComponentChange<T>(entity);
return result;
}
@@ -517,6 +542,7 @@ public:
* @details Resets the registry to its initial empty state.
*/
void clear() {
+ recordEntityChange(INVALID_ENTITY, ENTITY_CHANGE_RESET);
for (auto& pool : pools_) {
if (pool) {
pool->clear();
@@ -776,12 +802,14 @@ private:
entityValid_[index] = true;
disabled_[index] = 0;
destruction_pending_[index] = 0;
- invalidateActivityHierarchy();
+ if (disabled_count_) ++activity_epoch_;
generations_[index] = (generations_[index] + 1) & Entity::GEN_MASK;
if (generations_[index] == 0) generations_[index] = 1;
component_masks_[index].reset();
++entity_count_;
- return Entity::make(index, generations_[index]);
+ const auto entity = Entity::make(index, generations_[index]);
+ recordEntityChange(entity);
+ return entity;
}
// =========================================================================
@@ -789,6 +817,16 @@ private:
// =========================================================================
std::vector<u8> entityValid_;
+ EntityChangeJournal entity_changes_;
+
+ template<typename T>
+ void recordComponentChange(Entity entity, u32 flags = 0) {
+ if constexpr (std::is_same_v<T, Parent>) flags |= ENTITY_CHANGE_SUBTREE;
+ if constexpr (std::is_same_v<T, Parent> || std::is_same_v<T, Children>) {
+ if (disabled_count_) ++activity_epoch_;
+ }
+ recordEntityChange(entity, flags, componentTypeId<T>());
+ }
std::vector<u8> disabled_;
usize disabled_count_ = 0;
u32 activity_epoch_ = 1;
diff --git a/src/esengine/ecs/TransformSystem.hpp b/src/esengine/ecs/TransformSystem.hpp
index 4156e8a79..b600b11af 100644
--- a/src/esengine/ecs/TransformSystem.hpp
+++ b/src/esengine/ecs/TransformSystem.hpp
@@ -412,7 +412,7 @@ inline bool setParent(Registry& registry, Entity child, Entity newParent) {
registry.emplace<TransformDirty>(child);
}
invalidateTransformComposition();
- registry.invalidateActivityHierarchy();
+ registry.invalidateActivityHierarchy(child);
return true;
}
diff --git a/tests/ecs/test_entity_activity.cpp b/tests/ecs/test_entity_activity.cpp
index 3eccccd74..73d7d94d6 100644
--- a/tests/ecs/test_entity_activity.cpp
+++ b/tests/ecs/test_entity_activity.cpp
@@ -2,6 +2,8 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include <doctest.h>
+#include <array>
+#include <limits>
#include "esengine/ecs/TransformSystem.hpp"
using namespace esengine;
@@ -80,3 +82,118 @@ TEST_CASE("unrelated entity churn leaves the all-active epoch stable") {
const auto e = r.create(); r.destroy(e);
CHECK(r.activityEpoch() == epoch);
}
+
+struct JournalPosition {
+ float x = 0, y = 0;
+ JournalPosition() = default;
+ JournalPosition(float a, float b) : x(a), y(b) {}
+};
+
+TEST_CASE("entity change history is bounded and owned by independent readers") {
+ using namespace esengine::ecs;
+ EntityChangeJournal journal;
+ journal.record(1);
+ CHECK(journal.retainedRows() == 0);
+ std::array<EntityChangeRow, ENTITY_CHANGE_CAPACITY> rows{};
+ CHECK(journal.read(0, rows) == -1);
+ const auto first = journal.watch();
+ journal.record(10);
+ const auto second = journal.watch();
+ const auto cursor = journal.sequence();
+ journal.record(20, ENTITY_CHANGE_REPLACED);
+ REQUIRE(journal.read(0, rows) == 2);
+ CHECK(rows[0].entity == 10);
+ CHECK(rows[1].flags == ENTITY_CHANGE_REPLACED);
+ REQUIRE(journal.read(cursor, rows) == 1);
+ CHECK(rows[0].entity == 20);
+ journal.unwatch(first);
+ CHECK(journal.readerCount() == 1);
+ CHECK(journal.read(0, rows) == 2);
+ journal.unwatch(first);
+ CHECK(journal.readerCount() == 1);
+ journal.unwatch(second);
+ CHECK(journal.readerCount() == 0);
+ CHECK(journal.retainedRows() == 0);
+ CHECK(journal.read(cursor, rows) == -1);
+}
+
+TEST_CASE("entity change overflow and invalid cursors refuse partial histories") {
+ using namespace esengine::ecs;
+ EntityChangeJournal journal;
+ journal.watch();
+ std::array<EntityChangeRow, ENTITY_CHANGE_CAPACITY> rows{};
+ for (esengine::u32 i = 1; i <= ENTITY_CHANGE_CAPACITY + 1; ++i) journal.record(i);
+ rows[0].entity = 99;
+ CHECK(journal.read(0, rows) == -1);
+ CHECK(rows[0].entity == 99);
+ CHECK(journal.read(1, std::span(rows).first(1)) == -1);
+ CHECK(rows[0].entity == 99);
+ REQUIRE(journal.read(1, rows) == ENTITY_CHANGE_CAPACITY);
+ CHECK(rows.front().entity == 2);
+ CHECK(rows.back().entity == ENTITY_CHANGE_CAPACITY + 1);
+ CHECK(journal.read(-1, rows) == -1);
+ CHECK(journal.read(1.5, rows) == -1);
+ CHECK(journal.read(journal.sequence() + 1, rows) == -1);
+ CHECK(journal.read(std::numeric_limits<double>::quiet_NaN(), rows) == -1);
+ CHECK(journal.read(std::numeric_limits<double>::infinity(), rows) == -1);
+ CHECK(journal.read(journal.sequence(), {}) == 0);
+}
+
+TEST_CASE("registry history covers component lifetime and explicit native writes") {
+ using namespace esengine::ecs;
+ Registry registry;
+ const auto reader = registry.watchEntityChanges();
+ const auto entity = registry.create();
+ registry.emplace<JournalPosition>(entity, 1, 2);
+ registry.emplaceOrReplace<JournalPosition>(entity, 3, 4);
+ registry.getOrEmplace<Sample>(entity);
+ const auto beforeBorrow = registry.entityChangeSequence();
+ registry.getOrEmplace<JournalPosition>(entity);
+ registry.get<JournalPosition>(entity).x = 5;
+ CHECK(registry.entityChangeSequence() == beforeBorrow);
+ registry.recordEntityChange(entity, ENTITY_CHANGE_REPLACED);
+ registry.remove<JournalPosition>(entity);
+ registry.destroy(entity);
+ std::array<EntityChangeRow, 16> rows{};
+ REQUIRE(registry.readEntityChanges(0, rows) == 7);
+ for (int i = 0; i < 7; ++i) CHECK(rows[i].entity == entity.id());
+ CHECK(rows[2].flags == ENTITY_CHANGE_REPLACED);
+ CHECK(rows[4].flags == ENTITY_CHANGE_REPLACED);
+ CHECK(rows[0].component == ENTITY_CHANGE_NO_COMPONENT);
+ CHECK(rows[1].component == componentTypeId<JournalPosition>());
+ CHECK(rows[2].component == componentTypeId<JournalPosition>());
+ CHECK(rows[3].component == componentTypeId<Sample>());
+ CHECK(rows[5].component == componentTypeId<JournalPosition>());
+ const auto cursor = registry.entityChangeSequence();
+ registry.clear();
+ REQUIRE(registry.readEntityChanges(cursor, rows) == 1);
+ CHECK(rows[0].flags == ENTITY_CHANGE_RESET);
+ registry.unwatchEntityChanges(reader);
+}
+
+TEST_CASE("hierarchy changes identify the child subtree even with inactive unrelated entities") {
+ using namespace esengine::ecs;
+ Registry registry;
+ const auto parent = registry.create(), child = registry.create(), inactive = registry.create();
+ registry.setEntityEnabled(inactive, false);
+ registry.watchEntityChanges();
+ const auto added = registry.create();
+ REQUIRE(setParent(registry, child, parent));
+ registry.setEntityEnabled(parent, false);
+ std::array<EntityChangeRow, 64> rows{};
+ const auto count = registry.readEntityChanges(0, rows);
+ REQUIRE(count > 0);
+ bool childSubtree = false, parentSubtree = false, newEntity = false;
+ for (int i = 0; i < count; ++i) {
+ CHECK((rows[i].flags & ENTITY_CHANGE_RESET) == 0);
+ if (rows[i].entity == child.id() && (rows[i].flags & ENTITY_CHANGE_SUBTREE)) childSubtree = true;
+ if (rows[i].entity == parent.id() && (rows[i].flags & ENTITY_CHANGE_SUBTREE)) parentSubtree = true;
+ if (rows[i].entity == added.id()) newEntity = true;
+ }
+ CHECK(childSubtree); CHECK(parentSubtree); CHECK(newEntity);
+ const auto cursor = registry.entityChangeSequence();
+ registry.destroy(parent);
+ REQUIRE(registry.readEntityChanges(cursor, rows) > 0);
+ CHECK(rows[1].entity == child.id());
+ CHECK(rows[1].flags == ENTITY_CHANGE_SUBTREE);
+}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 89ebe4bd9..e1e85d236 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'refactor(ecs): expose bounded native entity change history':
+ { internal: 'Adds opt-in native entity and component mutation history as infrastructure for sparse synchronization, with independent cursors, bounded storage, hierarchy roots and overflow/reset signals; no user-facing synchronization policy changes in this commit.' },
'perf(tilemap): synchronize collision by changed chunk':
{ note: 'Tile edits preserve unaffected collision chunks and contacts.' },
'refactor(editor): use shared tile collision chunk readback':