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

package/src/avatar/adapters/pixi-crowd.ts

@@ -0,0 +1,329 @@
+/**
+ * `createCrowd` (§3.11): the world's whole avatar layer in Pixi 8. One
+ * y-sorted container; most avatars are atlas frames (shared page textures,
+ * so Pixi batches them), and up to `liveMax` flagged ones (nearest, hovered,
+ * talking, friends; the world decides) are live vector avatars with full
+ * expressions. Name tags and bubbles are cached textures, re-rendered only
+ * when their text changes. Baking is time-sliced; an avatar without a baked
+ * frame yet shows the silhouette.
+ */
+import { animator, type Animator } from '../animator/animator';
+import type { AvatarAtlas } from '../atlas';
+import { expressionFromEmote } from '../face';
+import { layout } from '../layout';
+import { toCode } from '../look-like';
+import { defaultLayer } from '../outputs/canvas';
+import { paintNodes } from '../outputs/canvas-paint';
+import { overlays, type Overlay, type ReactionGlyph } from '../overlays';
+import { frameBox } from '../render/frame';
+import type { BodyPose, Facing, Figure, LookLike, StatusProp } from '../render/types';
+import { pixiAvatar, type PixiAvatar } from './pixi-avatar';
+import { refresh, type PixiContainer, type PixiNs, type PixiRectangle, type PixiSprite, type PixiTexture } from './pixi-types';
+
+/** One avatar's state in the crowd (the world's own protocol fills it). */
+export interface CrowdMember {
+  readonly look: LookLike;
+  readonly x: number;
+  readonly y: number;
+  readonly facing?: Facing;
+  readonly body?: BodyPose;
+  readonly status?: StatusProp | null;
+  /** The username for the name tag (omit for no tag). */
+  readonly name?: string;
+  readonly friend?: boolean;
+  readonly you?: boolean;
+  /** "Playing Uno": the game's catalog title. */
+  readonly activity?: string;
+  /** A quick-chat emote to pop (shown for 2.5 s from when it's set). */
+  readonly emote?: string;
+  readonly reaction?: ReactionGlyph;
+  /** Ask for live vector rendering (granted to at most `liveMax`). */
+  readonly live?: boolean;
+  /** Hide the tag (the world fades tags by distance and hides them when crowded). */
+  readonly tagHidden?: boolean;
+  /** Moves the tag and bubble up by this much (container units), so a world can stack tags that would overlap. */
+  readonly tagLift?: number;
+}
+
+/** Crowd options; `container` is the game's own pixi `Container`. */
+export interface CrowdOptions<TSprite extends PixiSprite = PixiSprite> {
+  readonly atlas: AvatarAtlas;
+  /** The container avatars go into (it is made y-sortable). */
+  readonly container: PixiContainer<TSprite>;
+  /** Live vector avatars at most (default 6; 2 on low-end devices). */
+  readonly liveMax?: number;
+  /** Atlas baking budget per update, ms (default 4). */
+  readonly bakeMs?: number;
+  /**
+   * Where name tags and bubbles go (default `container`). A world puts them in
+   * a container above its lighting so tags stay readable at night.
+   */
+  readonly overlays?: PixiContainer<TSprite>;
+  /**
+   * Draws atlas avatars at this scale (default 1). Bake the atlas at
+   * `scale × devicePixelRatio` and pass `1 / devicePixelRatio` for crisp
+   * avatars on high-density screens; positions stay in the container's units.
+   */
+  readonly displayScale?: number;
+  /**
+   * The figure the atlas draws (default `blob`). Pass the atlas's own
+   * figure, so name tags sit on the right heads and walks step in time.
+   */
+  readonly figure?: Figure;
+}
+
+/** The crowd. */
+export interface AvatarCrowd {
+  set(id: string | number, member: CrowdMember): void;
+  remove(id: string | number): void;
+  /** Advances animation to `t` (ms), bakes, and lays everyone out. Call once per frame. */
+  update(t: number): void;
+  destroy(): void;
+}
+
+/** A cached overlay sprite and the key it shows. */
+interface OverlaySlot<TSprite extends PixiSprite> {
+  sprite: TSprite | null;
+  key: string;
+}
+
+interface Entry<TSprite extends PixiSprite> {
+  member: CrowdMember;
+  readonly sprite: TSprite;
+  readonly tag: OverlaySlot<TSprite>;
+  readonly bubble: OverlaySlot<TSprite>;
+  emoteAt: number;
+  /** A baked frame has been shown (while a new look bakes, the old one stays instead of the silhouette). */
+  hasFrame: boolean;
+  live: PixiAvatar<TSprite> | null;
+  body: BodyPose | null;
+  readonly anim: Animator;
+}
+
+const EMOTE_MS = 2500;
+const CYCLE: Readonly<Partial<Record<BodyPose, number>>> = { walk: 520, run: 320, dance: 900, jump: 700, cheer: 600, idle: 2400 };
+/** The walker's shorter legs step quicker. */
+const WALKER_CYCLE: Readonly<Partial<Record<BodyPose, number>>> = { ...CYCLE, walk: 440, run: 300, idle: 2800 };
+
+/** A crowd over an atlas: `createCrowd(pixi, { atlas, container })`. */
+export function createCrowd<TTexture extends PixiTexture, TSprite extends PixiSprite<TTexture>, TRectangle extends PixiRectangle>(
+  pixi: PixiNs<TTexture, TSprite, TRectangle>,
+  opts: CrowdOptions<NoInfer<TSprite>>,
+): AvatarCrowd {
+  const { atlas, container } = opts;
+  const overlayLayer = opts.overlays ?? container;
+  const displayScale = opts.displayScale ?? 1;
+  container.sortableChildren = true;
+  overlayLayer.sortableChildren = true;
+  const liveMax = opts.liveMax ?? 6;
+  const figure = opts.figure ?? 'blob';
+  const cycles = figure === 'walker' ? WALKER_CYCLE : CYCLE;
+  const [, liveTop, , liveHeight] = frameBox({ frame: 'full', figure });
+  const entries = new Map<string, Entry<TSprite>>();
+  const pageTextures: TTexture[] = [];
+  const frameTextures = new Map<string, TTexture>();
+  const overlayTextures = new Map<string, { texture: TTexture; ax: number; ay: number }>();
+
+  /** Where the name plate sits above the feet (rig units), cached per look, pose and prop. */
+  const nameplates = new Map<string, number>();
+  const nameplateY = (look: LookLike, body: BodyPose, status: StatusProp | null): number => {
+    const key = `${toCode(look)}|${body}|${status ?? ''}`;
+    let plateY = nameplates.get(key);
+    if (plateY === undefined) {
+      plateY = layout(look, { figure, pose: { body, status } }).nameplate.y;
+      nameplates.set(key, plateY);
+    }
+    return plateY;
+  };
+  const overlayTexture = (key: string, overlay: Overlay): { texture: TTexture; ax: number; ay: number } | null => {
+    const hit = overlayTextures.get(key);
+    if (hit) {
+      return hit;
+    }
+    const [left, top, w, h] = overlay.box;
+    const resolution = 2;
+    const made = defaultLayer(Math.ceil(w * resolution), Math.ceil(h * resolution));
+    if (!made || !('getContext' in made.canvas)) {
+      return null;
+    }
+    made.ctx.scale(resolution, resolution);
+    made.ctx.translate(-left, -top);
+    paintNodes(made.ctx, overlay.nodes);
+    const texture = pixi.Texture.from(made.canvas);
+    const out = { texture, ax: -left / w, ay: -top / h };
+    overlayTextures.set(key, out);
+    return out;
+  };
+
+  const textureFor = (page: number, left: number, top: number, w: number, h: number): TTexture | null => {
+    const sources = atlas.sources;
+    while (pageTextures.length < sources.length) {
+      const source = sources[pageTextures.length];
+      if (!source || !('getContext' in source)) {
+        return null;
+      }
+      pageTextures.push(pixi.Texture.from(source));
+    }
+    const base = pageTextures[page]?.source;
+    if (!base) {
+      return null;
+    }
+    const key = `${String(page)}:${String(left)}:${String(top)}`;
+    let tex = frameTextures.get(key);
+    if (!tex) {
+      tex = new pixi.Texture({ source: base, frame: new pixi.Rectangle(left, top, w, h) });
+      frameTextures.set(key, tex);
+    }
+    return tex;
+  };
+
+  const placeOverlay = (slot: OverlaySlot<TSprite>, key: string, make: () => Overlay | null, atX: number, atY: number): void => {
+    if (key === '') {
+      if (slot.sprite) {
+        slot.sprite.visible = false;
+      }
+      return;
+    }
+    let sprite = slot.sprite;
+    if (slot.key !== key || !sprite) {
+      const overlay = make();
+      const made = overlay ? overlayTexture(key, overlay) : null;
+      if (!made) {
+        return;
+      }
+      if (!sprite) {
+        sprite = new pixi.Sprite(made.texture);
+        overlayLayer.addChild(sprite);
+      }
+      slot.sprite = sprite;
+      sprite.texture = made.texture;
+      sprite.anchor.set(made.ax, made.ay);
+      sprite.scale.set(0.5);
+      slot.key = key;
+    }
+    sprite.visible = true;
+    sprite.x = atX;
+    sprite.y = atY;
+    sprite.zIndex = 1e6 + atY;
+  };
+
+  return {
+    set(id, member) {
+      const key = String(id);
+      const entry = entries.get(key);
+      if (entry) {
+        if (member.emote && member.emote !== entry.member.emote) {
+          entry.emoteAt = -1;
+          const face = expressionFromEmote(member.emote);
+          if (face) {
+            entry.anim.express(face);
+          }
+        }
+        if (member.look !== entry.member.look) {
+          entry.live?.setLook(member.look);
+        }
+        entry.member = member;
+        return;
+      }
+      const sprite = new pixi.Sprite();
+      container.addChild(sprite);
+      entries.set(key, {
+        member, sprite, tag: { sprite: null, key: '' }, bubble: { sprite: null, key: '' }, emoteAt: member.emote ? -1 : 0, hasFrame: false, live: null, body: null,
+        anim: animator(member.look, { seed: key }),
+      });
+    },
+    remove(id) {
+      const entry = entries.get(String(id));
+      if (!entry) {
+        return;
+      }
+      entry.sprite.destroy();
+      entry.tag.sprite?.destroy();
+      entry.bubble.sprite?.destroy();
+      entry.live?.destroy();
+      entries.delete(String(id));
+    },
+    update(t) {
+      if (atlas.bake(opts.bakeMs ?? 4) > 0) {
+        pageTextures.forEach(refresh);
+      }
+      const wantsLive = [...entries.values()].filter((e) => e.member.live === true).slice(0, liveMax);
+      const liveSet = new Set(wantsLive);
+      for (const entry of entries.values()) {
+        const m = entry.member;
+        const body = m.body ?? 'idle';
+        if (entry.emoteAt === -1) {
+          entry.emoteAt = t;
+        }
+        const isEmoting = m.emote !== undefined && t - entry.emoteAt < EMOTE_MS;
+        if (liveSet.has(entry)) {
+          if (!entry.live) {
+            entry.live = pixiAvatar(pixi, m.look, { frame: 'full', figure, size: 64, rim: true, shadow: false, animator: entry.anim });
+            container.addChild(entry.live.view);
+          }
+          entry.sprite.visible = false;
+          const view = entry.live.view;
+          if (entry.body !== body) {
+            entry.body = body;
+            entry.anim.setBody(body, { at: t });
+          }
+          entry.live.update({ ...entry.anim.pose(t), body, status: m.status ?? null, phase: (t / (cycles[body] ?? 600)) % 1 });
+          view.x = m.x;
+          view.y = m.y + (figure === 'walker' ? (liveTop + liveHeight / 2) * (64 / liveHeight) : -32);
+          view.zIndex = m.y;
+          view.visible = true;
+        } else {
+          if (entry.live) {
+            entry.live.view.visible = false;
+          }
+          const frame = atlas.frame({
+            look: m.look, facing: m.facing ?? 'S', body, status: m.status ?? null,
+            phase: (t / (cycles[body] ?? 600)) % 1, face: isEmoting ? 'happy' : 'neutral',
+          });
+          // Until its first frame bakes, a member shows the silhouette, anchored and scaled like a frame.
+          const shown = frame ?? (entry.hasFrame ? null : atlas.frame({ look: null }));
+          entry.hasFrame ||= frame !== null;
+          const tex = shown ? textureFor(shown.page, shown.x, shown.y, shown.w, shown.h) : null;
+          if (tex) {
+            entry.sprite.texture = tex;
+            entry.sprite.visible = true;
+          }
+          if (shown) {
+            entry.sprite.anchor.set(shown.footX / shown.w, shown.footY / shown.h);
+            entry.sprite.scale.set(shown.mirror ? -displayScale : displayScale, displayScale);
+          }
+          entry.sprite.x = m.x;
+          entry.sprite.y = m.y;
+          entry.sprite.zIndex = m.y;
+        }
+        const top = m.y - (m.tagLift ?? 0) + nameplateY(m.look, body, m.status ?? null) * (entry.live?.view.visible === true ? 64 / liveHeight : atlas.scale * displayScale);
+        const tagKey = m.name && !m.tagHidden ? `tag:${m.name}:${m.friend ? 1 : 0}:${m.you ? 1 : 0}` : '';
+        placeOverlay(entry.tag, tagKey, () => (m.name ? overlays.nameTag({ name: m.name, friend: m.friend === true, you: m.you === true }) : null), m.x, top);
+        const bubbleKey = isEmoting && m.emote ? `emote:${m.emote}` : m.reaction ? `react:${m.reaction}` : m.activity ? `act:${m.activity}` : '';
+        placeOverlay(entry.bubble, bubbleKey, () => {
+          if (isEmoting && m.emote) {
+            return overlays.emoteBubble(m.emote);
+          }
+          if (m.reaction) {
+            return overlays.reactionBubble(m.reaction);
+          }
+          return m.activity ? overlays.activityBubble({ game: m.activity }) : null;
+        }, m.x, top - 12);
+      }
+    },
+    destroy() {
+      for (const id of [...entries.keys()]) {
+        this.remove(id);
+      }
+      for (const tex of frameTextures.values()) {
+        tex.destroy(false);
+      }
+      for (const tex of pageTextures) {
+        tex.destroy(true);
+      }
+      for (const o of overlayTextures.values()) {
+        o.texture.destroy(true);
+      }
+    },
+  };
+}

