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

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

@@ -0,0 +1,242 @@
+import {
+  AgentGameError,
+  createAgentGameStore,
+  validateAgentGameAssetManifest,
+  validateAgentGameScene,
+  validateOfficeBuildingLayout,
+  validateOfficeLayoutDefinition,
+} from "../core/index.js";
+import { createAgentGamePhaserSceneConfig } from "./agent-game-scene.js";
+import {
+  createSceneReconciler,
+  type AgentDomOverlayRoot,
+  type AgentGameSceneReconciler,
+} from "./scene-reconciler.js";
+import type { AgentGameCameraControlsController } from "./camera-controls.js";
+import type { AgentGameRendererConfig } from "./scene-renderer.js";
+import type { TownOfficeDomOverlayRoot } from "./town-office-renderer.js";
+import type { AgentGameController, AgentGamePhaserOptions, PhaserGameLike } from "./types.js";
+import { resolveAgentGameViewportSize } from "./viewport.js";
+
+type RuntimeDomOverlayRoot = HTMLElement & AgentDomOverlayRoot & TownOfficeDomOverlayRoot;
+
+export async function createAgentGame(
+  container: HTMLElement,
+  options: AgentGamePhaserOptions,
+): Promise<AgentGameController> {
+  const scene = validateAgentGameScene(options.scene);
+  const assets = validateAgentGameAssetManifest(options.assets);
+  if (options.officeLayout) {
+    validateOfficeLayoutDefinition(options.officeLayout.definition, options.officeLayout.atlas);
+  }
+  if (options.officeBuilding) {
+    validateOfficeBuildingLayout(options.officeBuilding.layout, options.officeBuilding.atlas);
+  }
+  const avatarIds = new Set(assets.avatars.map((avatar) => avatar.id));
+
+  const store = options.store ?? createAgentGameStore(scene);
+  let destroyed = false;
+  let reconciler: AgentGameSceneReconciler | null = null;
+  let cameraControls: AgentGameCameraControlsController | null = null;
+  let unsubscribeStore: (() => void) | null = null;
+  const domOverlayRoot = createDomOverlayRoot(container, options);
+  const phaserGame = await createPhaserGame(
+    container,
+    options,
+    domOverlayRoot,
+    (controls) => {
+      cameraControls = controls;
+    },
+    (createdReconciler) => {
+      reconciler = createdReconciler;
+      unsubscribeStore = store.subscribe((snapshot) => {
+        reconciler?.reconcile(snapshot);
+      });
+      reconciler.reconcile(store.getSnapshot());
+    },
+  );
+
+  return {
+    dispatch(command) {
+      if (destroyed) {
+        throw new AgentGameError("runtime_destroyed", "Agent game runtime has been destroyed");
+      }
+      if (command.type === "agent.spawn" && !avatarIds.has(command.avatarId)) {
+        throw new AgentGameError("missing_avatar", `Agent game command references missing avatar: ${command.avatarId}`);
+      }
+      return store.dispatch(command);
+    },
+    getSnapshot() {
+      return store.getSnapshot();
+    },
+    getCameraControls() {
+      return cameraControls;
+    },
+    destroy() {
+      if (!destroyed) {
+        destroyed = true;
+        cameraControls = null;
+        unsubscribeStore?.();
+        unsubscribeStore = null;
+        domOverlayRoot?.remove();
+        phaserGame.destroy(true);
+      }
+    },
+  };
+}
+
+async function createPhaserGame(
+  container: HTMLElement,
+  options: AgentGamePhaserOptions,
+  domOverlayRoot: RuntimeDomOverlayRoot | undefined,
+  onCameraControlsReady: (controls: AgentGameCameraControlsController | null) => void,
+  onReconcilerReady: (reconciler: AgentGameSceneReconciler) => void,
+): Promise<PhaserGameLike> {
+  if (options.createPhaserGame) {
+    return options.createPhaserGame(createPhaserConfig(
+      container,
+      options,
+      domOverlayRoot,
+      onCameraControlsReady,
+      onReconcilerReady,
+    ));
+  }
+
+  const Phaser = await import("phaser");
+  return new Phaser.Game({
+    ...createPhaserConfig(container, options, domOverlayRoot, onCameraControlsReady, onReconcilerReady),
+    type: Phaser.AUTO,
+  });
+}
+
+function createPhaserConfig(
+  container: HTMLElement,
+  options: AgentGamePhaserOptions,
+  domOverlayRoot: RuntimeDomOverlayRoot | undefined,
+  onCameraControlsReady: (controls: AgentGameCameraControlsController | null) => void,
+  onReconcilerReady: (reconciler: AgentGameSceneReconciler) => void,
+) {
+  const { width, height } = resolveAgentGameViewportSize({
+    width: options.width,
+    height: options.height,
+    viewport: options.viewport,
+  });
+  const resolution = options.resolution ?? getRuntimeResolution();
+
+  return {
+    parent: container,
+    width,
+    height,
+    resolution,
+    pixelArt: true,
+    roundPixels: true,
+    render: {
+      pixelArt: true,
+      antialias: false,
+      antialiasGL: false,
+      roundPixels: true,
+    },
+    backgroundColor: options.backgroundColor ?? "#111827",
+    scene: createAgentGamePhaserSceneConfig({
+      definition: options.scene,
+      avatars: options.assets.avatars,
+      width,
+      height,
+      backgroundImage: options.backgroundImage,
+      officeLayout: options.officeLayout,
+      officeBuilding: options.officeBuilding,
+      townOfficeBuilding: options.townOfficeBuilding,
+      renderer: options.renderer ?? createLegacyRendererConfig(validateAgentGameScene(options.scene), width, height, options),
+      rendererRegistry: options.rendererRegistry,
+      domOverlayRoot,
+      debugOverlays: options.debugOverlays,
+      showAnchorDebug: options.showAnchorDebug,
+      cameraControls: options.cameraControls,
+      movementDurationMs: options.movementDurationMs,
+      onCameraControlsReady,
+      onCreate(scene) {
+        const createdReconciler = createSceneReconciler(scene, {
+          avatars: options.assets.avatars,
+          domOverlay: domOverlayRoot ? { root: domOverlayRoot } : undefined,
+          movementDurationMs: options.movementDurationMs ?? 220,
+          movementSpeedPxPerSecond: options.movementSpeedPxPerSecond,
+          movementMinDurationMs: options.movementMinDurationMs,
+          movementMaxDurationMs: options.movementMaxDurationMs,
+        });
+        onReconcilerReady(createdReconciler);
+        return createdReconciler;
+      },
+    }),
+  };
+}
+
+function createDomOverlayRoot(container: HTMLElement, options: AgentGamePhaserOptions): RuntimeDomOverlayRoot | undefined {
+  if (options.domOverlay === false || typeof document === "undefined" || !container.appendChild) {
+    return undefined;
+  }
+
+  const root = document.createElement("div");
+  root.className = "agent-dom-overlay";
+  container.appendChild(root);
+  return root as unknown as RuntimeDomOverlayRoot;
+}
+
+function createLegacyRendererConfig(
+  scene: ReturnType<typeof validateAgentGameScene>,
+  width: number,
+  height: number,
+  options: AgentGamePhaserOptions,
+): AgentGameRendererConfig {
+  if (options.officeBuilding) {
+    return {
+      kind: "office-building-atlas",
+      options: {
+        atlasKey: options.officeBuilding.atlasKey,
+        imageUrl: options.officeBuilding.imageUrl,
+        atlasUrl: options.officeBuilding.atlasUrl,
+        layout: options.officeBuilding.layout,
+      },
+    };
+  }
+
+  if (options.townOfficeBuilding) {
+    return {
+      kind: "town-office-building",
+      options: {
+        layout: options.townOfficeBuilding.layout,
+        debugOverlays: options.debugOverlays,
+      },
+    };
+  }
+
+  if (options.officeLayout) {
+    return {
+      kind: "office-layout",
+      options: {
+        atlasKey: options.officeLayout.atlasKey,
+        imageUrl: options.officeLayout.imageUrl,
+        atlasUrl: options.officeLayout.atlasUrl,
+        definition: options.officeLayout.definition,
+      },
+    };
+  }
+
+  return {
+    kind: "background",
+    options: {
+      definition: scene,
+      width,
+      height,
+      backgroundImage: options.backgroundImage,
+    },
+  };
+}
+
+function getRuntimeResolution(): number {
+  const ratio = globalThis.devicePixelRatio;
+  if (!Number.isFinite(ratio) || ratio < 1) {
+    return 1;
+  }
+
+  return ratio;
+}

