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.

🚀 Quick Start • 📖 Documentation • 🎨 Examples • 🔧 API Reference • ❓ FAQ

✨ Features

🎭 High-Quality 3D Rendering - Powered by Three.js and React Three Fiber
🎬 Custom GLB Animations - Support for any GLB model with animations
🔧 Dynamic Action Management - Add, remove, and modify actions at runtime
🎮 Function-Based Control - Complete programmatic control via hooks
🎨 Semantic Presets - Easy-to-use presets for size, position, speed, and more
📱 Responsive Design - Works perfectly on desktop and mobile
🎤 TTS Integration - Built-in support for text-to-speech synchronization
📦 Lightweight - Minimal bundle size - you provide your own GLB files
⚡ React 19 Compatible - Works with React 16.8+ through React 19
🛡️ WebGL Context Recovery - Handles WebGL context loss gracefully

🚀 Quick Start

Installation

npm install ryd-avatar

Basic Usage

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

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

  useEffect(() => {
    // Add your GLB files with semantic presets
    addAction('idle', {
      model: '/assets/idle.glb',        // Your GLB file
      animationIndex: 0,
      loop: true,
      speed: 'normal',                  // 'slow', 'normal', 'fast', 'very-fast', 'super-fast'
      scale: 'large',                   // 'tiny', 'small', 'medium', 'large', 'xlarge', 'huge'
      position: 'center',               // 'center', 'left', 'right', 'top', 'bottom', 'floating', 'grounded'
      rotation: 'front-slight',         // 'front', 'left', 'right', 'back', 'tilted', 'dynamic'
      autoPlaySound: false
    });

    // Start with idle animation
    playAction('idle');
  }, [addAction, playAction]);

  return (
    <AvatarProvider>
      <RYDAvatar size="main" lighting="soft" />
    </AvatarProvider>
  );
}

export default MyAvatar;

📖 Documentation

🎨 Semantic Presets

The package uses semantic words instead of numbers, making it incredibly easy to customize:

Size Presets

<RYDAvatar size="icon-small" />    // 64x64px - for buttons, icons
<RYDAvatar size="card" />          // 200x250px - for cards, sidebars  
<RYDAvatar size="main" />          // 400x500px - for main content
<RYDAvatar size="hero" />          // 600x700px - for hero sections
<RYDAvatar size="mobile" />        // 280x350px - mobile optimized
<RYDAvatar size="tablet" />        // 400x500px - tablet optimized
<RYDAvatar size="desktop" />       // 600x700px - desktop optimized

Animation Presets

addAction('dance', {
  speed: 'slow',        // 0.5x - slow motion
  speed: 'normal',      // 1.0x - normal speed
  speed: 'fast',        // 1.5x - fast
  speed: 'very-fast',   // 2.0x - very fast
  speed: 'super-fast',  // 3.0x - super fast
  
  scale: 'tiny',        // 0.5x - very small
  scale: 'small',       // 0.8x - small
  scale: 'medium',      // 1.0x - normal size
  scale: 'large',       // 1.5x - large (default)
  scale: 'xlarge',      // 2.0x - extra large
  scale: 'huge',        // 3.0x - huge
  
  position: 'center',   // Perfect center placement
  position: 'left',     // Left side
  position: 'right',    // Right side  
  position: 'top',      // Top placement
  position: 'bottom',   // Bottom placement
  position: 'floating', // Floating above ground
  position: 'grounded', // Grounded placement
  
  rotation: 'front',        // Facing forward
  rotation: 'left',         // Facing left
  rotation: 'right',        // Facing right
  rotation: 'back',         // Facing back
  rotation: 'tilted',       // Slightly tilted
  rotation: 'dynamic',      // Dynamic movement
  rotation: 'front-slight', // Front with slight tilt
  rotation: 'front-up',     // Front looking up
  rotation: 'front-down',   // Front looking down
});

Lighting Presets

<RYDAvatar lighting="bright" />    // Bright, well-lit
<RYDAvatar lighting="soft" />      // Soft, gentle lighting (default)
<RYDAvatar lighting="dramatic" />  // Dramatic shadows
<RYDAvatar lighting="minimal" />   // Minimal lighting

🎮 Function-Based Control

The package is designed for complete programmatic control:

const {
  // Action control
  playAction,    // Play an action with optional custom sound
  stopAction,    // Stop current action and sound
  pauseAction,   // Pause current action and sound
  resumeAction,  // Resume paused action and sound
  
  // Sound control
  playSound,     // Play custom sound
  stopSound,     // Stop current sound
  
  // Action management
  addAction,     // Add new action
  removeAction,  // Remove action
  updateAction,  // Update existing action
  
  // State
  currentState,  // Current action state
  isPlaying,     // Whether animation is playing
  actions        // All available actions
} = useAvatar();

🎤 TTS Integration

Built-in support for text-to-speech synchronization:

addAction('talking', {
  model: '/assets/talking.glb',
  animationIndex: 0,
  loop: true,
  speed: 'fast',
  scale: 'large',
  position: 'center',
  rotation: 'front-slight',
  
  // Sound configuration
  sound: '/assets/default-tts.mp3',  // Default sound file
  autoPlaySound: true,               // Auto-play when action starts
  soundVolume: 0.8,                  // Volume (0-1)
  soundDelay: 0                      // Delay before playing (ms)
});

