Website Blog Forums
Sign up

Unity SDK 2.0 Migration guide

Our Unity SDK has undergone a major transition to a modular architecture in order to ensure its maintainability and extendability. As part of this transition, several breaking changes have been introduced from the previous Unity SDK 1.x.

This guide outlines these changes and provides instructions on how to migrate from the old Unity SDK 1.x to the new one.

The new Unity SDK

We reorganized the modules into Unity Packages, made a few necessary changes to the API, and the samples now can be imported on demand.

Modules

The Ready Player Me Unity SDK 2.0 has been split into separate modules to improve development processes and to better enable development on different parts of the SDK simultaneously. As such, the Unity SDK consists of two main modules.

Unity-SDK-Core

Unity-SDK-Core contains all the core functionality of the Ready Player Me Unity SDK, plus all the classes and structures that are commonly used in other modules. The following components are included in the Unity-SDK-Core module.

  • Module update and install manager

  • Custom editor window base class

  • Optional editor analytics

  • Core RPM Avatar classes and data structures

    • Avatar config and RPM settings classes

Unity-SDK-Avatar-Loader

This module contains all the classes and structures related to loading avatar models and avatar renders.

Ready Player Me plugins moved to Packages

The new SDK modules are no longer installed in the Assets folder but are in the Packages folder with all the other Unity plugins.

Also because of this, all Scriptable Objects and other assets inside the modules are immutable, meaning that they can not be edited. If you would like to create your own version of a Scriptable Object or Animator from one of our modules, you can create a duplicate of the asset and place it in the Assets folder so that you can customize it as you wish. For example, drag and drop Avatar Animator.asset from Packages/Ready Player Me Avatar Loader/Resources to Assets/Ready Player Me/Resources.

API changes

New GLTF/GLB loader plugin

We have deprecated the support and use of GLTFUtility in favour of a new plugin GLTFast. The default avatar loader will be using glTFast APIs to load avatar models from .glb files.

You can find the glTFast plugin on GitHub.

https://github.com/atteneder/glTFast

AvatarLoader class is now AvatarObjectLoader

Due to the new Unity SDK’s modular structure, we used namespaces to separate the code between packages. For the AvatarLoader we used the ReadyPlayerMe.AvatarLoader namespace and renamed the AvatarLoader.cs class to AvatarObjectLoader.cs. This fixes any namespace clash and is more appropriate to the script's function.

If you have any custom scripts that use Avatar loader it is likely that you will need to update the code.

For example:

// Old API
var avatarLoader = new AvatarLoader();
// New API
var avatarLoader = new AvatarObjectLoader();

WebView class is now WebViewPanel

The WebView modules WebView.cs class has been changed to a WebViewPanel.cs class and the API to initialize the WebView has changed.

For Example:

// Old API
WebView.CreateWebView()
// New API
WebViewPanel.LoadWebView()

UrlConfig class added for WebView

The WebView module has a UrlConfig.cs class that can be used to configure features of the Avatar Creator website by adding query parameters to the URL.

For more information on the configuration or query parameters refer to our documentation.

Sample Scenes

Because the plugin is installed via the Package Manager the packages will now show up in the Package Manager window as shown below.

You can find also and import the sample Scenes from here as they are no longer imported by default.

For example, to import the AvatarLoader example Scene (previously called RuntimerLoaderExample), do the following.

  1. Open the Package Manager window.

  2. Expand the Packages - Ready Player Me section.

  3. Select the Ready Player Me Avatar Loader package.

  4. Expand the Samples section.

  5. Click the Import button next to AvatarLoading.

The sample Scene will now import into the folder as shown below.

Assets/Samples/Ready Player Me Avatar Loader/PACKAGE_VERSION_NUMBER/SAMPLE_NAME

Migration Guide

Follow the steps below to import the Unity SDK into a fresh project or an existing project that already has the old SDK in it.

For this, to work you need to have Git installed on your machine. After installation, you will also need to restart Unity. Git can be downloaded from here.

1. Backup

It is recommended that you back up your project before updating to the new Unity SDK if you are not using source control as there are a lot of big changes both in architecture and with the APIs.

2. Import the Ready Player Me Unity SDK

You must import the new Ready Player Me Unity SDK via the Unity Packager Manager. If you have a project that does not have the previous Unity SDK, this process is easy and automated. Follow the steps in 2.a).

If you want to upgrade the RPM Unity SDK in an existing project, you have to follow a more manual approach in 2.b).

