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

package/src/phaser/agent-game-scene.ts

@@ -0,0 +1,87 @@
+import type { AgentAvatarDefinition, AgentGameSceneDefinition, OfficeBuildingLayout, OfficeLayoutDefinition } from "../core/index.js";
+import { drawAnchorDebug } from "./anchor-debug.js";
+import { registerAgentAvatarAnimations } from "./avatar-registry.js";
+import {
+  installCameraControls,
+  type AgentGameCameraControlsController,
+  type AgentGameCameraControlsOptions,
+} from "./camera-controls.js";
+import type { AgentGameDebugOverlays } from "./debug-overlay.js";
+import {
+  createDefaultAgentGameSceneRendererRegistry,
+  type AgentGameRendererConfig,
+  type AgentGameSceneRendererRegistry,
+} from "./scene-renderer.js";
+import type { AgentGameSceneReconciler, PhaserReconcilerSceneLike } from "./scene-reconciler.js";
+import type { TownOfficeDomOverlayRoot } from "./town-office-renderer.js";
+
+export const AGENT_GAME_PHASER_SCENE_KEY = "agent-game-scene";
+
+export type AgentGamePhaserSceneConfig = {
+  key?: string;
+  definition: AgentGameSceneDefinition;
+  avatars: AgentAvatarDefinition[];
+  width: number;
+  height: number;
+  backgroundImage?: {
+    key: string;
+    url: string;
+    width: number;
+    height: number;
+  };
+  officeLayout?: {
+    atlasKey: string;
+    imageUrl: string;
+    atlasUrl: string;
+    definition: OfficeLayoutDefinition;
+  };
+  officeBuilding?: {
+    atlasKey: string;
+    imageUrl: string;
+    atlasUrl: string;
+    layout: OfficeBuildingLayout;
+  };
+  townOfficeBuilding?: {
+    layout: OfficeBuildingLayout;
+  };
+  renderer: AgentGameRendererConfig;
+  rendererRegistry?: AgentGameSceneRendererRegistry;
+  domOverlayRoot?: TownOfficeDomOverlayRoot;
+  debugOverlays?: AgentGameDebugOverlays;
+  showAnchorDebug?: boolean;
+  cameraControls?: AgentGameCameraControlsOptions;
+  movementDurationMs?: number;
+  onCameraControlsReady?: (controls: AgentGameCameraControlsController | null) => void;
+  onCreate?: (scene: PhaserReconcilerSceneLike) => AgentGameSceneReconciler;
+};
+
+export function createAgentGamePhaserSceneConfig(config: AgentGamePhaserSceneConfig) {
+  const rendererRegistry = config.rendererRegistry ?? createDefaultAgentGameSceneRendererRegistry();
+  const renderer = rendererRegistry.create(config.renderer.kind, {
+    ...(typeof config.renderer.options === "object" && config.renderer.options ? config.renderer.options : {}),
+    domOverlayRoot: config.domOverlayRoot,
+  });
+
+  return {
+    key: config.key ?? AGENT_GAME_PHASER_SCENE_KEY,
+    preload(this: PhaserReconcilerSceneLike) {
+      renderer.preload?.(this);
+      for (const avatar of config.avatars) {
+        this.load?.atlas(avatar.id, avatar.imageUrl, avatar.atlasUrl);
+      }
+    },
+    create(this: PhaserReconcilerSceneLike) {
+      for (const avatar of config.avatars) {
+        registerAgentAvatarAnimations(this, avatar);
+      }
+      renderer.create(this);
+      if (config.debugOverlays?.anchors || config.showAnchorDebug) {
+        drawAnchorDebug(this, config.definition);
+      }
+      if (config.cameraControls) {
+        config.onCameraControlsReady?.(installCameraControls(this, config.cameraControls));
+      }
+      config.onCreate?.(this);
+    },
+  };
+}

package/src/phaser/anchor-debug.ts

