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.

54.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// Package a project without the editor. `--help` states the options.
import path from 'node:path';
import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { createRequire } from 'node:module';
import { installedTemplateDir, iosTemplateSources } from '../../build-tools/utils/nativeTemplate.js';

const HERE = path.dirname(fileURLToPath(import.meta.url));
const PIPELINE = path.join(HERE, '..');
const REPO = path.join(PIPELINE, '..');

const USAGE = `usage: node pipeline/bin/estella.mjs create <template> <dir> [--name <project name>]
       node pipeline/bin/estella.mjs templates
       node pipeline/bin/estella.mjs tools status [--json]
       node pipeline/bin/estella.mjs tools install <tool> [--yes] [--base <dir|url>]
       node pipeline/bin/estella.mjs tools remove <tool>
       node pipeline/bin/estella.mjs luban gen|check <projectDir>
       node pipeline/bin/estella.mjs proto gen|check <projectDir>
       node pipeline/bin/estella.mjs export <projectDir> [options]
       node pipeline/bin/estella.mjs import-model <file.gltf|file.glb|file.fbx> [outDir]
                                     [--project <dir>] [--scale <n>]
                                     [--specular-map color|orm] [--lightmap-uv] [--lods <0-3>]
       node pipeline/bin/estella.mjs import-hdr <file.hdr> [outDir] [--face-size <n>]
       node pipeline/bin/estella.mjs bake-scene <scene.esscene> [--check]
       node pipeline/bin/estella.mjs package-openpaas <exportDir> --config <local.json> --out <game.sp>

  --platform <id>     a built-in (web, desktop, wechat, douyin, kuaishou, bilibili, playable, android, ios)
                      or a platform the project defines in .esengine/platforms/ (default web)
  --profile <name>    one of the project's export profiles (packaging.profiles): its
                      target, development or shipping, and the settings it overrides
                      A shipping Android build is signed with the project's release
                      key (platforms.android.releaseKey); its passphrase comes from
                      ESTELLA_ANDROID_KEY_PASSPHRASE
  --out <dir>         output dir (default <projectDir>/dist-<platform>)
  --wasm <dir>        engine runtime to ship (default: the build tree, else the editor's copy)
  --scene <path>      entry scene, project-relative (default: the project's own)
  --title <name>      app title (default: the project's name)
  --scripts <path>    scripts entry, project-relative (default: the project's scripts.main)
  --template <dir>    android/ios/desktop: the runtime template to wrap, else the installed one
  --output project    android: emit a Gradle project instead of an apk
  --emulator-abi      android: also carry the emulator's x86_64 libraries (about half of an empty
                      package; phones do not run them, so the default leaves them out)
  --json <file>       also write the result here, for a caller that reads it back
  --enforce-budget    fail (exit 1) when the package is over a size limit
  --minify            minify the bundled scripts, as a shipping build (or profile) does
  --debug-channel <url>  a development build dials this editor address
                      (ws://host:port/?token=…) so its frames can be captured;
                      refused together with --minify
  --no-aot            package without compiling the systems marked @compiled, so
                      the same project runs both ways and the frames are compared
  --steam-sdk <dir>   desktop: a Steamworks SDK whose redistributable ships in the app
  --steam-appid <id>  desktop: also write the Steam depot scripts for this app id

The result is printed as JSON: errors, warnings, and what the package weighs
against the limits in force. The size report rides the result rather than being a
second file — \`result.size\` carries the verdicts the build dialog draws, so CI
and the editor cannot disagree about whether a build fits.

import-model writes one \`.esmesh\` per triangle primitive next to the source (or
into outDir), the images the file carries inline, and one \`.esprefab\` placing
each piece where the source's node tree puts it, with its image and tint. A model
holds many primitives, so it is a source that PRODUCES assets rather than one the
engine loads — the products are what a scene references. Asset refs are
project-relative, so the project is found above the source unless --project says
otherwise; --scale sizes the model, whose metres are world units otherwise.
--specular-map orm reads an FBX's specular map as packed occlusion/roughness/
metalness (Falcor-era scenes such as Bistro); the source's own \`.meta\` setting
is used when the flag is absent. DDS images are converted to PNG on the way in.
--lightmap-uv gives every mesh a lightmap UV set (Generate Lightmap UVs in the
editor), unwrapping one where the source's second set is too sparse to bake into.
--lods <n> writes n cheaper levels of every mesh (about 50%, 20% and 7% of its
triangles) as <mesh>_lod<n>.esmesh and a LODGroup that swaps them in (Generate
LODs in the editor); skinned and morphing meshes keep one level.

import-hdr bakes an equirectangular panorama into the two things a renderer asks
an environment for: nine irradiance coefficients (in the \`.esenv\`) and one
prefiltered octahedral atlas beside it, which the document names as a sibling.
The panorama itself is not shipped — a light references the \`.esenv\`.`;

/** Options take a value; these do not — without the distinction a trailing flag
 *  swallows nothing, ends the loop, and a CI job silently gets no gate. */
const FLAGS = new Set(['enforce-budget', 'minify', 'no-aot', 'emulator-abi']);

function parseArgs(argv) {
  const [command, projectDir, ...rest] = argv;
  if (command === '--help' || command === '-h' || command === 'help') {
    console.log(USAGE);
    process.exit(0);
  }
  if (command === 'templates') return { command };
  // Optional third-party tools (a project switches them on in project.esproject `tools`; nothing here
  // fetches one the project did not ask for, and `install` shows what it would download and asks first).
  if (command === 'tools') {
    const sub = projectDir;
    const flags = rest.filter((a) => a.startsWith('--'));
    const base = rest.indexOf('--base');
    const id = rest.find((a, i) => !a.startsWith('--') && !(base >= 0 && i === base + 1));
    if (!['status', 'install', 'remove'].includes(sub) || (sub !== 'status' && !id)) {
      console.error('usage: tools status [--json] | tools install <tool> [--yes] [--base <dir|url>] | tools remove <tool>');
      process.exit(2);
    }
    return { command, sub, id, yes: flags.includes('--yes'), json: flags.includes('--json'), base: base >= 0 ? rest[base + 1] : undefined };
  }
  if (command === 'luban' || command === 'proto') {
    if (!['gen', 'check'].includes(projectDir) || !rest[0]) {
      console.error(`usage: ${command} gen|check <projectDir>`);
      process.exit(2);
    }
    return { command, sub: projectDir, projectDir: path.resolve(rest[0]) };
  }
  if (command === 'create') {
    const named = rest.indexOf('--name');
    if (!projectDir || !rest[0] || rest[0].startsWith('--')) {
      console.error('create requires a template and a folder: node pipeline/bin/estella.mjs create <template> <dir> [--name <project name>]');
      process.exit(2);
    }
    return { command, template: projectDir, dest: path.resolve(rest[0]), name: named >= 0 ? rest[named + 1] : undefined };
  }
  if (command === 'bake-scene') {
    if (!projectDir) {
      console.error(USAGE);
      process.exit(2);
    }
    return { command, source: path.resolve(projectDir), check: rest.includes('--check') };
  }
  if (command === 'package-openpaas') {
    const config = rest.indexOf('--config'), out = rest.indexOf('--out');
    if (!projectDir || config < 0 || !rest[config + 1] || out < 0 || !rest[out + 1]) {
      console.error('package-openpaas requires an exported directory, --config <local.json> and --out <game.sp>');
      process.exit(2);
    }
    return { command, source: path.resolve(projectDir), config: path.resolve(rest[config + 1]), out: path.resolve(rest[out + 1]) };
  }
  if (command === 'import-model' || command === 'import-gltf' || command === 'import-hdr') {
    if (!projectDir) {
      console.error(USAGE);
      process.exit(2);
    }
    const flag = rest.indexOf('--project');
    const scale = rest.indexOf('--scale');
    const faceSize = rest.indexOf('--face-size');
    const specular = rest.indexOf('--specular-map');
    const lightmapUV = rest.includes('--lightmap-uv');
    const lods = rest.indexOf('--lods');
    const out = rest[0] && !rest[0].startsWith('--') ? path.resolve(rest[0]) : null;
    return {
      command, out, source: path.resolve(projectDir),
      project: flag >= 0 && rest[flag + 1] ? path.resolve(rest[flag + 1]) : null,
      scale: scale >= 0 ? Number(rest[scale + 1]) || 1 : 1,
      faceSize: faceSize >= 0 ? Number(rest[faceSize + 1]) || undefined : undefined,
      specularMap: specular >= 0 ? rest[specular + 1] : undefined,
      lightmapUV,
      lodLevels: lods >= 0 ? Number(rest[lods + 1]) : undefined,
    };
  }
  if (command !== 'export' || !projectDir) {
    console.error(USAGE);
    process.exit(2);
  }
  const opts = { projectDir: path.resolve(projectDir) };
  for (let i = 0; i < rest.length;) {
    const key = rest[i]?.replace(/^--/, '');
    if (!key) break;
    if (FLAGS.has(key)) { opts[key] = true; i += 1; continue; }
    const value = rest[i + 1];
    if (value === undefined) break;
    opts[key] = value;
    i += 2;
  }
  return opts;
}

