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.

4.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { existsSync, readFileSync } from 'fs';
import { resolve } from 'path';
import type { ESEngineModule } from '../../src/wasm';

/**
 * Single source of truth for where the boundary integration tests find the
 * built WASM SDK (esengine.js + esengine.wasm). Resolution order:
 *   1. $ESENGINE_WASM_DIR        — explicit override (CI passes the build dir)
 *   2. <repo>/build/wasm/web     — the in-repo CMake/Emscripten output
 *   3. <repo>/desktop/public/wasm — the copy synced into the editor, when checked out
 *
 * The first candidate that actually contains esengine.wasm wins. If none do,
 * {@link HAS_WASM} is false and the integration suites skip themselves via
 * `describe.skipIf(!HAS_WASM)` rather than throwing. Previously every test
 * hard-coded the (nonexistent in this repo) desktop path, so the entire
 * C++/TS boundary was never exercised here.
 */
function resolveWasmDir(): string {
    const candidates = [
        process.env.ESENGINE_WASM_DIR,
        resolve(__dirname, '../../../build/wasm/web'),
        resolve(__dirname, '../../../desktop/public/wasm'),
    ].filter((c): c is string => Boolean(c));

    for (const dir of candidates) {
        if (existsSync(resolve(dir, 'esengine.wasm'))) return dir;
    }
    // None found — return the canonical in-repo build output so HAS_WASM and
    // any diagnostics point at where the WASM is expected to be built.
    return resolve(__dirname, '../../../build/wasm/web');
}

/** Directory containing the built WASM SDK, per {@link resolveWasmDir}. */
export const WASM_DIR = resolveWasmDir();

/** Absolute path to the built esengine.wasm binary. */
export const WASM_FILE = resolve(WASM_DIR, 'esengine.wasm');

/**
 * The side modules the SDK's suites load, beside the engine itself. Declared so
 * one place can say what a run will and will not cover.
 */
export const SIDE_MODULES = [
    'physics', 'physics3d', 'dragonbones', 'basis', 'videodec',
    'spine21', 'spine38', 'spine41', 'spine42', 'spine43',
] as const;

/**
 * Whether this run DECLARED that it has no engine build — the only reason a
 * boundary suite may skip.
 *
 * Inferred from the filesystem, "missing" and "unreachable" both came out as
 * `skipped`, which reads as "not applicable" rather than "unavailable".
 */
export const NO_WASM_MODE = process.env.SDK_TEST_MODE === 'no-wasm';

/** True unless this run declared it has no engine build. */
export const HAS_WASM = !NO_WASM_MODE;


let cachedModule: ESEngineModule | null = null;

/**
 * ESENGINE_ENGINE=asmjs runs the boundary suites on the engine built as plain
 * JavaScript (build/wasm/web/esengine.asm.js, wasm2js) instead of the wasm one —
 * the same C++ in the container a host without WebAssembly loads, held to the
 * same tests. Side modules stay wasm: only the core has a JS build.
 */
export const ENGINE_IS_ASMJS = process.env.ESENGINE_ENGINE === 'asmjs';
const ASMJS_FILE = resolve(__dirname, '../../../build/wasm/web/esengine.asm.js');

export async function loadWasmModule(): Promise<ESEngineModule> {
    if (cachedModule) return cachedModule;
    if (ENGINE_IS_ASMJS) {
        const factory = (await import(ASMJS_FILE)).default;
        cachedModule = await factory({}) as ESEngineModule;
        return cachedModule;
    }
    const wasmBinary = readFileSync(WASM_FILE);
    const factory = (await import(resolve(WASM_DIR, 'esengine.js'))).default;
    cachedModule = await factory({ wasmBinary }) as ESEngineModule;
    return cachedModule;
}

/**
 * A side module (physics, spine38, …), loaded the same way: bytes handed
 * straight to the factory.
 *
 * `locateFile` is the other way emscripten glue finds its binary, and it is the
 * wrong one here — under the happy-dom test environment the glue takes itself
 * for a browser and fetches the path, which resolves against localhost and is
 * refused. The physics benchmarks measured nothing for exactly that reason.
 */
export async function loadSideModule<T>(name: string): Promise<T> {
    const wasmBinary = readFileSync(resolve(WASM_DIR, `${name}.wasm`));
    const factory = (await import(resolve(WASM_DIR, `${name}.js`))).default;
    return await factory({ wasmBinary }) as T;
}

/** Whether a side module was built alongside the engine. False for every module
 *  in a declared no-wasm run, so one flag turns the whole corpus off. */
export const hasSideModule = (name: string): boolean =>
    !NO_WASM_MODE && existsSync(resolve(WASM_DIR, `${name}.wasm`));