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 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';
}