Chatbot Kit

Scenes

Scene configuration files define the complete 3D environment setup for each scenario in your application. Each scenario (e.g., customer-service, wellness-center, ...) has its own SceneConfig.js file that controls the space, lighting, camera positions, and avatar placement.

Scene Configuration

Scene settings are defined in the SceneConfig.js file located at /src/components/[scenario]/3d/SceneConfig.js.

export const SceneConfig = {
  scenario: "customer-service",
  setupManager: true,
  // ...
};
  • scenario → unique key identifying the scenario
  • setupManager → enables interactive setup panel for fine-tuning positions

We will discuss each section of the configuration in detail below.

Space

The space settings define the 3D environment model and its visual properties. The configuration includes the model file, background gradient settings, and spatial transformations.

Configuration Structure

spaceSettings: {
  spaceFile: "/models/customer-service/office.glb",  // Path to your 3D environment model (Optional)
  translation: {
    position: [0.25, 0, -3.5],  // [x, y, z] position in 3D space
    rotation: [0, 0, 0],        // [x, y, z] rotation in radians
    scale: 0.8                  // Uniform scale factor
  },
  screens: [                    // Optional: Define interactive screens in the space
    {
      name: "Screen1",                          // Name of the material in the GLB model
      url: "/images/customer-service/logo.png", // URL of the image to display
      type: "image"                             // Type of content (currently only "image" supported)
    }
  ],
  backgroundSettings: {       // Gradient background for simple good-looking backdrop (Optional)
    colorBottom: "#47210a",   // Bottom gradient color
    colorTop: "#ebebeb",      // Top gradient color
    colorMiddle: "#d6975a",   // Middle gradient color for transition
    blendMiddle: 0.1,         // Middle color blend position (0-1)
    blendIntensity: 0.37      // Overall gradient intensity
  }
}

Fine-tuning Space Position

You can adjust the space position, rotation, and scale to perfectly align your 3D environment:

  • Position: Moves the entire environment in 3D space [x, y, z]
  • Rotation: Rotates the environment around each axis [x, y, z] in radians
  • Scale: Uniformly scales the environment (1 = original size)

Enable setupManager in SceneConfig.js to use the interactive UI controls for fine-tuning and choose Space in Item to Edit:

Space Position Controls UI Use the UI controls to copy/paste space transformation values

Use the getTranslation button to copy space transformation values and paste them into your SceneConfig.js

Lighting

Lighting in your 3D scene is controlled through a dedicated <Lights /> component.

Each scenario has its own lighting component at /src/components/[scenario]/3d/Lights.jsx where you can define and customize:

  • Ambient Lights: Overall scene illumination
  • Directional Lights: Sun-like lighting with shadows
  • Point Lights: Localized light sources (lamps, screens)
  • Environment: HDRI-based lighting for realistic reflections

Example implementation:

// /components/customer-service/3d/Lights.jsx
export function Lights() {
  return (
    <>
      <ambientLight intensity={0.5} />
      <directionalLight position={[10, 10, 5]} intensity={1} />
      <pointLight position={[0, 2, 0]} intensity={0.5} color="white" />
    </>
  );
}

Camera Management

Camera settings control the viewport and user perspective. The system supports multiple camera positions for different UI states and responsive layouts.

Camera Configuration

cameraSettings: {
  fov: 60,                    // Field of view in degrees
  smoothTime: 0.5,            // Camera transition smoothing time
  idleCamWander: {            // Optional: Subtle camera movement when idle
    enabled: true,
    intensity: {
      x: 0.1,                 // Horizontal wander intensity
      y: 0.05                 // Vertical wander intensity
    },
    speed: {
      x: 0.4,                 // Horizontal wander speed
      y: 0.2                  // Vertical wander speed
    }
  },
  positions: {
    ["default"]: {            // Default layout positions
      [CameraPosition.LOADING]: {
        position: [x, y, z],  // Camera position
        target: [x, y, z]     // Camera look-at target
      },
      [CameraPosition.DEFAULT]: { /* ... */ },
      [CameraPosition.ZOOM_IN]: { /* ... */ },
      [CameraPosition.ZOOM_OUT]: { /* ... */ }
    },
    ["expanded"]: {           // Expanded layout positions
      // Alternative camera positions for different UI states
    }
  }
}

