@agent-os-lab/agent-game-sdk 0.1.15 → 0.1.17

package/README.md

@@ -91,6 +91,7 @@ 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",

package/USAGE.md

@@ -188,6 +188,7 @@ 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",
@@ -209,6 +210,7 @@ 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.
 

package/package.json

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

package/src/avatar/three-scene.ts

@@ -28,6 +28,7 @@ export type ResolvedAgentAvatar3DCameraOptions = Required<AgentAvatar3DCameraOpt
 
 export type AgentAvatar3DSceneOptions = {
   agent?: Partial<AgentGameOfficeAgent>;
+  backgroundColor?: THREE.ColorRepresentation | null;
   camera?: AgentAvatar3DCameraOptions;
   agentId?: string;
   framing?: AgentAvatar3DFraming;
@@ -52,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;
@@ -59,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);
@@ -84,8 +86,14 @@ 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);
       applyAvatar3DCamera(camera, state.camera);
       return state;
@@ -125,6 +133,12 @@ export function resolveAgentAvatar3DState(
   };
 }
 
+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,

package/src/avatar/three-view.ts

@@ -21,6 +21,7 @@ export type AgentAvatar3DViewAngle = "front" | "threeQuarter";
 
 export type AgentAvatar3DOptions = {
   agent?: Partial<AgentGameOfficeAgent>;
+  backgroundColor?: THREE.ColorRepresentation | null;
   camera?: AgentAvatar3DCameraOptions;
   agentId?: string;
   framing?: AgentAvatar3DFraming;
@@ -38,7 +39,7 @@ export type AgentAvatar3DOptions = {
 
 export type AgentAvatar3DUpdateOptions = Partial<Pick<
   AgentAvatar3DOptions,
-  "agent" | "agentId" | "camera" | "framing" | "sceneState" | "renderIndex" | "viewAngle"
+  "agent" | "agentId" | "backgroundColor" | "camera" | "framing" | "sceneState" | "renderIndex" | "viewAngle"
 >>;
 
 export type AgentAvatar3DController = {
@@ -91,6 +92,7 @@ export function mountAgentAvatar3D(
       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,

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

@@ -115,6 +115,7 @@ export function applyAgentPose(
 function resetPose(mesh: AgentMeshParts): void {
   mesh.visualRoot.position.y = 0;
   mesh.body.rotation.set(0, 0, 0);
+  mesh.headRoot.rotation.set(0, 0, 0);
   mesh.head.rotation.set(0, 0, 0);
   mesh.leftArm.rotation.set(0, 0, 0);
   mesh.rightArm.rotation.set(0, 0, 0);
@@ -150,7 +151,7 @@ function applyPoseMode(
       applySeatedLowerBody(mesh);
       mesh.visualRoot.position.y = CHAIR_SEATED_VISUAL_Y;
       mesh.body.rotation.x = -0.1;
-      mesh.head.rotation.x = -0.06;
+      mesh.headRoot.rotation.x = -0.06;
       mesh.leftArm.rotation.x = 0.58 + Math.sin(phase) * 0.18;
       mesh.rightArm.rotation.x = 0.58 - Math.sin(phase) * 0.18;
       mesh.leftArm.rotation.z = -0.08;
@@ -158,21 +159,21 @@ function applyPoseMode(
       return;
     }
     case "thinking":
-      mesh.head.rotation.y = Math.sin(elapsedSeconds * 1.2) * 0.35;
-      mesh.head.rotation.x = Math.sin(elapsedSeconds * 0.9) * 0.08;
+      mesh.headRoot.rotation.y = Math.sin(elapsedSeconds * 1.2) * 0.35;
+      mesh.headRoot.rotation.x = Math.sin(elapsedSeconds * 0.9) * 0.08;
       mesh.body.rotation.z = Math.sin(elapsedSeconds * 1.6) * 0.07;
       return;
     case "meeting":
       applySeatedLowerBody(mesh);
       mesh.visualRoot.position.y = CHAIR_SEATED_VISUAL_Y;
-      mesh.head.rotation.x = Math.sin(elapsedSeconds * 2) * 0.08;
+      mesh.headRoot.rotation.x = Math.sin(elapsedSeconds * 2) * 0.08;
       mesh.leftArm.rotation.x = 0.08;
       mesh.rightArm.rotation.x = -0.08;
       return;
     case "waiting":
       applySeatedLowerBody(mesh);
       mesh.visualRoot.position.y = CHAIR_SEATED_VISUAL_Y;
-      mesh.head.rotation.y = Math.sin(elapsedSeconds * 0.9) * 0.12;
+      mesh.headRoot.rotation.y = Math.sin(elapsedSeconds * 0.9) * 0.12;
       return;
     case "resting": {
       const breath = 1 + Math.sin(elapsedSeconds * 1.2) * 0.025;
@@ -180,7 +181,7 @@ function applyPoseMode(
       mesh.visualRoot.position.y = SOFA_SEATED_VISUAL_Y;
       mesh.body.scale.set(1, breath, 1);
       mesh.body.rotation.x = 0.08;
-      mesh.head.rotation.z = Math.sin(elapsedSeconds * 0.8) * 0.05;
+      mesh.headRoot.rotation.z = Math.sin(elapsedSeconds * 0.8) * 0.05;
       return;
     }
     case "idle": {

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

@@ -10,6 +10,7 @@ export type AgentMeshParts = {
   group: THREE.Group;
   visualRoot: THREE.Group;
   body: THREE.Object3D;
+  headRoot: THREE.Object3D;
   head: THREE.Object3D;
   leftEye: THREE.Object3D;
   rightEye: THREE.Object3D;
@@ -61,6 +62,15 @@ export type AgentBodyPartRenderSpec = {
   z: number;
 };
 
+const HEAD_ROOT_PART_KEYS = new Set<AgentBodyPartKey>([
+  "head",
+  "leftEye",
+  "rightEye",
+  "mouth",
+  "hairTop",
+  "hairBack",
+]);
+
 export function resolveAgentBodyPartRenderSpecs(index: number): AgentBodyPartRenderSpec[] {
   const shirt = agentColors[index % agentColors.length] ?? agentColors[0];
   const skin = skinColors[index % skinColors.length] ?? skinColors[0];
@@ -90,11 +100,25 @@ export function createAgentMesh(agent: AgentGameOfficeAgent, index: number): Age
   group.scale.setScalar(AGENT_MESH_SCALE);
   const visualRoot = new THREE.Group();
   group.add(visualRoot);
+  const specs = resolveAgentBodyPartRenderSpecs(index);
+  const headSpec = specs.find((part) => part.key === "head");
+  if (!headSpec) {
+    throw new Error("Agent mesh head part is required");
+  }
+  const headRoot = new THREE.Group();
+  headRoot.position.set(headSpec.x, headSpec.y, headSpec.z);
+  visualRoot.add(headRoot);
   const parts = Object.fromEntries(
-    resolveAgentBodyPartRenderSpecs(index).map((part) => [
-      part.key,
-      addPart(visualRoot, part.x, part.y, part.z),
-    ]),
+    specs.map((part) => {
+      const parent = HEAD_ROOT_PART_KEYS.has(part.key) ? headRoot : visualRoot;
+      const x = HEAD_ROOT_PART_KEYS.has(part.key) ? part.x - headSpec.x : part.x;
+      const y = HEAD_ROOT_PART_KEYS.has(part.key) ? part.y - headSpec.y : part.y;
+      const z = HEAD_ROOT_PART_KEYS.has(part.key) ? part.z - headSpec.z : part.z;
+      return [
+        part.key,
+        addPart(parent, x, y, z),
+      ];
+    }),
   ) as Record<AgentBodyPartKey, THREE.Object3D>;
   const activityGlow = createActivityGlow();
   const activityEffects = createAgentActivityEffects();
@@ -106,6 +130,7 @@ export function createAgentMesh(agent: AgentGameOfficeAgent, index: number): Age
     group,
     visualRoot,
     body: parts.body,
+    headRoot,
     head: parts.head,
     leftEye: parts.leftEye,
     rightEye: parts.rightEye,