Developers

Unity SDK

Load your Ava-Twin avatar into any Unity scene in minutes. The SDK handles downloading, setup, animations, and caching — you just provide the URL.

Installation

Option 1: Unity Package Manager (recommended)

Install directly from your dashboard using a Git URL:

1. Log in to your Ava-Twin dashboard and go to Apps → SDK to copy your package URL.
2. In Unity, open Window → Package Manager.
3. Click + and select Add package from git URL…
4. Paste your package URL and click Add.

Option 2: Manual installation

If you prefer not to use Git, you can download the package directly:

1. Go to your dashboard and navigate to Apps → SDK → Downloads.
2. Download the latest .unitypackage file.
3. In Unity, go to Assets → Import Package → Custom Package… and select the downloaded file.
4. Click Import to add all SDK files to your project.

Requirements: Unity 2021.3 LTS or later • .NET Standard 2.1 • WebGL, Windows, macOS, Linux, Android, or iOS build target • Your package URL is unique to your account — get it from your dashboard.

Quick Start

Get an avatar running in your scene in under five minutes:

1. Import the Ava-Twin SDK package (see Installation).
2. Create an empty GameObject in your scene and add the AvaTwinManager component to it.
3. In the Inspector, paste your API Key (from your dashboard under Apps → API Keys).
4. Add a CharacterLoader component to the same or another GameObject.
5. Set the avatar URL from the Ava-Twin customizer and press Play.

Or initialize everything from code:

csharp

using AvaTwin;
using UnityEngine;

public class AvatarLoader : MonoBehaviour
{
    [SerializeField] private string apiKey = "your-api-key-here";
    [SerializeField] private string appId  = "your-app-id-here";

    async void Start()
    {
        // Initialize the SDK with your API key
        var manager = AvaTwinManager.Instance;
        manager.Initialize(apiKey);

        // Load the avatar into the scene
        var avatar = await manager.LoadAvatar(appId);
        avatar.transform.SetParent(transform);
    }
}

Security note: Never hardcode API keys in production builds. Use Unity's ScriptableObject configs or load keys from a secure backend at runtime. See Configuration for recommended patterns.

The SDK takes it from there — downloading the avatar model, setting up the character controller, configuring animations, and caching the result for future loads.

API Reference

AvaTwinManager

Singleton that manages SDK initialization, avatar loading, and global configuration. Access it from anywhere via AvaTwinManager.Instance.

Methods

Initialize(string apiKey)

Initialize the SDK with your API key. Call once on startup before loading any avatars.

LoadAvatar(string appId)

Load an avatar by app ID. Returns a Task<AvatarInstance> that resolves when the avatar is ready in the scene.

LoadAvatarFromUrl(string glbUrl)

Load an avatar directly from a GLB URL (from the customizer). Useful when you already have the download URL.

GetAvatarConfig(string appId)

Retrieve the avatar configuration and metadata for an app without loading the 3D model.

SetQuality(AvatarQuality quality)

Set the global rendering quality for all avatars. Options: Low, Medium, High, Ultra. Affects LOD levels and texture resolution.

ClearCache()

Remove all cached avatar data from local storage. Useful for freeing disk space or forcing a fresh download.

IsInitialized { get; }

Read-only property. Returns true if Initialize() has been called with a valid API key.

AvatarInstance

Represents a loaded avatar in the scene. Returned by LoadAvatar() and LoadAvatarFromUrl().

Properties & Methods

transform

The Unity Transform of the avatar root. Use this to position, rotate, or parent the avatar in your scene hierarchy.

gameObject

The root GameObject of the loaded avatar.

SetAnimation(string name)

Play a named animation clip. Built-in clips include "idle", "walk", "run", "sprint", "jump", and "fly". Custom clips can be loaded from your customizer configuration.

SetExpression(string name, float weight)

Set a facial expression blend shape. Weight ranges from 0 (off) to 1 (full). Built-in expressions include "smile", "surprised", "angry", and "sad".

GetAnimator()

Returns the underlying Unity Animator component for advanced animation control such as blend trees and state machines.

OnLoaded

Event that fires when the avatar finishes loading and is fully ready in the scene. Subscribe to run setup logic after load completes.

Dispose()

Destroy the avatar and free its resources. Call this when you no longer need the avatar to prevent memory leaks.

CharacterLoader

MonoBehaviour component for loading avatars via the Inspector or at runtime. Attach it to any GameObject in your scene.

Inspector Settings & Methods

GlbUrl

The URL of your avatar from the Ava-Twin customizer. Set in the Inspector or at runtime via code.

EnableCaching

Toggle caching on or off. When enabled, the avatar is saved locally so it loads instantly on repeat visits.

CacheDurationDays

How long a cached avatar is kept before the SDK re-downloads it. Default is 7 days.

AutoLoad

When enabled, the avatar loads automatically on Start(). Disable to trigger loading manually.

LoadAndInstantiateAsync()

Trigger avatar loading manually. Uses the currently set GlbUrl. Returns a Task that completes when the avatar is in the scene.

