@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/penguin-run/PenguinModel.ts

@@ -0,0 +1,712 @@
+// A rigged 3D cartoon penguin for the Nayan engine, with its own animation library. The engine draws
+// glTF meshes but not skins, so the rig is built from attached entities instead of bones: a root on
+// the ground (moves and turns the whole bird), a pelvis (waddle, lean, crouch), the one-piece body
+// (PenguinMeshes.ts: head, face, eyes, beak, belly, tufts, tail and scarf in one mesh), two flippers hinged at the
+// shoulders and two feet. Every clip runs as keyframes in the engine's Rust core: no per-frame JS.
+//
+//   const p = spawnPenguin(world, [0, 0, 0], 1.6);
+//   playPenguin(world, p, 'walk');            // loops until another clip
+//   await playPenguin(world, p, 'punch');     // one-shots resolve when done
+import { type Color, type Entity, type Keyframe, type Quat, quat, type Vec3, type World } from '@nayan-ui/engine';
+import { bodyMesh, flipperMesh, footMesh } from './PenguinMeshes';
+
+export type PenguinAnim = 'idle' | 'walk' | 'run' | 'punch' | 'jab' | 'jump' | 'slide' | 'hit' | 'dance' | 'dead';
+
+/** Clips that loop until another one starts. */
+export const LOOPING: ReadonlySet<PenguinAnim> = new Set(['idle', 'walk', 'run', 'dance']);
+
+/** How long each one-shot clip runs, in seconds. */
+export const CLIP_TIME: Record<PenguinAnim, number> = {
+  idle: 5,
+  walk: 0.9,
+  run: 0.44,
+  punch: 0.52,
+  jab: 0.4,
+  jump: 0.95,
+  slide: 1.35,
+  hit: 0.75,
+  dance: 1.1,
+  dead: 1.7
+};
+
+export type Penguin = {
+  root: Entity;
+  pelvis: Entity;
+  body: Entity;
+  flipperL: Entity;
+  flipperR: Entity;
+  footL: Entity;
+  footR: Entity;
+  /** Where the root stands (ground x), kept in step with root moves. */
+  x: number;
+  /** The yaw the root faces, radians (0 looks at the camera). */
+  yaw: number;
+  anim: PenguinAnim | null;
+};
+
+// ── Rest pose (model units: the bird is about 1 tall) ────────────────
+
+const PELVIS_Y = 0.39;
+const BODY_SCALE: Vec3 = [0.94, 1.15, 0.94];
+const SHOULDER: Vec3 = [0.246, 0.18, 0.0];
+const FOOT: Vec3 = [0.12, 0.0, 0.06];
+const IDENTITY: Quat = [0, 0, 0, 1];
+
+/** Left flipper: positive `out` swings it away from the body (around z), `fwd` forward (around x, negative is forward). */
+const flipL = (fwd: number, out: number, twist = 0) => quat.fromEuler(fwd, twist, -out);
+const flipR = (fwd: number, out: number, twist = 0) => quat.fromEuler(fwd, -twist, out);
+const REST_L = flipL(0, 0.14);
+const REST_R = flipR(0, 0.14);
+const pelvisAt = (y = 0, z = 0): Vec3 => [0, PELVIS_Y + y, z];
+const footLAt = (y = 0, z = 0): Vec3 => [-FOOT[0], FOOT[1] + y, FOOT[2] + z];
+const footRAt = (y = 0, z = 0): Vec3 => [FOOT[0], FOOT[1] + y, FOOT[2] + z];
+const FOOT_L_REST = quat.y(-0.18);
+const FOOT_R_REST = quat.y(0.18);
+
+/** Builds the meshes ahead of time (each is made once per app). */
+export function preparePenguin() {
+  bodyMesh();
+  flipperMesh(-1);
+  flipperMesh(1);
+  footMesh();
+}
+
+// ── Rig ───────────────────────────────────────────────────────────────
+
+/** Spawns a penguin standing at `position` (feet on the ground), `size` units tall, facing the camera. */
+export function spawnPenguin(world: World, position: Vec3, size = 1, tint: Color = [1, 1, 1, 1]): Penguin {
+  const root = world.spawn({ mesh: 'none', position, scale: size, pickable: false });
+  const pelvis = world.spawn({ mesh: 'none', parent: root, position: pelvisAt(), pickable: false });
+  const body = world.spawn({ mesh: bodyMesh(), parent: pelvis, position: [0, 0, 0], scale: BODY_SCALE, color: tint, pickable: false });
+  const flipperL = world.spawn({
+    mesh: flipperMesh(-1),
+    parent: pelvis,
+    position: [-SHOULDER[0], SHOULDER[1], SHOULDER[2]],
+    rotation: REST_L,
+    color: tint,
+    pickable: false
+  });
+  const flipperR = world.spawn({
+    mesh: flipperMesh(1),
+    parent: pelvis,
+    position: [SHOULDER[0], SHOULDER[1], SHOULDER[2]],
+    rotation: REST_R,
+    color: tint,
+    pickable: false
+  });
+  const footL = world.spawn({ mesh: footMesh(), parent: root, position: footLAt(), rotation: FOOT_L_REST, color: tint, pickable: false });
+  const footR = world.spawn({ mesh: footMesh(), parent: root, position: footRAt(), rotation: FOOT_R_REST, color: tint, pickable: false });
+  return { root, pelvis, body, flipperL, flipperR, footL, footR, x: position[0], yaw: 0, anim: null };
+}
+
+const parts = (p: Penguin) => [p.pelvis, p.flipperL, p.flipperR, p.footL, p.footR];
+
+/** Puts every limb back in its rest pose over `duration` seconds (0 snaps). */
+function toRest(world: World, p: Penguin, duration: number) {
+  for (const e of parts(p)) world.stopAnimation(e);
+  const rest: [Entity, Vec3, Quat][] = [
+    [p.pelvis, pelvisAt(), IDENTITY],
+    [p.flipperL, [-SHOULDER[0], SHOULDER[1], SHOULDER[2]], REST_L],
+    [p.flipperR, [SHOULDER[0], SHOULDER[1], SHOULDER[2]], REST_R],
+    [p.footL, footLAt(), FOOT_L_REST],
+    [p.footR, footRAt(), FOOT_R_REST]
+  ];
+  for (const [e, position, rotation] of rest) {
+    if (duration <= 0) world.set(e, { position, rotation, ...(e === p.pelvis && { scale: 1 }) });
+    else world.animate(e, { position, rotation, ...(e === p.pelvis && { scale: 1 }) }, { duration, easing: 'easeOut' });
+  }
+}
+
+/** Turns the whole bird to `yaw` (0 faces the camera, π/2 faces +x). */
+export function facePenguin(world: World, p: Penguin, yaw: number, duration = 0.12) {
+  p.yaw = yaw;
+  if (duration <= 0) world.set(p.root, { rotation: quat.y(yaw) });
+  else world.animate(p.root, { rotation: quat.y(yaw) }, { duration });
+}
+
+/** Walks, runs or slides the root to ground x over `duration` (the limbs play whatever clip is on). */
+export function movePenguin(world: World, p: Penguin, x: number, duration: number, easing: 'linear' | 'easeOut' | 'easeInOut' = 'linear') {
+  p.x = x;
+  return world.animate(p.root, { position: [x, 0, 0] }, { duration, easing });
+}
+
+/** Snaps the bird to ground x, upright and facing `yaw`, every limb at rest (a new run). */
+export function placePenguin(world: World, p: Penguin, x: number, yaw = 0) {
+  world.stopAnimation(p.root);
+  p.x = x;
+  world.set(p.root, { position: [x, 0, 0] });
+  facePenguin(world, p, yaw, 0);
+  toRest(world, p, 0);
+  p.anim = null;
+}
+
+const BLEND = 0.12;
+
+// Pose helpers for the clips: pelvis offset and lean, foot placement with toe pitch
+const hip = (x: number, y: number, z: number): Vec3 => [x, PELVIS_Y + y, z];
+const lean = (rx: number, ry: number, rz: number) => quat.fromEuler(rx, ry, rz);
+const footRot = (side: -1 | 1, pitch: number, yaw = 0) => quat.fromEuler(pitch, side * 0.18 + yaw, 0);
+const k = (at: number, frame: Omit<Keyframe, 'at'>): Keyframe => ({ ...frame, at });
+/** The jump's height (model units) through the clip: on the ground until take-off at 0.26, landing at 0.78. */
+const AIR: [number, number][] = [
+  [0, 0],
+  [0.26, 0],
+  [0.4, 0.72],
+  [0.52, 0.95],
+  [0.64, 0.72],
+  [0.78, 0],
+  [1, 0]
+];
+const airAt = (t: number) => {
+  for (let i = 1; i < AIR.length; i++) {
+    const [t1, h1] = AIR[i]!;
+    const [t0, h0] = AIR[i - 1]!;
+    if (t <= t1) return h0 + ((h1 - h0) * (t - t0)) / Math.max(1e-6, t1 - t0);
+  }
+  return 0;
+};
+
+/**
+ * Plays a clip. Looping clips (idle, walk, run, dance) run until the next call and resolve at once;
+ * one-shots resolve when they end. `speed` scales the clip's pace.
+ *
+ * Every clip is keyed for weight and timing rather than evenly: a beat of anticipation before each
+ * action, a fast action, overshoot and a settle after it; feet planted while the body shifts its
+ * weight over them; flippers trailing the body's moves (overlapping action); squash on landings and
+ * stretch on take-offs. Curves run through the keys smoothly.
+ */
+export function playPenguin(world: World, p: Penguin, anim: PenguinAnim, speed = 1): Promise<void> {
+  if (p.anim === anim && LOOPING.has(anim)) return Promise.resolve();
+  p.anim = anim;
+  toRest(world, p, BLEND);
+  const T = CLIP_TIME[anim] / speed;
+  const loop = { duration: T, repeat: 'forever' as const, delay: BLEND, easing: 'linear' as const, path: 'smooth' as const };
+  const once = { duration: T, delay: BLEND, easing: 'linear' as const, path: 'smooth' as const };
+  const a = (e: Entity, keys: Keyframe[], o: Parameters<World['animate']>[2]) => world.animate(e, keys, o);
+  const { pelvis, flipperL: fl, flipperR: fr, footL, footR } = p;
+
+  switch (anim) {
+    case 'idle': {
+      // A slow, alive stand: breathing, a glance left, a glance right, a flipper twitch, a weight shift
+      a(
+        pelvis,
+        [
+          k(0, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 }),
+          k(0.12, { position: hip(0, 0.012, 0), rotation: lean(-0.02, 0, 0), scale: [1.01, 1.03, 1.01] }),
+          k(0.26, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 }),
+          k(0.36, { position: hip(0.006, 0, 0), rotation: lean(0.04, 0.42, -0.04), scale: 1 }),
+          k(0.5, { position: hip(0.006, 0.01, 0), rotation: lean(0.02, 0.38, -0.04), scale: [1.01, 1.025, 1.01] }),
+          k(0.58, { position: hip(-0.006, 0, 0), rotation: lean(0.04, -0.36, 0.04), scale: 1 }),
+          k(0.72, { position: hip(-0.006, 0.01, 0), rotation: lean(0.02, -0.33, 0.04), scale: [1.01, 1.025, 1.01] }),
+          k(0.8, { position: hip(-0.012, 0, 0), rotation: lean(0, 0, 0.05), scale: 1 }),
+          k(0.9, { position: hip(0, 0.012, 0), rotation: lean(-0.02, 0, 0), scale: [1.01, 1.03, 1.01] }),
+          k(1, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 })
+        ],
+        loop
+      );
+      a(
+        fl,
+        [
+          k(0, { rotation: REST_L }),
+          k(0.12, { rotation: flipL(0.02, 0.2) }),
+          k(0.26, { rotation: REST_L }),
+          k(0.4, { rotation: REST_L }),
+          k(0.44, { rotation: flipL(-0.1, 0.55) }),
+          k(0.48, { rotation: flipL(0, 0.25) }),
+          k(0.51, { rotation: flipL(-0.05, 0.45) }),
+          k(0.58, { rotation: REST_L }),
+          k(0.9, { rotation: flipL(0.02, 0.2) }),
+          k(1, { rotation: REST_L })
+        ],
+        loop
+      );
+      a(
+        fr,
+        [
+          k(0, { rotation: REST_R }),
+          k(0.12, { rotation: flipR(0.02, 0.2) }),
+          k(0.26, { rotation: REST_R }),
+          k(0.64, { rotation: REST_R }),
+          k(0.68, { rotation: flipR(0.15, 0.5) }),
+          k(0.74, { rotation: REST_R }),
+          k(0.9, { rotation: flipR(0.02, 0.2) }),
+          k(1, { rotation: REST_R })
+        ],
+        loop
+      );
+      // Settling the weight: one foot shuffles as the body shifts onto the other
+      a(
+        footR,
+        [
+          k(0, { position: footRAt() }),
+          k(0.78, { position: footRAt() }),
+          k(0.82, { position: footRAt(0.025, 0.02) }),
+          k(0.86, { position: footRAt() }),
+          k(1, { position: footRAt() })
+        ],
+        loop
+      );
+      return Promise.resolve();
+    }
+
+    case 'walk':
+    case 'run': {
+      const run = anim === 'run';
+      // The waddle: the body rolls and slides over whichever foot is planted, twisting a little with
+      // each step; the free foot lifts low (walk) or high (run), swings forward and lands flat.
+      const sway = run ? 0.025 : 0.04;
+      const roll = run ? 0.09 : 0.15;
+      const twist = run ? 0.04 : 0.08;
+      const pitch = run ? 0.4 : 0.05;
+      const low = run ? -0.025 : -0.005;
+      const high = run ? 0.06 : 0.025;
+      a(
+        pelvis,
+        [
+          k(0, { position: hip(-sway, low, 0), rotation: lean(pitch, twist, roll) }),
+          k(0.25, { position: hip(0, high, 0), rotation: lean(pitch + 0.02, 0, 0) }),
+          k(0.5, { position: hip(sway, low, 0), rotation: lean(pitch, -twist, -roll) }),
+          k(0.75, { position: hip(0, high, 0), rotation: lean(pitch + 0.02, 0, 0) }),
+          k(1, { position: hip(-sway, low, 0), rotation: lean(pitch, twist, roll) })
+        ],
+        loop
+      );
+      const lift = run ? 0.09 : 0.045;
+      const stride = run ? 0.11 : 0.06;
+      // A foot's cycle: planted and sliding back under the body, then a quick swing forward
+      const stepKeys = (side: -1 | 1, at: (y?: number, z?: number) => Vec3, phase: number): Keyframe[] => {
+        const frames: [number, Vec3, Quat][] = [
+          [0, at(0, -stride), footRot(side, 0)],
+          [0.12, at(lift * 0.6, -stride * 0.4), footRot(side, 0.35)],
+          [0.25, at(lift, stride * 0.4), footRot(side, -0.1)],
+          [0.4, at(0, stride), footRot(side, -0.15)],
+          [0.46, at(0, stride * 0.9), footRot(side, 0)],
+          [1, at(0, -stride), footRot(side, 0)]
+        ];
+        // Shift the cycle by `phase` (0 or 0.5) so the feet alternate
+        const shifted = frames.map(([t, position, rotation]) => [(t + phase) % 1, position, rotation] as const).sort((x, y) => x[0] - y[0]);
+        const first = shifted[0]!;
+        const keys = shifted.map(([t, position, rotation]) => k(t, { position, rotation }));
+        if (first[0] > 0) {
+          const last = shifted[shifted.length - 1]!;
+          keys.unshift(k(0, { position: last[1], rotation: last[2] }));
+        }
+        if (keys[keys.length - 1]!.at! < 1) keys.push(k(1, { position: keys[0]!.position!, rotation: keys[0]!.rotation! }));
+        return keys;
+      };
+      a(footR, stepKeys(1, footRAt, 0), loop);
+      a(footL, stepKeys(-1, footLAt, 0.5), loop);
+      // Flippers: held out for balance, rising on the side away from the planted foot; swept back
+      // and beating when running
+      const [fwd, outLo, outHi] = run ? [0.95, 0.55, 0.85] : [0.15, 0.3, 0.55];
+      a(
+        fl,
+        [
+          k(0, { rotation: flipL(fwd, outLo) }),
+          k(0.25, { rotation: flipL(fwd - 0.08, (outLo + outHi) / 2) }),
+          k(0.5, { rotation: flipL(fwd, outHi) }),
+          k(0.75, { rotation: flipL(fwd - 0.08, (outLo + outHi) / 2) }),
+          k(1, { rotation: flipL(fwd, outLo) })
+        ],
+        loop
+      );
+      a(
+        fr,
+        [
+          k(0, { rotation: flipR(fwd, outHi) }),
+          k(0.25, { rotation: flipR(fwd - 0.08, (outLo + outHi) / 2) }),
+          k(0.5, { rotation: flipR(fwd, outLo) }),
+          k(0.75, { rotation: flipR(fwd - 0.08, (outLo + outHi) / 2) }),
+          k(1, { rotation: flipR(fwd, outHi) })
+        ],
+        loop
+      );
+      return Promise.resolve();
+    }
+
+    case 'punch':
+    case 'jab': {
+      // Wind up (twist back, crouch, cock the flipper), snap forward with the hips leading, overshoot,
+      // hold the extension a beat, then recover slowly. The lead foot steps in; the rear foot pivots.
+      const right = anim === 'punch';
+      const s = right ? 1 : -1;
+      const power = right ? 1 : 0.7;
+      const strike = right ? fr : fl;
+      const guard = right ? fl : fr;
+      const f = right ? flipR : flipL;
+      const g = right ? flipL : flipR;
+      const lead = right ? footL : footR;
+      const rear = right ? footR : footL;
+      const leadAt = right ? footLAt : footRAt;
+      const rearSide: -1 | 1 = right ? 1 : -1;
+      a(
+        pelvis,
+        [
+          k(0, { position: hip(0, 0, 0), rotation: IDENTITY }),
+          k(0.3, { position: hip(0, -0.035 * power, -0.03), rotation: lean(-0.12, 0.45 * s * power, 0) }),
+          k(0.4, { position: hip(0, -0.04 * power, 0.1 * power), rotation: lean(0.32 * power, -0.38 * s * power, 0) }),
+          k(0.48, { position: hip(0, -0.04 * power, 0.12 * power), rotation: lean(0.38 * power, -0.46 * s * power, 0) }),
+          k(0.64, { position: hip(0, -0.03 * power, 0.09 * power), rotation: lean(0.26 * power, -0.32 * s * power, 0) }),
+          k(1, { position: hip(0, 0, 0), rotation: IDENTITY })
+        ],
+        once
+      );
+      a(
+        strike,
+        [
+          k(0, { rotation: right ? REST_R : REST_L }),
+          k(0.3, { rotation: f(0.95, 0.55) }),
+          k(0.4, { rotation: f(-1.6, 0.2, 0.15) }),
+          k(0.48, { rotation: f(-1.85, 0.12, 0.2) }),
+          k(0.64, { rotation: f(-1.55, 0.2, 0.1) }),
+          k(1, { rotation: right ? REST_R : REST_L })
+        ],
+        once
+      );
+      a(
+        guard,
+        [
+          k(0, { rotation: right ? REST_L : REST_R }),
+          k(0.3, { rotation: g(-0.5, 0.35) }),
+          k(0.42, { rotation: g(0.7, 0.55) }),
+          k(0.64, { rotation: g(0.5, 0.45) }),
+          k(1, { rotation: right ? REST_L : REST_R })
+        ],
+        once
+      );
+      a(
+        lead,
+        [
+          k(0, { position: leadAt() }),
+          k(0.3, { position: leadAt() }),
+          k(0.36, { position: leadAt(0.035, 0.07) }),
+          k(0.42, { position: leadAt(0, 0.13 * power) }),
+          k(0.7, { position: leadAt(0, 0.12 * power) }),
+          k(0.85, { position: leadAt(0.02, 0.05) }),
+          k(1, { position: leadAt() })
+        ],
+        once
+      );
+      return a(
+        rear,
+        [
+          k(0, { rotation: footRot(rearSide, 0) }),
+          k(0.4, { rotation: footRot(rearSide, -0.15, -0.45 * s) }),
+          k(0.7, { rotation: footRot(rearSide, -0.1, -0.35 * s) }),
+          k(1, { rotation: footRot(rearSide, 0) })
+        ],
+        once
+      );
+    }
+
+    case 'jump': {
+      // Deep crouch with flippers swung back, explode up stretching, flap hard at the top, tuck the
+      // feet, reach for the ground, land in a squash and bounce back up past standing to settle.
+      // The whole bird rises (pelvis and feet together), so whatever moves the root can keep moving it
+      const lift = (keys: Keyframe[]): Keyframe[] =>
+        keys.map((key) => (key.position ? { ...key, position: [key.position[0], key.position[1] + airAt(key.at ?? 0), key.position[2]] } : key));
+      const done = a(
+        pelvis,
+        lift([
+          k(0, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 }),
+          k(0.22, { position: hip(0, -0.09, 0.02), rotation: lean(0.22, 0, 0), scale: [1.14, 0.84, 1.14] }),
+          k(0.3, { position: hip(0, 0.02, 0), rotation: lean(-0.06, 0, 0), scale: [0.9, 1.16, 0.9] }),
+          k(0.4, { position: hip(0, 0.02, 0), rotation: lean(0.02, 0, 0), scale: 1 }),
+          k(0.52, { position: hip(0, 0.02, 0), rotation: lean(0.05, 0, 0), scale: 1 }),
+          k(0.64, { position: hip(0, 0.01, 0), rotation: lean(0, 0, 0), scale: 1 }),
+          k(0.72, { position: hip(0, 0.01, 0), rotation: lean(-0.04, 0, 0), scale: [0.95, 1.07, 0.95] }),
+          k(0.8, { position: hip(0, -0.09, 0.01), rotation: lean(0.18, 0, 0), scale: [1.16, 0.82, 1.16] }),
+          k(0.9, { position: hip(0, 0.015, 0), rotation: lean(-0.03, 0, 0), scale: [0.96, 1.05, 0.96] }),
+          k(1, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 })
+        ]),
+        once
+      );
+      const flap = (fn: typeof flipL, rest: Quat): Keyframe[] => [
+        k(0, { rotation: rest }),
+        k(0.22, { rotation: fn(1.1, 0.5) }),
+        k(0.32, { rotation: fn(-0.2, 2.3) }),
+        k(0.42, { rotation: fn(0.1, 1.0) }),
+        k(0.52, { rotation: fn(-0.1, 2.1) }),
+        k(0.66, { rotation: fn(0.1, 1.1) }),
+        k(0.8, { rotation: fn(-0.2, 1.7) }),
+        k(0.9, { rotation: fn(0, 0.5) }),
+        k(1, { rotation: rest })
+      ];
+      a(fl, flap(flipL, REST_L), once);
+      a(fr, flap(flipR, REST_R), once);
+      for (const [foot, at, side] of [
+        [footL, footLAt, -1],
+        [footR, footRAt, 1]
+      ] as const)
+        a(
+          foot,
+          lift([
+            k(0, { position: at(), rotation: footRot(side, 0) }),
+            k(0.28, { position: at(), rotation: footRot(side, -0.3) }),
+            k(0.42, { position: at(0.07, -0.05), rotation: footRot(side, 0.6) }),
+            k(0.52, { position: at(0.07, -0.04), rotation: footRot(side, 0.5) }),
+            k(0.62, { position: at(0.06, -0.03), rotation: footRot(side, 0.4) }),
+            k(0.76, { position: at(0.01, 0.02), rotation: footRot(side, -0.25) }),
+            k(0.8, { position: at(), rotation: footRot(side, 0) }),
+            k(1, { position: at(), rotation: footRot(side, 0) })
+          ]),
+          once
+        );
+      return done;
+    }
+
+    case 'slide': {
+      // Drop back into a low, feet-first slide leaning backwards, flippers out for balance,
+      // glide under the obstacle with a slight sway, then rock forward back onto the feet.
+      a(
+        pelvis,
+        [
+          k(0, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 }),
+          k(0.12, { position: hip(0, -0.06, -0.03), rotation: lean(-0.35, 0, 0), scale: [1.04, 0.92, 1.04] }),
+          k(0.24, { position: hip(0, -0.13, -0.08), rotation: lean(-1.05, 0, 0), scale: [1.06, 0.88, 1.06] }),
+          k(0.45, { position: hip(0, -0.13, -0.08), rotation: lean(-1.02, 0.04, 0.04), scale: [1.06, 0.88, 1.06] }),
+          k(0.6, { position: hip(0, -0.13, -0.08), rotation: lean(-1.05, -0.04, -0.04), scale: [1.06, 0.88, 1.06] }),
+          k(0.74, { position: hip(0, -0.13, -0.08), rotation: lean(-1.02, 0.03, 0.02), scale: [1.06, 0.88, 1.06] }),
+          k(0.86, { position: hip(0, -0.05, -0.03), rotation: lean(-0.3, 0, 0), scale: [1.03, 0.95, 1.03] }),
+          k(0.93, { position: hip(0, 0.01, 0), rotation: lean(0.06, 0, 0), scale: [0.98, 1.02, 0.98] }),
+          k(1, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 })
+        ],
+        once
+      );
+      const paddle = (fn: typeof flipL, rest: Quat, offset: number): Keyframe[] => [
+        k(0, { rotation: rest }),
+        k(0.12, { rotation: fn(-0.3, 0.6) }),
+        k(0.24, { rotation: fn(-0.5, 0.9) }),
+        k(0.4 + offset, { rotation: fn(-0.45, 1.0) }),
+        k(0.55 + offset, { rotation: fn(-0.55, 0.9) }),
+        k(0.74, { rotation: fn(-0.5, 0.95) }),
+        k(0.86, { rotation: fn(-0.15, 0.5) }),
+        k(1, { rotation: rest })
+      ];
+      a(fl, paddle(flipL, REST_L, 0), once);
+      a(fr, paddle(flipR, REST_R, 0.04), once);
+      for (const [foot, at, side, offset] of [
+        [footL, footLAt, -1, 0],
+        [footR, footRAt, 1, 0.05]
+      ] as const)
+        a(
+          foot,
+          [
+            k(0, { position: at(), rotation: footRot(side, 0) }),
+            k(0.12, { position: at(0.01, 0.08), rotation: footRot(side, -0.3) }),
+            k(0.24, { position: at(0.03, 0.18), rotation: footRot(side, -0.55) }),
+            k(0.5 + offset, { position: at(0.03, 0.18), rotation: footRot(side, -0.5) }),
+            k(0.76, { position: at(0.03, 0.18), rotation: footRot(side, -0.55) }),
+            k(0.88, { position: at(0.01, 0.05), rotation: footRot(side, -0.1) }),
+            k(1, { position: at(), rotation: footRot(side, 0) })
+          ],
+          once
+        );
+      return a(p.body, [k(0, { scale: 1 }), k(1, { scale: 1 })], once);
+    }
+
+    case 'hit': {
+      // Snapped back by the blow, flippers flung up, a stumble back, then a damped wobble to standing
+      world.animate(p.root, { shake: 0.045 }, { duration: T * 0.4 });
+      a(
+        pelvis,
+        [
+          k(0, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 }),
+          k(0.1, { position: hip(0, -0.02, -0.08), rotation: lean(-0.55, 0, 0.15), scale: [1.06, 0.93, 1.06] }),
+          k(0.26, { position: hip(0, 0, -0.05), rotation: lean(0.22, 0, -0.08), scale: 1 }),
+          k(0.42, { position: hip(0, 0, -0.03), rotation: lean(-0.12, 0, 0.05), scale: 1 }),
+          k(0.58, { position: hip(0, 0, -0.01), rotation: lean(0.06, 0, -0.02), scale: 1 }),
+          k(0.75, { position: hip(0, 0, 0), rotation: lean(-0.02, 0, 0), scale: 1 }),
+          k(1, { position: hip(0, 0, 0), rotation: IDENTITY, scale: 1 })
+        ],
+        once
+      );
+      a(
+        fl,
+        [
+          k(0, { rotation: REST_L }),
+          k(0.1, { rotation: flipL(-0.4, 1.9) }),
+          k(0.28, { rotation: flipL(0.2, 0.6) }),
+          k(0.44, { rotation: flipL(-0.1, 1.0) }),
+          k(0.62, { rotation: flipL(0, 0.4) }),
+          k(1, { rotation: REST_L })
+        ],
+        once
+      );
+      a(
+        fr,
+        [
+          k(0, { rotation: REST_R }),
+          k(0.12, { rotation: flipR(-0.4, 1.8) }),
+          k(0.3, { rotation: flipR(0.2, 0.55) }),
+          k(0.46, { rotation: flipR(-0.1, 0.95) }),
+          k(0.64, { rotation: flipR(0, 0.4) }),
+          k(1, { rotation: REST_R })
+        ],
+        once
+      );
+      a(
+        footL,
+        [
+          k(0, { position: footLAt() }),
+          k(0.14, { position: footLAt(0.04, -0.06) }),
+          k(0.24, { position: footLAt(0, -0.1) }),
+          k(0.7, { position: footLAt(0, -0.06) }),
+          k(1, { position: footLAt() })
+        ],
+        once
+      );
+      return a(
+        footR,
+        [
+          k(0, { position: footRAt() }),
+          k(0.3, { position: footRAt() }),
+          k(0.4, { position: footRAt(0.03, -0.04) }),
+          k(0.5, { position: footRAt(0, -0.07) }),
+          k(1, { position: footRAt() })
+        ],
+        once
+      );
+    }
+
+    case 'dance': {
+      // A happy shuffle: hop from foot to foot with a body roll, both flippers waving overhead
+      a(
+        pelvis,
+        [
+          k(0, { position: hip(-0.03, 0, 0), rotation: lean(0, 0.35, 0.18), scale: [1.04, 0.95, 1.04] }),
+          k(0.12, { position: hip(-0.01, 0.07, 0), rotation: lean(0, 0.2, 0.08), scale: [0.97, 1.05, 0.97] }),
+          k(0.25, { position: hip(0, 0.09, 0), rotation: lean(-0.05, 0, 0), scale: 1 }),
+          k(0.38, { position: hip(0.01, 0.07, 0), rotation: lean(0, -0.2, -0.08), scale: [0.97, 1.05, 0.97] }),
+          k(0.5, { position: hip(0.03, 0, 0), rotation: lean(0, -0.35, -0.18), scale: [1.04, 0.95, 1.04] }),
+          k(0.62, { position: hip(0.01, 0.07, 0), rotation: lean(0, -0.2, -0.08), scale: [0.97, 1.05, 0.97] }),
+          k(0.75, { position: hip(0, 0.09, 0), rotation: lean(-0.05, 0, 0), scale: 1 }),
+          k(0.88, { position: hip(-0.01, 0.07, 0), rotation: lean(0, 0.2, 0.08), scale: [0.97, 1.05, 0.97] }),
+          k(1, { position: hip(-0.03, 0, 0), rotation: lean(0, 0.35, 0.18), scale: [1.04, 0.95, 1.04] })
+        ],
+        loop
+      );
+      a(
+        fl,
+        [
+          k(0, { rotation: flipL(0, 2.6) }),
+          k(0.25, { rotation: flipL(-0.35, 1.9) }),
+          k(0.5, { rotation: flipL(0, 2.6) }),
+          k(0.75, { rotation: flipL(-0.35, 1.9) }),
+          k(1, { rotation: flipL(0, 2.6) })
+        ],
+        loop
+      );
+      a(
+        fr,
+        [
+          k(0, { rotation: flipR(-0.35, 1.9) }),
+          k(0.25, { rotation: flipR(0, 2.6) }),
+          k(0.5, { rotation: flipR(-0.35, 1.9) }),
+          k(0.75, { rotation: flipR(0, 2.6) }),
+          k(1, { rotation: flipR(-0.35, 1.9) })
+        ],
+        loop
+      );
+      a(
+        footL,
+        [
+          k(0, { position: footLAt() }),
+          k(0.6, { position: footLAt() }),
+          k(0.75, { position: footLAt(0.07, 0.03) }),
+          k(0.9, { position: footLAt() }),
+          k(1, { position: footLAt() })
+        ],
+        loop
+      );
+      a(
+        footR,
+        [
+          k(0, { position: footRAt() }),
+          k(0.1, { position: footRAt() }),
+          k(0.25, { position: footRAt(0.07, 0.03) }),
+          k(0.4, { position: footRAt() }),
+          k(1, { position: footRAt() })
+        ],
+        loop
+      );
+      return Promise.resolve();
+    }
+
+    case 'dead': {
+      // Rocked by the hit, staggers dizzily from side to side, then topples onto its back, bounces
+      // once and lies still with the flippers splayed and the feet in the air.
+      a(
+        pelvis,
+        [
+          k(0, { position: hip(0, 0, 0), rotation: IDENTITY }),
+          k(0.08, { position: hip(0, -0.02, -0.05), rotation: lean(-0.35, 0, 0.08) }),
+          k(0.2, { position: hip(0.02, 0, 0), rotation: lean(0.18, 0.15, 0.14) }),
+          k(0.34, { position: hip(-0.02, 0, 0), rotation: lean(-0.05, -0.2, -0.16) }),
+          k(0.48, { position: hip(0.015, 0, 0), rotation: lean(0.08, 0.15, 0.12) }),
+          k(0.6, { position: hip(0, -0.02, -0.03), rotation: lean(-0.3, 0, 0.05) }),
+          k(0.76, { position: [0, 0.3, -0.26], rotation: lean(-1.55, 0, 0.1) }),
+          k(0.84, { position: [0, 0.36, -0.24], rotation: lean(-1.38, 0, 0.12) }),
+          k(0.92, { position: [0, 0.3, -0.26], rotation: lean(-1.55, 0, 0.1) }),
+          k(1, { position: [0, 0.3, -0.26], rotation: lean(-1.55, 0, 0.1) })
+        ],
+        once
+      );
+      a(
+        fl,
+        [
+          k(0, { rotation: REST_L }),
+          k(0.08, { rotation: flipL(-0.3, 1.2) }),
+          k(0.3, { rotation: flipL(0.2, 0.8) }),
+          k(0.6, { rotation: flipL(-0.4, 1.6) }),
+          k(0.8, { rotation: flipL(-0.2, 1.45) }),
+          k(0.88, { rotation: flipL(-0.3, 1.7) }),
+          k(1, { rotation: flipL(-0.2, 1.4) })
+        ],
+        once
+      );
+      a(
+        fr,
+        [
+          k(0, { rotation: REST_R }),
+          k(0.1, { rotation: flipR(-0.3, 1.1) }),
+          k(0.36, { rotation: flipR(0.2, 0.9) }),
+          k(0.62, { rotation: flipR(-0.4, 1.5) }),
+          k(0.8, { rotation: flipR(-0.2, 1.4) }),
+          k(0.88, { rotation: flipR(-0.3, 1.65) }),
+          k(1, { rotation: flipR(-0.2, 1.35) })
+        ],
+        once
+      );
+      a(
+        footL,
+        [
+          k(0, { position: footLAt(), rotation: footRot(-1, 0) }),
+          k(0.2, { position: footLAt(0.03, 0.03), rotation: footRot(-1, 0) }),
+          k(0.26, { position: footLAt(0, 0.04), rotation: footRot(-1, 0) }),
+          k(0.6, { position: footLAt(), rotation: footRot(-1, 0) }),
+          k(0.78, { position: footLAt(0.2, 0.05), rotation: footRot(-1, -1.2) }),
+          k(1, { position: footLAt(0.18, 0.04), rotation: footRot(-1, -1.3) })
+        ],
+        once
+      );
+      return a(
+        footR,
+        [
+          k(0, { position: footRAt(), rotation: footRot(1, 0) }),
+          k(0.34, { position: footRAt(0.03, -0.03), rotation: footRot(1, 0) }),
+          k(0.4, { position: footRAt(0, -0.04), rotation: footRot(1, 0) }),
+          k(0.6, { position: footRAt(), rotation: footRot(1, 0) }),
+          k(0.8, { position: footRAt(0.22, 0.03), rotation: footRot(1, -1.1) }),
+          k(1, { position: footRAt(0.2, 0.02), rotation: footRot(1, -1.25) })
+        ],
+        once
+      );
+    }
+  }
+}
+
+/** Hand position for effects: where a strike lands, in world space, for a bird of `size` at its x and yaw. */
+export function strikePoint(p: Penguin, size: number): Vec3 {
+  return [p.x + Math.sin(p.yaw) * 0.45 * size, 0.55 * size, Math.cos(p.yaw) * 0.45 * size];
+}