const firstExisting = (candidates) => candidates.find((c) => c && existsSync(c));
const fileUrl = (p) => `file:///${p.replace(/\\/g, '/')}`;

/** Which desktop template this machine can also RUN, for --template. */
const HOST_DESKTOP_OS = process.platform === 'darwin' ? 'macos'
  : process.platform === 'win32' ? 'windows' : 'linux';

/**
 * Bundle a pipeline entry to a temp module and import it. ESM, because the cook
 * reads `import.meta.url` (the basis encoder locates its binary that way) — and
 * with a `require` shim, because some dependencies are CommonJS (pngjs). esbuild
 * itself stays external and resolves at runtime.
 */
const BAKE_IDENTITY_Q = { x: 0, y: 0, z: 0, w: 1 };
const BAKE_ONE = { x: 1, y: 1, z: 1 };
const BAKE_ZERO = { x: 0, y: 0, z: 0 };

const bakeComponent = (entity, type) => entity.components?.find((c) => c.type === type);

/** The project a scene belongs to: the nearest ancestor holding a `.esproject`.
 *  An asset ref is PROJECT-relative, which is what the editor resolves against. */
function bakeProjectRoot(sceneFile) {
  let dir = path.dirname(sceneFile);
  for (;;) {
    if (existsSync(path.join(dir, 'project.esproject'))) return dir;
    const up = path.dirname(dir);
    if (up === dir) return null;
    dir = up;
  }
}

/** uuid -> project-relative path, out of the `.meta` beside each asset. A scene
 *  the editor saved names its assets by uuid and one a person wrote names them
 *  by path; both have to reach the same file. */
function bakeAssetIndex(root) {
  const index = new Map();
  if (!root) return index;
  const walk = (dir) => {
    for (const entry of readdirSync(dir, { withFileTypes: true })) {
      const at = path.join(dir, entry.name);
      if (entry.isDirectory()) { if (entry.name[0] !== '.') walk(at); continue; }
      if (!entry.name.endsWith('.meta')) continue;
      try {
        const uuid = JSON.parse(readFileSync(at, 'utf8')).uuid;
        if (typeof uuid === 'string') {
          index.set(uuid, path.relative(root, at.slice(0, -'.meta'.length)).split(path.sep).join('/'));
        }
      } catch { /* a half-written .meta names nothing */ }
    }
  };
  walk(root);
  return index;
}
const bakeVec = (v, fallback) => ({ ...fallback, ...(v ?? {}) });
// Match the Transform component's float32 fields before composing a world pose.
const bakeWorldVec = (v, fallback) => Object.fromEntries(
  Object.entries(bakeVec(v, fallback)).map(([key, value]) => [key, Math.fround(value)]));

/** Column-major 4x4 from a document's Transform, through the SDK's own compose.
 *  Flat scenes only — see bakeScene. */
function bakeTransformOf(baker, entity) {
  const tf = bakeComponent(entity, 'Transform')?.data ?? {};
  return baker.composeTRS(bakeWorldVec(tf.position, BAKE_ZERO),
                          bakeWorldVec(tf.rotation, BAKE_IDENTITY_Q),
                          bakeWorldVec(tf.scale, BAKE_ONE));
}

/**
 * Bakes a shipped scene, or checks that what is committed IS a bake of it.
 *
 * Reads the DOCUMENT rather than a world, which is why a scene with a hierarchy
 * is refused: resolving one is the editor's job, and an atlas lit for a place
 * nothing is at looks like a bake that is wrong rather than one never run.
 */
