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): intern user component _id by name (stable identity)

esengine598e9c28511e
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index ac80850e4..6850729b0 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -166,6 +166,24 @@ function classifyKeys(obj: object): { flatKeys: string[]; objectKeys: string[];
return hasNested ? { flatKeys, objectKeys, arrayKeys } : null;
}
+// User component identity is interned by name: the same name always maps to the same
+// _id symbol, module-globally (like builtins, which are defined once at load). The
+// World keys storage/queries/change-tracking by _id, so a stable-by-name id lets a
+// re-imported project bundle (hot reload) resolve to the live World's existing
+// component storage instead of minting a fresh identity that silently misses every
+// existing entity. Component DATA stays isolated per-App at the World/storage layer,
+// not at the id, so sharing ids by name across contexts is safe — the same reason
+// builtins share one global id across every App. See docs/REARCH_HOT_RELOAD.md §3.
+const componentIdRegistry = new Map<string, symbol>();
+function componentId(name: string): symbol {
+ let id = componentIdRegistry.get(name);
+ if (id === undefined) {
+ id = Symbol(`Component_${name}`);
+ componentIdRegistry.set(name, id);
+ }
+ return id;
+}
+
function createComponentDef<T extends object>(
name: string,
defaults: T,
@@ -174,7 +192,7 @@ function createComponentDef<T extends object>(
const keyInfo = classifyKeys(defaults);
const defaultsRec = defaults as Record<string, unknown>;
return {
- _id: Symbol(`Component_${name}`),
+ _id: componentId(name),
_name: name,
_default: defaults,
_builtin: false as const,
diff --git a/sdk/tests/component-id-stable.test.ts b/sdk/tests/component-id-stable.test.ts
new file mode 100644
index 000000000..ba66b30c3
--- /dev/null
+++ b/sdk/tests/component-id-stable.test.ts
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { defineComponent, clearUserComponents, getComponent } from '../src/component';
+import { AppContext, getDefaultContext, setDefaultContext } from '../src/context';
+
+// RC10 P3 prerequisite: user component _id is interned by name (stable, module-global)
+// so a re-imported project bundle resolves to the live World's existing component
+// storage (which the World keys by _id) instead of minting a fresh identity that would
+// silently miss every existing entity. See docs/REARCH_HOT_RELOAD.md §3.
+describe('stable component _id by name (RC10 P3 prereq)', () => {
+ const original = getDefaultContext();
+ beforeEach(() => clearUserComponents());
+ afterEach(() => {
+ setDefaultContext(original);
+ clearUserComponents();
+ });
+
+ it('keeps the same _id when redefined after clearUserComponents (the hot-reload case)', () => {
+ const id1 = defineComponent('Patrol', { speed: 60 })._id;
+ clearUserComponents();
+ // Re-import after a code edit: the def object is new (and its shape may even
+ // differ), but the identity the World stores under must be the same.
+ const b = defineComponent('Patrol', { speed: 60, range: 120 });
+ expect(b._id).toBe(id1);
+ });
+
+ it('gives distinct names distinct ids', () => {
+ expect(defineComponent('IdA', { x: 0 })._id).not.toBe(defineComponent('IdB', { x: 0 })._id);
+ });
+
+ it('returns the existing def within one context (defineComponent dedup unchanged)', () => {
+ const a = defineComponent('Dup', { x: 0 });
+ expect(defineComponent('Dup', { x: 999 })).toBe(a);
+ });
+
+ it('shares the id by name across isolated contexts but keeps per-context defs', () => {
+ const ctxA = new AppContext();
+ const ctxB = new AppContext();
+
+ setDefaultContext(ctxA);
+ const a = defineComponent('Shared', { x: 0 });
+ setDefaultContext(ctxB);
+ const b = defineComponent('Shared', { x: 0 });
+
+ expect(b._id).toBe(a._id); // same stable identity, like a builtin
+ expect(b).not.toBe(a); // but the registries are isolated — distinct def objects
+
+ setDefaultContext(ctxA);
+ expect(getComponent('Shared')).toBe(a);
+ setDefaultContext(ctxB);
+ expect(getComponent('Shared')).toBe(b);
+ });
+});