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.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  Asset cook (REARCH_ASSETS.md A4). Produce a shippable asset set: from
 *        the entry scene(s), walk the AssetDatabase dependency graph to the
 *        REACHABLE assets, copy those files into an output dir (project-relative
 *        paths preserved), and emit the runtime `assets.manifest.json` (the
 *        shape `AssetRegistry.loadManifest` consumes). Assets nothing references
 *        are culled from the build.
 *
 * Reuses the A2 scanner (scanAssetDatabase) for the index + dep graph, so the
 * editor's resolution, the Content Browser, and the ship cook all read one
 * source of truth. Pure Node (fs), no Electron imports → unit-testable; IPC
 * wiring is in main.ts.
 *
 * Deferred (per-target work): transcode/compress per platform (web/wechat/
 * native), texture atlasing, and the full web-build (html + runtime + scripts).
 * This is the reachability + manifest + staging core they all build on.
 */
import { ENV_IMAGE_FIELDS } from './environmentFormat';
import { writeFile, mkdir, readFile, open } from 'node:fs/promises';
import { statSync } from 'node:fs';
import { isInsideRoot } from '../fs/pathSandbox';
import path from 'node:path';
import { pathToFileURL } from 'node:url';
import { scanAssetDatabase, type AssetEntry } from './assetDb';
import { packAtlas, decodePngImage, encodePagePng, type AtlasInputImage } from './atlasPacker';
// Per-asset texture cook settings (compress opt-out / format / size cap), read
// from the `.meta` `importer` block — the same registry the inspector edits, so a
// texture's ship-time compression is authored per asset, not one global switch.
import { readTextureCookSettings } from '../project/importSettings';
import { audioLoadTypeOf } from './audioCook';
// The compression a build gives one texture, and the one reason it is that.
// The branch below IS this function — a cook that re-derived the choice would
// be a second answer to the question an inspector asks before a build runs.
import {
  decideTextureCook, cookIntentDefeated, explainTextureCook, textureAsksCompression,
  type TextureCookDecision,
} from './textureCookDecision';
// Single-source content hash (sdk/src/asset/contentHash.ts). Imported as source —
// no hand-mirrored copy — so the cook and the runtime agree by construction.
import { contentHashHex } from '../../../sdk/src/asset/contentHash';
import { getAssetTypeEntry } from '../../../sdk/src/assetTypes';
import { isBuiltinAssetRef, resolveRelativePath, resolveDocumentRef } from '../../../sdk/src/asset/documentRef';
// Single source for the folder→delivery-group model, shared with the editor Play
// realm (sdk/src/asset/assetGroups.ts) so cook and editor never disagree.
import { resolveAssetGroup, resolveAtlas, type AssetGroupsConfig } from '../../../sdk/src/asset/assetGroups';
import type { BundleMode } from '../../../sdk/src/asset/AddressableManifest';
import {
  readKtx2Layout, wantsMipChain, halveRgba, spliceMipChain,
} from './ktx2Mips';
import { cookCached } from './cookCache';
import { cookTexture, loadTextureEncoder, pngDimensions, fillClearTexels, fillsClearTexels, COMPRESSED_TARGETS, type BasisEncoderModule } from './textureCook';
import { meshTextureRoles } from './textureUsage';
import { makeStreamTail, type StreamTail } from './streamTail';
import { matchScriptAssetRefs, scanScriptAssetRefs } from './scriptAssetRefs';
import { readManifest } from '../project/readProject';
import { resolveScripts } from '../project/format';

const MANIFEST = 'assets.manifest.json';

/**
 * One cooked asset in the ship manifest. Extends the DB index entry with the
 * physical-identity fields it needs: `contentHash` (XXH64 of the staged bytes)
 * and `size`. The runtime AssetRegistry consumes the same v1.0 manifest and
 * simply ignores these extra fields (it maps uuid→path); the AddressableManifest
 * and content-addressed naming are what read them.
 */
/** How an addressable group is delivered — the typed mode {@link resolveAssetGroup}
 *  assigns and the AddressableManifest carries. Alias of the SDK's BundleMode:
 *  `local` (main package), `lazy` (subpackage), `remote` (CDN / hot-update). */
export type GroupDelivery = BundleMode;

export interface CookManifestEntry extends AssetEntry {
  /** XXH64 (16 hex) of the exact bytes staged — the asset's physical identity. */
  contentHash: string;
  /** Staged byte length. */
  size: number;
  /**
   * The asset's LOGICAL project-relative path — its addressable identity, kept
   * even when content-addressed staging renames the physical file (`path`) or
   * texture encoding swaps its extension. This is what path-style references
   * (a scene's "assets/x.esmaterial", a material's relative "x.esshader")
   * name at runtime; a host maps it to `path` to serve them from a cooked build.
   */
  sourcePath: string;
  /** GPU formats the staged KTX2 can transcode to, when the asset was compressed. */
  compressedFormats?: string[];
  /**
   * The small copy of a texture a mesh draws (streamTail.ts), staged beside it: what texture streaming fetches first, so the full
   * file is downloaded only once a view needs it. `width`/`height` are the copy's, `fullWidth`/`fullHeight` the file's.
   */
  streamTail?: { path: string; size: number; width: number; height: number; fullWidth: number; fullHeight: number };
  /**
   * What this build did to the texture's compression request, for images only.
   *
   * `compressedFormats` says a payload can transcode; it cannot say why one is
   * absent, and a request defeated by the image's own dimensions and one
   * defeated by the Build dialog are fixed in different places.
   */
  cook?: TextureCookDecision;
  /**
   * Addressable group this asset belongs to. `'main'` ships in the main package
   * (loaded eagerly); any other name is a lazy subpackage (folder convention:
   * `subpackages/<name>/…` → group `<name>`), loaded on demand. The runtime
   * AssetRegistry ignores this field; the AddressableManifest + WeChat subpackage
   * layout read it.
   */
  group: string;
  /** How `group` is delivered (folder convention). Absent ⇒ `local`. The
   *  AddressableManifest maps it to bundleMode; the WeChat subpackage layout and
   *  the CDN / hot-update path both read it. */
  groupMode?: GroupDelivery;
  /**
   * Present when this texture was packed into an atlas page: `path` then points
   * at the PAGE file (URL-level redirect for free) and this records where the
   * original image sits inside it. Frame pixels are in image space (y from the
   * page top); the runtime catalog derives uvOffset/uvScale from frame + page
   * size. Membership comes from {@link resolveAtlas} — a declared atlas or the
   * `<name>.atlas/` folder convention.
   */
  atlas?: {
    page: number;
    frame: { x: number; y: number; width: number; height: number };
    pageWidth: number;
    pageHeight: number;
  };
}

/**
 * Why an asset is in the build — the answer to "what is this doing in my package".
 *
 * `dependency` is the only one with a `via`: the asset that referenced it. Follow
 * those and the chain ends at whichever seed let it in, which is what a size
 * report shows beside a file nobody remembers adding.
 */