package/src/phaser/debug-overlay.ts

@@ -0,0 +1,21 @@
+import { parseHexColor } from "../core/index.js";
+import type { TownOfficeSceneLike } from "./town-office-primitives.js";
+import { debugDepth } from "./render-layers.js";
+
+export type AgentGameDebugOverlays = {
+  worldBounds?: boolean;
+  anchors?: boolean;
+  camera?: boolean;
+};
+
+export function drawWorldBoundsDebugOverlay(
+  scene: TownOfficeSceneLike,
+  width: number,
+  height: number,
+): void {
+  scene.add
+    .rectangle(width / 2, height / 2, width, height, parseHexColor("#ff2d2d"))
+    .setDepth?.(debugDepth())
+    .setFillStyle?.(0xffffff, 0)
+    .setStrokeStyle?.(3, 0xff2d2d);
+}

package/src/phaser/index.ts

@@ -0,0 +1,13 @@
+export * from "./agent-game-scene.js";
+export * from "./avatar-registry.js";
+export * from "./camera-model.js";
+export * from "./camera-controls.js";
+export * from "./create-agent-game.js";
+export * from "./debug-overlay.js";
+export * from "./office-building-renderer.js";
+export * from "./office-layout-renderer.js";
+export * from "./scene-renderer.js";
+export * from "./scene-reconciler.js";
+export * from "./town-office-renderer.js";
+export * from "./types.js";
+export * from "./viewport.js";

