@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/avatar/render/walker-parts.ts

@@ -0,0 +1,121 @@
+/**
+ * The walker's drawing parts (`figure: 'walker'`): limbs as outlined round
+ * strokes, the shirt, trousers and shoes. Colours come from the look: the
+ * shirt is the body colour, the trousers and shoes are picked from the body
+ * colour so they always stand apart from the shirt.
+ */
+import { lightness, outline, shade } from '../colour';
+import { Path } from '../geom';
+import { ellipse, g, path, sc, tr, type SceneNode } from '../scene';
+import type { Colours } from './colours';
+import { LINE } from './context';
+
+/** A point in rig units. */
+export type Vec = readonly [number, number];
+
+/** The walker's clothes, derived from a look's colours. */
+export interface Outfit {
+  readonly trousers: string;
+  readonly trousersInk: string;
+  readonly shoes: string;
+  readonly shoesInk: string;
+}
+
+const TROUSERS = ['#34466e', '#2e323f', '#6a5642', '#4a3a60', '#3c5a4c', '#5a3a3a'] as const;
+const SHOES = ['#2c2430', '#f1ece2', '#5a3a2a', '#2c2430'] as const;
+
+/** A small stable hash of a colour string. */
+function hashOf(text: string): number {
+  let hash = 7;
+  for (let i = 0; i < text.length; i++) {
+    hash = (hash * 31 + text.charCodeAt(i)) >>> 0;
+  }
+  return hash;
+}
+
+/** Trousers and shoes for a shirt colour: a trouser tone at least a little lighter or darker than the shirt. */
+export function outfitFor(c: Colours): Outfit {
+  const hash = hashOf(c.body);
+  const shirt = lightness(c.body);
+  let trousers: string = TROUSERS[hash % TROUSERS.length] ?? TROUSERS[0];
+  for (let i = 1; i < TROUSERS.length && Math.abs(lightness(trousers) - shirt) < 0.12; i++) {
+    trousers = TROUSERS[(hash + i) % TROUSERS.length] ?? trousers;
+  }
+  const shoes: string = SHOES[(hash >>> 4) % SHOES.length] ?? SHOES[0];
+  return { trousers, trousersInk: outline(trousers), shoes, shoesInk: outline(shoes) };
+}
+
+/** A polyline as a path `d`. */
+function polyline(points: readonly Vec[]): string {
+  const line = new Path();
+  points.forEach(([px, py], i) => (i === 0 ? line.m(px, py) : line.l(px, py)));
+  return line.d();
+}
+
+/** A limb: a round stroke with a tonal outline under it. */
+export function limb(points: readonly Vec[], width: number, fill: string, ink: string): SceneNode[] {
+  const d = polyline(points);
+  return [
+    path(d, { fill: 'none', stroke: ink, sw: width + LINE * 1.3, cap: 'round' }),
+    path(d, { fill: 'none', stroke: fill, sw: width, cap: 'round' }),
+  ];
+}
+
+/** A shoe at a foot point, nudged along the facing. */
+export function shoe(at: Vec, forward: Vec, o: Outfit): SceneNode {
+  return ellipse(at[0] + forward[0] * 2.4, at[1] + forward[1] * 1.6 - 1.5, 6.2 + Math.abs(forward[0]) * 1.4, 3.8, { fill: o.shoes, stroke: o.shoesInk, sw: LINE * 0.8 });
+}
+
+/** A hand. */
+export function hand(c: Colours, at: Vec): SceneNode {
+  return ellipse(at[0], at[1], 4.3, 4.3, { fill: c.skin, stroke: c.skinInk, sw: LINE * 0.8 });
+}
+
+/** The torso's outline: shoulders at `top`, the hem at `hem`, `w` its width factor (narrower when turned). */
+export function torsoPath(w: number, top: number, hem: number): string {
+  const shoulder = 17.5 * w;
+  const waist = 14.5 * w;
+  const hip = 15.5 * w;
+  const mid = (top + hem) / 2 + 4;
+  return new Path()
+    .m(-shoulder, top + 6)
+    .c(-shoulder, top - 1, -shoulder + 5, top - 3, -shoulder * 0.35, top - 3)
+    .l(shoulder * 0.35, top - 3)
+    .c(shoulder - 5, top - 3, shoulder, top - 1, shoulder, top + 6)
+    .l(waist, mid)
+    .l(hip, hem)
+    .q(0, hem + 3, -hip, hem)
+    .l(-waist, mid)
+    .z()
+    .d();
+}
+
+/** The shirt: a shade base, the lit front, the outline, and the neckline (front) or collar (back). */
+export function shirt(c: Colours, w: number, top: number, hem: number, lean: number, isBack: boolean): SceneNode[] {
+  const d = torsoPath(w, top, hem);
+  const cy = (top + hem) / 2;
+  const nodes: SceneNode[] = [
+    path(d, { fill: c.bodyShade }),
+    g([path(d, { fill: c.body })], { tf: [tr(-1.5 - lean * 2, cy - 1.5), sc(0.9, 0.94), tr(0, -cy)] }),
+    path(`M${String(-15 * w)} ${String(hem - 2.5)}Q0 ${String(hem + 0.5)} ${String(15 * w)} ${String(hem - 2.5)}`, { fill: 'none', stroke: shade(c.bodyShade), sw: 2.2, opacity: 0.7 }),
+    path(d, { fill: 'none', stroke: c.bodyInk, sw: LINE }),
+  ];
+  const neckX = lean * 7;
+  if (isBack) {
+    nodes.push(path(`M${String(neckX - 6)} ${String(top - 2)}Q${String(neckX)} ${String(top + 1.5)} ${String(neckX + 6)} ${String(top - 2)}`, { fill: 'none', stroke: c.bodyShade, sw: 3 }));
+  } else {
+    nodes.push(path(`M${String(neckX - 6 * w)} ${String(top - 2.6)}Q${String(neckX)} ${String(top + 6)} ${String(neckX + 6 * w)} ${String(top - 2.6)}Z`, { fill: c.skin, stroke: c.bodyInk, sw: LINE * 0.8 }));
+  }
+  return nodes;
+}
+
+/** The seat of the trousers joining the legs under the hem. */
+export function hips(o: Outfit, w: number, hipY: number): SceneNode {
+  const half = 12 * w;
+  return path(new Path().m(-half, hipY - 4).l(half, hipY - 4).l(half, hipY + 4).q(0, hipY + 9, -half, hipY + 4).z().d(), { fill: o.trousers, stroke: o.trousersInk, sw: LINE * 0.8 });
+}
+
+/** The neck under the head. */
+export function neck(c: Colours, top: number, dx: number): SceneNode {
+  return path(new Path().m(dx - 4.5, top - 10).l(dx + 4.5, top - 10).l(dx + 4.5, top).l(dx - 4.5, top).z().d(), { fill: c.skinShade, stroke: c.skinInk, sw: LINE * 0.6 });
+}

