How to use the Unity Avatar SDK
Learn how to use the Ready Player Me Unity Avatar SDK with our guide explaining step by step implementation for apps and games.

Requirements

  • The SDK supports Unity 2019LTS and newer versions of the Unity3D game engine.
  • A valid avatar .glb URL was created from Ready Player Me to import an avatar to a Unity scene.
For iOS builds Microphone Usage Description field in Player Settings must be filled with an appropriate message. VoiceHandler component requires microphone permission, and if this area is not filled, the build will fail. To build without mic permission, simply remove this script.
Make sure to add GLTF Utility shaders into Always Included Shaders list in Graphics Settings to avoid run time issues regarding shaders.
You can find the Always Include Shaders list under Edit > Project Settings > Graphics and GLTFUtility Shaders under Plugins > GLTFUtility > Materials.

How to use

Loading Avatars

RPM Unity SDK editor window can be launched from the unity toolbar by navigating to Ready Player Me > Avatar Loader. To create and save your avatar in the editor, simply paste your avatar URL and click on Load Avatar button.
To be able to load an avatar during runtime, create an instance of AvatarLoader and call the LoadAvatar() method from the instance with the URL of the avatar to load.
1
private void LoadAvatar()
2
{
3
AvatarLoader avatarLoader = new AvatarLoader();
4
avatarLoader.LoadAvatar(avatarUrl, AvatarImportedCallback, AvatarLoadedCallback);
5
}
6
7
private void AvatarImportedCallback(GameObject avatar)
8
{
9
// called after GLB file is downloaded and imported
10
Debug.Log("Avatar Imported!");
11
}
12
13
private void AvatarLoadedCallback(GameObject avatar, AvatarMetaData metaData)
14
{
15
// called after avatar is prepared with components and anim controller
16
Debug.Log("Avatar Loaded!");
17
}
Copied!
This operation will download, import, and load the avatar model to the scene. You can pass two Action parameters as callbacks to be notified when the avatar is imported and when it is loaded. OnAvatarImported event is always called before OnAvatarLoaded event.
You can find an example of this function in Assets\Plugins\Wolf3D Ready Player Me SDK\Examples\Runtime Avatar Loader\RuntimeTest scene.
Ready Player Me updates a user's avatar while keeping the original URL. If you re-customize your avatar, change your avatar from full-body to half-body these changes are reflected on the same URL. Be mindful of this when loading multiple avatars.

Create avatars directly in Unity using WebView (Mobile only)

The WebView feature is only supported on Android and iOS builds. It will not work inside the Unity editor or on Desktop builds (Windows and macOS)
This feature lets users create Ready Player Me avatars directly in a WebView browser displayed in Unity at runtime on mobile devices.
This is achieved by displaying avatar creation and customization in a seamless interface allowing you to embed Ready Player Me avatar creation inside your Unity application.
Want to see how it works? Check these short guides below:
Android Guide
IOS Guide
An example of how the Webview implementation can be found at "Assets/Plugins/Wolf3D Ready Player Me SDK/Examples/Webview".
If you are an RPM partner you can edit the target URL to address your specific domain name from the WebView Partner Editor window, which can be found under the Ready Player Me menu. The default partner space is always demo which provides both full-body and half-body avatars.
WebView is tested on Unity 2019 LTS and newer versions. You might have errors in prior versions of Unity.
1
/*
2
As of 1.6.0 WebView is moved into a canvas prefab.
3
To use webview you can create the WebView Canvas via
4
GameObject/UI/WebView Canvas menu or
5
right-clicking in Hierarchy window and selecting IU/WebView Canvas menu
6
*/
7
8
private void LoadWebview()
9
{
10
Webview webview = FindObjectOfType<WebView>();
11
webView.CreateWebView();
12
webview.OnAvatarCreated = AvatarCreatedCallback;
13
}
14
15
private void AvatarCreatedCallback(string url)
16
{
17
Debug.Log(quot;Avatar Url received: { url }");
18
}
Copied!

API documentation

AvatarLoader

The main class is used for loading and downloading avatar models and configures the output.
public void LoadAvatar(string url, Action<GameObject> onAvatarImported = null, Action<GameObject, AvatarMetaData> onAvatarLoaded = null)
  • Initiates avatar download and import operations.
public int Timeout
  • The timeout value for avatar download request.

Webview (Mobile only)

The component that loads the In-Unity Browser targeting the Ready Player Me website. Hosted under WebViewCanvas prefab. To use WebView you can create the WebView Canvas via GameObject/UI/WebView Canvas menu or right-clicking in Hierarchy window and selecting IU/WebView Canvas menu.
public void CreateWebview()
  • Creates the WebView window and loads the Ready Player Me website.
public void SetScreenPadding(int left, int top, int right, int bottom)
  • Sets the screen padding of the WebView window. Default is 0 for all sides.
public Action<string> OnWebviewStarted
  • Event to call when WebView starts, receives a string as a status message.
public Action<string> OnAvatarCreated
  • Event to call when an avatar is created, receives GLB URL
public void SetVisible(bool visible)
  • Sets the visibility of WebView.

Extras

Ready Player Me Unity SDK comes with a few useful extra components to help you set up your avatar. You can add these components on your avatar object from the component menu or in runtime using Unity's AddComponent method.

EyeRotationHandler

Rotates and blinks the eyes of the avatar randomly. Blink delay can be set by the component inspector.
1
private void AvatarLoadedCallback(GameObject avatar)
2
{
3
avatar.AddComponent<EyeRotationHandler>();
4
}
Copied!

VoiceHandler

Uses microphone feedback to animate the mouthOpen blend shape via amplitude of the voice. The animation will have a 1-second delay due to minimum recording length.
1
private void AvatarLoadedCallback(GameObject avatar)
2
{
3
avatar.AddComponent<VoiceHandler>();
4
}
Copied!
public AudioClip AudioClip;
  • Audio Clip to play.
public AudioSource AudioSource;
  • Audio Source that will play the provided audio. If not assigned in inspector it will be created on the same object as the VoiceHandler component.
public AudioProviderType AudioProvider
  • Enum type of audio provider. Microphone or Audio Clip.
public void PlayCurrentAudioClip()
  • Play the current audio clip.
public void PlayAudioClip(AudioClip audioClip)
  • Set the current audio clip with the given parameter and play it.

Dependencies

Dependencies are already included in the .unitypackage file, if you are using an older or a newer version of these dependencies please backup your project before making changes.

Having issues integrating the Unity Avatar SDK?

Check out our Troubleshooting page for common fixes and a list of known issues.
Last modified 1mo ago