How to use Unity Avatar SDK

How to use Ready Player Me Unity SDK.

Requirements

  • The SDK supports Unity 2019LTS and newer versions of the Unity3D game engine.

  • A valid avatar URL 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 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 Ready Player Me > Avatar Loader menu. To create and save your avatar in editor time, simply paste your avatar URL and click on Load Avatar button.

To be able to load an avatar during play time, create an instance of AvatarLoader and call LoadAvatar method from the instance with the URL of the avatar to load.

private void LoadAvatar()
{
AvatarLoader avatarLoader = new AvatarLoader();
avatarLoader.LoadAvatar(avatarUrl, AvatarImportedCallback, AvatarLoadedCallback);
}
private void AvatarImportedCallback(GameObject avatar)
{
// called after glb file is downloaded and imported
Debug.Log("Avatar Imported!");
}
private void AvatarLoadedCallback(GameObject avatar, AvatarMetaData metaData)
{
// called after avatar is prepared with components and anim controller
Debug.Log("Avatar Loaded!");
}

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 called always 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 users avatar on the same 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)

This feature lets users create Ready Player Me avatars directly in a WebView displayed within Unity.

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 looks like? Check these short guides below:

Android Guide
IOS Guide

An example of how Webview is used and avatar is loaded afterwards can be found at "Assets/Plugins/Wolf3D Ready Player Me SDK/Examples/Webview".

If you are a 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 Ready Player Me menu. Default partner space is always demo which provides both fullbody and halfbody avatars.

WebView is tested on Unity 2019 LTS and newer versions. You might have errors in prior versions of Unity.

WebView plugin is mobile only and works on Android, IOS systems.

/*
As of 1.6.0 WebView is moved into a canvas 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
*/
private void LoadWebview()
{
Webview webview = FindObjectOfType<WebView>();
webView.CreateWebView();
webview.OnAvatarCreated = AvatarCreatedCallback;
}
private void AvatarCreatedCallback(string url)
{
Debug.Log($"Avatar Url received: { url }");
}

API documentation

AvatarLoader

The main class 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

Component that loads the In-Unity Browser targeting RPM 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 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 string as a status message.

public Action<string> OnAvatarCreated

  • Event to call when 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 setup your avatar. You can add these components on your avatar object from 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 from the component inspector.

private void AvatarLoadedCallback(GameObject avatar)
{
avatar.AddComponent<EyeRotationHandler>();
}

VoiceHandler

Uses microphone feedback to animate the mouthOpen blend shape via amplitude of the voice. Animation will have 1 second delay due to minimum recording length.

private void AvatarLoadedCallback(GameObject avatar)
{
avatar.AddComponent<VoiceHandler>();
}

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 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 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 versions of these dependencies please backup your project before making changes.

Known Issues

  1. Duplicated Newtonsoft JSON issue: If you are using a newer version of Unity that comes with one of the packages that depends on Newtonsoft JSON package (such as Version Control package) when you import RPM SDK you will see DLL file duplication error. If you already have Newtonsoft JSON or a package that depends on it, uncheck the folder in import window or remove the folder if you already imported.

  2. IOS WebView Not Loaded Issue: WebView is supported by IOS 14.3 and newer versions of IOS might not work stably or not work at all.

  3. IOS WebView Login Issue: IOS users might experience RPM Login screen getting stuck forever. This issue is being worked on.

  4. Can't Load an Avatar in Unity 2018: RPM SDK is no more tested and maintained for Unity 2018. If package import is interrupted please make sure you reimport the package without errors. Make sure you add GLTF Utility shaders to always included list in graphics settings.

Please let us know if you run into any issues.