> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/avatars/how-to-create-an-avatar.md).

# How to create an avatar

Avatar Studio can turn a rigged character into an avatar. Clothing textures are on [How to paint avatar clothing](https://studio-docs.sandbox.game/avatars/how-to-paint-avatar-clothing.md). A 3D accessory, such as a hat, is on [How to create an avatar accessory](https://studio-docs.sandbox.game/avatars/how-to-create-an-avatar-accessory.md).

A platform avatar is separate from the mesh on a pawn. That setup is [How to import a rigged character and animation clips](https://studio-docs.sandbox.game/the-editor/how-to-import-a-rigged-character-and-animation-clips.md). It is also separate from a Cosmetic you sell inside a game. Those items are on [What you can sell](https://studio-docs.sandbox.game/monetization/what-you-can-sell.md).

## Open Avatar Studio

Open the hamburger menu at the top left and choose **Avatar Studio...**. Choose **Create Avatar**, enter a name, and select **Create**.

The file is `.avatar.json`, under `assets/avatars/`. To reopen it, select it under **Open Recent**, or double-click it in the project.

## Create an avatar from your own mesh

Rig the character in Blender with the Sandbox Rigify add-on before you start. **Export** writes one `.glb` for the whole character. **Export Parts** writes one `.glb` per body slot.

### Step 1: Import the mesh

On **Import**, drop the files on the drop zone, or click it to choose them. Drop `character.glb` for the whole character, or one file per part, such as `Head.glb` and `UpperTorso.glb`. Each file fills one of 15 slots. To replace one part, export that part again and drop it.

<figure><img src="https://2877193296-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWgFjStdWWXj1Wc6xnrcJ%2Fuploads%2Fgit-blob-52d589cb3b1452571c3069598a8617dc121776be%2Favatar-studio-import.png?alt=media" alt="Import step with all 15 body parts imported"><figcaption><p><em>All 15 parts are imported. The drop zone takes one character file, or one file per body part.</em></p></figcaption></figure>

The 15 slots are the body parts in the exported folder:

|                     |                     |                  |
| ------------------- | ------------------- | ---------------- |
| `Head.glb`          | `UpperTorso.glb`    | `LowerTorso.glb` |
| `LeftUpperArm.glb`  | `LeftLowerArm.glb`  | `LeftHand.glb`   |
| `RightUpperArm.glb` | `RightLowerArm.glb` | `RightHand.glb`  |
| `LeftUpperLeg.glb`  | `LeftLowerLeg.glb`  | `LeftFoot.glb`   |
| `RightUpperLeg.glb` | `RightLowerLeg.glb` | `RightFoot.glb`  |

**Clear Import** empties the slots so you can drop the files again.

### Step 2: Validate the rig

Open **Validate**. A ready avatar fits the Sandbox rig and moves with the platform animations. The checks cover the body parts, skinned meshes, the Sandbox rig, finger bones, size, face, and the **Hat** socket. Each problem tells you how to fix it in Blender.

**Try Expressions** plays **Neutral**, **Happy**, **Sad**, **Angry**, and **Blink**.

<figure><img src="https://2877193296-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWgFjStdWWXj1Wc6xnrcJ%2Fuploads%2Fgit-blob-3c0076e55e85212670db66f168eb036daf2a8456%2Favatar-studio-validate.png?alt=media" alt="Validate step ready, with Try Expressions under the checks"><figcaption><p><em>Validate reads Ready. This avatar has 53 of 53 face expressions.</em></p></figcaption></figure>

{% hint style="info" %}
A missing ARKit face does not block the avatar. The face still renders. Expressions are what you lose.
{% endhint %}

### Step 3: Map the surfaces

Open **Surfaces**. Map each material to a platform surface, or leave it as it is. The surfaces are **Body**, **T-Shirt**, **Sleeves**, **Shorts**, **Legs**, and **Shoes**. Common names are filled in for you. Select the avatar to find the material under the cursor.

Check the UV match. **Template** saves the platform UV layout as a PNG to unwrap against.

<figure><img src="https://2877193296-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWgFjStdWWXj1Wc6xnrcJ%2Fuploads%2Fgit-blob-6a43a7bf8deeb7cec330751fa1be75313e48f61e%2Favatar-studio-surfaces.png?alt=media" alt="Surfaces step with all six platform surfaces mapped and the T-Shirt UV layout shown"><figcaption><p><em>Surfaces reads 6 of 6 mapped. The T-Shirt UV layout is on the right.</em></p></figcaption></figure>

### Step 4: Try on a platform outfit

**Try On** is optional. Pick an outfit and an accessory to see them on this avatar.

<figure><img src="https://2877193296-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWgFjStdWWXj1Wc6xnrcJ%2Fuploads%2Fgit-blob-13e7d7722b91341dc028080918413f44322885c0%2Favatar-studio-try-on.png?alt=media" alt="Try On step with Long Sleeves, Short Pants and headphones on the Hat socket"><figcaption><p><em>Long Sleeves, Short Pants is selected. Headphones are on the Hat socket.</em></p></figcaption></figure>

| Outfit                     | Parts |
| -------------------------- | ----- |
| Long Sleeves, Short Pants  | 8     |
| Long Sleeves, Long Pants   | 8     |
| Short Sleeves, Short Pants | 6     |
| Short Sleeves, Long Pants  | 6     |

{% hint style="info" %}
This step is a preview. It does not move sockets. Move a socket in Sandbox Rigify, then export the character again.
{% endhint %}

### Step 5: Paint a skin on this avatar

**Skins** is optional. Painting here works the same way as [How to paint avatar clothing](https://studio-docs.sandbox.game/avatars/how-to-paint-avatar-clothing.md), on the surfaces you mapped.

### Step 6: Export the avatar

Open **Export**. Name the avatar, and fix anything that step lists as blocking. Then select **Export Avatar...**.

You get one folder. `parts/` holds one `.glb` per body slot. `recipes/` holds a parts recipe, named from the avatar. If you painted a skin, that skin is in the folder too.

<figure><img src="https://2877193296-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWgFjStdWWXj1Wc6xnrcJ%2Fuploads%2Fgit-blob-926b215a5f400a34874e3629d23a4c80d2ccdcd0%2Favatar-studio-export-folder.png?alt=media" alt="Exported avatar folder with 15 part glb files and a parts recipe"><figcaption><p><em>Dorothy/parts holds the 15 body parts. Dorothy/recipes holds Dorothy-parts.recipe.json.</em></p></figcaption></figure>

## What you've done

The avatar is exported. To paint clothing textures, follow [How to paint avatar clothing](https://studio-docs.sandbox.game/avatars/how-to-paint-avatar-clothing.md). To add a hat or another 3D accessory, follow [How to create an avatar accessory](https://studio-docs.sandbox.game/avatars/how-to-create-an-avatar-accessory.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://studio-docs.sandbox.game/avatars/how-to-create-an-avatar.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
