Ava-Twin logo
← Back to Docs
Developers

Unity SDK

Load your Ava-Twin avatar into any Unity scene in minutes. The SDK handles customizer integration, GLB downloading, humanoid setup, animations, and caching.

v1.0.0Free plan available — no credit card required

Installation

Install via Unity Package Manager (UPM) using a Git URL:

  1. 1. In Unity, open Window → Package Manager.
  2. 2. Click + and select Add package from git URL…
  3. 3. Paste the following URL and click Add:
text
https://github.com/waqaszs/ava-twin-unity-sdk.git#v1.0.0
Dependencies: The SDK automatically resolves its dependencies via UPM: glTFast 5.2.0 and Newtonsoft.Json 3.2.1. No manual setup required.

Demo Scene

The SDK ships with a ready-to-play demo scene. After installing, open Window → Package Manager, select the Ava-Twin SDK, go to the Samples tab, and click Import next to Demo Scene.

Requirements: Unity 2021.3 LTS or later. .NET Standard 2.1. Supports WebGL, iOS, and Android (Desktop coming soon).

Quick Start

  1. 1. In Unity, go to Ava-Twin → Setup from the menu bar. Enter your App ID and API Key from your dashboard.
  2. 2. Call await SDK.OpenCustomizerAsync() to open the customizer and receive the avatar:
csharp
using AvaTwin;
using UnityEngine;

public class AvatarLoader : MonoBehaviour
{
    [SerializeField] private Transform playerTransform;
    [SerializeField] private Animator animator;

    async void Start()
    {
        var result = await SDK.OpenCustomizerAsync();
        if (result != null)
        {
            result.Root.transform.SetParent(playerTransform);

            var humanoid = result.GetUnityHumanoidAvatar();
            if (humanoid != null)
            {
                animator.avatar = humanoid;
                animator.Rebind();
            }
        }
    }
}
Security: Never hardcode API keys. Use a Credentials ScriptableObject and exclude it from version control via .gitignore.

API Reference

CharacterLoader — Methods

Methods
OpenCustomizer()
Open the customizer overlay (internal — use SDK.OpenCustomizerAsync() instead). WebGL: iframe. Mobile: native UI. Editor: loads a random avatar.
CloseCustomizer()
Close the customizer overlay.
LoadCharacterFromUrl(string url)
Load a character from a specific GLB URL.
LoadPreviewCharacterFromUrl(string url)
Load a preview character. Does not fire CharacterLoaded (fires CharacterVisualLoaded instead).
ResolveAndLoadAvatarDirect(string avatarId)
Resolve an avatar ID to a GLB URL via the API, then load it.
SetSkinToneHex(string hex)
Apply a skin tone to the loaded character. Hex format, e.g. "#C68642".
SetCredentials(string appId, string apiKey)
Override credentials at runtime instead of using the Inspector asset.
CancelLoad()
Cancel an in-progress avatar download.
GetLoadedCharacter()
Returns the loaded character GameObject, or null if none loaded.
GetLoadedCharacterAvatar()
Returns the humanoid Avatar asset from the loaded character.

CharacterLoader — Events

Advanced: These events are for advanced use cases (e.g. custom loading pipelines, progress tracking). For most scenarios, use SDK.OpenCustomizerAsync() or SDK.LoadAvatar() instead.
Events
CharacterLoaded
Action<GameObject> — fires when a character is fully loaded into the scene.
CharacterVisualLoaded
Action — fires on any visual load, including previews.
CharacterLoadFailed
Action<string> — fires on load error with a description of what went wrong.

CharacterLoader — Properties

Properties
GlbUrl (string)
Get or set the GLB URL. Setting this does not trigger a load automatically.
SkinToneHex (string)
Read-only. The current skin tone hex value.
IsCustomizerOpen (bool)
Read-only. Whether the customizer overlay is currently visible.

CharacterLoader — Inspector Fields

Inspector Fields
useCache (bool)
Enable local GLB caching. Default: true.
cacheTtlMinutes (float)
Minutes before a cached avatar is re-downloaded. Default: 60.
customizerUrl (string)
URL of the customizer page. Pre-filled with the Ava-Twin hosted customizer — only change this if you self-host.
credentials
Reference to a Credentials ScriptableObject that holds your App ID and API Key. Configure via Ava-Twin > Setup menu.
customizerAllowedOrigin
The origin allowed for postMessage communication between your app and the customizer iframe (e.g. "https://customizer.ava-twin.me").

SDK — Static Methods

The SDK static class provides the primary async/await API for loading avatars. These are the recommended entry points for most use cases.