package/src/avatar/render/walker.ts

@@ -0,0 +1,199 @@
+/**
+ * The world walker (`figure: 'walker'`): a small full-body character for
+ * maps and crowds, with legs, arms, a shirt, trousers and shoes, and the
+ * head drawn smaller on top ({@link WALKER_HEAD_SCALE}). It takes the blob's
+ * pose names: `walk` and `run` swing the legs and arms along the facing,
+ * `sit` folds the legs over a seat, `idle` breathes, `wave` and `cheer` lift
+ * the arms.
+ *
+ * Standing, the origin is the feet. Sitting (`sit`, `play`), the origin is
+ * the seat: the hips rest on it and the feet hang {@link WALKER_SEAT_DROP}
+ * units below, on the floor in front of it.
+ */
+import { ellipse, type SceneNode } from '../scene';
+import type { BodyLayout } from './body';
+import type { Colours } from './colours';
+import type { BodyPose } from './types';
+import { hand, hips, limb, neck, outfitFor, shirt, shoe, type Outfit, type Vec } from './walker-parts';
+
+/** The head's scale on a walker (the blob draws it at 1). */
+export const WALKER_HEAD_SCALE = 0.58;
+
+/** How far below the seat a sitter's feet reach (rig units). */
+export const WALKER_SEAT_DROP = 26;
+
+/** Heights of the hips, shoulders and head centre above the origin. */
+interface Heights {
+  readonly hip: number;
+  readonly shoulder: number;
+  readonly head: number;
+}
+
+const STANDING: Heights = { hip: -35, shoulder: -72, head: -103 };
+const SEATED: Heights = { hip: -3, shoulder: -40, head: -71 };
+const LEG = 32;
+const UPPER_ARM = 13;
+const FOREARM = 12;
+const LEG_W = 10.5;
+const SLEEVE_W = 10;
+const ARM_W = 7.5;
+const DEG = Math.PI / 180;
+
+/** A walker's layout: the blob's fields plus where the head goes and its scale. */
+export interface WalkerLayout extends BodyLayout {
+  readonly headY: number;
+  readonly headScale: number;
+}
+
+/** One side of the body: −1 is the character's right, +1 its left. */
+type Side = -1 | 1;
+
+/** The view of a facing: how far it is turned, which way is forward on screen. */
+interface View {
+  /** sin of the turn: 0 front or back, ~1 side on. */
+  readonly side: number;
+  /** cos of the turn: 1 front, −1 back. */
+  readonly front: number;
+  /** Forward on the floor, in screen units per unit (y is foreshortened). */
+  readonly forward: Vec;
+  readonly isBack: boolean;
+  /** The torso's width factor. */
+  readonly width: number;
+}
+
+function viewOf(angleDeg: number): View {
+  const side = Math.sin(angleDeg * DEG);
+  const front = Math.cos(angleDeg * DEG);
+  return { side, front, forward: [side, front * 0.45], isBack: angleDeg > 90, width: 1 - 0.36 * Math.abs(side) };
+}
+
+/** A body side's screen x for a lateral distance (sides overlap when turned). */
+const lateralX = (v: View, sideOf: Side, distance: number): number => sideOf * distance * v.front;
+
+/** How near the viewer a side is (> 0: drawn in front when turned). */
+const nearness = (v: View, sideOf: Side): number => -sideOf * v.side;
+
+const add = (a: Vec, b: Vec, k = 1): Vec => [a[0] + b[0] * k, a[1] + b[1] * k];
+
+/** What each limb does in a pose. */
+interface Limbs {
+  /** Foot (standing) or knee-then-foot (sitting) per side. */
+  readonly leg: (sideOf: Side) => readonly [Vec, Vec, Vec];
+  readonly arm: (sideOf: Side) => readonly [Vec, Vec, Vec];
+}
+
+function standingLimbs(v: View, h: Heights, pose: BodyPose, phase: number, bob: number): Limbs {
+  const isRun = pose === 'run';
+  const isWalking = pose === 'walk' || isRun || pose === 'dance';
+  const stride = isRun ? 38 : 27;
+  const swingOf = (sideOf: Side): number => (isWalking ? Math.sin((phase + (sideOf === 1 ? 0 : 0.5)) * Math.PI * 2) : 0);
+  return {
+    leg: (sideOf) => {
+      const hip: Vec = [lateralX(v, sideOf, 6), h.hip + bob];
+      const swing = swingOf(sideOf);
+      const lift = isWalking ? Math.max(0, Math.cos((phase + (sideOf === 1 ? 0 : 0.5)) * Math.PI * 2)) * (isRun ? 7 : 4.5) : 0;
+      const reach = Math.sin(stride * DEG) * LEG * swing;
+      const foot: Vec = [hip[0] + v.forward[0] * reach, -bob * 0.2 + v.forward[1] * reach - lift];
+      const knee: Vec = [(hip[0] + foot[0]) / 2 + v.forward[0] * lift * 0.9, (hip[1] + foot[1]) / 2 + v.forward[1] * lift * 0.9];
+      return [hip, knee, foot];
+    },
+    arm: (sideOf) => {
+      const shoulder: Vec = [lateralX(v, sideOf, 15.5 * v.width) + v.forward[0] * 1.5, h.shoulder + 4 + bob];
+      const out = sideOf * v.front * 2.2;
+      if (pose === 'cheer' || (pose === 'wave' && sideOf === -1)) {
+        const wave = pose === 'wave' ? Math.sin(phase * Math.PI * 2) * 4 : 0;
+        const elbow: Vec = [shoulder[0] + out * 3, shoulder[1] - 10];
+        return [shoulder, elbow, [elbow[0] + out * 1.5 + wave, elbow[1] - 12]];
+      }
+      const swing = isWalking ? -swingOf(sideOf) * (isRun ? 1.3 : 1) : Math.sin(phase * Math.PI * 2) * 0.06;
+      const reach = Math.sin(24 * DEG) * swing;
+      const elbow: Vec = [shoulder[0] + out + v.forward[0] * UPPER_ARM * reach * 0.6, shoulder[1] + UPPER_ARM + v.forward[1] * UPPER_ARM * reach];
+      const wrist: Vec = [elbow[0] + out * 0.4 + v.forward[0] * FOREARM * reach * 1.6, elbow[1] + FOREARM - Math.abs(reach) * 3 + v.forward[1] * FOREARM * reach];
+      return [shoulder, elbow, wrist];
+    },
+  };
+}
+
+function seatedLimbs(v: View, h: Heights, pose: BodyPose): Limbs {
+  const thigh: Vec = [v.forward[0] * 15, v.forward[1] * 16];
+  return {
+    leg: (sideOf) => {
+      const hip: Vec = [lateralX(v, sideOf, 6), h.hip];
+      const knee = add(hip, thigh);
+      return [hip, knee, [knee[0] + v.forward[0] * 3, WALKER_SEAT_DROP - 2]];
+    },
+    arm: (sideOf) => {
+      const shoulder: Vec = [lateralX(v, sideOf, 15.5 * v.width) + v.forward[0] * 1.5, h.shoulder + 4];
+      const elbow: Vec = [shoulder[0] + sideOf * v.front * 2 + v.forward[0] * 3, shoulder[1] + UPPER_ARM];
+      const lap = add([lateralX(v, sideOf, pose === 'play' ? 4 : 7), h.hip - 4], thigh, pose === 'play' ? 0.9 : 0.6);
+      return [shoulder, elbow, lap];
+    },
+  };
+}
+
+/** The walker's drawing for a pose, at a facing angle (0 = S, 180 = N; west facings are mirrored by the caller). */
+export function walkerLayout(c: Colours, pose: BodyPose, angleDeg: number, phase: number, outfit: Outfit = outfitFor(c)): WalkerLayout {
+  const v = viewOf(angleDeg);
+  const isSitting = pose === 'sit' || pose === 'play';
+  const h = isSitting ? SEATED : STANDING;
+  const cycle = Math.sin(phase * Math.PI * 2);
+  const isWalking = pose === 'walk' || pose === 'run' || pose === 'dance';
+  const hop = pose === 'jump' || pose === 'cheer' ? Math.abs(Math.sin(phase * Math.PI)) * (pose === 'jump' ? 16 : 8) : 0;
+  const bob = isWalking ? -2.2 * (1 - Math.abs(cycle)) : pose === 'idle' ? cycle * 0.6 : 0;
+  const limbs = isSitting ? seatedLimbs(v, h, pose) : standingLimbs(v, h, pose, phase, bob);
+  const o = outfit;
+  const [farSide, nearSide]: readonly [Side, Side] = nearness(v, 1) > nearness(v, -1) ? [-1, 1] : [1, -1];
+  const isTurned = Math.abs(v.side) > 0.3;
+  const lean = v.side * (isSitting ? 0.6 : 1);
+  const armNodes = (sideOf: Side): SceneNode[] => {
+    const [shoulder, elbow, wrist] = limbs.arm(sideOf);
+    return [...limb([shoulder, elbow, wrist], ARM_W, c.skin, c.skinInk), ...limb([shoulder, add(shoulder, [elbow[0] - shoulder[0], elbow[1] - shoulder[1]], 0.62)], SLEEVE_W, c.body, c.bodyInk), hand(c, wrist)];
+  };
+  const legNodes = (sideOf: Side): SceneNode[] => {
+    const points = limbs.leg(sideOf);
+    const foot = points[2];
+    return [...limb(points, LEG_W, o.trousers, o.trousersInk), shoe(foot, v.forward, o)];
+  };
+  const torso = shirt(c, v.width, h.shoulder + (isWalking ? bob : 0), h.hip + 3 + (isWalking ? bob : 0), lean, v.isBack);
+  // Seated with our back to us, the arms reach forward and the legs are under the seat: both hide behind the back.
+  const isTucked = isSitting && v.isBack;
+  const behind: SceneNode[] = isTucked ? [...armNodes(farSide), ...armNodes(nearSide)] : isTurned ? armNodes(farSide) : [];
+  // Sitting facing us, the thighs come toward the viewer over the shirt's hem.
+  const isLegsFirst = v.isBack || !isSitting;
+  const legs = isTucked ? [] : [...legNodes(farSide), ...legNodes(nearSide)];
+  const body: SceneNode[] = [
+    ...(isLegsFirst ? legs : []),
+    hips(o, v.width, h.hip + (isWalking ? bob : 0)),
+    neck(c, h.shoulder + bob, v.forward[0] * 2),
+    ...torso,
+    ...(isLegsFirst ? [] : legs),
+    ...(isTucked ? [] : isTurned ? armNodes(nearSide) : [...armNodes(-1), ...armNodes(1)]),
+  ];
+  const prop = add([0, h.hip - 12], v.forward, 8);
+  return {
+    behind, body, front: [],
+    headDx: v.forward[0] * 1.5, headDy: 0, headY: h.head + bob * 1.1, headScale: WALKER_HEAD_SCALE,
+    tilt: isWalking ? v.side * 2 : 0, lift: hop, prop: { x: prop[0], y: prop[1] },
+  };
+}
+
+const GREY = '#6f7787';
+const GREY_INK = '#5c6474';
+
+/** Every colour slot in the silhouette grey. */
+const GREY_COLOURS: Colours = {
+  skin: GREY, skinShade: GREY, skinLight: GREY, skinInk: GREY_INK, eyeRim: GREY, hair: GREY, hairShade: GREY, hairLight: GREY,
+  hairInk: GREY_INK, hairBuzz: GREY, brow: GREY, beard: GREY, beardShade: GREY, beardInk: GREY_INK, stubble: GREY, eye: GREY,
+  eyeDark: GREY, body: GREY, bodyShade: GREY, bodyLight: GREY, bodyInk: GREY_INK,
+};
+
+/** The grey walker shown before the art loads (or for a hidden player): its nodes, head centre and top. */
+export function walkerSilhouette(): { readonly nodes: readonly SceneNode[]; readonly headY: number; readonly top: number } {
+  const b = walkerLayout(GREY_COLOURS, 'idle', 0, 0, { trousers: GREY, trousersInk: GREY_INK, shoes: GREY, shoesInk: GREY_INK });
+  const r = 46 * WALKER_HEAD_SCALE;
+  return {
+    nodes: [...b.behind, ...b.body, ellipse(0, b.headY, r, r * 1.05, { fill: GREY })],
+    headY: b.headY,
+    top: b.headY - r - 4,
+  };
+}

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';

