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.

9.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  The built-in packaging targets, named once.
 *
 *        Three surfaces used to carry their own copy of this list — the build
 *        dialog's descriptors, the main process's readiness catalog, and the
 *        Inspector's per-platform Import Settings tabs — and the third had drifted
 *        (it never offered the mobile targets at all, so a texture could not be
 *        tuned for the platform where memory is tightest). The ids live here; each
 *        surface adds only what is genuinely its own (icons and copy in the
 *        renderer, filesystem probes in the main process).
 *
 *        Deliberately free of node and React imports: the electron export, the
 *        renderer and the tests all read it.
 */

/**
 * The targets the editor ships. `android` and `ios` are two platforms, not one
 * "native": they package through different toolchains (aapt2 + apksigner vs
 * Xcode), so a single row could not tell you what to run, whether this machine
 * can run it, or where the package comes out.
 */
export type BuiltinPlatform = 'web' | 'desktop' | 'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | 'alipay' | 'huawei' | 'playable' | 'android' | 'ios';

/** Built-ins, in the order they are offered. */
export const BUILTIN_PLATFORMS: readonly BuiltinPlatform[] = [
    'web', 'desktop', 'wechat', 'douyin', 'kuaishou', 'bilibili', 'quickgame', 'alipay', 'huawei', 'playable', 'android', 'ios',
];

/**
 * A packaging target. The editor's built-ins are named for completion, but the
 * type is OPEN: a project can add its own platform by dropping a profile in
 * `.esengine/platforms/<id>.mjs`, and that id flows through packaging settings,
 * the export result and the cook's per-platform Import Settings key exactly like
 * a built-in one.
 */
export type ExportPlatform = BuiltinPlatform | (string & {});

/**
 * The targets that ship as a real native app (embedded Dawn + QuickJS, see
 * `native/README.md`). They share ONE runtime and ONE export payload — content
 * only, since the engine, the SDK and the game runtime live in the app binary —
 * and differ in how that content is assembled into an installable app.
 *
 * `desktop` is one of them. The rule is not "mobile" but whether the host is
 * OURS: where a browser or a mini-game platform already provides JS and a GPU the
 * web runtime fits, and where the app must BE the host the native one does
 * (docs/REARCH_STEAM.md §6.0).
 */
export const NATIVE_PLATFORMS = ['android', 'ios', 'desktop'] as const;
export type NativePlatform = (typeof NATIVE_PLATFORMS)[number];

/** Whether this target's export is app CONTENT rather than a runnable payload. */
export function isNativePlatform(platform: ExportPlatform): platform is NativePlatform {
    return (NATIVE_PLATFORMS as readonly string[]).includes(platform);
}

/**
 * The targets that ship as a mini-game: a CommonJS package plus a vendor global.
 *
 * They share an engine build the way the native targets share a runtime. A
 * project's own vendor is one of these without appearing here, so that build
 * lives in the family's export defaults rather than behind this list.
 */
export const MINIGAME_PLATFORMS = ['wechat', 'douyin', 'kuaishou', 'bilibili', 'quickgame', 'alipay', 'huawei'] as const;
export type MiniGamePlatform = (typeof MINIGAME_PLATFORMS)[number];

/**
 * Which engine build a web-runtime target packages: the browser one, the
 * CommonJS mini-game one, or that one again without wasm SIMD — for the
 * quick-game hosts, whose V8 (8.3) refuses it, and for Alipay and Huawei, which
 * publish no wasm feature level to rely on.
 */
export function engineBuildFor(platform: ExportPlatform): 'web' | 'minigame' | 'quickgame' {
    if (platform === 'quickgame' || platform === 'alipay' || platform === 'huawei') return 'quickgame';
    return isMiniGamePlatform(platform) ? 'minigame' : 'web';
}

export function isMiniGamePlatform(platform: ExportPlatform): platform is MiniGamePlatform {
    return (MINIGAME_PLATFORMS as readonly string[]).includes(platform);
}

/**
 * The desktop OSes one `desktop` target is assembled for — per-OS where the
 * platform id is not, because the binaries are.
 *
 * A build produces one app per INSTALLED template, not one for the machine doing
 * the building: assembly is pure Node, so the OS running it is not an input. Only
 * signing a macOS bundle is, and that is a warning on one output rather than a
 * reason to withhold the others.
 */
