Direct API Integration

A step by step guide to integrate Player Zero into your game via our APIs

Note: these docs are still early access and partially incomplete

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.

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

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.

Parameter	Type	Description
quality	String	low, medium or high - Use quality presets to combine performance related parameters.
textureSizeLimit	Int	Sets the upper limit for texture resolution in pixels of any texture in the avatar.
textureAtlas	Int	Generates a texture atlas of the desired resolution. The operation merges all meshes and splits opaque objects from transparent ones resulting in a maximum of 2 draw calls.
textureFormat	String	Reduce avatar file size by formatting all textures into the specified format. Using webp encoding can result in up to 40% reduction in avatar file size. Supported values: webp, jpeg, png
morphTargets	String	Comma-separated list of individual morph targets or morph target standard groups to include on the avatar.
textureQuality	String	Choose which texture quality preset to get on the avatar. Options are 'low', 'medium', or 'high'.
meshCompression	Boolean	Whether or not to use mesh compression.
textureChannels	String	Define which textureChannels should be included in the .glb. It can be a comma-separated combination of the following values: baseColor, normal, metallicRoughness, emissive, occlusion.
meshLOD	Int	Control the triangle count of the assets equipped on the avatar.
targetBlueprint	String	The blueprint that the avatar should confirm to. This dictates the rig and the character proportions.
removeSkin	Boolean	Whether or not we should automatically remove parts of the avatar's skin mesh that is covered by clothing.

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.

Event	Required Properties	When to send
user_game_session_started	avatar_id: String game_session_id: String game_id: String	When your game launches, or a player starts playing.
user_game_session_ended	game_session_id: String game_id: String	When a player exits your game, or your game stops for any reason.
avatar_session_started	avatar_id: String avatar_session_id: String game_session_id: String game_id: String	When a player starts using their Player Zero avatar in your game.
avatar_session_heartbeat	avatar_session_id: String game_id: String	Fire one event for every minute that a player is using their Player Zero avatar in your game.
avatar_session_ended	avatar_session_id: String game_id: String	When a player stops using their Player Zero avatar in your game, or your game stops for any reason.