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

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.16",
   "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,