async function bakeScene(baker, meta, sceneFile, check) {
  const sceneDir = path.dirname(sceneFile);
  const rel = path.relative(REPO, sceneFile);
  const scene = JSON.parse(readFileSync(sceneFile, 'utf8'));

  const parented = (scene.entities ?? []).filter((e) => e.parent != null);
  if (parented.length > 0) {
    console.error(`bake-scene: ${rel} has ${parented.length} parented entit(ies), whose world`
      + ' transforms only the editor resolves — bake it there instead.');
    return 1;
  }
  const instances = (scene.entities ?? []).filter((e) => typeof e.prefab === 'string');
  if (instances.length > 0) {
    console.error(`bake-scene: ${rel} has ${instances.length} prefab instance(s), whose contents`
      + ' only the editor expands — bake it there instead.');
    return 1;
  }

  // The scene's own knobs, where it states them. Absent leaves the bake at its
  // defaults, which is what every scene got before the component existed.
  const declared = (scene.entities ?? [])
    .map((e) => bakeComponent(e, 'BakedLighting')).find(Boolean)?.data ?? {};
  const options = {
    atlasSize: declared.atlasSize, texelsPerUnit: declared.texelsPerUnit,
    bounces: declared.bounces, samples: declared.samples,
    probeSamples: declared.probeSamples,
  };
  for (const k of Object.keys(options)) if (typeof options[k] !== 'number') delete options[k];
  if (declared.skyOcclusion === true) options.skyOcclusion = true;

  // Where an asset ref resolves to. Not relative to the SCENE: a ref is what the
  // project's asset browser shows, and the editor resolves it against the root.
  const projectRoot = bakeProjectRoot(sceneFile);
  // The frame lights with the colour linearized in a linear project; so must the bake.
  let linearColor = false;
  try {
    const manifest = JSON.parse(readFileSync(path.join(projectRoot, 'project.esproject'), 'utf8'));
    linearColor = manifest.features?.rendering?.colorSpace === 'linear';
  } catch { /* no project: the gamma pipeline, as the runtime defaults to */ }
  const byUuid = bakeAssetIndex(projectRoot);
  const resolveRef = (ref) => {
    if (typeof ref !== 'string' || ref === '') return '';
    const relative = ref.startsWith('@uuid:') ? byUuid.get(ref.slice(6)) : ref;
    if (!relative) return '';
    return projectRoot ? path.resolve(projectRoot, relative) : path.resolve(sceneDir, relative);
  };

  const surfaces = [];
  const lights = [];
  const volumes = [];
  const reflectionProbes = [];
  const ambient = [0, 0, 0];
  // The sky a capture sees and the format its atlas adopts: the frame's environment,
  // which `sceneEnvironment` answers for every door that needs it (see below).
  let environment = null;
  const readEnvironment = (ref) => {
    const file = resolveRef(ref);
    if (!file || !existsSync(file)) return null;
    try {
      const document = JSON.parse(readFileSync(file, 'utf8'));
      // A sibling of the document, which is how an import names it — or a ref,
      // which is how one survives a package renaming files to their hash.
      const spec = typeof document.specular === 'string' ? document.specular : '';
      const atlas = spec.startsWith('@uuid:') ? resolveRef(spec)
                                              : path.resolve(path.dirname(file), spec);
      return { document, atlasPng: atlas && existsSync(atlas)
        ? new Uint8Array(readFileSync(atlas)) : new Uint8Array() };
    } catch { return null; }
  };
  // The REF as the document spells it, not the path it resolves to: the editor's
  // collector fingerprints the same string, and an absolute path would differ
  // between two checkouts of one project.
  const fingerprintSurfaces = [];
  for (const entity of scene.entities ?? []) {
    const tf = bakeComponent(entity, 'Transform')?.data ?? {};
    const mesh = bakeComponent(entity, 'MeshRenderer');
    const light = bakeComponent(entity, 'Light');
    const volume = bakeComponent(entity, 'LightProbeVolume');
    if (volume && volume.data?.enabled !== false) {
      const p = bakeWorldVec(tf.position, BAKE_ZERO);
      const h = bakeVec(volume.data?.halfExtents, { x: 100, y: 100, z: 100 });
      volumes.push({
        entity: entity.id, label: entity.name ?? String(entity.id),
        center: [p.x, p.y, p.z], halfExtents: [h.x, h.y, h.z],
        spacing: volume.data?.spacing ?? 100,
      });
    }
    // A decal is not a lightmap receiver: what it prints on was baked already,
    // and baking the overlay too would light the same surface twice.
    const isDecal = !!bakeComponent(entity, 'DecalProjector');
    if (mesh && mesh.data?.enabled !== false && !isDecal) {
      const ref = typeof mesh.data?.mesh === 'string' ? mesh.data.mesh : '';
      const builtin = ref.startsWith('builtin:') ? ref : undefined;
      const file = builtin ? '' : resolveRef(ref);
      if (builtin || (ref && existsSync(file))) {
        const c = mesh.data?.color;
        const body = bakeComponent(entity, 'RigidBody3D');
        const textureRef = typeof mesh.data?.texture === 'string' ? mesh.data.texture : '';
        const textureFile = resolveRef(textureRef);
        const materialRef = typeof mesh.data?.material === 'string' ? mesh.data.material : '';
        const materialFile = resolveRef(materialRef);
        const transform = bakeTransformOf(baker, entity);
        const holdsStill = baker.bakeHoldsStill({
          characterController: !!bakeComponent(entity, 'CharacterController3D'),
          bodyType: body ? (body.data?.bodyType ?? 2) : undefined,
        });
        const albedo = c ? [c.r ?? 1, c.g ?? 1, c.b ?? 1] : undefined;
        surfaces.push({
          entity: entity.id, label: entity.name ?? String(entity.id),
          meshFile: file, builtinRef: builtin, transform,
          baseColor: albedo, holdsStill, realtimeDirect: mesh.data?.lit === true,
          twoSided: mesh.data?.cullBackfaces === false,
          material: materialFile && existsSync(materialFile) ? materialFile : undefined,
          baseColorTexture: textureFile && existsSync(textureFile) ? textureFile : undefined,
        });
        fingerprintSurfaces.push({ mesh: ref, transform, albedo, texture: textureRef, holdsStill,
                                   realtimeDirect: mesh.data?.lit === true,
                                   twoSided: mesh.data?.cullBackfaces === false,
                                   material: materialRef || undefined });
      }
    }
    const reflection = bakeComponent(entity, 'ReflectionProbe');
    if (reflection && reflection.data?.enabled !== false) {
      const p = bakeWorldVec(tf.position, BAKE_ZERO);
      reflectionProbes.push({ entity: entity.id, label: entity.name ?? String(entity.id),
                              center: [p.x, p.y, p.z] });
    }
    if (light) {
      const p = bakeWorldVec(tf.position, BAKE_ZERO);
      const made = baker.bakeLightOf(light.data, [p.x, p.y, p.z],
                                     bakeWorldVec(tf.rotation, BAKE_IDENTITY_Q), linearColor);
      if (made?.lamp) lights.push(made.lamp);
      else if (made?.ambient) {
        ambient[0] += made.ambient[0];
        ambient[1] += made.ambient[1];
        ambient[2] += made.ambient[2];
      }
    }
  }

  // The same rule the frame and the editor's collector apply, read once from the
  // document rather than re-derived per light.
  const chosen = baker.sceneEnvironment(baker.sceneAmbientLights(scene.entities ?? [], (ref) => {
    const file = resolveRef(ref);
    return !!file && existsSync(file);
  })).effective;
  if (chosen?.environment) {
    environment = readEnvironment(chosen.environment);
    if (environment) environment.rotation = chosen.rotation;
  }

  const fingerprint = baker.bakeFingerprint({
    surfaces: fingerprintSurfaces, lights,
    volumes: volumes.map((v) => ({ center: v.center, halfExtents: v.halfExtents,
                                   spacing: v.spacing })),
    // A reflection is captured from a POINT, so where it stands is the whole of
    // what it contributes — a moved probe is a stale bake.
    reflections: reflectionProbes.map((p) => p.center),
    ambient, options,
  });
  const kernel = await baker.BakeKernelExecutor.load();
  let result;
  try {
    result = await baker.bakeSceneLightmapParallel({
      surfaces, lights, probeVolumes: volumes, reflectionProbes, environment,
      options: { ...options, ambient },
    }, kernel);
  } finally {
    await kernel.close();
  }
  for (const w of result.warnings) console.warn(`  ! ${w}`);

  const stem = path.basename(sceneFile).replace(/\.esscene$/i, '');
  const atlasName = `${stem}_lightmap.png`;
  const atlasFile = path.join(sceneDir, atlasName);

  // The REF and not the file name: a package addresses assets by uuid and renames
  // files to their content hash. Read from the product's own `.meta`, since `byUuid`
  // was built before this bake wrote anything.
  const refTo = (absFile) => {
    try {
      const meta = JSON.parse(readFileSync(`${absFile}.meta`, 'utf8'));
      return typeof meta.uuid === 'string' ? `@uuid:${meta.uuid}` : '';
    } catch { return ''; }
  };
  const atlasRef = refTo(atlasFile);

  // One file per volume, named for the entity that holds it: adding a second
  // volume must not rename the first one's grid.
  const grids = new Map();
  result.probes.forEach((doc, i) => {
    if (!doc) return;
    const name = `${stem}_probes_${volumes[i].entity}.esprobes`;
    grids.set(volumes[i].entity, {
      name, text: baker.probeDocumentText(doc), ref: refTo(path.join(sceneDir, name)),
    });
  });

  // The scene's reflections: one atlas and one document beside the lightmap, and
  // a column number written onto each probe. Named for the scene rather than for
  // a probe — there is one of these however many probes stand in it.
  const reflectionName = `${stem}_reflections.png`;
  const reflectionDocName = `${stem}_reflections.esenv`;
  const reflectionFile = path.join(sceneDir, reflectionName);
  const reflectionDocFile = path.join(sceneDir, reflectionDocName);
  let reflectionText = null;
  if (result.reflection) {
    result.reflection.document.specular = reflectionName;
    reflectionText = `${JSON.stringify(result.reflection.document, null, 2)}\n`;
  }
  const reflectionRef = reflectionText ? (refTo(reflectionDocFile) || reflectionDocName) : '';

  const placed = new Map();
  result.scaleOffset.forEach((rect, i) => { if (rect) placed.set(surfaces[i].entity, rect); });
  for (const entity of scene.entities ?? []) {
    const rect = placed.get(entity.id);
    const at = entity.components.findIndex((c) => c.type === 'MeshLightmap');
    if (!rect) {
      if (at >= 0) entity.components.splice(at, 1);
      continue;
    }
    const data = { lightmap: atlasRef || atlasName,
                   scaleOffset: { x: rect[0], y: rect[1], z: rect[2], w: rect[3] } };
    if (at >= 0) entity.components[at] = { type: 'MeshLightmap', data };
    else entity.components.push({ type: 'MeshLightmap', data });
  }
  for (const entity of scene.entities ?? []) {
    const at = entity.components.findIndex((c) => c.type === 'BakedLighting');
    if (at < 0) continue;
    entity.components[at] = {
      type: 'BakedLighting',
      data: { ...entity.components[at].data, bakedFrom: fingerprint },
    };
  }
  for (const entity of scene.entities ?? []) {
    const at = entity.components.findIndex((c) => c.type === 'ReflectionProbe');
    if (at < 0) continue;
    // Column 0 is the sky, so the first probe is column 1. A probe the bake did
    // not take keeps neither ref nor column: a stale one would reflect whatever
    // room happens to be baked at that number.
    const column = reflectionProbes.findIndex((p) => p.entity === entity.id);
    entity.components[at] = {
      type: 'ReflectionProbe',
      data: { ...entity.components[at].data,
              reflection: column >= 0 ? reflectionRef : '',
              slot: column >= 0 ? column + 1 : 0 },
    };
  }
  for (const entity of scene.entities ?? []) {
    const at = entity.components.findIndex((c) => c.type === 'LightProbeVolume');
    if (at < 0) continue;
    // A refused volume loses its ref rather than keeping the last grid: a box
    // the author has since resized is not described by what fitted the old one.
    const grid = grids.get(entity.id);
    entity.components[at] = {
      type: 'LightProbeVolume',
      data: { ...entity.components[at].data, probes: grid ? (grid.ref || grid.name) : '' },
    };
  }
  const document = `${JSON.stringify(scene, null, 2)}\n`;

  // A product with no `.meta` has no identity, so the cook carries neither it nor
  // the light in it. Checked here rather than written: a uuid is the stable name
  // refs resolve through, and minting one is the importer's to do.
  const products = [atlasFile, ...[...grids.values()].map((g) => path.join(sceneDir, g.name)),
                    ...(reflectionText ? [reflectionFile, reflectionDocFile] : [])];
  const unnamed = products.filter((f) => existsSync(f) && !existsSync(`${f}.meta`));
  if (check && unnamed.length > 0) {
    for (const f of unnamed) console.error(`bake-scene: ${path.relative(REPO, f)} has no .meta`);
    console.error('A package carries what has an identity. Give them one:'
      + `  node tools/asset-meta.js ${path.relative(REPO, sceneDir)}`);
    return 1;
  }

  if (check) {
    const staleAtlas = !existsSync(atlasFile)
      || Buffer.compare(readFileSync(atlasFile), Buffer.from(result.atlasBytes)) !== 0;
    // The atlas's import settings are the bake's too: an atlas decoded as sRGB, or
    // block-compressed, draws other light than the one that was baked.
    let staleSettings = false;
    if (existsSync(`${atlasFile}.meta`)) {
      const importer = JSON.parse(readFileSync(`${atlasFile}.meta`, 'utf8')).importer ?? {};
      staleSettings = JSON.stringify(baker.claimedLightmapImporter(importer, result.size)) !== JSON.stringify(importer);
    }
    const readText = (file) => readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
    const staleScene = readText(sceneFile) !== document;
    const staleGrids = [...grids.values()].some((g) => {
      const file = path.join(sceneDir, g.name);
      return !existsSync(file) || readText(file) !== g.text;
    });
    const staleReflections = reflectionText != null && (
      !existsSync(reflectionFile)
      || Buffer.compare(readFileSync(reflectionFile),
                        Buffer.from(result.reflection.atlasBytes)) !== 0
      || !existsSync(reflectionDocFile)
      || readText(reflectionDocFile) !== reflectionText);
    if (staleAtlas || staleSettings || staleScene || staleGrids || staleReflections) {
      const what = [staleAtlas && 'the atlas', staleSettings && "the atlas's import settings", staleScene && 'the scene',
                    staleGrids && 'a probe grid',
                    staleReflections && 'the reflections'].filter(Boolean).join(' and ');
      console.error(`bake-scene: ${rel} is not what a bake of it produces (${what} differ).`);
      console.error(`Rebake: node pipeline/bin/estella.mjs bake-scene ${rel}`);
      return 1;
    }
    console.log(`bake-scene: ${rel} matches a fresh bake`
      + ` (${result.lumels} lumel(s) over ${placed.size} object(s)`
      + `${grids.size ? `, ${grids.size} probe grid(s)` : ''}`
      + `${result.reflection ? `, ${result.reflection.columns} reflection column(s)` : ''}).`);
    return 0;
  }

  writeFileSync(atlasFile, result.atlasBytes);
  await baker.claimLightmapImage(atlasFile, result.size);
  for (const g of grids.values()) writeFileSync(path.join(sceneDir, g.name), g.text);
  if (reflectionText) {
    writeFileSync(reflectionFile, result.reflection.atlasBytes);
    writeFileSync(reflectionDocFile, reflectionText);
    // An RGBM encoding of radiance, the three settings an HDR import gives its own
    // atlas. Adopted here because this bake IS this file's importer, and a default
    // meta would linearize the multiplier and then compress it.
    await meta.adoptOrphan(reflectionFile, { sRGB: false, compress: 'off', wrapMode: 'clamp' });
    await meta.adoptOrphan(reflectionDocFile);
  }
  writeFileSync(sceneFile, document);

  // A product written for the first time has no `.meta` yet, so the scene had to
  // name it by file name — which an export cannot resolve. Said here rather than
  // left to --check, since this is the run that produced it.
  const nameless = [atlasRef ? '' : atlasName,
                    ...[...grids.values()].filter((g) => !g.ref).map((g) => g.name)].filter(Boolean);
  if (nameless.length > 0) {
    console.warn(`bake-scene: ${nameless.join(', ')} — no .meta, so the scene names it by file`
      + ' name and a package cannot carry it. Mint one and bake again:'
      + `  node tools/asset-meta.js ${path.relative(REPO, sceneDir)}`);
  }
  console.log(`bake-scene: ${result.lumels} lumel(s) over ${placed.size} object(s)`
    + `${grids.size ? `, ${grids.size} probe grid(s)` : ''}`
    + ` -> ${path.relative(REPO, atlasFile)}`);
  return 0;
}

