AvatarFactory

High-performance 2D avatar rendering library for React Native with native Metal (iOS) and OpenGL ES (Android) rendering engines.

Installation

npm install @oxyfoo/avatar-factory

Usage

import { AvatarFrame, AvatarCharacter } from '@oxyfoo/avatar-factory';

function MyComponent() {
  return (
    <AvatarFrame
      width={300}
      height={300}
      backgroundColor="#f0f0f0"
    >
      <AvatarCharacter
        body="human_00"
        bodyColor="#ffdbac"
        position={{ x: 0, y: 0 }}
        rotation={{ z: 0 }}
        scale={1.0}
        items={[
          { id: 'hair_00' },
          { id: 'top_00', color: '#ff0000' },
          { id: 'bottom_00', color: '#0000ff' },
          { id: 'shoes_00' }
        ]}
      />
    </AvatarFrame>
  );
}

API

Components

• <AvatarFrame> - Container component for rendering avatars
• <AvatarCharacter> - Defines an avatar to render inside the frame

Functions

• getTechnology() - Returns the rendering technology: 'Metal', 'OpenGL ES', 'Lite', or 'Unknown'

Note: All props are documented with TypeScript types and JSDoc comments. Use your IDE's autocomplete for detailed prop information.

Development

Build

npm run lint        # Lint code
npm run typecheck   # Type checking
npm run build       # Build TypeScript

Example app

cd Example
npm install
npm start

# Then
npm run ios         # Run on iOS simulator
npm run android     # Run on Android emulator

Multi-Avatar Stress Test

To test the SharedTextureManager with multiple avatars:

1. Edit Example/index.js and change:

   import App from './App';
   // to
   import App from './AppMultiTest';

2. Run the app - you can now display 5, 10, 20, or 30+ avatars simultaneously!

Architecture

┌─────────────────────────────────────────────────────────┐
│           SharedTextureManager (Singleton)              │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Global Texture Cache                             │  │
│  │  - Reference counting                             │  │
│  │  - Automatic cleanup                              │  │
│  │  - Thread-safe operations                         │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
         ▲              ▲              ▲
         │              │              │
    ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
    │ Avatar  │    │ Avatar  │    │ Avatar  │
    │ Frame 1 │    │ Frame 2 │    │ Frame N │
    └─────────┘    └─────────┘    └─────────┘

Each AvatarFrame shares the same texture cache, dramatically reducing memory usage.

License

UNLICENSED