package/src/phaser/movement-tween.ts

@@ -0,0 +1,59 @@
+export type MovementPoint = {
+  x: number;
+  y: number;
+};
+
+export type MovementTweenConfig = {
+  x: number;
+  y: number;
+  duration: number;
+  ease: "Linear";
+};
+
+export type MovementTimingOptions = {
+  durationMs?: number;
+  speedPxPerSecond?: number;
+  minDurationMs?: number;
+  maxDurationMs?: number;
+};
+
+export function createMovementTweenConfig(
+  current: MovementPoint,
+  target: MovementPoint,
+  timing: number | MovementTimingOptions,
+): MovementTweenConfig | null {
+  if (current.x === target.x && current.y === target.y) {
+    return null;
+  }
+
+  const duration = resolveMovementDuration(current, target, timing);
+
+  return {
+    x: target.x,
+    y: target.y,
+    duration,
+    ease: "Linear",
+  };
+}
+
+export function resolveMovementDuration(
+  current: MovementPoint,
+  target: MovementPoint,
+  timing: number | MovementTimingOptions,
+): number {
+  if (typeof timing === "number") {
+    return timing;
+  }
+
+  if (!timing.speedPxPerSecond || timing.speedPxPerSecond <= 0) {
+    return timing.durationMs ?? 0;
+  }
+
+  const dx = target.x - current.x;
+  const dy = target.y - current.y;
+  const distance = Math.sqrt(dx * dx + dy * dy);
+  const rawDuration = Math.round((distance / timing.speedPxPerSecond) * 1000);
+  const minDuration = timing.minDurationMs ?? 0;
+  const maxDuration = timing.maxDurationMs ?? Number.POSITIVE_INFINITY;
+  return Math.min(maxDuration, Math.max(minDuration, rawDuration));
+}

package/src/phaser/office-background.ts

