The avatar model
Slots, wearables, the lock rule, and why an avatar is not a profile picture.
What an avatar is made of, and the vocabulary the other two pages use.
An avatar
A full-body character a fan dresses with items they have earned. It is the most visible thing a fan owns in your community, and the reason a wearable is worth more to them than the same number of points.
Wearables are designed and published for your community by the FanBase team, and handed out through the Hub as quest rewards, store items and event prizes. Collectibles in the Hub docs covers that side.
Not the profile picture
Two different things get called an avatar. Keep them apart.
| What it is | Where it shows | |
|---|---|---|
| Avatar | The full-body character, built from wearables | A profile page, an avatar editor |
| Profile picture | A flat image, with an optional border | Next to a fan's name everywhere: leaderboard rows, comments, the header |
The profile picture, its border and the profile background are personalisation. The small picture next to a name is always that, never a render of the avatar.
Slots
An avatar is one item per slot. A slot is a place something can be worn: headgear, upper body, lower body, boots, each hand.
| Slot field | Means |
|---|---|
name | What to call it in your UI |
slug | A stable name for code, like headgear or boots |
defaultItemId | What the slot wears when the fan has chosen nothing |
allocatedItem | What it is wearing now |
editableValue | Whether the fan can change it |
required | Whether it can ever be empty |
The body itself is a slot, with the slug avatar. It is left out of every picker, because a fan does not unequip their own body.
Defaults
Most slots have a default item. That changes what unequip means: taking something off puts the default back on. A fan who removes their jacket is wearing the basic shirt, not nothing.
A slot with no default can be empty. A slot that is required and has no default cannot be emptied at all.
Items
A wearable is an avatar item. It belongs to one slot, has a rarity, and a fan either holds it or does not.
rarity | Display string |
|---|---|
common, rare, epic, elite, heroic, legendary, mythic | Inventory.rarity. followed by the value |
Locked items
An item a fan cannot wear yet is locked. The SDK decides that for you and puts it on every item as isLocked.
| Item | Locked when |
|---|---|
| Private, the usual kind | The fan does not hold one |
| Public | Only when the fan is signed out. Signed in, everyone can wear it. |
Show locked items. A grid of only what a fan already owns gives them nothing to want. The item itself can tell you how to get it: which quests and events hand it out.
Where wearables come from
| Source | Covered in |
|---|---|
| A store listing | Store |
| A quest reward | Rewards and claims |
| An event prize, or a loot box won in one | Results and rewards |
An event claim updates the fan's avatar items on its own. After a store purchase or a quest claim that grants a wearable, refresh them yourself, or the grid will still show the item as locked:
import { invalidateFanbaseAvatarQueries, useFanbase } from '@xborglabs/fanbase-react'
const { meta } = useFanbase()
invalidateFanbaseAvatarQueries(meta.queryClient)3D first, 2D behind it
Every wearable has a flat image. Most also have a 3D model. The SDK renders both.
| Render | When |
|---|---|
| 3D | Every item the avatar is wearing has a 3D model, and the browser can draw it |
| 2D | Anything else: one item without a model, no 3D graphics support, or the 3D scene failing |
Build the 3D view as the main one and keep the 2D stack as the fallback. A fan never sees a broken canvas that way. Another fan's avatar is always 2D.
The 3D renderer lives on its own import path with its own dependencies, so an app that never shows an avatar pays nothing for it. Rendering an avatar covers the install.
Editing is a draft
Dressing an avatar is not a series of saves. The fan tries things on, the avatar updates in front of them, and nothing is stored until they press save. Then every change goes in one request, all or nothing.
Avatar.Provider holds that draft. It is why one provider has to wrap both the avatar and the item grid: an item equipped in the grid shows on the avatar because they share it.
A community can have avatars off
Not every community uses avatars. When yours does not, the provider says so with AVATAR_DISABLED, and you hide the whole thing: the avatar, the editor, the inventory tab.
The two pages
| Page | Covers |
|---|---|
| Rendering an avatar | The 2D stack, the 3D scene, the camera, a downloadable picture |
| The avatar editor | Slots, the item grid, locks, the draft, saving, another fan's avatar |