Before taking a look at any of our integration guides, please ensure you have been in contact with a member of the Player Zero team, and that we have provided you with your developer account credentials.

🎥 Prefer to watch instead? This short video (under 5 minutes) walks you through the steps of integrating the Player Zero SDK into your Unity game.

Prerequisites

• You should have been in contact with a member of the Player Zero team.

• If you intend to use your own existing character proportions and rig with P0 visuals applied on top, then you should have sent us your base character FBX so we can setup a custom blueprint for you. Note: this is not required if you intend to use the default P0 proportions and P0 rig in your game.

• You have should have received confirmation from Player Zero that your account is setup, and you should've been given your Player Zero developer account credentials.

Step 1: Download SDK

You can visit our Unity SDK GitHub releases page to access the latest release and install it via the Unity Package Manager.

Step 2: Login to your Player Zero developer account

Using the credentials provided to you by your account manager, you should now login to your Player Zero developer account as shown in the screenshot below. You can access the developer login window by going to tools -> Player Zero.

Step 3: Verify that your blueprint appears in the list

Before following this document, your Player Zero account manager should've asked you for your character base model, and they should've taken it away and setup a blueprint for you account. Take some time now to verify that your blueprint appears in the window, similar to the ones shown below. It should also have already been populated with a default template prefab.

Step 4: Load a Player Zero avatar

Using the test script below, you can now try to test out loading a Player Zero character. You can use any avatar ID, including ones from the playerzero.readyplayer.me platform, or one of the test avatar IDs we’ve provided, such as: 6799e786ad3f17b0ac17f265, 6799e89a4f6181e930480786.

using PlayerZero.Runtime.Sdk;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    // Start is called before the first frame update
    private async void Start()
    {
        var avatar = await PlayerZeroSdk.InstantiateAvatarAsync(
            new CharacterRequestConfig()
            {
                AvatarId = "AVATAR_ID_HERE"
            }
        );
    }
}

Step 4.1: Load a Player Zero avatar using Mesh Transfer (Alternative Approach)

In some scenarios, you may already have a character prefab in your scene that is fully rigged and wired up with your controller logic, animations, clothing, and more. In this case, instantiating a brand new Player Zero avatar GameObject and setting everything up again at runtime can be unnecessary and complicated.

To simplify this, the SDK provides a Mesh Transfer utility class. This allows you to load a Player Zero avatar and transfer its mesh, materials, and textures onto an existing character prefab that already has the correct rig setup. The temporary avatar is cleaned up automatically after the transfer is complete.

✅ Benefits

• Keeps your original prefab, controller setup, and hierarchy intact.

• Supports runtime mesh customization while maintaining gameplay logic.

• Works with any prefab using a compatible rig (e.g., a Player Zero blueprint rig or custom rig if prearranged with the team).

🧠 How It Works

Under the hood:

1. A Player Zero avatar is loaded in the background.

2. Meshes and materials from the new avatar are transferred to your existing character.

3. The temporary avatar is destroyed after transfer.

📦 Prerequisites

• Your existing character prefab must use a compatible rig and hierarchy (typically a previously registered Player Zero blueprint).

• Your avatar should be loaded with a matching BlueprintId.

🧪 Example: Load and Transfer to Existing Character

using PlayerZero.Runtime.Sdk;
using PlayerZero.Runtime.MeshTransfer;
using UnityEngine;

public class MeshTransferExample : MonoBehaviour
{
    public GameObject existingCharacter; // This should be your in-scene character prefab with a SkinnedMeshRenderer setup.
    
    private async void Start()
    {
        var avatar = await PlayerZeroSdk.InstantiateAvatarAsync(new CharacterRequestConfig
        {
            AvatarId = "AVATAR_ID_HERE",
            BlueprintId = "BLUEPRINT_ID_HERE"
        });
        var meshTransfer = new MeshTransfer();
        // Perform the transfer from the new avatar to your existing character
        meshTransfer.Transfer(avatar, existingCharacter);
    }
}

Step 5: Load an avatar as a specific blueprint

Using the test script below, you can now try to test out loading a Player Zero character as a specific blueprint in your account. The returned avatar will come with the rig and proportions of whatever the target blueprint has.

using PlayerZero.Runtime.Sdk;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    // Start is called before the first frame update
    private async void Start()
    {
        var avatar = await PlayerZeroSdk.InstantiateAvatarAsync(
            new CharacterRequestConfig()
            {
                AvatarId = "AVATAR_ID_HERE",
                BlueprintId = "BLUEPRINT_ID_HERE"
            }
        );
    }
}