@@ -0,0 +1,48 @@
+import type { AgentGameSceneDefinition } from "../core/index.js";
+import { officeDepth } from "./render-layers.js";
+import type { PhaserDisplayObjectLike } from "./scene-reconciler.js";
+
+export type OfficeBackgroundSceneLike = {
+  add: {
+    rectangle: (x: number, y: number, width: number, height: number, fillColor: number) => PhaserDisplayObjectLike;
+    image?: (x: number, y: number, textureKey: string) => PhaserDisplayObjectLike;
+  };
+};
+
+export type OfficeBackgroundOptions = {
+  width: number;
+  height: number;
+  sceneImage?: {
+    key: string;
+    width: number;
+    height: number;
+  };
+};
+
+export function drawOfficeBackground(
+  scene: OfficeBackgroundSceneLike,
+  definition: AgentGameSceneDefinition,
+  options: OfficeBackgroundOptions,
+): void {
+  scene.add.rectangle(options.width / 2, options.height / 2, options.width, options.height, 0x111827).setDepth?.(officeDepth(0));
+
+  if (options.sceneImage && scene.add.image) {
+    const scale = Math.min(options.width / options.sceneImage.width, options.height / options.sceneImage.height);
+    scene.add.image(options.width / 2, options.height / 2, options.sceneImage.key).setScale?.(scale).setDepth?.(officeDepth(1));
+    return;
+  }
+
+  scene.add.rectangle(options.width / 2, 44, options.width - 64, 64, 0x1f2933).setDepth?.(officeDepth(1));
+
+  for (const anchor of definition.anchors) {
+    if (anchor.kind === "desk") {
+      scene.add.rectangle(anchor.x, anchor.y + 18, 72, 28, 0x26313a).setDepth?.(officeDepth(2));
+    }
+    if (anchor.kind === "meeting") {
+      scene.add.rectangle(anchor.x, anchor.y + 8, 104, 42, 0x3a4a52).setDepth?.(officeDepth(2));
+    }
+    if (anchor.kind === "break") {
+      scene.add.rectangle(anchor.x, anchor.y + 10, 86, 34, 0x40513f).setDepth?.(officeDepth(2));
+    }
+  }
+}

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

@@ -0,0 +1,87 @@
+import {
+  getOfficeRoomBounds,
+  parseHexColor,
+  type OfficeBuildingLayout,
+} 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 OfficeBuildingSceneLike = {
+  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;
+    image?: (x: number, y: number, textureKey: string, frame?: string) => PhaserDisplayObjectLike;
+  };
+};
+
+export type OfficeBuildingRenderOptions = {
+  atlasKey: string;
+};
+
+const TITLE_BAR_HEIGHT = 34;
+
+export function drawOfficeBuildingLayout(
+  scene: OfficeBuildingSceneLike,
+  layout: OfficeBuildingLayout,
+  options: OfficeBuildingRenderOptions,
+): void {
+  if (!scene.add.image) {
+    throw new Error("Office building rendering requires Phaser image support");
+  }
+
+  const size = getBuildingCanvasSize(layout);
+  scene.add
+    .rectangle(size.width / 2, size.height / 2, size.width, size.height, parseHexColor(layout.backgroundColor))
+    .setDepth?.(officeDepth(0));
+
+  for (const room of layout.rooms) {
+    const bounds = getOfficeRoomBounds(layout, room);
+    const floorColor = parseHexColor(room.theme.floorColor);
+    const titleColor = parseHexColor(room.theme.titleColor);
+    const borderColor = parseHexColor(room.theme.borderColor);
+    const titleTextColor = room.theme.titleTextColor ?? "#ffffff";
+
+    scene.add
+      .rectangle(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2, bounds.width, bounds.height, floorColor)
+      .setDepth?.(officeDepth(1))
+      .setStrokeStyle?.(2, borderColor);
+
+    scene.add
+      .rectangle(bounds.x + bounds.width / 2, bounds.y + TITLE_BAR_HEIGHT / 2, bounds.width, TITLE_BAR_HEIGHT, titleColor)
+      .setDepth?.(officeDepth(2));
+
+    scene.add
+      .text(bounds.x + bounds.width / 2, bounds.y + TITLE_BAR_HEIGHT / 2, room.name, crispTextStyle({
+        color: titleTextColor,
+        fontSize: "16px",
+        fontFamily: "sans-serif",
+        fontStyle: "700",
+      }))
+      .setOrigin?.(0.5, 0.5)
+      .setDepth?.(officeDepth(3));
+
+    for (const object of room.objects) {
+      const x = bounds.x + object.x;
+      const y = bounds.y + object.y;
+      const image = scene.add.image(x, y, options.atlasKey, object.frame);
+      image.setDepth?.(officeDepth(object.depth ?? y));
+      if (object.scale) {
+        image.setScale?.(object.scale);
+      }
+    }
+  }
+}
+
+function getBuildingCanvasSize(layout: OfficeBuildingLayout): { width: number; height: number } {
+  let width = layout.padding * 2;
+  let height = layout.padding * 2;
+
+  for (const room of layout.rooms) {
+    const bounds = getOfficeRoomBounds(layout, room);
+    width = Math.max(width, bounds.x + bounds.width + layout.padding);
+    height = Math.max(height, bounds.y + bounds.height + layout.padding);
+  }
+
+  return { width, height };
+}

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

