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

package/src/avatar/geom.ts

@@ -0,0 +1,173 @@
+/**
+ * A tiny path toolkit. Every shape is authored as points in head-local units
+ * (1 unit = 1/100 of the head height), so a whole part can be warped point by
+ * point (the 2.5D head turn) before it becomes an SVG `d` string.
+ */
+
+/** A point; the optional third flag marks a sharp corner in {@link blob}. */
+export type Pt = readonly [number, number] | readonly [number, number, 'c'];
+
+/** A point warp (the head turn). */
+export type Warp = (px: number, py: number) => readonly [number, number];
+
+interface Cmd {
+  readonly c: 'M' | 'L' | 'C' | 'Q' | 'Z';
+  readonly p: readonly number[];
+}
+
+/** Rounds to one decimal and drops a trailing `.0` and negative zero. */
+export function n(v: number): string {
+  const r = Math.round(v * 10) / 10;
+  return Object.is(r, -0) ? '0' : String(r);
+}
+
+/** A path of absolute M/L/C/Q/Z commands that can be warped as a whole. */
+export class Path {
+  private readonly cmds: Cmd[] = [];
+
+  m(px: number, py: number): this {
+    this.cmds.push({ c: 'M', p: [px, py] });
+    return this;
+  }
+
+  l(px: number, py: number): this {
+    this.cmds.push({ c: 'L', p: [px, py] });
+    return this;
+  }
+
+  c(x1: number, y1: number, x2: number, y2: number, px: number, py: number): this {
+    this.cmds.push({ c: 'C', p: [x1, y1, x2, y2, px, py] });
+    return this;
+  }
+
+  q(x1: number, y1: number, px: number, py: number): this {
+    this.cmds.push({ c: 'Q', p: [x1, y1, px, py] });
+    return this;
+  }
+
+  z(): this {
+    this.cmds.push({ c: 'Z', p: [] });
+    return this;
+  }
+
+  /** Appends every command of another path. */
+  add(other: Path): this {
+    this.cmds.push(...other.cmds);
+    return this;
+  }
+
+  /** The lowest y of any point (control points included, so it never under-reports). */
+  bottom(): number {
+    return this.cmds.reduce((low, { p }) => p.reduce((lo, v, i) => (i % 2 === 1 ? Math.max(lo, v) : lo), low), -Infinity);
+  }
+
+  /** The SVG `d` string, optionally warping every point. */
+  d(warp?: Warp): string {
+    return this.cmds.map(({ c, p }) => {
+      if (c === 'Z') {
+        return 'Z';
+      }
+      const out: string[] = [];
+      for (let i = 0; i < p.length; i += 2) {
+        const px = p[i] ?? 0;
+        const py = p[i + 1] ?? 0;
+        const [wx, wy] = warp ? warp(px, py) : [px, py];
+        out.push(`${n(wx)} ${n(wy)}`);
+      }
+      return c + out.join(' ');
+    }).join('');
+  }
+}
+
+/** A point by index, or the origin. */
+const at = (pts: readonly Pt[], i: number): Pt => pts[i] ?? [0, 0];
+
+/**
+ * A smooth Catmull-Rom curve through the points (cubic segments). Points
+ * flagged `'c'` become sharp corners.
+ */
+export function blob(pts: readonly Pt[], isClosed = true, tension = 1, into = new Path()): Path {
+  const count = pts.length;
+  if (count === 0) {
+    return into;
+  }
+  const wrap = (i: number): Pt => (isClosed ? at(pts, (i + count) % count) : at(pts, Math.max(0, Math.min(count - 1, i))));
+  const tangent = (i: number): readonly [number, number] => {
+    const p = wrap(i);
+    if (p[2] === 'c' || (!isClosed && (i === 0 || i === count - 1))) {
+      return [0, 0];
+    }
+    const a = wrap(i - 1);
+    const b = wrap(i + 1);
+    return [((b[0] - a[0]) * tension) / 6, ((b[1] - a[1]) * tension) / 6];
+  };
+  const first = at(pts, 0);
+  into.m(first[0], first[1]);
+  const segs = isClosed ? count : count - 1;
+  for (let i = 0; i < segs; i += 1) {
+    const p1 = wrap(i);
+    const p2 = wrap(i + 1);
+    const t1 = tangent(i);
+    const t2 = tangent(i + 1);
+    into.c(p1[0] + t1[0], p1[1] + t1[1], p2[0] - t2[0], p2[1] - t2[1], p2[0], p2[1]);
+  }
+  if (isClosed) {
+    into.z();
+  }
+  return into;
+}
+
+/** Points along an ellipse arc; angles in degrees, 0 = right, 90 = down. */
+export function arc(cx: number, cy: number, rx: number, ry: number, a0: number, a1: number, steps: number): Pt[] {
+  const out: Pt[] = [];
+  for (let i = 0; i <= steps; i += 1) {
+    const a = ((a0 + ((a1 - a0) * i) / steps) * Math.PI) / 180;
+    out.push([cx + rx * Math.cos(a), cy + ry * Math.sin(a)]);
+  }
+  return out;
+}
+
+/**
+ * A scalloped edge: one outward bump between each pair of points (quadratic
+ * curves), for curls and clouds. `side` 1 bumps to the left of travel.
+ */
+export function scallop(pts: readonly Pt[], bump: number, isClosed: boolean, side = 1, into = new Path()): Path {
+  const count = pts.length;
+  const first = at(pts, 0);
+  into.m(first[0], first[1]);
+  const segs = isClosed ? count : count - 1;
+  for (let i = 0; i < segs; i += 1) {
+    const a = at(pts, i);
+    const b = at(pts, (i + 1) % count);
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    const len = Math.hypot(dx, dy) || 1;
+    into.q((a[0] + b[0]) / 2 + (dy / len) * bump * side, (a[1] + b[1]) / 2 + (-dx / len) * bump * side, b[0], b[1]);
+  }
+  if (isClosed) {
+    into.z();
+  }
+  return into;
+}
+
+/** A rounded rectangle path. */
+export function roundedRect(px: number, py: number, w: number, h: number, r: number): Path {
+  return new Path()
+    .m(px + r, py).l(px + w - r, py).q(px + w, py, px + w, py + r).l(px + w, py + h - r).q(px + w, py + h, px + w - r, py + h)
+    .l(px + r, py + h).q(px, py + h, px, py + h - r).l(px, py + r).q(px, py, px + r, py).z();
+}
+
+/** A closed ellipse as cubic curves (never Pixi's `arc()`, which draws a stray line from the origin). */
+export function ellipsePath(cx: number, cy: number, rx: number, ry: number): Path {
+  const k = 0.5523;
+  return new Path()
+    .m(cx + rx, cy)
+    .c(cx + rx, cy + ry * k, cx + rx * k, cy + ry, cx, cy + ry)
+    .c(cx - rx * k, cy + ry, cx - rx, cy + ry * k, cx - rx, cy)
+    .c(cx - rx, cy - ry * k, cx - rx * k, cy - ry, cx, cy - ry)
+    .c(cx + rx * k, cy - ry, cx + rx, cy - ry * k, cx + rx, cy)
+    .z();
+}
+
+/** Clamps `v` to [lo, hi]. */
+export const clamp = (v: number, lo: number, hi: number): number => Math.max(lo, Math.min(hi, v));

