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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file check-native-subpath-imports.mjs — a natively packaged game really does
* receive what it imports from an `esengine/*` subpath.
*
* The unit test beside the registry proves the namespaces hold one token each.
* This proves the other half: that the exporter's rewrite reaches them, that the
* host's own bundle publishes them, and that the token a packaged script ends up
* holding is the token the runtime installs resources under.
*
* Each subpath is represented by an export the CORE namespace does not have, so
* a regression that quietly re-flattens subpaths onto `globalThis.ESEngine`
* fails here instead of on a phone. physics3d carries the identity claim: a
* resource token answers to its NAME (resource.ts), so a second copy resolves —
* but a token by another name must not, or the claim asks nothing.
*
* node tools/check-native-subpath-imports.mjs
*/
import { spawnSync } from 'node:child_process';
import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { MODULES, NATIVE_MODULE_REGISTRY, nativeSubpaths } from './nativeScriptModules.js';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const WORK = path.join(ROOT, '.golden', 'native-subpaths');
const SOURCE = path.join(ROOT, 'examples', 'hello-world');
const BUNDLE = path.join(ROOT, 'sdk', 'dist', 'index.native.bundled.js');
const results = [];
const check = (what, ok, detail) => {
results.push(ok);
console.log(`${ok ? '✓' : '✗'} ${what}${detail ? ` — ${detail}` : ''}`);
};
// One export per subpath that the core namespace does NOT carry. Picked for that
// property: a name core also exports would pass while the bug was live.
const WITNESS = {
'esengine/physics3d': 'Physics3D',
'esengine/physics': 'physics2dPlugin',
'esengine/spine': 'formatSpineDiagnostics',
'esengine/dragonbones': 'DragonBonesManager',
};
if (!existsSync(BUNDLE)) {
console.log('check-native-subpath-imports: no sdk/dist/index.native.bundled.js — '
+ 'build the SDK first (pnpm run build:sdk). Nothing judged.');
process.exit(2);
}
rmSync(WORK, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
mkdirSync(WORK, { recursive: true });
/** A copy of the fixture with an extra module the entry imports for effect. */
function project(name, source) {
const dir = path.join(WORK, name);
cpSync(SOURCE, dir, { recursive: true });
rmSync(path.join(dir, '.esengine'), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
const probe = path.join(dir, 'src', 'subpathProbe.ts');
writeFileSync(probe, source);
const main = path.join(dir, 'src', 'main.ts');
writeFileSync(main, `import './subpathProbe';\n${readFileSync(main, 'utf8')}`);
return dir;
}
function exportNative(dir, name) {
const out = path.join(WORK, `${name}-out`);
const r = spawnSync(process.execPath, [
path.join(ROOT, 'pipeline', 'bin', 'estella.mjs'), 'export', dir,
'--platform', 'desktop', '--out', out,
], { encoding: 'utf8', cwd: ROOT });
return { status: r.status, out, text: `${r.stdout ?? ''}${r.stderr ?? ''}` };
}
// 1. Every subpath a project may import packages, and reaches the registry.
{
const subs = nativeSubpaths();
const imports = subs.map((s, i) => `import { ${WITNESS[s]} as w${i} } from '${s}';`).join('\n');
// The witnesses are USED: esbuild elides an import whose binding is not, and
// an elided import proves nothing about how it would have resolved.
const uses = subs.map((_, i) => `w${i}`).join(', ');
const dir = project('all-subpaths', `${imports}\nexport const seen = [${uses}].map((w) => typeof w);\n`);
const { status, out, text } = exportNative(dir, 'all-subpaths');
check('a game importing every subpath packages', status === 0,
status === 0 ? `${subs.length} subpath(s)` : text.trim().split('\n').slice(-3).join(' | '));
if (status === 0) {
const js = readFileSync(path.join(out, 'scripts.js'), 'utf8');
const missed = subs.filter((s) => !js.includes(`${NATIVE_MODULE_REGISTRY}[${JSON.stringify(s)}]`));
check('each one resolves to the native module registry', missed.length === 0,
missed.length ? `still on the core global: ${missed.join(', ')}` : NATIVE_MODULE_REGISTRY);
check('none of them was flattened onto the core global',
!/module\.exports = globalThis\.ESEngine;[\s\S]{0,200}esengine\/(physics|spine|dragonbones)/.test(js),
'the bare specifier is the only core-global binding');
}
}
// 2. The host's own bundle publishes what those scripts will ask for, and the
// token a script holds reaches the slot the runtime installs under.
{
const harness = path.join(WORK, 'harness.mjs');
writeFileSync(harness, `
import { readFileSync } from 'node:fs';
const src = readFileSync(${JSON.stringify(BUNDLE)}, 'utf8');
(0, eval)(src);
const reg = globalThis[${JSON.stringify(NATIVE_MODULE_REGISTRY)}];
const out = {};
for (const [spec, name] of Object.entries(${JSON.stringify(WITNESS)})) {
out[spec] = reg?.[spec]?.[name] !== undefined;
}
const p3 = reg?.['esengine/physics3d']?.Physics3D;
const { App } = globalThis.ESEngine;
const app = App.new();
app.insertResource(p3, null);
out.identity = app.hasResource(p3) === true;
out.rivalResolves = app.hasResource(globalThis.ESEngine.defineResource(null, 'Physics3D')) === true;
out.strangerRejected = app.hasResource(globalThis.ESEngine.defineResource(null, 'Physics3DStranger')) === false;
console.log(JSON.stringify(out));
`);
const r = spawnSync(process.execPath, [harness], { encoding: 'utf8', cwd: ROOT });
let seen = null;
try { seen = JSON.parse((r.stdout || '').trim().split('\n').pop()); } catch { /* reported below */ }
if (!seen) {
check('the host bundle publishes the registry', false,
(r.stderr || r.stdout || 'no output').trim().split('\n').slice(-2).join(' | '));
} else {
for (const [spec, name] of Object.entries(WITNESS)) {
check(`${spec} hands a game its own ${name}`, seen[spec] === true,
seen[spec] ? 'present' : 'undefined — the core namespace does not carry it');
}
check('a resource installed by the runtime answers to the imported token',
seen.identity === true, 'Res(Physics3D) resolves');
check('a same-named token from a second bundle reaches the same slot',
seen.rivalResolves === true, 'the name is the address — a re-import lands on it');
check('and a token by another name does NOT',
seen.strangerRejected === true, 'the sabotage: without it the claim above asks nothing');
}
}
// 3. A specifier the SDK does not publish fails while it is being packaged.
{
const dir = project('unknown-subpath',
"import { nothing } from 'esengine/not-a-module';\nexport const seen = typeof nothing;\n");
const { status, text } = exportNative(dir, 'unknown-subpath');
check('an unknown esengine/* subpath fails the export', status !== 0,
status !== 0 ? 'refused while packaging' : 'it PACKAGED — the failure would land on a device');
if (status !== 0) {
check('and the refusal says which specifier and why',
text.includes('not a module the SDK publishes'), 'named in the error');
}
}
// 4. And an entry that is real but forbidden says so in its own words.
{
const forbidden = Object.entries(MODULES)
.find(([, m]) => m.disposition === 'forbidden-native-script')?.[0];
const dir = project('forbidden-subpath',
`import { anything } from '${forbidden}';\nexport const seen = typeof anything;\n`);
const { status, text } = exportNative(dir, 'forbidden-subpath');
check(`${forbidden} is refused to a game script`, status !== 0,
status !== 0 ? 'refused while packaging' : 'it PACKAGED');
if (status !== 0) {
check('with the reason the table records',
text.includes('cannot be imported by a game script'), 'the why reaches the person');
}
}
const failed = results.filter((ok) => !ok).length;
console.log(failed === 0
? `check-native-subpath-imports: ${results.length} claim(s) — a packaged game gets the module it named`
: `check-native-subpath-imports: ${failed} of ${results.length} claim(s) failed`);
process.exit(failed === 0 ? 0 : 1);