@@ -0,0 +1,58 @@
+import type { OfficeLayoutDefinition } from "../core/index.js";
+import { officeDepth } from "./render-layers.js";
+import type { PhaserDisplayObjectLike } from "./scene-reconciler.js";
+
+export type OfficeLayoutSceneLike = {
+  add: {
+    rectangle?: (x: number, y: number, width: number, height: number, fillColor: number) => PhaserDisplayObjectLike;
+    image?: (x: number, y: number, textureKey: string, frame?: string) => PhaserDisplayObjectLike;
+  };
+};
+
+export type OfficeLayoutRenderOptions = {
+  atlasKey: string;
+};
+
+export function drawOfficeLayout(
+  scene: OfficeLayoutSceneLike,
+  layout: OfficeLayoutDefinition,
+  options: OfficeLayoutRenderOptions,
+): void {
+  if (!scene.add.image) {
+    throw new Error("Office layout rendering requires Phaser image support");
+  }
+
+  for (const wall of layout.walls ?? []) {
+    scene.add.rectangle?.(wall.x, wall.y, wall.width, wall.height, wall.fillColor).setDepth?.(officeDepth(wall.depth ?? 0));
+  }
+
+  const floorX = layout.floor.x ?? 0;
+  const floorY = layout.floor.y ?? 0;
+  const floorWidth = layout.floor.width ?? layout.width;
+  const floorHeight = layout.floor.height ?? layout.height;
+
+  if (layout.floorFill) {
+    scene.add.rectangle
+      ?.(floorX + floorWidth / 2, floorY + floorHeight / 2, floorWidth, floorHeight, layout.floorFill.fillColor)
+      .setDepth?.(officeDepth(layout.floorFill.depth ?? 1));
+  }
+
+  if (layout.floor.visible !== false) {
+    for (let y = floorY + layout.tileSize / 2; y < floorY + floorHeight; y += layout.tileSize) {
+      for (let x = floorX + layout.tileSize / 2; x < floorX + floorWidth; x += layout.tileSize) {
+        scene.add
+          .image(x, y, options.atlasKey, layout.floor.frame)
+          .setDisplaySize?.(layout.tileSize, layout.tileSize)
+          .setDepth?.(officeDepth(1));
+      }
+    }
+  }
+
+  for (const object of layout.objects) {
+    const image = scene.add.image(object.x, object.y, options.atlasKey, object.frame);
+    image.setDepth?.(officeDepth(object.depth ?? object.y));
+    if (object.scale) {
+      image.setScale?.(object.scale);
+    }
+  }
+}

package/src/phaser/render-layers.ts

@@ -0,0 +1,30 @@
+export const RENDER_LAYERS = {
+  officeMin: 0,
+  officeMax: 9999,
+  agentBase: 20000,
+  agentUiBase: 40000,
+  debugBase: 90000,
+} as const;
+
+export function officeDepth(depth: number): number {
+  return clampDepth(depth, RENDER_LAYERS.officeMin, RENDER_LAYERS.officeMax);
+}
+
+export function agentDepth(worldY: number): number {
+  return RENDER_LAYERS.agentBase + Math.round(worldY);
+}
+
+export function agentUiDepth(offset = 0): number {
+  return RENDER_LAYERS.agentUiBase + offset;
+}
+
+export function debugDepth(offset = 0): number {
+  return RENDER_LAYERS.debugBase + offset;
+}
+
+function clampDepth(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) {
+    return min;
+  }
+  return Math.min(max, Math.max(min, Math.round(value)));
+}