@nano133/nanoterra 0.7.0 → 0.8.0

package/src/admin/panel/gameCard.ts

@@ -1,7 +1,7 @@
-// The "Game" card of /admin: two switches, "Players can play as their Nanoterra character" and "Players can sign in with Nanoterra", and one three-way
-// choice, "Friends list: Nanoterra / The game's own / Off". A press saves at once (POST {api}/game, behind the same admin guard as every admin call) and
-// the game reads the setting at run time, so the creator pushes and deploys nothing. The words are in ../switches.ts. The card changes ONLY these three
-// settings: never a look, a price or an order.
+// The "Game" card of /admin: two switches, "Players can play as their Nanoterra character" and "Players can sign in with Nanoterra", one three-way
+// choice, "Friends list: Nanoterra / The game's own / Off", and the switch "Allow Nanoterra emotes". A press saves at once (POST {api}/game, behind the
+// same admin guard as every admin call) and the game reads the setting at run time, so the creator pushes and deploys nothing. The words are in
+// ../switches.ts. The card changes ONLY these four settings: never a look, a price or an order.
 
 import { CHARACTER_NEEDS_SIGNIN, CHARACTER_SIGNIN_OFF, FRIENDS_CHOICES, FRIENDS_TITLE, REVIEW_LINK, REVIEW_NOTE, SWITCHES, pressOf, signinOn, stateOf, type Friends, type GameState, type SwitchId } from "../switches.js";
 import { ApiError, type Api } from "./api.js";
@@ -17,7 +17,7 @@ export function gameCard(api: Api, initial: GameState, defaultsFile = "the game'
   /** Under the character switch: it works only through sign-in, so it says so, and says what a player gets while sign-in is Off. */
   const needs = h("p", { class: "fine switch-needs" });
   const card = h("section", { class: "admin-card game-card", "aria-labelledby": "game-title" }, h("div", { class: "card-head" }, h("h2", { id: "game-title" }, "Game")));
-  card.append(h("p", { class: "fine card-intro" }, `Three choices about your game. A press saves at once: you push nothing and deploy nothing. They start from ${defaultsFile}, and a press here wins.`));
+  card.append(h("p", { class: "fine card-intro" }, `Four choices about your game. A press saves at once: you push nothing and deploy nothing. They start from ${defaultsFile}, and a press here wins.`));
   /** The friends choice: a radio group of three keys (arrow keys move between them, as a radio group does). */
   const friendsKeys = new Map<Friends, HTMLButtonElement>();
   const friendsNote = h("p", { class: "switch-note", id: "switch-friends-note" });
@@ -74,7 +74,8 @@ export function gameCard(api: Api, initial: GameState, defaultsFile = "the game'
     }
   };
 