package/src/avatar/adapters/pixi-types.ts

@@ -0,0 +1,84 @@
+/**
+ * The slice of PixiJS the adapters use, typed structurally so the hub has no
+ * dependency on pixi. Pixi 8 is the target; Pixi 7 works through the same
+ * calls where they exist (`Texture.from(canvas)`, `texture.update()`).
+ */
+
+/** A canvas-like source Pixi can upload. */
+export type PixiSource = HTMLCanvasElement | OffscreenCanvas;
+
+/** A texture's uploadable source (Pixi 8). */
+export interface PixiTextureSource {
+  update(): void;
+}
+
+/** A texture (Pixi 8: `source.update()`; Pixi 7: `update()`). */
+export interface PixiTexture {
+  readonly source?: PixiTextureSource;
+  update?(): void;
+  destroy(destroySource?: boolean): void;
+}
+
+/** A display object's shared fields. */
+export interface PixiDisplay {
+  x: number;
+  y: number;
+  visible: boolean;
+  alpha: number;
+  zIndex: number;
+  readonly scale: { x: number; y: number; set(x: number, y?: number): void };
+  destroy(options?: { children?: boolean }): void;
+}
+
+/** A sprite showing a `TTexture`. */
+export interface PixiSprite<TTexture extends PixiTexture = PixiTexture> extends PixiDisplay {
+  texture: TTexture;
+  readonly anchor: { set(x: number, y?: number): void };
+}
+
+/** A container that takes `TChild` sprites. */
+export interface PixiContainer<TChild extends PixiDisplay = PixiSprite> extends PixiDisplay {
+  sortableChildren: boolean;
+  addChild(child: TChild): void;
+  removeChild(child: TChild): void;
+}
+
+/** A frame rectangle. */
+export interface PixiRectangle {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The PIXI namespace, as passed in by the game (`import * as PIXI from
+ * 'pixi.js'`, or an object of the named imports). It is generic over the
+ * game's own classes, inferred from what is passed, so the sprites and
+ * textures that come back are pixi's own types and go straight into a
+ * `Container` with no cast.
+ */
+export interface PixiNs<
+  TTexture extends PixiTexture = PixiTexture,
+  TSprite extends PixiSprite<TTexture> = PixiSprite<TTexture>,
+  TRectangle extends PixiRectangle = PixiRectangle,
+> {
+  readonly Texture: {
+    from(source: PixiSource): TTexture;
+    new (options: { source: NonNullable<TTexture['source']>; frame: TRectangle }): TTexture;
+  };
+  readonly Sprite: new (texture?: TTexture) => TSprite;
+  /** Not used by the adapters; accepted so an object of the named imports can include it. */
+  readonly Container?: new () => PixiDisplay;
+  readonly Rectangle: new (x: number, y: number, width: number, height: number) => TRectangle;
+}
+
+/** Re-uploads a texture after its canvas changed (Pixi 8 and 7). */
+export function refresh(texture: PixiTexture): void {
+  if (texture.source) {
+    texture.source.update();
+  } else {
+    texture.update?.();
+  }
+}
+

package/src/avatar/adapters/three.ts

@@ -0,0 +1,126 @@
+/**
+ * three.js helpers (§3.8): an avatar on a `CanvasTexture` (redrawn only when
+ * the pose changes, at most 30 times a second) and a ready-made `Sprite`.
+ * Pass the game's three namespace; the hub never imports three. A 3D head is
+ * out of scope (§14.4, Q11).
+ */
+import type { Animator } from '../animator/animator';
+import { liveCanvas } from '../outputs/live-canvas';
+import type { LookLike, Pose, RenderOptions } from '../render/types';
+
+/**
+ * The slice of three.js {@link avatarCanvasTexture} uses: `import * as THREE
+ * from 'three'`, or an object of the named imports. Generic over the game's
+ * own `CanvasTexture`, inferred from what is passed, so the texture that comes
+ * back is three's own type.
+ */
+export interface ThreeTextureNs<TTexture extends ThreeTexture = ThreeTexture> {
+  readonly CanvasTexture: new (canvas: HTMLCanvasElement | OffscreenCanvas) => TTexture;
+  readonly SRGBColorSpace?: string;
+}
+
+/**
+ * The slice of three.js {@link avatarSprite} uses (the namespace, or the named
+ * imports). The sprite that comes back is three's own `Sprite`, so
+ * `scene.add(sprite)` needs no cast. `TMap` is what the game's
+ * `SpriteMaterial` takes as its `map` (three's `Texture`); it is inferred on
+ * its own so an inline object of the named imports infers too.
+ */
+export interface ThreeNs<
+  TTexture extends ThreeTexture = ThreeTexture,
+  TMaterial extends ThreeMaterial = ThreeMaterial,
+  TSprite extends ThreeSprite = ThreeSprite,
+  TMap = TTexture,
+> extends ThreeTextureNs<TTexture> {
+  readonly SpriteMaterial: new (params: { map: TMap; transparent: boolean }) => TMaterial;
+  readonly Sprite: new (material: TMaterial) => TSprite;
+}
+
+/** A texture. */
+export interface ThreeTexture {
+  needsUpdate: boolean;
+  colorSpace?: string;
+  dispose(): void;
+}
+
+/** A material. */
+export interface ThreeMaterial {
+  dispose(): void;
+}
+
+/** A sprite. */
+export interface ThreeSprite {
+  readonly scale: { set(x: number, y: number, z: number): void };
+}
+
+/** Options for the three.js helpers. */
+export interface ThreeAvatarOptions extends RenderOptions {
+  readonly animator?: Animator;
+  /** Texture pixels per `size` pixel (default 2). */
+  readonly resolution?: number;
+}
+
+/** A live avatar texture; `texture` is the game's own `CanvasTexture`. */
+export interface ThreeAvatarTexture<TTexture extends ThreeTexture = ThreeTexture> {
+  readonly texture: TTexture;
+  /** Redraws for the animator's pose at `t` (or a given pose), at most 30 times a second. */
+  update(t: number | Pose): void;
+  setLook(like: LookLike): void;
+  dispose(): void;
+}
+
+const MIN_FRAME_MS = 1000 / 30;
+
+/** A `CanvasTexture` showing the avatar. */
+export function avatarCanvasTexture<TTexture extends ThreeTexture>(
+  three: ThreeTextureNs<TTexture>,
+  like: LookLike,
+  opts: ThreeAvatarOptions = {},
+): ThreeAvatarTexture<TTexture> {
+  const live = liveCanvas(like, opts, opts.resolution ?? 2);
+  live.draw(opts.pose);
+  const texture = new three.CanvasTexture(live.canvas);
+  if (three.SRGBColorSpace) {
+    texture.colorSpace = three.SRGBColorSpace;
+  }
+  let last = -Infinity;
+  return {
+    texture,
+    update(t) {
+      if (typeof t === 'number') {
+        if (t - last < MIN_FRAME_MS) {
+          return;
+        }
+        last = t;
+      }
+      const pose = typeof t === 'number' ? opts.animator?.pose(t) : t;
+      if (live.draw(pose ?? opts.pose)) {
+        texture.needsUpdate = true;
+      }
+    },
+    setLook(next) {
+      live.setLook(next);
+      opts.animator?.setLook(next);
+      if (live.draw(opts.pose)) {
+        texture.needsUpdate = true;
+      }
+    },
+    dispose() {
+      texture.dispose();
+    },
+  };
+}
+
+/** A billboard `Sprite` of the avatar, `height` world units tall (default 1). */
+export function avatarSprite<TTexture extends ThreeTexture & TMap, TMaterial extends ThreeMaterial, TSprite extends ThreeSprite, TMap>(
+  three: ThreeNs<TTexture, TMaterial, TSprite, TMap>,
+  like: LookLike,
+  opts: ThreeAvatarOptions & { readonly height?: number } = {},
+): { readonly sprite: TSprite; readonly avatar: ThreeAvatarTexture<TTexture> } {
+  const avatar = avatarCanvasTexture(three, like, opts);
+  const sprite = new three.Sprite(new three.SpriteMaterial({ map: avatar.texture, transparent: true }));
+  const h = opts.height ?? 1;
+  const aspect = opts.frame === 'full' ? 172 / 206 : 1;
+  sprite.scale.set(h * aspect, h, 1);
+  return { sprite, avatar };
+}