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 set of platforms this project can package for, and whether each one
* can actually run right now.
*
* Two things the renderer cannot answer for itself:
*
* 1. READINESS. A target needs its engine runtime on disk; the dialog used
* to carry a static "requires the X runtime" line that showed whether or
* not you had built it — noise when you had, and a surprise mid-export
* when you hadn't. Readiness is a filesystem fact, so it is probed here.
*
* 2. PROJECT PLATFORMS. A game can ship a vendor the editor does not know
* about by dropping a profile in `.esengine/platforms/<id>.mjs`. Those
* modules export FUNCTIONS (emitConfigFiles / emitEntry), which cannot
* cross the IPC boundary — so the renderer gets metadata only, and the
* profile itself is loaded here, in the process that runs the export.
*
* The mini-game family is what makes (2) cheap: the pipeline is already
* vendor-neutral (exportMiniGame), so a project platform is a data literal
* merged over MINIGAME_PROFILE_DEFAULTS, not a fork of anything.
*/
import { existsSync } from 'node:fs';
import { readdir, mkdir, writeFile } from 'node:fs/promises';
import path from 'node:path';
import { pathToFileURL } from 'node:url';
import { defaultMiniGameEntry, openpaasExportProfile } from './miniGameExportProfile';
import {
BUILTIN_PLAYABLE_PROFILES, builtinPlayableProfile, genericPlayableProfile, isPlayableZipFileName,
type PlayableAdProfile,
} from './playableAdProfile';
import { BUILTIN_PLATFORMS, DESKTOP_OSES, compileTargetFor, desktopTemplateFor, type PlatformPrereq } from '../project/platforms';
import type { SizeBudget } from '../project/sizeBudget';
import { promisesCompilation } from '../bundle/buildCompiledSystems';
import { resolveNativeTemplate } from './nativeTemplates';
import { templateId } from '../../../build-tools/utils/nativeTemplate.js';
import { MINIGAME_ENGINE_BUILD, MINIGAME_ENGINE_GLUE, type MiniGameExportProfile, type MiniGameConfigContext } from './miniGameExportProfile';
/** Where a project keeps its own platform profiles. */
export const PROJECT_PLATFORM_DIR = path.join('.esengine', 'platforms');
/** Engine runtime dirs the probes look in (resolved by main.ts). */
export interface PlatformRuntimeDirs {
/** Web/playable engine runtime (esengine.js + esengine.wasm). */
web: string;
/** The mini-game engine runtime every vendor takes — see MINIGAME_ENGINE_GLUE.
* The directory is what makes a package's engine CommonJS; the filename in it
* is only a name, and a project's own vendor dir may use either. */
minigame: string;
/** The mini-game engine without SIMD and BigInt i64, for the quick-game hosts. */
quickgame: string;
}
/** What the renderer needs to draw one platform row. Serializable by construction. */
export interface PlatformStatus {
id: string;
/** 'builtin' rows get their label/icon/blurb from the editor's i18n; 'project'
* rows carry their own, since the project named them. */
source: 'builtin' | 'project';
/** Everything this target needs to produce an installable package is present. */
ready: boolean;
/** Present when `ready` is false. */
prereq?: PlatformPrereq;
/** Project platforms only — display data lifted from the profile. */
label?: string;
blurb?: string;
defaultOut?: string;
/** Project platforms only — the module failed to load, and why. The row still
* appears (silently dropping a file the user wrote is worse than naming it). */
error?: string;
/** Project platforms only — the profile hasn't been approved yet, so it was NOT
* imported. The row appears so the user can see it exists and go approve it,
* rather than wondering why the target never showed up. */
needsTrust?: boolean;
/** Project platforms only — the caps this vendor declared, so the build dialog
* can state them before a package exists. A built-in target's are the
* platform's rule and live in sizeBudget.ts, which the renderer reads. */
sizeBudgets?: readonly SizeBudget[];
}
// =============================================================================
// Built-in readiness
// =============================================================================
/** Display paths with forward slashes — the dialog shows them to a human, and a
* Windows `build\wasm\acme` reads worse than `build/wasm/acme`. */
const posix = (p: string): string => p.split(path.sep).join('/');
/** A built-in target's runtime dependency, as a real file probe. */
function builtinReadiness(
id: string, dirs: PlatformRuntimeDirs, engineVersion: string,
): { ready: boolean; prereq?: PlatformPrereq } {
const has = (dir: string, file: string) => existsSync(path.join(dir, file));
switch (id) {
case 'web':
// The web payload's engine runtime ships with the editor.
return has(dirs.web, 'esengine.js')
? { ready: true }
: { ready: false, prereq: { kind: 'runtime-missing', dir: posix(dirs.web), looked: ['esengine.js'], command: 'node build-tools/cli.js build -t web' } };
case 'desktop': {
// Like Android: the runtime template IS the prerequisite, because the app is
// assembled here in pure Node. ANY desktop template makes the target usable,
// not this machine's: assembly does not care which OS runs it, so a Mac with
// only the Windows template installed can still package — and does.
const installed = DESKTOP_OSES.filter((os) => resolveNativeTemplate(os, engineVersion));
if (installed.length > 0) return { ready: true };
// Which one to offer, though, IS this machine's: it is the build a developer
// can double-click when it comes out.
const mine = desktopTemplateFor(process.platform);
return { ready: false, prereq: { kind: 'template-missing', id: templateId(mine), version: engineVersion } };
}
case 'playable':
// Playable inlines the WEB runtime (exportPlayable reads esengine.js) — it
// does NOT need a `-t playable` build, whatever the old static hint said.
return has(dirs.web, 'esengine.js')
? { ready: true }
: { ready: false, prereq: { kind: 'runtime-missing', dir: posix(dirs.web), looked: ['esengine.js'], command: 'node build-tools/cli.js build -t web' } };
case 'wechat':
case 'douyin':
case 'kuaishou':
case 'bilibili':
// One probe for the family: they run the same engine build, so a machine
// ready for one is ready for the other — and answering otherwise offers a
// build command that produces a file the target already has.
return MINIGAME_ENGINE_GLUE.some((g) => has(dirs.minigame, g))
? { ready: true }
: { ready: false, prereq: { kind: 'runtime-missing', dir: posix(dirs.minigame), looked: [...MINIGAME_ENGINE_GLUE], command: `node build-tools/cli.js build -t ${MINIGAME_ENGINE_BUILD}` } };
case 'quickgame':
case 'alipay':
case 'huawei':
return MINIGAME_ENGINE_GLUE.some((g) => has(dirs.quickgame, g))
? { ready: true }
: { ready: false, prereq: { kind: 'runtime-missing', dir: posix(dirs.quickgame), looked: [...MINIGAME_ENGINE_GLUE], command: 'node build-tools/cli.js build -t quickgame' } };
case 'android':
// The runtime template is the whole prerequisite: the APK is assembled and
// signed here, on any OS, with nothing from the Android SDK.
return resolveNativeTemplate('android', engineVersion)
? { ready: true }
: { ready: false, prereq: { kind: 'template-missing', id: templateId('android'), version: engineVersion } };
case 'ios': {
// The template comes first because it is the harder blocker: without it the
// export cannot even write the Xcode project. WITH it, a Windows editor
// writes a complete project (the xcframework included) to carry to a Mac —
// the artifact is portable even though Apple's toolchain is not.
if (!resolveNativeTemplate('ios', engineVersion)) {
return { ready: false, prereq: { kind: 'template-missing', id: templateId('ios'), version: engineVersion } };
}
if (process.platform !== 'darwin') return { ready: false, prereq: { kind: 'toolchain-missing', tool: 'macos' } };
return existsSync('/Applications/Xcode.app')
? { ready: true }
: { ready: false, prereq: { kind: 'toolchain-missing', tool: 'xcode' } };
}
default:
return { ready: true };
}
}
// =============================================================================
// Project platform profiles
// =============================================================================
/**
* Everything a mini-game export profile needs when the project did not say.
* Defaults describe a STANDARD host: the vendor-neutral SDK entry, the engine
* build every mini-game host takes, and the generic entry above. A project
* platform that matches those supplies only `id`, `label` and `emitConfigFiles`.
*/
export const MINIGAME_PROFILE_DEFAULTS = {
sdkEntryFile: 'index.minigame.js',
sdkLeanEntryFile: 'index.minigame.lean.js',
runtimeInit: 'initMiniGameRuntime',
engineGlueCandidates: MINIGAME_ENGINE_GLUE,
esTarget: 'es2017' as const,
wasmBuildHint: MINIGAME_ENGINE_BUILD,
sideModuleBuildTargets: {} as Readonly<Record<string, string>>,
nativeSuffixes: new Set(['.js', '.json']) as ReadonlySet<string>,
// A project's own vendor publishes neither a whitelist nor an API global, so
// its package is staged as cooked and its engine stays in the main package.
packerSuffixes: null as ReadonlySet<string> | null,
hostGlobal: null as string | null,
wasmBrotli: false,
subpackageDir: 'subpackages',
// Most vendors take a root of assets as a subpackage; the ones that want an
// entry script in it say so (WeChat: game.js).
subpackageEntry: undefined as string | undefined,
emitEntry: defaultMiniGameEntry,
};
/**
* What a project profile declares itself to be. A mini-game vendor is a whole
* PLATFORM (its own host, packaging and runtime); a playable ad network is a
* variant of the built-in `playable` target (same browser host, same single-file
* pipeline — only the network's cap, head markup and click-through API differ).
* Absent ⇒ mini-game, which is what every profile written before this meant.
*/
export type ProjectPlatformKind = 'minigame' | 'playable';
/** The shape a `.esengine/platforms/<id>.mjs` default-exports. */
export interface ProjectPlatformModule extends Partial<MiniGameExportProfile>, Partial<PlayableAdProfile> {
id: string;
/** A shipped packaging/runtime profile, opt-in through the existing project platform seam. */
preset?: 'openpaas';
/** Family engine variant to use unless wasmDir overrides it. */
engineBuild?: 'minigame' | 'quickgame';
/** Shown in the platform list (the project names its own platforms). */
label: string;
kind?: ProjectPlatformKind;
blurb?: string;
defaultOut?: string;
/** Engine runtime dir for this platform, relative to the project root.
* Absent → the mini-game runtime the editor ships. */
wasmDir?: string;
/**
* Project-relative module whose default export is the RUNTIME
* `MiniGameProfile`: `{ id, hostLabel, global }` plus any capability this
* vendor replaces — its own video decoder, audio backend, socket or wasm
* loader. The generated entry installs it before booting.
*
* This file is the packaging half of a vendor; that module is the runtime
* half. Naming it here is what joins them.
*/
runtimeProfile?: string;
/** Mini-game kind only — a playable network has no vendor config files. */
emitConfigFiles?(ctx: MiniGameConfigContext): Array<{ file: string; content: string }>;
}
/** A loaded project platform: the export profile plus where its runtime lives. */
export interface ProjectPlatform {
profile: MiniGameExportProfile;
/** Absolute runtime dir, resolved from the module's `wasmDir` or the web default. */
wasmDir: string;
defaultOut: string;
}
function platformDir(root: string): string {
return path.join(root, PROJECT_PLATFORM_DIR);
}
// =============================================================================
// Scaffolding
// =============================================================================
/** Where the generated runtime half goes, relative to the project root. */
const runtimeHalfPath = (scriptsDir: string, id: string): string =>
path.join(scriptsDir, 'platforms', `${id}.runtime.ts`);
/** The packaging half — data plus the one emitter a vendor must write. */
function packagingTemplate(id: string, label: string, runtimeRel: string): string {
return `// Packaging profile for "${label}" — how Estella builds the package.
//
// This is one half of a platform. The other half (${runtimeRel}) describes the
// HOST at runtime, and is where you replace a capability: your own video
// decoder, audio backend, socket or wasm loader.
//
// Everything not set here defaults to a standard mini-game host, so this file
// only carries what is genuinely yours.
export default {
id: '${id}',
label: '${label}',
blurb: '${label} package.',
defaultOut: 'dist-${id}',
// Joins the two halves: the generated entry installs this profile before boot.
runtimeProfile: '${runtimeRel.split(path.sep).join('/')}',
// TODO: emit the config files your host's packer expects. The context carries
// the vendor-neutral facts the pipeline computed.
emitConfigFiles(ctx) {
return [
{
file: 'game.json',
content: JSON.stringify(
{
appName: ctx.title,
orientation: ctx.orientation,
// Lazy asset groups become the host's subpackage roots.
...(ctx.subPackages.length > 0 ? { subPackages: ctx.subPackages } : {}),
},
null,
2,
) + '\\n',
},
];
},
// Uncomment if your host needs its own engine build; the default is the
// editor's web runtime.
// wasmDir: 'build/wasm/${id}',
};
`;
}
/**
* A playable ad network. One file: the pipeline and the host are unchanged (a
* playable always runs in a browser), so all a network can differ in is the size
* it accepts, what it wants in `<head>`, and the API its click-through calls.
*/
function playableTemplate(id: string, label: string): string {
return `// Ad-network profile for "${label}" — how Estella packages a playable for it.
//
// Selected in Package Project → Playable → Ad network. The editor's own networks are
// written against this same contract, so anything they can do, this can.
export default {
id: '${id}',
kind: 'playable',
label: '${label}',
// The size this network accepts for the delivered index.html, and where that
// number comes from — the export quotes the note in its size warning, so keep it
// pointing at the network's docs rather than at a guess.
maxBytes: 5 * 1024 * 1024,
limitNote: 'TODO: cite this network\\'s published limit',
// Optional. Markup for <head> — an orientation meta tag, this network's SDK
// script. Note that some networks forbid ANY external request in a playable.
// emitHead: (ctx) => \`<meta name="ad.orientation" content="\${ctx.orientation}">\`,
// Optional. Installs the bridge the SDK's playableCta() dispatches through, so
// game code never names this network. Runs before the game bundle.
emitBridge: () => \`window.__ESTELLA_PLAYABLE__={cta:function(){
// TODO: call this network's click-through API.
}};\`,
};
`;
}
/** The runtime half — the host global, plus anything this vendor replaces. */
function runtimeTemplate(id: string, label: string): string {
return `// Runtime profile for "${label}" — what the host is, at run time.
//
// Three facts are all that is required. Everything a mini-game host shares —
// filesystem, fetch, canvas, image decode, touch/key input, storage,
// subpackages, audio, sockets, video — comes from the global below.
import type { MiniGameProfile } from 'esengine/minigame';
// TODO: point this at your host's global API object (the wx-shaped one).
declare const HOST_GLOBAL: unknown;
const profile: MiniGameProfile = {
id: '${id}',
hostLabel: '${label}',
// Read through a getter: the host global only exists at run time, so importing
// this file in a bundler or a test must not touch it.
get global() {
if (typeof HOST_GLOBAL === 'undefined') {
throw new Error('[${id}] set \`global\` in this file to your host API object');
}
return HOST_GLOBAL as MiniGameProfile['global'];
},
// ---------------------------------------------------------------------------
// Optional overrides. Write one ONLY where your host genuinely differs, or
// where you want a different implementation than the engine's.
// ---------------------------------------------------------------------------
// Your host does not use the standard \`WebAssembly\` (WeChat, for one, routes
// through WXWebAssembly and takes a package path rather than bytes):
// instantiateWasm(pathOrBuffer, imports) { … },
// Your own video decoding, instead of the engine's wasm MPEG-1 decoder:
// createVideoBackend(ctx) { return new MySoftwareDecoder(ctx); },
// Your own audio or socket transport, instead of the family defaults built on
// the host global:
// createAudioBackend() { return new MyAudioBackend(); },
// createSocket(options) { return new MySocket(options); },
};
export default profile;
`;
}
export interface CreatePlatformResult {
ok: boolean;
error?: string;
/** Project-relative paths of the two files written. */
packagingFile?: string;
runtimeFile?: string;
}
/**
* Scaffold a project platform: both halves, already joined.
*
* The editor writes them rather than asking the developer to create files by
* hand — the shape of a vendor (two files, linked by `runtimeProfile`) is
* exactly the thing that is hard to know before you have seen one.
*/
export async function createProjectPlatform(
root: string,
id: string,
label: string,
scriptsDir: string,
kind: ProjectPlatformKind = 'minigame',
): Promise<CreatePlatformResult> {
const bad = kind === 'playable' ? playableIdProblem(id) : idProblem(id);
if (bad) return { ok: false, error: bad };
if (!label.trim()) return { ok: false, error: 'platform needs a label' };
// A playable network has no runtime half: the host is the browser, unchanged.
if (kind === 'playable') {
const rel = path.join(PROJECT_PLATFORM_DIR, `${id}.mjs`);
const abs = path.join(root, rel);
if (existsSync(abs)) return { ok: false, error: `${rel} already exists` };
try {
await mkdir(path.dirname(abs), { recursive: true });
await writeFile(abs, playableTemplate(id, label), 'utf8');
return { ok: true, packagingFile: posix(rel) };
} catch (err) {
return { ok: false, error: err instanceof Error ? err.message : String(err) };
}
}
const packagingRel = path.join(PROJECT_PLATFORM_DIR, `${id}.mjs`);
const runtimeRel = runtimeHalfPath(scriptsDir, id);
const packagingAbs = path.join(root, packagingRel);
const runtimeAbs = path.join(root, runtimeRel);
if (existsSync(packagingAbs)) return { ok: false, error: `${packagingRel} already exists` };
try {
await mkdir(path.dirname(packagingAbs), { recursive: true });
await mkdir(path.dirname(runtimeAbs), { recursive: true });
await writeFile(packagingAbs, packagingTemplate(id, label, runtimeRel), 'utf8');
// Never clobber a runtime half the developer already wrote.
if (!existsSync(runtimeAbs)) await writeFile(runtimeAbs, runtimeTemplate(id, label), 'utf8');
return { ok: true, packagingFile: posix(packagingRel), runtimeFile: posix(runtimeRel) };
} catch (err) {
return { ok: false, error: err instanceof Error ? err.message : String(err) };
}
}
/** Ids that would collide with a built-in, or that are unsafe as a directory name. */
function idProblem(id: unknown): string | null {
if (typeof id !== 'string' || id.length === 0) return 'profile has no string `id`';
if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) return `id "${id}" must be lowercase letters, digits and dashes`;
if ((BUILTIN_PLATFORMS as readonly string[]).includes(id)) return `id "${id}" is a built-in platform`;
return null;
}
/** A playable network's id: same spelling rules, but it competes with the networks
* the editor ships rather than with the platform list. */
function playableIdProblem(id: unknown): string | null {
if (typeof id !== 'string' || id.length === 0) return 'profile has no string `id`';
if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) return `id "${id}" must be lowercase letters, digits and dashes`;
if (builtinPlayableProfile(id)) return `id "${id}" is a built-in ad network`;
return null;
}
/**
* Whether the user has approved a project platform profile. Injected (rather than
* threading a userData path through every catalog signature) the same way
* setAssetRefProblemResolver injects the editor's registry into the control surface.
*
* Unset means "not gated" — the pure-Node tests and any caller that has no user to
* ask see the pre-gate behaviour, which is what keeps this module unit-testable.
*/
let trustGate: ((id: string, file: string) => boolean) | null = null;
export function setPlatformTrustGate(fn: ((id: string, file: string) => boolean) | null): void {
trustGate = fn;
}
/** Id a platform profile file is approved under (shared with the Plugins panel). */
export const platformTrustId = (file: string): string => `platform.${path.basename(file, '.mjs')}`;
/**
* Import one project platform module. Returns its raw export, an error string, or
* `untrusted` when the user hasn't approved it — never throws: a project that ships
* a broken profile must still be able to open the dialog and package for every
* other target.
*
* The trust check comes FIRST and is the whole reason it exists here: this import
* runs project-supplied code in the MAIN process, with full Node — strictly more
* privileged than a renderer plugin, which the editor already gates. Leaving it open
* while gating the plugin would have the protection backwards.
*/
async function importPlatformModule(
file: string,
): Promise<{ mod?: ProjectPlatformModule; error?: string; untrusted?: boolean }> {
if (trustGate && !trustGate(platformTrustId(file), file)) return { untrusted: true };
try {
// Cache-busted so editing the profile and re-opening the dialog picks it up
// without restarting the editor.
const url = `${pathToFileURL(file).href}?t=${Date.now()}`;
const ns = (await import(/* @vite-ignore */ url)) as { default?: unknown };
const mod = ns.default;
if (!mod || typeof mod !== 'object') return { error: 'module has no default export object' };
const candidate = mod as ProjectPlatformModule;
// A playable network shares the `playable` target's id space (it is a variant of
// it, not a rival platform), so only a mini-game platform must avoid built-in ids.
const bad = candidate.kind === 'playable' ? playableIdProblem(candidate.id) : idProblem(candidate.id);
if (bad) return { error: bad };
if (typeof candidate.label !== 'string' || !candidate.label) return { error: 'profile has no `label`' };
if (candidate.kind === 'playable') {
if (typeof candidate.maxBytes !== 'number' || !(candidate.maxBytes > 0)) {
return { error: 'playable profile needs a positive `maxBytes` (the size this network accepts)' };
}
if (candidate.maxHtmlBytes !== undefined && (!Number.isFinite(candidate.maxHtmlBytes) || candidate.maxHtmlBytes <= 0)) {
return { error: 'playable profile needs a positive finite `maxHtmlBytes`' };
}
if (typeof candidate.limitNote !== 'string' || !candidate.limitNote) {
return { error: 'playable profile needs a `limitNote` saying where `maxBytes` comes from' };
}
if (candidate.delivery !== undefined && candidate.delivery !== 'single-html' && candidate.delivery !== 'zip') {
return { error: `\`delivery\` must be 'single-html' or 'zip' (got ${JSON.stringify(candidate.delivery)})` };
}
if (candidate.zipFileName !== undefined && !isPlayableZipFileName(candidate.zipFileName)) {
return { error: '`zipFileName` must be a portable alphanumeric/underscore ZIP filename' };
}
if (candidate.allowedExternalScripts !== undefined && (!Array.isArray(candidate.allowedExternalScripts) || !candidate.allowedExternalScripts.every(url => typeof url === 'string' && /^https:\/\//.test(url)))) {
return { error: 'allowedExternalScripts must list exact HTTPS host SDK URLs' };
}
if (candidate.requiredSdk !== undefined && (!candidate.requiredSdk || typeof candidate.requiredSdk.url !== 'string' || !/^https:\/\//.test(candidate.requiredSdk.url) || !['head', 'body-before-game'].includes(candidate.requiredSdk.placement))) {
return { error: 'requiredSdk needs an HTTPS URL and head/body-before-game placement' };
}
if (candidate.configOrientationField !== undefined && (typeof candidate.configOrientationField !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(candidate.configOrientationField))) {
return { error: 'configOrientationField must name a JSON field' };
}
for (const hook of ['emitHead', 'emitBody', 'emitBridge', 'emitZipFiles'] as const) {
if (candidate[hook] !== undefined && typeof candidate[hook] !== 'function') {
return { error: `playable profile hook ${hook} must be a function` };
}
}
return { mod: candidate };
}
if (candidate.preset !== undefined && candidate.preset !== 'openpaas') return { error: 'unknown mini-game profile preset' };
if (candidate.engineBuild !== undefined && !['minigame', 'quickgame'].includes(candidate.engineBuild)) {
return { error: 'engineBuild must be minigame or quickgame' };
}
if (candidate.entryFile !== undefined && (typeof candidate.entryFile !== 'string'
|| !/^[A-Za-z0-9_-][A-Za-z0-9_.-]*\.js$/.test(candidate.entryFile))) {
return { error: 'entryFile must be a root-level JavaScript filename' };
}
if (!candidate.preset && typeof candidate.emitConfigFiles !== 'function') return { error: 'profile has no `emitConfigFiles(ctx)`' };
return { mod: candidate };
} catch (err) {
return { error: err instanceof Error ? err.message : String(err) };
}
}
/** Every `.mjs` under the project's platform dir, sorted for a stable list. */
async function projectPlatformFiles(root: string): Promise<string[]> {
const dir = platformDir(root);
if (!existsSync(dir)) return [];
try {
const names = await readdir(dir);
return names.filter((n) => n.endsWith('.mjs')).sort().map((n) => path.join(dir, n));
} catch {
return [];
}
}
/**
* Load the project platform with this id, merged over the family defaults and
* ready to hand to {@link exportMiniGame}. Null when there is no such platform.
*/
export async function loadProjectPlatform(root: string, id: string, dirs: PlatformRuntimeDirs): Promise<ProjectPlatform | null> {
for (const file of await projectPlatformFiles(root)) {
const { mod } = await importPlatformModule(file);
if (!mod || mod.id !== id || mod.kind === 'playable') continue;
// The runtime half is resolved to an absolute path here: the generated entry
// is bundled with `resolveDir` at the project root, but an absolute specifier
// is unambiguous whatever the profile wrote.
const runtimeProfileModule = mod.runtimeProfile
? (path.isAbsolute(mod.runtimeProfile) ? mod.runtimeProfile : path.join(root, mod.runtimeProfile))
: undefined;
const preset = mod.preset === 'openpaas' ? openpaasExportProfile : {};
const profile = { ...MINIGAME_PROFILE_DEFAULTS, ...preset, ...mod, runtimeProfileModule,
...(runtimeProfileModule ? { runtimeProfileHost: undefined } : {}),
} as MiniGameExportProfile;
const wasmDir = mod.wasmDir
? (path.isAbsolute(mod.wasmDir) ? mod.wasmDir : path.join(root, mod.wasmDir))
: dirs[mod.engineBuild ?? (mod.preset === 'openpaas' ? 'quickgame' : 'minigame')];
return { profile, wasmDir, defaultOut: mod.defaultOut ?? `dist-${id}` };
}
return null;
}
// =============================================================================
// Playable ad networks
// =============================================================================
/** One row of the network picker. Serializable by construction (it crosses IPC). */
export interface PlayableNetworkOption {
id: string;
label: string;
source: 'builtin' | 'project';
/** Project networks only — the profile that defines it, project-relative. A network
* the project WROTE is a file it has to be able to find and edit, so the dialog can
* point at it (and at the error, when one fails to load). */
file?: string;
/** Present when a project profile failed to load, and why — the row still appears. */
error?: string;
}
/**
* Every ad network this project can package a playable for: the ones the editor
* ships, then the project's own. One list, one contract — a network the editor
* never heard of appears here on equal terms, which is the whole point of the
* `kind: 'playable'` profile.
*/
export async function listPlayableNetworks(root: string | null): Promise<PlayableNetworkOption[]> {
const out: PlayableNetworkOption[] = BUILTIN_PLAYABLE_PROFILES
.map((p) => ({ id: p.id, label: p.label, source: 'builtin' as const }));
if (!root) return out;
for (const file of await projectPlatformFiles(root)) {
const { mod, error, untrusted } = await importPlatformModule(file);
// A broken profile is NAMED rather than dropped — a project that wrote a file
// and sees nothing cannot tell the difference between "not loaded" and "typo".
// The same applies to one awaiting approval.
const rel = posix(path.relative(root, file));
if (untrusted) {
const id = path.basename(file, '.mjs');
if (!out.some((p) => p.id === id)) {
out.push({ id, label: path.basename(file), source: 'project', file: rel, error: 'awaiting approval in the Plugins panel' });
}
continue;
}
if (error) {
const id = path.basename(file, '.mjs');
if (!out.some((p) => p.id === id)) out.push({ id, label: path.basename(file), source: 'project', file: rel, error });
continue;
}
if (!mod || mod.kind !== 'playable') continue;
out.push({ id: mod.id, label: mod.label, source: 'project', file: rel });
}
return out;
}
/**
* Resolve a network id to the profile the playable export runs with. Built-ins
* first, then the project's; an id that resolves to nothing falls back to generic
* rather than failing the export — a package that ships without a click-through is
* still a package, and the missing network is reported as a warning by the caller.
*/
export async function loadPlayableProfile(root: string | null, id: string | undefined): Promise<PlayableAdProfile | null> {
if (!id) return genericPlayableProfile;
const builtin = builtinPlayableProfile(id);
if (builtin) return builtin;
if (!root) return null;
for (const file of await projectPlatformFiles(root)) {
const { mod } = await importPlatformModule(file);
if (!mod || mod.kind !== 'playable' || mod.id !== id) continue;
// Field by field rather than a spread: this object crosses into the export as a
// profile, and a project module carrying stray keys (or a mini-game field) must
// not become part of one.
return {
id: mod.id,
label: mod.label,
maxBytes: mod.maxBytes as number,
limitNote: mod.limitNote as string,
maxHtmlBytes: mod.maxHtmlBytes,
delivery: mod.delivery,
zipFileName: mod.zipFileName,
allowedExternalScripts: mod.allowedExternalScripts,
requiredSdk: mod.requiredSdk,
configOrientationField: mod.configOrientationField,
deliveryNote: mod.deliveryNote,
emitHead: mod.emitHead,
emitBody: mod.emitBody,
emitZipFiles: mod.emitZipFiles,
emitBridge: mod.emitBridge,
};
}
return null;
}
// =============================================================================
// The catalog
// =============================================================================
/**
* Every platform this project can target, built-ins first, then the project's
* own — each with its readiness probed.
*/
export async function listPlatforms(
root: string | null, dirs: PlatformRuntimeDirs, engineVersion: string,
/** The compilers this machine has, one per target a package can be built
* for. Required rather than probed here so the caller passes the SAME
* answers to the export — a readiness the dialog computed one way and the
* export another is worse than none. */
toolchains: AotToolchains,
): Promise<PlatformStatus[]> {
const out: PlatformStatus[] = BUILTIN_PLATFORMS.map((id) => ({
id,
source: 'builtin' as const,
...builtinReadiness(id, dirs, engineVersion),
}));
if (!root) return out;
for (const file of await projectPlatformFiles(root)) {
const { mod, error, untrusted } = await importPlatformModule(file);
if (untrusted) {
out.push({
id: path.basename(file, '.mjs'),
source: 'project',
ready: false,
label: path.basename(file),
needsTrust: true,
});
continue;
}
if (error || !mod) {
out.push({
id: path.basename(file, '.mjs'),
source: 'project',
ready: false,
label: path.basename(file),
error,
});
continue;
}
// A playable network is not a platform row — it is chosen inside the built-in
// `playable` target (Project Settings → Packaging → Playable).
if (mod.kind === 'playable') continue;
const wasmDir = mod.wasmDir
? (path.isAbsolute(mod.wasmDir) ? mod.wasmDir : path.join(root, mod.wasmDir))
: dirs[mod.engineBuild ?? (mod.preset === 'openpaas' ? 'quickgame' : 'minigame')];
// A runtime half that points nowhere is caught here rather than on a device:
// the export would bundle fine and then fail to resolve the import.
if (mod.runtimeProfile) {
const abs = path.isAbsolute(mod.runtimeProfile) ? mod.runtimeProfile : path.join(root, mod.runtimeProfile);
if (![abs, `${abs}.ts`, `${abs}.js`, `${abs}.mjs`].some(existsSync)) {
out.push({
id: mod.id,
source: 'project',
ready: false,
label: mod.label,
error: `runtimeProfile "${mod.runtimeProfile}" does not exist`,
});
continue;
}
}
const glues = mod.engineGlueCandidates ?? MINIGAME_PROFILE_DEFAULTS.engineGlueCandidates;
const ready = glues.some((g) => existsSync(path.join(wasmDir, g)));
out.push({
id: mod.id,
source: 'project',
ready,
label: mod.label,
blurb: mod.blurb,
defaultOut: mod.defaultOut ?? `dist-${mod.id}`,
sizeBudgets: mod.sizeBudgets,
prereq: ready
? undefined
// No command: the editor does not know how this project builds its own
// engine runtime, so it reports where it looked and stops there.
: { kind: 'runtime-missing', dir: posix(path.relative(root, wasmDir) || wasmDir), looked: [...glues] },
});
}
return withAotPrereq(out, root, toolchains);
}
/** What a machine has for each road a compiled module can be built along. */
export interface AotToolchains {
/** emcc, for a module that shares the engine's memory. */
emcc: string | null;
/** The host's own C compiler, for a library a native host loads. */
cc: string | null;
/** Whether the Android NDK is here, which cross-compiles an Android package's module. Absent: not probed. */
ndk?: boolean;
}
/**
* Mark the targets whose export would compile systems this machine cannot build.
*
* Unlike Xcode this cannot be deferred: the module ships inside the package. A
* project that promised nothing is told nothing, and a row already blocked by a
* missing engine runtime keeps that harder answer.
*/
function withAotPrereq(
rows: PlatformStatus[], root: string, toolchains: AotToolchains,
): PlatformStatus[] {
if (!promisesCompilation(root)) return rows;
for (const row of rows) {
if (!row.ready) continue;
const target = compileTargetFor(row.id);
if (target === null) continue;
// One probe per road: a machine with emcc and no cc packages for the web
// and not for the desktop, and being sent to install the other toolchain
// is worse than being told nothing.
// Android cross-compiles: its compiler is the NDK, not this machine's own cc.
const android = row.id === 'android';
if (target === 'wasm' ? toolchains.emcc : android ? toolchains.ndk !== false : toolchains.cc) continue;
row.ready = false;
row.prereq = { kind: 'toolchain-missing', tool: target === 'wasm' ? 'emsdk' : android ? 'ndk' : 'hostcc' };
}
return rows;
}