How avatars work in games · Learn

On NEO a player designs one character and plays it in every game. This page explains what an avatar is made of, how players edit it, and how a game built on the NEO engine's gameplay kit puts it on the player's character. If you make avatar items, it also shows where hats, shirts and emotes fit in.

What an avatar is#

An avatar is a small record stored by the platform, the same everywhere: the Avatar message of the platform API's AvatarService. A game or tool reads it as JSON.

Field	What it holds
`base`	The 3D base body. The default is `mannequin`, the stylised body the templates use.
`proportions`	Seven factors on the base body, where 1.0 is the base itself (below).
`tints`	A `#rrggbb` colour per part: `skin`, `shirt`, `pants`, `hair` and `eyes`. `skin` is the skin tone.
`body`	The 2D body type used for headshots: `classic`, `slim`, `sturdy` or `round`.
`wornItemIds`	The hats and shirts the player wears, in layer order. Players can only wear items they own.
`emotes`	Emote items by slot, 1 to 8.

Proportions#

Proportions change the body by scaling bone lengths. The platform accepts only these ranges, and at these ranges the character's animations stay planted on every body:

Factor	Range	What it scales
`height`	0.8 to 1.2	Every bone length
`head`	0.8 to 1.3	The head (a visual scale)
`torso`	0.85 to 1.15	The spine, neck and head offset
`arms`	0.85 to 1.15	Forearms and hands
`legs`	0.85 to 1.15	Calves, feet and pelvis height
`shoulders`	0.8 to 1.25	Upper arms
`hips`	0.85 to 1.2	Thighs

A factor left unset counts as 1.0. A value outside its range is refused when saving.

One animation set works on every body because the engine fits each animation to the body's bone lengths as it plays: feet land where the animation puts them, whatever the leg length.

The avatar editor#

Players edit their avatar at /avatar.

The 3D editor at the top of the page is a real NEO scene: the avatar is a game character, animated by the engine. Its panel has:

Body: the base body;
Proportions: one slider per factor, and Reset proportions;
Skin: the skin tone palette;
Preview: Idle, Walk, Run, Crouch and Jump, which drive the character's own movement;
Save avatar.

Edits apply to the character as you make them. Drag the view to orbit and scroll to zoom.

Below it, under Items and emotes, the rest of the avatar: Body (the 2D body type), Colors (skin, shirt, pants, hair and eyes, from presets or a custom colour), Hats, Shirts and Emotes (fill the eight slots with emotes you own). Save avatar saves these. When the 3D editor isn't available, this panel is the whole editor.

The two parts don't overwrite each other: saving from one keeps the fields the other one edits.

Headshots#

The platform draws each player's headshot from their saved avatar. It shows the skin, hair and eye colours, the shirt colour, worn hats, the body type, and the shoulder and head proportions. Headshots appear across the platform (friends, chat, servers, profiles) and refresh when the player saves.

Avatars in games#

Games built on the gameplay kit, including every project made from the GASP template, can put the player's avatar on the player's character:

Part of the avatar	What the game does with it
`base`	Picks the model. `mannequin` is the game's own character model.
`proportions`	Rebuilds the character's bone lengths from the model's rest pose, so changes never compound.
`tints.skin`	Paints the mannequin in the skin tone.

If the avatar changes while the game runs, new proportions or colours are rebuilt and repainted in place.

The game reads the avatar when it starts, from the neo_avatar launch parameter: the Avatar JSON, passed in the address (#neo_avatar=…) on the web or the NEO_AVATAR environment variable on the desktop. Without it the player keeps the game's own model.

Reading a player's avatar yourself#

The avatar is public. Any client can read it with AvatarService.GetAvatar and the player's userId; see the avatar API reference. In a multiplayer game, each remote player's platform account is known to the game, so the same lookup works for other players.

Launch parameters#

These are the launch parameters the engine reads for the platform. On the web each is #key=value or ?key=value in the game's address; on the desktop it's the NEO_<KEY> environment variable (neo_api becomes NEO_API).

Key	Value
`neo_api`	The platform API's address.
`neo_token`	A token for the platform API. Embedded editors get a short-lived token scoped to their calls, never the player's own sign-in.
`neo_web`	The embedding page's origin. Messages go only there.
`neo_avatar`	The Avatar JSON. Games apply it at start.
`neo_autostart`	`1` starts a web build as soon as its content is in, with no Play button.