@@ -0,0 +1,22 @@
+import type { AgentGameSceneDefinition } from "../core/index.js";
+import { debugDepth } from "./render-layers.js";
+import type { PhaserDisplayObjectLike, PhaserTextLike } from "./scene-reconciler.js";
+import { crispTextStyle } from "./text-style.js";
+
+export type AnchorDebugSceneLike = {
+  add: {
+    rectangle: (x: number, y: number, width: number, height: number, fillColor: number) => PhaserDisplayObjectLike;
+    text: (x: number, y: number, text: string, style?: Record<string, unknown>) => PhaserTextLike;
+  };
+};
+
+export function drawAnchorDebug(scene: AnchorDebugSceneLike, definition: AgentGameSceneDefinition): void {
+  for (const anchor of definition.anchors) {
+    scene.add.rectangle(anchor.x, anchor.y, 8, 8, 0xf97316).setDepth?.(debugDepth(10));
+    scene.add.text(anchor.x + 8, anchor.y + 6, anchor.id, crispTextStyle({
+      color: "#f8fafc",
+      fontSize: "10px",
+      fontFamily: "monospace",
+    })).setDepth?.(debugDepth(11));
+  }
+}

package/src/phaser/avatar-registry.ts

@@ -0,0 +1,46 @@
+import {
+  AgentGameError,
+  REQUIRED_AGENT_AVATAR_ANIMATIONS,
+  normalizeAgentAvatarAnimationFrames,
+  validateAgentAvatarDefinition,
+  type AgentAvatarDefinition,
+  type AgentAvatarAnimationName,
+} from "../core/index.js";
+
+export type PhaserAnimationSceneLike = {
+  textures?: {
+    getFrame?: (textureKey: string, frame: string) => unknown;
+  };
+  anims?: {
+    create: (config: {
+      key: string;
+      frames: Array<{ key: string; frame: string }>;
+      frameRate: number;
+      repeat: number;
+    }) => unknown;
+  };
+};
+
+export function createAgentAvatarAnimationKey(avatarId: string, animation: AgentAvatarAnimationName): string {
+  return `${avatarId}:${animation}`;
+}
+
+export function registerAgentAvatarAnimations(scene: PhaserAnimationSceneLike, avatar: AgentAvatarDefinition): void {
+  validateAgentAvatarDefinition(avatar);
+
+  for (const animation of REQUIRED_AGENT_AVATAR_ANIMATIONS) {
+    const frames = normalizeAgentAvatarAnimationFrames(avatar.animations[animation]);
+    for (const frame of frames) {
+      if (scene.textures?.getFrame && !scene.textures.getFrame(avatar.id, frame)) {
+        throw new AgentGameError("missing_animation", `Agent game avatar ${avatar.id} is missing frame: ${frame}`);
+      }
+    }
+
+    scene.anims?.create({
+      key: createAgentAvatarAnimationKey(avatar.id, animation),
+      frames: frames.map((frame) => ({ key: avatar.id, frame })),
+      frameRate: animation.startsWith("walk.") ? 8 : 4,
+      repeat: -1,
+    });
+  }
+}

package/src/phaser/camera-controls.ts