-  for (const id of ["character", "signin"] as const) {
+  /** A switch's row: its title, the On/Off key, the sentence for its state and the save status. */
+  const switchRow = (id: SwitchId) => {
     const label = h("span", { class: "switch-title", id: `switch-${id}-label` }, SWITCHES[id].title);
     const button = h(
       "button",
@@ -87,9 +88,11 @@ export function gameCard(api: Api, initial: GameState, defaultsFile = "the game'
     button.addEventListener("click", () => void press(id));
     rows.set(id, { button, sentence, status });
     card.append(h("div", { class: "switch-row" }, h("div", { class: "switch-head" }, label, button), sentence, id === "character" ? needs : null, status));
-    // The sign-in word is part of the listing file: Nanoterra's review decides what Nanoterra shows. This page cannot see that review.
-    if (id === "signin") card.append(h("p", { class: "fine switch-review" }, REVIEW_NOTE, " ", h("a", { href: REVIEW_LINK, target: "_blank", rel: "noopener noreferrer" }, "Open the launch page")));
-  }
+  };
+  switchRow("character");
+  switchRow("signin");
+  // The sign-in word is part of the listing file: Nanoterra's review decides what Nanoterra shows. This page cannot see that review.
+  card.append(h("p", { class: "fine switch-review" }, REVIEW_NOTE, " ", h("a", { href: REVIEW_LINK, target: "_blank", rel: "noopener noreferrer" }, "Open the launch page")));
 
   const order = Object.keys(FRIENDS_CHOICES) as Friends[];
   const group = h("div", { class: "seg friends-choice", role: "radiogroup", "aria-labelledby": "switch-friends-label", "aria-describedby": "switch-friends-note" });
@@ -108,6 +111,7 @@ export function gameCard(api: Api, initial: GameState, defaultsFile = "the game'
     group.append(key);
   }
   card.append(h("div", { class: "switch-row friends-row" }, h("div", { class: "switch-head" }, h("span", { class: "switch-title", id: "switch-friends-label" }, FRIENDS_TITLE), group), friendsNote, friendsStatus));
+  switchRow("emotes");
   draw();
   return card;
 }

package/src/admin/panel/icons.ts

@@ -31,7 +31,10 @@ const SHAPES = {
   sun: [["circle", { cx: 12, cy: 12, r: 4 }], ["path", { d: "M12 2.5v2.2M12 19.3v2.2M2.5 12h2.2M19.3 12h2.2M5.3 5.3l1.6 1.6M17.1 17.1l1.6 1.6M5.3 18.7l1.6-1.6M17.1 6.9l1.6-1.6" }]],
   moon: [["path", { d: "M20 14.5A8.5 8.5 0 1 1 9.5 4a6.8 6.8 0 0 0 10.5 10.5Z" }]],
   device: [["circle", { cx: 12, cy: 12, r: 8.5 }], ["path", { d: "M12 3.5a8.5 8.5 0 0 1 0 17Z", fill: "currentColor" }]],
+  // A gear of 8 teeth (the options key): the settings icon above reads as a sun at 20 px.
+  gear: [["path", { d: "M19.23 9.65 21.77 9.86V14.14L19.23 14.35 18.77 15.45 20.42 17.39 17.39 20.42 15.45 18.77 14.35 19.23 14.14 21.77H9.86L9.65 19.23 8.55 18.77 6.61 20.42 3.58 17.39 5.23 15.45 4.77 14.35 2.23 14.14V9.86L4.77 9.65 5.23 8.55 3.58 6.61 6.61 3.58 8.55 5.23 9.65 4.77 9.86 2.23H14.14L14.35 4.77 15.45 5.23 17.39 3.58 20.42 6.61 18.77 8.55Z" }], ["circle", { cx: 12, cy: 12, r: 3.2 }]],
   sparkle: [["path", { d: "M12 3v4M12 17v4M3 12h4M17 12h4M6 6l2.5 2.5M15.5 15.5 18 18M6 18l2.5-2.5M15.5 8.5 18 6" }]],
+  smile: [["circle", { cx: 12, cy: 12, r: 9 }], ["path", { d: "M8.2 14.2a4.6 4.6 0 0 0 7.6 0" }], ["path", { d: "M9 9.6h.01M15 9.6h.01", "stroke-width": 2.6 }]],
 } satisfies Record<string, Shape[]>;
 
 export type IconName = keyof typeof SHAPES;

package/src/admin/panel/overview.ts

@@ -47,7 +47,7 @@ export function overviewView(looks: readonly Look[], colourOf: (lookId: string)
   const linkKey = (words: string, to: () => void) => h("button", { class: "btn btn-small btn-quiet link-key", type: "button", onclick: to }, words, h("span", { "aria-hidden": "true" }, "→"));
 
   function drawGame() {
-    const rows = (["character", "signin"] as const).map((id) => {
+    const rows = (["character", "signin", "emotes"] as const).map((id) => {
       const on = game ? stateOf(id, game) : null;
       return h("li", {}, h("span", {}, SWITCHES[id].title), on === null ? h("span", { class: "pill" }, "Unknown") : h("span", { class: `pill ${on ? "pill-on" : "pill-off"}` }, on ? "On" : "Off"));
     });

package/src/admin/store.ts

@@ -48,13 +48,13 @@ export type AdminLogin = { at: number; country: string | null; browser: string }
 export const ADMIN_LOGINS_SHOWN = 10;
 
 /**
- * The game's database, as the handler needs it. An adapter writes ONLY what these calls say: the three settings and, when the game turns it on, the deletion of the admin sessions
+ * The game's database, as the handler needs it. An adapter writes ONLY what these calls say: the four settings and, when the game turns it on, the deletion of the admin sessions
  * (`signOutEverywhere`). Nothing else.
  * (There is no call that writes a look, a price or an order: the Shelf gives text to copy, and a change of looks is a change of the repository.)
  */
 export interface AdminStore {
   /** The settings that /admin has saved. A value that is not a known word is ignored by the handler, so an adapter returns what it holds. */
-  readSettings(): Promise<{ character?: unknown; signin?: unknown; friends?: unknown }>;
+  readSettings(): Promise<{ character?: unknown; signin?: unknown; friends?: unknown; emotes?: unknown }>;
   /** Saves a checked patch: all of it or none of it. */
   saveSettings(patch: GamePatch, now: number): Promise<void>;
   summary(now: number): Promise<StoreSummary>;

package/src/admin/switches.ts

@@ -1,5 +1,5 @@
 // The switches of the "Game" card in /admin, and the words that say what each does. The handler checks a press with `parsePatch`; the panel
-// draws the card from `SWITCHES` and `FRIENDS_CHOICES`. A switch changes ONLY these three settings; never a look, a price or an order.
+// draws the card from `SWITCHES` and `FRIENDS_CHOICES`. A switch changes ONLY these four settings; never a look, a price or an order.
 
 /** Which character the player is: Nanoterra's island character (the one the player has there) or the game's own. */
 export type Character = "nanoterra" | "own";
@@ -10,46 +10,54 @@ export type Signin = "exchange" | "ticket" | "none";
  * A three-way choice, not an On/Off switch.
  */
 export type Friends = "nanoterra" | "own" | "off";
-/** The game's own words for the switches. `friends` may be left out: it is "nanoterra" then (on by default). */
-export type GameSettings = { character: Character; signin: Signin; friends?: Friends };
+/** Whether the game shows Nanoterra's emotes ("@nano133/nanoterra/emotes"): the wheel's Nanoterra emotes and the other players' on their characters. Off leaves the game's own emotes. */
+export type Emotes = "on" | "off";
+/** The game's own words for the switches. `friends` and `emotes` may be left out: "nanoterra" and "on" then (on by default). */
+export type GameSettings = { character: Character; signin: Signin; friends?: Friends; emotes?: Emotes };
 /** What a press can set: sign-in is on ("exchange": a game with a server) or off ("none"). */
-export type GamePatch = { character?: Character; signin?: "exchange" | "none"; friends?: Friends };
+export type GamePatch = { character?: Character; signin?: "exchange" | "none"; friends?: Friends; emotes?: Emotes };
 /** The settings as they are now, and which ones /admin has set (the others still have the game's default). */
-export type GameState = { character: Character; signin: Signin; friends: Friends; fromAdmin: { character: boolean; signin: boolean; friends: boolean } };
+export type GameState = { character: Character; signin: Signin; friends: Friends; emotes: Emotes; fromAdmin: { character: boolean; signin: boolean; friends: boolean; emotes: boolean } };
 
 export const isCharacter = (v: unknown): v is Character => v === "nanoterra" || v === "own";
 export const isSigninChoice = (v: unknown): v is "exchange" | "none" => v === "exchange" || v === "none";
 export const isSignin = (v: unknown): v is Signin => v === "exchange" || v === "ticket" || v === "none";
 export const isFriends = (v: unknown): v is Friends => v === "nanoterra" || v === "own" || v === "off";
+export const isEmotes = (v: unknown): v is Emotes => v === "on" || v === "off";
 /** The friends list a game shows while neither its own words nor /admin say: Nanoterra's. */
 export const DEFAULT_FRIENDS: Friends = "nanoterra";
+/** Nanoterra's emotes are on while neither the game's own words nor /admin say. */
+export const DEFAULT_EMOTES: Emotes = "on";
 /** The sign-in switch is on for any way but "none". */
 export const signinOn = (s: Signin): boolean => s !== "none";
 
 /** A request body for a press: only the two known words, at least one. Anything else is refused, with the reason in words. */
 export function parsePatch(body: unknown): { ok: true; patch: GamePatch } | { ok: false; error: string } {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: 'Send an object with "character", "signin" or "friends".' };
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: 'Send an object with "character", "signin", "friends" or "emotes".' };
   const patch: GamePatch = {};
   for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
     if (key === "character" && isCharacter(value)) patch.character = value;
     else if (key === "signin" && isSigninChoice(value)) patch.signin = value;
     else if (key === "friends" && isFriends(value)) patch.friends = value;
+    else if (key === "emotes" && isEmotes(value)) patch.emotes = value;
     else if (key === "friends") return { ok: false, error: '"friends" must be "nanoterra", "own" or "off".' };
+    else if (key === "emotes") return { ok: false, error: '"emotes" must be "on" or "off".' };
     else if (key === "character") return { ok: false, error: '"character" must be "nanoterra" or "own".' };
     else if (key === "signin") return { ok: false, error: '"signin" must be "exchange" or "none".' };
     else return { ok: false, error: `"${key}" is not a game switch.` };
   }
-  if (!Object.keys(patch).length) return { ok: false, error: 'Send "character", "signin" or "friends".' };
+  if (!Object.keys(patch).length) return { ok: false, error: 'Send "character", "signin", "friends" or "emotes".' };
   return { ok: true, patch };
 }
 
 /** The settings from what the store kept and the game's defaults. A stored value that is not one of the known words is ignored. */
-export function mergeSettings(stored: { character?: unknown; signin?: unknown; friends?: unknown }, defaults: GameSettings): GameState {
+export function mergeSettings(stored: { character?: unknown; signin?: unknown; friends?: unknown; emotes?: unknown }, defaults: GameSettings): GameState {
   return {
     character: isCharacter(stored.character) ? stored.character : defaults.character,
     signin: isSigninChoice(stored.signin) ? stored.signin : defaults.signin,
     friends: isFriends(stored.friends) ? stored.friends : isFriends(defaults.friends) ? defaults.friends : DEFAULT_FRIENDS,
-    fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin), friends: isFriends(stored.friends) },
+    emotes: isEmotes(stored.emotes) ? stored.emotes : isEmotes(defaults.emotes) ? defaults.emotes : DEFAULT_EMOTES,
+    fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin), friends: isFriends(stored.friends), emotes: isEmotes(stored.emotes) },
   };
 }
 
