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(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.ts
index 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.mjs
index 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.ts
new file mode 100644
index 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.js
similarity index 100%
rename from tools/nativeScriptModules.mjs
rename to tools/nativeScriptModules.js