@@ -0,0 +1,419 @@
+import {
+  clampCameraScrollValue,
+  dragCamera,
+  getCameraScrollBounds,
+  snapCameraScrollToPixel,
+  zoomAroundPoint,
+} from "./camera-model.js";
+
+export type AgentGameCameraControlsOptions = {
+  enabled?: boolean;
+  worldWidth: number;
+  worldHeight: number;
+  initialZoom?: number | "fit-width";
+  minZoom?: number;
+  maxZoom?: number;
+  zoomStep?: number;
+  zoomLevels?: number[];
+  wheelZoom?: boolean;
+  centerWhenViewLarger?: boolean;
+  onZoomChange?: (zoom: number) => void;
+  onViewChange?: (view: AgentGameCameraViewState) => void;
+};
+
+export type AgentGameCameraControlsController = {
+  getZoom(): number;
+  zoomIn(): void;
+  zoomOut(): void;
+  setZoom(zoom: number): void;
+};
+
+export type AgentGameCameraViewState = {
+  zoom: number;
+  scrollX: number;
+  scrollY: number;
+  visibleWidth: number;
+  visibleHeight: number;
+  bounds: {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+  };
+};
+
+export type PhaserCameraControlsSceneLike = {
+  cameras?: {
+    main?: PhaserCameraLike;
+  };
+  input?: {
+    on: (eventName: string, handler: (...args: any[]) => void) => unknown;
+  };
+  game?: {
+    canvas?: HTMLCanvasElement;
+  };
+  sys?: {
+    game?: {
+      canvas?: HTMLCanvasElement;
+    };
+  };
+};
+
+type PhaserCameraLike = {
+  zoom: number;
+  scrollX: number;
+  scrollY: number;
+  width?: number;
+  height?: number;
+  setBounds?: (x: number, y: number, width: number, height: number) => unknown;
+  setOrigin?: (x: number, y: number) => unknown;
+  setZoom?: (zoom: number) => unknown;
+};
+
+type PointerLike = {
+  x: number;
+  y: number;
+  isDown?: boolean;
+};
+
+export function installCameraControls(
+  scene: PhaserCameraControlsSceneLike,
+  options: AgentGameCameraControlsOptions,
+): AgentGameCameraControlsController | null {
+  if (options.enabled === false) {
+    return null;
+  }
+
+  const camera = scene.cameras?.main;
+  if (!camera || !scene.input) {
+    return null;
+  }
+
+  const minZoom = options.minZoom ?? 0.5;
+  const maxZoom = options.maxZoom ?? 2;
+  const zoomStep = options.zoomStep ?? 0.1;
+  camera.setOrigin?.(0, 0);
+  camera.setZoom?.(resolveInitialZoom(camera, options, minZoom, maxZoom));
+  clampCameraScroll(camera, options.worldWidth, options.worldHeight);
+  centerCameraIfViewLarger(camera, options);
+  snapCameraScroll(camera);
+  emitCameraView(camera, options);
+
+  const controls: AgentGameCameraControlsController = {
+    getZoom() {
+      return camera.zoom;
+    },
+    zoomIn() {
+      zoomCamera(camera, options, getNextZoom(camera.zoom, 1, {
+        minZoom,
+        maxZoom,
+        zoomStep,
+        zoomLevels: options.zoomLevels,
+      }));
+    },
+    zoomOut() {
+      zoomCamera(camera, options, getNextZoom(camera.zoom, -1, {
+        minZoom,
+        maxZoom,
+        zoomStep,
+        zoomLevels: options.zoomLevels,
+      }));
+    },
+    setZoom(zoom: number) {
+      zoomCamera(camera, options, clamp(zoom, minZoom, maxZoom));
+    },
+  };
+
+  let dragStart: { x: number; y: number; scrollX: number; scrollY: number } | null = null;
+  let windowMoveHandler: ((event: PointerEvent) => void) | null = null;
+  let windowUpHandler: (() => void) | null = null;
+
+  if (options.wheelZoom !== false) {
+    scene.input.on("wheel", (pointer: PointerLike, _gameObjects: unknown, _deltaX: number, deltaY: number) => {
+      const direction = deltaY < 0 ? 1 : -1;
+      const newZoom = getNextZoom(camera.zoom, direction, {
+        minZoom,
+        maxZoom,
+        zoomStep,
+        zoomLevels: options.zoomLevels,
+      });
+      zoomCamera(camera, options, newZoom, getZoomAnchor(pointer, camera));
+    });
+  }
+
+  scene.input.on("pointerdown", (pointer: PointerLike) => {
+    dragStart = {
+      x: pointer.x,
+      y: pointer.y,
+      scrollX: camera.scrollX,
+      scrollY: camera.scrollY,
+    };
+    installWindowDragHandlers(scene, camera, options, () => dragStart, (point) => {
+      updateDrag(camera, options, dragStart, point);
+    }, () => {
+      dragStart = null;
+      uninstallWindowDragHandlers(windowMoveHandler, windowUpHandler);
+      windowMoveHandler = null;
+      windowUpHandler = null;
+    }, (moveHandler, upHandler) => {
+      windowMoveHandler = moveHandler;
+      windowUpHandler = upHandler;
+    });
+  });
+
+  scene.input.on("pointermove", (pointer: PointerLike) => {
+    if (!dragStart || pointer.isDown === false) {
+      return;
+    }
+    updateDrag(camera, options, dragStart, pointer);
+  });
+
+  const stopDrag = () => {
+    dragStart = null;
+    uninstallWindowDragHandlers(windowMoveHandler, windowUpHandler);
+    windowMoveHandler = null;
+    windowUpHandler = null;
+  };
+  scene.input.on("pointerup", stopDrag);
+  scene.input.on("pointerupoutside", stopDrag);
+
+  return controls;
+}
+
+function zoomCamera(
+  camera: PhaserCameraLike,
+  options: AgentGameCameraControlsOptions,
+  targetZoom: number,
+  anchor = getZoomAnchor(undefined, camera),
+): void {
+  const zoomed = zoomAroundPoint({
+    scrollX: camera.scrollX,
+    scrollY: camera.scrollY,
+    zoom: camera.zoom,
+    targetZoom,
+    anchorX: anchor.x,
+    anchorY: anchor.y,
+  });
+
+  camera.setZoom?.(zoomed.zoom);
+  camera.scrollX = zoomed.scrollX;
+  camera.scrollY = zoomed.scrollY;
+  clampCameraScroll(camera, options.worldWidth, options.worldHeight);
+  centerCameraIfViewLarger(camera, options);
+  snapCameraScroll(camera);
+  emitCameraView(camera, options);
+}
+
+function updateDrag(
+  camera: PhaserCameraLike,
+  options: AgentGameCameraControlsOptions,
+  dragStart: { x: number; y: number; scrollX: number; scrollY: number } | null,
+  point: { x: number; y: number },
+): void {
+  if (!dragStart) {
+    return;
+  }
+
+  const next = dragCamera({
+    startX: dragStart.x,
+    startY: dragStart.y,
+    currentX: point.x,
+    currentY: point.y,
+    startScrollX: dragStart.scrollX,
+    startScrollY: dragStart.scrollY,
+    zoom: camera.zoom,
+    xBounds: getCameraScrollBounds(options.worldWidth, camera.width ?? 0, camera.zoom),
+    yBounds: getCameraScrollBounds(options.worldHeight, camera.height ?? 0, camera.zoom),
+  });
+  camera.scrollX = next.scrollX;
+  camera.scrollY = next.scrollY;
+  snapCameraScroll(camera);
+  emitCameraView(camera, options);
+}
+
+function installWindowDragHandlers(
+  scene: PhaserCameraControlsSceneLike,
+  camera: PhaserCameraLike,
+  options: AgentGameCameraControlsOptions,
+  getDragStart: () => { x: number; y: number; scrollX: number; scrollY: number } | null,
+  update: (point: { x: number; y: number }) => void,
+  stop: () => void,
+  setHandlers: (moveHandler: (event: PointerEvent) => void, upHandler: () => void) => void,
+): void {
+  if (!globalThis.window || !globalThis.window.addEventListener) {
+    return;
+  }
+
+  const canvas = getSceneCanvas(scene);
+  if (!canvas) {
+    return;
+  }
+
+  const moveHandler = (event: PointerEvent) => {
+    if (!getDragStart()) {
+      return;
+    }
+    update(clientPointToGamePoint(event.clientX, event.clientY, canvas, camera));
+  };
+  const upHandler = () => {
+    stop();
+  };
+  setHandlers(moveHandler, upHandler);
+  globalThis.window.addEventListener("pointermove", moveHandler);
+  globalThis.window.addEventListener("pointerup", upHandler);
+}
+
+function uninstallWindowDragHandlers(
+  moveHandler: ((event: PointerEvent) => void) | null,
+  upHandler: (() => void) | null,
+): void {
+  if (!globalThis.window || !globalThis.window.removeEventListener) {
+    return;
+  }
+  if (moveHandler) {
+    globalThis.window.removeEventListener("pointermove", moveHandler);
+  }
+  if (upHandler) {
+    globalThis.window.removeEventListener("pointerup", upHandler);
+  }
+}
+
+function getSceneCanvas(scene: PhaserCameraControlsSceneLike): HTMLCanvasElement | undefined {
+  return scene.game?.canvas ?? scene.sys?.game?.canvas;
+}
+
+function clientPointToGamePoint(
+  clientX: number,
+  clientY: number,
+  canvas: HTMLCanvasElement,
+  camera: PhaserCameraLike,
+): { x: number; y: number } {
+  const bounds = canvas.getBoundingClientRect();
+  const width = camera.width ?? bounds.width;
+  const height = camera.height ?? bounds.height;
+
+  return {
+    x: bounds.width > 0 ? (clientX - bounds.left) * width / bounds.width : clientX,
+    y: bounds.height > 0 ? (clientY - bounds.top) * height / bounds.height : clientY,
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function resolveInitialZoom(
+  camera: PhaserCameraLike,
+  options: AgentGameCameraControlsOptions,
+  minZoom: number,
+  maxZoom: number,
+): number {
+  if (options.initialZoom === "fit-width") {
+    const width = camera.width ?? 0;
+    if (width > 0 && options.worldWidth > 0) {
+      return clamp(width / options.worldWidth, minZoom, maxZoom);
+    }
+    return clamp(camera.zoom ?? 1, minZoom, maxZoom);
+  }
+
+  return clamp(options.initialZoom ?? camera.zoom ?? 1, minZoom, maxZoom);
+}
+
+function getNextZoom(
+  currentZoom: number,
+  direction: number,
+  options: {
+    minZoom: number;
+    maxZoom: number;
+    zoomStep: number;
+    zoomLevels?: number[];
+  },
+): number {
+  const levels = normalizeZoomLevels(options.zoomLevels, options.minZoom, options.maxZoom);
+  if (levels.length > 0) {
+    if (direction > 0) {
+      return levels.find((level) => level > currentZoom + Number.EPSILON) ?? levels.at(-1)!;
+    }
+    return [...levels].reverse().find((level) => level < currentZoom - Number.EPSILON) ?? levels[0]!;
+  }
+
+  return clamp(currentZoom + direction * options.zoomStep, options.minZoom, options.maxZoom);
+}
+
+function normalizeZoomLevels(levels: number[] | undefined, minZoom: number, maxZoom: number): number[] {
+  return [...new Set((levels ?? [])
+    .filter((level) => Number.isFinite(level) && level >= minZoom && level <= maxZoom))]
+    .sort((a, b) => a - b);
+}
+
+function getZoomAnchor(pointer: PointerLike | undefined, camera: PhaserCameraLike): { x: number; y: number } {
+  return {
+    x: Number.isFinite(pointer?.x) ? pointer!.x : (camera.width ?? 0) / 2,
+    y: Number.isFinite(pointer?.y) ? pointer!.y : (camera.height ?? 0) / 2,
+  };
+}
+
+function clampScroll(value: number, worldSize: number, viewportSize: number | undefined, zoom: number): number {
+  if (!viewportSize || viewportSize <= 0) {
+    return value;
+  }
+
+  return clampCameraScrollValue(value, getCameraScrollBounds(worldSize, viewportSize, zoom));
+}
+
+function clampCameraScroll(camera: PhaserCameraLike, worldWidth: number, worldHeight: number): void {
+  camera.scrollX = clampScroll(camera.scrollX, worldWidth, camera.width, camera.zoom);
+  camera.scrollY = clampScroll(camera.scrollY, worldHeight, camera.height, camera.zoom);
+}
+
+function snapCameraScroll(camera: PhaserCameraLike): void {
+  camera.scrollX = snapCameraScrollToPixel(camera.scrollX, camera.zoom);
+  camera.scrollY = snapCameraScrollToPixel(camera.scrollY, camera.zoom);
+}
+
+function centerCameraIfViewLarger(camera: PhaserCameraLike, options: AgentGameCameraControlsOptions): void {
+  if (!options.centerWhenViewLarger) {
+    return;
+  }
+
+  const width = camera.width ?? 0;
+  const height = camera.height ?? 0;
+  if (width > 0 && width / camera.zoom > options.worldWidth) {
+    const bounds = getCameraScrollBounds(options.worldWidth, width, camera.zoom);
+    camera.scrollX = (bounds.min + bounds.max) / 2;
+  }
+  if (height > 0 && height / camera.zoom > options.worldHeight) {
+    const bounds = getCameraScrollBounds(options.worldHeight, height, camera.zoom);
+    camera.scrollY = (bounds.min + bounds.max) / 2;
+  }
+}
+
+function emitCameraView(camera: PhaserCameraLike, options: AgentGameCameraControlsOptions): void {
+  options.onZoomChange?.(camera.zoom);
+  options.onViewChange?.(createCameraViewState(camera, options.worldWidth, options.worldHeight));
+}
+
+function createCameraViewState(
+  camera: PhaserCameraLike,
+  worldWidth: number,
+  worldHeight: number,
+): AgentGameCameraViewState {
+  const visibleWidth = camera.width && camera.width > 0 ? camera.width / camera.zoom : 0;
+  const visibleHeight = camera.height && camera.height > 0 ? camera.height / camera.zoom : 0;
+  const xBounds = getCameraScrollBounds(worldWidth, camera.width ?? 0, camera.zoom);
+  const yBounds = getCameraScrollBounds(worldHeight, camera.height ?? 0, camera.zoom);
+
+  return {
+    zoom: camera.zoom,
+    scrollX: camera.scrollX,
+    scrollY: camera.scrollY,
+    visibleWidth,
+    visibleHeight,
+    bounds: {
+      minX: xBounds.min,
+      maxX: xBounds.max,
+      minY: yBounds.min,
+      maxY: yBounds.max,
+    },
+  };
+}

package/src/phaser/camera-model.ts

@@ -0,0 +1,81 @@
+export type CameraScrollBounds = {
+  min: number;
+  max: number;
+};
+
+export type ZoomAroundPointInput = {
+  scrollX: number;
+  scrollY: number;
+  zoom: number;
+  targetZoom: number;
+  anchorX: number;
+  anchorY: number;
+};
+
+export type DragCameraInput = {
+  startX: number;
+  startY: number;
+  currentX: number;
+  currentY: number;
+  startScrollX: number;
+  startScrollY: number;
+  zoom: number;
+  xBounds: CameraScrollBounds;
+  yBounds: CameraScrollBounds;
+};
+
+export function getCameraScrollBounds(worldSize: number, viewportSize: number, zoom: number): CameraScrollBounds {
+  if (viewportSize <= 0) {
+    return { min: 0, max: worldSize };
+  }
+
+  const visibleWorldSize = viewportSize / zoom;
+  const edgeAlignedScroll = worldSize - visibleWorldSize;
+  return {
+    min: Math.min(0, edgeAlignedScroll),
+    max: Math.max(0, edgeAlignedScroll),
+  };
+}
+
+export function clampCameraScrollValue(value: number, bounds: CameraScrollBounds): number {
+  return Math.min(bounds.max, Math.max(bounds.min, value));
+}
+
+export function getWorldOriginScreenPosition(scrollX: number, scrollY: number, zoom: number): { x: number; y: number } {
+  return {
+    x: -scrollX * zoom,
+    y: -scrollY * zoom,
+  };
+}
+
+export function snapCameraScrollToPixel(scroll: number, zoom: number): number {
+  if (!Number.isFinite(scroll) || !Number.isFinite(zoom) || zoom <= 0) {
+    return scroll;
+  }
+
+  return Math.round(scroll * zoom) / zoom;
+}
+
+export function zoomAroundPoint(input: ZoomAroundPointInput): { zoom: number; scrollX: number; scrollY: number } {
+  const anchorWorldX = input.scrollX + input.anchorX / input.zoom;
+  const anchorWorldY = input.scrollY + input.anchorY / input.zoom;
+
+  return {
+    zoom: input.targetZoom,
+    scrollX: anchorWorldX - input.anchorX / input.targetZoom,
+    scrollY: anchorWorldY - input.anchorY / input.targetZoom,
+  };
+}
+
+export function dragCamera(input: DragCameraInput): { scrollX: number; scrollY: number } {
+  return {
+    scrollX: clampCameraScrollValue(
+      input.startScrollX + (input.startX - input.currentX) / input.zoom,
+      input.xBounds,
+    ),
+    scrollY: clampCameraScrollValue(
+      input.startScrollY + (input.startY - input.currentY) / input.zoom,
+      input.yBounds,
+    ),
+  };
+}