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.

10.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  check-entry-boots.mjs — an entry still installs its platform after a
 *        bundler has been through it.
 *
 * `sideEffects` in package.json is a list of FILES, and which file a statement
 * ends up in is the BUNDLER's choice. Move an entry's prologue into a module the
 * entries share and it lands in a chunk nobody whitelisted, where tree-shaking
 * drops it — the code is still in `dist`, so every text probe says it shipped.
 * It has cost two boots: a lean-entry WeChat package, and the editor, which came
 * up on "Platform not initialized".
 *
 * So this bundles a CONSUMER the way one really resolves the package — through
 * node_modules, so `sideEffects` applies — and RUNS it.
 *
 *   node tools/check-entry-boots.mjs
 */
import { spawnSync } from 'node:child_process';
import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const SDK = path.join(ROOT, 'sdk');

/** Enough of `wx` for a WeChat entry's prologue to run in node. */
const WX_STUB = "globalThis.wx = new Proxy({}, { get: (t, k) => k === 'env' ? {} : (() => ({})) });";

/** Each entry a consumer can resolve, and the platform it must have installed. */
const ENTRIES = [
    { specifier: 'esengine', platform: 'web' },
    { specifier: 'esengine/lean', file: 'dist/index.lean.js', platform: 'web' },
    { specifier: 'esengine/wechat', file: 'dist/index.wechat.js', platform: 'wechat', banner: WX_STUB },
    { specifier: 'esengine/wechat-lean', file: 'dist/index.wechat.lean.js', platform: 'wechat', banner: WX_STUB },
];

/** An engine component with no typed const: only the entry's prologue registers
 *  it, so a scene that uses it is where a lost prologue shows. */
const UNTYPED_BUILTIN = 'MeshSkin';

