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

package/src/phaser/town-office-primitives.ts

@@ -0,0 +1,53 @@
+import { parseHexColor } from "../core/index.js";
+import { officeDepth } from "./render-layers.js";
+import type { PhaserDisplayObjectLike, PhaserTextLike } from "./scene-reconciler.js";
+import { crispTextStyle } from "./text-style.js";
+
+export type TownOfficeSceneLike = {
+  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;
+  };
+  cameras?: {
+    main?: {
+      zoom: number;
+      scrollX: number;
+      scrollY: number;
+      width?: number;
+      height?: number;
+    };
+  };
+  events?: {
+    on: (eventName: string, handler: (...args: any[]) => void) => unknown;
+  };
+};
+
+export function rect(
+  scene: TownOfficeSceneLike,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  color: string,
+  depth: number,
+): PhaserDisplayObjectLike {
+  return scene.add.rectangle(x, y, width, height, parseHexColor(color)).setDepth?.(officeDepth(depth))
+    ?? scene.add.rectangle(x, y, width, height, parseHexColor(color));
+}
+
+export function text(
+  scene: TownOfficeSceneLike,
+  x: number,
+  y: number,
+  value: string,
+  fontSize: number,
+  color: string,
+  depth: number,
+): void {
+  scene.add.text(x, y, value, crispTextStyle({
+    color,
+    fontSize: `${Math.max(1, fontSize)}px`,
+    fontFamily: "sans-serif",
+    fontStyle: "700",
+  })).setOrigin?.(0.5, 0.5).setDepth?.(officeDepth(depth));
+}

package/src/phaser/town-office-renderer.ts

