Avatars

An avatar is a stack of sprite sheets, one per part, that the client draws over each other at the player's position. A tenant's catalogue lists the sheets its members may wear: the built-in ones and those the tenant adds.

Sprite sheets

A sheet is a PNG image of 96 × 128 pixels: frames of 32 pixels square, three to a row and a row per direction.

A walking avatar shows the frames of its row in the order 1, 2, 3, 2, ten a second; a standing one shows the middle frame. The bottom middle of a frame stands on the player's position, the point under its feet (Map format). Pictures in the user interface show the standing frame facing down.

Parts

The client draws them in this order, the body at the back. An avatar wears one texture of a part at most, and a body always.

Catalogue

GET /api/v1/avatars lists the parts in drawing order, each with its collections and their textures: an id, a name and the URL of the sheet. The tenant's own textures come first, then the built-in ones. The catalogue also names a fallback, which the client draws for an avatar whose sheets fail to load: a body, eyes and plain clothes.

Sheets are served at GET /api/v1/avatar-textures/<file> under names that carry their content hash, so browsers keep them for a year.

Built-in textures

The built-in textures are drawn by the product's own code when the process starts: six bodies, four eyes, six outfits, six hair styles, three hats and three accessories in the collection Basics. They need no image files. Their ids, such as body-3, stay the same from release to release. Their names and the collection's come from the server's catalogues, in the language of the request (Languages); the tenant's own textures keep the names their admins gave them.

Tenant textures

A tenant's admins add textures with POST /api/v1/admin/avatars?part=…&collection=…&name=…, the sheet as the body with Content-Type: image/png, up to 256 KiB; the answer carries the texture's id, a UUID. GET /api/v1/admin/avatars lists the textures the tenant added, part by part in drawing order, and DELETE /api/v1/admin/avatars/{texture} removes one, and avatars that wore it go on without it. The images live in object storage under tenants/<tenant id>/avatars/ with a file_object row of kind avatar_texture, and every change goes to the audit log.

A tenant whose builtInAvatars flag is off (Tenancy) offers only its own textures; the fallback stays built in.

Companions

A companion is a small animal that follows a player's avatar. Its sheet is laid out as a texture's, the animal standing on the bottom of each frame. The product draws six when the process starts: cat, dog, fox, rabbit, owl and turtle. Every tenant offers them, whatever its builtInAvatars flag, and tenants add none. Their names come from the server's catalogues (companion.<id>). The catalogue lists them under companions, each with its id, name and the URL of its sheet, which is served as the textures' are.

Wearing an avatar

• An account keeps the ids of what it wears in app_user.avatar, with the id of its companion when it has one. A first visit picks its avatar and companion before it has an account and sends them with POST /api/v1/auth/anonymous; anyone signed in changes them with PUT /api/v1/me/avatar. Both check the ids against the tenant's catalogue and store the textures in drawing order, and both refuse an unknown texture or companion, two of a part or a missing body with 400.
• GET /api/v1/me answers the textures the account wears and its companion; an account that wears nothing, or whose textures are all gone, wears the fallback.
• The gateway reads the account's avatar when a connection opens and resolves it to texture ids and URLs, with its companion's, which RoomUser.avatar carries to everyone in the room; a companion the catalogue no longer has is left out. A changed avatar shows from the player's next connection: the client connects again after saving it.