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
refactor(ecs): expose bounded native entity change history
yhh4f559e1b4279
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 @experimentaldiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex cd5152dfb..7eb22f7e6 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -404,11 +404,15 @@ provideReplacementDevice: (() => boolean) | undefinedrecoverDevice: (() => boolean) | undefinedregistryLayoutEpoch: (registry: CppRegistry) => numberregistry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => void+registry_entityChangeSequence: ((registry: CppRegistry) => number) | undefinedregistry_getCameraEntities: (registry: CppRegistry) => number[]registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefinedregistry_getCanvasEntity: (registry: CppRegistry) => numberregistry_getGeneration: (registry: CppRegistry, entity: number) => number+registry_readEntityChanges: ((registry: CppRegistry, after: number, outputPtr: number, capacity: number) => number) | undefinedregistry_readWorldPoses2D: ((registry: CppRegistry, entitiesPtr: number, count: number, outputPtr: number) => number) | undefined+registry_unwatchEntityChanges: ((registry: CppRegistry, reader: number) => void) | undefined+registry_watchEntityChanges: ((registry: CppRegistry) => number) | undefinedrenderer_begin: (matrixPtr: number, targetHandle: number, clearFlags: number, r: number, g: number, b: number, a: number, clearX: number, clearY: number, clearW: number, clearH: number) => voidrenderer_beginFrame: (elapsedSec: number) => voidrenderer_beginScreenOverlay: ((projectionPtr: number, vpX: number, vpY: number, vpW: number, vpH: number) => void) | undefineddiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 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.tsindex 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 ofdiff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 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.tsindex 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.tsnew file mode 100644index 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.cppindex 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.hppindex 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);#endifu32 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.cppindex 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.cppindex 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.hppnew file mode 100644index 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::ecsdiff --git a/src/esengine/ecs/Registry.hpp b/src/esengine/ecs/Registry.hppindex 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.hppindex 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.cppindex 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.mjsindex 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':