@diffenderfer-games/hub 2.0.0-next.5 → 2.0.0-next.6

package/src/avatar/render/eyewear.ts

@@ -0,0 +1,56 @@
+/** Glasses and the `goggles` status prop, both following the head turn. */
+import type { GlassesPart } from '../art/shape';
+import { ink } from '../colour';
+import { blob, Path } from '../geom';
+import { g, line, path, sc, tr, type SceneNode } from '../scene';
+import { feat, LINE, turnWarp, type Ctx } from './context';
+
+/** Glasses: arms toward the ears, a lens at each eye, and the bridge. */
+export function glasses(ctx: Ctx, part: GlassesPart, frame: string): SceneNode[] {
+  const out: SceneNode[] = [];
+  const warp = turnWarp(ctx.phi, ctx.dy);
+  for (const side of [-1, 1] as const) {
+    if (feat(ctx, 30 * side).vis) {
+      out.push(path(new Path().m(30 * side, 2).l(45 * side, 0).d(warp), line(frame, 2.6)));
+    }
+  }
+  for (const side of [-1, 1] as const) {
+    const f = feat(ctx, 17 * side);
+    if (!f.vis) {
+      continue;
+    }
+    out.push(g([
+      path(part.lens.d(), { fill: '#ffffff', fillOpacity: 0.16, stroke: frame, sw: 3.2 }),
+      path('M-6 -4L-2 -7', line('#ffffff', 1.8, 'round', 0.7)),
+    ], { tf: [tr(f.x, 4 + ctx.dy), sc(f.sx, 1)] }));
+  }
+  const fb = feat(ctx, 0);
+  out.push(g([path(part.bridge.d(), line(frame, 2.8))], { tf: [tr(fb.x, 4 + ctx.dy), sc(fb.sx, 1)] }));
+  return out;
+}
+
+const STRAP_FRONT = new Path().m(-47, -2).c(-30, -6, 30, -6, 47, -2);
+const STRAP_BACK = new Path().m(-47, -2).c(-30, 4, 30, 4, 47, -2);
+const SHELL = blob([[-31, -9], [-4, -10], [0, -6], [4, -10], [31, -9], [34, 4], [26, 16], [7, 16], [0, 11], [-7, 16], [-26, 16], [-34, 4]]);
+const GLASS_L = blob([[-27, -5], [-7, -6], [-5, 8], [-9, 12], [-24, 12], [-29, 4]]);
+const GLASS_R = blob([[27, -5], [7, -6], [5, 8], [9, 12], [24, 12], [29, 4]]);
+
+/** Play goggles over the eyes (they replace the eyes and any glasses); the strap is the body colour. */
+export function goggles(ctx: Ctx): SceneNode[] {
+  const w = turnWarp(ctx.phi, ctx.dy);
+  const band = ctx.c.body;
+  const strap = STRAP_FRONT.d(w);
+  return [
+    path(strap, line(ink(band), 9)), path(strap, line(band, 6)),
+    path(SHELL.d(w), { fill: '#2a3142', stroke: '#0d0f14', sw: LINE }),
+    path(GLASS_L.d(w), { fill: '#5fe3f2' }), path(GLASS_R.d(w), { fill: '#5fe3f2' }),
+    path(new Path().m(-22, 6).l(-14, -2).d(w), line('#e8fbff', 3)),
+    path(new Path().m(12, 6).l(20, -2).d(w), line('#e8fbff', 3)),
+  ];
+}
+
+/** The goggles strap seen from behind. */
+export function gogglesStrapBack(ctx: Ctx, phi: number): SceneNode[] {
+  const d = STRAP_BACK.d(turnWarp(phi));
+  return [path(d, line(ink(ctx.c.body), 9)), path(d, line(ctx.c.body, 6))];
+}

package/src/avatar/render/frame.ts

