Bot Avatar

An interactive 3D bot avatar component built with React Three Fiber. Features smooth animations, customizable themes, and expressive states.

Features

• Multiple bot states (IDLE, LISTENING, THINKING, TALKING, SURPRISED, SAD)
• Customizable color themes
• Smooth animations and transitions
• Eye tracking and mouth animations
• Particle effects during speech
• Fully composable component architecture

Installation

npm install @mayurkakade/bot-avatar

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react react-dom three @react-three/fiber @react-three/drei @react-three/postprocessing

Usage

Basic Example (New Expression System)

The new expression system allows you to combine emotions with activities like speaking!

import React, { useState } from 'react';
import { BotScene, BotExpression, createExpression } from '@mayurkakade/bot-avatar';

function App() {
  const [expression, setExpression] = useState<BotExpression>(
    createExpression('NEUTRAL', 'IDLE')
  );

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BotScene expression={expression} />

      <button onClick={() => setExpression(createExpression('HAPPY', 'SPEAKING'))}>
        Happy Speaking
      </button>
      <button onClick={() => setExpression(createExpression('SAD', 'SPEAKING'))}>
        Sad Speaking
      </button>
    </div>
  );
}

Using Helper Functions

import { BotScene, BotExpressions } from '@mayurkakade/bot-avatar';

function App() {
  const [expression, setExpression] = useState(BotExpressions.neutral());

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BotScene expression={expression} />

      <button onClick={() => setExpression(BotExpressions.happySpeaking())}>
        Happy Speaking
      </button>
      <button onClick={() => setExpression(BotExpressions.surprisedSpeaking())}>
        Surprised Speaking
      </button>
      <button onClick={() => setExpression(BotExpressions.sadSpeaking())}>
        Sad Speaking
      </button>
    </div>
  );
}

Legacy State API (Still Supported)

import React, { useState } from 'react';
import { BotScene, BotState } from '@mayurkakade/bot-avatar';

function App() {
  const [botState, setBotState] = useState<BotState>('IDLE');

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BotScene botState={botState} />

      <button onClick={() => setBotState('TALKING')}>
        Make Bot Talk
      </button>
    </div>
  );
}

Using Custom Colors

import { BotScene, BotColors, THEME_PRESETS } from '@mayurkakade/bot-avatar';

const customColors: BotColors = {
  primary: '#ff6b6b',
  secondary: '#4ecdc4',
  tertiary: '#ffe66d'
};

function App() {
  return (
    <BotScene
      botState="IDLE"
      colors={customColors}
    />
  );
}

// Or use built-in presets
function AppWithPreset() {
  return (
    <BotScene
      botState="IDLE"
      colors={THEME_PRESETS.Emerald}
    />
  );
}

Look At Control

import { BotScene, BotLookAt } from '@mayurkakade/bot-avatar';

function App() {
  const [lookAt, setLookAt] = useState<BotLookAt>({ x: 0, y: 0 });

  const handleMouseMove = (e: MouseEvent) => {
    const x = (e.clientX / window.innerWidth) * 2 - 1;
    const y = -(e.clientY / window.innerHeight) * 2 + 1;
    setLookAt({ x, y });
  };

  return (
    <div onMouseMove={handleMouseMove} style={{ width: '100vw', height: '100vh' }}>
      <BotScene
        botState="IDLE"
        lookAt={lookAt}
      />
    </div>
  );
}

Composable Components

For advanced use cases, you can use individual components:

import { Canvas } from '@react-three/fiber';
import {
  BotAvatar,
  SceneLighting,
  Rings,
  BotColors
} from '@mayurkakade/bot-avatar';

function CustomScene() {
  const colors: BotColors = {
    primary: '#00bcd4',
    secondary: '#9c27b0',
    tertiary: '#ff5722'
  };

  return (
    <Canvas>
      <SceneLighting state="IDLE" colors={colors} />
      <BotAvatar state="TALKING" colors={colors} lookAt={{ x: 0, y: 0 }} />
      <Rings />
    </Canvas>
  );
}

API Reference

BotScene

Main component that renders the complete bot scene.

Props:

• expression?: BotExpression - Bot expression (emotion + activity) - New!
• botState?: BotState - Current state (legacy support)
• colors?: BotColors - Custom color scheme (optional, defaults to Gemini theme)
• lookAt?: BotLookAt - Look direction (optional, defaults to { x: 0, y: 0 })

BotAvatar

The avatar component without the Canvas wrapper.

Props:

• expression?: BotExpression - Bot expression (emotion + activity) - New!
• state?: BotState - Current state (legacy support)
• colors: BotColors - Color scheme
• lookAt?: BotLookAt - Look direction (optional)

Helper Functions

createExpression

createExpression(emotion: BotEmotion, activity?: BotActivity): BotExpression

BotExpressions

Pre-built expressions for quick use:

BotExpressions.neutral()
BotExpressions.neutralSpeaking()
BotExpressions.happy()
BotExpressions.happySpeaking()
BotExpressions.surprised()
BotExpressions.surprisedSpeaking()
BotExpressions.sad()
BotExpressions.sadSpeaking()
BotExpressions.thinking()
BotExpressions.thinkingSpeaking()
// ... and more

Types

BotExpression (New!)

interface BotExpression {
  emotion: BotEmotion;
  activity: BotActivity;
}

type BotEmotion = 'NEUTRAL' | 'HAPPY' | 'SURPRISED' | 'SAD' | 'THINKING';
type BotActivity = 'IDLE' | 'LISTENING' | 'SPEAKING';

Key Feature: You can now combine any emotion with any activity! For example:

• { emotion: 'HAPPY', activity: 'SPEAKING' } - Bot speaks while happy
• { emotion: 'SAD', activity: 'SPEAKING' } - Bot speaks while sad
• { emotion: 'SURPRISED', activity: 'LISTENING' } - Bot listens while surprised

BotState (Legacy)

type BotState = 'IDLE' | 'LISTENING' | 'THINKING' | 'TALKING' | 'SURPRISED' | 'SAD';

BotColors

interface BotColors {
  primary: string;   // Main face color (e.g. Cyan)
  secondary: string; // Secondary gradient color (e.g. Purple)
  tertiary: string;  // Accent/Tertiary gradient color (e.g. Orange)
}

BotLookAt

interface BotLookAt {
  x: number; // Horizontal direction (-1 to 1)
  y: number; // Vertical direction (-1 to 1)
}

Theme Presets

import { THEME_PRESETS } from '@mayurkakade/bot-avatar';

// Available presets:
THEME_PRESETS.Gemini
THEME_PRESETS.Emerald
THEME_PRESETS.Rose
THEME_PRESETS.Amber
THEME_PRESETS.Slate

Development

# Install dependencies
npm install

# Run demo
npm run dev

# Build library
npm run build

# Build demo
npm run build:demo

License

MIT