@agent-os-lab/agent-game-sdk 0.1.9 → 0.1.11

package/src/office/mount.ts

@@ -62,6 +62,9 @@ export async function mountAgentGameOffice(
   if (options.focusedAgentId !== undefined) {
     controller.focusAgent?.(options.focusedAgentId);
   }
+  if (options.focusedFloorId !== undefined) {
+    controller.focusFloor?.(options.focusedFloorId);
+  }
 
   return {
     updateAgents(agents: AgentPresence[]) {
@@ -69,12 +72,24 @@ export async function mountAgentGameOffice(
         mutableSource.updateAgents(agents);
       }
     },
+    resetCamera() {
+      controller?.resetCamera?.();
+    },
     focusAgent(agentId) {
       controller?.focusAgent?.(agentId);
     },
+    focusFloor(floorId) {
+      controller?.focusFloor?.(floorId);
+    },
+    getFocusedFloor() {
+      return controller?.getFocusedFloor?.() ?? null;
+    },
     refreshAgents() {
       runtimeSubscription?.refresh();
     },
+    getNavigationErrors() {
+      return controller?.getNavigationErrors?.() ?? [];
+    },
     destroy() {
       unsubscribe();
       runtimeSubscription?.close();

package/src/office/react/AgentGameOfficeView.ts

@@ -59,6 +59,10 @@ export function AgentGameOfficeView({
     viewRef.current?.focusAgent(options.focusedAgentId ?? null);
   }, [options.focusedAgentId]);
 
+  useEffect(() => {
+    viewRef.current?.focusFloor(options.focusedFloorId ?? null);
+  }, [options.focusedFloorId]);
+
   return React.createElement("div", {
     ref: containerRef,
     className,
@@ -75,8 +79,20 @@ function createOfficeConfigKey(office: AgentGameOfficeMountOptions["office"]): s
   if (!office) {
     return "default";
   }
-  return JSON.stringify(office.rooms.map((room) => ({
-    type: room.type,
-    capacity: room.capacity ?? null,
-  })));
+  return JSON.stringify({
+    floors: office.building.floors.map((floor) => ({
+      id: floor.id,
+      name: floor.name,
+      rooms: floor.rooms.map((room) => ({
+        type: room.type,
+        capacity: room.capacity ?? null,
+      })),
+    })),
+    connectors: office.building.connectors.map((connector) => ({
+      id: connector.id,
+      name: connector.name,
+      type: connector.type,
+      serves: connector.serves,
+    })),
+  });
 }

package/src/office/renderers/three/agent-body-instancing.ts

@@ -9,6 +9,7 @@ export type AgentBodyInstanceRecord = {
   mesh: AgentMeshParts;
   renderIndex: number;
   visible: boolean;
+  opacity?: number;
 };
 
 type AgentBodyBatch = {
@@ -17,8 +18,8 @@ type AgentBodyBatch = {
   count: number;
 };
 
-const geometryCache = new Map<string, THREE.BoxGeometry>();
-const materialCache = new Map<number, THREE.MeshLambertMaterial>();
+const geometryCache = new Map<string, THREE.BufferGeometry>();
+const materialCache = new Map<string, THREE.MeshLambertMaterial>();
 const matrixHelper = new THREE.Matrix4();
 
 export class AgentBodyInstancedLayer {
@@ -41,7 +42,7 @@ export class AgentBodyInstancedLayer {
       }
       record.mesh.group.updateMatrixWorld(true);
       resolveAgentBodyPartRenderSpecs(record.renderIndex).forEach((part) => {
-        const batch = this.ensureBatch(part, records.length * 2);
+        const batch = this.ensureBatch(part, records.length * 2, record.opacity ?? 1);
         const object = record.mesh[part.key];
         object.updateMatrixWorld(true);
         matrixHelper.copy(object.matrixWorld);
@@ -67,8 +68,10 @@ export class AgentBodyInstancedLayer {
   private ensureBatch(
     part: ReturnType<typeof resolveAgentBodyPartRenderSpecs>[number],
     requiredCapacity: number,
+    opacity: number,
   ): AgentBodyBatch {
-    const key = `${part.width}:${part.height}:${part.depth}:${part.color}`;
+    const shape = part.shape ?? "box";
+    const key = `${shape}:${part.width}:${part.height}:${part.depth}:${part.color}:${opacity}`;
     const existing = this.batches.get(key);
     if (existing && existing.capacity >= requiredCapacity) {
       return existing;
@@ -78,8 +81,8 @@ export class AgentBodyInstancedLayer {
     }
 
     const mesh = new THREE.InstancedMesh(
-      getGeometry(part.width, part.height, part.depth),
-      getMaterial(part.color),
+      getGeometry(part),
+      getMaterial(part.color, opacity),
       Math.max(requiredCapacity, 1),
     );
     mesh.castShadow = false;
@@ -98,23 +101,45 @@ export function createAgentBodyInstancedLayer(scene: THREE.Scene): AgentBodyInst
   return new AgentBodyInstancedLayer(scene);
 }
 
-function getGeometry(width: number, height: number, depth: number): THREE.BoxGeometry {
-  const key = `${width}:${height}:${depth}`;
+function getGeometry(part: ReturnType<typeof resolveAgentBodyPartRenderSpecs>[number]): THREE.BufferGeometry {
+  const shape = part.shape ?? "box";
+  const key = `${shape}:${part.width}:${part.height}:${part.depth}`;
   const cached = geometryCache.get(key);
   if (cached) {
     return cached;
   }
-  const geometry = new THREE.BoxGeometry(width, height, depth);
+  const geometry = createGeometry(part);
   geometryCache.set(key, geometry);
   return geometry;
 }
 
-function getMaterial(color: number): THREE.MeshLambertMaterial {
-  const cached = materialCache.get(color);
+function createGeometry(part: ReturnType<typeof resolveAgentBodyPartRenderSpecs>[number]): THREE.BufferGeometry {
+  switch (part.shape) {
+    case "frontPlane":
+      return new THREE.PlaneGeometry(part.width, part.height);
+    case "backPlane": {
+      const geometry = new THREE.PlaneGeometry(part.width, part.height);
+      geometry.rotateY(Math.PI);
+      return geometry;
+    }
+    case "box":
+    case undefined:
+      return new THREE.BoxGeometry(part.width, part.height, part.depth);
+  }
+}
+
+function getMaterial(color: number, opacity: number): THREE.MeshLambertMaterial {
+  const key = `${color}:${opacity}`;
+  const cached = materialCache.get(key);
   if (cached) {
     return cached;
   }
-  const material = new THREE.MeshLambertMaterial({ color });
-  materialCache.set(color, material);
+  const material = new THREE.MeshLambertMaterial({
+    color,
+    transparent: opacity < 1,
+    opacity,
+    depthWrite: opacity >= 1,
+  });
+  materialCache.set(key, material);
   return material;
 }

package/src/office/renderers/three/agent-effect-instancing.ts

@@ -5,6 +5,7 @@ import type { AgentMeshParts } from "./agent-mesh";
 export type AgentEffectInstanceRecord = {
   mesh: AgentMeshParts;
   visible: boolean;
+  opacity?: number;
 };
 
 type EffectBatch = {
@@ -34,13 +35,14 @@ export class AgentEffectInstancedLayer {
         return;
       }
       record.mesh.group.updateMatrixWorld(true);
-      this.addObject("glow", record.mesh.activityGlow, records.length);
+      const opacity = record.opacity ?? 1;
+      this.addObject("glow", record.mesh.activityGlow, records.length, opacity);
       record.mesh.activityEffects.typingDots.forEach((dot) => {
-        this.addObject("typingDot", dot, records.length * 3);
+        this.addObject("typingDot", dot, records.length * 3, opacity);
       });
-      this.addObject("toolBlock", record.mesh.activityEffects.toolBlock, records.length);
-      this.addObject("runningRing", record.mesh.activityEffects.runningRing, records.length);
-      this.addObject("completionRing", record.mesh.activityEffects.completionRing, records.length);
+      this.addObject("toolBlock", record.mesh.activityEffects.toolBlock, records.length, opacity);
+      this.addObject("runningRing", record.mesh.activityEffects.runningRing, records.length, opacity);
+      this.addObject("completionRing", record.mesh.activityEffects.completionRing, records.length, opacity);
     });
 
     this.batches.forEach((batch) => {
@@ -57,19 +59,20 @@ export class AgentEffectInstancedLayer {
     this.batches.clear();
   }
 
-  private addObject(key: EffectKey, object: THREE.Object3D, capacity: number): void {
+  private addObject(key: EffectKey, object: THREE.Object3D, capacity: number, opacity: number): void {
     if (!object.visible) {
       return;
     }
-    const batch = this.ensureBatch(key, capacity);
+    const batch = this.ensureBatch(key, capacity, opacity);
     object.updateMatrixWorld(true);
     matrixHelper.copy(object.matrixWorld);
     batch.mesh.setMatrixAt(batch.count, matrixHelper);
     batch.count += 1;
   }
 
-  private ensureBatch(key: EffectKey, requiredCapacity: number): EffectBatch {
-    const existing = this.batches.get(key);
+  private ensureBatch(key: EffectKey, requiredCapacity: number, opacity: number): EffectBatch {
+    const batchKey = `${key}:${opacity}`;
+    const existing = this.batches.get(batchKey);
     if (existing && existing.capacity >= requiredCapacity) {
       return existing;
     }
@@ -80,21 +83,32 @@ export class AgentEffectInstancedLayer {
     const spec = effectSpecs[key];
     const mesh = new THREE.InstancedMesh(
       spec.geometry,
-      spec.material,
+      resolveEffectMaterial(spec.material, opacity),
       Math.max(requiredCapacity, 1),
     );
     mesh.castShadow = false;
     mesh.receiveShadow = false;
     mesh.frustumCulled = false;
-    mesh.name = `agentEffect:${key}`;
+    mesh.name = `agentEffect:${batchKey}`;
     this.scene.add(mesh);
 
     const batch = { mesh, capacity: Math.max(requiredCapacity, 1), count: 0 };
-    this.batches.set(key, batch);
+    this.batches.set(batchKey, batch);
     return batch;
   }
 }
 
+function resolveEffectMaterial(material: THREE.Material, opacity: number): THREE.Material {
+  if (opacity >= 1) {
+    return material;
+  }
+  const clone = material.clone();
+  clone.transparent = true;
+  clone.opacity *= opacity;
+  clone.depthWrite = false;
+  return clone;
+}
+
 export function createAgentEffectInstancedLayer(scene: THREE.Scene): AgentEffectInstancedLayer {
   return new AgentEffectInstancedLayer(scene);
 }

package/src/office/renderers/three/agent-label.ts

@@ -2,6 +2,8 @@ import * as THREE from "three";
 
 import type { AgentGameOfficeAgent } from "../../core/types";
 
+export const AGENT_LABEL_WORLD_Y_OFFSET = 3.05;
+
 export type AgentLabelRecord = {
   root: HTMLDivElement;
   title: HTMLDivElement;
@@ -69,7 +71,7 @@ export function updateAgentLabelPosition(
   viewport: HTMLElement,
 ): void {
   const projected = position.clone();
-  projected.y += 2.2;
+  projected.y += AGENT_LABEL_WORLD_Y_OFFSET;
   projected.project(camera);
   const x = (projected.x * 0.5 + 0.5) * viewport.clientWidth;
   const y = (-projected.y * 0.5 + 0.5) * viewport.clientHeight;

package/src/office/renderers/three/agent-mesh.ts

@@ -13,6 +13,9 @@ export type AgentMeshParts = {
   head: THREE.Object3D;
   leftEye: THREE.Object3D;
   rightEye: THREE.Object3D;
+  mouth: THREE.Object3D;
+  chestFront: THREE.Object3D;
+  backPanel: THREE.Object3D;
   hairTop: THREE.Object3D;
   hairBack: THREE.Object3D;
   leftArm: THREE.Object3D;
@@ -38,6 +41,9 @@ export type AgentBodyPartKey =
   | "head"
   | "leftEye"
   | "rightEye"
+  | "mouth"
+  | "chestFront"
+  | "backPanel"
   | "hairTop"
   | "hairBack"
   | "leftArm"
@@ -45,6 +51,7 @@ export type AgentBodyPartKey =
 
 export type AgentBodyPartRenderSpec = {
   key: AgentBodyPartKey;
+  shape?: "box" | "frontPlane" | "backPlane";
   width: number;
   height: number;
   depth: number;
@@ -66,8 +73,11 @@ export function resolveAgentBodyPartRenderSpecs(index: number): AgentBodyPartRen
     { key: "leftFoot", width: 0.24, height: 0.12, depth: 0.34, color: 0x111827, x: -0.14, y: 0.06, z: 0.08 },
     { key: "rightFoot", width: 0.24, height: 0.12, depth: 0.34, color: 0x111827, x: 0.14, y: 0.06, z: 0.08 },
     { key: "head", width: 0.5, height: 0.48, depth: 0.42, color: skin, x: 0, y: 1.48, z: 0 },
-    { key: "leftEye", width: 0.06, height: 0.07, depth: 0.035, color: 0x111827, x: -0.11, y: 1.5, z: 0.225 },
-    { key: "rightEye", width: 0.06, height: 0.07, depth: 0.035, color: 0x111827, x: 0.11, y: 1.5, z: 0.225 },
+    { key: "leftEye", shape: "frontPlane", width: 0.06, height: 0.07, depth: 0, color: 0x111827, x: -0.11, y: 1.5, z: 0.235 },
+    { key: "rightEye", shape: "frontPlane", width: 0.06, height: 0.07, depth: 0, color: 0x111827, x: 0.11, y: 1.5, z: 0.235 },
+    { key: "mouth", shape: "frontPlane", width: 0.16, height: 0.035, depth: 0, color: 0x7f1d1d, x: 0, y: 1.38, z: 0.245 },
+    { key: "chestFront", shape: "frontPlane", width: 0.28, height: 0.12, depth: 0, color: 0xe0f2fe, x: 0, y: 1.02, z: 0.185 },
+    { key: "backPanel", shape: "backPlane", width: 0.36, height: 0.44, depth: 0, color: 0x0f172a, x: 0, y: 0.92, z: -0.185 },
     { key: "hairTop", width: 0.54, height: 0.14, depth: 0.46, color: hair, x: 0, y: 1.78, z: -0.01 },
     { key: "hairBack", width: 0.52, height: 0.28, depth: 0.09, color: hair, x: 0, y: 1.61, z: -0.23 },
     { key: "leftArm", width: 0.15, height: 0.56, depth: 0.17, color: shirt, x: -0.43, y: 0.88, z: 0 },
@@ -99,6 +109,9 @@ export function createAgentMesh(agent: AgentGameOfficeAgent, index: number): Age
     head: parts.head,
     leftEye: parts.leftEye,
     rightEye: parts.rightEye,
+    mouth: parts.mouth,
+    chestFront: parts.chestFront,
+    backPanel: parts.backPanel,
     hairTop: parts.hairTop,
     hairBack: parts.hairBack,
     leftArm: parts.leftArm,

package/src/office/renderers/three/agent-route.ts

@@ -0,0 +1,220 @@
+import type {
+  AgentGameOfficeAgent,
+  AgentNavigationError,
+} from "../../core/types";
+import {
+  NoBuildingRouteError,
+  planAgentRoute,
+  type AgentRoute,
+  type Vector3Like,
+} from "../../layout";
+import type {
+  ResolvedOffstageAnchor,
+  ResolvedOfficeLayout,
+  ResolvedSeatAnchor,
+} from "../../layout";
+
+export type RenderAgentLocationState = {
+  currentNodeId: string;
+  currentPosition: Vector3Like;
+  destinationAnchorId: string | null;
+  activeRoute: AgentRoute | null;
+  activeStepIndex: number;
+  error?: AgentNavigationError;
+};
+
+type TargetAnchorResult =
+  | { anchor: ResolvedSeatAnchor | ResolvedOffstageAnchor; error?: undefined }
+  | { anchor?: undefined; error: AgentNavigationError };
+
+export function createAgentRouteState(
+  layout: ResolvedOfficeLayout,
+  agent: AgentGameOfficeAgent,
+  previous: RenderAgentLocationState | undefined,
+): RenderAgentLocationState {
+  if (agent.targetPosition) {
+    return {
+      currentNodeId: previous?.currentNodeId ?? `explicit:${agent.id}`,
+      currentPosition: {
+        x: agent.targetPosition.x,
+        y: previous?.currentPosition.y ?? 0,
+        z: agent.targetPosition.z,
+      },
+      destinationAnchorId: null,
+      activeRoute: null,
+      activeStepIndex: 0,
+    };
+  }
+
+  const target = resolveAgentRouteTargetAnchor(layout, agent);
+  if (target.error) {
+    return createErrorState(agent, previous, target.error);
+  }
+
+  const targetNodeId = target.anchor.id;
+  const targetPosition = resolveAnchorPosition(layout, target.anchor);
+  if (!previous) {
+    return {
+      currentNodeId: targetNodeId,
+      currentPosition: targetPosition,
+      destinationAnchorId: targetNodeId,
+      activeRoute: null,
+      activeStepIndex: 0,
+    };
+  }
+
+  if (!layout.building.navigation.nodes.some((node) => node.id === previous.currentNodeId)) {
+    return createErrorState(agent, previous, {
+      agentId: agent.id,
+      code: "stale-location-node",
+      message: `Agent ${agent.id} references missing building navigation node ${previous.currentNodeId}`,
+      fromNodeId: previous.currentNodeId,
+      toNodeId: targetNodeId,
+    });
+  }
+
+  if (previous.destinationAnchorId === targetNodeId && !previous.error) {
+    return previous;
+  }
+
+  try {
+    const route = planAgentRoute(layout.building.navigation, previous.currentNodeId, targetNodeId);
+    return {
+      currentNodeId: previous.currentNodeId,
+      currentPosition: previous.currentPosition,
+      destinationAnchorId: targetNodeId,
+      activeRoute: route,
+      activeStepIndex: 0,
+    };
+  } catch (error) {
+    if (error instanceof NoBuildingRouteError) {
+      return createErrorState(agent, previous, {
+        agentId: agent.id,
+        code: "missing-route",
+        message: error.message,
+        zoneId: agent.zoneId,
+        fromNodeId: previous.currentNodeId,
+        toNodeId: targetNodeId,
+      });
+    }
+    throw error;
+  }
+}
+
+export function resolveAgentRouteTargetAnchor(
+  layout: ResolvedOfficeLayout,
+  agent: AgentGameOfficeAgent,
+): TargetAnchorResult {
+  if (agent.zoneId === "offstage") {
+    return { anchor: layout.anchors.offstage };
+  }
+
+  const floorOrder = new Map(layout.building.floors.map((floor, index) => [floor.id, index]));
+  const roomsById = new Map(layout.rooms.map((room) => [room.id, room]));
+  const candidates = layout.anchors.seats
+    .filter((anchor) => anchor.zoneId === agent.zoneId && anchor.floorId !== "offstage")
+    .sort((left, right) => {
+      if (agent.zoneId === "meeting-room") {
+        const leftIsAuditorium = roomsById.get(left.roomId)?.type === "auditorium";
+        const rightIsAuditorium = roomsById.get(right.roomId)?.type === "auditorium";
+        if (leftIsAuditorium !== rightIsAuditorium) {
+          return leftIsAuditorium ? -1 : 1;
+        }
+      }
+      const floorDelta = (floorOrder.get(left.floorId) ?? 0) - (floorOrder.get(right.floorId) ?? 0);
+      if (floorDelta !== 0) {
+        return floorDelta;
+      }
+      return left.id.localeCompare(right.id);
+    });
+
+  const anchor = candidates[0];
+  if (!anchor) {
+    return {
+      error: {
+        agentId: agent.id,
+        code: "missing-zone-anchor",
+        message: `No building navigation anchor for agent ${agent.id} zone ${agent.zoneId}`,
+        zoneId: agent.zoneId,
+      },
+    };
+  }
+  return { anchor };
+}
+
+export function resolveRouteTargetPosition(state: RenderAgentLocationState): Vector3Like {
+  const step = state.activeRoute?.steps[state.activeStepIndex];
+  return step?.to ?? state.currentPosition;
+}
+
+export function advanceAgentRouteState(
+  state: RenderAgentLocationState,
+  currentPosition: Vector3Like,
+): RenderAgentLocationState {
+  if (!state.activeRoute) {
+    return { ...state, currentPosition };
+  }
+  const step = state.activeRoute.steps[state.activeStepIndex];
+  if (!step) {
+    return {
+      ...state,
+      currentPosition,
+      currentNodeId: state.activeRoute.toNodeId,
+      activeRoute: null,
+      activeStepIndex: 0,
+    };
+  }
+  if (state.activeStepIndex < state.activeRoute.steps.length - 1) {
+    return {
+      ...state,
+      currentPosition: step.to,
+      currentNodeId: step.toNodeId,
+      activeStepIndex: state.activeStepIndex + 1,
+    };
+  }
+  return {
+    ...state,
+    currentPosition: step.to,
+    currentNodeId: step.toNodeId,
+    activeRoute: null,
+    activeStepIndex: 0,
+  };
+}
+
+export function resolveAgentRouteFloorId(
+  layout: ResolvedOfficeLayout,
+  state: RenderAgentLocationState,
+): string | null {
+  const node = layout.building.navigation.nodes.find((item) => item.id === state.currentNodeId);
+  return node?.floorId ?? null;
+}
+
+function createErrorState(
+  agent: AgentGameOfficeAgent,
+  previous: RenderAgentLocationState | undefined,
+  error: AgentNavigationError,
+): RenderAgentLocationState {
+  return {
+    currentNodeId: previous?.currentNodeId ?? "offstage",
+    currentPosition: previous?.currentPosition ?? { x: 0, y: 0, z: 0 },
+    destinationAnchorId: previous?.destinationAnchorId ?? null,
+    activeRoute: null,
+    activeStepIndex: 0,
+    error: { ...error, agentId: agent.id },
+  };
+}
+
+function resolveAnchorPosition(
+  layout: ResolvedOfficeLayout,
+  anchor: ResolvedSeatAnchor | ResolvedOffstageAnchor,
+): Vector3Like {
+  if (anchor.floorId === null) {
+    return anchor.position;
+  }
+  const floor = layout.building.floors.find((item) => item.id === anchor.floorId);
+  return {
+    x: anchor.position.x,
+    y: floor?.elevation ?? 0,
+    z: anchor.position.z,
+  };
+}