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

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,62 @@
+/**
+ * `@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 { 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, 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;
+  }
+}

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

@@ -0,0 +1,34 @@
+/** Building {@link AvatarRef}s from codes, payloads and seeds. */
+import { decodeLook, defaultLook, encodeLook } from '@diffenderfer-games/hub-contract/avatar';
+import type { AvatarRef } from './avatar-types';
+
+/** A ref for a code (`''` = hidden). */
+export function refOf(code: string, isDefault = false): AvatarRef {
+  if (code === '') {
+    return { code: '', look: null, isDefault: false, hidden: true };
+  }
+  return { code, look: decodeLook(code)?.look ?? null, isDefault, hidden: false };
+}
+
+/** A seeded default look as a ref (bots, previews, local pass-and-play seats). */
+export function botRef(seed: string | number): AvatarRef {
+  const look = defaultLook(seed);
+  return { code: encodeLook(look), look, isDefault: true, hidden: false };
+}
+
+/** Anything that carries a player's look: a seat, a `PlayerLite`, a racer, a ticket user. */
+export interface CarriesLook {
+  readonly look?: string;
+  readonly userId?: number;
+  readonly id?: number;
+  readonly uid?: number;
+}
+
+/** The ref a payload carries; an old hub's payload (no `look`) falls back to the id's default. */
+export function refFrom(carrier: CarriesLook): AvatarRef {
+  if (carrier.look !== undefined) {
+    return refOf(carrier.look);
+  }
+  const id = carrier.userId ?? carrier.id ?? carrier.uid;
+  return id === undefined ? refOf('') : botRef(id);
+}

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

@@ -0,0 +1,43 @@
+/** The shapes `hub.avatar` works with (avatars.md §6). */
+import type { AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+
+/**
+ * A player's avatar as games hold it: the code (pass it to any renderer),
+ * the decoded look, whether it is their generated default, and whether the
+ * player is hidden from you (draw the silhouette).
+ */
+export interface AvatarRef {
+  readonly code: string;
+  /** `null` when hidden or the code is malformed (renderers draw the silhouette). */
+  readonly look: AvatarLook | null;
+  /** They never designed one: this is their generated default. */
+  readonly isDefault: boolean;
+  /** Hidden where the username is hidden (§2.8). */
+  readonly hidden: boolean;
+}
+
+/** A player's avatar changed (`hub.avatar.on('change')`). */
+export interface AvatarChange {
+  readonly userId: number;
+  readonly ref: AvatarRef;
+}
+
+/** Options for the designer. */
+export interface OpenDesignerOptions {
+  /** Why it opened (`'game'`, `'world'`, …), for metrics only. */
+  readonly reason?: string;
+}
+
+/** What the designer reports when it closes. */
+export interface DesignerResult {
+  /** The player saved a new look. */
+  readonly saved: boolean;
+}
+
+/** What the social runtime adds for avatars (feature version 5). */
+export interface RuntimeAvatarApi {
+  /** Open "Make your avatar" over the page; resolves when it closes. */
+  openDesigner(options?: OpenDesignerOptions): Promise<DesignerResult>;
+  /** Live `ev:avatar` changes (yours, friends', your room's). */
+  on(event: 'change', listener: (change: { readonly userId: number; readonly code: string }) => void): () => void;
+}