🎭 React Native 3D Avatar Creator

A comprehensive React Native package for creating customizable 3D avatars with AR support, similar to Snapchat's Bitmoji.

✨ Features

• 🎭 3D Avatar Creation - Fully customizable 3D avatars
• 👗 Outfit Selection - Multiple clothing categories
• 📱 AR Integration - Face tracking and world tracking
• 🎨 Real-time Preview - See changes instantly
• 💾 Persistent Storage - Save and load avatars
• 🔄 Export/Import - Share avatars across devices
• 📦 Easy Integration - Drop-in React Native components
• 🔧 TypeScript Support - Full type safety

🚀 Quick Start

Installation

npm install react-native-3d-avatar-creator
# or
yarn add react-native-3d-avatar-creator

Required Dependencies

npm install @react-three/fiber @react-three/drei three expo-gl expo-file-system expo-asset @viro-community/react-viro zustand uuid

iOS Setup

cd ios && pod install

Android Setup

Add to android/app/build.gradle:

android {
    compileSdkVersion 31
    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 31
    }
}

📖 Usage

Basic Avatar Creator

import React from 'react';
import { View, StyleSheet } from 'react-native';
import { AvatarCreator } from 'react-native-3d-avatar-creator';

export default function App() {
  return (
    <View style={styles.container}>
      <AvatarCreator onAvatarSaved={(avatar) => console.log('Saved:', avatar)} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

Avatar Viewer

import { AvatarViewer, useAvatarStore } from 'react-native-3d-avatar-creator';

function AvatarDisplay() {
  const { currentAvatar } = useAvatarStore();
  
  if (!currentAvatar) return null;
  
  return <AvatarViewer avatar={currentAvatar} autoRotate />;
}

AR Camera

import { ARCamera } from 'react-native-3d-avatar-creator';

function ARView() {
  const { currentAvatar } = useAvatarStore();
  
  return (
    <ARCamera 
      avatar={currentAvatar} 
      mode="face-tracking"
      onEvent={(event) => console.log('AR Event:', event)}
    />
  );
}

Programmatic Usage

import { useAvatarStore, AvatarExporter } from 'react-native-3d-avatar-creator';

function AvatarManager() {
  const { createAvatar, updateAvatar, currentAvatar } = useAvatarStore();
  
  // Create new avatar
  const newAvatar = createAvatar('My Avatar');
  
  // Update features
  updateAvatar(newAvatar.id, {
    facialFeatures: {
      faceShape: 'oval',
      skinTone: '#FDB5A6',
      eyeColor: '#4A5568',
      hairStyle: 'short',
      hairColor: '#2D3748',
    }
  });
  
  // Export avatar
  const exportAvatar = async () => {
    const avatarData = await AvatarExporter.exportToJSON(currentAvatar);
    console.log('Exported:', avatarData);
  };
  
  return null;
}

🎭 Avatar Configuration

interface AvatarConfig {
  id: string;
  name: string;
  facialFeatures: {
    faceShape: 'round' | 'oval' | 'square' | 'heart' | 'diamond';
    skinTone: string;
    eyeColor: string;
    eyeShape: 'almond' | 'round' | 'hooded' | 'monolid';
    eyeSize: number;
    eyebrowStyle: 'thick' | 'thin' | 'arched' | 'straight' | 'medium';
    eyebrowColor: string;
    noseShape: 'small' | 'medium' | 'large' | 'pointed' | 'wide';
    mouthShape: 'full' | 'thin' | 'wide' | 'small';
    lipColor: string;
    hairStyle: string;
    hairColor: string;
    facialHair: 'none' | 'mustache' | 'beard' | 'goatee';
    facialHairColor: string;
  };
  outfit: {
    id: string;
    name: string;
    category: 'casual' | 'formal' | 'sport' | 'party' | 'work';
    modelPath: string;
    thumbnail: string;
    colors: string[];
  };
  accessories: {
    glasses?: string;
    hat?: string;
    earrings?: string;
    necklace?: string;
  };
}

📱 Components

AvatarCreator

Main component for creating and customizing avatars.

Props:

• onAvatarSaved?: (avatar: AvatarConfig) => void - Callback when avatar is saved
• initialAvatar?: AvatarConfig - Initial avatar configuration

AvatarViewer

Component for displaying 3D avatars.

Props:

• avatar: AvatarConfig - Avatar to display
• autoRotate?: boolean - Enable automatic rotation (default: true)

ARCamera

AR camera component for using avatars in augmented reality.

Props:

• avatar: AvatarConfig - Avatar to use in AR
• mode?: 'face-tracking' | 'world-tracking' - AR tracking mode
• onEvent?: (event: AREvent) => void - AR event callback

🎨 Customization

Adding Custom Outfits

const customOutfit = {
  id: 'custom-001',
  name: 'Custom Outfit',
  category: 'casual',
  modelPath: 'path/to/model.glb',
  thumbnail: 'path/to/thumbnail.png',
  colors: ['#FF0000', '#00FF00', '#0000FF'],
};

Custom Color Palettes

const customColors = {
  skinTone: ['#FFE0BD', '#FFCD94', '#EAC086', '#FFAD60', '#E0AC69'],
  eyeColor: ['#4A5568', '#2D3748', '#8B4513', '#228B22', '#4169E1'],
  hairColor: ['#2D3748', '#1A202C', '#8B4513', '#D2691E', '#F5DEB3'],
};

🔄 Export/Import

Export Avatar

import { AvatarExporter } from 'react-native-3d-avatar-creator';

// Export as JSON
const jsonUri = await AvatarExporter.exportToJSON(avatarData);

// Export as image
const imageUri = await AvatarExporter.exportToImage(avatarData);

// Share avatar
await AvatarExporter.shareAvatar(avatarData);

Import Avatar

import { AvatarImporter } from 'react-native-3d-avatar-creator';

// Import from JSON
const avatar = await AvatarImporter.importFromJSON(jsonString);

// Import from file
const avatar = await AvatarImporter.importFromFile(fileUri);

// Import from URL
const avatar = await AvatarImporter.importFromURL(url);

🛠️ API Reference

useAvatarStore

Zustand store for managing avatar state.

Methods:

• createAvatar(name: string) => AvatarConfig
• updateAvatar(id: string, updates: Partial<AvatarConfig>) => void
• deleteAvatar(id: string) => void
• setCurrentAvatar(avatar: AvatarConfig | null) => void
• getAvatarById(id: string) => AvatarConfig | undefined
• exportAvatar(id: string) => Promise<AvatarData>
• importAvatar(avatarData: AvatarData) => AvatarConfig

AvatarExporter

Export avatars to various formats.

Methods:

• exportToJSON(avatarData: AvatarData) => Promise<string>
• exportToImage(avatarData: AvatarData) => Promise<string>
• shareAvatar(avatarData: AvatarData) => Promise<void>
• exportForSocialMedia(avatarData: AvatarData) => Promise<{image: string, metadata: any}>

AvatarImporter

Import avatars from various sources.

Methods:

• importFromJSON(jsonString: string) => Promise<AvatarData>
• importFromFile(fileUri: string) => Promise<AvatarData>
• importFromURL(url: string) => Promise<AvatarData>
• importFromQRCode(qrData: string) => Promise<AvatarData>
• batchImport(fileUris: string[]) => Promise<{successful: AvatarData[], failed: any[]}>

🎮 Example App

Check out the /example folder for a complete implementation with:

• Navigation between screens
• Avatar management
• AR camera usage
• Export/import functionality

To run the example:

cd example
npm install
npm start

🐛 Troubleshooting

Common Issues

1. 3D Models Not Loading

   • Ensure GLB/OBJ files are properly placed in assets
   • Check file paths in outfit configurations
   • Verify 3D model formats are supported

2. AR Not Working

   • Verify ARKit/ARCore setup
   • Check camera permissions
   • Ensure device supports AR
   • Install ViroReact properly

3. Performance Issues

   • Reduce polygon count in 3D models
   • Use texture compression
   • Implement LOD (Level of Detail) system
   • Optimize render cycles

4. Build Issues

   • Ensure all peer dependencies are installed
   • Check minimum SDK versions
   • Verify native module linking

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

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

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• GitHub Issues: Create an issue

🙏 Acknowledgments

• React Three Fiber team for 3D rendering
• ViroReact team for AR capabilities
• Zustand team for state management
• Expo team for cross-platform development

Made with ❤️ by the React Native community