UE Troubleshooting

Troubleshooting common problems with the Unreal Engine Avatar SDK.

Crashes on built applications - Missing materials error
A common cause of crashes on built applications using the Ready Player Me SDK is missing files or folders, such as the glTFRuntime materials. 
To fix this, adjust the packaging settings.
1. Go to Edit > Project Settings > Packaging.
2.Expand the Packaging section and look for Additional Asset Directories to Cook. Alternatively, you can search for this setting from the top of the Project Settings window. 
3.Add the /ReadyPlayerMe and /glTFRuntime folders as shown below. 
Errors on Blueprint projects
While we recommend using a C++ project (or converting your Blueprint project to a C++ project), it is possible to work with the plugin on a Blueprint Only project. If you are having issues integrating the SDK into your Unreal Blueprint project, here are some things to note. 
There are separate versions of the plugin for Blueprint projects. Check in the Blueprint Only folder here and select the version that matches your Unreal Engine version.
For Blueprint Only projects the plugin needs to be installed into the specific engine, check out how to do an Engine Install here.
Unable to compile or open a C++ project
When importing the plugin into your Unreal C++ project, you should extract the plugin Zip file into the PROJECT_NAME/Plugins directory. If the directory doesn't exist, create it.
If you encounter errors that prevent you from compiling, the most common fix is to remove all generated files/folders and perform a clean build, as follows.
1.Insider your project, delete the folders Binaries, Intermediate, and Saved.
2.Delete the [PROJECT_NAME].sln file (if using Visual Studio) .
3.Delete the Binaries and Intermediate folders inside the plugin folders Plugins/glTFRuntime, Plugins/ReadyPlayerMe.
4.Navigate back to the project root folder, right-click the [PROJECT_NAME].uproject file, and select Generate Visual Studio Project Files.
5.Reopen your project.
If this does not fix your issues, you can open the .sln file and try debugging the issue, or contact us at [email protected] with an email explaining your issue. 
Animation is not playing on character in packaged builds
If animations are not playing after you load a packaged build, this is likely because the character blueprint is not set up correctly. 
1.Check the AnimClass property on your blueprints SkeletalMeshComponent. 
2.Set your AnimClass to the animation blueprint you want to use.  You must set this in the editor before running the application. 
Known Issues/Limitations
Significant lag when loading avatars at runtime
This is currently a known limitation to the free 3rd party glTFRuntime plugin used for handling the import of gltf/glb files both in the editor and at runtime. They are actively working on improvements. Feel free to contact their amazing developers on the discord server here. 
Unreal SDK 0.17.0 breaking changes
Due to major changes to the architecture and classes in the 0.17.0 update,  you may see some errors after updating the plugin. The errors and suggested solutions are shown below. 
Several helper functions have been removed. 
For the helper functions that validated the url, make sure the URL string is not empty.
For the functions that created glTFRuntime configs, you need to create the configs manually. However, you shouldn't be using glTFRuntimr configs manually as the ReadyPlayerMeComponent provides most of the functionality you will need.
For the helper functions that changed the morph targets, use the SkeletalMeshComponent->SetMorphTarget function directly.
The ReadyPlayerMeActorComponent has been renamed to ReadyPlayerMeComponent. This might introduce issues in the existing projects, where the component may be broken and not show any details. The safest way of fixing this issue is to recreate the actor blueprint where the component was included. Just renamaing the component in the code might not work. 
If the comonent was included in the code, you might need to do the following.
1.Remove the component from the code.
2.Compile the project.
3.Save the blueprint of the actor that contained the component.
4.Re-add the component in the code.
5.Compile the project again.
The RunAvatarSetup function has been renamed to LoadAvatar. To fix the broken blueprint, replace the RunAvatarSetup blueprint function with the LoadAvatar.
Unreal SDK 0.18.0 breaking changes
The OnLoadCompleted callback parameter has been added to the LoadAvatar and LoadNewAvatar functions in the ReadyPlayerMeComponent.
The avatar caching logic has changed. If you enabled avatar caching, this change will affect you. The directory where the avatar model is cached will contain a subdirectory where the model is saved. This change supports caching the same avatar with the different Avatar Configurations. You might need to delete the generated PersistentDownloadDir directory.
In ReadyPlayerMeAvatarLoader an AvatarConfig parameter has been added to the LoadAvatar function. This change will not affect you if you use the ReadyPlayerMeComponent.
​

Examples

Help us improve the Unreal SDK

Last modified 1mo ago