Unity Integration

A step by step guide to integrate the Player Zero SDK into your game

Note: these docs are still early access and partially incomplete

🎥 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.

If any of the above prerequisites are not true, please reach out to us before continuing.

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.

Making sure you have set your GAME ID in tools -> Player Zero, otherwise you will see an error and player sessions will not be captured

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

Important: If you're sending custom analytics events manually (not using the PlayerZeroAnalytics component), you must send the full set of required events to ensure session tracking and payouts work properly: – GameSessionStartedEvent

– AvatarSessionStartedEvent

– AvatarSessionHeartbeatEvent

– AvatarSessionEndedEvent

– GameSessionEndedEvent

Missing any of these will result in uncaptured sessions and missed payouts.

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