/** An hour: longer than any run, so this can only be a dir nothing owns. */
const STALE_MS = 60 * 60 * 1000;

/**
 * Remove build dirs a previous run could not: `process.on('exit')` covers a
 * normal end, and Ctrl-C is not one. 277 of them had collected, 219MB of half
 * the toolchain sitting where every source-scanning gate reads.
 */
function sweepStaleBuildDirs(srcDir) {
  const now = Date.now();
  for (const name of readdirSync(srcDir)) {
    if (!name.startsWith('.build-')) continue;
    const dir = path.join(srcDir, name);
    try {
      if (now - statSync(dir).mtimeMs < STALE_MS) continue;
      rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
    } catch { /* a concurrent run may be removing it; either way it is gone. */ }
  }
}

async function loadPipeline(entry, outName) {
  const { outfile, cleanup } = await bundlePipeline(entry, outName);
  try {
    return { mod: await import(fileUrl(outfile)), cleanup };
  } catch (err) {
    cleanup();
    throw err;
  }
}

/** A pipeline module bundled to a runnable file, for a worker thread to start from. */
async function bundlePipeline(entry, outName) {
  const require = createRequire(path.join(PIPELINE, 'package.json'));
  const esbuild = require('esbuild');
  // As deep in the package as the cook is: the Basis encoder is kept external so
  // it finds its own .cjs/.wasm, which means its relative specifier has to
  // resolve from the temp dir the same way it does from the cook.
  sweepStaleBuildDirs(path.join(PIPELINE, 'src'));
  const dir = mkdtempSync(path.join(PIPELINE, 'src', '.build-'));
  const outfile = path.join(dir, outName);
  await esbuild.build({
    entryPoints: [entry],
    outfile,
    bundle: true,
    format: 'esm',
    platform: 'node',
    target: 'node20',
    // 'typescript' (the AOT step parses a project with it) reads `__filename` at
    // load, which an ESM bundle has none of: inlined, the bundle dies before it
    // exports anything.
    external: ['esbuild', 'electron', 'sharp', 'draco3dgltf', 'typescript',
      '../../../build-tools/basis/encoder.mjs', '../../../build-tools/ufbx/reader.mjs',
      '../../../build-tools/lightmap/kernel.mjs'],
    logLevel: 'error',
    banner: {
      js: "import { createRequire as __esCreateRequire } from 'node:module';\n"
        + `const require = __esCreateRequire('${fileUrl(path.join(PIPELINE, 'package.json'))}');\n`,
    },
  });
  let gone = false;
  const cleanup = () => {
    if (gone) return;
    gone = true;
    rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
  };
  // The dir lives inside `pipeline/src`, so one left behind is half the toolchain
  // sitting where every source-scanning gate reads. A caller's own cleanup is a
  // path that can be missed — 277 had been — so the exit is what guarantees it.
  process.on('exit', cleanup);
  return { outfile, cleanup };
}