export type InclusionReason =
    /** An entry scene itself. */
    | 'entry'
    /** Referenced by another included asset (`via`). */
    | 'dependency'
    /** In a subpackage or remote group: delivered on demand, so nothing references it. */
    | 'group'
    /** In a group the project declared always-include. */
    | 'always-include'
    /** A locale table — loaded by code, so reachability would cull it. */
    | 'locale'
    /** A data asset (`.json`), named by the code that loads it. */
    | 'data'
    /** Named by a string literal in the project's scripts (`via` holds it). */
    | 'script';

/** How one asset got in: the reason, and for a dependency the asset that named it. */
export interface Inclusion {
  reason: InclusionReason;
  /** The referring asset's logical path, for `dependency`. */
  via?: string;
}

/** `assets.manifest.json` as the cook writes it — what the package carries. */
export interface CookManifest {
  version: string;
  entries: CookManifestEntry[];
}

/**
 * Load the project's asset-delivery config (`.esengine/asset-groups.json`) — the
 * single authored source for which folders ship as remote (CDN) / subpackage
 * groups. Absent or unparseable → null, and {@link resolveAssetGroup} falls back
 * to the legacy `remote/`/`subpackages/` folder-name convention.
 */
export async function loadAssetGroups(root: string): Promise<AssetGroupsConfig | null> {
  try {
    const raw = await readFile(path.join(root, '.esengine', 'asset-groups.json'), 'utf8');
    return JSON.parse(raw) as AssetGroupsConfig;
  } catch {
    return null;
  }
}

/**
 * The directory a non-local group's files live under — `subpackages/<name>` for a
 * lazy group, `remote/<name>` for a CDN one; null for the main package. A vendor
 * MOUNTS this root (a WeChat 分包 names it in game.json), so delivery fixes it
 * rather than the layout: a root the package lacks is refused with "root 不存在".
 */
export function groupRoot(name: string, delivery: GroupDelivery): string | null {
  if (delivery === 'lazy') return `subpackages/${name}`;
  if (delivery === 'remote') return `remote/${name}`;
  return null;
}

/** Content-addressed base dir for a group's delivery: main → `assets`,
 *  lazy → `subpackages/<name>/assets`, remote → `remote/<name>/assets`. */
function caBaseFor(name: string, delivery: GroupDelivery): string {
  const root = groupRoot(name, delivery);
  return root ? `${root}/assets` : 'assets';
}

/** `rel` moved under its group's root when names are kept. A path already there —
 *  the `subpackages/<name>/` folder convention — is its own root and stays put. */
function underGroupRoot(rel: string, name: string, delivery: GroupDelivery): string {
  const root = groupRoot(name, delivery);
  if (!root || rel === root || rel.startsWith(`${root}/`)) return rel;
  return `${root}/${rel}`;
}


/** What cooking one asset reports, held apart so concurrent cooks merge in order. */
interface CookSink {
  warnings: string[];
  failed: string[];
  defeatedByFormat: string[];
  manifestEntries: CookManifestEntry[];
}

/** A PNG's width and height from its IHDR, reading only the header; null for anything else. */
async function pngHeaderSize(file: string): Promise<{ width: number; height: number } | null> {
  let handle;
  try {
    handle = await open(file, 'r');
    const header = new Uint8Array(24);
    await handle.read(header, 0, 24, 0);
    return header[1] === 0x50 && header[2] === 0x4e ? pngDimensions(header) : null;
  } catch {
    return null;
  } finally {
    await handle?.close();
  }
}

/** `fn` over `items` with at most `limit` running, results in the items' order. */
async function mapInOrder<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
  const results = new Array<R>(items.length);
  let next = 0;
  const lane = async (): Promise<void> => {
    while (next < items.length) {
      const i = next++;
      results[i] = await fn(items[i]!);
    }
  };
  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, lane));
  return results;
}

const KTX2_SCHEME_ZSTD = 2;

/** Replace a path's extension (e.g. .png → .ktx2); appends if it had none. */
function swapExt(p: string, ext: string): string {
  const cur = path.extname(p);
  return (cur ? p.slice(0, p.length - cur.length) : p) + ext;
}

/**
 * Rewrite a material's RELATIVE refs (shader / instanceOf / texture properties)
 * to the referenced asset's logical project path. Materials resolve relative
 * refs against their own directory at runtime — a structure content-addressed
 * staging destroys — so the staged copy carries directory-free logical refs and
 * the runtime's logical→staged maps take it from there. Logical paths outside
 * the runtime's passthrough prefixes ship as "/<logical>" (project-absolute).
 * `@uuid:`/URL refs and already-logical refs pass through unchanged.
 */
function rewriteMaterialRefs(
  bytes: Uint8Array,
  matPath: string,
  byPath: Map<string, AssetEntry>,
): Uint8Array {
  const json = JSON.parse(Buffer.from(bytes).toString('utf8')) as Record<string, unknown>;
  const rewrite = (ref: unknown): unknown => logicalRef(ref, matPath, byPath);
  if (typeof json.shader === 'string') json.shader = rewrite(json.shader);
  if (typeof json.instanceOf === 'string') json.instanceOf = rewrite(json.instanceOf);
  if (json.properties && typeof json.properties === 'object') {
    const props = json.properties as Record<string, unknown>;
    for (const key of Object.keys(props)) props[key] = rewrite(props[key]);
  }
  return new TextEncoder().encode(JSON.stringify(json, null, 2) + '\n');
}

/**
 * One document-relative ref as the logical project path a staged copy must carry:
 * staging is content-addressed, so the directory a relative ref resolves against
 * does not survive it. `@uuid:` / `builtin:` / URLs / already-logical refs and
 * anything naming no asset pass through.
 */
