@agent-os-lab/agent-game-sdk 0.1.1

package/src/phaser/scene-reconciler.ts

@@ -0,0 +1,614 @@
+import {
+  normalizeAgentAvatarAnimationFrames,
+  type AgentAvatarAnimationName,
+  type AgentAvatarDefinition,
+  type AgentGameActivity,
+  type AgentGameAgent,
+  type AgentGameDirection,
+  type AgentGameSnapshot,
+} from "../core/index.js";
+import { createMovementTweenConfig, type MovementTimingOptions } from "./movement-tween.js";
+import { agentDepth, agentUiDepth } from "./render-layers.js";
+import { crispTextStyle } from "./text-style.js";
+
+const SPRITE_AGENT_SCALE = 1;
+const SPRITE_AGENT_FOOT_ORIGIN_Y = 1;
+const SPRITE_AGENT_LABEL_OFFSET_Y = 13;
+const SPRITE_AGENT_BUBBLE_OFFSET_Y = -51;
+const SPRITE_AGENT_EMOTION_OFFSET_X = 14;
+const SPRITE_AGENT_EMOTION_OFFSET_Y = -30;
+const PLACEHOLDER_AGENT_LABEL_OFFSET_Y = 30;
+const PLACEHOLDER_AGENT_BUBBLE_OFFSET_Y = -45;
+const PLACEHOLDER_AGENT_EMOTION_OFFSET_X = 18;
+const PLACEHOLDER_AGENT_EMOTION_OFFSET_Y = -24;
+const ARRIVAL_EPSILON = 0.5;
+
+export type PhaserDisplayObjectLike = {
+  x?: number;
+  y?: number;
+  setPosition?: (x: number, y: number) => PhaserDisplayObjectLike;
+  setDepth?: (depth: number) => PhaserDisplayObjectLike;
+  setFillStyle?: (fillColor: number, fillAlpha?: number) => PhaserDisplayObjectLike;
+  setStrokeStyle?: (lineWidth: number, color: number) => PhaserDisplayObjectLike;
+  setScale?: (scale: number) => PhaserDisplayObjectLike;
+  setDisplaySize?: (width: number, height: number) => PhaserDisplayObjectLike;
+  setOrigin?: (x?: number, y?: number) => PhaserDisplayObjectLike;
+  setVisible?: (visible: boolean) => PhaserDisplayObjectLike;
+  play?: (animationKey: string, ignoreIfPlaying?: boolean) => PhaserDisplayObjectLike;
+  stop?: () => PhaserDisplayObjectLike;
+  setFrame?: (frame: string) => PhaserDisplayObjectLike;
+};
+
+export type PhaserTextLike = PhaserDisplayObjectLike & {
+  setText?: (text: string) => PhaserTextLike;
+  setVisible?: (visible: boolean) => PhaserTextLike;
+  setOrigin?: (x?: number, y?: number) => PhaserTextLike;
+};
+
+export type PhaserReconcilerSceneLike = {
+  load?: {
+    atlas: (key: string, imageUrl: string, atlasUrl: string) => unknown;
+    image?: (key: string, imageUrl: string) => unknown;
+  };
+  textures?: {
+    getFrame?: (textureKey: string, frame: string) => unknown;
+  };
+  anims?: {
+    create: (config: {
+      key: string;
+      frames: Array<{ key: string; frame: string }>;
+      frameRate: number;
+      repeat: number;
+    }) => unknown;
+  };
+  add: {
+    rectangle: (x: number, y: number, width: number, height: number, fillColor: number) => PhaserDisplayObjectLike;
+    image?: (x: number, y: number, textureKey: string, frame?: string) => PhaserDisplayObjectLike;
+    sprite?: (x: number, y: number, textureKey: string, frame?: string) => PhaserDisplayObjectLike;
+    text: (x: number, y: number, text: string, style?: Record<string, unknown>) => PhaserTextLike;
+  };
+  tweens?: {
+    add: (config: Record<string, unknown>) => unknown;
+    killTweensOf?: (target: PhaserDisplayObjectLike) => unknown;
+  };
+  cameras?: {
+    main?: {
+      zoom: number;
+      scrollX: number;
+      scrollY: number;
+      width?: number;
+      height?: number;
+      setBounds?: (x: number, y: number, width: number, height: number) => unknown;
+      setZoom?: (zoom: number) => unknown;
+    };
+  };
+  input?: {
+    on: (eventName: string, handler: (...args: any[]) => void) => unknown;
+  };
+  events?: {
+    on: (eventName: string, handler: (...args: any[]) => void) => unknown;
+  };
+  children?: {
+    bringToTop?: (target: PhaserDisplayObjectLike) => unknown;
+  };
+};
+
+export type AgentGameSceneReconciler = {
+  reconcile(snapshot: AgentGameSnapshot): void;
+};
+
+type AgentVisual = {
+  shadow: PhaserDisplayObjectLike;
+  body: PhaserDisplayObjectLike;
+  head?: PhaserDisplayObjectLike;
+  usesSprite: boolean;
+  label: PhaserTextLike;
+  bubble: PhaserTextLike;
+  emotion: PhaserTextLike;
+  dom?: AgentDomOverlayVisual;
+  moveToken: number;
+  isMoving: boolean;
+  targetX: number;
+  targetY: number;
+  movementDirection: AgentGameDirection | null;
+};
+
+export type SceneReconcilerOptions = {
+  avatars?: AgentAvatarDefinition[];
+  domOverlay?: {
+    root: AgentDomOverlayRoot;
+  };
+  movementDurationMs?: number;
+  movementSpeedPxPerSecond?: number;
+  movementMinDurationMs?: number;
+  movementMaxDurationMs?: number;
+};
+
+export type AgentDomOverlayElement = {
+  className: string;
+  textContent: string | null;
+  clientWidth?: number;
+  clientHeight?: number;
+  style: Record<string, string>;
+  appendChild?: (child: AgentDomOverlayElement) => unknown;
+  remove?: () => unknown;
+};
+
+export type AgentDomOverlayRoot = AgentDomOverlayElement & {
+  ownerDocument?: {
+    createElement: (tagName: string) => AgentDomOverlayElement;
+  };
+};
+
+type AgentDomOverlayVisual = {
+  root: AgentDomOverlayRoot;
+  name: AgentDomOverlayElement;
+  bubble: AgentDomOverlayElement;
+  emotion: AgentDomOverlayElement;
+};
+
+export function createSceneReconciler(
+  scene: PhaserReconcilerSceneLike,
+  options: SceneReconcilerOptions = {},
+): AgentGameSceneReconciler {
+  const visuals = new Map<string, AgentVisual>();
+  const movementDurationMs = options.movementDurationMs ?? 0;
+  const movementSpeedPxPerSecond = options.movementSpeedPxPerSecond;
+  const movementMinDurationMs = options.movementMinDurationMs;
+  const movementMaxDurationMs = options.movementMaxDurationMs;
+  const avatarFrameRegistry = createAvatarFrameRegistry(options.avatars ?? []);
+  let postUpdateInstalled = false;
+
+  if (options.domOverlay?.root) {
+    installDomOverlayPostUpdate(scene, visuals, options.domOverlay.root, () => {
+      updateAllDomOverlays(scene, visuals);
+    });
+    postUpdateInstalled = true;
+  }
+
+  return {
+    reconcile(snapshot) {
+      for (const agent of Object.values(snapshot.agents)) {
+        const anchor = resolveAgentAnchor(snapshot, agent);
+        let visual = visuals.get(agent.agentId);
+        if (!visual) {
+          visual = createAgentVisual(scene, agent, anchor.x, anchor.y);
+          if (options.domOverlay?.root) {
+            visual.dom = createAgentDomOverlay(options.domOverlay.root);
+            hideCanvasLabels(visual);
+          }
+          visuals.set(agent.agentId, visual);
+        }
+
+        const fillColor = getActivityColor(agent.activity);
+        const movementDirection = moveVisual(scene, visual, anchor.x, anchor.y, {
+          durationMs: movementDurationMs,
+          speedPxPerSecond: movementSpeedPxPerSecond,
+          minDurationMs: movementMinDurationMs,
+          maxDurationMs: movementMaxDurationMs,
+        }, () => {
+          showStationaryFrame(visual.body, agent, avatarFrameRegistry);
+        });
+        const depth = getAgentDepth(anchor.y);
+        visual.shadow.setDepth?.(depth - 1);
+        visual.body.setFillStyle?.(fillColor);
+        visual.body.setDepth?.(depth);
+        if (movementDirection) {
+          visual.body.play?.(getWalkAnimationName(agent, movementDirection), true);
+        } else {
+          showStationaryFrame(visual.body, agent, avatarFrameRegistry);
+        }
+        visual.head?.setDepth?.(depth + 1);
+        visual.label.setText?.(agent.name).setDepth?.(depth + 2);
+        visual.bubble.setText?.(getStatusBubbleText(agent));
+        visual.bubble.setVisible?.(shouldShowStatusBubble(agent));
+        visual.bubble.setDepth?.(agentUiDepth());
+        visual.emotion.setText?.("");
+        visual.emotion.setVisible?.(false);
+        visual.emotion.setDepth?.(agentUiDepth(1));
+        updateDomOverlay(visual, scene, agent);
+      }
+      promoteAgentVisuals(scene, visuals);
+      if (options.domOverlay?.root && !postUpdateInstalled) {
+        updateAllDomOverlays(scene, visuals);
+      }
+    },
+  };
+}
+
+function installDomOverlayPostUpdate(
+  scene: PhaserReconcilerSceneLike,
+  visuals: Map<string, AgentVisual>,
+  root: AgentDomOverlayRoot,
+  update: () => void,
+): void {
+  if (!root || !visuals) {
+    return;
+  }
+  scene.events?.on?.("postupdate", update);
+}
+
+function getAgentDepth(y: number): number {
+  return agentDepth(y);
+}
+
+function promoteAgentVisuals(scene: PhaserReconcilerSceneLike, visuals: Map<string, AgentVisual>): void {
+  if (!scene.children?.bringToTop) {
+    return;
+  }
+
+  const orderedVisuals = [...visuals.values()].sort((a, b) => (a.body.y ?? 0) - (b.body.y ?? 0));
+  for (const visual of orderedVisuals) {
+    scene.children.bringToTop(visual.shadow);
+    scene.children.bringToTop(visual.body);
+    if (visual.head) {
+      scene.children.bringToTop(visual.head);
+    }
+    scene.children.bringToTop(visual.label);
+    scene.children.bringToTop(visual.bubble);
+    scene.children.bringToTop(visual.emotion);
+  }
+}
+
+function moveVisual(
+  scene: PhaserReconcilerSceneLike,
+  visual: AgentVisual,
+  x: number,
+  y: number,
+  movementTiming: MovementTimingOptions,
+  onArrive: () => void,
+): AgentGameDirection | null {
+  const current = {
+    x: visual.body.x ?? x,
+    y: visual.body.y ?? y,
+  };
+  if (isAtTarget(current, { x, y })) {
+    visual.isMoving = false;
+    visual.movementDirection = null;
+    visual.targetX = x;
+    visual.targetY = y;
+    return null;
+  }
+
+  if (visual.isMoving && visual.targetX === x && visual.targetY === y) {
+    return visual.movementDirection;
+  }
+
+  const tweenConfig = (movementTiming.speedPxPerSecond ?? movementTiming.durationMs ?? 0) > 0
+    ? createMovementTweenConfig(current, { x, y }, movementTiming)
+    : null;
+
+  if (tweenConfig && scene.tweens) {
+    killVisualTweens(scene, visual);
+    const moveToken = ++visual.moveToken;
+    const movementDirection = getMovementDirection(current, { x, y });
+    visual.isMoving = true;
+    visual.targetX = x;
+    visual.targetY = y;
+    visual.movementDirection = movementDirection;
+    scene.tweens.add({
+      targets: visual.body,
+      ...tweenConfig,
+      onComplete: () => {
+        if (visual.moveToken === moveToken) {
+          visual.isMoving = false;
+          visual.movementDirection = null;
+          visual.body.setPosition?.(x, y);
+          onArrive();
+        }
+      },
+    });
+    scene.tweens.add({ targets: visual.shadow, ...tweenConfig, y: y + 10 });
+    if (visual.head) {
+      scene.tweens.add({ targets: visual.head, ...tweenConfig, y: y - 14 });
+    }
+    scene.tweens.add({ targets: visual.label, ...tweenConfig, y: y + getLabelOffsetY(visual) });
+    scene.tweens.add({ targets: visual.bubble, ...tweenConfig, y: y + getBubbleOffsetY(visual) });
+    scene.tweens.add({ targets: visual.emotion, ...tweenConfig, x: x + getEmotionOffsetX(visual), y: y + getEmotionOffsetY(visual) });
+    return movementDirection;
+  }
+
+  killVisualTweens(scene, visual);
+  visual.moveToken++;
+  visual.isMoving = false;
+  visual.targetX = x;
+  visual.targetY = y;
+  visual.movementDirection = null;
+  visual.shadow.setPosition?.(x, y + 10);
+  visual.body.setPosition?.(x, y);
+  visual.head?.setPosition?.(x, y - 14);
+  visual.label.setPosition?.(x, y + getLabelOffsetY(visual));
+  visual.bubble.setPosition?.(x, y + getBubbleOffsetY(visual));
+  visual.emotion.setPosition?.(x + getEmotionOffsetX(visual), y + getEmotionOffsetY(visual));
+  return null;
+}
+
+function isAtTarget(current: { x: number; y: number }, target: { x: number; y: number }): boolean {
+  return Math.abs(current.x - target.x) <= ARRIVAL_EPSILON && Math.abs(current.y - target.y) <= ARRIVAL_EPSILON;
+}
+
+function killVisualTweens(scene: PhaserReconcilerSceneLike, visual: AgentVisual): void {
+  scene.tweens?.killTweensOf?.(visual.body);
+  scene.tweens?.killTweensOf?.(visual.shadow);
+  if (visual.head) {
+    scene.tweens?.killTweensOf?.(visual.head);
+  }
+  scene.tweens?.killTweensOf?.(visual.label);
+  scene.tweens?.killTweensOf?.(visual.bubble);
+  scene.tweens?.killTweensOf?.(visual.emotion);
+}
+
+function getMovementDirection(current: { x: number; y: number }, target: { x: number; y: number }): AgentGameDirection {
+  const dx = target.x - current.x;
+  const dy = target.y - current.y;
+  if (Math.abs(dx) >= Math.abs(dy)) {
+    return dx < 0 ? "left" : "right";
+  }
+  return dy < 0 ? "up" : "down";
+}
+
+function createAgentVisual(scene: PhaserReconcilerSceneLike, agent: AgentGameAgent, x: number, y: number): AgentVisual {
+  const shadow = scene.add.rectangle(x, y + 10, 24, 8, 0x0f172a);
+  shadow.setDepth?.(9);
+  shadow.setVisible?.(false);
+  let usesSprite = false;
+  let body: PhaserDisplayObjectLike;
+  if (scene.add.sprite) {
+    usesSprite = true;
+    body = scene.add.sprite(x, y, agent.avatarId);
+  } else {
+    body = scene.add.rectangle(x, y, 18, 24, getActivityColor(agent.activity));
+  }
+  body.setScale?.(usesSprite ? SPRITE_AGENT_SCALE : 1.5);
+  body.setOrigin?.(0.5, usesSprite ? SPRITE_AGENT_FOOT_ORIGIN_Y : 0.72);
+  body.setDepth?.(10);
+  const head = usesSprite ? undefined : scene.add.rectangle(x, y - 14, 14, 12, 0xf8c8a0);
+  head?.setDepth?.(11);
+  const label = scene.add.text(x, y + getLabelOffsetY({ usesSprite }), agent.name, crispTextStyle({
+    color: "#f8fafc",
+    fontSize: usesSprite ? "8px" : "11px",
+    fontFamily: "monospace",
+  }));
+  label.setOrigin?.(0.5, 0);
+  const bubble = scene.add.text(x, y + getBubbleOffsetY({ usesSprite }), getStatusBubbleText(agent), crispTextStyle({
+    color: "#111827",
+    backgroundColor: "#f8fafc",
+    fontSize: usesSprite ? "8px" : "12px",
+    fontFamily: "sans-serif",
+    padding: usesSprite ? { x: 4, y: 2 } : { x: 6, y: 4 },
+  }));
+  bubble.setOrigin?.(0.5, 1);
+  bubble.setVisible?.(shouldShowStatusBubble(agent));
+  const emotion = scene.add.text(x + getEmotionOffsetX({ usesSprite }), y + getEmotionOffsetY({ usesSprite }), "", crispTextStyle({
+    color: "#f8fafc",
+    fontSize: usesSprite ? "7px" : "10px",
+    fontFamily: "monospace",
+    padding: usesSprite ? { x: 3, y: 1 } : { x: 4, y: 2 },
+  }));
+  emotion.setOrigin?.(0, 0.5);
+  emotion.setVisible?.(false);
+
+  return {
+    shadow,
+    body,
+    head,
+    usesSprite,
+    label,
+    bubble,
+    emotion,
+    dom: undefined,
+    moveToken: 0,
+    isMoving: false,
+    targetX: x,
+    targetY: y,
+    movementDirection: null,
+  };
+}
+
+function createAgentDomOverlay(root: AgentDomOverlayRoot): AgentDomOverlayVisual {
+  const name = createDomOverlayElement(root, "agent-dom-label");
+  const bubble = createDomOverlayElement(root, "agent-dom-bubble");
+  const emotion = createDomOverlayElement(root, "agent-dom-emotion");
+  root.appendChild?.(name);
+  root.appendChild?.(bubble);
+  root.appendChild?.(emotion);
+  return { root, name, bubble, emotion };
+}
+
+function createDomOverlayElement(root: AgentDomOverlayRoot, className: string): AgentDomOverlayElement {
+  const element = root.ownerDocument?.createElement("div") ?? globalThis.document?.createElement?.("div");
+  if (!element) {
+    throw new Error("DOM overlay requires document.createElement");
+  }
+  element.className = className;
+  element.style.position = "absolute";
+  element.style.left = "0";
+  element.style.top = "0";
+  element.style.pointerEvents = "none";
+  element.style.transform = "translate3d(-9999px, -9999px, 0)";
+  return element as AgentDomOverlayElement;
+}
+
+function hideCanvasLabels(visual: AgentVisual): void {
+  visual.label.setVisible?.(false);
+  visual.bubble.setVisible?.(false);
+  visual.emotion.setVisible?.(false);
+}
+
+function updateAllDomOverlays(scene: PhaserReconcilerSceneLike, visuals: Map<string, AgentVisual>): void {
+  for (const visual of visuals.values()) {
+    if (visual.dom) {
+      positionDomOverlay(visual, scene);
+    }
+  }
+}
+
+function updateDomOverlay(visual: AgentVisual, scene: PhaserReconcilerSceneLike, agent: AgentGameAgent): void {
+  if (!visual.dom) {
+    return;
+  }
+  visual.label.setVisible?.(false);
+  visual.bubble.setVisible?.(false);
+  visual.emotion.setVisible?.(false);
+  visual.dom.name.textContent = agent.name;
+  visual.dom.bubble.textContent = getStatusBubbleText(agent);
+  visual.dom.bubble.style.display = shouldShowStatusBubble(agent) ? "block" : "none";
+  visual.dom.emotion.textContent = "";
+  visual.dom.emotion.style.display = "none";
+  positionDomOverlay(visual, scene);
+}
+
+function positionDomOverlay(visual: AgentVisual, scene: PhaserReconcilerSceneLike): void {
+  const camera = scene.cameras?.main;
+  if (!camera || !visual.dom) {
+    return;
+  }
+  setDomPosition(visual.dom.root, visual.dom.name, visual, camera, 0, getLabelOffsetY(visual));
+  setDomPosition(visual.dom.root, visual.dom.bubble, visual, camera, 0, getBubbleOffsetY(visual));
+  setDomPosition(visual.dom.root, visual.dom.emotion, visual, camera, getEmotionOffsetX(visual), getEmotionOffsetY(visual));
+}
+
+function setDomPosition(
+  root: AgentDomOverlayRoot,
+  element: AgentDomOverlayElement,
+  visual: AgentVisual,
+  camera: NonNullable<PhaserReconcilerSceneLike["cameras"]>["main"],
+  offsetX: number,
+  offsetY: number,
+): void {
+  if (!camera) {
+    return;
+  }
+  const scaleX = camera.width && root.clientWidth ? root.clientWidth / camera.width : 1;
+  const scaleY = camera.height && root.clientHeight ? root.clientHeight / camera.height : 1;
+  const x = Math.round(((visual.body.x ?? 0) + offsetX - camera.scrollX) * camera.zoom * scaleX);
+  const y = Math.round(((visual.body.y ?? 0) + offsetY - camera.scrollY) * camera.zoom * scaleY);
+  const scale = camera.zoom * Math.min(scaleX, scaleY);
+  element.style.transform = `translate3d(${x}px, ${y}px, 0) translate(-50%, -50%) scale(${formatDomScale(scale)})`;
+}
+
+function formatDomScale(scale: number): string {
+  return Number.isInteger(scale) ? String(scale) : scale.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function getLabelOffsetY(visual: Pick<AgentVisual, "usesSprite">): number {
+  return visual.usesSprite ? SPRITE_AGENT_LABEL_OFFSET_Y : PLACEHOLDER_AGENT_LABEL_OFFSET_Y;
+}
+
+function getBubbleOffsetY(visual: Pick<AgentVisual, "usesSprite">): number {
+  return visual.usesSprite ? SPRITE_AGENT_BUBBLE_OFFSET_Y : PLACEHOLDER_AGENT_BUBBLE_OFFSET_Y;
+}
+
+function getEmotionOffsetX(visual: Pick<AgentVisual, "usesSprite">): number {
+  return visual.usesSprite ? SPRITE_AGENT_EMOTION_OFFSET_X : PLACEHOLDER_AGENT_EMOTION_OFFSET_X;
+}
+
+function getEmotionOffsetY(visual: Pick<AgentVisual, "usesSprite">): number {
+  return visual.usesSprite ? SPRITE_AGENT_EMOTION_OFFSET_Y : PLACEHOLDER_AGENT_EMOTION_OFFSET_Y;
+}
+
+function resolveAgentAnchor(snapshot: AgentGameSnapshot, agent: AgentGameAgent) {
+  const targetLocationId = agent.activity.kind === "moving" ? agent.activity.toLocationId : agent.locationId;
+  return snapshot.scene.anchors.find((anchor) => anchor.id === targetLocationId) ?? snapshot.scene.anchors.find((anchor) => anchor.id === agent.locationId)!;
+}
+
+function getActivityColor(activity: AgentGameActivity): number {
+  switch (activity.kind) {
+    case "moving":
+      return 0xfacc15;
+    case "working":
+      return 0x22c55e;
+    case "thinking":
+      return 0xa78bfa;
+    case "talking":
+      return 0x38bdf8;
+    case "tool_call":
+      return activity.status === "failed" ? 0xef4444 : activity.status === "succeeded" ? 0x14b8a6 : 0xfb923c;
+    case "idle":
+      return 0xe5e7eb;
+  }
+}
+
+function getStatusBubbleText(agent: AgentGameAgent): string {
+  const emotionLabel = getEmotionLabel(agent);
+  const prefix = emotionLabel ? `${emotionLabel} ` : "";
+  switch (agent.activity.kind) {
+    case "moving":
+      return `${prefix}移动中`;
+    case "working":
+      return `${prefix}工作中`;
+    case "thinking":
+      return agent.activity.text ? `${prefix}思考中：${agent.activity.text}` : `${prefix}思考中`;
+    case "talking":
+      return `${prefix}说话中：${agent.activity.text}`;
+    case "tool_call":
+      return `${prefix}${agent.activity.toolName}: ${getToolCallStatusLabel(agent.activity.status)}`;
+    case "idle":
+      return getEmotionLabel(agent);
+  }
+}
+
+function getToolCallStatusLabel(status: Extract<AgentGameActivity, { kind: "tool_call" }>["status"]): string {
+  switch (status) {
+    case "started":
+      return "执行中";
+    case "succeeded":
+      return "完成";
+    case "failed":
+      return "失败";
+  }
+}
+
+function getWalkAnimationName(agent: AgentGameAgent, movementDirection: AgentGameDirection): string {
+  return `${agent.avatarId}:walk.${movementDirection}`;
+}
+
+function showStationaryFrame(
+  body: PhaserDisplayObjectLike,
+  agent: AgentGameAgent,
+  registry: AvatarFrameRegistry,
+): void {
+  body.stop?.();
+  body.setFrame?.(getStationaryFrame(agent, registry));
+}
+
+type AvatarFrameRegistry = Map<string, Partial<Record<AgentAvatarAnimationName, string>>>;
+
+function createAvatarFrameRegistry(avatars: AgentAvatarDefinition[]): AvatarFrameRegistry {
+  const registry: AvatarFrameRegistry = new Map();
+  for (const avatar of avatars) {
+    const frames: Partial<Record<AgentAvatarAnimationName, string>> = {};
+    for (const [animation, animationFrames] of Object.entries(avatar.animations)) {
+      const firstFrame = normalizeAgentAvatarAnimationFrames(animationFrames)[0];
+      if (firstFrame) {
+        frames[animation as AgentAvatarAnimationName] = firstFrame;
+      }
+    }
+    registry.set(avatar.id, frames);
+  }
+  return registry;
+}
+
+function getStationaryFrame(agent: AgentGameAgent, registry: AvatarFrameRegistry): string {
+  const animation = `idle.${agent.direction}` as AgentAvatarAnimationName;
+  return registry.get(agent.avatarId)?.[animation] ?? `idle-${agent.direction}-0`;
+}
+
+function getEmotionLabel(agent: AgentGameAgent): string {
+  switch (agent.emotion) {
+    case "focused":
+      return "🎯";
+    case "happy":
+      return "🙂";
+    case "blocked":
+      return "⛔";
+    case "tired":
+      return "😴";
+    case undefined:
+      return agent.activity.kind === "idle" ? "🙂" : "";
+  }
+}
+
+function shouldShowStatusBubble(agent: AgentGameAgent): boolean {
+  return getStatusBubbleText(agent) !== "";
+}