# 3D Avatar

The `CustomizeAvatar` component makes it possible to embed customizable 3D avatars on any fan application. This component allows users to view and customize their in-game avatars with different wearables and items from their inventory.

### Installation

To use the `CustomizeAvatar` component, install the `@xborglabs/avatar` package:

```bash
npm install @xborglabs/avatar
```

Or using yarn:

```bash
yarn add @xborglabs/avatar
```

### Basic Usage

Import and use the component in your React project:

```jsx
import { CustomizeAvatar } from "@xborglabs/avatar";
import { getPublicConfig } from "@xborglabs/ui-shared";

// Get the avatar configuration for your tenant
const avatarConfig = getPublicConfig();

// Define the inventory slots with the items the user has equipped
const slots = [
  // Slots will be populated from your inventory API
];

function AvatarComponent() {
  return (
    <CustomizeAvatar 
      slots={slots} 
      config={avatarConfig} 
    />
  );
}
```

### Props

#### Required Props

| Prop     | Type                  | Description                                                                                                 |
| -------- | --------------------- | ----------------------------------------------------------------------------------------------------------- |
| `slots`  | `InventorySlotType[]` | Current inventory slots used to build the avatar. These define which items are equipped on the avatar.      |
| `config` | `object`              | Configuration for the avatar, retrievable per tenant using `getPublicConfig()` from `@xborglabs/ui-shared`. |

#### Optional Props

| Prop         | Type     | Description                                                                                                                                           |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className`  | `string` | Custom HTML class for additional styling.                                                                                                             |
| `cameraZoom` | `string` | Specifies which part of the avatar to zoom in on. Possible values: `all`, `left-hand`, `right-hand`, `headgear`, `upper-body`, `lower-body`, `boots`. |

### Advanced Usage

#### Zooming to Specific Body Parts

You can direct the camera to focus on specific parts of the avatar:

```jsx
import { useState } from 'react';
import { CustomizeAvatar } from "@xborglabs/avatar";

function AdvancedAvatarComponent() {
  const [focus, setFocus] = useState('all');
  
  return (
    <div>
      <div className="controls">
        <button onClick={() => setFocus('all')}>Full View</button>
        <button onClick={() => setFocus('headgear')}>Headgear</button>
        <button onClick={() => setFocus('upper-body')}>Upper Body</button>
        <button onClick={() => setFocus('lower-body')}>Lower Body</button>
        <button onClick={() => setFocus('boots')}>Boots</button>
        <button onClick={() => setFocus('left-hand')}>Left Hand</button>
        <button onClick={() => setFocus('right-hand')}>Right Hand</button>
      </div>
      
      <CustomizeAvatar 
        slots={slots} 
        config={avatarConfig} 
        cameraZoom={focus}
        className="custom-avatar-showcase" 
      />
    </div>
  );
}
```

### Configuration Example

The `config` object contains settings for camera positioning, zoom constraints, and interactivity. Below is an example configuration:

```json
{
  "distance": 3,
  "zoomConfig": {
    "headgear": {
      "move": [0, -0.05, 0],
      "target": [-0.8, 0, 0],
      "position": [0, 0, 1.6]
    },
    "boots": {
      "move": [0, -0.5, 0],
      "target": [-1.9, 0, 0],
      "position": [0, 0, 1.4]
    },
    "upper-body": {
      "move": [0, -0.3, 0],
      "target": [-2, 0, 0],
      "position": [-0.6, 0, 1.3]
    },
    "all": {
      "move": [0, -0.3, 0],
      "target": [-1.9, 0, 0],
      "position": [0, 0, 1.3]
    },
    "left-hand": {
      "move": [0, -0.4, 0],
      "target": [-1.5, 0, 0],
      "position": [1, 0, 1]
    },
    "lower-body": {
      "move": [0, -0.45, 0],
      "target": [-1.9, 0, 0],
      "position": [0, 0, 1.2]
    },
    "right-hand": {
      "move": [0, -0.4, 0],
      "target": [0, 0, 0],
      "position": [-0.8, 0, 2.3]
    }
  },
  "maxDistance": 4.5,
  "minDistance": 2,
  "zoomAllowed": true,
  "controlsAllowed": true
}
```

#### Configuration Properties

| Property          | Type      | Description                                                    |
| ----------------- | --------- | -------------------------------------------------------------- |
| `distance`        | `number`  | Default camera distance from the avatar                        |
| `maxDistance`     | `number`  | Maximum allowed camera distance for zoom out                   |
| `minDistance`     | `number`  | Minimum allowed camera distance for zoom in                    |
| `zoomAllowed`     | `boolean` | Whether users can zoom in/out with mouse wheel                 |
| `controlsAllowed` | `boolean` | Whether users can rotate the avatar with mouse drag            |
| `zoomConfig`      | `object`  | Configuration for camera positioning for different focus areas |

### Performance Considerations

* The 3D avatar may require significant resources to render, especially on lower-end devices
* Consider implementing loading states for slower connections

### Browser Compatibility

The `CustomizeAvatar` component uses WebGL for rendering and is compatible with all modern browsers that support WebGL:

* Chrome 9+
* Firefox 4+
* Safari 5.1+
* Edge 12+
* Opera 12+

Mobile support depends on the device's GPU capabilities and available memory.

### Support

For additional support or questions about the `CustomizeAvatar` component, please contact XBorg's developer support team.