@n1h/web-characters 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @n1h/web-characters
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Animated glTF characters for any web page. The core of [catwalk](https://github.com/n0t-invented-here/catwalk).
+
+- A see-through canvas per character, over the page.
+- Drops in, falls, lands on the page's bottom edge or on another character's head.
+- Idles, walks, runs, turns at the sides, bumps into others, can be picked up and thrown.
+- Clicks beside the model reach the page.
+- Models come from packs (`@n1h/web-characters-cube-pets`, `@n1h/web-characters-block-characters`) or your own `ModelSpec`.
+
+```ts
+import { createCharacter } from "@n1h/web-characters";
+import { cat } from "@n1h/web-characters-cube-pets/cat";
+
+createCharacter({ model: cat, spawn: { x: 300, y: 0 } });
+```
+
+| Entry | Exports |
+|---|---|
+| `@n1h/web-characters` | `createCharacter`, settings, the spec helpers, the life and framing for anyone building on them |
+| `@n1h/web-characters/react` | `<Character>` |
+| `@n1h/web-characters/model` | the `ModelSpec` type |
+
+Reference: [the core](https://github.com/n0t-invented-here/catwalk/blob/main/docs/core.md), [the model spec](https://github.com/n0t-invented-here/catwalk/blob/main/docs/model-spec.md), [how it works](https://github.com/n0t-invented-here/catwalk/blob/main/docs/internals.md).

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@n1h/web-characters",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Animated glTF characters for any web page: a see-through canvas that drops a model in at a point, lands it on the bottom edge or on another character's head and lets it live there, idle, walk, run, bump, be picked up and thrown. Babylon.js underneath; a framework-free createCharacter() and a React <Character>. Models come from packs (@n1h/web-characters-cube-pets, @n1h/web-characters-block-characters) or your own ModelSpec.",
+  "license": "MIT OR 0BSD",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/n0t-invented-here/catwalk.git",
+    "directory": "packages/web-characters"
+  },
+  "homepage": "https://github.com/n0t-invented-here/catwalk#readme",
+  "bugs": {
+    "url": "https://github.com/n0t-invented-here/catwalk/issues"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./react": "./src/react.tsx",
+    "./model": "./src/model.ts",
+    "./assets": {
+      "types": "./src/assets.d.ts"
+    }
+  },
+  "dependencies": {
+    "@babylonjs/core": "^9.35.0",
+    "@babylonjs/loaders": "^9.35.0"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/assets.d.ts

@@ -0,0 +1,11 @@
+// A model file imported by path: the import resolves to a URL the page can
+// fetch, and the bundler ships the file. Bun, Vite and esbuild do this by
+// default; webpack needs asset modules for .glb and .png.
+declare module "*.glb" {
+  const url: string;
+  export default url;
+}
+declare module "*.png" {
+  const url: string;
+  export default url;
+}

package/src/character.ts

@@ -0,0 +1,235 @@
+// A character on a page: a see-through canvas the model is drawn on, placed over the
+// page and moved every frame as the life says. Characters on the same ground step
+// together (ground.ts) and bump into each other. Clicks reach the page through
+// the canvas everywhere the model is not; over the model, the hand cursor
+// shows and a press picks the character up.
+
+import { groundFor } from "./ground";
+import { BODY, FEET, HEAD, createLife, type Box } from "./life";
+import type { ModelSpec } from "./model";
+import { createModelScene } from "./scene";
+import { DEFAULT_CHARACTER_SETTINGS, sanitizeCharacterSettings, type CharacterSettings } from "./settings";
+
+/** The character's box edge at scale 1, in CSS pixels. */
+export const CHARACTER_SIZE = 192;
+
+export type Point = { x: number; y: number };
+
+export type CharacterOptions = {
+  /** A spec from one of the packs, or your own. */
+  model: ModelSpec;
+  /**
+   * Where the character's centre appears before it falls, in CSS pixels from the
+   * top-left of its bounds (the viewport, or `host`). By default somewhere
+   * along the top edge, so it drops in from above.
+   */
+  spawn?: Point;
+  scale?: number;
+  bottom?: number;
+  /**
+   * The element the character lives in: its bounds are the element's box, the character
+   * is positioned inside it (the element becomes `position: relative` when
+   * it was static). Without one the character is fixed to the viewport and stays
+   * on screen while the page scrolls.
+   */
+  host?: HTMLElement;
+  /** Stacking of the canvas over the page's content. */
+  zIndex?: number;
+  /** Something failed after the character was created (a model that would not load). `console.error` by default. */
+  onFault?: (message: string, error?: unknown) => void;
+};
+
+export type CharacterHandle = {
+  /** The model on show. */
+  readonly model: ModelSpec;
+  readonly settings: CharacterSettings;
+  /** The box's top-left in bounds coordinates, and its edge. */
+  readonly position: Point;
+  readonly size: number;
+  /** Switch model; resolves when the new one is up (or failed and reported). */
+  setModel(model: ModelSpec): Promise<void>;
+  /** Change the scale or the bottom; the reply is the clamped result. */
+  setSettings(patch: Partial<CharacterSettings>): CharacterSettings;
+  /** Put the character's centre here and let it fall. */
+  spawn(at: Point): void;
+  dispose(): void;
+};
+
+/** Creates the canvas and starts the character. Throws when WebGL is not available. */
+export function createCharacter(options: CharacterOptions): CharacterHandle {
+  const fault = options.onFault ?? ((message: string, error?: unknown) => console.error(message, error ?? ""));
+  const host = options.host;
+  if (host && getComputedStyle(host).position === "static") host.style.position = "relative";
+
+  const canvas = document.createElement("canvas");
+  canvas.className = "web-character";
+  Object.assign(canvas.style, {
+    position: host ? "absolute" : "fixed",
+    left: "0",
+    top: "0",
+    display: "block",
+    pointerEvents: "none", // on only while the pointer is over the model (see hover below)
+    touchAction: "none",
+    userSelect: "none",
+    willChange: "transform",
+    zIndex: String(options.zIndex ?? 2147483000),
+  } satisfies Partial<CSSStyleDeclaration>);
+  (host ?? document.body).append(canvas);
+
+  let scene: ReturnType<typeof createModelScene>;
+  try {
+    scene = createModelScene(canvas);
+  } catch (err) {
+    canvas.remove();
+    throw err;
+  }
+
+  let model = options.model;
+  let settings = sanitizeCharacterSettings({ scale: options.scale, bottom: options.bottom }, DEFAULT_CHARACTER_SETTINGS);
+  let size = Math.round(CHARACTER_SIZE * settings.scale);
+
+  const bounds = (): Box => (host ? { x: 0, y: 0, width: host.clientWidth, height: host.clientHeight } : { x: 0, y: 0, width: window.innerWidth, height: window.innerHeight });
+  const life = createLife({
+    bounds,
+    size: () => size,
+    scale: () => settings.scale,
+    bottom: () => settings.bottom,
+    model: () => model,
+    has: (clip) => scene.has(clip),
+    clipSeconds: (clip) => scene.clipSeconds(clip),
+    body: () => scene.proportions()?.body ?? BODY,
+    head: () => scene.proportions()?.head ?? HEAD,
+    feet: () => scene.proportions()?.feet ?? FEET,
+  });
+
+  scene.resize(size, settings.scale);
+
+  const spawn = (at: Point) => life.spawn(at.x - size / 2, at.y - size / 2);
+  spawn(options.spawn ?? { x: bounds().width * (0.2 + Math.random() * 0.6), y: -size / 2 });
+
+  const show = async (next: ModelSpec) => {
+    model = next;
+    try {
+      await scene.show(model);
+      const measured = scene.proportions();
+      if (measured) Object.assign(canvas.dataset, { model: model.name, body: measured.body.toFixed(3), head: measured.head.toFixed(3), feet: measured.feet.toFixed(3) }); // what the page can read about the fit
+    } catch (err) {
+      fault(`loading the ${model.name} model (${model.url}) failed`, err);
+    }
+  };
+
+  // ---- pointer: a press on the model picks it up; everywhere else the canvas is not there ----
+  // The canvas takes no pointer events, so the page under it works as if it were
+  // not there. On every move the pointer is tested against the model with a
+  // triangle pick; over the model the canvas takes events and shows the hand,
+  // so the press lands here. One move of lag, never a stolen click.
+
+  /** The pointer's place in bounds coordinates. */
+  const toBounds = (e: PointerEvent): Point => {
+    if (!host) return { x: e.clientX, y: e.clientY };
+    const r = host.getBoundingClientRect();
+    return { x: e.clientX - r.left + host.scrollLeft, y: e.clientY - r.top + host.scrollTop };
+  };
+  const overModel = (e: PointerEvent): boolean => {
+    const r = canvas.getBoundingClientRect();
+    const cx = e.clientX - r.left;
+    const cy = e.clientY - r.top;
+    return cx >= 0 && cy >= 0 && cx < r.width && cy < r.height && scene.solidAt(cx, cy);
+  };
+  const hover = (e: PointerEvent) => {
+    if (life.state.kind === "carried") return;
+    const on = overModel(e);
+    canvas.style.pointerEvents = on ? "auto" : "none";
+    canvas.style.cursor = on ? "grab" : "";
+  };
+  document.addEventListener("pointermove", hover, { passive: true });
+
+  let grab = { dx: 0, dy: 0 };
+  let lastDrag = { x: 0, y: 0, t: 0, vy: 0 };
+  const onDown = (e: PointerEvent) => {
+    if (e.button !== 0 || !overModel(e)) return;
+    e.preventDefault();
+    canvas.setPointerCapture(e.pointerId);
+    const p = toBounds(e);
+    grab = { dx: p.x - life.x, dy: p.y - life.y };
+    lastDrag = { x: p.x, y: p.y, t: performance.now(), vy: 0 };
+    canvas.style.cursor = "grabbing";
+    life.pickUp();
+  };
+  const onMove = (e: PointerEvent) => {
+    if (life.state.kind !== "carried") return;
+    const p = toBounds(e);
+    const now = performance.now();
+    const dt = Math.max(1, now - lastDrag.t) / 1000;
+    const dx = p.x - lastDrag.x;
+    lastDrag = { x: p.x, y: p.y, t: now, vy: (p.y - lastDrag.y) / dt };
+    life.carryTo(p.x - grab.dx, p.y - grab.dy);
+    if (Math.abs(dx) > 2) life.face(dx < 0 ? -1 : 1);
+  };
+  const onUp = (e: PointerEvent) => {
+    if (life.state.kind !== "carried") return;
+    life.drop(lastDrag.vy);
+    canvas.style.cursor = "grab";
+    hover(e);
+  };
+  canvas.addEventListener("pointerdown", onDown);
+  canvas.addEventListener("pointermove", onMove);
+  canvas.addEventListener("pointerup", onUp);
+  canvas.addEventListener("pointercancel", onUp);
+  canvas.addEventListener("contextmenu", (e) => e.preventDefault());
+
+  // ---- loop: the ground steps every character on this ground, then each draws itself ----
+  let lastPlaced = { x: NaN, y: NaN };
+  const leave = groundFor(host ?? document).add({
+    life,
+    frame(dt) {
+      scene.play(life.animation(), life.animationSpeed());
+      scene.face(life.facing);
+      scene.render(dt);
+      const rx = Math.round(life.x);
+      const ry = Math.round(life.y);
+      if (rx !== lastPlaced.x || ry !== lastPlaced.y) {
+        lastPlaced = { x: rx, y: ry };
+        canvas.style.transform = `translate3d(${rx}px, ${ry}px, 0)`;
+      }
+    },
+  });
+
+  void show(model);
+
+  return {
+    get model() {
+      return model;
+    },
+    get settings() {
+      return settings;
+    },
+    get position() {
+      return { x: life.x, y: life.y };
+    },
+    get size() {
+      return size;
+    },
+    setModel: show,
+    setSettings(patch) {
+      settings = sanitizeCharacterSettings(patch, settings);
+      const nextSize = Math.round(CHARACTER_SIZE * settings.scale);
+      if (nextSize !== size) {
+        // Grow and shrink about the feet, so a standing character stays where it stood.
+        const feetX = life.x + size / 2;
+        size = nextSize;
+        if (life.state.kind === "carried") life.carryTo(feetX - size / 2, life.y);
+        else if (life.state.kind === "fall") life.spawn(feetX, life.y);
+      }
+      scene.resize(size, settings.scale);
+      return settings;
+    },
+    spawn,
+    dispose() {
+      leave();
+      document.removeEventListener("pointermove", hover);
+      scene.dispose();
+      canvas.remove();
+    },
+  };
+}

package/src/framing.ts

@@ -0,0 +1,132 @@
+// The camera, as numbers, and what a model's box looks like through it:
+// where its feet, its head and its sides land on the square canvas. The
+// scene aims its camera from these; the life uses the fractions for bumping
+// into other characters and standing on their heads.
+
+import type { Direction } from "./model";
+
+/** A level look from the character's own height. */
+export const CAMERA_DISTANCE = 4.4;
+export const CAMERA_FOV = 0.5;
+/** How far the models reach toward the camera; the front of that footprint sits on the canvas's bottom edge. */
+export const FOOTPRINT_Z = 0.8;
+// A fitted model faces +z, away from the camera at -z, and its face is on
+// the front, so a pure side view hides it. Facing right is a quarter turn
+// plus a bit toward the viewer; facing left is the mirror on the far side of
+// pi (facing the camera), so a turn swings the face past the viewer, never
+// the back. (Rotation about y by θ takes +z to (sin θ, 0, cos θ) and +x to
+// (cos θ, 0, -sin θ); checked against Babylon, not derived.)
+const TOWARD = 0.5;
+export const yawFor = (dir: Direction) => (dir === 1 ? Math.PI / 2 + TOWARD : (3 * Math.PI) / 2 - TOWARD);
+
+export type Bounds = { min: { x: number; y: number; z: number }; max: { x: number; y: number; z: number } };
+
+/** Where a model-space point lands on the canvas, as fractions of its edge (0,0 top-left), at any scale. Ignores the two-pixel ground margin. */
+export function projectToCanvas(p: { x: number; y: number; z: number }): { x: number; y: number } {
+  const t = Math.tan(CAMERA_FOV / 2);
+  const cameraHeight = (CAMERA_DISTANCE - FOOTPRINT_Z) * t;
+  const depth = p.z + CAMERA_DISTANCE;
+  const nx = p.x / (depth * t);
+  const ny = (p.y - cameraHeight) / (depth * t);
+  return { x: (1 + nx) / 2, y: (1 - ny) / 2 };
+}
+
+export type Proportions = {
+  /** How much of the canvas's width the model spans, as seen facing along the ground: its lower three quarters, so a raised tail or a hat does not count. */
+  body: number;
+  /** How far down the canvas the top of the model's head is: the surface straight above the model's middle, so a character standing on it stands on the head, not on a tail tip. */
+  head: number;
+  /** How far down the canvas the model's feet are, at its centre: above the bottom edge, which the front of the footprint touches. */
+  feet: number;
+};
+
+/** Where the ground at a model's centre lands on the canvas: the feet of a fitted model. */
+export const FEET = projectToCanvas({ x: 0, y: 0, z: 0 }).y;
+
+/** The lower share of the model's height that counts as its body, side to side. */
+const BAND = 0.75;
+
+/**
+ * The highest surface of the model straight above the point (x, z): the
+ * top of whatever is there, found through the triangles, so a box with
+ * only corner vertices still has a top in its middle. Nothing there: undefined.
+ */
+export function topAt(points: ArrayLike<number>, triangles: ArrayLike<number>, x: number, z: number): number | undefined {
+  let top: number | undefined;
+  for (let i = 0; i + 2 < triangles.length; i += 3) {
+    const a = triangles[i]! * 3;
+    const b = triangles[i + 1]! * 3;
+    const c = triangles[i + 2]! * 3;
+    const ax = points[a]! - x;
+    const az = points[a + 2]! - z;
+    const bx = points[b]! - x;
+    const bz = points[b + 2]! - z;
+    const cx = points[c]! - x;
+    const cz = points[c + 2]! - z;
+    // Barycentric test in the ground plane.
+    const d = (bz - cz) * ax + (cx - bx) * az + bx * cz - cx * bz;
+    if (Math.abs(d) < 1e-12) continue;
+    const u = ((bz - cz) * 0 + (cx - bx) * 0 + bx * cz - cx * bz) / d;
+    const v = ((cz - az) * 0 + (ax - cx) * 0 + cx * az - ax * cz) / d;
+    const w = 1 - u - v;
+    if (u < -1e-9 || v < -1e-9 || w < -1e-9) continue;
+    const y = u * points[a + 1]! + v * points[b + 1]! + w * points[c + 1]!;
+    if (top === undefined || y > top) top = y;
+  }
+  return top;
+}
+
+/**
+ * A fitted model's points (x, y, z triples, centred on its box with its
+ * feet at y = 0) and triangles (point indices), turned to `yaw` about y and
+ * seen through the camera.
+ */
+export function proportionsOf(points: ArrayLike<number>, triangles: ArrayLike<number>, yaw: number): Proportions {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  let minZ = Infinity;
+  let maxZ = -Infinity;
+  for (let i = 0; i + 2 < points.length; i += 3) {
+    minX = Math.min(minX, points[i]!);
+    maxX = Math.max(maxX, points[i]!);
+    minY = Math.min(minY, points[i + 1]!);
+    maxY = Math.max(maxY, points[i + 1]!);
+    minZ = Math.min(minZ, points[i + 2]!);
+    maxZ = Math.max(maxZ, points[i + 2]!);
+  }
+  if (minX === Infinity) return { body: 0, head: 0, feet: FEET };
+  // The head: the top above the middle, or above the nearest of a few spots around it; the model's top when none has anything.
+  const spots = [
+    [0, 0],
+    [(maxX - minX) * 0.1, 0],
+    [-(maxX - minX) * 0.1, 0],
+    [0, (maxZ - minZ) * 0.1],
+    [0, -(maxZ - minZ) * 0.1],
+  ];
+  let headTop = -Infinity;
+  for (const [sx, sz] of spots) {
+    const t = topAt(points, triangles, sx!, sz!);
+    if (t !== undefined) headTop = Math.max(headTop, t);
+  }
+  if (headTop === -Infinity) headTop = maxY;
+  const bandTop = minY + (maxY - minY) * BAND;
+  const c = Math.cos(yaw);
+  const s = Math.sin(yaw);
+  let left = Infinity;
+  let right = -Infinity;
+  for (let i = 0; i + 2 < points.length; i += 3) {
+    const x = points[i]!;
+    const y = points[i + 1]!;
+    const z = points[i + 2]!;
+    if (y <= bandTop) {
+      const px = projectToCanvas({ x: x * c + z * s, y, z: -x * s + z * c }).x;
+      left = Math.min(left, px);
+      right = Math.max(right, px);
+    }
+  }
+  const head = projectToCanvas({ x: 0, y: headTop, z: 0 }).y;
+  const feet = projectToCanvas({ x: 0, y: minY, z: 0 }).y;
+  return { body: Math.min(1, Math.max(0, right - left)), head: Math.max(0, head), feet: Math.min(1, feet) };
+}

package/src/ground.ts

@@ -0,0 +1,61 @@
+// Every character on the same ground steps in one loop, so they can land on
+// each other and bump into each other. One ground per host element (or per
+// document, for characters fixed to the viewport); it runs while it has
+// members.
+
+import { separate, type Life } from "./life";
+
+export type Member = {
+  life: Life;
+  /** Draw this character after the step; `dt` in seconds. */
+  frame(dt: number): void;
+};
+
+export type Ground = {
+  /** Join; the reply leaves. */
+  add(member: Member): () => void;
+};
+
+const grounds = new WeakMap<object, Ground>();
+
+/** The ground for characters that share one: a host element, or the document for the viewport. */
+export function groundFor(on: object): Ground {
+  let ground = grounds.get(on);
+  if (!ground) {
+    ground = createGround();
+    grounds.set(on, ground);
+  }
+  return ground;
+}
+
+function createGround(): Ground {
+  const members = new Set<Member>();
+  let frame: number | undefined;
+  let last = 0;
+  const loop = () => {
+    const now = performance.now();
+    const dt = Math.min(0.05, (now - last) / 1000);
+    last = now;
+    const lives = [...members].map((m) => m.life);
+    for (const life of lives) life.step(now, dt, lives);
+    separate(lives);
+    for (const m of members) m.frame(dt);
+    frame = members.size ? requestAnimationFrame(loop) : undefined;
+  };
+  return {
+    add(member) {
+      members.add(member);
+      if (frame === undefined) {
+        last = performance.now();
+        frame = requestAnimationFrame(loop);
+      }
+      return () => {
+        members.delete(member);
+        if (members.size === 0 && frame !== undefined) {
+          cancelAnimationFrame(frame);
+          frame = undefined;
+        }
+      };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+/// <reference path="./assets.d.ts" />
+export { createCharacter, CHARACTER_SIZE, type CharacterHandle, type CharacterOptions, type Point } from "./character";
+export { clipFor, clipNames, drawMood, sameModel, type ClipRef, type ClipSpec, type Direction, type MoodCommand, type MoodSpec, type ModelSpec, type Role } from "./model";
+export { DEFAULT_CHARACTER_SETTINGS, SCALE_MIN, SCALE_MAX, BOTTOM_MIN, BOTTOM_MAX, clampNumber, sanitizeCharacterSettings, type CharacterSettings } from "./settings";
+export { createLife, separate, BODY, HEAD, FEET, GRAVITY, MAX_THROW, type Box, type Life, type LifeState, type World } from "./life";
+export { projectToCanvas, proportionsOf, topAt, type Bounds, type Proportions } from "./framing";

package/src/life.ts

@@ -0,0 +1,318 @@
+// The character's little life, with no screen in it: a square box that falls,
+// lands, walks and runs along the bottom edge of its bounds, turns at the
+// sides, and can be picked up and thrown. With other lives on the same
+// ground it lands on their heads, rides along, walks off, and bumps into the
+// ones at its level. Units are whatever the world's are (CSS pixels on a
+// page); the page draws the model in the box.
+
+import { FEET } from "./framing";
+import { clipFor, drawMood, type ClipRef, type Direction, type MoodCommand, type MoodSpec, type ModelSpec } from "./model";
+
+export type Box = { x: number; y: number; width: number; height: number };
+
+export type LifeState =
+  | { kind: "ground"; mood: MoodSpec; dir: Direction; until: number }
+  | { kind: "fall"; vy: number }
+  | { kind: "carried" }
+  | { kind: "landed"; until: number };
+
+/** What the life reads each step; every value may change between steps (a resize, a settings change). */
+export type World = {
+  /** Where the character may be. The ground is the bottom edge. */
+  bounds: () => Box;
+  /** Edge of the character's square box. */
+  size: () => number;
+  /** The model's scale: speeds follow it, so the stride matches the walk cycle at every size. */
+  scale: () => number;
+  /** Lift above the bounds' bottom edge. */
+  bottom: () => number;
+  /** Which model this is: its moods, its clips. */
+  model: () => ModelSpec;
+  /** Which clips the loaded file has; a mood whose clip it lacks is never drawn. All, when not given. */
+  has?: (clip: string) => boolean;
+  /** How long a clip takes; a `landed` clip played once sets how long the landing lasts. */
+  clipSeconds?: (clip: string) => number | undefined;
+  /** How much of the box the model fills side to side, how far down its head is, and how far down its feet are; the defaults when not given. */
+  body?: () => number;
+  head?: () => number;
+  feet?: () => number;
+  /** What to do next on the ground; a weighted draw from the model's moods by default. */
+  nextCommand?: (model: ModelSpec) => MoodCommand;
+};
+
+export type Life = {
+  /** The box's top-left. */
+  readonly x: number;
+  readonly y: number;
+  readonly facing: Direction;
+  readonly state: LifeState;
+  /** The box's edge, as the world says. */
+  readonly size: number;
+  /** How much of the box the body fills side to side, how far down the head is, and how far down the feet are, as fractions of the box. */
+  readonly body: number;
+  readonly head: number;
+  readonly feet: number;
+  /** How far the last step moved it sideways (walking, riding); what a character on its head follows. */
+  readonly dx: number;
+  /** The character it stands on, when not on the ground. */
+  readonly standingOn: Life | undefined;
+  /** Where the box's top is when the character stands on the ground. */
+  groundY(): number;
+  /** Put the box's top-left here and let the character fall. */
+  spawn(x: number, y: number): void;
+  pickUp(): void;
+  /** While carried: the box's new top-left. */
+  carryTo(x: number, y: number): void;
+  /** Turn to face this way; walking and running set it themselves. */
+  face(dir: Direction): void;
+  /** Let go, moving at this vertical speed (units per second, positive is down); clamped to a throw. */
+  drop(vy: number): void;
+  /** Pushed sideways by another character, on the ground only; a walker pushed against its way turns around. The reply is how far it went (less than asked at a side edge). */
+  bump(dx: number): number;
+  /** Advance by `dt` seconds at time `now` (milliseconds, as `performance.now()`), among the other lives on this ground (heads to land on, backs to ride). */
+  step(now: number, dt: number, others?: readonly Life[]): void;
+  /** The clip for the current state, and its speed. */
+  animation(): ClipRef;
+  animationSpeed(): number;
+};
+
+export const GRAVITY = 2400;
+export const MAX_THROW = 800;
+const LANDED_MS = 1200; // the landing clip, when it loops
+const REST_AFTER_LANDING_MS = 800;
+/** How much of its box the character may hang past a side edge: the model does not fill the square. */
+const OVERHANG = 0.2;
+/** How much of its box a character's body fills side to side, until the model is measured: for bumping into other characters and standing on them. */
+export const BODY = 0.6;
+/** How far down its box the top of a character's head is, until the model is measured: where another character's feet rest. */
+export const HEAD = 0.25;
+export { FEET };
+const isStanding = (l: Life) => l.state.kind === "ground" || l.state.kind === "landed";
+
+export function createLife(world: World): Life {
+  const pickNext = world.nextCommand ?? ((model: ModelSpec) => drawMood(model, world.has));
+  const moving = (mood: MoodSpec) => (mood.speed ?? 0) > 0;
+  /** Standing still after a landing, before the first mood: the idle clip. */
+  const rest = (): MoodSpec => ({ name: "idle", clip: clipFor(world.model(), "idle").name, seconds: [0, 0] });
+  /** How long a landing lasts: the landed clip's length when it plays once, else a fixed moment. */
+  const landedMs = () => {
+    const clip = clipFor(world.model(), "landed");
+    const seconds = clip.once ? world.clipSeconds?.(clip.name) : undefined;
+    return seconds ? seconds * 1000 : LANDED_MS;
+  };
+  let x = 0;
+  let y = 0;
+  let dx = 0;
+  let facing: Direction = 1;
+  let state: LifeState = { kind: "fall", vy: 0 };
+  let on: Life | undefined;
+
+  const groundY = () => {
+    const b = world.bounds();
+    return b.y + b.height - world.size() - world.bottom();
+  };
+  const sideLimits = () => {
+    const b = world.bounds();
+    const size = world.size();
+    return { minX: b.x - size * OVERHANG, maxX: b.x + b.width - size * (1 - OVERHANG) };
+  };
+  const clampX = () => {
+    const { minX, maxX } = sideLimits();
+    x = Math.max(minX, Math.min(maxX, x));
+  };
+  const apply = (cmd: MoodCommand, now: number) => {
+    state = { kind: "ground", mood: cmd.mood, dir: cmd.dir, until: now + cmd.seconds * 1000 };
+    if (moving(cmd.mood)) facing = cmd.dir;
+  };
+  /**
+   * Where this character's box top rests: the ground, or the head of the highest
+   * standing character whose body is under this character's centre and whose head was
+   * not above the feet (at `feetBefore`) when the step began, so a fall
+   * never passes through a head and a character beside another never climbs it.
+   */
+  const floorAmong = (others: readonly Life[], feetBefore: number): { y: number; on: Life | undefined } => {
+    const size = world.size();
+    const cx = x + size / 2;
+    const feetOffset = size * self.feet; // the feet are drawn this far down the box
+    let best: { y: number; on: Life | undefined } = { y: groundY(), on: undefined };
+    for (const o of others) {
+      if (o === self || !isStanding(o)) continue;
+      if (cx < o.x + o.size * (0.5 - o.body / 2) || cx > o.x + o.size * (0.5 + o.body / 2)) continue;
+      const head = o.y + o.size * o.head;
+      if (head < feetBefore - 1) continue;
+      if (head - feetOffset < best.y) best = { y: head - feetOffset, on: o };
+    }
+    return best;
+  };
+  /** Standing: follow the floor; when it is gone (the support walked away or was picked up), fall. The reply is whether the character still stands. */
+  const stand = (others: readonly Life[], feetBefore: number): boolean => {
+    const floor = floorAmong(others, feetBefore);
+    if (floor.y > y + 1) {
+      state = { kind: "fall", vy: 0 };
+      on = undefined;
+      return false;
+    }
+    y = floor.y;
+    on = floor.on;
+    if (on) x += on.dx; // ride
+    return true;
+  };
+
+  const self: Life = {
+    get x() {
+      return x;
+    },
+    get y() {
+      return y;
+    },
+    get dx() {
+      return dx;
+    },
+    get facing() {
+      return facing;
+    },
+    get state() {
+      return state;
+    },
+    get size() {
+      return world.size();
+    },
+    get body() {
+      return world.body?.() ?? BODY;
+    },
+    get head() {
+      return world.head?.() ?? HEAD;
+    },
+    get feet() {
+      return world.feet?.() ?? FEET;
+    },
+    get standingOn() {
+      return on;
+    },
+    groundY,
+    spawn(nx, ny) {
+      x = nx;
+      y = ny;
+      clampX();
+      state = { kind: "fall", vy: 0 };
+      on = undefined;
+    },
+    pickUp() {
+      state = { kind: "carried" };
+      on = undefined;
+    },
+    carryTo(nx, ny) {
+      if (state.kind !== "carried") return;
+      x = nx;
+      y = ny;
+    },
+    face(dir) {
+      facing = dir;
+    },
+    drop(vy) {
+      if (state.kind !== "carried") return;
+      state = { kind: "fall", vy: Math.max(-MAX_THROW, Math.min(MAX_THROW, vy)) };
+    },
+    bump(dx) {
+      if (!isStanding(self)) return 0;
+      const from = x;
+      x += dx;
+      clampX();
+      if (state.kind === "ground" && moving(state.mood) && Math.sign(dx) === -state.dir) {
+        state = { ...state, dir: (-state.dir) as Direction };
+        facing = state.dir;
+      }
+      return x - from;
+    },
+    step(now, dt, others = []) {
+      const xBefore = x;
+      const feetBefore = y + world.size() * self.feet;
+      switch (state.kind) {
+        case "ground": {
+          if (!stand(others, feetBefore)) break;
+          if (now >= state.until) apply(pickNext(world.model()), now);
+          if (state.kind === "ground" && moving(state.mood)) {
+            x += state.dir * state.mood.speed! * world.scale() * dt;
+            const { minX, maxX } = sideLimits();
+            if (x < minX || x > maxX) {
+              clampX();
+              state = { ...state, dir: (-state.dir) as Direction };
+              facing = state.dir;
+            }
+          } else {
+            clampX(); // the bounds or the size may have changed under a standing character
+          }
+          break;
+        }
+        case "fall": {
+          state.vy += GRAVITY * dt;
+          y += state.vy * dt;
+          const floor = floorAmong(others, feetBefore);
+          if (y >= floor.y) {
+            y = floor.y;
+            on = floor.on;
+            clampX(); // dropped past a side edge: back inside
+            state = { kind: "landed", until: now + landedMs() };
+          }
+          break;
+        }
+        case "landed":
+          if (!stand(others, feetBefore)) break;
+          if (now >= state.until) state = { kind: "ground", mood: rest(), dir: facing, until: now + REST_AFTER_LANDING_MS };
+          break;
+        case "carried":
+          break;
+      }
+      dx = x - xBefore;
+    },
+    animation() {
+      switch (state.kind) {
+        case "ground":
+          return { name: state.mood.clip, once: false };
+        case "carried":
+          return clipFor(world.model(), "carried");
+        case "fall":
+          return clipFor(world.model(), "falling");
+        case "landed":
+          return clipFor(world.model(), "landed");
+      }
+    },
+    animationSpeed() {
+      return state.kind === "carried" ? 1.5 : 1;
+    },
+  };
+  return self;
+}
+
+/**
+ * Keeps characters standing at the same level (on the ground, or on the same head)
+ * from overlapping: any two whose bodies overlap are pushed apart by half
+ * the overlap each (one that cannot give way, at a side edge, leaves its
+ * half to the other), and a walker pushed against its way turns around. A
+ * character on another's head is not pushed off it; characters in the air or in hand
+ * pass freely. Passes until nothing moves, because a push can make a new
+ * overlap further along; a pile spreads out over a few of them.
+ */
+export function separate(lives: readonly Life[]): void {
+  const standing = lives.filter(isStanding);
+  if (standing.length < 2) return;
+  const sameLevel = (a: Life, b: Life) => Math.abs(a.y + a.size * a.feet - (b.y + b.size * b.feet)) < 0.5 * Math.min(a.size, b.size);
+  for (let pass = 0; pass < 32; pass++) {
+    standing.sort((a, b) => a.x + a.size / 2 - (b.x + b.size / 2));
+    let moved = 0;
+    for (let i = 0; i + 1 < standing.length; i++) {
+      for (let j = i + 1; j < standing.length; j++) {
+        const a = standing[i]!;
+        const b = standing[j]!;
+        if (!sameLevel(a, b)) continue;
+        const overlap = a.x + a.size * (0.5 + a.body / 2) - (b.x + b.size * (0.5 - b.body / 2));
+        if (overlap <= 0) continue;
+        const wentA = a.bump(-overlap / 2);
+        const wentB = b.bump(overlap + wentA);
+        if (wentB < overlap + wentA) a.bump(-(overlap + wentA - wentB)); // b was at its edge too: a takes what b could not
+        moved += Math.abs(wentA) + Math.abs(wentB);
+      }
+    }
+    if (moved < 1e-6) return;
+  }
+}

package/src/model.ts

@@ -0,0 +1,104 @@
+// What a character is made of, as data: which file, how to fit it, which clips
+// play for which states, and which moods it draws from on the ground. The
+// packs in src/packs are specs of this shape, one named export per model;
+// a page passes its own for any glTF with animations.
+
+export type Direction = -1 | 1;
+
+/** A clip in the model's file, by its animation-group name. */
+export type ClipSpec =
+  | string
+  | {
+      name: string;
+      /** Play through once rather than loop. A `landed` clip played once sets how long the landing lasts. */
+      once?: boolean;
+    };
+
+/** Something to do on the ground: a clip, for a while, with a weight in the draw and a speed when it moves. */
+export type MoodSpec = {
+  name: string;
+  clip: string;
+  /** How likely, against the other moods. 1 by default. */
+  weight?: number;
+  /** How long it lasts, drawn between these two, in seconds. */
+  seconds: [number, number];
+  /** Movement along the ground while it plays, in CSS pixels per second at scale 1; tuned to the clip's stride so the feet do not slide. None: stands still. */
+  speed?: number;
+};
+
+export type ModelSpec = {
+  /** For labels. */
+  name: string;
+  /** Where the glTF is fetched from: an imported file (`import url from "./robot.glb"`), so the build ships it, or any URL. */
+  url: string;
+  /**
+   * Where the textures the file references by relative path are fetched
+   * from, by that path: `{ "Textures/colormap.png": colormapUrl }`. A
+   * bundler renames files, so a texture beside the glTF is found only
+   * through this. Not needed for a glTF with its textures embedded.
+   */
+  textures?: Record<string, string>;
+  /** Fit the model to this height in scene units (the cube pets are about 1 to 1.4). None: as modelled. */
+  height?: number;
+  /** Which way the model faces as modelled. `+z` by default. */
+  forward?: "+z" | "-z" | "+x" | "-x";
+  clips: {
+    idle: ClipSpec;
+    /** While held by the pointer. `idle` when missing. */
+    carried?: ClipSpec;
+    /** While falling. `carried` when missing. */
+    falling?: ClipSpec;
+    /** Just after a landing. `idle` when missing. */
+    landed?: ClipSpec;
+  };
+  /** What it does on the ground. At least one; a mood whose clip the file lacks is dropped at load. */
+  moods: MoodSpec[];
+};
+
+export type Role = "idle" | "carried" | "falling" | "landed";
+export type ClipRef = { name: string; once: boolean };
+
+const asRef = (spec: ClipSpec): ClipRef => (typeof spec === "string" ? { name: spec, once: false } : { name: spec.name, once: spec.once ?? false });
+
+/** The clip for a state, with the fallbacks (falling → carried → idle, landed → idle). */
+export function clipFor(model: ModelSpec, role: Role): ClipRef {
+  const c = model.clips;
+  switch (role) {
+    case "idle":
+      return asRef(c.idle);
+    case "carried":
+      return asRef(c.carried ?? c.idle);
+    case "falling":
+      return asRef(c.falling ?? c.carried ?? c.idle);
+    case "landed":
+      return asRef(c.landed ?? c.idle);
+  }
+}
+
+/** Every clip name the model uses. */
+export const clipNames = (model: ModelSpec): string[] => [
+  ...new Set([...(["idle", "carried", "falling", "landed"] as const).map((r) => clipFor(model, r).name), ...model.moods.map((m) => m.clip)]),
+];
+
+export type MoodCommand = { mood: MoodSpec; dir: Direction; seconds: number };
+
+/** A weighted draw from the model's moods, with a direction and a length. `has` leaves out moods whose clip is not in the file. */
+export function drawMood(model: ModelSpec, has: (clip: string) => boolean = () => true): MoodCommand {
+  const moods = model.moods.filter((m) => has(m.clip));
+  const pool = moods.length ? moods : model.moods;
+  const total = pool.reduce((sum, m) => sum + (m.weight ?? 1), 0);
+  let r = Math.random() * total;
+  let mood = pool[pool.length - 1]!;
+  for (const m of pool) {
+    r -= m.weight ?? 1;
+    if (r < 0) {
+      mood = m;
+      break;
+    }
+  }
+  const [lo, hi] = mood.seconds;
+  return { mood, dir: Math.random() < 0.5 ? -1 : 1, seconds: lo + Math.random() * (hi - lo) };
+}
+
+/** The same model, by what it loads from. */
+export const sameModel = (a: ModelSpec, b: ModelSpec): boolean => a.url === b.url;

package/src/react.tsx

@@ -0,0 +1,41 @@
+// The character as a React component. It renders nothing itself: the canvas is
+// appended to `host` (or the body) outside React's tree, and removed on
+// unmount. Props after the first render reach the character through its handle.
+// `model` is compared by its URL, so an object literal in the render body does
+// not reload it.
+
+import { useEffect, useImperativeHandle, useRef, useState, type Ref } from "react";
+import { sameModel } from "./model";
+import { createCharacter, type CharacterHandle, type CharacterOptions } from "./character";
+
+export type CharacterProps = CharacterOptions & {
+  /** The running character, for `spawn`, `setModel`, `setSettings` and `position`. Null until the first effect has run. */
+  ref?: Ref<CharacterHandle>;
+};
+
+export function Character({ ref, model, scale, bottom, spawn, host, zIndex, onFault }: CharacterProps) {
+  const [handle, setHandle] = useState<CharacterHandle | null>(null);
+  // The latest of every prop, for the one-time creation below, so changing a prop does not re-create the character.
+  const latest = useRef({ model, scale, bottom, spawn, onFault });
+  latest.current = { model, scale, bottom, spawn, onFault };
+
+  useEffect(() => {
+    const created = createCharacter({ ...latest.current, host, zIndex, onFault: (m, e) => latest.current.onFault?.(m, e) ?? console.error(m, e ?? "") });
+    setHandle(created);
+    return () => {
+      created.dispose();
+      setHandle(null);
+    };
+  }, [host, zIndex]);
+
+  useEffect(() => {
+    if (handle && !sameModel(model, handle.model)) void handle.setModel(model);
+  }, [handle, model]);
+
+  useEffect(() => {
+    handle?.setSettings({ scale, bottom });
+  }, [handle, scale, bottom]);
+
+  useImperativeHandle(ref, () => handle as CharacterHandle, [handle]); // a RefObject's current is nullable; it is null until the character is up
+  return null;
+}

package/src/scene.ts

@@ -0,0 +1,226 @@
+// The picture: a Babylon.js scene on one canvas, with a level camera aimed so
+// the model's feet sit on the canvas's bottom edge at every scale, one model
+// at a time, fitted (centred, feet at zero, to the spec's height, turned to
+// face +z), its clips by name, and a triangle pick for "is the character under
+// this point".
+
+import "@babylonjs/loaders/glTF/2.0";
+import "@babylonjs/core/Culling/ray"; // scene.pick
+import type { AssetContainer } from "@babylonjs/core/assetContainer";
+import { TargetCamera } from "@babylonjs/core/Cameras/targetCamera";
+import { Engine } from "@babylonjs/core/Engines/engine";
+import { DirectionalLight } from "@babylonjs/core/Lights/directionalLight";
+import { HemisphericLight } from "@babylonjs/core/Lights/hemisphericLight";
+import { LoadAssetContainerAsync } from "@babylonjs/core/Loading/sceneLoader";
+import { Color3, Color4 } from "@babylonjs/core/Maths/math.color";
+import { Vector3 } from "@babylonjs/core/Maths/math.vector";
+import { TransformNode } from "@babylonjs/core/Meshes/transformNode";
+import { Scene } from "@babylonjs/core/scene";
+import { CAMERA_DISTANCE, CAMERA_FOV, FOOTPRINT_Z, proportionsOf, yawFor, type Bounds, type Proportions } from "./framing";
+import { clipFor, type ClipRef, type Direction, type ModelSpec } from "./model";
+
+export type ModelScene = {
+  /** Fit the canvas to a `size` CSS-pixel square showing the model at `scale`, feet on the bottom edge. */
+  resize(size: number, scale: number): void;
+  /** Load the model and show it in place of the current one, fitted as the spec says. A later call wins over an earlier one still loading. */
+  show(model: ModelSpec): Promise<void>;
+  /** Is this clip in the loaded file? */
+  has(clip: string): boolean;
+  /** How long one pass of the clip takes at speed 1. */
+  clipSeconds(clip: string): number | undefined;
+  /** The loaded model's box through the camera: how wide it is and how far down its head is, as fractions of the canvas. */
+  proportions(): Proportions | undefined;
+  play(clip: ClipRef, speed: number): void;
+  /** Turn toward this side; the turn is eased over the next frames. */
+  face(dir: Direction): void;
+  /** Draw a frame; `dt` in seconds, for the turn. */
+  render(dt: number): void;
+  /** Is any of the model's geometry under this point of the canvas (CSS pixels)? Triangle-accurate. */
+  solidAt(cssX: number, cssY: number): boolean;
+  dispose(): void;
+};
+
+const GROUND_MARGIN_PX = 2;
+/** The turn that makes a model face +z: rotation about y by θ takes +x to (cos θ, -sin θ), so +x needs -π/2 and -x needs π/2. */
+const forwardYaw = (forward: ModelSpec["forward"]): number => (forward === "-z" ? Math.PI : forward === "+x" ? -Math.PI / 2 : forward === "-x" ? Math.PI / 2 : 0);
+
+/** Throws when WebGL is not available: there is no character without it. */
+export function createModelScene(canvas: HTMLCanvasElement): ModelScene {
+  const engine = new Engine(canvas, true, { premultipliedAlpha: false, alpha: true }, true);
+  const scene = new Scene(engine);
+  // A scene attaches its own pointer handling to the canvas (a pick on every
+  // move, and the cursor reset to its default each time). The character does its own
+  // picking and sets its own cursor, so that goes.
+  scene.detachControl();
+  scene.clearColor = new Color4(0, 0, 0, 0);
+
+  const camera = new TargetCamera("camera", new Vector3(0, 0, -CAMERA_DISTANCE), scene);
+  camera.fov = CAMERA_FOV;
+  camera.minZ = 0.1;
+  const key = new DirectionalLight("key", new Vector3(-0.6, -1, 0.8), scene);
+  key.intensity = 1.6;
+  const fill = new HemisphericLight("fill", new Vector3(0, 1, 0), scene);
+  fill.intensity = 0.9;
+  fill.groundColor = new Color3(0.45, 0.42, 0.5);
+
+  const root = new TransformNode("character", scene); // the fitted model hangs here; its feet are at y = 0
+  let yaw = yawFor(1);
+  let yawTarget = yaw;
+  let scale = 1;
+
+  // The model's ground (y = 0 across its footprint) sits on the canvas's bottom
+  // edge. With a level camera a ground point at depth z projects to
+  // -height / ((distance + z) tan(fov / 2)) in clip space, so the camera
+  // height that puts the front of the footprint on the last pixel row is exact.
+  // The scale scales the model, the camera's distance and the canvas together,
+  // so the framing is the same at every size.
+  const aimAtGround = () => {
+    const margin = (2 * GROUND_MARGIN_PX) / engine.getRenderHeight();
+    const height = (1 - margin) * (CAMERA_DISTANCE - FOOTPRINT_Z) * scale * Math.tan(CAMERA_FOV / 2);
+    camera.position.set(0, height, -CAMERA_DISTANCE * scale);
+    camera.setTarget(new Vector3(0, height, 0));
+    root.scaling.setAll(scale);
+  };
+
+  let container: AssetContainer | undefined;
+  let mount: TransformNode | undefined;
+  let animations = new Map<string, AssetContainer["animationGroups"][number]>();
+  let playing: string | undefined;
+  let measured: Proportions | undefined;
+  let loadSeq = 0;
+
+  /**
+   * Every vertex of every mesh, in the space the nodes hang in now, posed on
+   * the first frame of `pose`: a model's bind pose is a T-pose with the arms
+   * out, twice as wide as the figure standing, and a skinned mesh's own
+   * vertices are that bind pose until they are run through its skeleton.
+   */
+  const measure = (loaded: AssetContainer, pose: AssetContainer["animationGroups"][number] | undefined): { bounds: Bounds; points: number[]; triangles: number[] } => {
+    if (pose) {
+      pose.start(true, 1);
+      pose.goToFrame(pose.from);
+    }
+    for (const node of loaded.transformNodes) node.computeWorldMatrix(true);
+    const min = { x: Infinity, y: Infinity, z: Infinity };
+    const max = { x: -Infinity, y: -Infinity, z: -Infinity };
+    const points: number[] = [];
+    const triangles: number[] = [];
+    const p = new Vector3();
+    for (const mesh of loaded.meshes) {
+      if (mesh.getTotalVertices() === 0) continue;
+      mesh.computeWorldMatrix(true);
+      if (mesh.skeleton) mesh.skeleton.prepare();
+      const data = mesh.getPositionData(!!mesh.skeleton, true);
+      if (!data) continue;
+      const world = mesh.getWorldMatrix();
+      const base = points.length / 3;
+      const indices = mesh.getIndices();
+      if (indices) for (const i of indices) triangles.push(base + i);
+      else for (let i = 0; i < data.length / 3; i++) triangles.push(base + i);
+      for (let i = 0; i + 2 < data.length; i += 3) {
+        Vector3.TransformCoordinatesFromFloatsToRef(data[i]!, data[i + 1]!, data[i + 2]!, world, p);
+        points.push(p.x, p.y, p.z);
+        min.x = Math.min(min.x, p.x);
+        min.y = Math.min(min.y, p.y);
+        min.z = Math.min(min.z, p.z);
+        max.x = Math.max(max.x, p.x);
+        max.y = Math.max(max.y, p.y);
+        max.z = Math.max(max.z, p.z);
+      }
+    }
+    return { bounds: { min, max }, points, triangles };
+  };
+
+  return {
+    resize(size, nextScale) {
+      scale = nextScale;
+      canvas.style.width = `${size}px`;
+      canvas.style.height = `${size}px`;
+      engine.resize();
+      aimAtGround();
+    },
+    async show(model) {
+      const seq = ++loadSeq;
+      // A texture the file references by relative path is fetched from the spec's URL for that path, when it has one.
+      const textures = Object.entries(model.textures ?? {});
+      const loaded = await LoadAssetContainerAsync(model.url, scene, {
+        pluginOptions: {
+          gltf: {
+            preprocessUrlAsync: async (url) => textures.find(([path]) => url.endsWith(path))?.[1] ?? url,
+          },
+        },
+      });
+      if (seq !== loadSeq) {
+        loaded.dispose(); // another model was asked for while this one loaded
+        return;
+      }
+      container?.dispose();
+      mount?.dispose();
+      container = loaded;
+      animations = new Map(loaded.animationGroups.map((g) => [g.name, g]));
+      for (const g of loaded.animationGroups) {
+        g.stop();
+        g.enableBlending = true;
+        g.blendingSpeed = 0.08;
+      }
+      loaded.addAllToScene(); // before any re-parenting: the container checks its hierarchy here
+      // Fit: as modelled, measure; then centre it, put its feet at y = 0 and
+      // scale it to the spec's height; then turn it to face +z; then hang it
+      // under the root, which carries the character's own turn and scale.
+      const fit = new TransformNode("fit", scene);
+      for (const node of loaded.rootNodes) node.parent = fit;
+      const pose = animations.get(clipFor(model, "idle").name);
+      const { bounds: as, points, triangles } = measure(loaded, pose);
+      pose?.stop();
+      const k = model.height ? model.height / (as.max.y - as.min.y) : 1;
+      const cx = (as.min.x + as.max.x) / 2;
+      const cz = (as.min.z + as.max.z) / 2;
+      fit.scaling.setAll(k);
+      fit.position.set(-cx * k, -as.min.y * k, -cz * k);
+      const turn = new TransformNode("turn", scene);
+      turn.rotation.y = forwardYaw(model.forward);
+      fit.parent = turn;
+      turn.parent = root;
+      mount = turn;
+      for (let i = 0; i + 2 < points.length; i += 3) {
+        points[i] = (points[i]! - cx) * k;
+        points[i + 1] = (points[i + 1]! - as.min.y) * k;
+        points[i + 2] = (points[i + 2]! - cz) * k;
+      }
+      measured = proportionsOf(points, triangles, yawFor(1) + turn.rotation.y);
+      playing = undefined;
+    },
+    has: (clip) => animations.has(clip),
+    clipSeconds(clip) {
+      const g = animations.get(clip);
+      if (!g) return undefined;
+      const fps = g.targetedAnimations[0]?.animation.framePerSecond ?? 60;
+      return (g.to - g.from) / fps;
+    },
+    proportions: () => measured,
+    play(clip, speed) {
+      if (clip.name === playing) return;
+      animations.get(playing ?? "")?.stop();
+      const g = animations.get(clip.name) ?? animations.values().next().value; // a clip the file lacks: the file's first
+      g?.start(!clip.once, speed);
+      playing = clip.name;
+    },
+    face(dir) {
+      yawTarget = yawFor(dir);
+    },
+    render(dt) {
+      yaw += (yawTarget - yaw) * Math.min(1, dt * 10);
+      root.rotation.y = yaw;
+      scene.render();
+    },
+    solidAt(cssX, cssY) {
+      return container !== undefined && scene.pick(cssX, cssY, undefined, false).hit;
+    },
+    dispose() {
+      loadSeq++;
+      container?.dispose();
+      scene.dispose();
+      engine.dispose();
+    },
+  };
+}

package/src/settings.ts

@@ -0,0 +1,27 @@
+// What a page can adjust on a character while it runs.
+
+export type CharacterSettings = {
+  /** Size of the character; 1 is the model's own size, 192 CSS pixels tall. The canvas scales with it. */
+  scale: number;
+  /** How far above the bottom edge of its bounds the character stands, in CSS pixels; negative sinks it below the edge. */
+  bottom: number;
+};
+
+export const DEFAULT_CHARACTER_SETTINGS: CharacterSettings = { scale: 1, bottom: 0 };
+export const SCALE_MIN = 0.25;
+export const SCALE_MAX = 8;
+export const BOTTOM_MIN = -2000;
+export const BOTTOM_MAX = 4000;
+
+/** A finite number kept in range, or the fallback. */
+export const clampNumber = (v: unknown, fallback: number, min: number, max: number): number =>
+  typeof v === "number" && Number.isFinite(v) ? Math.min(max, Math.max(min, v)) : fallback;
+
+/** Fills gaps with `current` (the defaults when not given) and keeps every value in range, whatever the source. */
+export function sanitizeCharacterSettings(input: unknown, current: CharacterSettings = DEFAULT_CHARACTER_SETTINGS): CharacterSettings {
+  const s = (typeof input === "object" && input !== null ? input : {}) as Partial<Record<keyof CharacterSettings, unknown>>;
+  return {
+    scale: Math.round(clampNumber(s.scale, current.scale, SCALE_MIN, SCALE_MAX) * 100) / 100,
+    bottom: Math.round(clampNumber(s.bottom, current.bottom, BOTTOM_MIN, BOTTOM_MAX)),
+  };
+}