function logicalRef(ref: unknown, docPath: string, byPath: Map<string, AssetEntry>): unknown {
  if (typeof ref !== 'string' || ref.startsWith('@uuid:') || isBuiltinAssetRef(ref) || ref.includes('://')) return ref;
  const norm = ref.replace(/^\.\//, '').replace(/^\//, '');
  if (byPath.has(norm)) return ref;
  const proj = resolveRelativePath(docPath, ref);  // collapses ./ and ../
  if (!byPath.has(proj)) return ref;
  // Passthrough-safe spelling: bare when the runtime treats it as absolute,
  // "/"-rooted otherwise (both registered by the cooked host's maps).
  return proj.startsWith('assets/') ? proj : `/${proj}`;
}

/**
 * A bitmap font names its page image as a sibling, in TEXT rather than JSON — the
 * same staging problem, and the same fix: the staged copy names the project path.
 */
function rewriteFontRefs(
  bytes: Uint8Array,
  fntPath: string,
  byPath: Map<string, AssetEntry>,
): Uint8Array {
  const text = Buffer.from(bytes).toString('utf8');
  return new TextEncoder().encode(text.replace(
    /(\bpage\b[^\n]*\bfile=")([^"]+)(")/g,
    (whole, head: string, ref: string, tail: string) => {
      const logical = logicalRef(ref, fntPath, byPath);
      return typeof logical === 'string' ? `${head}${logical}${tail}` : whole;
    },
  ));
}

/**
 * An animator controller names the clips its motions play as sibling files, which
 * staging moves out from under it. The controller then loads and every state
 * plays nothing, which reads as a broken graph rather than a missing asset.
 */
function rewriteAnimatorRefs(
  bytes: Uint8Array,
  docPath: string,
  byPath: Map<string, AssetEntry>,
): Uint8Array {
  const json = JSON.parse(Buffer.from(bytes).toString('utf8')) as {
    states?: { motion?: unknown; stateMachine?: { states?: unknown[] } }[];
    layers?: { states?: unknown[] }[];
  };
  // Only a motion whose clip is an ASSET: a sprite clip and a spine animation
  // are names their own runtime holds, and rewriting those would break them.
  const ASSET_KINDS = new Set(['timeline']);
  const walk = (motion: unknown): void => {
    if (!motion || typeof motion !== 'object') return;
    const m = motion as {
      kind?: string; clip?: string;
      thresholds?: { motion?: unknown }[]; points?: { motion?: unknown }[];
    };
    if (m.kind === 'blend1d' || m.kind === 'blend2d') {
      for (const child of m.thresholds ?? m.points ?? []) walk(child.motion);
      return;
    }
    if (m.kind && ASSET_KINDS.has(m.kind) && typeof m.clip === 'string') {
      m.clip = logicalRef(m.clip, docPath, byPath) as string;
    }
  };
  const states = (list: unknown[] | undefined): void => {
    for (const state of list ?? []) {
      const st = state as { motion?: unknown; stateMachine?: { states?: unknown[] } };
      walk(st.motion);
      states(st.stateMachine?.states);
    }
  };
  // Every machine, not just the base one: a clip only a layer plays ships with
  // its authored ref intact, which resolves to nothing once staging has moved
  // the file — the layer is then silent in the package and nowhere else.
  states(json.states);
  for (const layer of json.layers ?? []) states(layer.states);
  return new TextEncoder().encode(JSON.stringify(json, null, 2) + '\n');
}

/**
 * A baked environment names its images as SIBLING files, which staging moves out
 * from under it — the runtime then asks for `assets/sky_env.png` and gets a 404,
 * and the frame silently loses every reflection, or the sky, the game was made with.
 */
function rewriteEnvironmentRefs(
  bytes: Uint8Array,
  envPath: string,
  byPath: Map<string, AssetEntry>,
): Uint8Array {
  const json = JSON.parse(Buffer.from(bytes).toString('utf8')) as Record<string, unknown>;
  for (const field of ENV_IMAGE_FIELDS) {
    if (typeof json[field] === 'string') json[field] = logicalRef(json[field], envPath, byPath);
  }
  return new TextEncoder().encode(JSON.stringify(json, null, 2) + '\n');
}

/**
 * Rewrite a Tiled map's tileset `image` (inline) and `source` (external `.tsj`) refs
 * from document-relative (`"../textures/tileset.png"`) to the referenced asset's logical
 * project path — the same shape rewriteMaterialRefs produces. The playable loads a map by
 * its `@uuid` (which carries no directory), so the runtime's `resolveRelativePath(@uuid,
 * "../textures/x.png")` yields a WRONG root-relative path that matches no embedded asset;
 * a directory-free logical ref (`assets/textures/x.png`) resolves to the same inlined
 * asset in every realm. `@uuid:`/URL/already-logical refs pass through unchanged.
 */
function rewriteTilemapRefs(
  bytes: Uint8Array,
  tmjPath: string,
  byPath: Map<string, AssetEntry>,
): Uint8Array {
  const json = JSON.parse(Buffer.from(bytes).toString('utf8')) as Record<string, unknown>;
  const rewrite = (ref: unknown): unknown => logicalRef(ref, tmjPath, byPath);
  const tilesets = Array.isArray(json.tilesets) ? (json.tilesets as Record<string, unknown>[]) : [];
  for (const ts of tilesets) {
    if (typeof ts.image === 'string') ts.image = rewrite(ts.image);    // inline tileset image
    if (typeof ts.source === 'string') ts.source = rewrite(ts.source); // external .tsj tileset
    if (Array.isArray(ts.tiles)) {
      // Image-collection tileset: one image per tile.
      for (const t of ts.tiles as Record<string, unknown>[]) {
        if (typeof t?.image === 'string') t.image = rewrite(t.image);
      }
    }
  }
  return new TextEncoder().encode(JSON.stringify(json, null, 2) + '\n');
}

/**
 * Asset paths a staged document names that the package does not carry. Three
 * defects of this shape were each a different type, and each was found by a game
 * drawing the wrong thing — a document's own references being the one place
 * nothing checked. Only KNOWN asset extensions count, so ordinary strings do not.
 */
function unresolvedDocumentRefs(
  docPath: string,
  text: string,
  shipped: ReadonlySet<string>,
): string[] {
  const missing = new Set<string>();
  for (const [, ref] of text.matchAll(/"([^"\n]{3,200})"/g)) {
    // By EXTENSION, not by looksLikeAssetPath: that one wants a directory in the
    // string, and a document naming a sibling — the exact shape of every defect
    // this is here for — has none.
    if (ref.includes('://') || !/\.[A-Za-z0-9]+$/.test(ref) || !getAssetTypeEntry(ref)) continue;
    // Resolved the way a loader will: refs travel in LOGICAL space, so a sibling
    // is a sibling of the document's project path, not of where staging put it.
    if (!shipped.has(resolveDocumentRef(docPath, ref))) missing.add(ref);
  }
  return [...missing];
}

export interface CookResult {
  ok: boolean;
  /** Absolute output dir the assets + manifest were staged into. */
  outDir: string;
  /** Absolute manifest path, or null if not written. */
  manifestPath: string | null;
  /** uuids included (reachable from the entry scenes). */
  included: string[];
  /** The same assets as `included`, by project-relative source path — what a
   *  caller needs to read the content it just shipped (e.g. to scan the scenes
   *  for subsystems the target cannot render). */
  includedPaths: string[];
  /** The shipped audio clips whose import settings choose how they load (not `auto`), by logical path. */
  audioLoadTypes: Record<string, 'streaming' | 'decompress'>;
  /**
   * The shipped clips that were re-encoded, by logical path: how long each really is and the silence the encoding
   * put before it, in seconds. The runtime plays a clip from past that silence and loops it at its real end;
   * without this a loop that was seamless as a WAV has a gap every time round once it is packaged.
   */
  audioEncoded: Record<string, { seconds: number; lead: number }>;
  /** uuids present in the project but unreachable — culled from the build. */
  unused: string[];
  /**
   * Why each included asset is in the build, by its logical (project-relative)
   * path. The size report walks `via` back to a seed to say what pulled a file in.
   */
  inclusion: Record<string, Inclusion>;
  warnings: string[];
  /**
   * Assets the game REACHES that could not be produced, as `<path>: <why>`. Each
   * one is a hole in the package: the scene still references it and the runtime
   * fetches a path nothing staged. Kept apart from `warnings` because it is the
   * one cook outcome a caller must not ship.
   */
  failed: string[];
}

