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

package/dist/turns.js

@@ -0,0 +1,183 @@
+import { c as parseJsonText } from "./shared/json-guards.js";
+import { createTurnRng, defineTurnRules, turnRngStateFromSeed } from "./turns-rules.js";
+import { createTurnRng as createTurnRng$1, turnRngStateFromSeed as turnRngStateFromSeed$1 } from "@diffenderfer-games/hub-contract/turns-rules";
+//#region src/turns-kit/check-rules.ts
+/**
+* The rules conformance kit (docs/multiplayer.md "Turn games: testing"):
+* `checkTurnRules(rules, options)` plays many seeded games through a rules
+* module the way the hub does and throws on the first broken promise:
+*
+* - every game reaches an outcome within `maxMoves`, and `toAct` is never
+*   empty before it; every seat in `toAct` gets to move (not only the
+*   first), and so do the seats in `mayAct` (out of turn: a jump-in, a
+*   catch) whose `autoReact` (or `options.reactMove`) has a move;
+* - `toAct` and `mayAct` only name seats that exist;
+* - the state survives a JSON round trip after every move, and the same seed
+*   plays the same game (no `Math.random`, no hidden globals);
+* - `autoMove` and `autoReact` (when the rules have them) are always legal;
+* - no seat's `view` or `eventView` shows another seat's secrets: markers
+*   planted with `options.plant` never appear in anyone else's view until
+*   the rules reveal them (`options.revealed`: a card played face up);
+* - with `options.shuffleHidden` (the "twin table"): shuffling everything a
+*   seat may not see never changes that seat's view;
+* - stored fixtures from older versions `migrate` to a state that views;
+* - views, events and moves stay within the hub's size caps.
+*
+* It needs no hub: run it in a game's own unit tests (vitest, node:test).
+*/
+/** The hub's caps. */
+const STATE_MAX_BYTES = 65536;
+const MOVE_MAX_BYTES = 2048;
+/** The UTF-8 bytes of a JSON text. */
+function bytesOf(json) {
+	return new TextEncoder().encode(json).length;
+}
+/** Throw a kit failure. */
+function fail(message) {
+	throw new Error(`checkTurnRules: ${message}`);
+}
+/** A JSON copy (what the hub stores and reads back). */
+function roundTrip(value) {
+	const copy = parseJsonText(JSON.stringify(value));
+	if (copy === null && value !== null) fail("a state or move is not JSON");
+	return isGamesOwn(copy, value) ? copy : fail("a state or move is not JSON");
+}
+/** Always true: JSON a game's rules made is read back as the game's own type (the game vouches for it, as `toGameData` does). */
+function isGamesOwn(_value, _like) {
+	return true;
+}
+/** A move for `seat`: the check's own chooser, else the rules' autoMove. */
+function pickMove(rules, options, state, seat, rng) {
+	if (options.randomMove !== void 0) return options.randomMove(state, seat, rng);
+	if (rules.autoMove === void 0) return fail("the rules have no autoMove: pass options.randomMove");
+	return rules.autoMove(state, seat, rng);
+}
+/** An out-of-turn move for `seat`: the check's own chooser, else the rules' autoReact, else none. */
+function pickReaction(rules, options, state, seat, rng) {
+	if (options.reactMove !== void 0) return options.reactMove(state, seat, rng);
+	return rules.autoReact?.(state, seat, rng) ?? null;
+}
+/** Fail unless every seat in `list` exists. */
+function checkSeats(list, seats, what, seed) {
+	if (list.some((seat) => !Number.isInteger(seat) || seat < 0 || seat >= seats)) fail(`${what} named a seat that doesn't exist: [${list.join(", ")}] (seed ${String(seed)})`);
+}
+/**
+* The next move of a game: half the time a seat in `mayAct` that has an
+* out-of-turn move, else a seat in `toAct` (any of them, not only the
+* first). The kit's own `pick` RNG chooses, so the game's RNG sees only
+* the rules' own draws.
+*/
+function nextMove(rules, options, state, toAct, rng, pick) {
+	const optional = (rules.mayAct?.(state) ?? []).filter((seat) => !toAct.includes(seat));
+	if (optional.length > 0 && pick.int(2) === 0) {
+		const seat = pick.pick(optional);
+		const move = pickReaction(rules, options, state, seat, rng);
+		if (move !== null) return {
+			seat,
+			move,
+			by: options.reactMove === void 0 ? "autoReact" : "reactMove"
+		};
+	}
+	const seat = toAct.length === 0 ? void 0 : pick.pick(toAct);
+	return seat === void 0 ? null : {
+		seat,
+		move: pickMove(rules, options, state, seat, rng),
+		by: options.randomMove === void 0 ? "autoMove" : "randomMove"
+	};
+}
+/** Play one seeded game; answers its moves and a trace for the determinism check. */
+function playGame(rules, seats, seed, options) {
+	const rng = createTurnRng$1(turnRngStateFromSeed$1(seed));
+	const pick = createTurnRng$1(turnRngStateFromSeed$1(seed ^ 1540483477));
+	const twinRng = createTurnRng$1(turnRngStateFromSeed$1(seed ^ 668265263));
+	const marker = `MARKER-${String(seed)}-`;
+	const markerOf = (owner) => `${marker}${String(owner)}`;
+	let state = rules.setup({
+		seats,
+		options: options.setupOptions ?? null,
+		mode: options.mode ?? null,
+		rng
+	});
+	if (options.plant !== void 0) for (let seat = 0; seat < seats; seat++) state = options.plant(state, seat, markerOf(seat));
+	const maxMoves = options.maxMoves ?? 2e3;
+	const trace = [];
+	let outOfTurn = 0;
+	/** The twin table: each seat's view is the same after what it can't see is shuffled. */
+	const checkTwin = () => {
+		if (options.shuffleHidden === void 0) return;
+		for (let viewer = 0; viewer < seats; viewer++) {
+			const real = JSON.stringify(rules.view(state, viewer));
+			if (JSON.stringify(rules.view(roundTrip(options.shuffleHidden(roundTrip(state), viewer, twinRng)), viewer)) !== real) fail(`seat ${String(viewer)}'s view changed when what it can't see was shuffled: it shows something hidden (seed ${String(seed)})`);
+		}
+	};
+	/** The seats whose planted marker is still secret (the rules haven't revealed it). */
+	const secret = new Set(options.plant === void 0 ? [] : Array.from({ length: seats }, (_, seat) => seat));
+	const checkViews = (events) => {
+		for (const owner of secret) if (options.revealed?.(state, markerOf(owner)) === true) secret.delete(owner);
+		for (let viewer = 0; viewer < seats; viewer++) {
+			const seen = JSON.stringify(rules.view(state, viewer)) + JSON.stringify(events.map((event) => rules.eventView?.(event, viewer) ?? null));
+			for (const owner of secret) if (owner !== viewer && seen.includes(markerOf(owner))) fail(`seat ${String(viewer)} can see seat ${String(owner)}'s secret (seed ${String(seed)})`);
+		}
+		const shown = JSON.stringify(rules.view(state, null));
+		for (const owner of secret) if (shown.includes(markerOf(owner))) fail(`the public view shows seat ${String(owner)}'s secret (seed ${String(seed)})`);
+		checkTwin();
+	};
+	checkViews([]);
+	for (let moves = 0; moves < maxMoves; moves++) {
+		if (rules.outcome(state) !== null) return {
+			moves,
+			outOfTurn,
+			trace: trace.join("|")
+		};
+		const toAct = rules.toAct(state);
+		checkSeats(toAct, seats, "toAct", seed);
+		checkSeats(rules.mayAct?.(state) ?? [], seats, "mayAct", seed);
+		if (toAct.length === 0) fail(`toAct is empty but there is no outcome yet (seed ${String(seed)}, move ${String(moves)})`);
+		const next = nextMove(rules, options, state, toAct, rng, pick);
+		if (next === null) return fail(`no seat could move (seed ${String(seed)}, move ${String(moves)})`);
+		const { seat, move } = next;
+		outOfTurn += toAct.includes(seat) ? 0 : 1;
+		if (bytesOf(JSON.stringify(move)) > MOVE_MAX_BYTES) fail(`a move is over ${String(MOVE_MAX_BYTES)} bytes`);
+		const result = rules.apply(roundTrip(state), seat, roundTrip(move), rng);
+		if ("error" in result) fail(`${next.by} made an illegal move for seat ${String(seat)}: ${result.error} (seed ${String(seed)}, move ${String(moves)})`);
+		state = roundTrip(result.state);
+		if (bytesOf(JSON.stringify(state)) > STATE_MAX_BYTES) fail(`the state is over ${String(STATE_MAX_BYTES)} bytes`);
+		checkViews(result.events ?? []);
+		rules.progress(state, seat);
+		trace.push(`${String(seat)}:${JSON.stringify(move)}`);
+	}
+	return fail(`a game did not end within ${String(maxMoves)} moves (seed ${String(seed)})`);
+}
+/** Check a rules module (see the file comment); throws on the first failure. */
+function checkTurnRules(rules, options = {}) {
+	if (!Number.isInteger(rules.version) || rules.version < 0) fail("rules.version must be a whole number");
+	let games = 0;
+	let moves = 0;
+	let longestGame = 0;
+	let outOfTurn = 0;
+	for (const seats of options.seats ?? [2]) for (let game = 0; game < (options.games ?? 25); game++) {
+		const seed = seats * 100003 + game;
+		const played = playGame(rules, seats, seed, options);
+		if (playGame(rules, seats, seed, options).trace !== played.trace) fail(`the same seed played a different game (seed ${String(seed)}): use the rng you are given, never Math.random`);
+		games += 1;
+		moves += played.moves;
+		longestGame = Math.max(longestGame, played.moves);
+		outOfTurn += played.outOfTurn;
+	}
+	for (const fixture of options.fixtures ?? []) if (fixture.version < rules.version) {
+		if (rules.migrate === void 0) fail(`a version ${String(fixture.version)} fixture needs rules.migrate`);
+		const migrated = rules.migrate(roundTrip(fixture.state), fixture.version);
+		rules.view(migrated, null);
+		rules.toAct(migrated);
+	}
+	return {
+		games,
+		moves,
+		longestGame,
+		outOfTurn
+	};
+}
+//#endregion
+export { checkTurnRules, createTurnRng, defineTurnRules, turnRngStateFromSeed };
+
+//# sourceMappingURL=turns.js.map