package/src/avatar.ts

@@ -0,0 +1,63 @@
+/**
+ * `@diffenderfer-games/hub/avatar`: draw players' avatars in any game.
+ *
+ * ```ts
+ * import { ready, render, animator } from '@diffenderfer-games/hub/avatar';
+ *
+ * await ready();                                   // loads the art once
+ * el.innerHTML = render.svg(seat.look, { size: 48 });
+ * const anim = animator(seat.look, { seed: seat.userId });
+ * anim.express('happy');
+ * render.canvas(ctx, seat.look, { x, y, size: 64, pose: anim.pose(now) });
+ * ```
+ *
+ * The art loads lazily (`ready()`); before it does, renders draw the
+ * silhouette. Zero dependencies; the Pixi and three.js adapters take the
+ * library as an argument (`/avatar/pixi`, `/avatar/three`). Docs: "Avatars"
+ * in docs/hub.md.
+ *
+ * @packageDocumentation
+ */
+import { renderBitmap, renderDataUrl } from './avatar/outputs/bitmap';
+import { renderCanvas, renderCanvasAt } from './avatar/outputs/canvas';
+import { renderElement } from './avatar/outputs/element';
+import { renderSvg } from './avatar/outputs/svg';
+
+export {
+  ACCESSORY_SLOTS, CATALOG, CATALOG_REVISION, DEFAULT_GEN, FRAME_PRESETS, LOOK_CODE_PREFIX, PALETTES, SECOND_COLOUR_CODE,
+  canonicalLook, decodeLook, defaultLook, distinctLooks, encodeLook, isLookCode, isTinted, isValidLook, lookProblem,
+  normaliseHex, partById, partName, partsOf, randomLook, resolveColour, sameLook, seededRng,
+  type AccessorySlot, type AvatarLook, type CatalogEntry, type DecodedLook, type LookAccessory, type LookColour,
+  type LookPart, type LookProblem, type PaletteName, type PartCategory, type Preset, type RandomLookOptions, type Rng,
+} from '@diffenderfer-games/hub-contract/avatar';
+export { ready, onArtReady } from './avatar/art-store';
+export { animator, Animator, type AnimatorOptions, type At, type Feeling } from './avatar/animator/animator';
+export { REACTIONS, type Reaction } from './avatar/animator/reactions';
+export { EXPRESSIONS, EXPRESSION_NAMES, expressionFromEmote, isExpression, mix, type BrowParams, type Expression, type FaceExtra, type FaceParams, type MouthParams } from './avatar/face';
+export { facingFrom, layout, lookToward } from './avatar/layout';
+export { avatarEmoji, describe } from './avatar/describe';
+export { defineAvatarElement } from './avatar/outputs/custom-element';
+export type { AvatarElement } from './avatar/outputs/element';
+export type { CanvasPlacement } from './avatar/outputs/canvas';
+export { overlays, type ActivityIcon, type Overlay, type ReactionGlyph } from './avatar/overlays';
+export { overlaySvg, paintOverlay } from './avatar/outputs/overlay-svg';
+export { catalog } from './avatar/catalog-view';
+export { composeAvatar, HEAD_Y, type Composed } from './avatar/render/compose';
+export { WALKER_HEAD_SCALE, WALKER_SEAT_DROP } from './avatar/render/walker';
+export { paintNodes, type Ctx2D } from './avatar/outputs/canvas-paint';
+export { sceneToSvg } from './avatar/outputs/svg-markup';
+export { toCode, toLook } from './avatar/look-like';
+export { contrast, deltaE, lightness } from './avatar/colour';
+export type { SceneNode } from './avatar/scene';
+export type { Anchor, BodyPose, Facing, Figure, Frame, LookDir, LookLike, Point, Pose, RenderOptions, StatusProp, View } from './avatar/render/types';
+export { AvatarAtlas, createAtlas, type AtlasFrame, type AtlasOptions } from './avatar/atlas';
+
+/** Every output: SVG markup, a live element, Canvas 2D, a bitmap or a data URL. */
+export const render = {
+  svg: renderSvg,
+  element: renderElement,
+  canvas: renderCanvas,
+  canvasAt: renderCanvasAt,
+  bitmap: renderBitmap,
+  dataUrl: renderDataUrl,
+};

