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(native): the subpath namespaces come from the graph that is already running

yhha23a2491bc3e
diff --git a/sdk/src/index.native.ts b/sdk/src/index.native.ts
index 30f8deb34..e0f245efc 100644
--- a/sdk/src/index.native.ts
+++ b/sdk/src/index.native.ts
@@ -23,6 +23,7 @@
*/
import { ensureBuiltinComponentsRegistered, markEngineComponentBaseline } from './ecs/component';
import { ensureBuiltinAiRegistrations } from './ai/builtins';
+import { installNativeModuleRegistry } from './platform/nativeModuleRegistry';
// No setPlatform here — the shell calls installNativePlatform(bridge) at boot.
// Register every engine component / AI name up front so a scene can never silently
@@ -31,6 +32,11 @@ ensureBuiltinComponentsRegistered();
ensureBuiltinAiRegistrations();
markEngineComponentBaseline();
+// The public subpath namespaces, from THIS graph, so `Res(Physics3D)` in a game
+// names the token the runtime installed. A resolution target, not public API:
+// nothing re-exports it and the core namespace stays unflattened.
+installNativeModuleRegistry();
+
export * from './core';
export * from './runtime/webAppFactory';
diff --git a/sdk/src/platform/nativeModuleRegistry.ts b/sdk/src/platform/nativeModuleRegistry.ts
new file mode 100644
index 000000000..da4696f9b
--- /dev/null
+++ b/sdk/src/platform/nativeModuleRegistry.ts
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file nativeModuleRegistry.ts
+ * @brief The public `esengine/*` subpath namespaces, published for a native
+ * game script to resolve against THIS module graph.
+ *
+ * A native build has no module loader: the exporter rewrites every
+ * `esengine` import to something already evaluated. The bare specifier
+ * binds to `globalThis.ESEngine`; a subpath binds here.
+ *
+ * It has to be this graph and not a second copy. `Physics3D` is
+ * `defineResource(null, 'Physics3D')` — a JS identity, not a C++
+ * binding — and `Res` is keyed by that identity. A separately bundled
+ * `physics3d` would mint a second token, the runtime would install a
+ * resource under the first, and the game would ask for the second and
+ * be told nothing is there.
+ *
+ * NOT public API. It is a non-enumerable global the packaging step
+ * resolves against, and nothing re-exports it.
+ */
+import * as Physics2DModule from '../physics';
+import * as Physics3DModule from '../physics3d';
+import * as SpineModule from '../spine';
+import * as DragonBonesModule from '../dragonbones';
+
+/** Must equal NATIVE_MODULE_REGISTRY in tools/nativeScriptModules.mjs, which is
+ * what the exporter emits and what check-native-script-modules reads. */
+export const NATIVE_MODULE_REGISTRY = '__ESTELLA_NATIVE_MODULES__';
+
+/**
+ * Namespace per specifier. The keys are the specifiers a project writes, so the
+ * exporter's lookup and this table are spelled the same way on both sides.
+ */
+export const NATIVE_MODULE_NAMESPACES: Readonly<Record<string, unknown>> = {
+ 'esengine/physics': Physics2DModule,
+ 'esengine/physics3d': Physics3DModule,
+ 'esengine/spine': SpineModule,
+ 'esengine/dragonbones': DragonBonesModule,
+};
+
+/**
+ * Publish the namespaces on the global the exporter resolves against.
+ *
+ * Non-enumerable so it stays out of anything that walks globalThis, and
+ * idempotent because a host may evaluate the bundle more than once.
+ */
+export function installNativeModuleRegistry(target: object = globalThis): void {
+ const holder = target as Record<string, unknown>;
+ if (holder[NATIVE_MODULE_REGISTRY]) return;
+ Object.defineProperty(holder, NATIVE_MODULE_REGISTRY, {
+ value: NATIVE_MODULE_NAMESPACES,
+ enumerable: false,
+ writable: false,
+ configurable: true,
+ });
+}
diff --git a/sdk/tests/native-module-identity.test.ts b/sdk/tests/native-module-identity.test.ts
new file mode 100644
index 000000000..3bb5c1927
--- /dev/null
+++ b/sdk/tests/native-module-identity.test.ts
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file native-module-identity.test.ts — a subpath a native game imports and
+ * the graph the runtime installs from are ONE module.
+ *
+ * `Res` is keyed by identity, so a separately bundled `esengine/physics3d`
+ * mints a second `Physics3D`: the runtime installs a resource under the first,
+ * the game asks with the second, and the two halves miss each other with no
+ * error anywhere. `Physics3D !== undefined` cannot see that — the last case
+ * here is the sabotage, and it is what makes the assertion above mean something.
+ */
+import { describe, it, expect } from 'vitest';
+import { App } from '../src/app/app';
+import { defineResource } from '../src/ecs/resource';
+import { Physics3D } from '../src/physics3d/Physics3DPlugin';
+import { Physics2D } from '../src/physics/Physics2DPlugin';
+import { Spine } from '../src/spine/SpinePlugin';
+import {
+ NATIVE_MODULE_NAMESPACES, NATIVE_MODULE_REGISTRY, installNativeModuleRegistry,
+} from '../src/platform/nativeModuleRegistry';
+
+/** What a packaged game script gets for `import … from '<specifier>'`. */
+const imported = (specifier: string): Record<string, unknown> =>
+ NATIVE_MODULE_NAMESPACES[specifier] as Record<string, unknown>;
+
+describe('native subpath modules resolve to this graph', () => {
+ it('publishes a namespace for every subpath a project may import', () => {
+ expect(Object.keys(NATIVE_MODULE_NAMESPACES).sort()).toEqual([
+ 'esengine/dragonbones', 'esengine/physics', 'esengine/physics3d', 'esengine/spine',
+ ]);
+ });
+
+ it('carries the exports the core namespace does not', () => {
+ // The four that made this a bug rather than a tidy-up: `Physics3D` is what
+ // third-person-3d imports, and it is absent from the core global.
+ expect(imported('esengine/physics3d').Physics3D).toBeDefined();
+ expect(imported('esengine/physics3d').Physics3DPlugin).toBeDefined();
+ expect(imported('esengine/spine').formatSpineDiagnostics).toBeDefined();
+ expect(imported('esengine/physics').physics2dPlugin).toBeDefined();
+ });
+
+ it('hands back the SAME token the plugins define, not a copy of one', () => {
+ expect(imported('esengine/physics3d').Physics3D).toBe(Physics3D);
+ expect(imported('esengine/physics').Physics2D).toBe(Physics2D);
+ expect(imported('esengine/spine').Spine).toBe(Spine);
+ });
+
+ it('installs a non-enumerable global, once', () => {
+ const host: Record<string, unknown> = {};
+ installNativeModuleRegistry(host);
+ installNativeModuleRegistry(host);
+ expect(host[NATIVE_MODULE_REGISTRY]).toBe(NATIVE_MODULE_NAMESPACES);
+ expect(Object.keys(host)).toEqual([]);
+ expect(Object.getOwnPropertyDescriptor(host, NATIVE_MODULE_REGISTRY)?.enumerable).toBe(false);
+ });
+});
+
+describe('identity, which is the whole point', () => {
+ it('a resource installed by the runtime is found by the token a game imported', () => {
+ const app = new App();
+ // What installing physics3d does, reduced to the part identity depends on.
+ app.insertResource(Physics3D, null);
+
+ const asTheGameImportsIt = imported('esengine/physics3d').Physics3D as typeof Physics3D;
+ expect(app.hasResource(asTheGameImportsIt)).toBe(true);
+ });
+
+ it('a second bundle of the same module is NOT found — the failure this prevents', () => {
+ const app = new App();
+ app.insertResource(Physics3D, null);
+
+ // Byte-for-byte what Physics3DPlugin.ts declares. Same name, same default,
+ // different object — which is all a separately bundled subpath would be.
+ const rival = defineResource<unknown>(null, 'Physics3D');
+ expect(app.hasResource(rival)).toBe(false);
+ expect(rival).not.toBe(Physics3D);
+ });
+});
diff --git a/tools/check-native-script-modules.mjs b/tools/check-native-script-modules.mjs
index 2cea33e68..d56b0561d 100644
--- a/tools/check-native-script-modules.mjs
+++ b/tools/check-native-script-modules.mjs
@@ -25,6 +25,7 @@ import { MODULES, DISPOSITIONS, NATIVE_MODULE_REGISTRY, subpathOf, specifierOf,
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const PKG = path.join(ROOT, 'sdk', 'package.json');
+const REGISTRY = path.join(ROOT, 'sdk', 'src', 'platform', 'nativeModuleRegistry.ts');
const NATIVE_ENTRY = path.join(ROOT, 'sdk', 'src', 'index.native.ts');
const problems = [];
@@ -68,24 +69,30 @@ for (const [specifier, m] of Object.entries(MODULES)) {
}
}
-// 5. Every native-subpath has a namespace in the registry the native entry
-// installs. Skipped with a word — not silently — while that entry is being
-// written, since a check that cannot see its subject must say so.
+// 5. Every native-subpath has a namespace in the registry, and the native entry
+// actually installs it. A table nothing calls publishes nothing.
const subs = nativeSubpaths();
-if (existsSync(NATIVE_ENTRY)) {
- const entry = readFileSync(NATIVE_ENTRY, 'utf8');
- if (!entry.includes(NATIVE_MODULE_REGISTRY)) {
- console.log(`check-native-script-modules: sdk/src/index.native.ts does not install `
- + `${NATIVE_MODULE_REGISTRY} yet — ${subs.length} native-subpath namespace(s) unchecked.`);
- } else {
- for (const specifier of subs) {
- if (!entry.includes(`'${specifier}'`) && !entry.includes(`"${specifier}"`)) {
- problems.push(
- `"${specifier}" is a native-subpath and ${NATIVE_MODULE_REGISTRY} does not `
- + `publish a namespace for it — a game importing it would resolve to nothing.`);
- }
+if (existsSync(REGISTRY)) {
+ const reg = readFileSync(REGISTRY, 'utf8');
+ for (const specifier of subs) {
+ if (!reg.includes(`'${specifier}'`) && !reg.includes(`"${specifier}"`)) {
+ problems.push(
+ `"${specifier}" is a native-subpath and sdk/src/platform/nativeModuleRegistry.ts `
+ + `publishes no namespace for it — a game importing it would resolve to nothing.`);
}
}
+ if (!reg.includes(`'${NATIVE_MODULE_REGISTRY}'`)) {
+ problems.push(
+ `sdk/src/platform/nativeModuleRegistry.ts must spell ${NATIVE_MODULE_REGISTRY}, which `
+ + `is the global the exporter resolves a subpath against.`);
+ }
+} else {
+ problems.push('sdk/src/platform/nativeModuleRegistry.ts is missing — nothing publishes the '
+ + 'subpath namespaces a packaged native game resolves against.');
+}
+if (existsSync(NATIVE_ENTRY) && !readFileSync(NATIVE_ENTRY, 'utf8').includes('installNativeModuleRegistry()')) {
+ problems.push('sdk/src/index.native.ts does not call installNativeModuleRegistry() — the '
+ + 'namespaces exist and no host ever publishes them.');
}
if (problems.length) {