/**
 * The function that gives a `.esshader` its derived WGSL twin, or null when the converters are not here (anywhere but a checkout of the engine).
 * Loaded by a path it holds in a variable: the bundlers must leave the module and its wasm alone, and the cook runs from the same depth in
 * the package whether it is bundled or not, which is what lets one relative specifier name it.
 */
let twinDeriver: Promise<((source: string) => Promise<string>) | null> | undefined;
function shaderTwinDeriver(): Promise<((source: string) => Promise<string>) | null> {
  twinDeriver ??= (async () => {
    try {
      // A host that ships the converters (the packaged editor) says where they are;
      // a checkout of the engine finds them beside this file.
      const root = process.env.ESTELLA_SHADER_TWINS_ROOT;
      const specifier = root
        ? pathToFileURL(path.join(root, 'tools', 'lib', 'derivedTwin.mjs')).href
        : '../../../tools/lib/derivedTwin.mjs';
      return ((await import(/* @vite-ignore */ specifier)) as { withDerivedTwin: (source: string) => Promise<string> }).withDerivedTwin;
    } catch {
      return null;
    }
  })();
  return twinDeriver;
}

/**
 * Cook assets reachable from `entryScenes` (project-relative scene paths) into
 * `outDir` (project-relative or absolute). Returns what was included vs culled.
 */
/** The folder the project's startup script lives in — every export target cooks
 *  from here, so each one ships what the scripts name without being told. */
async function projectScriptDirs(root: string): Promise<string[]> {
  try {
    const main = resolveScripts(await readManifest(root)).main;
    return main ? [path.posix.dirname(main.split(path.sep).join('/').split('\\').join('/'))] : [];
  } catch {
    return [];
  }
}