const PROJECT_FILES = ['project.esproject', 'project.esproj', 'project.json'];

/** The project directory a path sits in, walking up; null when it is outside one. */
/** The flag, else the source's own `.meta` import setting, else the plain reading. */
function specularMapFor(opts) {
  if (opts.specularMap) {
    if (opts.specularMap !== 'color' && opts.specularMap !== 'orm') {
      console.error(`--specular-map must be color or orm, not "${opts.specularMap}"`);
      process.exit(2);
    }
    return opts.specularMap;
  }
  try {
    return JSON.parse(readFileSync(`${opts.source}.meta`, 'utf8')).importer?.specularMap === 'orm' ? 'orm' : 'color';
  } catch {
    return 'color';
  }
}

/** The flag, else the source's own `.meta` import setting — the editor's door reads the same one. */
function lightmapUVFor(opts) {
  if (opts.lightmapUV) return true;
  try {
    return JSON.parse(readFileSync(`${opts.source}.meta`, 'utf8')).importer?.lightmapUV === true;
  } catch {
    return false;
  }
}

/** The flag, else the source's own `.meta` import settings: [levels, minimum triangles]. */
function lodSettingsFor(opts) {
  let importerMeta = {};
  try {
    importerMeta = JSON.parse(readFileSync(`${opts.source}.meta`, 'utf8')).importer ?? {};
  } catch { /* no meta: the schema's defaults */ }
  const levels = Number.isFinite(opts.lodLevels) ? opts.lodLevels : importerMeta.lodLevels;
  const min = importerMeta.lodMinTriangles;
  return {
    levels: typeof levels === 'number' ? Math.min(3, Math.max(0, Math.floor(levels))) : 0,
    minTriangles: typeof min === 'number' && min >= 0 ? min : 256,
  };
}

function findProjectRoot(from) {
  for (let dir = from, prev = ''; dir !== prev; prev = dir, dir = path.dirname(dir)) {
    if (PROJECT_FILES.some((name) => existsSync(path.join(dir, name)))) return dir;
  }
  return null;
}

/** The project's raw settings file, for the fields read before the parser runs. */
function projectSettings(projectDir) {
  for (const name of PROJECT_FILES) {
    const file = path.join(projectDir, name);
    if (existsSync(file)) {
      try {
        return JSON.parse(readFileSync(file, 'utf8'));
      } catch {
        return {};
      }
    }
  }
  return {};
}

/**
 * The engine runtime for this target. The build tree is preferred over the copy
 * synced into the editor's public/, so a machine that built the engine and never
 * built the editor can still package. A mini-game takes a different build of the
 * same engine — handing it the web one is a syntax error at the first `require`.
 */