Step 6: Hot load an avatar as a specific blueprint

Using the test script below, you can now try to test out loading a Player Zero character that has been passed to the SDK via hot loading, as a specific blueprint in your account. The returned avatar will come with the rig and proportions of whatever the target blueprint has.

using PlayerZero.Runtime.Sdk;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    // Start is called before the first frame update
    private async void Start()
    {
        var avatarId = PlayerZeroSdk.GetHotLoadedAvatarId();
        
        var avatar = await PlayerZeroSdk.InstantiateAvatarAsync(
            new CharacterRequestConfig()
            {
                AvatarId = avatarId,
                BlueprintId = "BLUEPRINT_ID_HERE"
            });
    }
}

Step 7: Add Player Zero analytics to your game

🎥 Prefer to watch instead? This short video (under 2 minutes) walks you through how to set up Player Zero SDK analytics in your Unity game.

In order for us to understand how Player Zero players are interacting with your game, we require you to add the PlayerZeroAnalytics component into your game. The metric captured by this component are vital to your partnership with Player Zero. To set this up, simply create a new empty component in the initial scene of your game, and then add the PlayerZeroAnalytics component.

Step 8: Fire a custom game event

As part of the integration of Player Zero, you may sometimes need to trigger Player Zero game events manually at certain points in your game loop. For example, if you allow your player to switch out their Player Zero avatar for one of your own. Doing this is as simple as calling the SendEvent and StartEventSession functions that is are available through the SDK.

The difference between StartEventSession and SendEvent is that the former creates a new session id when it is sent, and the latter requires a session id to be passed to it to end the session. There are multiple event types that can be sent, and you can see all of these in the Events folder in the SDK.

using PlayerZero.Api.V1;
using PlayerZero.Runtime.Sdk;
using UnityEngine;

public class TestScript : MonoBehaviour
{
    // Start is called before the first frame update
    private void Start()
    {
        var avatarId = PlayerZeroSdk.GetHotLoadedAvatarId();

        PlayerZeroSdk.StartEventSession<GameSessionStartedEvent, GameSessionStartedProperties>(
            new GameSessionStartedEvent()
            {
                Properties = new GameSessionStartedProperties()
                {
                    AvatarId = avatarId,
                }
            });
    }
}

Advanced Features

Extras

Player Zero Lobby

Enable multiplayer-style lobby support, allowing players to gather before entering the game. 👉 Learn more about Player Zero Lobby

Deeplinking

Allow your app to respond to custom URLs for loading specific avatars or scenes directly. 👉 Learn more about Deeplinking

The QuickStart Sample is included with the Player Zero Unity SDK to demonstrate how to use the SDK to load Ready Player Me avatars onto existing player prefabs in both First Person and Third Person setups.

This guide will help you:

• Import the sample from Unity Package Manager

• Open and run the sample scene

• Customize the avatar by editing the Sample Avatar Loader component

📦 Importing the Sample

1. Open your Unity project.

2. In the Unity Editor toolbar, go to: Window > Package Manager

3. Locate the Player Zero SDK package.

4. Click the arrow to expand the package details.

5. Scroll to the bottom and click Import into Project under QuickStart sample.

After import, you'll find the sample under:

Assets/Samples/Player Zero SDK/<version>/QuickStart/

🗺️ Running the Sample Scene

Once imported:

1. Navigate to: Assets/Samples/Player Zero SDK/<version>/QuickStart/

2. Open the appropriate sample scene:

   • FirstPerson/PlayerZeroFP.unity

   • ThirdPerson/PlayerZeroTP.unity

3. Press Play in the Unity Editor.

You’ll see a player character with a Ready Player Me avatar loaded via our SDK.

🛠️ Assigning Your Avatar ID

To load your own avatar:

1. Select the PlayerZeroAvatar GameObject in the scene hierarchy.

   • This may be named something like PlayerZeroAvatarFP , PlayerZeroAvatarTP

2. In the Inspector, locate the Sample Avatar Loader component.

3. Set the Avatar ID field to your personal or test avatar ID.
4. Press Play again. The scene will load the avatar linked to the ID you provided.

✅ Tip: You can obtain an avatar ID by creating one via the Player Zero Avatar Creator or API.

The Player Zero platform allows players to form pre-game lobbies with their friends, then launch your Unity game together with synchronized session data.

When a host starts the game from the Player Zero website, the game is launched with metadata that helps your game:

• Identify the lobby (lobbyId)

