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 or shortcode 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 the 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 the Load Avatar button.
Avatar Loader Editor Window
To load an avatar during runtime, create an instance of the AvatarLoader and call the LoadAvatar() method from the instance with the URL of the avatar to load.
1
private void LoadAvatar()
2
{
3
var avatarLoader = new AvatarLoader();
4
avatarLoader.OnCompleted += AvatarLoadingCompleted;
5
avatarLoader.OnFailed += AvatarLoadingFailed;
6
avatarLoader.OnProgressChanged += AvatarLoadingProgressChanged;
7
8
avatarLoader.LoadAvatar(avatarUrl);
9
}
10
11
private void AvatarLoadingCompleted(object sender, CompletionEventArgs args)
12
{
13
Debug.Log(quot;{args.Avatar.name} is imported!");
14
}
15
16
private void AvatarLoadingFailed(object sender, FailureEventArgs args)
17
{
18
Debug.Log(quot;Failed with {args.Type}: {args.Message}");
19
}
20
21
private void AvatarLoadingProgressChanged(object sender, ProgressChangeEventArgs args)
22
{
23
Debug.Log(quot;Progress: {args.Progress * 100}%");
24
}
Copied!
This operation will download, import, and load the avatar model to the scene. You can use OnCompleted, OnFailed and OnProgressChanged events to notify you app about the current state of the avatar loading operation.
You can find an example of this function in the 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 and 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). For VR and Desktop builds please check the next page.
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 in "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 Partner Editor Window
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 the 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 configuring the output.
public void LoadAvatar(string url)
  • Initiates avatar download and import operations.
public event EventHandler<FailureEventArgs> OnFailed
  • Called upon avatar loader failure.
public event EventHandler<CompletionEventArgs> OnCompleted
  • Called upon avatar loader success.
public event EventHandler<ProgressChangedEventArgs> OnProgressChanged
  • Called upon avatar loader progress change.
public IAvatarImporter AvatarImporter;
  • Avatar Importer instance used for importing the GLB model.
public bool UseAvatarCaching { get; set; }
  • If true, the loader will load the avatar from the project local instead of downloading it.
public string LocalDirectory { get; set; }
  • Directory where the GLB files and avatar metadata will be cached.
WebView (Mobile only)
The component that loads the In-Unity Browser targets 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 the 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.
public void ClearAvatarData()
  • Clear avatar data from the WebView local storage and reload the RPM page for new avatar creation.

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!
public floatBlinkSpeed;
  • How fast the eyes blink in seconds.
public AudioSource BlinkInterval;
  • Frequency of eye blinking in seconds.

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.

Have issues while integrating the Unity Avatar SDK?

Check out our Troubleshooting page for common fixes and a list of known issues.