function engineRuntimeDir(platform) {
  const build = fmt.engineBuildFor(platform);
  const dirs = build === 'quickgame'
    ? [path.join(REPO, 'build', 'wasm', 'quickgame'), path.join(REPO, 'desktop', 'public', 'wasm-quickgame')]
    : build === 'minigame'
      ? [path.join(REPO, 'build', 'wasm', 'wechat'), path.join(REPO, 'desktop', 'public', 'wasm-wechat')]
      : [path.join(REPO, 'build', 'wasm', 'web'), path.join(REPO, 'desktop', 'public', 'wasm')];
  return firstExisting(dirs) ?? dirs[dirs.length - 1];
}

const opts = parseArgs(process.argv.slice(2));

// The editor's New Project gallery and these two are one implementation (src/project/scaffold.ts): the same templates, the same files.
if (opts.command === 'templates' || opts.command === 'create') {
  const { mod, cleanup } = await loadPipeline(path.join(PIPELINE, 'src/project/scaffold.ts'), 'scaffold.mjs');
  try {
    const roots = [{ root: path.join(REPO, 'templates'), kind: 'starter' }, { root: path.join(REPO, 'examples'), kind: 'example' }];
    const found = await mod.listTemplates(roots);
    if (opts.command === 'templates') {
      const width = Math.max(...found.map((t) => path.basename(t.dir).length));
      for (const t of found) console.log(`${path.basename(t.dir).padEnd(width)}  ${t.kind.padEnd(7)}  ${t.description ?? t.name}`);
    } else {
      const template = found.find((t) => path.basename(t.dir) === opts.template);
      if (!template) throw new Error(`no template "${opts.template}"; \`templates\` lists them`);
      const root = await mod.createFromTemplate(template.dir, path.dirname(opts.dest), path.basename(opts.dest), opts.name ?? path.basename(opts.dest));
      console.log(`created ${path.relative(process.cwd(), root) || root} from ${opts.template}`);
      console.log('Open it in the Estella editor once (it stages the SDK types the project\'s tsconfig points at), or export it with:');
      console.log(`  node pipeline/bin/estella.mjs export ${path.relative(process.cwd(), root) || root}`);
    }
  } catch (error) {
    console.error(error.message);
    process.exitCode = 1;
  } finally { cleanup(); }
  process.exit(process.exitCode ?? 0);
}

if (opts.command === 'tools' || opts.command === 'luban' || opts.command === 'proto') {
  const { mod, cleanup } = await loadPipeline(path.join(PIPELINE, 'src', 'tools', 'toolsCli.ts'), 'toolsCli.mjs');
  let code = 1;
  try {
    if (opts.command === 'luban') code = await mod.lubanCommand(opts.sub, opts.projectDir);
    else if (opts.command === 'proto') code = await mod.protoCommand(opts.sub, opts.projectDir);
    else if (opts.sub === 'status') code = mod.toolsStatus({ json: opts.json });
    else if (opts.sub === 'install') code = await mod.toolsInstall(opts.id, { yes: opts.yes, base: opts.base });
    else code = mod.toolsRemove(opts.id);
  } catch (error) {
    console.error(error.message);
  } finally { cleanup(); }
  process.exit(code);
}

if (opts.command === 'package-openpaas') {
  const { mod, cleanup } = await loadPipeline(path.join(PIPELINE, 'src/export/openpaasPackage.ts'), 'openpaasPackage.mjs');
  try {
    console.log(JSON.stringify(await mod.packageOpenPaaS(opts.source, opts.out, opts.config), null, 2));
  } catch (error) {
    console.error(error.message);
    process.exitCode = 1;
  } finally { cleanup(); }
  // No export, login or upload follows packaging.
  process.exit(process.exitCode ?? 0);
}

// `import-gltf` is the name this command shipped under; it reads any of the
// model sources now, and the old spelling keeps working.
if (opts.command === 'import-model' || opts.command === 'import-gltf') {
  const { mod: reader, cleanup: cleanupReader } = await loadPipeline(
    path.join(PIPELINE, 'src', 'assets', 'readModelSource.ts'), 'readModelSource.mjs');
  const { mod: importer, cleanup } = await loadPipeline(
    path.join(PIPELINE, 'src', 'assets', 'modelImport.ts'), 'modelImport.mjs');
  // The products are project assets, so they get their `.meta` here rather than
  // waiting for a scan — which is also the only moment the source's own import
  // settings (a sampler's filter and wrap) are still in hand.
  const { mod: meta, cleanup: cleanupMeta } = await loadPipeline(
    path.join(PIPELINE, 'src', 'assets', 'assetMeta.ts'), 'assetMeta.mjs');
  let imported = 0;
  try {
    const sourceDir = path.dirname(opts.source);
    const dir = opts.out ?? sourceDir;
    const stem = reader.modelStem(opts.source);
    // A component's asset ref is project-relative, so the products can only be
    // named once the project root is known; without one they are bare names.
    const root = opts.project ?? findProjectRoot(sourceDir);
    const projectRef = (abs) => path.relative(root, abs).split(path.sep).join('/');
    let characters = false;
    let springBones = false;
    try {
      const importerMeta = JSON.parse(readFileSync(`${opts.source}.meta`, 'utf8')).importer;
      characters = importerMeta?.characterMaterials === 'auto';
      springBones = importerMeta?.springBones === 'auto';
    } catch { /* no meta: the schema's default */ }
    const refs = root
      ? { prefix: projectRef(dir) ? `${projectRef(dir)}/` : '',
          external: (uri) => projectRef(path.resolve(sourceDir, uri)), characters, springBones }
      : { characters, springBones };

    const { meshes, textures, nodes, animations, warnings } = await reader.readModelSource(
      new Uint8Array(readFileSync(opts.source)), stem,
      {
        filename: opts.source,
        externalBuffers: (uri) => {
          const abs = path.join(sourceDir, uri);
          return existsSync(abs) ? new Uint8Array(readFileSync(abs)) : null;
        },
        specularMap: specularMapFor(opts),
      },
    );
    if (lightmapUVFor(opts)) warnings.push(...importer.applyLightmapUV(meshes));
    warnings.push(...await importer.generateLods(meshes, lodSettingsFor(opts)));
    if (characters) importer.orderHairTriangles(meshes);
    for (const w of warnings) console.warn(`  ! ${w}`);
    if (!root && meshes.length > 0) {
      console.warn('  ! no project found above the source — refs are bare file names'
        + ' (pass --project <dir>)');
    }
    const report = (file, what) =>
      console.log(`${path.relative(process.cwd(), file)}: ${what}`);
    // Settings the source asked for, by product name; only ever the FIRST mint.
    const settings = new Map();
    const externalImages = new Set();
    for (const [file, { external, settings: asked }] of importer.importedImageSettings(meshes)) {
      settings.set(external ? path.resolve(sourceDir, file) : file, asked);
      if (external) externalImages.add(path.resolve(sourceDir, file));
    }
    const adopt = (file) => meta.adoptOrphan(file, settings.get(file) ?? settings.get(path.basename(file)));

    // An image the source names on disk is referenced where it lies, so it has to
    // be an asset too: an export resolves refs through the registry, and a file
    // with no sidecar is one it does not ship.
    for (const file of externalImages) {
      if (!existsSync(file)) {
        console.warn(`  ! ${path.relative(process.cwd(), file)} is referenced by the model and does not exist`);
        continue;
      }
      if ((await adopt(file)) === 'adopted') report(file, 'registered');
    }

    for (const mesh of meshes) {
      const outFile = path.join(dir, `${mesh.name}.esmesh`);
      writeFileSync(outFile, importer.encodeImportedMesh(mesh));
      await adopt(outFile);
      report(outFile, `${mesh.vertexCount} vertices, ${mesh.triangleCount} triangles`);
      for (const [i, lod] of (mesh.lods ?? []).entries()) {
        const lodFile = path.join(dir, `${importer.lodName(mesh, i + 1)}.esmesh`);
        writeFileSync(lodFile, importer.encodeGeneratedLod(lod));
        await adopt(lodFile);
        report(lodFile, `LOD ${i + 1}: ${lod.triangleCount} triangles`);
      }
    }
    for (const texture of textures) {
      const outFile = path.join(dir, texture.name);
      writeFileSync(outFile, texture.bytes);
      await adopt(outFile);
      report(outFile, `${texture.bytes.length} bytes`);
    }
    for (const material of importer.materialProducts(meshes, stem, refs)) {
      const outFile = path.join(dir, `${material.name}.esmaterial`);
      writeFileSync(outFile, `${JSON.stringify(material.data, null, 2)}\n`);
      await adopt(outFile);
      report(outFile, Object.keys(material.data.properties).join(', '));
    }
    let firstClip;
    for (const animation of animations) {
      const outFile = path.join(dir, `${animation.name}.estimeline`);
      writeFileSync(outFile, `${JSON.stringify(animation.document, null, 2)}\n`);
      await adopt(outFile);
      const tracks = animation.document.tracks.length;
      report(outFile, `${animation.document.duration}s, ${tracks} track${tracks === 1 ? '' : 's'}`);
      firstClip ??= `${refs.prefix ?? ''}${animation.name}.estimeline`;
    }
    if (meshes.length > 0) {
      const outFile = path.join(dir, `${stem}.esprefab`);
      const prefab = importer.assembleModelPrefab(
        stem, meshes, { refs, nodes, scale: opts.scale, timeline: firstClip });
      writeFileSync(outFile, `${JSON.stringify(prefab, null, 2)}\n`);
      await adopt(outFile);
      report(outFile, `${prefab.entities.length} entit${prefab.entities.length === 1 ? 'y' : 'ies'}`);

      // A glTF is authored in metres and a world unit is a design pixel, so a
      // real-world model arrives a few pixels across unless --scale says otherwise.
      const extent = Math.max(...meshes.flatMap(
        (m) => m.data.aabbMax.map((v, i) => v - m.data.aabbMin[i])));
      if (opts.scale === 1 && extent < 8) {
        console.warn(`  ! the model is ${extent.toFixed(2)} units across — models are authored`
          + ' in metres and a world unit is a design pixel; pass --scale if it should be bigger');
      }
    }
    imported = meshes.length;
  } finally {
    cleanupReader();
    cleanup();
    cleanupMeta();
  }
  process.exit(imported > 0 ? 0 : 1);
}