Camera Position States

The system supports multiple predefined camera positions:

  • LOADING: Initial camera position during scene loading
  • DEFAULT: Standard viewing position
  • ZOOM_IN: Closer view for detailed interactions
  • ZOOM_OUT: Wider view for overview perspective

Fine-tuning Camera Positions

Each camera position requires:

  • position: [x, y, z] coordinates where the camera is located
  • target: [x, y, z] coordinates where the camera looks at

To find the perfect values, enable setupManager in SceneConfig.js and use the mouse and your keyboard to navigate the 3D scene:

Controls:

  • Left Click + Drag: Rotate around the target
  • W: Move forward
  • S: Move backward
  • A: Move left
  • D: Move right
  • Q: Move down
  • E: Move up

Once you have the desired view, use the getCameraPosition button in the Camera section of the setup panel. This will copy the current camera position and target to your clipboard, which you can then paste into your SceneConfig.js.

Avatar Position

Avatar positioning controls where your 3D character appears in the scene and how they orient relative to the camera.

Avatar Translation Configuration

avatarSettings: {
  translations: {
    ["default"]: {
      position: [-0.02, 0, -0.975],      // [x, y, z] position
      rotation: [0, 0, 0],               // [x, y, z] rotation in radians
      scale: [1, 1, 1]                   // [x, y, z] scale factors
    }
  },
  lookAtCameraOffset: {
    x: 0,      // Horizontal offset for head tracking
    y: 0,      // Vertical offset for head tracking
    z: 0       // Depth offset for head tracking
  }
}

Position Fine-tuning

  • Position: Places the avatar in 3D space [x, y, z]

    • x: Left (-) / Right (+)
    • y: Down (-) / Up (+)
    • z: Forward (-) / Back (+)

  • Rotation: Orients the avatar [x, y, z] in radians

    • x: Pitch (tilt forward/back)
    • y: Yaw (turn left/right)
    • z: Roll (tilt sideways)

  • Scale: Adjusts avatar size [x, y, z]

    • Use uniform values (e.g., [1.2, 1.2, 1.2]) to maintain proportions

When setupManager is enabled in SceneConfig.js, you can use the UI controls to adjust avatar position interactively. Choose Avatar in Item to Edit:

Avatar Position Controls UI

Use the getTranslation button to copy/paste avatar transformation values

Look-At Camera Offset

The lookAtCameraOffset fine-tunes how the avatar's head tracks the camera:

  • Positive x: Head looks more to the right
  • Positive y: Head looks higher
  • Positive z: Head looks further forward

Customization Notes

Remember that you have complete control over the 3D experience and can fine-tune every aspect:

  1. Multiple Layouts: Define different camera and avatar positions for various UI states (default, expanded, session, etc.)

  2. Responsive Design: Use different position sets for different screen sizes or interaction modes

  3. Dynamic Updates: All values can be updated programmatically during runtime for interactive experiences

  4. Testing Values: Use the UI controls to experiment with values in real-time, then copy the perfect configuration to your SceneConfig file

  5. Scene Variants: Each scenario can have completely different spatial configurations, allowing unique experiences for different use cases

Advanced Customization - Key Files to Edit

For developers who want to go beyond configuration and customize the default behavior, here are the key files you can modify:

Scene Configuration Files

  • /components/[scenario]/3d/SceneConfig.js: Main configuration file for each scenario. Feel free to add custom properties as needed.
  • /store/constants.js: Global constants for camera positions and animation states

3D Components

  • /components/[scenario]/3d/Lights.jsx: Custom lighting setup for each scenario
  • /components/[scenario]/3d/Scene.jsx: Main 3D scene component handling rendering
  • /components/[scenario]/3d/Experience.jsx: Core 3D experience logic and interactions

Avatar System

  • /components/core/3d/avatar/Avatar.jsx: Base avatar component and loading logic
  • /components/core/3d/avatar/Animations.jsx: Animation system and blending logic

Camera System

  • /components/core/3d/CameraManager.jsx: Camera state and position management

Space and Environment

  • /components/core/3d/space/Space.jsx: 3D environment loading and setup
  • /components/core/3d/space/Background.jsx: Gradient background implementation

Next

Avatars & Animations