Avatars

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 isWhere it shows
AvatarThe full-body character, built from wearablesA profile page, an avatar editor
Profile pictureA flat image, with an optional borderNext 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 fieldMeans
nameWhat to call it in your UI
slugA stable name for code, like headgear or boots
defaultItemIdWhat the slot wears when the fan has chosen nothing
allocatedItemWhat it is wearing now
editableValueWhether the fan can change it
requiredWhether 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.

rarityDisplay string
common, rare, epic, elite, heroic, legendary, mythicInventory.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.

ItemLocked when
Private, the usual kindThe fan does not hold one
PublicOnly 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

SourceCovered in
A store listingStore
A quest rewardRewards and claims
An event prize, or a loot box won in oneResults 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.

RenderWhen
3DEvery item the avatar is wearing has a 3D model, and the browser can draw it
2DAnything 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

PageCovers
Rendering an avatarThe 2D stack, the 3D scene, the camera, a downloadable picture
The avatar editorSlots, the item grid, locks, the draft, saving, another fan's avatar

On this page