const work = mkdtempSync(path.join(tmpdir(), 'estella-entry-boots-'));
const fail = (message, detail) => {
    console.error(`check-entry-boots: ${message}`);
    if (detail) console.error(String(detail).trim());
    rmSync(work, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
    process.exit(1);
};

if (!existsSync(path.join(SDK, 'dist', 'index.js'))) {
    fail('no SDK build at sdk/dist — build it first (pnpm --filter ./sdk build).');
}

mkdirSync(path.join(work, 'node_modules'), { recursive: true });
symlinkSync(SDK, path.join(work, 'node_modules', 'esengine'), process.platform === 'win32' ? 'junction' : 'dir');

const { build } = await import('esbuild');
const results = [];
for (const entry of ENTRIES) {
    const name = entry.specifier.replace(/\W+/g, '-');
    const src = path.join(work, `${name}.mjs`);
    const out = path.join(work, `${name}.bundle.mjs`);
    writeFileSync(src, `import { getPlatformType, getComponent } from ${JSON.stringify(entry.specifier)};\n`
        + `console.log(JSON.stringify({ platform: getPlatformType(), untyped: !!getComponent(${JSON.stringify(UNTYPED_BUILTIN)}) }));\n`);
    try {
        await build({
            entryPoints: [src], outfile: out, bundle: true, format: 'esm',
            platform: 'node', logLevel: 'silent',
            // A subpath the package does not publish still has to be reachable
            // by the file it is: this asks what the BUILD produced.
            ...(entry.file ? { alias: { [entry.specifier]: path.join(SDK, entry.file) } } : {}),
            ...(entry.banner ? { banner: { js: entry.banner } } : {}),
        });
    } catch (err) {
        fail(`${entry.specifier} did not bundle.`, err?.message ?? err);
    }
    const run = spawnSync(process.execPath, [out], { encoding: 'utf8' });
    if (run.status !== 0) fail(`${entry.specifier} threw on import.`, run.stderr);
    let got = null;
    try { got = JSON.parse((run.stdout ?? '').trim().split('\n').at(-1)); } catch { /* reported below */ }
    const prologueLost = '\n\nIts prologue is a statement in a module the bundler put in an unlisted chunk.'
        + ' Make it a call the entry makes (runtime/webEntry.ts, runtime/wechatEntry.ts),'
        + ' or list that file in sdk/package.json "sideEffects".';
    if (got?.platform !== entry.platform) {
        fail(`${entry.specifier} installed no platform after bundling — got ${got?.platform || '(nothing)'},`
            + ` expected ${entry.platform}.${prologueLost}`);
    }
    if (!got.untyped) {
        fail(`${entry.specifier} never registered ${UNTYPED_BUILTIN} after bundling, so a scene using it`
            + ` loads without it ("Unknown component type").${prologueLost}`);
    }
    results.push(`${entry.specifier} → ${got.platform}`);
}

// One process can hold two entries: a node tool reaches `esengine` through
// modules a browser also runs. They share one core, so the host that declared
// itself must keep the platform whichever order they arrive in.
for (const [first, second] of [['esengine', 'esengine/node'], ['esengine/node', 'esengine']]) {
    const src = path.join(work, `order-${first.replace(/\W+/g, '-')}.mjs`);
    const out = `${src}.bundle.mjs`;
    writeFileSync(src, `import ${JSON.stringify(first)};\n`
        + `import { getPlatformType } from ${JSON.stringify(second)};\n`
        + `console.log(getPlatformType());\n`);
    await build({ entryPoints: [src], outfile: out, bundle: true, format: 'esm', platform: 'node', logLevel: 'silent' });
    const run = spawnSync(process.execPath, [out], { encoding: 'utf8' });
    const got = (run.stdout ?? '').trim();
    if (got !== 'node') {
        fail(`loading ${first} then ${second} left the platform as ${got || '(nothing)'}, not node.`
            + '\n\nA host entry claims the platform outright; the web entry installs one only when'
            + ' nobody has (runtime/webEntry.ts). A node process that ends up on the web adapter'
            + ' reads files over fetch and throws on localStorage.');
    }
    results.push(`${first}+${second} → ${got}`);
}

// The debug channel reaches a package only through its subpath, which a
// development export imports: a lean shipping bundle must neither carry it nor
// find it, and one that imports the subpath must have it installed.
const NO_CHANNEL = 'packaged without esengine/debug-channel';
for (const c of [
    { name: 'lean', imports: [], installed: false },
    { name: 'lean+channel', imports: ['esengine/debug-channel'], installed: true },
    { name: 'full', imports: [], entry: 'esengine', installed: true },
]) {
    const src = path.join(work, `channel-${c.name.replace(/\W+/g, '-')}.mjs`);
    const out = `${src}.bundle.mjs`;
    const entry = c.entry ?? 'esengine/lean';
    writeFileSync(src, c.imports.map((m) => `import ${JSON.stringify(m)};\n`).join('')
        + `import { startDebugChannel } from ${JSON.stringify(entry)};\n`
        + `startDebugChannel({ url: 'ws://127.0.0.1:9/?token=t' });\n`
        + `setTimeout(() => process.exit(0), 50);\n`);
    await build({
        entryPoints: [src], outfile: out, bundle: true, format: 'esm', platform: 'node', logLevel: 'silent',
        alias: { 'esengine/lean': path.join(SDK, 'dist/index.lean.js') },
    });
    const run = spawnSync(process.execPath, [out], { encoding: 'utf8' });
    const said = `${run.stdout ?? ''}${run.stderr ?? ''}`;
    const carried = readFileSync(out, 'utf8').includes('draws no frames');
    if (c.installed === said.includes(NO_CHANNEL) || c.installed !== carried) {
        fail(`${c.name}: the debug channel ${c.installed ? 'should be installed' : 'should be absent'}, `
            + `but the bundle ${carried ? 'carries' : 'lacks'} it and starting it ${said.includes(NO_CHANNEL) ? 'found none' : 'found one'}.`
            + '\n\nThe subpath installs it with a call (debug-channel/index.ts); the full entries call the'
            + ' same registration; the lean entries must not.');
    }
    results.push(`${c.name} channel → ${c.installed ? 'installed' : 'absent'}`);
}

// A texture recipe is drawn by esengine/image, which installs its drawer by being
// imported and exports nothing a package's host uses. Its entry is a re-export of
// a chunk the native entry shares, so the install is a statement in that chunk:
// unlisted, the bundler dropped the whole of it, and an export that shipped
// recipes drew its ground and its walls with no texture ("nothing here draws
// recipes"). The words are the drawer's own, so they are in a bundle only when it is.
const RECIPE_DRAWER = 'has no canvas to draw text on';
for (const c of [
    { name: 'lean', imports: [], installed: false },
    { name: 'lean+image', imports: ['esengine/image'], installed: true },
    // The same for a clip made from its source: esengine/sound, whose words these are.
    { name: 'lean+sound', imports: ['esengine/sound'], installed: true, words: 'a recipe plays .wav recordings only', what: 'maker of audio recipes' },
    { name: 'lean without sound', imports: [], installed: false, words: 'a recipe plays .wav recordings only', what: 'maker of audio recipes' },
]) {
    const src = path.join(work, `recipes-${c.name.replace(/\W+/g, '-')}.mjs`);
    const out = `${src}.bundle.mjs`;
    writeFileSync(src, c.imports.map((m) => `import ${JSON.stringify(m)};\n`).join('') + `import 'esengine/lean';\n`);
    await build({
        entryPoints: [src], outfile: out, bundle: true, format: 'esm', platform: 'node', logLevel: 'silent',
        alias: { 'esengine/lean': path.join(SDK, 'dist/index.lean.js') },
    });
    const carried = readFileSync(out, 'utf8').includes(c.words ?? RECIPE_DRAWER);
    if (carried !== c.installed) {
        fail(`${c.name}: the ${c.what ?? 'drawer of texture recipes'} ${c.installed ? 'should be installed' : 'should be absent'}, `
            + `but the bundle ${carried ? 'carries' : 'lacks'} it.`
            + '\n\nThe subpath installs it with a call at the end of its index.ts, which the build puts in a shared chunk:'
            + ' list that chunk in sdk/package.json "sideEffects".');
    }
    results.push(`${c.name} recipes → ${c.installed ? 'installed' : 'absent'}`);
}

rmSync(work, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
console.log(`check-entry-boots: ${results.length} case(s) bundled and run — ${results.join(', ')}.`);