export async function cookAssets(
  root: string,
  opts: {
    entryScenes: string[]; outDir: string;
    contentAddressed?: boolean; compressTextures?: boolean; atlasTextures?: boolean;
    /** Honor PNG Max Size without enabling GPU compression or loading Basis. */
    resizeTextures?: boolean;
    compressAudio?: boolean; transcodeVideo?: boolean;
    /** Target platform — selects each texture's per-platform Import Settings
     *  override (Default when absent). No effect on audio/video/atlas. */
    platform?: string;
    /**
     * What the package would pay to READ a KTX2 — the transcoder's bytes. A
     * project whose whole art weighs less than that cannot come out ahead by
     * compressing any of it, and is answered before anything is encoded.
     */
    textureDecoderBytes?: number;
    /** Stage a small copy of each texture a mesh draws as its surface (streamTail.ts), for texture streaming to fetch first.
     *  Worth it where files are fetched as they are needed (the web); a package downloaded whole only grows. */
    streamTails?: boolean;
    /** Project-relative folders holding the game's scripts: an asset a literal there
     *  names ships even when no scene references it (scriptAssetRefs.ts). Absent:
     *  the folder of the project's startup script; `[]` scans nothing. */
    scriptDirs?: string[];
  },
): Promise<CookResult> {
  const contentAddressed = opts.contentAddressed ?? false;
  const atlasTextures = opts.atlasTextures ?? false;
  const compressAudio = opts.compressAudio ?? false;
  const transcodeVideo = opts.transcodeVideo ?? false;
  const platform = opts.platform;
  const streamTails = opts.streamTails ?? false;
  const { index } = await scanAssetDatabase(root, { write: false, adopt: false });
  const warnings: string[] = [];
  const failed: string[] = [];
  // Second gate: nothing reaches it while the scanner drops these upstream, but
  // this is where bytes become an artifact someone else runs. Warns rather than
  // dropping silently — an asset missing from a build has to say why.
  const shippable = index.entries.filter((e) => {
    if (isInsideRoot(root, path.join(root, e.path))) return true;
    warnings.push(`${e.path}: resolves outside the project through a link — not shipped`);
    return false;
  });
  const byUuid = new Map(shippable.map((e) => [e.uuid, e]));
  const byPath = new Map(shippable.map((e) => [e.path, e]));
  // Asset-delivery config: which folders are remote (CDN) / subpackage groups.
  const groupsConfig = await loadAssetGroups(root);

  // Seed reachability from the entry scenes (path → uuid)…
  const reachable = new Set<string>();
  const queue: string[] = [];
  // Kept as it is discovered, not derived afterwards: the FIRST way in is the
  // shortest one, and re-deriving it later would answer a different question.
  const inclusionByUuid = new Map<string, Inclusion>();
  const seed = (uuid: string, how: Inclusion): void => {
    if (!reachable.has(uuid)) {
      reachable.add(uuid);
      inclusionByUuid.set(uuid, how);
      queue.push(uuid);
    }
  };
  for (const scenePath of opts.entryScenes) {
    const entry = byPath.get(scenePath);
    if (!entry) {
      warnings.push(`entry scene not in asset index: ${scenePath}`);
      continue;
    }
    seed(entry.uuid, { reason: 'entry' });
  }
  // Force-include lazy-subpackage assets: they're loaded on demand, so the entry
  // scene never references them — but they (and their deps) must still ship. A
  // shared dep that lives outside subpackages/ resolves to group 'main' below, so
  // it lands in the always-present main package, not duplicated per subpackage.
  for (const e of shippable) {
    const group = resolveAssetGroup(e.path, groupsConfig);
    // …and every non-local (subpackage / remote-CDN) asset: never scene-
    // referenced, but must be cooked + staged for its group's delivery.
    if (group.delivery !== 'local') seed(e.uuid, { reason: 'group' });
    // …and every asset in a group the project declared always-include: what a
    // scene cannot reference because only code names it (a path built at run
    // time, a texture in rich-text markup). Reachability would cull it, and the
    // first anyone would hear of that is a missing image on a device.
    else if (group.alwaysInclude) seed(e.uuid, { reason: 'always-include' });
  }
  // Force-include locale string tables: translations load by code / plugin
  // option (a scene never references them — Text carries KEYS, not paths), so
  // reachability would always cull them, and a build missing its languages is
  // strictly wrong. Text is tiny; dead tables cost nothing.
  for (const e of shippable) {
    if (e.path.toLowerCase().endsWith('.eslocale')) seed(e.uuid, { reason: 'locale' });
  }
  // …and data assets, for the same reason one step further: a `.json` table is
  // named by the code that loads it, so nothing in the scene graph points at it.
  // Culling it produces the worst failure this pipeline can produce — it works in
  // the editor, which serves the whole project, and 404s only in the build.
  for (const e of shippable) {
    if (e.type === 'json') seed(e.uuid, { reason: 'data' });
  }
  // …and what the scripts name: a path only code holds never reaches a scene,
  // and culling it is a build that works in the editor and 404s on a device.
  const scriptDirs = opts.scriptDirs ?? await projectScriptDirs(root);
  if (scriptDirs.length > 0) {
    const named = matchScriptAssetRefs(await scanScriptAssetRefs(root, scriptDirs), shippable);
    const byFolder = new Map<string, number>();
    for (const { uuid, via } of named) {
      if (reachable.has(uuid)) continue;
      seed(uuid, { reason: 'script', via });
      if (via.endsWith('/')) byFolder.set(via, (byFolder.get(via) ?? 0) + 1);
    }
    for (const [folder, n] of byFolder) {
      warnings.push(`scripts build paths under "${folder}" at run time, so all ${n} asset(s) there ship; `
        + 'name the files whole, or list them as alwaysInclude, to ship only what is used');
    }
  }
  // …then take the transitive closure over the dependency graph.
  while (queue.length > 0) {
    const uuid = queue.shift()!;
    const from = byUuid.get(uuid)?.path;
    for (const dep of index.deps[uuid] ?? []) seed(dep, { reason: 'dependency', via: from });
  }

  const absOut = path.isAbsolute(opts.outDir) ? opts.outDir : path.join(root, opts.outDir);
  await mkdir(absOut, { recursive: true });

  // Stage each reachable asset's file + build the ship manifest. We read the
  // bytes (rather than copyFile) so we can content-hash exactly what ships — the
  // asset's physical identity. Once textures are encoded this naturally hashes the
  // ENCODED artifact (e.g. the .ktx2), since it hashes whatever bytes we stage.
  // Load the KTX2 encoder lazily (only when compressing — it pulls a ~MB wasm) and
  // by dynamic import, so the Electron-main bundle keeps it external rather than
  // inlining a module that resolves its wasm via import.meta.url.
  // Atlas pages compress as UASTC (they aggregate many textures — no single
  // per-asset setting applies); standalone textures use `textureEnc` directly so
  // each honors its own format / srgb / opt-out from the importer block.

  // Compressing cannot save more than the art weighs, and one KTX2 obliges the
  // package to carry the transcoder — so art lighter than it is answered before
  // the encoder loads. A project that authored a KTX2 pays either way.
  const textureSources = [...reachable]
    .map((uuid) => byUuid.get(uuid))
    .filter((e): e is AssetEntry => e !== undefined && e.type === 'texture');
  const authoredKtx2 = textureSources.some((e) => e.path.toLowerCase().endsWith('.ktx2'));
  const artBytes = textureSources.reduce((n, e) => {
    try { return n + statSync(path.join(root, e.path)).size; } catch { return n; }
  }, 0);
  const decoderBytes = opts.textureDecoderBytes;
  const decoderCanPay = decoderBytes === undefined || authoredKtx2 || artBytes > decoderBytes;
  const compressTextures = (opts.compressTextures ?? false) && decoderCanPay;
  if ((opts.compressTextures ?? false) && !decoderCanPay) {
    const kb = (n: number) => `${Math.round(n / 1024)}KB`;
    warnings.push(`textures ship raw: compressing every one of them could save at most `
      + `${kb(artBytes)}, and a package that holds a KTX2 carries a ${kb(decoderBytes!)} transcoder`);
  }

  let encodePng: ((png: Uint8Array) => Promise<Uint8Array>) | null = null;
  let textureEnc: BasisEncoderModule | null = null;
  let encoderId = '';
  if (compressTextures) {
    ({ module: textureEnc, id: encoderId } = await loadTextureEncoder());
    encodePng = (png) => textureEnc!.encodePngToKtx2(png, { mode: 'uastc' });
  }
  // WAV → MP3 (LAME wasm) rides the same lazy pattern; per-asset importer
  // settings can opt a clip out (seamless loops) or pick a bitrate.
  const encodedByUuid = new Map<string, { seconds: number; lead: number }>();
  let audioEnc: typeof import('./audioCook') | null = null;
  if (compressAudio) {
    audioEnc = await import('./audioCook');
  }
  // Video → MPEG-1 `.esv` + `.m4a` audio sibling, for targets whose only video
  // path is the wasm decoder (WeChat). ffmpeg loads lazily the same way.
  let videoEnc: typeof import('./videoCook') | null = null;
  if (transcodeVideo) {
    videoEnc = await import('./videoCook');
  }

  const manifestEntries: CookManifestEntry[] = [];
  const staged = new Set<string>();  // staged output paths, for content-addressed dedup
  // Images that asked to be compressed and are not PNG. Named together: this is
  // one fact about the project's source art, and one line per JPEG would bury
  // the per-asset findings that each need their own fix.
  const defeatedByFormat: string[] = [];
  // What Auto compression resolves by: whether a mesh anywhere in the project draws it.
  const roles = await meshTextureRoles(root, shippable);
  const drawnIn3D = new Set(roles.keys());
  const pageCompressedBy = (frame: AssetEntry): boolean =>
    textureAsksCompression(readTextureCookSettings(frame.importer, platform).compress, drawnIn3D.has(frame.uuid));

  // ---- Auto-atlas (`<name>.atlas/` folder convention) -----------------------
  // Pack the reachable PNGs of each atlas directory into pages BEFORE the
  // per-asset staging loop; each packed frame's manifest entry then points its
  // `path` at the page file (frame → page redirect happens at the URL level,
  // through the same buildPath machinery as every other rename). Pages are
  // plain textures to the rest of the cook: KTX2 compression and content-
  // addressed naming apply to them exactly as they would to a lone PNG.
  const atlasPlan = new Map<string, NonNullable<CookManifestEntry['atlas']> & {
    pageOutRel: string; pageHash: string; pageSize: number; compressedFormats?: string[];
  }>();
  if (atlasTextures) {
    const groups = new Map<string, AssetEntry[]>();
    for (const uuid of reachable) {
      const entry = byUuid.get(uuid);
      if (!entry || entry.type === 'scene') continue;
      if (path.extname(entry.path).toLowerCase() !== '.png') continue;
      const dir = resolveAtlas(entry.path, groupsConfig)?.name ?? null;
      if (!dir) continue;
      let list = groups.get(dir);
      if (!list) groups.set(dir, (list = []));
      list.push(entry);
    }
    for (const [dir, entries] of [...groups.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
      const images: AtlasInputImage[] = [];
      for (const entry of [...entries].sort((a, b) => a.path.localeCompare(b.path))) {
        try {
          images.push(decodePngImage(entry.path, await readFile(path.join(root, entry.path))));
        } catch (err) {
          warnings.push(`${entry.path}: atlas decode failed, staging standalone — ${err instanceof Error ? err.message : String(err)}`);
        }
      }
      if (images.length === 0) continue;
      const pages = packAtlas(images);
      for (let n = 0; n < pages.length; n++) {
        // A page is one image: its frames' clear texels and the clear gaps between
        // them are filled as a lone texture's are, or the frame edge samples the
        // gap's black. Only where every frame on it allows (see fillsClearTexels).
        const onPage = pages[n].placements.map((p) => byPath.get(p.key)).filter((e): e is AssetEntry => !!e);
        if (onPage.length > 0 && onPage.every((e) => fillsClearTexels(e.importer, platform))) {
          const filled = fillClearTexels(pages[n]);
          if (filled) pages[n] = { ...pages[n], rgba: filled };
        }
        const pagePng: Uint8Array = encodePagePng(pages[n]);
        let pageBytes: Uint8Array = pagePng;
        let pageExt = '.png';
        let compressedFormats: string[] | undefined;
        // One payload for every frame on the page, so it is compressed when a
        // frame on it asks to be; a page of sprites on Auto ships as a PNG.
        const pageFrames = pages[n].placements.map((p) => byPath.get(p.key)).filter((e): e is AssetEntry => !!e);
        if (encodePng && pageFrames.some((e) => pageCompressedBy(e))) {
          pageBytes = await encodePng(pagePng);
          pageExt = '.ktx2';
          compressedFormats = COMPRESSED_TARGETS;
        }
        const pageHash = contentHashHex(pageBytes);
        const { name: group, delivery } = resolveAssetGroup(`${dir}/`, groupsConfig);
        const caBase = caBaseFor(group, delivery);
        const pageOutRel = contentAddressed
          ? `${caBase}/${pageHash}${pageExt}`
          : underGroupRoot(`${dir}.page${n}${pageExt}`, group, delivery);
        const dst = path.join(absOut, pageOutRel);
        if (!staged.has(pageOutRel)) {
          await mkdir(path.dirname(dst), { recursive: true });
          await writeFile(dst, pageBytes);
          staged.add(pageOutRel);
        }
        for (const placement of pages[n].placements) {
          atlasPlan.set(placement.key, {
            page: n,
            frame: { x: placement.x, y: placement.y, width: placement.width, height: placement.height },
            pageWidth: pages[n].width,
            pageHeight: pages[n].height,
            pageOutRel, pageHash, pageSize: pageBytes.byteLength, compressedFormats,
          });
        }
      }
    }
  }

  // Each asset cooks on its own, and the encoder runs ENCODER_PARALLELISM images
  // at once, so that many are kept in flight. What each reports is merged back in
  // `reachable` order, which keeps the manifest and the warnings a serial cook's.
  const cookOne = async (uuid: string, { warnings, failed, defeatedByFormat,
                                         manifestEntries }: CookSink): Promise<void> => {
    const entry = byUuid.get(uuid);
    if (!entry) return;
    // Atlas-packed frame: the page is already staged; this entry just records
    // where the frame lives (page path + rect). Its physical identity IS the
    // page's (hash/size of the bytes actually served for this ref).
    const framePlan = atlasPlan.get(entry.path);
    if (framePlan) {
      const fg = resolveAssetGroup(entry.path, groupsConfig);
      // A frame's own Compress rows never reach an encoder: the page is what
      // ships. Saying so is the point — the row still reads as if it applied.
      const frameTex = readTextureCookSettings(entry.importer, platform);
      const frameCook = decideTextureCook({
        compressTextures, atlasTextures, inAtlas: true, raster: true,
        atlasPageCompressed: framePlan.compressedFormats !== undefined,
        compress: frameTex.compress, drawnIn3D: drawnIn3D.has(entry.uuid), format: frameTex.format, size: null,
      });
      if (cookIntentDefeated(frameCook)) {
        warnings.push(`${entry.path}: ${explainTextureCook(frameCook)}`);
      }
      manifestEntries.push({
        uuid: entry.uuid,
        path: framePlan.pageOutRel,
        sourcePath: entry.path,
        type: entry.type,
        importer: entry.importer,
        contentHash: framePlan.pageHash,
        size: framePlan.pageSize,
        group: fg.name,
        groupMode: fg.delivery,
        ...(framePlan.compressedFormats ? { compressedFormats: framePlan.compressedFormats } : {}),
        cook: frameCook,
        atlas: {
          page: framePlan.page,
          frame: framePlan.frame,
          pageWidth: framePlan.pageWidth,
          pageHeight: framePlan.pageHeight,
        },
      });
      return;
    }
    try {
      // Videos headed for transcode skip the eager read: ffmpeg streams the
      // file itself, so slurping a (potentially huge) source here would double
      // the I/O just to throw the bytes away.
      const willTranscodeVideo =
        videoEnc != null && entry.type === 'video' && path.extname(entry.path).toLowerCase() !== '.esv';
      let data: Uint8Array = willTranscodeVideo
        ? new Uint8Array(0)
        : await readFile(path.join(root, entry.path));
      let ext = path.extname(entry.path);
      let tail: StreamTail | null = null;
      let compressedFormats: string[] | undefined;
      let cook: TextureCookDecision | undefined;
      // An authored single-level UASTC KTX2 gets the chain a compressed texture
      // cannot generate on the device, under its own untouched level 0.
      const layout = textureEnc && entry.type === 'texture' && ext.toLowerCase() === '.ktx2' ? readKtx2Layout(data) : null;
      if (textureEnc && wantsMipChain(layout)) {
        const enc = textureEnc;
        const source = data;
        try {
          data = (await cookCached(root, [source, 'ktx2-mip-chain:1', encoderId], async () => {
            const decoded = await enc.transcodeKtx2ToRgba(source);
            const half = halveRgba(decoded.pixels, decoded.width, decoded.height, layout.srgb);
            const below = await enc.encodeToKtx2(
              { type: enc.ImageType.RGBA, data: half.rgba, width: half.width, height: half.height },
              {
                mode: 'uastc', srgb: layout.srgb, mipmaps: true, yFlip: false, uastcLevel: 0,
                supercompress: layout.scheme === KTX2_SCHEME_ZSTD,
              });
            return spliceMipChain(source, below);
          })).bytes;
        } catch (err) {
          warnings.push(`${entry.path}: ships its single level without mips — ${err instanceof Error ? err.message : String(err)}`);
        }
      }
      // Every image takes the decision, not only the ones an encoder accepts: a
      // JPEG whose Compress row reads ON leaves no other trace. Hash + name below
      // reflect the ENCODED bytes, so this composes with content-addressing.
      if (entry.type !== 'scene' && getAssetTypeEntry(entry.path)?.contentType === 'image') {
        const t = await cookTexture({
          root, path: entry.path, data, ext, importer: entry.importer, platform,
          encoder: textureEnc ? { module: textureEnc, id: encoderId } : null,
          compressTextures, atlasTextures, drawnIn3D: drawnIn3D.has(entry.uuid),
          resizeTextures: opts.resizeTextures,
        });
        data = t.data; ext = t.ext; cook = t.cook; compressedFormats = t.compressedFormats;
        warnings.push(...t.warnings);
        if (t.defeatedByFormat) defeatedByFormat.push(entry.path);
        // After the payload is decided, from its bytes: the copy is the picture that ships, in the format it ships in.
        if (streamTails && roles.get(entry.uuid)?.has('surface')) {
          try {
            tail = await makeStreamTail(data, ext, readTextureCookSettings(entry.importer, platform).srgb, textureEnc);
          } catch (err) {
            warnings.push(`${entry.path}: no small copy for streaming — ${err instanceof Error ? err.message : String(err)}`);
          }
        }
      }
      // WAV sources re-encode to MP3 (universal decode); other audio formats are
      // already compressed and pass through. Hash + name reflect the ENCODED bytes.
      if (audioEnc && ext.toLowerCase() === '.wav') {
        const settings = audioEnc.audioImportSettings(entry.importer);
        if (settings.compress) {
          const mp3 = await audioEnc.encodeWavToMp3(data, settings.bitrateKbps);
          if (mp3 && mp3.byteLength < data.byteLength) {
            const trim = audioEnc.encodedClipTrim(data);
            if (trim) encodedByUuid.set(entry.uuid, trim);
            data = mp3;
            ext = '.mp3';
          } else if (!mp3) {
            warnings.push(`${entry.path}: WAV parse failed — shipped raw`);
          }
        }
      }
      // Video → `.esv` (MPEG-1 for the wasm decoder) + audio-track sibling.
      // `.esv` sources are already in the cooked format and pass through.
      let videoAudio: Uint8Array | null = null;
      if (willTranscodeVideo && videoEnc) {
        const settings = videoEnc.videoImportSettings(entry.importer);
        const res = await videoEnc.transcodeVideoForWasm(path.join(root, entry.path), settings);
        warnings.push(...res.warnings.map((w) => `${entry.path}: ${w}`));
        if (res.esv) {
          data = res.esv;
          ext = '.esv';
          videoAudio = res.audio;
        } else {
          throw new Error('video transcode failed — the original video cannot play on this target\'s WASM decoder');
        }
      }
      // Materials: relative refs → logical project paths (see rewriteMaterialRefs).
      if (ext.toLowerCase() === '.esmaterial') {
        try {
          data = rewriteMaterialRefs(data, entry.path, byPath);
        } catch (err) {
          warnings.push(`${entry.path}: material ref rewrite failed — ${err instanceof Error ? err.message : String(err)}`);
        }
      }
      // Bitmap fonts: the sibling page image → its logical project path.
      if (ext.toLowerCase() === '.fnt') {
        try {
          data = rewriteFontRefs(data, entry.path, byPath);
        } catch (err) {
          warnings.push(`${entry.path}: font ref rewrite failed — ${err instanceof Error ? err.message : String(err)}`);
        }
      }
      // Environments: the sibling reflection atlas → its logical project path.
      if (ext.toLowerCase() === '.esenv') {
        try {
          data = rewriteEnvironmentRefs(data, entry.path, byPath);
        } catch (err) {
          warnings.push(`${entry.path}: environment ref rewrite failed — ${err instanceof Error ? err.message : String(err)}`);
        }
      }
      // Animator controllers: the clips their motions play → logical project paths.
      if (ext.toLowerCase() === '.esanimator') {
        try {
          data = rewriteAnimatorRefs(data, entry.path, byPath);
        } catch (err) {
          warnings.push(`${entry.path}: animator ref rewrite failed — ${err instanceof Error ? err.message : String(err)}`);
        }
      }
      // Tilemaps: relative tileset image/source refs → logical project paths, so the
      // @uuid-loaded map resolves them to the embedded assets (see rewriteTilemapRefs).
      if (ext.toLowerCase() === '.tmj' || ext.toLowerCase() === '.tmx') {
        try {
          data = rewriteTilemapRefs(data, entry.path, byPath);
        } catch (err) {
          warnings.push(`${entry.path}: tilemap ref rewrite failed — ${err instanceof Error ? err.message : String(err)}`);
        }
      }
      // A WGSL twin is what makes a shader run on the WebGPU backend. The repo's own
      // sources carry none, so one is derived here from the GLSL when the converters
      // are at hand (a checkout of the engine); a project that ships its own twin has it
      // already, and one with neither is worth a cook-time warning.
      // Asked of every shader: a generated twin that no longer matches its GLSL is
      // derived afresh, and a hand-written one is left exactly as it is.
      if (ext.toLowerCase() === '.esshader') {
        const derive = await shaderTwinDeriver();
        if (derive) data = Buffer.from(await derive(Buffer.from(data).toString('utf8')), 'utf8');
      }
      if (ext.toLowerCase() === '.esshader' &&
          !Buffer.from(data).toString('utf8').includes('#pragma fragment wgsl')) {
        warnings.push(
          `${entry.path}: no WGSL twin, and it could not be derived from the GLSL here — this shader will not ` +
          'render on the WebGPU backend (export from the editor, which derives it, or add a `#pragma fragment wgsl` twin)',
        );
      }
      const hash = contentHashHex(data);
      // Content-addressed naming: leaf assets ship as assets/<hash><ext>, so
      // byte-identical assets collapse to one file (dedup) and the URL is immutable
      // — content changes yield a new name, so it is permanently cacheable. Scenes
      // keep their logical path: they're loaded by name and the exporters read +
      // transform them in place. Refs are by uuid, so renaming leaves is transparent.
      // Group by folder convention. Lazy-subpackage assets must stay under their
      // subpackage root (subpackages/<name>/…) so the root maps to a WeChat
      // subPackage — including the content-addressed layout (root/assets/<hash>).
      const { name: group, delivery } = resolveAssetGroup(entry.path, groupsConfig);
      // Scenes keep their logical path in every layout — they are loaded by name
      // and the exporters transform them in place, addressed by it — so a scene
      // cannot travel inside a group root, and says so instead.
      const useCA = contentAddressed && entry.type !== 'scene';
      const caBase = caBaseFor(group, delivery);
      const outRel = entry.type === 'scene'
        ? swapExt(entry.path, ext)
        : useCA
          ? `${caBase}/${hash}${ext}`
          : underGroupRoot(swapExt(entry.path, ext), group, delivery);
      if (entry.type === 'scene' && groupRoot(group, delivery)) {
        warnings.push(`${entry.path}: a scene ships in the main package — group '${group}' cannot carry it`);
      }
      const dst = path.join(absOut, outRel);
      if (!staged.has(outRel)) {
        staged.add(outRel);
        await mkdir(path.dirname(dst), { recursive: true });
        await writeFile(dst, data);
      }
      let streamTail: CookManifestEntry['streamTail'];
      if (tail) {
        const tailRel = useCA ? `${caBase}/${contentHashHex(tail.bytes)}${tail.ext}` : `${outRel}.tail${tail.ext}`;
        if (!staged.has(tailRel)) {
          staged.add(tailRel);
          await writeFile(path.join(absOut, tailRel), tail.bytes);
        }
        streamTail = { path: tailRel, size: tail.bytes.byteLength, width: tail.width, height: tail.height, fullWidth: tail.fullWidth, fullHeight: tail.fullHeight };
      }
      manifestEntries.push({
        uuid: entry.uuid,
        path: outRel,
        sourcePath: entry.path,
        type: entry.type,
        importer: entry.importer,
        contentHash: hash,
        size: data.byteLength,
        group,
        groupMode: delivery,
        ...(compressedFormats ? { compressedFormats } : {}),
        ...(cook ? { cook } : {}),
        ...(streamTail ? { streamTail } : {}),
      });
      // The video's audio track ships as its own manifest entry addressed as
      // `<source path>.m4a` / uuid `<video uuid>-audio` — the runtime resolves
      // it through the same ref channel as everything else. The flat layout
      // also keeps the `<staged>.m4a` sibling NAME (appended, not
      // extension-swapped, so it can't collide with a real `.m4a` asset) as a
      // resolver-free fallback; content addressing names it by ITS OWN bytes —
      // two videos with identical footage but different audio must not dedup
      // to one soundtrack.
      if (videoAudio) {
        const audioHash = contentHashHex(videoAudio);
        const audioOutRel = useCA ? `${caBase}/${audioHash}.m4a` : `${outRel}.m4a`;
        if (!staged.has(audioOutRel)) {
          staged.add(audioOutRel);
          await writeFile(path.join(absOut, audioOutRel), videoAudio);
        }
        manifestEntries.push({
          uuid: `${entry.uuid}-audio`,
          path: audioOutRel,
          sourcePath: `${entry.path}.m4a`,
          type: 'audio',
          contentHash: audioHash,
          size: videoAudio.byteLength,
          group,
          groupMode: delivery,
        });
      }
    } catch (err) {
      const why = err instanceof Error ? err.message : String(err);
      warnings.push(`copy failed ${entry.path}: ${why}`);
      failed.push(`${entry.path}: ${why}`);
    }
  };
  const sinks = await mapInOrder([...reachable], textureEnc?.ENCODER_PARALLELISM ?? 1, async (uuid) => {
    const sink: CookSink = { warnings: [], failed: [], defeatedByFormat: [], manifestEntries: [] };
    await cookOne(uuid, sink);
    return sink;
  });
  for (const sink of sinks) {
    warnings.push(...sink.warnings);
    failed.push(...sink.failed);
    defeatedByFormat.push(...sink.defeatedByFormat);
    manifestEntries.push(...sink.manifestEntries);
  }
  manifestEntries.sort((a, b) => a.path.localeCompare(b.path));

  // Is the package self-consistent? A document still naming a path the package
  // lacks is a 404 the game shows as a missing texture or absent lighting rather
  // than as an error — and the type it happens on need not be one anyone wired up.
  const shipped = new Set(manifestEntries.map((e) => e.sourcePath));
  for (const entry of manifestEntries) {
    const type = getAssetTypeEntry(entry.sourcePath);
    if (type?.contentType !== 'json' && type?.contentType !== 'text') continue;
    let text: string;
    try {
      text = (await readFile(path.join(absOut, entry.path))).toString('utf8');
    } catch { continue; }
    for (const ref of unresolvedDocumentRefs(entry.sourcePath, text, shipped)) {
      warnings.push(`${entry.sourcePath}: names '${ref}', which the package does not carry`);
    }
  }

  const manifestPath = path.join(absOut, MANIFEST);
  await writeFile(
    manifestPath,
    JSON.stringify({ version: '1.0', entries: manifestEntries }, null, 2) + '\n',
  );

  const unused = index.entries.filter((e) => !reachable.has(e.uuid)).map((e) => e.uuid);
  const includedPaths = [...reachable].map((uuid) => byUuid.get(uuid)?.path).filter((p): p is string => p !== undefined);
  // Said, not overridden: the author chose the file, and this is what it costs. A
  // lightmap is left out — the bake keeps it exact on purpose.
  const drawnRaw = compressTextures ? [...reachable].map((uuid) => byUuid.get(uuid)!)
    .filter((e) => e.type === 'texture' && roles.get(e.uuid)?.has('surface') && !atlasPlan.has(e.path)
      && readTextureCookSettings(e.importer, platform).compress === 'off') : [];
  if (drawnRaw.length) {
    let decoded = 0;
    for (const e of drawnRaw) {
      const size = await pngHeaderSize(path.join(root, e.path));
      if (size) decoded += size.width * size.height * 4 * 4 / 3;
    }
    warnings.push(`${drawnRaw.length} texture(s) a mesh draws ship as their original image (Compression: `
      + `Original image) — ${Math.round(decoded / 2 ** 20)} MiB of video memory decoded, where GPU `
      + `compressed would take about a quarter of it: ${drawnRaw.slice(0, 5).map((e) => e.path).join(', ')}`
      + `${drawnRaw.length > 5 ? ', …' : ''}`);
  }
  if (defeatedByFormat.length) {
    const shown = defeatedByFormat.slice(0, 3).join(', ');
    warnings.push(`${defeatedByFormat.length} image(s) ask to be compressed but are not PNG, so they `
      + `ship as they are — ${shown}${defeatedByFormat.length > 3 ? ', …' : ''}`);
  }
  // Keyed by logical path: that is what a reference names and what a report can
  // show, while the uuid is an identity nobody reading the report has.
  const inclusion: Record<string, Inclusion> = {};
  for (const [uuid, how] of inclusionByUuid) {
    const logical = byUuid.get(uuid)?.path;
    if (logical) inclusion[logical] = how;
  }
  const audioLoadTypes: Record<string, 'streaming' | 'decompress'> = {};
  for (const uuid of reachable) {
    const e = byUuid.get(uuid);
    const type = e?.type === 'audio' ? audioLoadTypeOf(e.importer) : null;
    if (e && type) audioLoadTypes[e.path] = type;
  }
  const audioEncoded: Record<string, { seconds: number; lead: number }> = {};
  for (const [uuid, trim] of encodedByUuid) {
    const e = byUuid.get(uuid);
    // To a hundred-thousandth of a second, which is finer than a sample and keeps the config short.
    if (e && reachable.has(uuid)) audioEncoded[e.path] = { seconds: Math.round(trim.seconds * 1e5) / 1e5, lead: Math.round(trim.lead * 1e5) / 1e5 };
  }
  return {
    ok: failed.length === 0,
    outDir: absOut, manifestPath, included: [...reachable], includedPaths, audioLoadTypes, audioEncoded, unused, warnings, failed,
    inclusion,
  };
}