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.

36.4 KB
Raw Blame
// 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;
}