three-vat 4.1.0 → 4.2.0

package/README.md

@@ -91,8 +91,10 @@ says why. [The rig encoding](./docs/usage.md#the-rig-encoding-encoding-rig).
 <details>
 <summary><b>Does it work with my model?</b></summary>
 
-If `GLTFLoader` loads it and it has an `AnimationClip`, yes — the four shapes
-listed in the snippet above, and any mix of them, through that one call.
+If `GLTFLoader` or `FBXLoader` loads it and it has an `AnimationClip`, yes — the
+four shapes listed in the snippet above, and any mix of them, through that one
+call. Run an FBX mesh's geometry through `mergeVertices` first: the loader never
+indexes it ([Loading FBX](./docs/usage.md#loading-fbx)).
 
 The bake unit is the **subtree**, not the mesh
 ([ADR-0008](./docs/adr/0008-a-vat-bakes-a-posed-subtree-not-a-skinnedmesh.md)),
@@ -103,7 +105,8 @@ Positions bake exactly under any rig; normals match what three's own skinning
 shader draws, which is approximate under non-uniform bone scale — `bakeVAT`
 warns once and names the bone. A rest-pose track such as Mixamo's `TPose` bakes
 to a frozen band and reports it as a near-zero `clip.maxDelta`: filter those out
-of `gltf.animations` rather than spending texture rows on them.
+of `gltf.animations` rather than spending texture rows on them, as you would
+the empty `Take 001` a Mixamo FBX carries.
 
 </details>
 
@@ -137,6 +140,22 @@ which is the finer grain anyway.
 
 </details>
 
+<details>
+<summary><b>Playing backwards</b></summary>
+
+A negative rate plays a clip backwards, from the band already baked, with
+nothing extra in the texture. Two spellings:
+
+- **One instance:** `speed: -1` on its entry, or on a `setVATInstance` write.
+- **Every instance of a clip:** `action.timeScale = -1` on the action handed to
+  `bakeVAT`, the way three already spells it. An instance's own `speed`
+  still overrides it, in either direction.
+
+A reversed one-shot starts on its last frame, with no `action.time` to move
+first. [Playing backwards](./docs/usage.md#playing-backwards).
+
+</details>
+
 <details>
 <summary><b>Upgrading from 1.x</b></summary>
 
@@ -179,18 +198,28 @@ The bake is CPU work done once at load. Under the vertex encoding that is about
 many clips; the rig encoding bakes several to a few hundred times faster. It
 never touches the renderer, so `bakeVATInWorker` runs it in a Web Worker as-is.
 
+Or bake once at build time, with `three-vat bake --out`, and `loadVAT` reads
+the **baked file** back as the VAT `bakeVAT` would have returned:
+
+```js
+import { loadVAT } from 'three-vat'
+
+const vat = await loadVAT('/model.vat.glb')
+const { mesh, time } = createVATMesh(vat, instances)
+```
+
 **[docs/usage.md](./docs/usage.md)** has the measured bake-cost table, the
-worker bake, the draw-call arithmetic, and the primitives underneath
-`createVATMesh` for when you are not rendering onto a plain `InstancedMesh`.
+worker bake, [baking at build time](./docs/usage.md#baking-at-build-time-loadvat),
+the draw-call arithmetic, and the primitives underneath `createVATMesh` for
+when you are not rendering onto a plain `InstancedMesh`.
 
 </details>
 
 <details>
 <summary><b>What it does not do</b></summary>
 
-No LOD, no baking CLI or file format, no React/drei binding, glTF input
-only. Each is a decision rather than a
-gap, and each is written up with its reasoning in
+No LOD, no React/drei binding, glTF and FBX input only. Each is a decision
+rather than a gap, and each is written up with its reasoning in
 **[docs/usage.md](./docs/usage.md#what-10-does-not-do)**, alongside the
 trade-offs against `SkinnedMesh` and bone-texture instancing.
 

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -0,0 +1,585 @@
+#!/usr/bin/env node
+import { writeBakedFile, readSourceImages, pbrConversions, dataURI } from './chunk-7TT7B5WS.js';
+import { bakeVAT } from './chunk-P6AFXEBT.js';
+import { EndMode, INFINITE_REPETITIONS, LoopMode } from './chunk-4IKOXUSX.js';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { dirname } from 'path';
+import process, { cwd, argv, stderr, stdout } from 'process';
+import { AnimationMixer, LoopPingPong, LoopOnce, LoopRepeat, LoadingManager, Texture, InterleavedBufferAttribute } from 'three';
+import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
+import { FBXLoader } from 'three/examples/jsm/loaders/FBXLoader.js';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { mergeVertices, deinterleaveAttribute } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+
+var EXIT_OK = 0;
+var EXIT_REFUSED = 1;
+var EXIT_USAGE = 2;
+var EXIT_CRASH = 3;
+var CONFIG_NAME = "vat.config.json";
+var USAGE = `usage: three-vat bake <input.glb|input.gltf|input.fbx> [flags]
+
+  --fps <n>                 sample rate, default 30
+  --clips <name,...>        the clips to bake, default every clip in the file
+  --encoding <auto|rig|delta>
+  --max-texture-size <n>    the target GPU's largest texture dimension
+  --no-normals              drop the vertex encoding's normal layer
+  --merge-flat-materials    collapse materials that differ only in colour
+  --max-bytes <n>           fail when the VAT's textures exceed this many bytes
+  --config <path>           a vat.config.json, default the one beside the input
+  --out <path>              also write a baked file, for loadVAT to load
+`;
+var CommandError = class extends Error {
+  constructor(message, code, showUsage = false) {
+    super(message);
+    this.code = code;
+    this.showUsage = showUsage;
+  }
+};
+var usage = (message) => new CommandError(`three-vat: ${message}`, EXIT_USAGE);
+var ENCODINGS = ["auto", "rig", "delta"];
+function positiveInteger(name, raw) {
+  const value = typeof raw === "string" && raw.trim() !== "" ? Number(raw) : raw;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw usage(`${name} takes a positive integer, not ${JSON.stringify(raw)}`);
+  }
+  return value;
+}
+function positiveNumber(name, raw) {
+  const value = typeof raw === "string" && raw.trim() !== "" ? Number(raw) : raw;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw usage(`${name} takes a positive number, not ${JSON.stringify(raw)}`);
+  }
+  return value;
+}
+function encodingOf(name, raw) {
+  if (!ENCODINGS.includes(raw)) {
+    throw usage(`${name} takes ${ENCODINGS.join(", ")}, not ${JSON.stringify(raw)}`);
+  }
+  return raw;
+}
+function parseArgs(argv2) {
+  const [command, ...rest] = argv2;
+  if (command !== "bake") {
+    throw usage(command === void 0 ? "no command given" : `unknown command "${command}"; the one command is "bake"`);
+  }
+  const flags = {};
+  let input;
+  let config;
+  let out;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (!arg.startsWith("--")) {
+      if (input !== void 0) throw usage(`one input at a time: "${input}", then "${arg}"`);
+      input = arg;
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    const flag = eq === -1 ? arg : arg.slice(0, eq);
+    const value = () => {
+      if (eq !== -1) return arg.slice(eq + 1);
+      const next = rest[++i];
+      if (next === void 0) throw usage(`${flag} takes a value`);
+      return next;
+    };
+    const bare = () => {
+      if (eq !== -1) throw usage(`${flag} takes no value`);
+    };
+    switch (flag) {
+      case "--fps":
+        flags.fps = positiveNumber(flag, value());
+        break;
+      case "--clips":
+        flags.clips = value().split(",").map((name) => name.trim()).filter((name) => name !== "");
+        if (flags.clips.length === 0) throw usage("--clips names no clip");
+        break;
+      case "--encoding":
+        flags.encoding = encodingOf(flag, value());
+        break;
+      case "--max-texture-size":
+        flags.maxTextureSize = positiveInteger(flag, value());
+        break;
+      case "--no-normals":
+        bare();
+        flags.bakeNormals = false;
+        break;
+      case "--merge-flat-materials":
+        bare();
+        flags.mergeFlatMaterials = true;
+        break;
+      case "--max-bytes":
+        flags.maxBytes = positiveInteger(flag, value());
+        break;
+      case "--config":
+        config = value();
+        break;
+      case "--out":
+        out = value();
+        break;
+      default:
+        throw usage(`unknown flag ${flag}`);
+    }
+  }
+  if (input === void 0) throw usage("bake takes an input file");
+  return { input, config, out, flags };
+}
+var CONFIG_KEYS = [
+  "fps",
+  "clips",
+  "encoding",
+  "maxTextureSize",
+  "bakeNormals",
+  "mergeFlatMaterials",
+  "maxBytes",
+  "clipDefaults"
+];
+var CLIP_DEFAULT_KEYS = ["loopMode", "repetitions", "endMode", "speed"];
+var LOOP_NAMES = ["repeat", "once", "pingpong"];
+var END_NAMES = ["clamp", "rewind"];
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function parseConfigEntry(where, entry) {
+  if (!isRecord(entry)) throw usage(`${where} is not an object`);
+  const options = {};
+  for (const [key, raw] of Object.entries(entry)) {
+    const name = `${where}.${key}`;
+    switch (key) {
+      case "fps":
+        options.fps = positiveNumber(name, raw);
+        break;
+      case "clips":
+        if (!Array.isArray(raw) || raw.length === 0 || raw.some((c) => typeof c !== "string")) {
+          throw usage(`${name} takes a list of clip names`);
+        }
+        options.clips = raw;
+        break;
+      case "encoding":
+        options.encoding = encodingOf(name, raw);
+        break;
+      case "maxTextureSize":
+        options.maxTextureSize = positiveInteger(name, raw);
+        break;
+      case "maxBytes":
+        options.maxBytes = positiveInteger(name, raw);
+        break;
+      case "bakeNormals":
+      case "mergeFlatMaterials":
+        if (typeof raw !== "boolean") throw usage(`${name} takes true or false`);
+        options[key] = raw;
+        break;
+      case "clipDefaults":
+        if (!isRecord(raw)) throw usage(`${name} is not an object keyed by clip name`);
+        options.clipDefaults = {};
+        for (const [clip, defaults] of Object.entries(raw)) {
+          options.clipDefaults[clip] = parseClipDefaults(`${name}.${clip}`, defaults);
+        }
+        break;
+      default:
+        throw usage(`unknown config key "${key}" in ${where}; expected one of ${CONFIG_KEYS.join(", ")}`);
+    }
+  }
+  return options;
+}
+function parseClipDefaults(where, raw) {
+  if (!isRecord(raw)) throw usage(`${where} is not an object`);
+  const defaults = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const name = `${where}.${key}`;
+    switch (key) {
+      case "loopMode":
+        if (!LOOP_NAMES.includes(value)) throw usage(`${name} takes ${LOOP_NAMES.join(", ")}`);
+        defaults.loopMode = value;
+        break;
+      case "endMode":
+        if (!END_NAMES.includes(value)) throw usage(`${name} takes ${END_NAMES.join(", ")}`);
+        defaults.endMode = value;
+        break;
+      case "repetitions":
+        defaults.repetitions = positiveInteger(name, value);
+        break;
+      case "speed":
+        if (typeof value !== "number" || !Number.isFinite(value)) throw usage(`${name} takes a number`);
+        defaults.speed = value;
+        break;
+      default:
+        throw usage(`unknown config key "${key}" in ${where}; expected one of ${CLIP_DEFAULT_KEYS.join(", ")}`);
+    }
+  }
+  return defaults;
+}
+var isAbsolute = (path) => /^([A-Za-z]:)?[\\/]/.test(path);
+function resolvePath(from, path) {
+  const joined = isAbsolute(path) ? path : `${from.replace(/[\\/]+$/, "")}/${path}`;
+  const drive = /^[A-Za-z]:/.exec(joined)?.[0] ?? (/^[\\/]{2}(?![\\/])/.test(joined) ? "/" : "");
+  const parts = [];
+  for (const part of joined.slice(drive.length).split(/[\\/]+/)) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") parts.pop();
+    else parts.push(part);
+  }
+  return `${drive}/${parts.join("/")}`;
+}
+var dirnameOf = (path) => path.slice(0, Math.max(path.lastIndexOf("/"), 0)) || "/";
+function readConfig(io, input, named) {
+  const path = named !== void 0 ? resolvePath(io.cwd, named) : resolvePath(dirnameOf(input), CONFIG_NAME);
+  if (named === void 0 && !io.exists(path)) return { path: null, options: {} };
+  let text;
+  try {
+    text = new TextDecoder().decode(io.readFile(path));
+  } catch (error) {
+    throw usage(`cannot read the config ${named ?? path}: ${error.message}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    throw usage(`the config ${named ?? path} is not JSON: ${error.message}`);
+  }
+  if (!isRecord(json)) throw usage(`the config ${named ?? path} is not an object keyed by input file`);
+  const dir = dirnameOf(path);
+  for (const [key, entry] of Object.entries(json)) {
+    if (resolvePath(dir, key) === input) return { path: named ?? path, options: parseConfigEntry(`"${key}"`, entry) };
+  }
+  return { path: named ?? path, options: {} };
+}
+var DRACO = "KHR_draco_mesh_compression";
+var ownBuffer = (bytes) => new Uint8Array(bytes).buffer;
+function gltfJSON(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const isGLB = bytes.byteLength >= 20 && view.getUint32(0, true) === 1179937895;
+  const text = isGLB ? new TextDecoder().decode(bytes.subarray(20, 20 + view.getUint32(12, true))) : new TextDecoder().decode(bytes);
+  const json = JSON.parse(text);
+  if (!isRecord(json)) throw new Error("its JSON is not an object");
+  return json;
+}
+var meshesIn = (root) => {
+  const meshes = [];
+  root.traverse((o) => void (o.isMesh && meshes.push(o)));
+  return meshes;
+};
+var vertexTotal = (root) => meshesIn(root).reduce((n, mesh) => n + (mesh.geometry.attributes.position?.count ?? 0), 0);
+async function loadGLTF(io, input, argPath, bytes) {
+  let json;
+  try {
+    json = gltfJSON(bytes);
+  } catch (error) {
+    throw usage(`cannot read ${argPath} as glTF: ${error.message}`);
+  }
+  const used = Array.isArray(json.extensionsUsed) ? json.extensionsUsed : [];
+  if (used.includes(DRACO)) {
+    const decoded = argPath.replace(/(\.[^./\\]+)?$/, ".decoded$1");
+    throw usage(
+      `${argPath} is Draco-compressed (${DRACO}), which the command cannot decode in Node. Decode it first, then bake the result:
+
+  npx @gltf-transform/cli copy ${argPath} ${decoded}
+`
+    );
+  }
+  const readBuffer = (url) => {
+    const data = dataURI(url);
+    if (data) return data;
+    return ownBuffer(io.readFile(resolvePath(dirnameOf(input), decodeURIComponent(url))));
+  };
+  const fileLoader = {
+    load(url, onLoad, _, onError) {
+      let buffer;
+      try {
+        buffer = readBuffer(url);
+      } catch (error) {
+        onError(error);
+        return;
+      }
+      onLoad(buffer);
+    }
+  };
+  await MeshoptDecoder.ready;
+  const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).setKTX2Loader({}).register((parser2) => {
+    const reach = parser2;
+    reach.fileLoader = fileLoader;
+    reach.loadImageSource = () => Promise.resolve(new Texture());
+    return { name: "three-vat:read-through-the-command" };
+  });
+  let gltf;
+  try {
+    gltf = await loader.parseAsync(ownBuffer(bytes), "");
+  } catch (error) {
+    throw usage(`cannot load ${argPath}: ${error.message}`);
+  }
+  deinterleave(gltf.scene);
+  const { parser } = gltf;
+  return {
+    root: gltf.scene,
+    clips: gltf.animations,
+    loadedVertices: vertexTotal(gltf.scene),
+    readImages: () => readSourceImages(parser, readBuffer)
+  };
+}
+function deinterleave(root) {
+  const copyOut = deinterleaveAttribute;
+  const copies = /* @__PURE__ */ new Map();
+  const plain = (attribute) => {
+    if (!(attribute instanceof InterleavedBufferAttribute)) return attribute;
+    let copy = copies.get(attribute);
+    if (!copy) copies.set(attribute, copy = copyOut(attribute));
+    return copy;
+  };
+  for (const mesh of meshesIn(root)) {
+    const geometry = mesh.geometry;
+    for (const [name, attribute] of Object.entries(geometry.attributes)) geometry.setAttribute(name, plain(attribute));
+    for (const targets of Object.values(geometry.morphAttributes)) {
+      targets.forEach((attribute, i) => targets[i] = plain(attribute));
+    }
+  }
+}
+var NoImageLoader = class {
+  constructor() {
+    this.path = "";
+  }
+  setPath(path) {
+    this.path = path;
+    return this;
+  }
+  load() {
+    return new Texture();
+  }
+};
+function loadFBX(argPath, bytes) {
+  const manager = new LoadingManager();
+  manager.addHandler(/./, new NoImageLoader());
+  let root;
+  try {
+    root = new FBXLoader(manager).parse(ownBuffer(bytes), "");
+  } catch (error) {
+    throw usage(`cannot load ${argPath}: ${error.message}`);
+  }
+  const loadedVertices = vertexTotal(root);
+  for (const mesh of meshesIn(root)) mesh.geometry = mergeVertices(mesh.geometry);
+  const clips = root.animations.filter((clip) => !(clip.name === "Take 001" && clip.tracks.length === 0));
+  return { root, clips, loadedVertices, readImages: () => Promise.resolve(/* @__PURE__ */ new Map()) };
+}
+async function load(io, input, argPath) {
+  const extension = /\.([^./\\]+)$/.exec(input)?.[1]?.toLowerCase();
+  if (extension !== "glb" && extension !== "gltf" && extension !== "fbx") {
+    throw usage(`${argPath} is not a supported format; the command bakes .glb, .gltf and .fbx`);
+  }
+  let bytes;
+  try {
+    bytes = io.readFile(input);
+  } catch (error) {
+    throw usage(`cannot read ${argPath}: ${error.message}`);
+  }
+  return extension === "fbx" ? loadFBX(argPath, bytes) : loadGLTF(io, input, argPath, bytes);
+}
+var LOOP_STYLES = {
+  repeat: LoopRepeat,
+  once: LoopOnce,
+  pingpong: LoopPingPong
+};
+function bakeInputs(loaded, options) {
+  const byName = new Map(loaded.clips.map((clip) => [clip.name, clip]));
+  const known = () => [...byName.keys()].map((name) => `"${name}"`).join(", ") || "none";
+  const names = options.clips ?? [...byName.keys()];
+  for (const name of [...names, ...Object.keys(options.clipDefaults ?? {})]) {
+    if (!byName.has(name)) throw usage(`no clip named "${name}"; the file has ${known()}`);
+  }
+  const mixer = new AnimationMixer(loaded.root);
+  const endModes = /* @__PURE__ */ new Map();
+  const inputs = names.map((name) => {
+    const clip = byName.get(name);
+    const defaults = options.clipDefaults?.[name];
+    if (defaults === void 0) return clip;
+    const action = mixer.clipAction(clip);
+    if (defaults.loopMode !== void 0) action.loop = LOOP_STYLES[defaults.loopMode];
+    if (defaults.repetitions !== void 0) action.repetitions = defaults.repetitions;
+    if (defaults.speed !== void 0) action.timeScale = defaults.speed;
+    if (defaults.endMode !== void 0) endModes.set(name, defaults.endMode === "rewind" ? EndMode.Rewind : EndMode.Clamp);
+    return action;
+  });
+  return { inputs, endModes };
+}
+function layersOf(vat) {
+  if (vat.encoding === "rig") return [{ name: "rig", texture: vat.rigTexture, format: "RGBA32F" }];
+  const layers = [{ name: "position", texture: vat.positionTexture, format: "RGBA16F" }];
+  if (vat.normalTexture) layers.push({ name: "normal", texture: vat.normalTexture, format: "RG8" });
+  return layers;
+}
+var bytesOf = (texture) => texture.image.data.byteLength;
+var round = (n) => String(Number(n.toFixed(2)));
+function describeDefaults(clip) {
+  const times = clip.repetitions === INFINITE_REPETITIONS ? "forever" : `x${clip.repetitions}`;
+  const loop = clip.loopMode === LoopMode.Once ? "once" : clip.loopMode === LoopMode.PingPong ? `pingpong ${times}` : `repeat ${times}`;
+  const end = clip.endMode === EndMode.Rewind ? "rewind" : "clamp";
+  return `${loop}, ${end}, speed ${round(clip.speed)}`;
+}
+function report(argPath, config, loaded, vat, ms, written) {
+  const lines = [`three-vat bake ${argPath}`, `config: ${config ?? "none"}`];
+  if (vat.encoding === "rig") {
+    lines.push(`encoding: rig, ${vat.slotCount} slot${vat.slotCount === 1 ? "" : "s"}`);
+  } else {
+    const rows = vat.rowsPerFrame > 1 ? `, ${vat.rowsPerFrame} rows per frame` : "";
+    lines.push(`encoding: delta${vat.fallback === null ? "" : ", fallen back from rig"}${rows}`);
+    if (vat.fallback !== null) lines.push(`fallback: ${vat.fallback}`);
+  }
+  lines.push(`clips: ${vat.clips.length}, ${vat.totalFrames} frames`);
+  for (const clip of vat.clips) {
+    lines.push(`  ${clip.name}: ${clip.frames} frames at ${round(clip.fps)} fps, ${describeDefaults(clip)}`);
+  }
+  const layers = layersOf(vat);
+  lines.push("textures:");
+  for (const { name, texture, format } of layers) {
+    lines.push(`  ${name}: ${texture.image.width} x ${texture.image.height} ${format}, ${bytesOf(texture)} bytes`);
+  }
+  lines.push(`  total: ${textureBytes(vat)} bytes`);
+  lines.push(`vertices: ${loaded.loadedVertices} as loaded, ${vat.vertexCount} merged`);
+  lines.push(`materials: ${vat.materials.length}`);
+  if (written) {
+    for (const { name, from, lost } of pbrConversions(vat.materials)) {
+      lines.push(`  ${name}: ${from} written as MeshStandardMaterial${lost.length ? `, losing ${lost.join(" and ")}` : ""}`);
+    }
+    lines.push(`written: ${written.path}, ${written.bytes} bytes`);
+  }
+  lines.push(`bake time: ${Math.round(ms)} ms`);
+  return `${lines.join("\n")}
+`;
+}
+var textureBytes = (vat) => layersOf(vat).reduce((n, { texture }) => n + bytesOf(texture), 0);
+async function runCommand(argv2, io) {
+  if (argv2.length === 0) {
+    io.stderr(USAGE);
+    return EXIT_USAGE;
+  }
+  const [first, ...rest] = argv2;
+  if (first === "--help" || first === "-h" || first === "bake" && rest.includes("--help")) {
+    io.stdout(USAGE);
+    return EXIT_OK;
+  }
+  try {
+    return await bake(argv2, io);
+  } catch (error) {
+    if (!(error instanceof CommandError)) throw error;
+    io.stderr(`${error.message}
+`);
+    if (error.showUsage) io.stderr(`
+${USAGE}`);
+    return error.code;
+  }
+}
+async function bake(argv2, io) {
+  let invocation;
+  try {
+    invocation = parseArgs(argv2);
+  } catch (error) {
+    if (error instanceof CommandError) throw new CommandError(error.message, error.code, true);
+    throw error;
+  }
+  const { input: argPath, config: named, out, flags } = invocation;
+  const input = resolvePath(io.cwd, argPath);
+  const config = readConfig(io, input, named);
+  const defined = Object.fromEntries(Object.entries(flags).filter(([, v]) => v !== void 0));
+  const options = { ...config.options, ...defined };
+  const loaded = await load(io, input, argPath);
+  const { inputs, endModes } = bakeInputs(loaded, options);
+  const bakeOptions = {
+    fps: options.fps,
+    encoding: options.encoding,
+    maxTextureSize: options.maxTextureSize,
+    bakeNormals: options.bakeNormals,
+    mergeFlatMaterials: options.mergeFlatMaterials
+  };
+  const now = io.now ?? (() => performance.now());
+  const start = now();
+  let vat;
+  try {
+    vat = bakeVAT(loaded.root, inputs, bakeOptions);
+  } catch (error) {
+    throw refusal(error);
+  }
+  const ms = now() - start;
+  for (const clip of vat.clips) {
+    const endMode = endModes.get(clip.name);
+    if (endMode !== void 0) clip.endMode = endMode;
+  }
+  const printReport = (written2) => io.stdout(report(argPath, config.path, loaded, vat, ms, written2));
+  const bytes = textureBytes(vat);
+  if (options.maxBytes !== void 0 && bytes > options.maxBytes) {
+    printReport(null);
+    throw new CommandError(
+      `three-vat: the VAT's textures are ${bytes} bytes, over the ${options.maxBytes} --max-bytes allows`,
+      EXIT_REFUSED
+    );
+  }
+  let written = null;
+  if (out !== void 0) {
+    let images;
+    try {
+      images = await loaded.readImages();
+    } catch (error) {
+      printReport(null);
+      throw usage(`cannot read the images of ${argPath}: ${error.message}`);
+    }
+    let file;
+    try {
+      file = await writeBakedFile(vat, { images });
+    } catch (error) {
+      printReport(null);
+      throw refusal(error);
+    }
+    written = writeBakedFileTo(io, out, file);
+  }
+  printReport(written);
+  return EXIT_OK;
+}
+function refusal(error) {
+  if (!(error instanceof Error) || error instanceof TypeError || error instanceof RangeError || error instanceof ReferenceError) {
+    throw error;
+  }
+  return new CommandError(error.message, EXIT_REFUSED);
+}
+function writeBakedFileTo(io, out, file) {
+  try {
+    io.writeFile(resolvePath(io.cwd, out), file);
+  } catch (error) {
+    throw usage(`cannot write ${out}: ${error.message}`);
+  }
+  return { path: out, bytes: file.byteLength };
+}
+
+// src/file-reader.ts
+function installFileReader() {
+  const scope = globalThis;
+  if (scope.FileReader !== void 0) return;
+  scope.FileReader = class {
+    constructor() {
+      this.result = null;
+      this.onloadend = null;
+    }
+    readAsArrayBuffer(blob) {
+      void blob.arrayBuffer().then((buffer) => {
+        this.result = buffer;
+        this.onloadend?.();
+      });
+    }
+  };
+}
+
+// src/bin.ts
+installFileReader();
+runCommand(argv.slice(2), {
+  cwd: cwd(),
+  readFile: (path) => readFileSync(path),
+  exists: existsSync,
+  writeFile: (path, bytes) => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, bytes);
+  },
+  stdout: (text) => void stdout.write(text),
+  stderr: (text) => void stderr.write(text)
+}).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    stderr.write(`three-vat: the command crashed; please report it
+${error?.stack ?? String(error)}
+`);
+    process.exitCode = EXIT_CRASH;
+  }
+);

package/dist/carrier-DmKhB4QL.d.ts

@@ -0,0 +1,13 @@
+import { InstancedMesh, BatchedMesh } from 'three';
+
+/**
+ * A mesh a VAT crowd can ride.
+ *
+ * `InstancedMesh` is what `createVATMesh` builds on either path.
+ * `BatchedMesh` is reached through the primitives, and buys per-instance
+ * frustum culling and depth sorting from three.js itself — see
+ * docs/usage.md, which also says what it does *not* buy.
+ */
+type VATCarrier = InstancedMesh | BatchedMesh;
+
+export type { VATCarrier as V };