Package Exports

ryd-avatar
ryd-avatar/dist/index.cjs.js
ryd-avatar/dist/index.esm.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ryd-avatar) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

RYD Avatar

A powerful React package for 3D avatar animations with customizable GLB models and dynamic actions.

Features

🎭 3D Avatar Rendering: High-quality 3D avatar rendering using Three.js
🎬 Custom Animations: Support for custom GLB models and animations
🔧 Dynamic Actions: Add, remove, and modify avatar actions at runtime
🎮 Easy Integration: Simple React components and hooks
🎨 Customizable: Full control over lighting, camera, and styling
📱 Responsive: Works on desktop and mobile devices
🎤 TTS Integration: Built-in support for text-to-speech synchronization

Installation

npm install ryd-avatar

Quick Start

⚠️ Important: You need to provide your own GLB files. See the GLB Setup Guide for detailed instructions.

import React, { useEffect } from 'react';
import { RYDAvatar, AvatarProvider, useAvatar } from 'ryd-avatar';

function App() {
  const { addAction, playAction } = useAvatar();

  useEffect(() => {
    // Add your GLB files - make sure they exist in your public/assets/ folder
    addAction('idle', {
      model: '/assets/idle.glb', // Replace with your GLB file path
      animationIndex: 0,
      loop: true,
      speed: 1.0,
      scale: 1.5,
      position: [0, -1.5, 0],
      rotation: [-0.1, 0, 0]
    });
  }, [addAction]);

  return (
    <AvatarProvider>
      <div style={{ width: '600px', height: '700px' }}>
        <RYDAvatar />
        <button onClick={() => playAction('idle')}>Play Idle</button>
      </div>
    </AvatarProvider>
  );
}

Basic Usage

Simple Avatar

import React from 'react';
import { RYDAvatar, AvatarProvider } from 'ryd-avatar';

const MyAvatar = () => {
  return (
    <AvatarProvider>
      <div style={{ width: '600px', height: '700px' }}>
        <RYDAvatar />
      </div>
    </AvatarProvider>
  );
};

Custom Actions

import React from 'react';
import { RYDAvatar, AvatarProvider } from 'ryd-avatar';

const customActions = {
  // Override default action
  dance: {
    model: '/path/to/your/custom-dance.glb',
    animationIndex: 0,
    loop: true,
    speed: 1.2,
    scale: 1.5,
    position: [0, -1.5, 0],
    rotation: [-0.1, 0, 0],
    label: 'Custom Dance',
    icon: '💃',
    color: 'purple'
  },
  // Add new action
  yoga: {
    model: '/path/to/your/yoga.glb',
    animationIndex: 0,
    loop: true,
    speed: 0.8,
    scale: 1.5,
    position: [0, -1.5, 0],
    rotation: [-0.1, 0, 0],
    label: 'Yoga',
    icon: '🧘',
    color: 'green'
  }
};

const CustomAvatar = () => {
  return (
    <AvatarProvider customActions={customActions}>
      <RYDAvatar />
    </AvatarProvider>
  );
};

Controlled Avatar

import React from 'react';
import { RYDAvatar, AvatarProvider, useAvatar } from 'ryd-avatar';

const ControlledAvatar = () => {
  const { playAction, currentState, getAvailableActions } = useAvatar();

  return (
    <div>
      <RYDAvatar />
      
      <div>
        <h3>Available Actions:</h3>
        {getAvailableActions().map(action => (
          <button
            key={action}
            onClick={() => playAction(action)}
            style={{
              backgroundColor: currentState === action ? '#007bff' : '#f8f9fa',
              color: currentState === action ? 'white' : 'black',
              padding: '10px',
              margin: '5px',
              border: '1px solid #dee2e6',
              borderRadius: '4px',
              cursor: 'pointer'
            }}
          >
            {action}
          </button>
        ))}
      </div>
    </div>
  );
};

const App = () => {
  return (
    <AvatarProvider>
      <ControlledAvatar />
    </AvatarProvider>
  );
};

API Reference

Components

`RYDAvatar`