@@ -0,0 +1,60 @@
+/**
+ * Frames (§3.4): which part of rig space an output shows, and the badge
+ * background (the site's rounded panel with a ring that lightens on dark
+ * skin, §3.9).
+ */
+import { normaliseHex, resolveColour, type AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import { lightness } from '../colour';
+import { g, rect, type SceneNode } from '../scene';
+import type { Frame, RenderOptions } from './types';
+
+/** A frame's box in rig units: x, y, width, height. */
+export type Box = readonly [number, number, number, number];
+
+/** The three frames' boxes. */
+export const FRAMES: Readonly<Record<Frame, Box>> = {
+  head: [-66, -164, 132, 132],
+  bust: [-84, -188, 168, 168],
+  full: [-86, -196, 172, 206],
+};
+
+/** The site panel colour behind badges. */
+export const PANEL = '#11141c';
+
+/** The frame an options object asks for (default `head`). */
+export function frameOf(opts: RenderOptions): Frame {
+  return opts.frame ?? 'head';
+}
+
+/** Output pixel size for a frame (the longer edge is `size`). */
+export function pixelSize(opts: RenderOptions): { readonly width: number; readonly height: number; readonly scale: number } {
+  const [, , w, h] = FRAMES[frameOf(opts)];
+  const size = opts.size ?? 48;
+  const scale = size / Math.max(w, h);
+  return { width: w * scale, height: h * scale, scale };
+}
+
+/** The badge ring colour: lighter when the skin is darker than the panel, so every skin has an edge. */
+export function ringColour(look: AvatarLook | null): string {
+  return look && lightness(resolveColour(look.skin)) < 0.42 ? '#6f7787' : '#2a3142';
+}
+
+/** Wraps the avatar's nodes in the frame's background (a badge clips to the rounded panel). */
+export function framed(nodes: readonly SceneNode[], look: AvatarLook | null, opts: RenderOptions): SceneNode[] {
+  const [left, top, w, h] = FRAMES[frameOf(opts)];
+  const background = opts.background ?? (frameOf(opts) === 'head' ? 'badge' : 'none');
+  if (background === 'badge') {
+    const r = w * 0.24;
+    return [
+      rect(left, top, w, h, { fill: PANEL }, r),
+      g(nodes, { clip: { shapes: [rect(left, top, w, h, {}, r)] } }),
+      rect(left + 1.5, top + 1.5, w - 3, h - 3, { fill: 'none', stroke: ringColour(look), sw: 3 }, r - 1.5),
+    ];
+  }
+  if (background === 'none') {
+    return [...nodes];
+  }
+  // A caller-supplied colour is normalised, so it can never become markup.
+  const fill = normaliseHex(background);
+  return fill ? [rect(left, top, w, h, { fill }), ...nodes] : [...nodes];
+}

package/src/avatar/render/head.ts

@@ -0,0 +1,81 @@
+/** The head, ears, cheeks and the small face and ear extras. */
+import { clamp } from '../geom';
+import { ellipse, g, line, path, sc, tr, type SceneNode } from '../scene';
+import { FIXED } from './colours';
+import { feat, HEAD_PATH, LINE, SKULL_R, type Ctx } from './context';
+
+const EAR = 'M-2 -10C6 -12 11 -6 10 1C9 8 5 11 -1 10Z';
+const EAR_FOLD = 'M1.5 -5C5.5 -5 6.5 0 5 3.5';
+
+/** Ear extras: studs or hoops, in a colour. */
+export interface EarExtra {
+  readonly kind: 'studs' | 'hoops';
+  readonly colour: string;
+}
+
+/** Ears behind the head (`behind`) or in front of it (`front`), hidden when turned away. */
+export function ears(ctx: Ctx, which: 'behind' | 'front', extra?: EarExtra): SceneNode[] {
+  const out: SceneNode[] = [];
+  for (const side of [-1, 1] as const) {
+    const t = (Math.PI / 2) * side + ctx.phi;
+    const cos = Math.cos(t);
+    if (cos < -0.15) {
+      continue;
+    }
+    const isInFront = cos > 0.3;
+    if ((which === 'front') !== isInFront) {
+      continue;
+    }
+    const earX = clamp(SKULL_R * Math.sin(t), -SKULL_R + 2, SKULL_R - 2);
+    const w = isInFront ? 0.75 + 0.25 * cos : 1;
+    const flip = isInFront ? -Math.sign(earX || side) : side;
+    const parts: SceneNode[] = [
+      path(EAR, { fill: ctx.c.skin, stroke: ctx.c.skinInk, sw: LINE }),
+      path(EAR_FOLD, line(ctx.c.skinShade, 2.2)),
+    ];
+    if (extra?.kind === 'studs') {
+      parts.push(ellipse(3, 7, 2.2, 2.2, { fill: extra.colour, stroke: '#3a2a2a', sw: 0.8 }));
+    }
+    if (extra?.kind === 'hoops') {
+      parts.push(ellipse(3, 12, 3.6, 4.4, line(extra.colour, 1.8)));
+    }
+    out.push(g(parts, { tf: [tr(earX, 6 + ctx.dy * 0.3), sc(flip * w, 1)] }));
+  }
+  return out;
+}
+
+/** The head: a shade base, the lit face, and the tonal outline. */
+export function head(ctx: Ctx): SceneNode[] {
+  const d = HEAD_PATH.d();
+  const lx = -2.5 + Math.sin(ctx.phi) * 3;
+  return [
+    path(d, { fill: ctx.c.skinShade }),
+    path(d, { fill: ctx.c.skin }, [tr(lx, -3), sc(0.95)]),
+    path(d, { fill: 'none', stroke: ctx.c.skinInk, sw: LINE }),
+  ];
+}
+
+const FRECKLES: readonly (readonly [number, number])[] = [[-3.5, -1.5], [0, 0.8], [3.5, -1.2], [1.5, -3.5]];
+
+/** Cheek blush (from the expression, plus `rosy`) and freckles. */
+export function cheeks(ctx: Ctx, hasFreckles: boolean, isRosy: boolean): SceneNode[] {
+  const out: SceneNode[] = [];
+  const blush = Math.min(1, ctx.face.cheeks + (isRosy ? 0.45 : 0));
+  for (const side of [-1, 1] as const) {
+    const f = feat(ctx, 25 * side);
+    if (!f.vis) {
+      continue;
+    }
+    const parts: SceneNode[] = [];
+    if (blush > 0.02) {
+      parts.push(ellipse(0, 0, 6.5, 3.8, { fill: FIXED.blush, opacity: Math.round(blush * 5) / 10 }));
+    }
+    if (hasFreckles) {
+      parts.push(...FRECKLES.map(([fx, fy]) => ellipse(fx, fy, 1.05, 1.05, { fill: ctx.c.skinInk, opacity: 0.45 })));
+    }
+    if (parts.length > 0) {
+      out.push(g(parts, { tf: [tr(f.x, 18 + ctx.dy), sc(f.sx, 1)] }));
+    }
+  }
+  return out;
+}

package/src/avatar/render/mouth.ts

@@ -0,0 +1,86 @@
+/**
+ * The nose, the mouth morph (one cubic structure for every shape, so any two
+ * expressions tween, §3.5) and the small FX glyphs.
+ */
+import { n } from '../geom';
+import { ellipse, g, line, path, rect, sc, tr, type SceneNode } from '../scene';
+import { FIXED, SOFT_INK } from './colours';
+import { feat, LINE, type Ctx } from './context';
+
+/** The nose: a soft shade with a highlight. */
+export function nose(ctx: Ctx): SceneNode[] {
+  const f = feat(ctx, 0);
+  return [g([
+    ellipse(0, 0, 4.4, 3, { fill: ctx.c.skinShade }),
+    ellipse(-1.5, -1, 1.2, 1.2, { fill: ctx.c.skinLight, opacity: 0.9 }),
+  ], { tf: [tr(f.x, 16 + ctx.dy), sc(Math.max(0.6, f.sx), 1)] })];
+}
+
+/** The mouth: a line when closed, a filled shape with teeth and tongue when open. Talking adds opening. */
+export function mouth(ctx: Ctx): SceneNode[] {
+  const base = ctx.face.mouth;
+  const m = { ...base, open: base.open + ctx.talk * 9 * (1 - base.round * 0.4) };
+  const f = feat(ctx, m.dx);
+  const baseY = 27;
+  const lx = -m.w / 2;
+  const ly = baseY - m.sL;
+  const rx = m.w / 2;
+  const ry = baseY - m.sR;
+  const s = (m.sL + m.sR) / 2;
+  const corner = baseY - s;
+  const ctrl = (target: number): number => (target - 0.25 * corner) / 0.75;
+  const place = [tr(f.x, ctx.dy * 0.8), sc(Math.max(0.35, f.sx), 1)];
+  if (m.open < 1) {
+    const c = ctrl(baseY + s * 0.55);
+    return [g([path(`M${n(lx)} ${n(ly)}C${n(-m.w * 0.18)} ${n(c)} ${n(m.w * 0.18)} ${n(c)} ${n(rx)} ${n(ry)}`, line(SOFT_INK, LINE * 0.95))], { tf: place })];
+  }
+  const up = baseY + s * 0.3 - m.round * m.open * 0.45;
+  const lo = baseY + s * 0.55 + m.open * (1 - m.round * 0.45);
+  const kx = (m.w / 2) * (0.55 + m.round * 0.8);
+  const d = `M${n(lx)} ${n(ly)}C${n(-kx)} ${n(ctrl(up))} ${n(kx)} ${n(ctrl(up))} ${n(rx)} ${n(ry)}C${n(kx)} ${n(ctrl(lo))} ${n(-kx)} ${n(ctrl(lo))} ${n(lx)} ${n(ly)}Z`;
+  const inside: SceneNode[] = [];
+  if (m.tongue > 0.05) {
+    inside.push(ellipse(0, lo + 1, m.w * 0.32, m.open * 0.42 * m.tongue + 1, { fill: FIXED.tongue }));
+  }
+  if (m.teeth > 0.05) {
+    inside.push(rect(-m.w / 2, up - 6, m.w, 6 + m.open * 0.22 * m.teeth, { fill: FIXED.white }));
+  }
+  return [g([
+    path(d, { fill: FIXED.mouth }),
+    g(inside, { clip: { shapes: [path(d, {})] } }),
+    path(d, line(SOFT_INK, LINE * 0.9)),
+  ], { tf: place })];
+}
+
+/** FX glyphs beside the head (sparkle, tear, sweat, anger, question, zzz). */
+export function extras(ctx: Ctx): SceneNode[] {
+  const out: SceneNode[] = [];
+  const f = feat(ctx, 0);
+  for (const e of ctx.face.extras) {
+    if (e === 'sparkle') {
+      out.push(path('M0 -9Q1.4 -1.4 9 0Q1.4 1.4 0 9Q-1.4 1.4 -9 0Q-1.4 -1.4 0 -9Z', { fill: '#ffd23f', stroke: '#0d0f14', sw: 1.6 }, [tr(48 + f.x * 0.2, -44)]));
+    }
+    if (e === 'tear') {
+      const t = feat(ctx, -16);
+      if (t.vis) {
+        out.push(path('M0 -5Q4.5 2 0 5Q-4.5 2 0 -5Z', { fill: '#7cc7ff', stroke: '#1f3b5c', sw: 1.4 }, [tr(t.x - 5, 16 + ctx.dy)]));
+      }
+    }
+    if (e === 'sweat') {
+      out.push(path('M0 -6Q5 2 0 6Q-5 2 0 -6Z', { fill: '#9fdcff', stroke: '#1f3b5c', sw: 1.4 }, [tr(40 + f.x * 0.2, -26)]));
+    }
+    if (e === 'anger') {
+      out.push(g([
+        path('M-6 -2Q-2 -2 -2 -6', line('#ff4d4d', 2.6)), path('M2 -6Q2 -2 6 -2', line('#ff4d4d', 2.6)),
+        path('M6 2Q2 2 2 6', line('#ff4d4d', 2.6)), path('M-2 6Q-2 2 -6 2', line('#ff4d4d', 2.6)),
+      ], { tf: [tr(30 + f.x * 0.3, -36)] }));
+    }
+    if (e === 'question') {
+      out.push({ k: 'text', x: 50 + f.x * 0.2, y: -40, text: '?', size: 26, font: 'pixel', fill: '#ffd23f', stroke: '#0d0f14', sw: 1.2 });
+    }
+    if (e === 'zzz') {
+      out.push({ k: 'text', x: 44 + f.x * 0.2, y: -42, text: 'z z', size: 20, font: 'pixel', fill: '#8ab4ff', stroke: '#0d0f14', sw: 1.2 });
+    }
+  }
+  return out;
+}

package/src/avatar/render/props.ts

@@ -0,0 +1,91 @@
+/**
+ * Status props (§3.11, §14.3): runtime-only parts the world (or a preview)
+ * puts on a player. `goggles` lives in eyewear.ts; the head props here sit on
+ * the head, the hand props at the `prop` anchor in front of the body.
+ */
+import { arc, blob, Path, roundedRect } from '../geom';
+import { ellipse, g, line, path, rect, rot, sc, tr, type SceneNode } from '../scene';
+import { LINE, SKULL_R, turnWarp, type Ctx } from './context';
+import type { StatusProp } from './types';
+
+const DARK = '#0d0f14';
+/** Hand props are drawn at this scale so they read at small sizes. */
+const PROP_SCALE = 1.45;
+
+/** A headset: a band over the head, ear cups and a mic (head space). */
+export function headset(ctx: Ctx, isBack: boolean): SceneNode[] {
+  const w = turnWarp(isBack ? 0 : ctx.phi);
+  const band = blob(arc(0, -4, 51, 51, 196, 344, 8), false);
+  const nodes: SceneNode[] = [path(band.d(w), line(DARK, 8)), path(band.d(w), line('#4a5470', 5))];
+  const phi = isBack ? 0 : ctx.phi;
+  for (const side of [-1, 1] as const) {
+    // The cups sit over the ears, so they follow the ears through a turn.
+    const t = (Math.PI / 2) * side + phi;
+    if (Math.cos(t) < -0.15) {
+      continue;
+    }
+    const cupX = Math.max(-SKULL_R - 1, Math.min(SKULL_R + 1, SKULL_R * Math.sin(t)));
+    const wide = 6 + 3 * Math.max(0, Math.cos(t));
+    nodes.push(path(roundedRect(cupX - wide, -6, wide * 2, 20, 5).d(), { fill: '#2a3142', stroke: DARK, sw: LINE }));
+  }
+  if (!isBack && Math.abs(phi) < 0.7) {
+    nodes.push(path(new Path().m(-46, 12).q(-40, 30, -18, 30).d(w), line('#4a5470', 3)), ellipse(-17, 30, 3, 3, { fill: '#ff5f3b', stroke: DARK, sw: 1.2 }));
+  }
+  return nodes;
+}
+
+/** A small crown on top of the head (head space; `top` is the hair or hat top). */
+export function crown(top: number): SceneNode[] {
+  const d = 'M-16 0L-18 -16L-8 -8L0 -20L8 -8L18 -16L16 0Z';
+  return [g([
+    path(d, { fill: '#ffd23f', stroke: '#8a5a00', sw: LINE }),
+    ellipse(0, -5, 2.4, 2.4, { fill: '#ff5f3b' }),
+  ], { tf: [tr(0, -50 - top + 4)] })];
+}
+
+const card = (colour: string): SceneNode =>
+  rect(-6, -9, 12, 17, { fill: colour, stroke: DARK, sw: 1.6 }, 2.5);
+
+/** Nub hands holding something at the prop anchor (body space). */
+function nubs(body: string, ink: string, spread: number, atY: number): SceneNode[] {
+  return [-1, 1].map((s) => ellipse(spread * s, atY, 7, 6, { fill: body, stroke: ink, sw: LINE }));
+}
+
+/** A hand prop drawn at the `prop` anchor (x, y) in front of the body. */
+export function handProp(prop: StatusProp, atX: number, atY: number, body: string, bodyInk: string): SceneNode[] {
+  switch (prop) {
+    case 'cards':
+      return [g([
+        g([card('#ff5f3b')], { tf: [tr(-8, 0), rot(-18)] }),
+        g([card('#ffd23f')], { tf: [tr(0, -3)] }),
+        g([card('#3d7bff')], { tf: [tr(8, 0), rot(18)] }),
+        ...nubs(body, bodyInk, 13, 8),
+      ], { tf: [tr(atX, atY), sc(PROP_SCALE)] })];
+    case 'controller':
+      return [g([
+        path(new Path().m(-20, -4).c(-20, -12, 20, -12, 20, -4).c(24, 10, 14, 14, 8, 6).l(-8, 6).c(-14, 14, -24, 10, -20, -4).z().d(), { fill: '#2a3142', stroke: DARK, sw: LINE }),
+        ellipse(-9, -2, 2.6, 2.6, { fill: '#8ab4ff' }), ellipse(10, -4, 2, 2, { fill: '#ff5f3b' }), ellipse(13, 0, 2, 2, { fill: '#4ade80' }),
+        ...nubs(body, bodyInk, 20, 4),
+      ], { tf: [tr(atX, atY), sc(PROP_SCALE)] })];
+    case 'book':
+      return [g([
+        path('M0 -2C-8 -8 -18 -8 -24 -5L-24 12C-18 9 -8 9 0 14C8 9 18 9 24 12L24 -5C18 -8 8 -8 0 -2Z', { fill: '#f4f1ea', stroke: DARK, sw: LINE }),
+        path('M0 -2L0 14', line('#c9c2b4', 1.6)),
+        path('M-19 0L-5 3M-19 5L-5 8M5 3L19 0M5 8L19 5', line('#9a9384', 1.2)),
+        path('M-24 12C-18 9 -8 9 0 14C8 9 18 9 24 12L24 15C18 12 8 12 0 17C-8 12 -18 12 -24 15Z', { fill: '#ff5f3b', stroke: DARK, sw: 1.4 }),
+        ...nubs(body, bodyInk, 25, 6),
+      ], { tf: [tr(atX, atY), sc(PROP_SCALE)] })];
+    case 'trophy':
+      return [g([
+        path('M-11 -14L11 -14L9 0C8 6 -8 6 -9 0Z', { fill: '#ffd23f', stroke: '#8a5a00', sw: LINE }),
+        path('M-11 -11C-18 -11 -18 -2 -9 -1M11 -11C18 -11 18 -2 9 -1', line('#8a5a00', 2.2)),
+        rect(-3, 4, 6, 6, { fill: '#e0a800' }), rect(-9, 10, 18, 5, { fill: '#6b4f12', stroke: DARK, sw: 1.2 }, 1.5),
+        ellipse(13, 6, 7, 6, { fill: body, stroke: bodyInk, sw: LINE }),
+      ], { tf: [tr(atX + 24, atY - 10), sc(PROP_SCALE)] })];
+    default:
+      return [];
+  }
+}
+
+/** Props worn on the head (drawn in head space). */
+export const HEAD_PROPS: ReadonlySet<StatusProp> = new Set(['goggles', 'headset', 'crown']);

package/src/avatar/render/types.ts

@@ -0,0 +1,84 @@
+/** The renderer's public option and pose types (avatars.md §3.3, §3.4, §3.11). */
+import type { AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import type { Expression, FaceParams } from '../face';
+
+/** Eight facings: `S` faces the viewer; `W`, `SW` and `NW` mirror `E`, `SE` and `NE`. */
+export type Facing = 'S' | 'SE' | 'E' | 'NE' | 'N' | 'NW' | 'W' | 'SW';
+
+/** The 4-direction aliases. */
+export type View = 'front' | 'back' | 'left' | 'right';
+
+/** Body poses on the blob; a future limbed body re-implements the same names. */
+export type BodyPose = 'idle' | 'walk' | 'run' | 'sit' | 'play' | 'wave' | 'cheer' | 'jump' | 'dance' | 'away';
+
+/** Runtime status props (never stored in the look). */
+export type StatusProp = 'goggles' | 'headset' | 'cards' | 'controller' | 'trophy' | 'crown' | 'book';
+
+/** How much of the character a frame shows. */
+export type Frame = 'head' | 'bust' | 'full';
+
+/** A point in rig units. */
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Where the eyes look: x right, y down, each in [−1, 1]. */
+export type LookDir = Point;
+
+/**
+ * Everything that moves: the face (an expression or raw parameters), gaze,
+ * blink, talk, the body pose and the status prop. The animator produces one
+ * per frame; a still render takes a partial one.
+ */
+export interface Pose {
+  readonly expression?: Expression;
+  /** Raw face parameters (wins over `expression`). */
+  readonly face?: FaceParams;
+  readonly look?: LookDir;
+  /** Extra lid closure, 0 … 1 (a blink). */
+  readonly blink?: number;
+  /** Extra mouth opening, 0 … 1 (talking). */
+  readonly talk?: number;
+  readonly body?: BodyPose;
+  /** Walk, dance or jump cycle phase, 0 … 1. */
+  readonly phase?: number;
+  readonly status?: StatusProp | null;
+  /** Reaction offset of the head, rig units. */
+  readonly bob?: Point;
+  /** Reaction tilt added to the head, degrees. */
+  readonly tilt?: number;
+  /** Reaction squash added to the head. */
+  readonly squash?: number;
+}
+
+/** Render options shared by every output. */
+export interface RenderOptions {
+  /** Output px of the frame's longer edge (default 48). */
+  readonly size?: number;
+  /** `head` badge (default), `bust` or `full` character. */
+  readonly frame?: Frame;
+  /** `badge` = the site's rounded panel and ring (the default for `head`); `none`; or a `#rrggbb`. */
+  readonly background?: 'badge' | 'none' | `#${string}`;
+  readonly facing?: Facing;
+  readonly view?: View;
+  readonly pose?: Pose;
+  /** The accessible name ("Sam's avatar"); omitted, the avatar is decorative. */
+  readonly title?: string;
+  /** A prefix for SVG ids when inlining many. */
+  readonly idPrefix?: string;
+  /** A soft light rim for dark scenes (the world; on by default in the atlas). */
+  readonly rim?: boolean;
+  /** The ground shadow (default: on for `full`). */
+  readonly shadow?: boolean;
+  /** Draws a stool under `sit` and `play` (pose sheets and previews). */
+  readonly stool?: boolean;
+}
+
+/** Anything a render accepts: a look, an `AV1…` code, or an object carrying a code. */
+export type LookLike = AvatarLook | string | { readonly code: string } | { readonly look: AvatarLook } | null | undefined;
+
+/** Named rig anchors (feet origin, y down), for name plates, bubbles, props and the world. */
+export type Anchor =
+  | 'feet' | 'body' | 'neck' | 'head' | 'eyeLine' | 'mouth' | 'hatTop' | 'nameplate' | 'bubble'
+  | 'seat' | 'prop' | 'shadow' | 'handL' | 'handR' | 'pod';

package/src/avatar/scene.ts

@@ -0,0 +1,119 @@
+/**
+ * The display list every renderer draws: a small tree of groups and shapes
+ * in rig units. The composer builds it once per pose; `toSvg` turns it into
+ * markup, `paintCanvas` draws it on a 2D canvas, and the Pixi and three.js
+ * adapters draw it through a canvas. Colours in a scene are always derived
+ * `#rrggbb` values or fixed constants, never caller text.
+ */
+
+/** One transform step, applied in order (SVG semantics). */
+export type TfOp =
+  | { readonly k: 't'; readonly x: number; readonly y: number }
+  | { readonly k: 's'; readonly x: number; readonly y: number }
+  | { readonly k: 'r'; readonly a: number }
+  | { readonly k: 'skx'; readonly a: number };
+
+/** How a shape is painted. */
+export interface Paint {
+  readonly fill?: string;
+  readonly fillOpacity?: number;
+  readonly stroke?: string;
+  readonly sw?: number;
+  readonly cap?: 'round' | 'butt';
+  readonly opacity?: number;
+  readonly evenOdd?: boolean;
+}
+
+/** A path shape. */
+export interface PathNode extends Paint {
+  readonly k: 'path';
+  readonly d: string;
+  readonly tf?: readonly TfOp[];
+}
+
+/** An ellipse (a circle when rx = ry). */
+export interface EllipseNode extends Paint {
+  readonly k: 'ellipse';
+  readonly cx: number;
+  readonly cy: number;
+  readonly rx: number;
+  readonly ry: number;
+  readonly tf?: readonly TfOp[];
+}
+
+/** A rectangle with optional rounded corners. */
+export interface RectNode extends Paint {
+  readonly k: 'rect';
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+  readonly r?: number;
+  readonly tf?: readonly TfOp[];
+}
+
+/** A line of text (overlay labels and FX glyphs). */
+export interface TextNode extends Paint {
+  readonly k: 'text';
+  readonly x: number;
+  readonly y: number;
+  readonly text: string;
+  readonly size: number;
+  readonly font: 'mono' | 'pixel';
+  readonly anchor?: 'start' | 'middle';
+  readonly bold?: boolean;
+}
+
+/** A clip region: the union of its shapes (even-odd when asked). */
+export interface Clip {
+  readonly shapes: readonly (PathNode | EllipseNode | RectNode)[];
+  readonly evenOdd?: boolean;
+}
+
+/** A group: a transform, an optional clip and opacity, and children. */
+export interface GroupNode {
+  readonly k: 'g';
+  readonly tf?: readonly TfOp[];
+  readonly clip?: Clip;
+  readonly opacity?: number;
+  /** A soft light rim around the silhouette (the world, §14.2). */
+  readonly rim?: boolean;
+  readonly children: readonly SceneNode[];
+}
+
+/** Anything in a scene. */
+export type SceneNode = GroupNode | PathNode | EllipseNode | RectNode | TextNode;
+
+/** A group helper that drops empty groups' wrapping. */
+export function g(children: readonly SceneNode[], opts: Omit<GroupNode, 'k' | 'children'> = {}): GroupNode {
+  return { k: 'g', ...opts, children };
+}
+
+/** A path helper. */
+export function path(d: string, paint: Paint, tf?: readonly TfOp[]): PathNode {
+  return { k: 'path', d, ...paint, ...(tf ? { tf } : {}) };
+}
+
+/** An ellipse helper. */
+export function ellipse(cx: number, cy: number, rx: number, ry: number, paint: Paint, tf?: readonly TfOp[]): EllipseNode {
+  return { k: 'ellipse', cx, cy, rx, ry, ...paint, ...(tf ? { tf } : {}) };
+}
+
+/** A rect helper. */
+export function rect(left: number, top: number, w: number, h: number, paint: Paint, r?: number): RectNode {
+  return { k: 'rect', x: left, y: top, w, h, ...paint, ...(r === undefined ? {} : { r }) };
+}
+
+/** A translate step. */
+export const tr = (dx: number, dy: number): TfOp => ({ k: 't', x: dx, y: dy });
+/** A scale step (uniform when `sy` is omitted). */
+export const sc = (sx: number, sy = sx): TfOp => ({ k: 's', x: sx, y: sy });
+/** A rotate step, degrees. */
+export const rot = (a: number): TfOp => ({ k: 'r', a });
+/** A horizontal skew step, degrees. */
+export const skewX = (a: number): TfOp => ({ k: 'skx', a });
+
+/** A round-joined stroke paint. */
+export function line(colour: string, width: number, cap: 'round' | 'butt' = 'round', opacity?: number): Paint {
+  return { fill: 'none', stroke: colour, sw: width, cap, ...(opacity === undefined ? {} : { opacity }) };
+}

package/src/avatar-pixi.ts

@@ -0,0 +1,20 @@
+/**
+ * `@diffenderfer-games/hub/avatar/pixi`: avatars in PixiJS. Pass your PIXI
+ * namespace (the hub has no pixi dependency):
+ *
+ * ```ts
+ * import * as PIXI from 'pixi.js';
+ * import { ready, animator } from '@diffenderfer-games/hub/avatar';
+ * import { pixiAvatar } from '@diffenderfer-games/hub/avatar/pixi';
+ *
+ * await ready();
+ * const face = pixiAvatar(PIXI, seat.look, { size: 64, animator: animator(seat.look, { seed: seat.userId }) });
+ * stage.addChild(face.view);
+ * app.ticker.add(() => face.update(performance.now()));
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { pixiAvatar, avatarTexture, type PixiAvatar, type PixiAvatarOptions } from './avatar/adapters/pixi-avatar';
+export { createCrowd, type AvatarCrowd, type CrowdMember, type CrowdOptions } from './avatar/adapters/pixi-crowd';
+export type { PixiContainer, PixiNs, PixiSprite, PixiTexture } from './avatar/adapters/pixi-types';

package/src/avatar-svg.ts

@@ -0,0 +1,21 @@
+/**
+ * `@diffenderfer-games/hub/avatar/svg`: avatars as SVG markup with no DOM,
+ * for servers, workers and server-side rendering. The same renderer as
+ * `@diffenderfer-games/hub/avatar` (`render.svg`), without the DOM, canvas
+ * and animation outputs.
+ *
+ * ```ts
+ * import { ready, renderSvg } from '@diffenderfer-games/hub/avatar/svg';
+ *
+ * await ready();
+ * const markup = renderSvg(player.look, { size: 64, pose: { expression: 'happy' } });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { decodeLook, defaultLook, encodeLook, type AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+export { ready } from './avatar/art-store';
+export { EXPRESSION_NAMES, isExpression, type Expression } from './avatar/face';
+export { renderSvg } from './avatar/outputs/svg';
+export { describe } from './avatar/describe';
+export type { Facing, Frame, LookLike, Pose, RenderOptions } from './avatar/render/types';

package/src/avatar-three.ts

@@ -0,0 +1,18 @@
+/**
+ * `@diffenderfer-games/hub/avatar/three`: avatars in three.js, as a
+ * `CanvasTexture` or a billboard `Sprite`. Pass your THREE namespace (the hub
+ * has no three dependency):
+ *
+ * ```ts
+ * import * as THREE from 'three';
+ * import { ready } from '@diffenderfer-games/hub/avatar';
+ * import { avatarSprite } from '@diffenderfer-games/hub/avatar/three';
+ *
+ * await ready();
+ * const { sprite } = avatarSprite(THREE, me.look, { frame: 'head', size: 128, height: 0.4 });
+ * helmet.add(sprite);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { avatarCanvasTexture, avatarSprite, type ThreeAvatarOptions, type ThreeAvatarTexture, type ThreeNs, type ThreeTextureNs } from './avatar/adapters/three';