• Determine who is the host (host)

• Match all players to the correct region (region)

This page explains how to read this data inside your Unity project and use it to connect all players to the same multiplayer session, especially when using a networking solution like Photon.

🧩 What Player Zero provides to your game

When the game is launched from a Player Zero lobby, the following parameters are passed:

🛠️ How to use this in Unity

The Player Zero SDK includes a helper class called ZeroLobby that makes it easy to retrieve lobby data passed from the Player Zero platform.

You can use it to:

• Check if lobby data is available LobbyQueryHandler.CheckForLobby()

• Get the lobby ID LobbyQueryHandler.LobbyId

• Check if the player is the host LobbyQueryHandler.IsHost

• Get the region of the host LobbyQueryHandler.HostRegion

Call LobbyQueryHandler.CheckForLobby() early in your game's startup flow to initialize and apply the correct values.

For example you might have a NetworkManager class that checks for a lobby in the Start function.

using PlayerZero.Runtime;
public class NetworkManager 
{

    private void Start()
    {
        if(LobbyQueryHandler.CheckForLobby())
        {
            //Lobby parameters found, setup in game network room or lobby
        }
    }
}

1. Use lobbyId as your room name

This ensures that all players connect to the same room or lobby.

PhotonNetwork.JoinOrCreateRoom(LobbyQueryHandler.LobbyId, new RoomOptions(), TypedLobby.Default);

2. Use LobbyQueryHandler.IsHost to determine role

If LobbyQueryHandler.IsHost == true, the player should create the room. Otherwise, they should join the room.

if (LobbyQueryHandler.IsHost) //host will create room while others will join room
{
    PhotonNetwork.CreateRoom(LobbyQueryHandler.LobbyId, new RoomOptions(), TypedLobby.Default);
}
else
{
    PhotonNetwork.JoinRoom(LobbyQueryHandler.LobbyId);
}

3. Use region to connect to the correct server

Photon normally selects a region based on the player's location. You'll want to force all players to use the host's region to prevent mismatched rooms.

PhotonNetwork.PhotonServerSettings.AppSettings.FixedRegion = LobbyQueryHandler.HostRegion;
PhotonNetwork.ConnectUsingSettings();

4. Optionally send players back to Player Zero after the game ends

If you're building a WebGL game, the SDK includes a function that allows you to return players back to the Player Zero lobby after a game session ends

To trigger this behavior from your Unity code, call the following method:

// playerScore is an int value that represents the players score.
// the score is used to determine which member of the lobby is the "winner" of the game
// if score is not applicable to your game then you can just send 0
PlayerZeroSDK.SendBackToPlayerZero(playerScore);

Calling this will exit the game view and return the player to the Player Zero lobby interface.

Summary

By using lobbyId, host, and region, you can ensure:

• All players join the same room

• The correct player creates the room

• Everyone connects to the same region

This approach ensures a consistent multiplayer experience across all participants, especially when using cloud-based networking solutions like Photon.

Introduction

Deep linking allows your application to respond to external URLs and launch directly into specific content or actions within the app. This is particularly useful for experiences like loading user-specific avatars or jumping into a custom scene from a shared link. Our SDK supports deep linking across mobile platforms (Android and iOS) as well as desktop platforms (Windows and macOS). This guide will walk you through enabling and handling deep links in your Unity project using our SDK.

Mobile Deeplinking Setup

When it comes to sending avatars created in our PlayerZero web platform the simplest way to send them to a mobile application is by passing data via deep linking. Unity supports deeplinking and the steps described below can also be found in the Unity documentation here. 🎥 Prefer to watch instead? This short video (2 minutes) walks you through how to set up mobile deep linking using the PlayerZero SDK in Unity on both Android and iOS.

Android

To enable deeplinking for Android you can use an intent filter. The process is as follows:

1. In Unity navigate to Edit > Project Settings > Player

2. In the Android settings tab, expand the Publishing Settings section

3. In the Build section, enable Custom Main Manifest. This creates a new file called AndroidManifest.xml in Assets/Plugins/Android.

4. In the Project window, go to Assets > Plugins > Android and open the AndroidManifest.xml file

5. Add the following code sample inside the Unity<activity> element, named com.unity3d.player.UnityPlayerGameActivity or com.unity3d.player.UnityPlayerActivity, and save the file.

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="playerzero0000" android:host="playerzero" /> 
</intent-filter>

iOS

To enable deeplinking for iOS it is even simpler, the process is as follows.

1. Go to Edit > Project Settings > Player > Other Settings > Configuration.