if (opts.command === 'bake-scene') {
  const { mod: baker, cleanup } = await loadPipeline(
    path.join(PIPELINE, 'src', 'assets', 'lightmapBake.ts'), 'lightmapBake.mjs');
  const { mod: meta, cleanup: cleanupMeta } = await loadPipeline(
    path.join(PIPELINE, 'src', 'assets', 'assetMeta.ts'), 'assetMeta.mjs');
  try {
    process.exit(await bakeScene(baker, meta, opts.source, opts.check));
  } finally {
    cleanup();
    cleanupMeta();
  }
}

if (opts.command === 'import-hdr') {
  const { mod: importer, cleanup } = await loadPipeline(
    path.join(PIPELINE, 'src', 'assets', 'environmentImport.ts'), 'environmentImport.mjs');
  const { mod: meta, cleanup: cleanupMeta } = await loadPipeline(
    path.join(PIPELINE, 'src', 'assets', 'assetMeta.ts'), 'assetMeta.mjs');
  try {
    const sourceDir = path.dirname(opts.source);
    const dir = opts.out ?? sourceDir;
    const stem = path.basename(opts.source).replace(/\.hdr$/i, '');
    const result = importer.importEnvironment(
      new Uint8Array(readFileSync(opts.source)), stem, { faceSize: opts.faceSize });
    for (const w of result.warnings) console.warn(`  ! ${w}`);
    const report = (file, what) =>
      console.log(`${path.relative(process.cwd(), file)}: ${what}`);

    const atlasFile = path.join(dir, result.atlasName);
    writeFileSync(atlasFile, result.atlasBytes);
    await meta.adoptOrphan(atlasFile, { ...importer.ENV_IMAGE_SETTINGS });
    report(atlasFile, `${result.document.mipCount} prefiltered mips`);
    if (result.sky) {
      const skyFile = path.join(dir, result.sky.name);
      writeFileSync(skyFile, result.sky.bytes);
      await meta.adoptOrphan(skyFile, { ...importer.ENV_IMAGE_SETTINGS });
      result.document.sky = result.sky.name;
      report(skyFile, 'the sky, at the panorama\'s resolution');
    }

    // Beside the document, the way an imported material names its images.
    result.document.specular = result.atlasName;
    const envFile = path.join(dir, `${stem}.esenv`);
    writeFileSync(envFile, `${JSON.stringify(result.document, null, 2)}\n`);
    await meta.adoptOrphan(envFile);
    report(envFile, `irradiance + ${result.document.faceSize}px reflection`);
  } finally {
    cleanup();
    cleanupMeta();
  }
  process.exit(0);
}

const project = projectSettings(opts.projectDir);
// A profile names its target, so `--profile` alone is enough; the parser that
// applies it refuses one that disagrees with an explicit --platform.
const platform = opts.platform ?? project.packaging?.profiles?.[opts.profile]?.platform ?? 'web';

const entryScene = opts.scene ?? project.defaultScene ?? (
  firstExisting([
    path.join(opts.projectDir, 'assets', 'scenes', 'main.esscene'),
    path.join(opts.projectDir, 'scenes', 'main.esscene'),
  ])?.slice(opts.projectDir.length + 1).replace(/\\/g, '/')
);
if (!entryScene) {
  console.error(`No entry scene found in ${opts.projectDir} (pass --scene <project-relative path>).`);
  process.exit(2);
}

const outDir = path.resolve(opts.out ?? path.join(opts.projectDir, `dist-${platform}`));

// The editor's package.json is the version of the whole product, and the runtime
// templates are stored per version.
const engineVersion = JSON.parse(readFileSync(path.join(REPO, 'package.json'), 'utf8')).version;
const nativePlatform = platform === 'android' || platform === 'ios';
const templateDir = nativePlatform
  ? (opts.template ? path.resolve(opts.template) : firstExisting([installedTemplateDir(engineVersion, platform)]) ?? null)
  : null;