package/dist/turns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turns.js","names":["createTurnRng","turnRngStateFromSeed"],"sources":["../src/turns-kit/check-rules.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffenderfer-games/hub",
-  "version": "2.0.0-next.1",
+  "version": "2.0.0-next.10",
   "description": "The diffenderfer.games hub client for games: accounts, saves, stats, leaderboards, inventory, daily challenges, the input system and the social/multiplayer forwarders, typed from the hub contract.",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/diffenderfer-games/diffenderfer-games.git",
-    "directory": "next/packages/public/hub"
+    "directory": "packages/public/hub"
   },
   "engines": {
     "node": ">=20"
@@ -59,11 +59,41 @@
       "types": "./dist/rooms.d.ts",
       "default": "./dist/rooms.js"
     },
+    "./turns": {
+      "source": "./src/turns.ts",
+      "types": "./dist/turns.d.ts",
+      "default": "./dist/turns.js"
+    },
+    "./turns-rules": {
+      "source": "./src/turns-rules.ts",
+      "types": "./dist/turns-rules.d.ts",
+      "default": "./dist/turns-rules.js"
+    },
     "./types": {
       "source": "./src/types.ts",
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
     },
+    "./avatar": {
+      "source": "./src/avatar.ts",
+      "types": "./dist/avatar.d.ts",
+      "default": "./dist/avatar.js"
+    },
+    "./avatar/pixi": {
+      "source": "./src/avatar-pixi.ts",
+      "types": "./dist/avatar-pixi.d.ts",
+      "default": "./dist/avatar-pixi.js"
+    },
+    "./avatar/three": {
+      "source": "./src/avatar-three.ts",
+      "types": "./dist/avatar-three.d.ts",
+      "default": "./dist/avatar-three.js"
+    },
+    "./avatar/svg": {
+      "source": "./src/avatar-svg.ts",
+      "types": "./dist/avatar-svg.d.ts",
+      "default": "./dist/avatar-svg.js"
+    },
     "./auto": {
       "source": "./src/auto.ts",
       "types": "./dist/auto.d.ts",
@@ -81,9 +111,15 @@
   },
   "dependencies": {
     "@ayepi/core": "0.4.1",
-    "@diffenderfer-games/hub-contract": "2.0.0-next.1"
+    "@diffenderfer-games/hub-contract": "2.0.0-next.10",
+    "@diffenderfer-games/world": "2.0.0-next.10"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@types/three": "0.186.0",
+    "pixi.js": "8.19.0",
+    "three": "0.186.1"
   }
 }

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