2. Expand Supported URL schemes to set the following properties:

   • Size property to 1.

   • Element 0 property to the URL scheme to use with your application. For example, use playerzero0000 to open your application when the device processes a link that starts with playerzero0000://.

Desktop Deeplinking Setup

Windows

To enable deeplinking for desktop applications on Windows we a custom entry needs to be added to the Window registry. Without this it is not possible to trigger the application to launch from a web URL. For more information on Windows registries including how to add and remove them please refer to the Windows documentation.

1. Ensure that you have set your GameID by logging into the Player Zero Developer Window located in the tool bar Tools > Player Zero

2. In your first scene add an empty GameObject and add the component DesktopDeepLinkSetup.

3. If you look in the components inspector the SetupOnStart property will be enabled by default. If enabled this means that when this scene is run it will automatically create a custom Windows registry that will enable us to launch the application from a web URL.

MacOS

The deeplinking setup process for MacOS is exactly the same as for iOS. In any case you can find the steps below.

1. Go to Edit > Project Settings > Player > Other Settings > Configuration.

2. Expand Supported URL schemes to set the following properties:

   • Size property to 1.

   • Element 0 property to the URL scheme to use with your application. For example, use playerzero0000 to open your application when the device processes a link that starts with playerzero0000://.

Loading avatars via Deeplink

Now that we have enabled deeplinking we can make use of the PlayerZeroSdk.OnHotLoadedAvatarIdChanged event.

Lets create a new C# script and call it DeepLinkingSample.

First we will create a load avatar function that uses our PlayerZeroSDK functions to request, download and instantiate the character model.

 public class DeepLinkingSample : MonoBehaviour {    

    public async Task LoadAvatar(string avatarId)
    {
        var response = await PlayerZeroSdk.GetAvatarMetadataAsync(avatarId);
        var characterRequestConfig = new CharacterRequestConfig()
        {
            AvatarId = avatarId,
            AvatarUrl = response.ModelUrl,
            BlueprintId = response.BlueprintId,
            Parent = transform
        };

        var avatarGameObject = await PlayerZeroSdk.InstantiateAvatarAsync(characterRequestConfig);
    }
}

Now we can create a new function that uses the PlayerZeroSDK.HotLoadedAvatarId() to get the avatarId.

public void LoadHotLoadedAvatar()
{
    LoadAvatar(PlayerZeroSdk.GetHotLoadedAvatarId());
}

Now you can use the LoadHotLoadedAvatar() function whenever you want to load the avatar.

Alternatively you can subscribe to the PlayerZeroSdk.OnHotLoadedAvatarIdChanged event which is automatically triggered whenever a new avatar id has been detected.

To do this lets we can use the Awake function subscribe to the OnHotLoadedAvatarIdChanged event and assign a new function that loads the avatar.

private void Awake()
{
    PlayerZeroSdk.OnHotLoadedAvatarIdChanged += OnHotLoadedAvatarIdChanged;
}

private void OnHotLoadedAvatarIdChanged(string avatarId)
{
    LoadAvatar(avatarId);
}

Don't forget to unsubscribe to the event

private void OnDestroy()
{
    PlayerZeroSdk.OnHotLoadedAvatarIdChanged -= OnHotLoadedAvatarIdChanged
}

Below you can find the full sample script.

using System.Threading.Tasks;
using PlayerZero.Runtime.Sdk;
using UnityEngine;

public class DeepLinkingSample : MonoBehaviour
{
    private void Awake()
    {
        PlayerZeroSdk.OnHotLoadedAvatarIdChanged += OnHotLoadedAvatarIdChanged;
    }
    
    private void OnDestroy()
    {
        PlayerZeroSdk.OnHotLoadedAvatarIdChanged -= OnHotLoadedAvatarIdChanged;
    }
    
    private void OnHotLoadedAvatarIdChanged(string avatarId)
    {
        LoadAvatar(avatarId);
    }
    
    public void LoadHotLoadedAvatar()
    {
        LoadAvatar(PlayerZeroSdk.GetHotLoadedAvatarId());
    }
    
    public async Task LoadAvatar(string avatarId)
    {
        var response = await PlayerZeroSdk.GetAvatarMetadataAsync(avatarId);
        var characterRequestConfig = new CharacterRequestConfig()
        {
            AvatarId = avatarId,
            AvatarUrl = response.ModelUrl,
            BlueprintId = response.BlueprintId,
            Parent = transform
        };

        var avatarGameObject = await PlayerZeroSdk.InstantiateAvatarAsync(characterRequestConfig);
    }
}