// Desktop takes a template PER OS and assembles one app for each it finds; the
// assembler is pure Node, so one machine produces the set the editor would.
// --template names one and then it is the only one.
const desktopTemplates = platform !== 'desktop' ? [] : (opts.template
  ? [{ os: HOST_DESKTOP_OS, dir: path.resolve(opts.template) }]
  : ['windows', 'macos', 'linux'].flatMap((os) => {
    const dir = firstExisting([installedTemplateDir(engineVersion, os)]);
    return dir ? [{ os, dir }] : [];
  }));

const { mod: fmt, cleanup: cleanupFmt } = await loadPipeline(
  path.join(PIPELINE, 'src', 'project', 'index.ts'), 'projectFormat.mjs');
const { parseManifest, ignoredManifestKeys } = fmt;
// PARSED, not read by hand: the parser normalizes legacy platform ids and drops
// values that could not be judged against. A setting read straight off the JSON
// here is a second answer to what a project means.
const manifest = parseManifest(project);
for (const { key, under } of ignoredManifestKeys(project)) {
  console.warn(under
    ? `  ! project.esproject: "${key}" belongs under "${under}" — ignored where it is`
    : `  ! project.esproject: "${key}" is not a project setting — ignored`);
}

// A project that has Luban or Protobuf switched on is packaged from generated files that are up to date, or not at
// all. One that has them off is not touched, and nothing is looked for or downloaded.
if (project.tools?.luban?.enabled === true || project.tools?.protobuf?.enabled === true) {
  const { mod: toolsCli, cleanup: cleanupTools } = await loadPipeline(path.join(PIPELINE, 'src', 'tools', 'toolsCli.ts'), 'toolsCli.mjs');
  try {
    const stop = await toolsCli.prepareProjectTools(opts.projectDir);
    if (stop) {
      console.error(stop);
      process.exit(1);
    }
  } finally { cleanupTools(); }
}

const { mod: exporter, cleanup: cleanupExport } = await loadPipeline(
  path.join(PIPELINE, 'src', 'export', 'exportGame.ts'), 'exportGame.mjs');
const { mod: projectOpts, cleanup: cleanupProjectOpts } = await loadPipeline(
  path.join(PIPELINE, 'src', 'export', 'projectExportOptions.ts'), 'projectExportOptions.mjs');

// A platform the project defines in .esengine/platforms/, loaded the way the
// build dialog loads it, so a headless package is the one the dialog makes.
let projectPlatform = null;
if (!fmt.BUILTIN_PLATFORMS.includes(platform)) {
  const { mod: catalog, cleanup: cleanupCatalog } = await loadPipeline(
    path.join(PIPELINE, 'src', 'export', 'platformCatalog.ts'), 'platformCatalog.mjs');
  try {
    projectPlatform = await catalog.loadProjectPlatform(opts.projectDir, platform,
      { web: engineRuntimeDir('web'), minigame: engineRuntimeDir('wechat'), quickgame: engineRuntimeDir('quickgame') });
  } finally {
    cleanupCatalog();
  }
  if (!projectPlatform) {
    console.error(`Unknown platform "${platform}": not a built-in (${fmt.BUILTIN_PLATFORMS.join(', ')}),`
      + ` and ${opts.projectDir} defines none by that id in .esengine/platforms/.`);
    process.exit(2);
  }
}

let code = 1;
try {
  const result = await exporter.exportGame({
    ...await projectOpts.projectExportOptions(opts.projectDir, manifest, platform, opts.profile,
      { androidKeyPassphrase: process.env.ESTELLA_ANDROID_KEY_PASSPHRASE }),
    entryScene,
    ...(opts.scripts ? { scriptsEntry: opts.scripts } : {}),
    ...(opts.title ? { title: opts.title } : {}),
    hostsDir: path.join(PIPELINE, 'src', 'runtime'),
    packagesDir: path.join(REPO, 'plugins'),
    sdkDistDir: path.join(REPO, 'sdk', 'dist'),
    wasmDir: opts.wasm ? path.resolve(opts.wasm) : projectPlatform?.wasmDir ?? engineRuntimeDir(platform),
    miniGameProfile: projectPlatform?.profile,
    outDir,
    androidTemplate: platform === 'android' ? templateDir : null,
    desktopTemplates,
    ...(opts['steam-appid'] ? { desktopChannel: 'steam' } : {}),
    ...((opts['steam-appid'] || opts['steam-sdk']) ? {
      steam: {
        ...manifest.packaging?.platforms?.desktop?.steam,
        ...(opts['steam-appid'] ? { appId: Number(opts['steam-appid']) } : {}),
        ...(opts['steam-sdk'] ? { sdkPath: opts['steam-sdk'] } : {}),
      },
    } : {}),
    iosSources: platform === 'ios' && templateDir ? iosTemplateSources(templateDir) : null,
    ...(opts.output === 'project' ? { androidOutput: 'project' } : {}),
    ...(opts['emulator-abi'] ? { androidEmulatorAbi: true } : {}),
    ...(opts.minify ? { minify: true } : {}),
    ...(opts['debug-channel'] ? { debugChannel: { url: opts['debug-channel'] } } : {}),
    // `dev` is what the AOT step calls "do not compile" — the editor's preview
    // mode, reused here so there is one word for it (docs/REARCH_AOT.md §9).
    ...(opts['no-aot'] ? { aotMode: 'dev' } : {}),
  });
  const report = { ...result, outDir };
  console.log(JSON.stringify(report, null, 2));
  // stdout carries the cook's own progress too, so a caller that wants the result
  // mechanically cannot just redirect it.
  if (opts.json) writeFileSync(path.resolve(opts.json), `${JSON.stringify(report, null, 2)}\n`);
  code = result.ok ? 0 : 1;

  // The gate is opt-in. A package over its limit is still a package — whether that
  // blocks a release belongs to the caller. Said in prose on stderr as well as in
  // the exit code, because a CI log that only goes red tells nobody which limit.
  const over = (result.size?.verdicts ?? []).filter((v) => v.status === 'over');
  const mb = (n) => `${(n / 1024 / 1024).toFixed(2)}MB`;
  // What the engine weighs, when it is still in the package the limit counts.
  const engineBytes = (result.subPackageRoots ?? []).length > 0 ? 0
    : (result.size?.byKind ?? []).find((k) => k.kind === 'engine')?.bytes ?? 0;
  for (const v of over) {
    console.error(`size budget: ${v.budget.scope} is ${mb(v.measuredBytes)}, over the `
      + `${mb(v.budget.maxBytes)} limit (${v.budget.note}).`);
    // Naming the limit and stopping there leaves the reader to discover two
    // settings that exist: five of the corpus's projects, three over this limit,
    // and every one of them over it by less than the engine weighs.
    if (v.budget.scope === 'initial' && engineBytes > v.measuredBytes - v.budget.maxBytes) {
      console.error(`  the engine is ${mb(engineBytes)} of that, in the main package. `
        + '`packaging.engineSubpackage` moves it into a subpackage the host loads at '
        + 'startup; `packaging.compressWasm` ships it compressed.');
    }
  }
  if (over.length > 0 && opts['enforce-budget']) code = 1;
} finally {
  // Before the exit, not after: process.exit() in the try block would skip this
  // and leave the bundle dirs behind.
  cleanupExport();
  cleanupProjectOpts();
  cleanupFmt();
}
process.exit(code);