@@ -68,7 +76,7 @@ export const FRIENDS_CHOICES: Record<Friends, { name: string; note: string }> =
 };
 
 /** One switch of the card: its title, and one plain sentence for each state. */
-export type SwitchId = "character" | "signin";
+export type SwitchId = "character" | "signin" | "emotes";
 export const SWITCHES: Record<SwitchId, { title: string; on: string; off: string }> = {
   character: {
     title: "Players can play as their Nanoterra character",
@@ -80,6 +88,11 @@ export const SWITCHES: Record<SwitchId, { title: string; on: string; off: string
     on: "On: this game's listing file says players can sign in with Nanoterra, and the game accepts that sign-in.",
     off: "Off: the listing file says no sign-in, and the game refuses it: a link made before still signs nobody in.",
   },
+  emotes: {
+    title: "Allow Nanoterra emotes",
+    on: "On: players can play Nanoterra's emotes (Wave, Dance, Sit and more) from the Emotes wheel, and see the other players' emotes.",
+    off: "Off: the game shows no Nanoterra emote. The game's own emotes, if it has any, stay on the wheel.",
+  },
 };
 
 /**
@@ -96,5 +109,9 @@ export const REVIEW_NOTE =
 export const REVIEW_LINK = "https://nano133.com/build/nanoterra/launch";
 
 /** The state of a switch from the settings, and the patch that a press sends (the other state). */
-export const stateOf = (id: SwitchId, s: GameSettings): boolean => (id === "character" ? s.character === "nanoterra" : signinOn(s.signin));
-export const pressOf = (id: SwitchId, s: GameSettings): GamePatch => (id === "character" ? { character: s.character === "nanoterra" ? "own" : "nanoterra" } : { signin: signinOn(s.signin) ? "none" : "exchange" });
+export const stateOf = (id: SwitchId, s: GameSettings): boolean => (id === "character" ? s.character === "nanoterra" : id === "emotes" ? (s.emotes ?? DEFAULT_EMOTES) === "on" : signinOn(s.signin));
+export function pressOf(id: SwitchId, s: GameSettings): GamePatch {
+  if (id === "character") return { character: s.character === "nanoterra" ? "own" : "nanoterra" };
+  if (id === "emotes") return { emotes: stateOf("emotes", s) ? "off" : "on" };
+  return { signin: signinOn(s.signin) ? "none" : "exchange" };
+}

package/src/character/create.ts

@@ -2,6 +2,7 @@ import * as THREE from "three";
 import { assemble, type Assembled } from "./assemble.js";
 import { BASE_SPECS } from "./bases/index.js";
 import { HEIGHTS } from "./lists.js";
+import { poseLayerOf } from "./layer.js";
 import { assertLook, recordProblem, type Look } from "./look.js";
 import { buildWith, paintCharacter, type Made } from "./make.js";
 import { makePose, MAX_DT, type Motion } from "./pose.js";
@@ -202,7 +203,7 @@ export function createCharacter(options: CharacterOptions = {}): Character {
     r.a.skeleton.dispose();
   };
 
-  return {
+  const self: Character = {
     object,
     get record() {
       return frozen(record);
@@ -223,7 +224,9 @@ export function createCharacter(options: CharacterOptions = {}): Character {
       if (!(step > 0)) return;
       time += step;
       rig.pose.step(step, motion ?? {}, reducedMotion);
-      // The body's own moving parts (a tail, wings, long hair) follow what the pose did.
+      // A layer over the pose (an emote: layer.ts), then the body's own moving parts (a tail, wings, long hair) follow what the pose did.
+      const state = rig.pose.state;
+      poseLayerOf(self)?.(rig.a.bones as Record<BoneName, THREE.Bone>, { dt: step, speed: state.speed, airborne: state.air, reducedMotion });
       rig.a.mover?.(step, time, rig.pose.state.speed, reducedMotion);
     },
     wave() {
@@ -282,4 +285,5 @@ export function createCharacter(options: CharacterOptions = {}): Character {
       ramp.dispose();
     },
   };
+  return self;
 }

package/src/character/layer.ts

@@ -0,0 +1,21 @@
+import type * as THREE from "three";
+import type { BoneName } from "./skeleton.js";
+
+// A layer over the pose: one function a character may carry, which its `update` calls each frame after the walk is solved and before the character's
+// own bones (a tail, wings, long hair) follow, so they follow the layer's turns too. The emotes (`@nano133/nanoterra/emotes/player`) are such a layer:
+// a clip blends over the bones the solver just turned. It is kept beside the character, not on it, so `Character` stays as it is. One layer a character.
+
+/** What the pose did this frame: the step it took (s), its eased speed (m/s), whether it is in the air, and the reduced-motion setting. */
+export type PoseFrame = { dt: number; speed: number; airborne: boolean; reducedMotion: boolean };
+export type PoseLayer = (bones: Readonly<Record<BoneName, THREE.Bone>>, frame: PoseFrame) => void;
+
+const layers = new WeakMap<object, PoseLayer>();
+
+/** Gives a character its layer (null takes it off). */
+export function setPoseLayer(character: object, layer: PoseLayer | null): void {
+  if (layer) layers.set(character, layer);
+  else layers.delete(character);
+}
+
+/** The character's layer, if it has one. */
+export const poseLayerOf = (character: object): PoseLayer | undefined => layers.get(character);

package/src/emotes/clip.ts

@@ -0,0 +1,204 @@
+import * as THREE from "three";
+import { BONES } from "../character/skeleton.js";
+
+// Plays an emote's clip on a character, over the pose the solver gave its bones this frame: nano133.com's app/island/character/emotes/play.ts, with
+// the same numbers. A clip (./clips.ts) holds each bone's turn from its parent for every frame, 30 a second, in the character's own space: Blender's
+// IK and all is already in them, so nothing here solves. A clip fades in, and out at its end; a "full" clip (the whole body) stops when the character
+// moves, jumps or swims, an "upper" one (the spine, the arms and the head) plays over the walk and stops only in the water. A loop plays until it
+// stops; with reduced motion an emote holds its one picture (the clip's `hold` frame) instead. The clips load on the first emote (one chunk of their
+// own), not with the game.
+//
+// The island measures a clip's age on the page's clock; here it is the sum of the steps the character's `update` took, so a paused game pauses its
+// emotes too, and a test steps them exactly.
+
+/** One clip as the file holds it: whole numbers, each bone's first frame then each frame's change (`q`: the bone's index, then 4 numbers a frame). */
+export type RawClip = { n: number; loop: boolean; from?: number; kind: "full" | "upper"; hold: number; label: string; q: number[][]; p?: number[] };
+export type RawClips = { v: number; fps: number; bones: string[]; clips: Record<string, RawClip> };
+
+export type Clip = {
+  /** Frames (a loop's last frame is its first, so it is not among them). */
+  n: number;
+  loop: boolean;
+  /** The frame a loop goes back to (0: the whole clip loops; more: an opening that plays once, then the loop). */
+  from: number;
+  kind: "full" | "upper";
+  hold: number;
+  /** A one-shot's length in seconds. */
+  seconds: number;
+  turns: { bone: string; q: Float32Array }[];
+  /** The hips' place from their rest place, three numbers a frame (or one place), or null. */
+  hips: Float32Array | null;
+};
+
+const FPS = 30;
+const Q = 10000;
+/** Fades, in seconds: in at the start, out at a one-shot's end, and out when a move stops it. */
+export const FADE_IN = 0.12;
+export const FADE_END = 0.22;
+export const FADE_STOP = 0.18;
+const HIPS_REST = (() => {
+  const b = BONES.find((x) => x[0] === "hips")!;
+  return new THREE.Vector3(b[2], b[3], b[4]);
+})();
+
+let clips: Map<string, Clip> | null = null;
+let loading: Promise<void> | null = null;
+
+/**
+ * Loads the clips, once (about 84 kB, 19 kB gzipped). Call it when the wheel first opens; a clip that plays before calls it too, and starts when they
+ * arrive. A failed load (the network) may be tried again.
+ */
+export function loadEmotes(): Promise<void> {
+  loading ??= import("./clips.js").then(
+    (m) => {
+      clips = decodeClips(m.default);
+    },
+    (e: unknown) => {
+      loading = null;
+      throw e;
+    },
+  );
+  return loading;
+}
+
+/** True once the clips are loaded. */
+export const emotesLoaded = (): boolean => clips !== null;
+/** A loaded clip by its id, or null. */
+export const emoteClip = (id: string): Clip | null => clips?.get(id) ?? null;
+
+/** Whole numbers, the first frame then each frame's change, back to the frames (`width` numbers each); one frame when it never changes. */
+function unpack(vals: readonly number[], width: number): Float32Array {
+  const out = new Float32Array(vals.length);
+  const acc = new Array<number>(width).fill(0);
+  for (let i = 0; i < vals.length; i++) {
+    acc[i % width] += vals[i];
+    out[i] = acc[i % width] / Q;
+  }
+  return out;
+}
+
+export function decodeClips(raw: RawClips): Map<string, Clip> {
+  const out = new Map<string, Clip>();
+  for (const [id, c] of Object.entries(raw.clips)) {
+    const turns = c.q.map(([bone, ...vals]) => {
+      const q = unpack(vals, 4);
+      // The whole numbers round each turn a little: back to unit length.
+      for (let i = 0; i < q.length; i += 4) {
+        const l = Math.hypot(q[i], q[i + 1], q[i + 2], q[i + 3]) || 1;
+        for (let k = 0; k < 4; k++) q[i + k] /= l;
+      }
+      return { bone: raw.bones[bone], q };
+    });
+    out.set(id, { n: c.n, loop: c.loop, from: c.from ?? 0, kind: c.kind, hold: c.hold, seconds: (c.n - 1) / (raw.fps || FPS), turns, hips: c.p ? unpack(c.p, 3) : null });
+  }
+  return out;
+}
+
+/** What one character keeps between frames: the clip on show, its age (s), when a move or `stop` stopped it (its age then, or -1), and why it ended. */
+export type ClipRun = { id: string | null; age: number; stopAge: number; stopWhy: "move" | "stop"; waiting: boolean; ended: "end" | "move" | "stop" | null };
+export const newRun = (): ClipRun => ({ id: null, age: 0, stopAge: -1, stopWhy: "move", waiting: false, ended: null });
+
+/**
+ * Starts a clip on a run, `age` seconds in (a remote player's emote that began a little before). A loop already on show, and not stopping, goes on
+ * through its own repeat: a player's loop is sent again for those who come later.
+ */
+export function startClip(run: ClipRun, id: string, age = 0): void {
+  const now = run.id ? clips?.get(run.id) : null;
+  if (run.id === id && now && now.loop && run.stopAge < 0) return;
+  run.id = id;
+  run.age = Math.max(0, age);
+  run.stopAge = -1;
+  run.waiting = !clips;
+  run.ended = null;
+}
+
+/** Stops the clip on show with its fade (`stop` from the game). */
+export function stopClip(run: ClipRun): void {
+  if (run.id && run.stopAge < 0) {
+    run.stopAge = run.age;
+    run.stopWhy = "stop";
+  }
+}
+
+export type ClipFrame = {
+  /** The step (s). */
+  dt: number;
+  moving: boolean;
+  air: boolean;
+  swim: boolean;
+  calm: boolean;
+};
+
+const qa = new THREE.Quaternion();
+const qb = new THREE.Quaternion();
+const va = new THREE.Vector3();
+const vb = new THREE.Vector3();
+const smooth = (w: number) => w * w * (3 - 2 * w);
+
+/** Where a clip is at `age` seconds: the frame before, the frame after and how far between. */
+function frameAt(c: Clip, age: number, calm: boolean): [number, number, number] {
+  if (calm) return [c.hold, c.hold, 0];
+  let f = age * FPS;
+  if (c.loop && f >= c.n) f = c.from + ((f - c.from) % (c.n - c.from));
+  else f = Math.min(f, c.n - 1);
+  const i0 = Math.floor(f);
+  const i1 = i0 + 1 >= c.n ? (c.loop ? c.from : c.n - 1) : i0 + 1;
+  return [i0, i1, f - i0];
+}
+
+/**
+ * One frame of the clip on a character: `bones` by name, already posed by the solver. Returns whether the clip showed. When it ends (its end, a move,
+ * the water or `stopClip`), `run.id` goes back to null and `run.ended` says why.
+ */
+export function stepClip(run: ClipRun, bones: Readonly<Record<string, THREE.Bone>>, o: ClipFrame): boolean {
+  if (!run.id) return false;
+  const clip = clips?.get(run.id);
+  if (!clip) {
+    // Not loaded yet (or not a clip): it starts when the clips arrive, from its first frame.
+    if (!clips) {
+      run.waiting = true;
+      void loadEmotes().catch(() => undefined);
+    } else run.id = null;
+    return false;
+  }
+  if (run.waiting) {
+    run.waiting = false;
+    run.age = 0;
+  } else run.age += o.dt;
+  const age = run.age;
+  const stop = o.swim || (clip.kind === "full" && (o.moving || o.air));
+  if (stop && run.stopAge < 0) {
+    run.stopAge = age;
+    run.stopWhy = "move";
+  }
+  let w = Math.min(1, age / FADE_IN);
+  if (!clip.loop) w = Math.min(w, (clip.seconds - age) / FADE_END);
+  if (run.stopAge >= 0) w = Math.min(w, 1 - (age - run.stopAge) / FADE_STOP);
+  if (w <= 0) {
+    if (run.stopAge >= 0 || (!clip.loop && age >= clip.seconds)) {
+      run.ended = run.stopAge >= 0 ? run.stopWhy : "end";
+      run.id = null;
+    }
+    return false;
+  }
+  w = smooth(Math.min(1, w));
+  const [i0, i1, t] = frameAt(clip, age, o.calm);
+  for (const tr of clip.turns) {
+    const bone = bones[tr.bone];
+    if (!bone) continue;
+    if (tr.q.length === 4) qa.fromArray(tr.q, 0);
+    else {
+      qa.fromArray(tr.q, i0 * 4);
+      qb.fromArray(tr.q, i1 * 4);
+      qa.slerp(qb, t);
+    }
+    bone.quaternion.slerp(qa, w);
+  }
+  const hips = bones.hips;
+  if (clip.hips && hips) {
+    if (clip.hips.length === 3) va.fromArray(clip.hips, 0);
+    else va.fromArray(clip.hips, i0 * 3).lerp(vb.fromArray(clip.hips, i1 * 3), t);
+    hips.position.lerp(va.add(HIPS_REST), w);
+  }
+  return true;
+}