// Custom TTS integration
const handleTTS = async (text) => {
  const audioUrl = await generateTTS(text); // Your TTS function
  playAction('talking', audioUrl); // Play action with custom sound
};

🎨 Examples

Small Avatar for Buttons

<RYDAvatar size="icon-small" lighting="bright" />

Large Avatar for Hero Section

<RYDAvatar size="hero" lighting="dramatic" />

Responsive Avatar

<RYDAvatar 
  size="mobile"  // Automatically adjusts for mobile
  lighting="soft" 
/>

Multiple Actions

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

  useEffect(() => {
    addAction('idle', {
      model: '/assets/idle.glb',
      animationIndex: 0,
      loop: true,
      speed: 'normal',
      scale: 'large',
      position: 'center',
      rotation: 'front-slight'
    });

    addAction('dance', {
      model: '/assets/dance.glb',
      animationIndex: 0,
      loop: true,
      speed: 'fast',
      scale: 'large',
      position: 'center',
      rotation: 'dynamic'
    });

    addAction('celebration', {
      model: '/assets/celebration.glb',
      animationIndex: 0,
      loop: false,
      speed: 'very-fast',
      scale: 'xlarge',
      position: 'floating',
      rotation: 'dynamic',
      sound: '/assets/celebration.mp3',
      autoPlaySound: true
    });

    // Start with idle
    playAction('idle');
  }, [addAction, playAction]);

  return (
    <div>
      <RYDAvatar size="main" lighting="soft" />
      
      <div style={{ marginTop: '20px' }}>
        <button onClick={() => playAction('idle')}>Idle</button>
        <button onClick={() => playAction('dance')}>Dance</button>
        <button onClick={() => playAction('celebration')}>Celebrate</button>
      </div>
    </div>
  );
}

Dynamic Action Management

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

// Add new action at runtime
addAction('yoga', {
  model: '/assets/yoga.glb',
  animationIndex: 0,
  loop: true,
  speed: 'slow',
  scale: 'large',
  position: 'center',
  rotation: 'front-slight'
});

// Update existing action
updateAction('dance', { speed: 'super-fast', scale: 'huge' });

// Remove action
removeAction('yoga');

🔧 API Reference

Components

`RYDAvatar`

The main avatar component.

Props:

className (string): Custom CSS class
style (object): Custom styles
width (number|string): Container width (number or preset)
height (number|string): Container height (number or preset)
size (string): Size preset ('icon-small', 'card', 'main', 'hero', 'mobile', 'tablet', 'desktop')
lighting (string|object): Lighting preset or custom configuration
enableShadows (boolean): Enable contact shadows (default: true)
enableLights (boolean): Enable default lighting (default: true)
camera (object): Camera 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
playAction (function): Play specific action
stopAction (function): Stop current action
pauseAction (function): Pause current action
resumeAction (function): Resume current action
playSound (function): Play custom sound
stopSound (function): Stop current sound
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|string,             // Animation speed (number or preset)
  scale: number|string,             // Model scale (number or preset)
  position: [x, y, z]|string,       // Model position (array or preset)
  rotation: [x, y, z]|string,       // Model rotation (array or preset)
  sound: string|Audio,              // Sound file path or Audio object
  autoPlaySound: boolean,           // Whether to auto-play sound
  soundVolume: number,              // Sound volume (0-1)
  soundDelay: number,               // Delay before playing sound (ms)
  label: string,                    // Display label
  icon: string,                     // Emoji or icon
  color: string                     // Color theme
}

❓ FAQ

Q: Do I need to provide my own GLB files?

A: Yes! The package is lightweight and doesn't include any GLB files. You need to provide your own GLB models with animations.

Q: What GLB file format is supported?

A: Any GLB file with animations. The package uses Three.js GLTFLoader, so it supports the standard GLB format.

Q: How do I find the right animation index?

A: Most GLB files have the main animation at index 0. If that doesn't work, try indices 1, 2, 3, etc. You can also use browser dev tools to inspect the GLB file.

Q: Why is my animation not playing?

A: Common issues:

Wrong animation index (try 1, 2, 3 instead of 0)
Animation speed too slow (try 'fast' or 'very-fast')
GLB file doesn't contain animations
WebGL context issues (try refreshing the page)

Q: Is this compatible with React 19?

A: Yes! The package supports React 16.8+ through React 19. There may be some version warnings with React 19, but they don't affect functionality.

Q: Can I use this in production?

A: Absolutely! The package is production-ready and includes WebGL context recovery, error handling, and performance optimizations.

Q: How do I handle WebGL context loss?

A: The package automatically handles WebGL context loss and recovery. If you encounter issues, try refreshing the page or using the restart functionality.

🛠️ Requirements

React 16.8.0, 17.x, 18.x, or 19.x
Three.js compatible browser
WebGL support
Your own GLB files with animations

📦 Dependencies

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

🤝 Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

📧 Email: support@ryd.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📖 Documentation: Full Documentation

🌟 Star History

Made with ❤️ by the RYD Team

⭐ Star this repo • 🐛 Report Bug • 💡 Request Feature