Package Exports

@mayurkakade/bot-avatar

Readme

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