@@ -0,0 +1,73 @@
+/**
+ * One live avatar in Pixi (§3.8): a sprite backed by a canvas that redraws
+ * only when the pose changes, so a dozen animated faces stay cheap. Pass the
+ * game's pixi namespace; the hub never imports pixi.
+ */
+import type { Animator } from '../animator/animator';
+import { drawToCanvas } from '../outputs/bitmap';
+import { liveCanvas } from '../outputs/live-canvas';
+import type { LookLike, Pose, RenderOptions } from '../render/types';
+import { refresh, type PixiNs, type PixiRectangle, type PixiSprite, type PixiTexture } from './pixi-types';
+
+/** Options for {@link pixiAvatar}. */
+export interface PixiAvatarOptions extends RenderOptions {
+  /** Drives the face each `update(t)`; without one the avatar is still. */
+  readonly animator?: Animator;
+  /** Texture pixels per CSS pixel (default 2). */
+  readonly resolution?: number;
+}
+
+/** A live Pixi avatar; `view` is the game's own pixi `Sprite`. */
+export interface PixiAvatar<TSprite extends PixiSprite = PixiSprite> {
+  /** The sprite to add to the stage (anchored at its centre). */
+  readonly view: TSprite;
+  /** Renders the animator's pose at `t` (or a given pose). */
+  update(t: number | Pose): void;
+  /** Swaps the look. */
+  setLook(like: LookLike): void;
+  destroy(): void;
+}
+
+/** A live avatar sprite: `pixiAvatar(pixi, seat.look, { size: 64, animator })`. */
+export function pixiAvatar<TTexture extends PixiTexture, TSprite extends PixiSprite<TTexture>, TRectangle extends PixiRectangle>(
+  pixi: PixiNs<TTexture, TSprite, TRectangle>,
+  like: LookLike,
+  opts: PixiAvatarOptions = {},
+): PixiAvatar<TSprite> {
+  const resolution = opts.resolution ?? 2;
+  const live = liveCanvas(like, opts, resolution);
+  live.draw(opts.pose);
+  const texture = pixi.Texture.from(live.canvas);
+  const view = new pixi.Sprite(texture);
+  view.anchor.set(0.5);
+  view.scale.set(1 / resolution);
+  return {
+    view,
+    update(t) {
+      const pose = typeof t === 'number' ? opts.animator?.pose(t) : t;
+      if (live.draw(pose ?? opts.pose)) {
+        refresh(texture);
+      }
+    },
+    setLook(next) {
+      live.setLook(next);
+      opts.animator?.setLook(next);
+      if (live.draw(opts.pose)) {
+        refresh(texture);
+      }
+    },
+    destroy() {
+      view.destroy();
+      texture.destroy(true);
+    },
+  };
+}
+
+/** A still avatar texture (Pixi 7 games use this from a bitmap-like canvas). */
+export function avatarTexture<TTexture extends PixiTexture, TSprite extends PixiSprite<TTexture>, TRectangle extends PixiRectangle>(
+  pixi: PixiNs<TTexture, TSprite, TRectangle>,
+  like: LookLike,
+  opts: RenderOptions = {},
+): TTexture {
+  return pixi.Texture.from(drawToCanvas(like, opts));
+}

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);
+      }
+    },
+  };
+}