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
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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mjsindex 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) {