@agent-os-lab/agent-game-sdk 0.1.14 → 0.1.16

package/README.md

@@ -91,9 +91,16 @@ import { mountAgentAvatar3D } from "@agent-os-lab/agent-game-sdk/avatar";
 
 const view = mountAgentAvatar3D(container, {
   agentId: "agent-1",
+  backgroundColor: "#f8fafc",
   sceneState: "working",
   framing: "upperBody",
   viewAngle: "front",
+  camera: {
+    fov: 32,
+    positionY: 2.1,
+    positionZ: 1.35,
+    lookAtY: 1.42,
+  },
 });
 
 view.update({ sceneState: "thinking", framing: "fullBody", viewAngle: "threeQuarter" });

package/USAGE.md

@@ -188,9 +188,16 @@ import { mountAgentAvatar3D } from "@agent-os-lab/agent-game-sdk/avatar";
 
 const view = mountAgentAvatar3D(container, {
   agentId: "agent-1",
+  backgroundColor: "#f8fafc",
   sceneState: "working",
   framing: "upperBody",
   viewAngle: "front",
+  camera: {
+    fov: 32,
+    positionY: 2.1,
+    positionZ: 1.35,
+    lookAtY: 1.42,
+  },
 });
 
 view.update({
@@ -203,6 +210,8 @@ view.destroy();
 ```
 
 `framing` supports `fullBody` and `upperBody`. `viewAngle` supports `front` and `threeQuarter`.
+The default 3D avatar background is transparent. Pass `backgroundColor` when the canvas or thumbnail should render with a solid color.
+Use `camera` to fine-tune the portrait crop with `fov`, `positionY`, `positionZ`, and `lookAtY`.
 Passing the same `agentId` used in the office game gives the standalone 3D view the same appearance as the office game scene. Use `renderIndex` only when you need to override that AgentID-derived appearance.
 
 ### Static 3D Thumbnails

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-os-lab/agent-game-sdk",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "files": [
     "src",

package/src/avatar/three-scene.ts

@@ -17,8 +17,19 @@ import {
 import { createAgentMesh, type AgentMeshParts } from "../office/renderers/three/agent-mesh";
 import type { AgentAvatar3DFraming, AgentAvatar3DViewAngle } from "./three-view";
 
+export type AgentAvatar3DCameraOptions = {
+  fov?: number;
+  positionY?: number;
+  positionZ?: number;
+  lookAtY?: number;
+};
+
+export type ResolvedAgentAvatar3DCameraOptions = Required<AgentAvatar3DCameraOptions>;
+
 export type AgentAvatar3DSceneOptions = {
   agent?: Partial<AgentGameOfficeAgent>;
+  backgroundColor?: THREE.ColorRepresentation | null;
+  camera?: AgentAvatar3DCameraOptions;
   agentId?: string;
   framing?: AgentAvatar3DFraming;
   sceneState?: AgentGameOfficeSceneState;
@@ -29,6 +40,7 @@ export type AgentAvatar3DSceneOptions = {
 };
 
 export type ResolvedAgentAvatar3DState = AgentGameOfficeAgent & {
+  camera: ResolvedAgentAvatar3DCameraOptions;
   framing: AgentAvatar3DFraming;
   renderIndex: number;
   viewAngle: AgentAvatar3DViewAngle;
@@ -41,6 +53,7 @@ export type AgentAvatar3DScene = {
   bodyLayer: AgentBodyInstancedLayer;
   effectLayer: AgentEffectInstancedLayer;
   state: ResolvedAgentAvatar3DState;
+  setBackground(backgroundColor?: THREE.ColorRepresentation | null): void;
   setState(options: AgentAvatar3DSceneOptions, preservedRenderIndex?: number): ResolvedAgentAvatar3DState;
   render(renderer: { render(scene: THREE.Scene, camera: THREE.Camera): void }, nowMs: number): void;
   dispose(): void;
@@ -48,7 +61,7 @@ export type AgentAvatar3DScene = {
 
 export function createAgentAvatar3DScene(options: AgentAvatar3DSceneOptions): AgentAvatar3DScene {
   const scene = new THREE.Scene();
-  scene.background = new THREE.Color(0xf8fafc);
+  applyAvatar3DBackground(scene, options.backgroundColor);
   const camera = new THREE.PerspectiveCamera(38, options.width / options.height, 0.1, 100);
   scene.add(new THREE.HemisphereLight(0xffffff, 0xd9e2ef, 1.8));
   const keyLight = new THREE.DirectionalLight(0xffffff, 1.4);
@@ -59,7 +72,7 @@ export function createAgentAvatar3DScene(options: AgentAvatar3DSceneOptions): Ag
   const mesh = createAgentMesh(state, state.renderIndex);
   mesh.group.position.set(0, 0, 0);
   applyAvatar3DViewAngle(mesh.group, state.viewAngle);
-  applyAvatar3DFraming(camera, state.framing);
+  applyAvatar3DCamera(camera, state.camera);
   scene.add(mesh.group);
   const bodyLayer = createAgentBodyInstancedLayer(scene);
   const effectLayer = createAgentEffectInstancedLayer(scene);
@@ -73,10 +86,16 @@ export function createAgentAvatar3DScene(options: AgentAvatar3DSceneOptions): Ag
     get state() {
       return state;
     },
+    setBackground(backgroundColor) {
+      applyAvatar3DBackground(scene, backgroundColor);
+    },
     setState(nextOptions, preservedRenderIndex) {
       state = resolveAgentAvatar3DState(nextOptions, preservedRenderIndex);
+      if ("backgroundColor" in nextOptions) {
+        applyAvatar3DBackground(scene, nextOptions.backgroundColor);
+      }
       applyAvatar3DViewAngle(mesh.group, state.viewAngle);
-      applyAvatar3DFraming(camera, state.framing);
+      applyAvatar3DCamera(camera, state.camera);
       return state;
     },
     render(renderer, nowMs) {
@@ -106,6 +125,7 @@ export function resolveAgentAvatar3DState(
   };
   return {
     ...agent,
+    camera: resolveAgentAvatar3DCamera(options.framing ?? "fullBody", options.camera),
     framing: options.framing ?? "fullBody",
     sceneState: options.sceneState ?? agent.sceneState,
     renderIndex: options.renderIndex ?? preservedRenderIndex ?? resolveAgentAvatarRenderIndex(agent.id),
@@ -113,15 +133,38 @@ export function resolveAgentAvatar3DState(
   };
 }
 
-function applyAvatar3DFraming(camera: THREE.PerspectiveCamera, framing: AgentAvatar3DFraming): void {
+function applyAvatar3DBackground(scene: THREE.Scene, backgroundColor?: THREE.ColorRepresentation | null): void {
+  scene.background = backgroundColor === undefined || backgroundColor === null
+    ? null
+    : new THREE.Color(backgroundColor);
+}
+
+function resolveAgentAvatar3DCamera(
+  framing: AgentAvatar3DFraming,
+  camera?: AgentAvatar3DCameraOptions,
+): ResolvedAgentAvatar3DCameraOptions {
   if (framing === "upperBody") {
-    camera.position.set(0, 2.55, 3.35);
-    camera.lookAt(0, 1.42, 0);
-    return;
+    return {
+      fov: camera?.fov ?? 32,
+      positionY: camera?.positionY ?? 2.1,
+      positionZ: camera?.positionZ ?? 1.35,
+      lookAtY: camera?.lookAtY ?? 1.42,
+    };
   }
 
-  camera.position.set(0, 2.1, 5.2);
-  camera.lookAt(0, 1.05, 0);
+  return {
+    fov: camera?.fov ?? 38,
+    positionY: camera?.positionY ?? 2.1,
+    positionZ: camera?.positionZ ?? 5.2,
+    lookAtY: camera?.lookAtY ?? 1.05,
+  };
+}
+
+function applyAvatar3DCamera(camera: THREE.PerspectiveCamera, options: ResolvedAgentAvatar3DCameraOptions): void {
+  camera.fov = options.fov;
+  camera.position.set(0, options.positionY, options.positionZ);
+  camera.lookAt(0, options.lookAtY, 0);
+  camera.updateProjectionMatrix();
 }
 
 function applyAvatar3DViewAngle(group: THREE.Group, viewAngle: AgentAvatar3DViewAngle): void {

package/src/avatar/three-thumbnail.ts

@@ -47,6 +47,7 @@ export type AgentAvatar3DThumbnailMountOptions = AgentAvatar3DThumbnailOptions &
 export type AgentAvatar3DThumbnailController = {
   image: HTMLImageElement;
   thumbnail: AgentAvatar3DThumbnail;
+  update(options: AgentAvatar3DThumbnailOptions): AgentAvatar3DThumbnail;
   destroy(): void;
 };
 
@@ -100,7 +101,8 @@ export function mountAgentAvatar3DThumbnail(
   container: HTMLElement,
   options: AgentAvatar3DThumbnailMountOptions,
 ): AgentAvatar3DThumbnailController {
-  const thumbnail = renderAgentAvatar3DThumbnail(options);
+  const renderer = createAgentAvatar3DThumbnailRenderer(options);
+  let thumbnail = renderer.render(options);
   const image = options.createImage?.() ?? new Image();
   image.src = thumbnail.dataUrl;
   image.width = thumbnail.width;
@@ -109,8 +111,21 @@ export function mountAgentAvatar3DThumbnail(
 
   return {
     image,
-    thumbnail,
+    get thumbnail() {
+      return thumbnail;
+    },
+    update(nextOptions) {
+      thumbnail = renderer.render({
+        ...options,
+        ...nextOptions,
+      });
+      image.src = thumbnail.dataUrl;
+      image.width = thumbnail.width;
+      image.height = thumbnail.height;
+      return thumbnail;
+    },
     destroy() {
+      renderer.destroy();
       image.remove();
     },
   };

package/src/avatar/three-view.ts

@@ -4,6 +4,7 @@ import type { AgentGameOfficeAgent, AgentGameOfficeSceneState } from "../office/
 import { AgentGameError } from "../core/errors";
 import {
   createAgentAvatar3DScene,
+  type AgentAvatar3DCameraOptions,
   type ResolvedAgentAvatar3DState,
 } from "./three-scene";
 
@@ -20,6 +21,8 @@ export type AgentAvatar3DViewAngle = "front" | "threeQuarter";
 
 export type AgentAvatar3DOptions = {
   agent?: Partial<AgentGameOfficeAgent>;
+  backgroundColor?: THREE.ColorRepresentation | null;
+  camera?: AgentAvatar3DCameraOptions;
   agentId?: string;
   framing?: AgentAvatar3DFraming;
   sceneState?: AgentGameOfficeSceneState;
@@ -36,7 +39,7 @@ export type AgentAvatar3DOptions = {
 
 export type AgentAvatar3DUpdateOptions = Partial<Pick<
   AgentAvatar3DOptions,
-  "agent" | "agentId" | "framing" | "sceneState" | "renderIndex" | "viewAngle"
+  "agent" | "agentId" | "backgroundColor" | "camera" | "framing" | "sceneState" | "renderIndex" | "viewAngle"
 >>;
 
 export type AgentAvatar3DController = {
@@ -47,7 +50,7 @@ export type AgentAvatar3DController = {
   getState(): ResolvedAgentAvatar3DState;
 };
 
-export type { ResolvedAgentAvatar3DState } from "./three-scene";
+export type { AgentAvatar3DCameraOptions, ResolvedAgentAvatar3DState } from "./three-scene";
 
 export function mountAgentAvatar3D(
   container: HTMLElement,
@@ -84,10 +87,13 @@ export function mountAgentAvatar3D(
         throw new AgentGameError("runtime_destroyed", "Agent avatar 3D view has been destroyed");
       }
       const agentIdChanged = nextOptions.agentId !== undefined || nextOptions.agent?.id !== undefined;
+      const framingChanged = nextOptions.framing !== undefined && nextOptions.framing !== avatarScene.state.framing;
       const preserveRenderIndex = hasExplicitRenderIndex && nextOptions.renderIndex === undefined && !agentIdChanged;
       avatarScene.setState({
         agent: { ...avatarScene.state, ...nextOptions.agent },
         agentId: nextOptions.agentId,
+        backgroundColor: nextOptions.backgroundColor,
+        camera: nextOptions.camera ?? (framingChanged ? undefined : avatarScene.state.camera),
         framing: nextOptions.framing ?? avatarScene.state.framing,
         sceneState: nextOptions.sceneState ?? avatarScene.state.sceneState,
         renderIndex: nextOptions.renderIndex,