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:

npm install @xborglabs/avatar

Or using yarn:

yarn add @xborglabs/avatar

Basic Usage

Import and use the component in your React project:

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:

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:

{
  "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.