Avatar

An Avatar shows a player's profile photo on an Actor. Avatars are useful for multiplayer player tokens, leaderboard podiums, or anywhere you want to identify a specific user visually.

An avatar is a layer on a drawing, alongside the usual shapes and paint layers. This means you can stack other layers above or below it — for example, a hat painted on top of the photo, or a body painted underneath.

Adding an avatar

The fastest way to add an avatar to your deck is to drag the Avatar blueprint out of the Library — it comes pre-set with a single avatar layer.

To add an avatar to an existing drawing, open the drawing's layers sheet and tap Add Layer → Avatar. Only one avatar layer is allowed per drawing.

Choosing which user to show

By default, an avatar actor shows its owner — in multiplayer, the player who controls the actor; otherwise, the local player. You don't need to do anything to get this behavior.

To show someone other than the owner (for example, the top scorer on a leaderboard), call one of the castle.avatar.* functions from a Lua script:

• castle.avatar.setToCurrentUser(actor) — show the local player's photo.
• castle.avatar.setToOwner(actor) — show the player who controls this actor in multiplayer.
• castle.avatar.setToUser(actor, userId) — show a specific user in the current session by their userId.
• castle.avatar.setToLeaderboardEntry(actor, config, rank) — show the user at a given rank in a cached Leaderboard. Call castle.fetchLeaderboardData first to populate the cache.
• castle.avatar.getUser(actor) — read back who the avatar is currently showing.

-- show the #1 player on the high-score leaderboard
castle.fetchLeaderboardData({ variable = "score", type = "high" }, function()
  castle.avatar.setToLeaderboardEntry(self, { variable = "score", type = "high" }, 1)
end)

Multiplayer: Persist when player leaves

Avatar actors have an extra option in the Inspector's multiplayer section: Persist when player leaves, and reclaim if they rejoin.

When this is off (the default), the actor is destroyed as soon as the depicted player disconnects. When it is on, the actor stays in the session after the player leaves and is automatically reclaimed by that player if they reconnect — preserving its position and state. This is useful for persistent player tokens that should survive reconnects.