/** Every platform a runtime template is published for — the mobile hosts plus
 *  each desktop OS. Mirrors build-tools' TemplatePlatform; a test pins them equal. */
export type TemplatePlatform = 'android' | 'ios' | DesktopOs;

export const DESKTOP_OSES = ['windows', 'macos', 'linux'] as const;
export type DesktopOs = (typeof DESKTOP_OSES)[number];

/** The desktop OS this machine is, for the template hint a missing prerequisite
 *  offers and for choosing which build a size limit is judged on. */
export function desktopTemplateFor(osPlatform: string): DesktopOs {
    if (osPlatform === 'darwin') return 'macos';
    return osPlatform === 'win32' ? 'windows' : 'linux';
}

/**
 * Platform ids written by an older editor, and what they are today. `native` was
 * one row covering both mobile targets; a project that selected it re-opens on
 * Android — the target whose toolchain runs on every desktop OS.
 */
export const LEGACY_PLATFORM_IDS: Readonly<Record<string, BuiltinPlatform>> = {
    native: 'android',
};

/** A persisted platform id, as this editor spells it. Unknown ids pass through —
 *  they belong to the project's own platforms. */
export function normalizePlatform(id: string): string {
    return LEGACY_PLATFORM_IDS[id] ?? id;
}

/** The default output directory for a built-in target. */
export function defaultOutDir(platform: ExportPlatform): string {
    return `dist-${platform}`;
}

/**
 * Why a target is not ready to produce a package. STRUCTURED, not prose: the main
 * process probes the filesystem but has no locale, so it reports the facts and
 * the build dialog writes the sentence.
 *
 * The two kinds are not the same severity, and the dialog says so. A missing
 * ENGINE RUNTIME means the package cannot be produced at all. A missing native
 * TOOLCHAIN does not: the export writes the app's content either way — only the
 * final assembly into an installable app needs the toolchain, and that step can
 * run on another machine (an iOS build always does, when the editor is on
 * Windows).
 */
export type PlatformPrereq =
    | {
        kind: 'runtime-missing';
        /** Display path that was searched (project-relative where possible). */
        dir: string;
        /** Glue filenames looked for in it. */
        looked: string[];
        /** The build command that produces it — only when the editor ships that target. */
        command?: string;
    }
    | {
        kind: 'toolchain-missing';
        /** Which piece is absent — the dialog maps it to a localized sentence. */
        tool: ToolchainPiece;
    }
    | {
        /**
         * No RUNTIME TEMPLATE for this target: the prebuilt engine a native app is
         * assembled around (see `build-tools/utils/nativeTemplate.js`). Its own kind
         * because the fix is neither "build the engine" nor "install a toolchain" —
         * it is an artifact this editor release ships, installed once.
         */
        kind: 'template-missing';
        /** The template looked for, in the vocabulary the release PUBLISHES them
         *  in (`windows`, not the `desktop` target it belongs to) — this is the id
         *  the download asks for. */
        id: TemplatePlatform;
        /** The version it must carry — this editor's. A template is matched exactly:
         *  the SDK bundle is compiled into the app binary. */
        version: string;
    };

/**
 * The toolchain pieces the editor probes for.
 *
 * `xcode` and `macos` gate ASSEMBLY, which can happen on another machine; a
 * target missing them still exports its content. `emsdk` gates the export
 * itself, because the compiled module ships inside the package.
 */
export type ToolchainPiece = 'xcode' | 'macos' | 'emsdk' | 'hostcc' | 'ndk';

/**
 * WHICH machine this target's compiled systems are built for, or null where it
 * runs no such step.
 *
 * Not a boolean: the two answers want different compilers — emcc for a module
 * sharing the engine's memory, the host's own cc for a library it loads — and a
 * surface asking only "does it compile" would guess which to look for. A
 * playable has nowhere to put a module; iOS and Android need a cross-compiler.
 */
export function compileTargetFor(platform: ExportPlatform): 'wasm' | 'native' | null {
    if (platform === 'web' || isMiniGamePlatform(platform)) return 'wasm';
    // Android is native too: the same 64-bit module, built by the NDK for each ABI
    // the package carries (export/androidAot.ts). iOS still waits on its link step.
    if (platform === 'desktop' || platform === 'android') return 'native';
    if (platform === 'playable' || platform === 'ios') return null;
    // A project platform is a mini-game platform: the playable ones are chosen
    // inside the built-in target, not offered as a row of their own.
    return 'wasm';
}