LoadAndInstantiateAsync(string url)

Load a specific avatar URL, overriding the Inspector value. Useful for runtime avatar selection.

OnAvatarLoaded

UnityEvent that fires when loading completes. Wire it up in the Inspector to trigger UI changes or gameplay logic.

Loading an Avatar

There are two ways to load avatars — pick whichever fits your workflow:

Via the Inspector

Attach CharacterLoader to a GameObject, paste your avatar URL in the Inspector, enable AutoLoad, and press Play. No code required.

Via code

For dynamic scenarios like avatar selection screens, load avatars at runtime:

csharp

using AvaTwin;
using UnityEngine;

public class AvatarSelector : MonoBehaviour
{
    [SerializeField] private CharacterLoader characterLoader;
    [SerializeField] private Transform spawnPoint;

    // Called when the player picks an avatar in your UI
    public async void OnAvatarSelected(string avatarUrl)
    {
        // Load and instantiate the selected avatar
        await characterLoader.LoadAndInstantiateAsync(avatarUrl);

        // Position it at the spawn point
        characterLoader.transform.position = spawnPoint.position;
        characterLoader.transform.rotation = spawnPoint.rotation;
    }
}

Using AvaTwinManager directly

For more control, use the manager singleton:

csharp

using AvaTwin;
using UnityEngine;

public class GameManager : MonoBehaviour
{
    [SerializeField] private string apiKey = "your-api-key-here";
    [SerializeField] private string appId  = "your-app-id-here";

    private AvatarInstance currentAvatar;

    async void Start()
    {
        AvaTwinManager.Instance.Initialize(apiKey);

        // Load avatar
        currentAvatar = await AvaTwinManager.Instance.LoadAvatar(appId);
        currentAvatar.transform.position = Vector3.zero;

        // Play idle animation
        currentAvatar.SetAnimation("idle");

        // Set a facial expression
        currentAvatar.SetExpression("smile", 0.5f);
    }

    void OnDestroy()
    {
        // Clean up when done
        currentAvatar?.Dispose();
    }
}

Tip: Always call Dispose() on avatars you no longer need, especially in WebGL builds where memory is limited.

Customizer Integration

The Ava-Twin Customizer lets your players build and personalize their own avatars. Here's how to integrate it into your Unity project.

Opening the Customizer from Unity

In WebGL builds, open the customizer in a browser overlay. On desktop/mobile platforms, open it in the system browser:

csharp

using AvaTwin;
using UnityEngine;

public class CustomizerButton : MonoBehaviour
{
    [SerializeField] private string apiKey = "your-api-key-here";
    [SerializeField] private string appId  = "your-app-id-here";

    public async void OpenCustomizer()
    {
        // Mint a secure session token
        var token = await AvaTwinManager.Instance.MintCustomizerToken(appId);

        // Build the customizer URL
        string url = $"https://customizer.ava-twin.me?token={token}";

        // Open in browser
        Application.OpenURL(url);
    }
}

How tokens work: Customizer tokens are short-lived, single-use credentials that authenticate a player session without exposing your API key. The SDK mints them through a secure server-side call. Tokens expire after 15 minutes.

Receiving customization updates

After a player saves their avatar in the customizer, you need to load the updated model. There are two approaches:

Polling (simpler)

Periodically check for avatar updates using GetAvatarConfig(). Good for turn-based games or lobby screens where real-time updates aren't critical.

Webhook (recommended for multiplayer)

Configure a webhook URL in your dashboard (Apps → Settings → Webhooks). When a player saves their avatar, your server receives a POST with the updated GLB URL. Forward this to your Unity client to reload the avatar instantly.

csharp

using AvaTwin;
using UnityEngine;

public class AvatarUpdater : MonoBehaviour
{
    [SerializeField] private CharacterLoader characterLoader;
    [SerializeField] private string appId = "your-app-id-here";

    // Poll for updates (call on a timer or after returning from customizer)
    public async void CheckForUpdates()
    {
        var config = await AvaTwinManager.Instance.GetAvatarConfig(appId);

        if (config.LastModified > lastKnownUpdate)
        {
            // Avatar was changed — reload it
            await characterLoader.LoadAndInstantiateAsync(config.GlbUrl);
            lastKnownUpdate = config.LastModified;
        }
    }

    private System.DateTime lastKnownUpdate;
}

Demo Scene

The SDK ships with a ready-to-play demo scene. Import it from Package Manager:

1. Open Window → Package Manager and select the Ava-Twin SDK package.
2. Open the Samples tab and click Import next to Demo Scene.
3. Open the imported scene, paste your avatar URL into CharacterLoader, and press Play.

What's included: The demo scene has a loaded avatar, third-person camera, and full movement controls (walk, run, sprint, jump, fly) wired up and ready to test.

Controls

The demo scene comes with keyboard and mouse controls out of the box:

Default Key Bindings

W / A / S / D

Move forward, left, backward, right.

Left Shift

Hold to sprint.

Space

Jump.

Toggle fly mode on / off.

Right Mouse Button