package/src/avatar/layout.ts

@@ -0,0 +1,47 @@
+/** Anchors, facings from movement, and the look-at helper (§3.2, §3.3, §3.6). */
+import { toLook } from './look-like';
+import { composeAvatar } from './render/compose';
+import type { Anchor, Facing, LookDir, LookLike, Point, Pose, RenderOptions } from './render/types';
+
+/**
+ * The rig anchors for a look in a facing and pose: place name plates,
+ * bubbles, props and world objects with these, never with magic numbers.
+ * Rig units (a 100-unit head), feet at (0, 0), y down.
+ */
+export function layout(like: LookLike, opts: Pick<RenderOptions, 'facing' | 'view' | 'pose' | 'figure'> = {}): Readonly<Record<Anchor, Point>> {
+  return composeAvatar(toLook(like), { frame: 'full', ...opts }).anchors;
+}
+
+const EIGHT: readonly Facing[] = ['E', 'SE', 'S', 'SW', 'W', 'NW', 'N', 'NE'];
+const FOUR: readonly Facing[] = ['E', 'S', 'W', 'N'];
+
+/** The facing for a movement vector (screen space, y down), in 8 or 4 directions. */
+export function facingFrom(dx: number, dy: number, dirs: 4 | 8 = 8): Facing {
+  if (dx === 0 && dy === 0) {
+    return 'S';
+  }
+  const angle = Math.atan2(dy, dx);
+  const list = dirs === 8 ? EIGHT : FOUR;
+  const step = (Math.PI * 2) / list.length;
+  const index = ((Math.round(angle / step) % list.length) + list.length) % list.length;
+  return list[index] ?? 'S';
+}
+
+/**
+ * A look direction from one screen point toward another, for card tables
+ * where each seat looks at the active player. `strength` scales it.
+ */
+export function lookToward(from: Point, to: Point, strength = 1): LookDir {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const len = Math.hypot(dx, dy);
+  if (len < 1e-6) {
+    return { x: 0, y: 0 };
+  }
+  return { x: (dx / len) * strength, y: (dy / len) * strength * 0.7 };
+}
+
+/** A pose's gaze toward a point, keeping the rest of the pose. */
+export function withGaze(pose: Pose, look: LookDir): Pose {
+  return { ...pose, look };
+}