2.a) Import the Unity SDK 2.0 into a new project

The new Ready Player Me Unity SDK must be imported via the Unity Packager Manager by importing via the Git URL of our core module. The Unity-Core package automatically imports all dependencies (glTFast, WebView, Avatar-Loader).

Dependencies will only be installed if you do not have any compile errors.

  1. With Unity Editor open go to Window>Package Manager.

  2. Click the + icon in the top left corner of the Package Manager window.

  3. Click Add package from git URL.

  4. Paste this URL to our Core module: https://github.com/readyplayerme/rpm-unity-sdk-core.git#v1.0.0.

  5. Click Add and wait for the plugins and all required dependencies to be installed.

  6. Once the import process is complete, you will notice that it automatically created two assets.

    • AvatarLoaderSettings (scriptable object)

2.b) Import the Unity SDK 2.0 into a Project with the old Unity SDK

If you have customized avatar configurations or made changes to the animator that’s delivered with the SDK, you should back them up so that you can refer to them after you have updated to the new SDK.

Remove old Unity SDK

To remove the old SDK, delete the following folders from inside the Assets/Plugins folder, if they are present.

  • Assets/Plugins/Ready Player Me

  • Assets/Plugins/GLTFUtility

  • Assets/Plugins/Newtonsoft Json

  • Assets/Plugins/WebView

Import the new Unity SDK and its dependencies

If you have any compile errors as a result of removing the old Ready Player Me Unity SDK, the auto module installer included in the Core package will fail to import the other package and dependencies. You will need to manually import the other 3 dependencies via the Unity Package Manager by importing via the Git URL.

  1. With Unity Editor open, go to Window > Package Manager.

  2. Click the + icon in the top left corner of the Package Manager window.

  3. Click Add package from git URL.

  4. Paste this the URL to our Core module: https://github.com/readyplayerme/rpm-unity-sdk-core.git#v1.0.0

  5. Click Add and wait for the plugins to be installed.

  6. Repeat this for the following three packages (the order is important):

    1. https://github.com/atteneder/glTFast.git#v5.0.0

    2. https://github.com/readyplayerme/rpm-unity-sdk-avatar-loader.git#v1.0.0

    3. https://github.com/readyplayerme/rpm-unity-sdk-webview.git#v1.0.0

  7. Once the import process is complete, you will need to manually create two assets in the Ready Player Me → Resources → Settings Folder. You can do this by right-click → Create → Scriptable Objects → Ready Player Me →

    • AvatarLoaderSettings (scriptable object)

    • CoreSettings (scriptable object)

    The name and location of those files are important. Please do not change.

  8. Fix compile errors due to API changes and namespaces. See API Changes Section above.

Upgrading from Unity Core 0.1.0 to 1.0.0

After core version 0.1.0 we renamed all of the module repositories.

They now follow the convention rpm-unity-sdk-[module name], such as:

rpm-unity-sdk-core

rpm-unity-sdk-avatar-loader

rpm-unity-sdk-webview

Due to this change, you will need to manually upgrade from Unity Core 0.1.0 to 1.0.0 by going to the Unity package manager and adding this URL https://github.com/readyplayerme/rpm-unity-sdk-core.git#v1.0.0.

After the update, if you encounter issues with the Core modules, select the “Check for updates” option in the Unity editor toolbar, as shown in the issue described here. To fix this, you can either do a clean install of the modules or open the projects manifest.json and update the modules' URLs.

To do a clean install follow these steps.

  1. Close your Unity project

  2. Open the projects manifest.json file located at PROJECT_ROOT/Packages/manifest.json.

  3. Find the 3 Ready Player Me modules, and delete the lines shown in the screenshot below.

  4. Reopen the Unity project and do an install as per the steps in 2.b

To manually update the URLs:

  1. Open up the projects manifest.json file located at PROJECT_ROOT/Packages/manifest.json.

  2. Update the URLs for the 3 Ready Player Me modules to match this.

"com.readyplayerme.avatarloader": "<https://github.com/readyplayerme/rpm-unity-sdk-avatar-loader.git#v1.0.0>",
"com.readyplayerme.core": "<https://github.com/readyplayerme/rpm-unity-sdk-core.git#v1.0.0>",
"com.readyplayerme.webview": "<https://github.com/readyplayerme/rpm-unity-sdk-webview.git#v1.0.0>",
PreviousFirewall issuesNextUpdating to the new SDK

Last updated

Change request #130: Asset API