The main avatar component.

Props:

className (string): Custom CSS class
style (object): Custom styles
width (number): Container width (default: 600)
height (number): Container height (default: 700)
enableShadows (boolean): Enable contact shadows (default: true)
enableLights (boolean): Enable default lighting (default: true)
camera (object): Camera configuration
lighting (object): Custom lighting configuration

`AvatarProvider`

Context provider for avatar state management.

Props:

children (ReactNode): Child components
customActions (object): Custom action configurations
defaultState (string): Default avatar state
onStateChange (function): Callback when state changes
onAnimationComplete (function): Callback when animation completes

Hooks

`useAvatar()`

Hook for controlling avatar actions and state.

Returns:

currentState (string): Current avatar state
isPlaying (boolean): Whether animation is playing
actions (object): Available actions
setState (function): Set avatar state
setPlaying (function): Set playing state
playAction (function): Play specific action
stopAction (function): Stop current action
pauseAction (function): Pause current action
resumeAction (function): Resume current action
addAction (function): Add new action
removeAction (function): Remove action
updateAction (function): Update existing action
hasAction (function): Check if action exists
getCurrentAction (function): Get current action config
getAvailableActions (function): Get all available actions

Action Configuration

Each action is configured with the following properties:

{
  model: string,           // Path to GLB model file
  animationIndex: number,  // Index of animation in GLB file
  loop: boolean,          // Whether animation should loop
  speed: number,          // Animation speed multiplier
  scale: number,          // Model scale
  position: [x, y, z],    // Model position
  rotation: [x, y, z],    // Model rotation
  label: string,          // Display label
  icon: string,           // Emoji or icon
  color: string           // Color theme
}

Default Actions

The package comes with these default actions:

idle: Default idle animation
talking: Talking animation for TTS
hello: Hello/wave animation
dance: Dance animation
celebration: Celebration animation
disappointment: Disappointment animation
push: Push animation
waiting: Waiting animation

Advanced Usage

Dynamic Action Management

const { addAction, removeAction, updateAction } = useAvatar();

// Add new action
addAction('yoga', {
  model: '/path/to/yoga.glb',
  animationIndex: 0,
  loop: true,
  speed: 0.8,
  scale: 1.5,
  position: [0, -1.5, 0],
  rotation: [-0.1, 0, 0],
  label: 'Yoga',
  icon: '🧘',
  color: 'green'
});

// Update existing action
updateAction('dance', { speed: 1.5, scale: 2.0 });

// Remove action
removeAction('yoga');

Text-to-Speech Integration

const { playAction, setPlaying } = useAvatar();

const speak = (text) => {
  playAction('talking');
  setPlaying(true);

  const utterance = new SpeechSynthesisUtterance(text);
  utterance.onend = () => {
    playAction('idle');
    setPlaying(false);
  };

  speechSynthesis.speak(utterance);
};

Custom Styling

<RYDAvatar
  width={800}
  height={600}
  className="my-avatar"
  style={{
    border: '2px solid #007bff',
    borderRadius: '10px',
    boxShadow: '0 4px 8px rgba(0,0,0,0.1)'
  }}
  enableShadows={true}
  enableLights={true}
  camera={{ position: [0, 2, 8], fov: 40 }}
  lighting={{
    ambient: { intensity: 0.8 },
    directional: { position: [5, 5, 5], intensity: 2.0 },
    spot: { position: [0, 10, 5], angle: 0.2, penumbra: 0.5, intensity: 1.0 }
  }}
/>

Requirements

React 16.8.0, 17.x, 18.x, or 19.x
Three.js compatible browser
WebGL support

React 19 Compatibility

This package supports React 19, but please note:

@react-three/drei and @react-three/fiber may show version warnings with React 19
These warnings are cosmetic and don't affect functionality
The package works correctly with React 19 despite the warnings

Dependencies

@react-three/fiber: React renderer for Three.js
@react-three/drei: Useful helpers for react-three-fiber
three: 3D graphics library

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For support, please open an issue on GitHub or contact the RYD team.