package/src/avatar/look-like.ts

@@ -0,0 +1,52 @@
+/** Turns anything a render accepts into a look (or `null` for the silhouette), caching decoded codes. */
+import { decodeLook, encodeLook, type AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import type { LookLike } from './render/types';
+
+const decoded = new Map<string, AvatarLook | null>();
+const DECODE_CACHE = 512;
+
+/** Decodes a code once (an LRU of 512). */
+function fromCode(code: string): AvatarLook | null {
+  const hit = decoded.get(code);
+  if (hit !== undefined || decoded.has(code)) {
+    return hit ?? null;
+  }
+  const look = decodeLook(code)?.look ?? null;
+  if (decoded.size >= DECODE_CACHE) {
+    const oldest = decoded.keys().next().value;
+    if (oldest !== undefined) {
+      decoded.delete(oldest);
+    }
+  }
+  decoded.set(code, look);
+  return look;
+}
+
+/** The look a {@link LookLike} names, or `null` (hidden, malformed, missing). */
+export function toLook(like: LookLike): AvatarLook | null {
+  if (like === null || like === undefined || like === '') {
+    return null;
+  }
+  if (typeof like === 'string') {
+    return fromCode(like);
+  }
+  if ('v' in like) {
+    return like;
+  }
+  if ('look' in like) {
+    return like.look;
+  }
+  return fromCode(like.code);
+}
+
+/** The code a {@link LookLike} names (`''` for none). */
+export function toCode(like: LookLike): string {
+  if (typeof like === 'string') {
+    return like;
+  }
+  if (like && 'code' in like) {
+    return like.code;
+  }
+  const look = toLook(like);
+  return look ? encodeLook(look) : '';
+}

package/src/avatar/outputs/bitmap.ts

@@ -0,0 +1,75 @@
+/**
+ * `render.bitmap` and `render.dataUrl`: cached images of an avatar, keyed by
+ * code, pose bucket, size and view (an LRU of 256 entries).
+ */
+import { toCode } from '../look-like';
+import { pixelSize } from '../render/frame';
+import type { LookLike, RenderOptions } from '../render/types';
+import { renderCanvas } from './canvas';
+import { renderKey } from './pose-key';
+import { renderSvg } from './svg';
+
+const CACHE_SIZE = 256;
+const bitmaps = new Map<string, Promise<ImageBitmap>>();
+
+function remember<T>(cache: Map<string, T>, key: string, make: () => T): T {
+  const hit = cache.get(key);
+  if (hit !== undefined) {
+    cache.delete(key);
+    cache.set(key, hit);
+    return hit;
+  }
+  const value = make();
+  cache.set(key, value);
+  if (cache.size > CACHE_SIZE) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) {
+      cache.delete(oldest);
+    }
+  }
+  return value;
+}
+
+/** A canvas of the avatar's frame size (an `OffscreenCanvas` where available). */
+export function drawToCanvas(like: LookLike, opts: RenderOptions): OffscreenCanvas | HTMLCanvasElement {
+  const { width, height } = pixelSize(opts);
+  const w = Math.max(1, Math.ceil(width));
+  const h = Math.max(1, Math.ceil(height));
+  if (typeof OffscreenCanvas === 'undefined') {
+    const canvas = Object.assign(document.createElement('canvas'), { width: w, height: h });
+    const ctx = canvas.getContext('2d');
+    if (ctx) {
+      renderCanvas(ctx, like, { ...opts, x: 0, y: 0 });
+    }
+    return canvas;
+  }
+  const canvas = new OffscreenCanvas(w, h);
+  const ctx = canvas.getContext('2d');
+  if (ctx) {
+    renderCanvas(ctx, like, { ...opts, x: 0, y: 0 });
+  }
+  return canvas;
+}
+
+/** An `ImageBitmap` of the avatar (cached). */
+export function renderBitmap(like: LookLike, opts: RenderOptions = {}): Promise<ImageBitmap> {
+  return remember(bitmaps, renderKey(toCode(like), opts), () => createImageBitmap(drawToCanvas(like, opts)));
+}
+
+/** A data URL: `svg` (synchronous inside, the default) or `png`. */
+export async function renderDataUrl(like: LookLike, opts: RenderOptions = {}, type: 'svg' | 'png' = 'svg'): Promise<string> {
+  if (type === 'svg') {
+    return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(renderSvg(like, opts))}`;
+  }
+  const canvas = drawToCanvas(like, opts);
+  if ('toDataURL' in canvas) {
+    return canvas.toDataURL('image/png');
+  }
+  const blob = await canvas.convertToBlob({ type: 'image/png' });
+  const bytes = new Uint8Array(await blob.arrayBuffer());
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return `data:image/png;base64,${btoa(binary)}`;
+}

package/src/avatar/outputs/canvas-paint.ts

@@ -0,0 +1,177 @@
+/**
+ * Scene → Canvas 2D. Paths become cached `Path2D`s (no string building per
+ * frame after the first), transforms map to `ctx.transform`, clips to
+ * `ctx.clip`. The rim draws its group into a layer and stamps it with a
+ * light edge in one `drawImage`.
+ */
+import type { Clip, Paint, SceneNode, TfOp } from '../scene';
+import { RIM_COLOUR } from './svg-markup';
+
+/** A 2D context from a canvas or an `OffscreenCanvas`. */
+export type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+
+/** Makes a scratch canvas of a size (for the rim layer); `null` where none can be made. */
+export type LayerFactory = (width: number, height: number) => { readonly canvas: CanvasImageSource; readonly ctx: Ctx2D } | null;
+
+const FONTS = { mono: "'Space Mono', monospace", pixel: "'VT323', monospace" } as const;
+const pathCache = new Map<string, Path2D>();
+const PATH_CACHE = 4096;
+
+function path2d(d: string): Path2D {
+  let p = pathCache.get(d);
+  if (!p) {
+    p = new Path2D(d);
+    if (pathCache.size >= PATH_CACHE) {
+      pathCache.clear();
+    }
+    pathCache.set(d, p);
+  }
+  return p;
+}
+
+function applyTf(ctx: Ctx2D, tf: readonly TfOp[] | undefined): void {
+  for (const op of tf ?? []) {
+    switch (op.k) {
+      case 't':
+        ctx.translate(op.x, op.y);
+        break;
+      case 's':
+        ctx.scale(op.x, op.y);
+        break;
+      case 'r':
+        ctx.rotate((op.a * Math.PI) / 180);
+        break;
+      case 'skx':
+        ctx.transform(1, 0, Math.tan((op.a * Math.PI) / 180), 1, 0, 0);
+        break;
+    }
+  }
+}
+
+function shapePath(node: SceneNode): Path2D | null {
+  if (node.k === 'path') {
+    return path2d(node.d);
+  }
+  if (node.k === 'ellipse') {
+    const p = new Path2D();
+    p.ellipse(node.cx, node.cy, node.rx, node.ry, 0, 0, Math.PI * 2);
+    return p;
+  }
+  if (node.k === 'rect') {
+    const p = new Path2D();
+    const r = Math.min(node.r ?? 0, node.w / 2, node.h / 2);
+    p.moveTo(node.x + r, node.y);
+    p.arcTo(node.x + node.w, node.y, node.x + node.w, node.y + node.h, r);
+    p.arcTo(node.x + node.w, node.y + node.h, node.x, node.y + node.h, r);
+    p.arcTo(node.x, node.y + node.h, node.x, node.y, r);
+    p.arcTo(node.x, node.y, node.x + node.w, node.y, r);
+    p.closePath();
+    return p;
+  }
+  return null;
+}
+
+function applyClip(ctx: Ctx2D, clip: Clip): void {
+  const all = new Path2D();
+  for (const shape of clip.shapes) {
+    const p = shapePath(shape);
+    if (p) {
+      all.addPath(p);
+    }
+  }
+  ctx.clip(all, clip.evenOdd ? 'evenodd' : 'nonzero');
+}
+
+function fillAndStroke(ctx: Ctx2D, p: Path2D, paint: Paint): void {
+  const alpha = ctx.globalAlpha;
+  if (paint.opacity !== undefined) {
+    ctx.globalAlpha = alpha * paint.opacity;
+  }
+  if (paint.fill && paint.fill !== 'none') {
+    const fillAlpha = ctx.globalAlpha;
+    if (paint.fillOpacity !== undefined) {
+      ctx.globalAlpha = fillAlpha * paint.fillOpacity;
+    }
+    ctx.fillStyle = paint.fill;
+    ctx.fill(p, paint.evenOdd ? 'evenodd' : 'nonzero');
+    ctx.globalAlpha = fillAlpha;
+  }
+  if (paint.stroke && paint.stroke !== 'none') {
+    ctx.strokeStyle = paint.stroke;
+    ctx.lineWidth = paint.sw ?? 1;
+    ctx.lineJoin = 'round';
+    ctx.lineCap = paint.cap ?? 'round';
+    ctx.stroke(p);
+  }
+  ctx.globalAlpha = alpha;
+}
+
+/** Paints scene nodes in the context's current transform (rig units → pixels is the caller's job). */
+export function paintNodes(ctx: Ctx2D, nodes: readonly SceneNode[], layer?: LayerFactory): void {
+  for (const node of nodes) {
+    paintNode(ctx, node, layer);
+  }
+}
+
+function paintRim(ctx: Ctx2D, children: readonly SceneNode[], layer: LayerFactory | undefined): boolean {
+  const target = ctx.canvas;
+  const made = layer?.(target.width, target.height);
+  if (!made || !('filter' in made.ctx)) {
+    return false;
+  }
+  made.ctx.setTransform(ctx.getTransform());
+  paintNodes(made.ctx, children, layer);
+  const scale = Math.hypot(ctx.getTransform().a, ctx.getTransform().b);
+  const r = Math.max(1, 2.8 * scale);
+  const c = `${RIM_COLOUR}7a`;
+  ctx.save();
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.filter = `drop-shadow(${String(r)}px 0 0 ${c}) drop-shadow(${String(-r)}px 0 0 ${c}) drop-shadow(0 ${String(r)}px 0 ${c}) drop-shadow(0 ${String(-r)}px 0 ${c})`;
+  ctx.drawImage(made.canvas, 0, 0);
+  ctx.restore();
+  return true;
+}
+
+function paintNode(ctx: Ctx2D, node: SceneNode, layer: LayerFactory | undefined): void {
+  ctx.save();
+  if (node.k === 'g') {
+    applyTf(ctx, node.tf);
+    if (node.clip) {
+      applyClip(ctx, node.clip);
+    }
+    if (node.opacity !== undefined) {
+      ctx.globalAlpha *= node.opacity;
+    }
+    if (!(node.rim === true && paintRim(ctx, node.children, layer))) {
+      paintNodes(ctx, node.children, layer);
+    }
+    ctx.restore();
+    return;
+  }
+  if (node.k === 'text') {
+    ctx.font = `${node.bold ? '700 ' : ''}${String(node.size)}px ${FONTS[node.font]}`;
+    ctx.textAlign = node.anchor === 'middle' ? 'center' : 'left';
+    ctx.textBaseline = 'alphabetic';
+    if (node.opacity !== undefined) {
+      ctx.globalAlpha *= node.opacity;
+    }
+    if (node.stroke && node.stroke !== 'none') {
+      ctx.strokeStyle = node.stroke;
+      ctx.lineWidth = node.sw ?? 1;
+      ctx.lineJoin = 'round';
+      ctx.strokeText(node.text, node.x, node.y);
+    }
+    if (node.fill && node.fill !== 'none') {
+      ctx.fillStyle = node.fill;
+      ctx.fillText(node.text, node.x, node.y);
+    }
+    ctx.restore();
+    return;
+  }
+  applyTf(ctx, node.tf);
+  const p = shapePath(node);
+  if (p) {
+    fillAndStroke(ctx, p, node);
+  }
+  ctx.restore();
+}

package/src/avatar/outputs/canvas.ts

@@ -0,0 +1,62 @@
+/**
+ * `render.canvas` and `render.canvasAt`: draw an avatar on a 2D canvas,
+ * synchronously once the art is ready. `canvas` fills a frame box at (x, y);
+ * `canvasAt` puts the feet at (x, y) with a pixels-per-unit scale (the world
+ * and crowds).
+ */
+import { toLook } from '../look-like';
+import { composeAvatar } from '../render/compose';
+import { frameBox, framed, pixelSize } from '../render/frame';
+import type { LookLike, RenderOptions } from '../render/types';
+import type { SceneNode } from '../scene';
+import { paintNodes, type Ctx2D, type LayerFactory } from './canvas-paint';
+
+/** A scratch canvas for the rim layer: an `OffscreenCanvas`, else a DOM canvas, else none. */
+export const defaultLayer: LayerFactory = (width, height) => {
+  if (typeof OffscreenCanvas !== 'undefined') {
+    const canvas = new OffscreenCanvas(width, height);
+    const ctx = canvas.getContext('2d');
+    return ctx ? { canvas, ctx } : null;
+  }
+  if (typeof document !== 'undefined') {
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    return ctx ? { canvas, ctx } : null;
+  }
+  return null;
+};
+
+/** Where and how big: the frame box's top-left corner in canvas pixels. */
+export interface CanvasPlacement extends RenderOptions {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Paints scene nodes with rig space mapped to the frame box at (x, y). */
+export function paintFramed(ctx: Ctx2D, nodes: readonly SceneNode[], opts: CanvasPlacement): void {
+  const [fx, fy] = frameBox(opts);
+  const { scale } = pixelSize(opts);
+  ctx.save();
+  ctx.translate(opts.x, opts.y);
+  ctx.scale(scale, scale);
+  ctx.translate(-fx, -fy);
+  paintNodes(ctx, nodes, defaultLayer);
+  ctx.restore();
+}
+
+/** Draws an avatar in a frame box whose top-left is (x, y), `size` px on its longer edge. */
+export function renderCanvas(ctx: Ctx2D, like: LookLike, opts: CanvasPlacement): void {
+  const look = toLook(like);
+  paintFramed(ctx, framed(composeAvatar(look, opts).nodes, look, opts), opts);
+}
+
+/** Draws the full character with its feet at (x, y), `scale` px per rig unit (a 100-unit head). */
+export function renderCanvasAt(ctx: Ctx2D, like: LookLike, opts: RenderOptions & { readonly x: number; readonly y: number; readonly scale: number }): void {
+  ctx.save();
+  ctx.translate(opts.x, opts.y);
+  ctx.scale(opts.scale, opts.scale);
+  paintNodes(ctx, composeAvatar(toLook(like), { frame: 'full', ...opts }).nodes, defaultLayer);
+  ctx.restore();
+}