Personalisation
Profile pictures, borders and backgrounds a fan owns, and equipping them per community.
The cosmetics a fan collects, and the picker where they show them off.
Personalisations
A personalisation is a cosmetic a fan can equip. Three kinds exist, and a fan wears one of each at a time:
kind | What it is |
|---|---|
pfp | Profile picture |
border | A frame around the avatar |
background | A profile backdrop |
Fans get them as quest rewards, from loot boxes, from the battlepass and from the store. Owning one does not equip it. That is the fan's choice, in your picker.
Per community
Equipping is per community. A fan's animated border in one community is not their border in another, and choosing one here never changes what they wear there. Every read and write on this page is scoped to your community.
What a fan owns
import { useEquippedPersonalization, usePersonalizations } from '@xborglabs/fanbase-react'
const { data: owned } = usePersonalizations({ ownedOnly: true, kind: 'pfp' })
const { data: equipped } = useEquippedPersonalization()usePersonalizations lists them, filtered by kind. Each row carries isOwned, isEquipped and its art in mediaPath. Leave ownedOnly off to show the locked ones as well, which is a good way to show fans what is left to earn.
useEquippedPersonalization is what the fan is wearing now: equipped.pfp, equipped.border and equipped.background, each with a mediaUrl. Use it anywhere you draw their avatar.
Both resolve your community from the slug on FanbaseProvider.
The picker
Let the fan try things on, then save once. Hold their choices in your own state as a draft, and send the whole draft together:
import { useBatchEquipPersonalizations, useResolvedCommunityId } from '@xborglabs/fanbase-react'
function SaveButton({ draft }) {
const containerId = useResolvedCommunityId()
const { batchEquip, isPending } = useBatchEquipPersonalizations()
return (
<button
disabled={!containerId || isPending}
onClick={() =>
batchEquip({
containerId,
items: [
{ kind: 'pfp', personalizationId: draft.pfp },
{ kind: 'border', personalizationId: draft.border },
{ kind: 'background', personalizationId: draft.background },
],
})
}
>
Save
</button>
)
}The batch is all or nothing, so a fan never ends up half changed. The equipped set refreshes on its own afterwards.
Writes need the community id, which useResolvedCommunityId gives you. Keep the button disabled until it is there.
Taking one off
A personalizationId of null takes that kind off:
batchEquip({ containerId, items: [{ kind: 'border', personalizationId: null }] })There is no "remove everything" call. To clear all three, send all three as null.
For a single change with no draft, like an "Equip" button on a reward the fan just won, useEquipPersonalization and useUnequipPersonalization do one kind at a time.
After a purchase or a reward
A personalisation bought in the store comes back as its own outcome, with the item's id, which is the moment to offer "Equip now". After a purchase.
The same goes for a personalisation won from a quest. It is in their inventory the moment the claim goes through.
Checklist
- The picker lists what the fan owns, by kind
- Locked personalisations show what is left to earn, if you want that
- Saving sends one batch, not one call per kind
- Setting a kind to
nulltakes it off - The avatar everywhere reads from
useEquippedPersonalization - Choices in one community never show up in another