package/src/core/avatar/avatar-cache.ts

@@ -0,0 +1,95 @@
+/**
+ * The device's avatar cache (avatars.md §5.6), so faces render offline:
+ * your own look (`hub:avatar:me`, read synchronously at startup) and an LRU
+ * of other players' codes (`hub:avatar:cache`, 200 entries).
+ */
+import { isLookCode } from '@diffenderfer-games/hub-contract/avatar';
+import { isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import type { KeyValueStore } from '../storage/key-value';
+
+/** Your own look as cached. */
+export interface CachedMine {
+  readonly userId: number;
+  readonly code: string;
+  readonly isDefault: boolean;
+  readonly updatedAt: number;
+}
+
+const MINE_KEY = 'hub:avatar:me';
+const OTHERS_KEY = 'hub:avatar:cache';
+const OTHERS_MAX = 200;
+
+/** The device cache over a key-value store. */
+export class AvatarCache {
+  private readonly store: KeyValueStore;
+  private others: Map<number, string> | null = null;
+
+  constructor(store: KeyValueStore) {
+    this.store = store;
+  }
+
+  /** Your cached look, or `null` (never cached, or another player's on this device). */
+  readMine(userId: number | null): CachedMine | null {
+    const parsed = parseJsonText(this.store.read(MINE_KEY) ?? '');
+    if (!isRecord(parsed)) {
+      return null;
+    }
+    const id = optionalNumber(parsed.userId);
+    const code = optionalString(parsed.code);
+    if (id === undefined || code === undefined || !isLookCode(code) || (userId !== null && id !== userId)) {
+      return null;
+    }
+    return { userId: id, code, isDefault: parsed.isDefault === true, updatedAt: optionalNumber(parsed.updatedAt) ?? 0 };
+  }
+
+  /** Remember your look. */
+  writeMine(mine: CachedMine): void {
+    this.store.write(MINE_KEY, JSON.stringify(mine));
+    this.remember(mine.userId, mine.code);
+  }
+
+  /** A player's cached code, or `undefined`. */
+  codeOf(userId: number): string | undefined {
+    return this.loadOthers().get(userId);
+  }
+
+  /** Remember a player's code (most recent last; the oldest drop past 200). */
+  remember(userId: number, code: string): void {
+    if (code === '') {
+      return;
+    }
+    const others = this.loadOthers();
+    if (others.get(userId) === code) {
+      return;
+    }
+    others.delete(userId);
+    others.set(userId, code);
+    while (others.size > OTHERS_MAX) {
+      const oldest = others.keys().next().value;
+      if (oldest === undefined) {
+        break;
+      }
+      others.delete(oldest);
+    }
+    this.store.write(OTHERS_KEY, JSON.stringify([...others]));
+  }
+
+  private loadOthers(): Map<number, string> {
+    if (this.others !== null) {
+      return this.others;
+    }
+    const others = new Map<number, string>();
+    const parsed = parseJsonText(this.store.read(OTHERS_KEY) ?? '[]');
+    if (Array.isArray(parsed)) {
+      for (const entry of parsed) {
+        const id = Array.isArray(entry) ? optionalNumber(entry[0]) : undefined;
+        const code = Array.isArray(entry) ? optionalString(entry[1]) : undefined;
+        if (id !== undefined && code !== undefined && isLookCode(code)) {
+          others.set(id, code);
+        }
+      }
+    }
+    this.others = others;
+    return others;
+  }
+}