Prerequisites

• You should have been in contact with a member of the Player Zero team.

• If you intend to use your own existing character proportions and rig with P0 visuals applied on top, then you should have sent us your base character FBX so we can setup a custom blueprint for you. Note: this is not required if you intend to use the default P0 proportions and P0 rig in your game.

• You have should have received confirmation from Player Zero that your account is setup, and you should've been given your Player Zero developer account credentials and/or blueprint id.

Step 1: Load a Player Zero avatar's metadata

Using the example http call below, you cantry to test out loading a Player Zero avatar's metadata. You can use any avatar ID, including ones from the playerzero.readyplayer.me platform, or from any test avatar ids we have provided to you.

```
GET https://api.readyplayer.me/v1/characters/:avatarId
```
Example Response:
{
    "data": {
        "id": "avatarId",
        "userId": "userId",
        "applicationId": "applicationId",
        "blueprintId": "blueprintId",
        "assets": {
            "iris": [
                "irisId"
            ],
            "sclera": [
                "scleraId"
            ],
            "hair": [
                "hairId"
            ],
            "eyebrows": [
                "eyebrowsId"
            ],
            "lipshape": [
                "lipshapeId"
            ],
            "eyeshape": [
                "eyeshapeId
            ],
            "faceshape": [
                "faceshapeId"
            ],
            "top": [
                "topId"
            ],
            "bottom": [
                "bottomId"
            ],
            "footwear": [
                "footwearId"
            ],
            "piercing": [],
            "tattoo": [],
            "eyeliner": [],
            "blemish": [],
            "scar": [],
            "foundation": [],
            "lipstick": [],
            "blush": [],
            "eyeshadow": [],
            "sticker": [],
            "cloth": [],
            "freckles": [],
            "sunburn": [],
            "vitiligo": [],
            "teeth": [],
            "attachment": []
        },
        "colors": {
            "skin": "#B06B45",
            "lips": "#C97B7B",
            "hair": {
                "primary": "#191919",
                "secondary": "#583C2F"
            },
            "beard": {
                "primary": "#2e201a",
                "secondary": "#543f36"
            },
            "eyebrows": {
                "primary": "#4B3329",
                "secondary": "#715447"
            },
            "eye": "#9d6937",
            "eyeshadow": {
                "primary": "#0c0804"
            }
        },
        "createdAt": "2025-02-22T13:32:59.906Z",
        "updatedAt": "2025-02-22T13:32:59.906Z",
        "username": "anonymous",
        "modelUrl": "https://avatars.readyplayer.me/:avatarId.glb",
        "iconUrl": "https://avatars.readyplayer.me/:avatarId.png"
    }
}

Step 2: Load a Player Zero avatar

Using the modelUrl from the response in step 1, you can make a GET request to that to download the Player Zero avatar GLB. You can also optionally pass a blueprintId as a query parameter to load a version of the Player Zero avatar that matches the proportions and rig of a given blueprint.

```
GET https://avatars.readyplayer.me/:avatarId.glb?targetBlueprintId=:blueprintId
```

Example Response:

.GLB file download response

Step 3: Hot load an avatar

On the Player Zero platform, avatar ids will be provided to you as a query param in the url that loads the game. In order to hot load an avatar you need to take this avatar id from the url, and pass it to the endpoint in step 1 in order to successfully hot load an avatar. An example of a game url on the Player Zero platform would be the below.

https://playerzero.readyplayer.me/games/my-great-game?avatarId=AVATAR_ID_HERE

Step 4: Optimize your avatar

The Player Zero APIs support a range of optimization query parameters that enable you to maximize the performance of your avatars for different use-cases. Below are the available parameters that you can add to https://avatars.readyplayer.me/:avatarId.glb API calls.

Step 5: Send some game events

As part of your partnership with Player Zero, it is crucial that you we receive accurate game events from you about how Player Zero players are using your game. For this we provide a game events endpoint which you can call to provide information about player sessions.

```
POST https://api.readyplayer.me/v1/public/events
```

Example Payload:
{
    "data": {
        "event": "avatar_session_ended",
        "properties": {
            "avatar_session_id": "AVATAR_SESSION_ID"
        }
    }
}

Example Response:
{
    "data": {
        "event": "avatar_session_ended",
        "properties": {
            "avatar_session_id": "AVATAR_SESSION_ID"
        }
    }
}

There are a range of events that we required you to send to this endpoint in different scenarios. These are detailed below.