Enter aim / strafe mode.

Mouse

Orbit the camera around your character.

These bindings are configured in Edit → Project Settings → Input Manager and can be changed to suit your game.

Configuration

Fine-tune SDK behavior to match your project's requirements.

Quality settings

AvatarQuality Enum

AvatarQuality.Low

Lowest polygon count and texture resolution. Best for mobile and WebGL with many simultaneous avatars.

AvatarQuality.Medium

Balanced quality and performance. Recommended for most WebGL projects.

AvatarQuality.High

High-fidelity avatars with detailed textures. Suitable for desktop builds.

AvatarQuality.Ultra

Maximum quality with full texture resolution and no LOD reduction. Desktop and console only.

csharp

// Set quality before loading avatars
AvaTwinManager.Instance.SetQuality(AvatarQuality.Medium);

Caching

The SDK caches downloaded avatars locally to avoid re-downloading on every session. Caching is enabled by default.

Cache Settings

EnableCaching

Master toggle for the local cache. Default: true.

CacheDurationDays

Number of days before a cached avatar is considered stale and re-downloaded. Default: 7.

MaxCacheSizeMB

Maximum disk space the cache can use. Oldest entries are evicted first when the limit is reached. Default: 200 MB.

WebGL caching: In WebGL builds, avatars are cached in IndexedDB. The cache persists across browser sessions, so repeat visits load instantly without a network request.

Secure API key management

For production builds, avoid embedding your API key directly in the build:

csharp

using AvaTwin;
using UnityEngine;

// Create a ScriptableObject to hold your config
[CreateAssetMenu(fileName = "AvaTwinConfig", menuName = "Ava-Twin/Config")]
public class AvaTwinConfig : ScriptableObject
{
    [Tooltip("Your API key from the Ava-Twin dashboard")]
    public string apiKey;

    [Tooltip("Your app ID from the Ava-Twin dashboard")]
    public string appId;
}

// Load it at runtime
public class SecureInitializer : MonoBehaviour
{
    [SerializeField] private AvaTwinConfig config;

    void Start()
    {
        AvaTwinManager.Instance.Initialize(config.apiKey);
    }
}

Important: Exclude your config ScriptableObject from version control by adding it to .gitignore. Each team member should create their own local config with their API key.

WebGL Notes

CORS configuration

The SDK handles CORS automatically for all Ava-Twin API endpoints. If you're hosting your WebGL build on a custom domain, add it to your allowed origins in the dashboard under Apps → Settings → Allowed Origins.

Memory management

WebGL builds run in a fixed memory heap. Call Dispose() on avatars you no longer need to free memory. For scenes with many avatars, use AvatarQuality.Low or Medium and load avatars on demand rather than all at once.

Loading strategies

Use the OnAvatarLoaded event or OnLoaded callback to show a loading indicator while avatars download. First loads typically take 1–3 seconds; cached loads are nearly instant.

Browser compatibility

Tested on modern versions of Chrome, Firefox, Safari, and Edge — including iOS Safari and Android Chrome. WebGL 2.0 is required (supported by all modern browsers).

Compression

Enable Brotli or Gzip compression in your Unity WebGL build settings (Player Settings → Publishing Settings → Compression Format). This significantly reduces download size for both the build and avatar assets.

Troubleshooting

Problem

Character doesn’t appear after loading

Solution

Open the Console (Window → General → Console) and check for errors. Verify the avatar URL is valid and the CharacterLoader component is attached to an active GameObject. If using AvaTwinManager, ensure Initialize() was called before LoadAvatar().

Problem

"Not initialized" error on LoadAvatar()

Solution

Call AvaTwinManager.Instance.Initialize(apiKey) before any load calls. Check that your API key is valid and hasn’t been revoked in the dashboard.

Problem

No animations — character is stuck in a T-pose

Solution

Make sure the CharacterController asset is present in your project’s Resources folder. It ships with the SDK — check that the import completed without errors. If using a custom Animator, verify the animation clips are assigned.

Problem

Avatar loads in the Editor but not in a WebGL build

Solution

Confirm your WebGL build target is set (File → Build Settings → WebGL). Check that your hosting domain is in the allowed origins list in your dashboard. Try clearing your browser cache and reloading.

Problem

CORS errors in the browser console

Solution

Add your hosting domain to Apps → Settings → Allowed Origins in your dashboard. For local development, add http://localhost and your dev server port.

Problem

Demo scene controls don’t work

Solution

Click inside the game window to give it focus — browsers require a click before capturing keyboard and mouse input. Check that the Input Manager axes are configured (the SDK adds them on import).

Problem

Out of memory in WebGL

Solution

Call Dispose() on avatars you no longer need. Lower the quality with SetQuality(AvatarQuality.Low). Reduce the WebGL memory size in Player Settings or enable memory growth.

Problem

Slow first load times

Solution

First loads require downloading the avatar model. Enable caching (on by default) so subsequent loads are instant. For WebGL, enable Brotli compression in build settings.

Get the Unity SDK

Open Dashboard

← Getting Started REST API Reference →