@@ -0,0 +1,429 @@
+import {
+  createTownOfficeRoomObjects,
+  getOfficeRoomBounds,
+  measureOfficeBuildingLayoutSize,
+  normalizeOfficeBuildingLayoutForRatio,
+  type OfficeBuildingLayout,
+  type OfficeBuildingObjectDefinition,
+  type OfficeRoomBounds,
+} from "../core/index.js";
+import {
+  drawBattery,
+  drawBeaker,
+  drawBicycleRack,
+  drawBigScreen,
+  drawCertBadge,
+  drawChartBoard,
+  drawEVCharger,
+  drawGazebo,
+  drawHenanMap,
+  drawKpiCard,
+  drawMegaphone,
+  drawMonitorWall,
+  drawPartyFlag,
+  drawPingPongTable,
+  drawPodium,
+  drawRedBanner,
+  drawSeal,
+  drawServerRack,
+  drawSolarPanel,
+  drawTestRack,
+  drawTickerBoard,
+  drawTransmissionTower,
+  drawTree,
+  drawTV,
+  drawWindTurbine,
+} from "./town-office-business-props.js";
+import { drawWorldBoundsDebugOverlay, type AgentGameDebugOverlays } from "./debug-overlay.js";
+import {
+  drawAirConditioner,
+  drawDoor,
+  drawExitSign,
+  drawLightSwitch,
+  drawPicture,
+  drawPrinter,
+  drawRoomEnvironment,
+  drawSocket,
+  drawWindow,
+  type TownOfficeRoomStyle,
+} from "./town-office-environment.js";
+import {
+  drawBench,
+  drawBookshelf,
+  drawBulletinBoard,
+  drawCabinet,
+  drawChair,
+  drawClock,
+  drawCoffeeMachine,
+  drawDesk,
+  drawFireExtinguisher,
+  drawFlowerPot,
+  drawLaptop,
+  drawMachine,
+  drawMonitor,
+  drawPhone,
+  drawPlant,
+  drawRugMat,
+  drawScheduleBoard,
+  drawSofa,
+  drawTable,
+  drawTrashCan,
+  drawVendingMachine,
+  drawWhiteboard,
+} from "./town-office-furniture.js";
+import { rect, type TownOfficeSceneLike } from "./town-office-primitives.js";
+import { crispTextStyle } from "./text-style.js";
+import { officeDepth } from "./render-layers.js";
+
+export type { TownOfficeSceneLike } from "./town-office-primitives.js";
+
+const HEADER_HEIGHT = 34;
+const HEADER_TITLE_PADDING_X = 12;
+const HEADER_TITLE_OFFSET_Y = 2;
+const FLOOR_GRID_LINE_WIDTH = 2;
+
+const ROOM_STYLES: Record<string, TownOfficeRoomStyle> = {
+  dispatch: { floor: "#e8edf4", wallTop: "#1a365d", accent: "#0d2340" },
+  trading: { floor: "#e8edf4", wallTop: "#1a365d", accent: "#0d2340" },
+  testing: { floor: "#e4ebf0", wallTop: "#1e3a5f", accent: "#0f2847" },
+  lab: { floor: "#e4ebf0", wallTop: "#1e3a5f", accent: "#0f2847" },
+  resource: { floor: "#e4f0ea", wallTop: "#1a6b4a", accent: "#0e5538" },
+  archive: { floor: "#eae6de", wallTop: "#3a3028", accent: "#2a2018" },
+  library: { floor: "#eae6de", wallTop: "#3a3028", accent: "#2a2018" },
+  cafeteria: { floor: "#f0ece4", wallTop: "#8b4513", accent: "#6b3008" },
+  lounge: { floor: "#eeebe4", wallTop: "#4a3828", accent: "#3a2818" },
+  fitness: { floor: "#e4ede8", wallTop: "#1a5a3a", accent: "#0e4a2a" },
+  meeting: { floor: "#ebe8f0", wallTop: "#2d3a5c", accent: "#1a2845" },
+};
+
+export type TownOfficeBuildingRenderOptions = {
+  debugOverlays?: AgentGameDebugOverlays;
+  domOverlayRoot?: TownOfficeDomOverlayRoot;
+};
+
+export type TownOfficeDomOverlayElement = {
+  className: string;
+  textContent: string | null;
+  clientWidth?: number;
+  clientHeight?: number;
+  style: Record<string, string>;
+  appendChild?: (child: TownOfficeDomOverlayElement) => unknown;
+};
+
+export type TownOfficeDomOverlayRoot = TownOfficeDomOverlayElement & {
+  ownerDocument?: {
+    createElement: (tagName: string) => TownOfficeDomOverlayElement;
+  };
+};
+
+export function drawTownOfficeBuildingLayout(
+  scene: TownOfficeSceneLike,
+  layout: OfficeBuildingLayout,
+  options: TownOfficeBuildingRenderOptions = {},
+): void {
+  const normalizedLayout = normalizeOfficeBuildingLayoutForRatio(layout);
+  const size = getBuildingCanvasSize(normalizedLayout);
+  rect(scene, size.width / 2, size.height / 2, size.width, size.height, "#e8ecf0", 0);
+  if (options.debugOverlays?.worldBounds) {
+    drawWorldBoundsDebugOverlay(scene, size.width, size.height);
+  }
+  drawBackgroundPattern(scene, size.width, size.height);
+
+  for (const room of normalizedLayout.rooms) {
+    const bounds = getOfficeRoomBounds(normalizedLayout, room);
+    const roomStyleKey = room.type ?? room.id;
+    const style = ROOM_STYLES[roomStyleKey] ?? ROOM_STYLES[room.id] ?? {
+      floor: room.theme.floorColor,
+      wallTop: room.theme.titleColor,
+      accent: room.theme.borderColor,
+    };
+
+    rect(scene, bounds.x + bounds.width / 2, bounds.y + bounds.height / 2, bounds.width, bounds.height, style.floor, 1)
+      .setStrokeStyle?.(1, 0x000000);
+    drawFloorPattern(scene, bounds, roomStyleKey);
+    rect(scene, bounds.x + bounds.width / 2, bounds.y + HEADER_HEIGHT / 2, bounds.width, HEADER_HEIGHT, style.wallTop, 2);
+    rect(scene, bounds.x + bounds.width / 2, bounds.y + HEADER_HEIGHT + 1, bounds.width, 2, style.accent, 2);
+    const titleX = bounds.x + HEADER_TITLE_PADDING_X;
+    const titleY = bounds.y + HEADER_HEIGHT / 2 + HEADER_TITLE_OFFSET_Y;
+    if (options.domOverlayRoot) {
+      createRoomTitleOverlay(scene, options.domOverlayRoot, titleX, titleY, room.name);
+    } else {
+      scene.add
+        .text(titleX, titleY, room.name, crispTextStyle({
+          color: room.theme.titleTextColor ?? "#ffffff",
+          fontSize: "14px",
+          fontFamily: "sans-serif",
+          fontStyle: "700",
+        }))
+        .setOrigin?.(0, 0.5)
+        .setDepth?.(officeDepth(3));
+    }
+
+    drawRoomEnvironment(scene, bounds, roomStyleKey, style);
+    const objects = room.objects.length > 0 || !room.type
+      ? room.objects
+      : createTownOfficeRoomObjects({
+        roomId: room.id,
+        roomType: room.type,
+        width: bounds.width,
+        height: bounds.height,
+      });
+    for (const object of objects) {
+      drawTownOfficeObject(scene, bounds, object);
+    }
+  }
+}
+
+function createRoomTitleOverlay(
+  scene: TownOfficeSceneLike,
+  root: TownOfficeDomOverlayRoot,
+  worldX: number,
+  worldY: number,
+  title: string,
+): void {
+  const element = root.ownerDocument?.createElement("div") ?? globalThis.document?.createElement?.("div");
+  if (!element) {
+    throw new Error("Town office DOM overlay requires document.createElement");
+  }
+
+  element.className = "room-dom-title";
+  element.textContent = title;
+  element.style.position = "absolute";
+  element.style.left = "0";
+  element.style.top = "0";
+  element.style.pointerEvents = "none";
+  element.style.transformOrigin = "left center";
+  root.appendChild?.(element as TownOfficeDomOverlayElement);
+
+  const update = () => {
+    positionDomElement(scene, root, element as TownOfficeDomOverlayElement, worldX, worldY);
+  };
+  scene.events?.on?.("postupdate", update);
+  update();
+}
+
+function positionDomElement(
+  scene: TownOfficeSceneLike,
+  root: TownOfficeDomOverlayRoot,
+  element: TownOfficeDomOverlayElement,
+  worldX: number,
+  worldY: number,
+): void {
+  const camera = scene.cameras?.main;
+  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((worldX - camera.scrollX) * camera.zoom * scaleX);
+  const y = Math.round((worldY - camera.scrollY) * camera.zoom * scaleY);
+  const scale = camera.zoom * Math.min(scaleX, scaleY);
+  element.style.transform = `translate3d(${x}px, ${y}px, 0) translateY(-50%) scale(${formatDomScale(scale)})`;
+}
+
+function formatDomScale(scale: number): string {
+  return Number.isInteger(scale) ? String(scale) : scale.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function drawBackgroundPattern(scene: TownOfficeSceneLike, width: number, height: number): void {
+  for (let y = 0; y < height; y += 40) {
+    for (let x = 0; x < width; x += 40) {
+      const color = (x / 40 + y / 40) % 2 === 0 ? "#e4e8ec" : "#e8ecf0";
+      rect(scene, x + 20, y + 20, 40, 40, color, 0);
+    }
+  }
+}
+
+function drawFloorPattern(scene: TownOfficeSceneLike, bounds: OfficeRoomBounds, roomType: string): void {
+  const step = roomType === "cafeteria" || roomType === "fitness" ? 16 : 24;
+  const lineColor = roomType === "cafeteria" || roomType === "fitness" ? "#d0ccc4" : "#c8c0b4";
+  for (let x = bounds.x + step; x < bounds.x + bounds.width; x += step) {
+    rect(scene, x, bounds.y + bounds.height / 2, FLOOR_GRID_LINE_WIDTH, bounds.height - HEADER_HEIGHT, lineColor, 1);
+  }
+  for (let y = bounds.y + HEADER_HEIGHT + step; y < bounds.y + bounds.height; y += step) {
+    rect(scene, bounds.x + bounds.width / 2, y, bounds.width, FLOOR_GRID_LINE_WIDTH, lineColor, 1);
+  }
+}
+
+function drawTownOfficeObject(scene: TownOfficeSceneLike, bounds: OfficeRoomBounds, object: OfficeBuildingObjectDefinition): void {
+  const x = bounds.x + object.x;
+  const y = bounds.y + object.y;
+  const scale = object.scale ?? 1;
+
+  switch (object.frame) {
+    case "desk-single":
+    case "desk-long":
+      drawDesk(scene, x, y, scale, !object.id.includes("training-desk-single"));
+      break;
+    case "chair-office":
+      drawChair(scene, x, y, scale);
+      break;
+    case "whiteboard":
+    case "wall-art":
+      drawWhiteboard(scene, x - 42 * scale, y - 14 * scale, 84 * scale, 28 * scale);
+      break;
+    case "plant-small":
+    case "plant-large":
+      drawPlant(scene, x, y, scale * (object.frame === "plant-large" ? 1.4 : 1));
+      break;
+    case "monitor":
+      drawMonitor(scene, x, y, scale);
+      break;
+    case "sofa-long":
+      drawSofa(scene, x, y, scale);
+      break;
+    case "laptop":
+      drawLaptop(scene, x, y, scale);
+      break;
+    case "bookshelf":
+      drawBookshelf(scene, x, y, scale);
+      break;
+    case "filing-cabinet":
+      drawCabinet(scene, x, y, scale);
+      break;
+    case "meeting-table":
+      drawTable(scene, x, y, 72 * scale, 34 * scale);
+      break;
+    case "coffee-machine":
+      drawCoffeeMachine(scene, x, y, scale);
+      break;
+    case "water-dispenser":
+    case "locker":
+      drawMachine(scene, x, y, scale);
+      break;
+    case "vending-machine":
+      drawVendingMachine(scene, x, y, scale);
+      break;
+    case "phone":
+      drawPhone(scene, x, y, scale);
+      break;
+    case "schedule-board":
+      drawScheduleBoard(scene, x, y, scale);
+      break;
+    case "trash-can":
+      drawTrashCan(scene, x, y, scale);
+      break;
+    case "bench":
+      drawBench(scene, x, y, scale);
+      break;
+    case "flower-pot":
+      drawFlowerPot(scene, x, y, scale, "#e85080");
+      break;
+    case "clock":
+      drawClock(scene, x, y, scale);
+      break;
+    case "bulletin-board":
+      drawBulletinBoard(scene, x, y, scale);
+      break;
+    case "fire-extinguisher":
+      drawFireExtinguisher(scene, x, y, scale);
+      break;
+    case "rug-mat":
+      drawRugMat(scene, x, y, scale);
+      break;
+    case "window":
+      drawWindow(scene, x, y, scale);
+      break;
+    case "air-conditioner":
+      drawAirConditioner(scene, x, y, scale);
+      break;
+    case "exit-sign":
+      drawExitSign(scene, x, y, scale);
+      break;
+    case "picture":
+      drawPicture(scene, x, y, scale, "#5588bb");
+      break;
+    case "printer":
+      drawPrinter(scene, x, y, scale);
+      break;
+    case "door":
+      drawDoor(scene, x, y, scale);
+      break;
+    case "light-switch":
+      drawLightSwitch(scene, x, y, scale);
+      break;
+    case "socket":
+      drawSocket(scene, x, y, scale);
+      break;
+    case "server-rack":
+      drawServerRack(scene, x, y, scale);
+      break;
+    case "tv":
+      drawTV(scene, x, y, scale);
+      break;
+    case "monitor-wall":
+      drawMonitorWall(scene, x, y, scale);
+      break;
+    case "ticker-board":
+      drawTickerBoard(scene, x, y, scale);
+      break;
+    case "test-rack":
+      drawTestRack(scene, x, y, scale);
+      break;
+    case "cert-badge":
+      drawCertBadge(scene, x, y, scale);
+      break;
+    case "henan-map":
+      drawHenanMap(scene, x, y, scale);
+      break;
+    case "battery":
+      drawBattery(scene, x, y, scale);
+      break;
+    case "solar-panel":
+      drawSolarPanel(scene, x, y, scale);
+      break;
+    case "ev-charger":
+      drawEVCharger(scene, x, y, scale);
+      break;
+    case "megaphone":
+      drawMegaphone(scene, x, y, scale);
+      break;
+    case "chart-board":
+      drawChartBoard(scene, x, y, scale);
+      break;
+    case "red-banner":
+      drawRedBanner(scene, x, y, scale);
+      break;
+    case "beaker":
+      drawBeaker(scene, x, y, scale);
+      break;
+    case "ping-pong-table":
+      drawPingPongTable(scene, x, y, scale);
+      break;
+    case "podium":
+      drawPodium(scene, x, y, scale);
+      break;
+    case "party-flag":
+      drawPartyFlag(scene, x, y, scale);
+      break;
+    case "wind-turbine":
+      drawWindTurbine(scene, x, y, scale);
+      break;
+    case "transmission-tower":
+      drawTransmissionTower(scene, x, y, scale);
+      break;
+    case "tree":
+      drawTree(scene, x, y, scale);
+      break;
+    case "gazebo":
+      drawGazebo(scene, x, y, scale);
+      break;
+    case "bicycle-rack":
+      drawBicycleRack(scene, x, y, scale);
+      break;
+    case "big-screen":
+      drawBigScreen(scene, x, y, scale);
+      break;
+    case "kpi-card":
+      drawKpiCard(scene, x, y, scale);
+      break;
+    case "seal":
+      drawSeal(scene, x, y, scale);
+      break;
+  }
+}
+
+function getBuildingCanvasSize(layout: OfficeBuildingLayout): { width: number; height: number } {
+  return measureOfficeBuildingLayoutSize(layout);
+}

package/src/phaser/types.ts

@@ -0,0 +1,67 @@
+import type { AgentGameAssetManifest } from "../core/assets.js";
+import type { AgentGameCommand } from "../core/commands.js";
+import type { OfficeBuildingLayout } from "../core/office-building-layout.js";
+import type { OfficeLayoutDefinition, OfficeObjectAtlasDefinition } from "../core/office-layout.js";
+import type { AgentGameSceneDefinition } from "../core/scene.js";
+import type { AgentGameSnapshot } from "../core/state.js";
+import type { AgentGameStore } from "../core/agent-game-store.js";
+import type { AgentGameCameraControlsController, AgentGameCameraControlsOptions } from "./camera-controls.js";
+import type { AgentGameDebugOverlays } from "./debug-overlay.js";
+import type { AgentGameRendererConfig, AgentGameSceneRendererRegistry } from "./scene-renderer.js";
+import type { AgentGameViewportOptions } from "./viewport.js";
+
+export type PhaserGameLike = {
+  destroy(removeCanvas?: boolean): void;
+};
+
+export type AgentGamePhaserOptions = {
+  scene: AgentGameSceneDefinition;
+  assets: AgentGameAssetManifest;
+  width?: number;
+  height?: number;
+  viewport?: AgentGameViewportOptions;
+  resolution?: number;
+  backgroundColor?: string;
+  backgroundImage?: {
+    key: string;
+    url: string;
+    width: number;
+    height: number;
+  };
+  officeLayout?: {
+    atlasKey: string;
+    imageUrl: string;
+    atlasUrl: string;
+    definition: OfficeLayoutDefinition;
+    atlas: OfficeObjectAtlasDefinition;
+  };
+  officeBuilding?: {
+    atlasKey: string;
+    imageUrl: string;
+    atlasUrl: string;
+    layout: OfficeBuildingLayout;
+    atlas: OfficeObjectAtlasDefinition;
+  };
+  townOfficeBuilding?: {
+    layout: OfficeBuildingLayout;
+  };
+  debugOverlays?: AgentGameDebugOverlays;
+  showAnchorDebug?: boolean;
+  cameraControls?: AgentGameCameraControlsOptions;
+  domOverlay?: boolean;
+  movementDurationMs?: number;
+  movementSpeedPxPerSecond?: number;
+  movementMinDurationMs?: number;
+  movementMaxDurationMs?: number;
+  store?: AgentGameStore;
+  renderer?: AgentGameRendererConfig;
+  rendererRegistry?: AgentGameSceneRendererRegistry;
+  createPhaserGame?: (config: unknown) => PhaserGameLike;
+};
+
+export type AgentGameController = {
+  dispatch(command: AgentGameCommand): AgentGameSnapshot;
+  getSnapshot(): AgentGameSnapshot;
+  getCameraControls(): AgentGameCameraControlsController | null;
+  destroy(): void;
+};

package/src/phaser/viewport.ts

@@ -0,0 +1,88 @@
+export type AgentGameViewportRatio = {
+  width: number;
+  height: number;
+};
+
+export type AgentGameViewportOptions = {
+  ratio: AgentGameViewportRatio;
+  baseWidth?: number;
+};
+
+export type AgentGameViewportSizeInput = {
+  width?: number;
+  height?: number;
+  viewport?: AgentGameViewportOptions;
+};
+
+export type AgentGameViewportSize = {
+  width: number;
+  height: number;
+};
+
+export function resolveAgentGameViewportSize(input: AgentGameViewportSizeInput): AgentGameViewportSize {
+  if (!isPlainObject(input)) {
+    throw new Error("Agent game viewport input must be an object");
+  }
+
+  validateExplicitSize(input.width, "width");
+  validateExplicitSize(input.height, "height");
+
+  if ((input.width === undefined) !== (input.height === undefined)) {
+    throw new Error("Agent game viewport requires both width and height when using explicit sizing");
+  }
+
+  if (input.viewport !== undefined) {
+    validateViewport(input.viewport);
+  }
+
+  if (input.width !== undefined && input.height !== undefined) {
+    return { width: input.width, height: input.height };
+  }
+
+  if (input.viewport === undefined) {
+    return { width: 800, height: 480 };
+  }
+
+  const width = input.viewport.baseWidth ?? 800;
+  const height = Math.round((width * input.viewport.ratio.height) / input.viewport.ratio.width);
+  if (height <= 0) {
+    throw new Error("Agent game viewport resolved height must be a positive integer");
+  }
+
+  return { width, height };
+}
+
+function validateViewport(viewport: AgentGameViewportOptions): void {
+  if (!isPlainObject(viewport)) {
+    throw new Error("Agent game viewport must be an object");
+  }
+
+  if (!viewport.ratio) {
+    throw new Error("Agent game viewport.ratio is required");
+  }
+
+  validatePositiveInteger(viewport.ratio.width, "viewport.ratio.width");
+  validatePositiveInteger(viewport.ratio.height, "viewport.ratio.height");
+
+  if (viewport.baseWidth !== undefined) {
+    validatePositiveInteger(viewport.baseWidth, "viewport.baseWidth");
+  }
+}
+
+function validateExplicitSize(value: number | undefined, field: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  validatePositiveInteger(value, field);
+}
+
+function validatePositiveInteger(value: number, field: string): void {
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+    throw new Error(`Agent game ${field} must be a positive integer`);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}