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
fix(pipeline): a native import is looked up, and an unknown one fails packaging
yhh64a1fef2046f
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex f37661583..307f051be 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -60,6 +60,7 @@ import { measureBuild, type BuildSizeReport } from './sizeReport';import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';import { collectSubsystems, subsystemGapWarnings, targetGaps, type Subsystem } from '../project/targetSupport';import { scanSideModuleIds, sideModuleFiles, shipsSideModule } from '../bundle/sideModuleScan';+import { MODULES, NATIVE_MODULE_REGISTRY } from '../../../tools/nativeScriptModules.js';export type { ExportPlatform };/**@@ -284,17 +285,36 @@ function indexHtml(title: string, orientation?: ScreenOrientation): string {}/** A filesystem-safe slug for the app id / package name. */-/** Resolve every `esengine` import to the host's global SDK. A native build has- * no module loader and no second copy of the SDK: the engine bundle the host- * already evaluated installs `globalThis.ESEngine`, and the project's scripts- * must bind to THAT instance or their components land in a rival registry. */+/** Bind every `esengine` import to what the host already evaluated: a native+ * build has no module loader, and a second copy would put a game's tokens in+ * a rival registry. Each specifier is LOOKED UP in tools/nativeScriptModules.js,+ * never pattern-matched — a subpath must never be able to mean the bare name. */function esengineGlobalPlugin(): Plugin {return {name: 'esengine-global',setup(build) {- build.onResolve({ filter: /^esengine(\/.*)?$/ }, (args) => ({ path: args.path, namespace: 'esengine-global' }));- build.onLoad({ filter: /.*/, namespace: 'esengine-global' }, () => ({- contents: 'module.exports = globalThis.ESEngine;', loader: 'js',+ build.onResolve({ filter: /^esengine(\/.*)?$/ }, (args) => {+ const m = MODULES[args.path];+ if (!m) {+ return { errors: [{ text:+ `"${args.path}" is not a module the SDK publishes. Importing it from a game `+ + `script would resolve to nothing on a native build. Declare it in `+ + `tools/nativeScriptModules.js if it is meant to exist.` }] };+ }+ if (m.disposition === 'forbidden-native-script') {+ return { errors: [{ text:+ `"${args.path}" cannot be imported by a game script in a native package: `+ + `${m.why ?? 'no reason recorded'}.` }] };+ }+ return { path: args.path, namespace: 'esengine-global' };+ });+ build.onLoad({ filter: /.*/, namespace: 'esengine-global' }, (args) => ({+ // The bare specifier is the core global; a subpath is its own namespace+ // from that same running graph, so a resource token has one author.+ contents: MODULES[args.path]?.disposition === 'native-subpath'+ ? `module.exports = globalThis.${NATIVE_MODULE_REGISTRY}[${JSON.stringify(args.path)}];`+ : 'module.exports = globalThis.ESEngine;',+ loader: 'js',}));},};diff --git a/tools/check-native-script-modules.mjs b/tools/check-native-script-modules.mjsindex d56b0561d..d004dbfe1 100644--- a/tools/check-native-script-modules.mjs+++ b/tools/check-native-script-modules.mjs@@ -21,7 +21,7 @@ import { readFileSync, existsSync } from 'node:fs';import path from 'node:path';import { fileURLToPath } from 'node:url';import { MODULES, DISPOSITIONS, NATIVE_MODULE_REGISTRY, subpathOf, specifierOf, nativeSubpaths }- from './nativeScriptModules.mjs';+ from './nativeScriptModules.js';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');const PKG = path.join(ROOT, 'sdk', 'package.json');@@ -95,6 +95,31 @@ if (existsSync(NATIVE_ENTRY) && !readFileSync(NATIVE_ENTRY, 'utf8').includes('in+ 'namespaces exist and no host ever publishes them.');}+// 6. The exporter dispatches on this table rather than pattern-matching. A rule+// that covers the bare specifier and its subpaths together is how a subpath+// came to mean the core namespace, and the fix is only real if it is read here.+const EXPORTER = path.join(ROOT, 'pipeline', 'src', 'export', 'exportGame.ts');+if (existsSync(EXPORTER)) {+ const src = readFileSync(EXPORTER, 'utf8');+ if (!src.includes('nativeScriptModules.js')) {+ problems.push(+ 'pipeline/src/export/exportGame.ts does not read tools/nativeScriptModules.js — '+ + 'a second, unchecked opinion about what a specifier means.');+ }+ // The identifier, not its value: the exporter importing the constant is what+ // keeps the emitted global and this table spelled the same way.+ if (!src.includes('NATIVE_MODULE_REGISTRY')) {+ problems.push(+ `pipeline/src/export/exportGame.ts never emits ${NATIVE_MODULE_REGISTRY}, so every `+ + 'specifier still resolves to the core global and a subpath means the bare name.');+ }+ if (!src.includes("'forbidden-native-script'")) {+ problems.push(+ 'pipeline/src/export/exportGame.ts does not refuse forbidden specifiers — an entry '+ + 'a game script must not import would package and fail on a device instead.');+ }+}+if (problems.length) {console.error('check-native-script-modules: the module vocabulary and its native answer disagree.\n');for (const p of problems) console.error(` ✗ ${p}\n`);diff --git a/tools/nativeScriptModules.d.ts b/tools/nativeScriptModules.d.tsnew file mode 100644index 000000000..7276eb9d0--- /dev/null+++ b/tools/nativeScriptModules.d.ts@@ -0,0 +1,23 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+export type NativeScriptDisposition =+ 'core-global' | 'native-subpath' | 'forbidden-native-script';++export interface NativeScriptDispositionClass {+ readonly means: string;+ readonly resolvesTo: string | null;+ readonly needsNamespace: boolean;+}++export interface NativeScriptModule {+ readonly disposition: NativeScriptDisposition;+ /** Owed by `forbidden-native-script`: what to reach for instead, and why. */+ readonly why?: string;+}++export const NATIVE_MODULE_REGISTRY: string;+export const DISPOSITIONS: Readonly<Record<NativeScriptDisposition, NativeScriptDispositionClass>>;+export const MODULES: Readonly<Record<string, NativeScriptModule>>;+export function subpathOf(specifier: string): string;+export function specifierOf(subpath: string): string;+export function nativeSubpaths(): string[];diff --git a/tools/nativeScriptModules.mjs b/tools/nativeScriptModules.jssimilarity index 100%rename from tools/nativeScriptModules.mjsrename to tools/nativeScriptModules.js