Avatar Caching

Store avatar assets and date locally.

The SDK provides an experimental avatar caching functionality. If avatar caching is enabled, every time an avatar is loaded, its assets are stored locally. If you subsequently try to load the avatar again, the system checks if the avatar needs to be updated, and if so, downloads and saves the updated avatar locally. If the avatar does not need to be updated, the avatar is loaded from the locally stored file.

Avatar caching is available at runtime and includes support for Avatar Configurations.

If a Ready Player Me user changes an existing avatar, for example, chooses a different hairstyle, then the avatar needs to be redownloaded even if it is cached locally. This ensures that the application loads the most up-to-date avatar.

Enable Caching

Avatar caching is disabled by default. To enable avatar caching, do the following.

  1. Open Ready Player Me > Settings.

  2. Check Avatar caching enabled.

We recommend deleting any previously created cache after updating to the latest version of the Ready Player Me Unity SDK. See Manage avatar cache data below for details.

Custom Avatar Configuration parameters

When Avatars are loaded via the Avatar API, you can include custom Avatar Configuration parameters to control the configuration of the downloaded avatar. Customizations include texture settings, mesh LODs, and included morph targets.

See Load Avatars for more information and links to example code.

Stored avatar data location

Downloaded avatar data is stored based not only on the avatar GUID, but also the assigned Avatar Configuration parameters. This means that multiple instances of an avatar's data may exist in cache at any given time.

Avatar data is stored at

<Persistent Data Path>/Avatars/<avatar GUID>/<Avatar Config parameters hash>/

Cached avatar data use and updating

  • At runtime, when caching is enabled via the Ready Player Me Settings window, the Avatar Loader checks the state of the avatar on the Ready Player Me server before downloading. If the avatar has not been modified since it was last stored in the client-side cache, the avatar data for the given avatar GUID and Avatar Configuration parameters are loaded from the cache.

  • If changes were made to the avatar on the Ready Player Me server, the client-side cache for the given avatar GUID is cleared and recreated when subsequent AvatarObjectLoader.LoadAvatar()requests are made.

  • If the avatar download is interrupted or aborted during data transmission, any corrupt client-side cache data is deleted and recreated the next time the avatar is downloaded.

Disable Caching

  1. Open Ready Player Me > Settings.

  2. Uncheck Avatar caching enabled.

If caching is disabled, the Avatar Loader always downloads the avatar data from the Ready Player Me server and overwrites data stored on the client. Only one copy of the avatar is stored on the client and replaced on each avatar load request.

If different Avatar Configuration parameters are used for multiple avatar load requests, the parameter hash subfolder name will be replaced in the client-side cache storage.

Manage avatar cache data

You can use the following methods to clear the cache on-device for built applications.

  • AvatarCache.Clear()

  • AvatarCache.DeleteAvatarFolder(string guid)

To clear cache data manually in the Unity Editor, do one of the following.

  • Call AvatarCache.Clear()to clear all client-side cache or AvatarCache.DeleteAvatarFolder(string guid)to clear all client-side cache data for a specific avatar GUID.

  • Open Ready Player Me > Settings and click Clear local avatar cache.

  • Open Ready Player Me > Settings and click Reveal in Finder (Mac) or Show in Explorer (Windows) to go to the Avatars folder containing the data.

Unity Editor Avatar Loader never caches

Avatar caching is not supported when avatars are loaded via the Ready Player Me Avatar Loader window inside the Unity Editor.

When you download avatars using the Avatar Loader window, the avatar data is always downloaded from the server, and a single instance of the avatar data is stored in the project folder.

<Project Folder>/Assets/Ready Player Me/Avatars/

Each time a new avatar is requested, with or without new Avatar Configuration parameters, the stored avatar data is overwritten and the prefab is updated.


To get started with Avatar Caching support, see the Runtime Example Scenes included with the SDK at Assets/Samples/Ready Player Me Core/[VERSION_NUMBER]/AvatarLoadingSamples/AvatarLoading

Last updated