Static Methods
SDK.OpenCustomizerAsync()
Opens the customizer overlay and returns Task<AvatarResult>. Resolves when the user confirms their avatar. Returns null if the user cancels. Credentials are loaded automatically from the Credentials asset.
SDK.LoadAvatar(string avatarId, string skinToneHex = null)
Resolves an avatar ID to a GLB URL via the API, loads it, and returns Task<AvatarResult>. Optionally applies a skin tone. Credentials are loaded automatically from the Credentials asset.
Note: Credentials are loaded automatically from the Credentials asset (set up via Ava-Twin > Setup menu in Unity). No need to pass appId or apiKey as parameters.
csharp
using AvaTwin;
using UnityEngine;

public class QuickLoad : MonoBehaviour
{
    [SerializeField] private Animator animator;

    async void Start()
    {
        var result = await SDK.OpenCustomizerAsync();
        if (result != null)
        {
            result.Root.transform.SetParent(transform);

            var humanoid = result.GetUnityHumanoidAvatar();
            if (humanoid != null)
            {
                animator.avatar = humanoid;
                animator.Rebind();
            }
        }
    }
}

AvatarResult

Returned by SDK.OpenCustomizerAsync() and SDK.LoadAvatar(). Contains the instantiated avatar and metadata needed for animation, persistence, and networking.

Properties
Root (GameObject)
The instantiated avatar root GameObject in the scene.
AvatarId (string)
Opaque identifier for this avatar. Use for persistence (save/load) and network sync.
SkinToneHex (string)
The skin tone hex color applied to this avatar (e.g. "#C68642").
Methods
GetUnityHumanoidAvatar()
Returns the Unity Humanoid Avatar asset for Mecanim animation. Assign to Animator.avatar and call Rebind() to drive the avatar with your animation controller.

AvaTwinCharacterController

A third-person character controller included in the SDK demo. Drives a humanoid Animator with four parameters: Speed, Grounded, Jump, and FreeFall.

Public Fields
moveSpeed (float)
Walk speed in units/sec.
sprintSpeed (float)
Sprint speed in units/sec.
jumpHeight (float)
Jump height in units.
gravity (float)
Gravity strength (negative value).

AvaTwinInput

Input data struct consumed by AvaTwinCharacterController.

Fields
move (Vector2)
Movement input (WASD / left stick).
look (Vector2)
Camera look input (mouse / right stick).
jump (bool)
Jump input.
sprint (bool)
Sprint input.

Platform Notes

Supported platforms: WebGL, iOS, and Android. Desktop (Windows, macOS, Linux) support is coming soon.
WebGL
The customizer opens as an iframe overlay. The SDK uses postMessage for iframe communication — set the customizerAllowedOrigin field on the CharacterLoader to match your hosting domain. Enable Brotli compression in Player Settings for smaller builds. Avatars are cached in IndexedDB across browser sessions.
Mobile (Android / iOS)
The customizer opens as a native in-app UI with category tabs (head, top, bottom, shoes), a skin tone picker with a default/clear option, and a drag-to-rotate avatar preview. The mobile customizer prefab loads automatically from Resources — no Inspector configuration needed. Set your build target to Android or iOS in Build Settings. The same SDK.OpenCustomizerAsync() and SDK.LoadAvatar() API works on mobile — no code changes required. GLB downloads use UnityWebRequest (no CORS restrictions on native mobile).
Unity Editor
Calling SDK.OpenCustomizerAsync() in the Editor auto-loads a random avatar for quick iteration. No browser or iframe is opened. Use LoadCharacterFromUrl() to test with a specific avatar.

Troubleshooting

Problem
Character doesn’t appear after loading
Solution
Check the Console for errors. Verify CharacterLoader is on an active GameObject and the Credentials asset has a valid App ID and API Key.
Problem
"Not initialized" or credentials error
Solution
Configure your credentials via Ava-Twin > Setup in the menu bar with a valid App ID and API Key from your dashboard.
Problem
T-pose (no animations)
Solution
Ensure the SDK’s Animator Controller is in your project. If using a custom Animator, verify the clips use the correct humanoid avatar from AvatarResult.GetUnityHumanoidAvatar().
Problem
CORS errors in browser console
Solution
Set the customizerAllowedOrigin field on the CharacterLoader Inspector to match your hosting domain (e.g. "https://yourgame.com"). For local dev, use "http://localhost" with your port.
Problem
Works in Editor but not in WebGL build
Solution
The Editor auto-loads a random avatar and skips iframe logic. In WebGL, confirm the customizerAllowedOrigin field on your CharacterLoader component in Unity matches your hosting domain, and that the WebGL template is set to AvaTwin.
Problem
Slow first load
Solution
First loads download the GLB over the network (1–3s typical). Caching is on by default (useCache = true), so subsequent loads are near-instant.
Get the Unity SDK
Sign up for free, get your API key, and install the SDK via UPM in minutes.
Open Dashboard
← Getting StartedREST API Reference →