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.

fix(sdk): guarantee every engine component is registered (kill dual-source drop)

yhhe406f2f33bf9
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 96efdd617..2833c8721 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -461,6 +461,27 @@ export function defineBuiltin<T>(name: string, defaults: T, metadata?: Component
return def;
}
+/**
+ * Register every engine component in COMPONENT_META that doesn't already have a
+ * typed builtin const below. COMPONENT_META is EHT-generated from the C++
+ * `ES_COMPONENT` structs, so it is the single source of truth for *which*
+ * components exist; this guarantees each one is registered — and therefore
+ * loadable from a scene — even before someone hand-writes its typed
+ * `export const`. Without this backstop a newly-added C++ component had metadata
+ * + a binding but no registry entry, so `loadSceneData` silently dropped it.
+ *
+ * Idempotent (defineBuiltin no-ops on an already-registered builtin). The typed
+ * consts below remain the ergonomic, type-checked overlay; this only fills gaps.
+ * Called once from the package entry (index.ts / index.wechat.ts).
+ */
+export function ensureBuiltinComponentsRegistered(): void {
+ for (const name of Object.keys(COMPONENT_META)) {
+ if (!builtinRegistry.has(name)) {
+ defineBuiltin(name, COMPONENT_META[name].defaults as Record<string, unknown>);
+ }
+ }
+}
+
// =============================================================================
// Camera / Canvas Enums
// =============================================================================
diff --git a/sdk/src/index.ts b/sdk/src/index.ts
index d8874bbd5..e882c1b77 100644
--- a/sdk/src/index.ts
+++ b/sdk/src/index.ts
@@ -6,8 +6,13 @@
*/
import { setPlatform, webAdapter } from './platform';
+import { ensureBuiltinComponentsRegistered } from './component';
setPlatform(webAdapter);
+// Register every engine component (COMPONENT_META) up front so a scene can never
+// silently drop a component that exists in the engine but lacks a typed const.
+ensureBuiltinComponentsRegistered();
+
export * from './core';
export * from './webAppFactory';
diff --git a/sdk/src/index.wechat.ts b/sdk/src/index.wechat.ts
index fd114d7a1..f53756307 100644
--- a/sdk/src/index.wechat.ts
+++ b/sdk/src/index.wechat.ts
@@ -7,10 +7,15 @@
import { setPlatform } from './platform';
import { wechatAdapter, initWeChatPlatform } from './platform/wechat';
+import { ensureBuiltinComponentsRegistered } from './component';
initWeChatPlatform();
setPlatform(wechatAdapter);
+// Register every engine component (COMPONENT_META) so scenes never silently drop
+// a component that exists in the engine but lacks a typed const.
+ensureBuiltinComponentsRegistered();
+
export * from './core';
export * from './webAppFactory';
diff --git a/sdk/tests/component-registry-completeness.test.ts b/sdk/tests/component-registry-completeness.test.ts
new file mode 100644
index 000000000..7bce59b4d
--- /dev/null
+++ b/sdk/tests/component-registry-completeness.test.ts
@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { COMPONENT_META } from '../src/component.generated';
+import { getComponent, ensureBuiltinComponentsRegistered } from '../src/component';
+
+describe('builtin component registry completeness', () => {
+ it('every COMPONENT_META component is registered (no silent-drop)', () => {
+ // The invariant violated by the ShadowCaster2D bug: a component present in
+ // the EHT-generated COMPONENT_META but absent from the registry, so the
+ // scene loader silently dropped it.
+ ensureBuiltinComponentsRegistered();
+ for (const name of Object.keys(COMPONENT_META)) {
+ expect(getComponent(name), `"${name}" is in COMPONENT_META but not registered`).toBeDefined();
+ }
+ });
+
+ it('backstop registers a COMPONENT_META component that lacks a typed const', () => {
+ const FAKE = '__BackstopProbe__';
+ const meta = COMPONENT_META as Record<string, unknown>;
+ meta[FAKE] = {
+ defaults: { amount: 1 },
+ assetFields: [], entityFields: [], colorFields: [], animatableFields: [], fields: {},
+ };
+ try {
+ expect(getComponent(FAKE)).toBeUndefined();
+ ensureBuiltinComponentsRegistered();
+ const def = getComponent(FAKE);
+ expect(def).toBeDefined();
+ expect(def?._default).toEqual({ amount: 1 });
+ } finally {
+ delete meta[FAKE];
+ }
+ });
+
+ it('is idempotent (re-running keeps the same def instance)', () => {
+ ensureBuiltinComponentsRegistered();
+ const first = getComponent('Sprite');
+ ensureBuiltinComponentsRegistered();
+ expect(getComponent('Sprite')).toBe(first);
+ });
+});