Builtin Library
README.md
avatarAnimator
An avatar's parameters, its animator, its expression menu and its own parts, declared as
data in avatar.json (or passed to
asset.create("avatar", name, { parameters, animator, menu, parts })).
The AvatarAnimator component runs them on every peer; the app menu's Expressions tab
shows the menu to the person whose avatar it is.
local avatarAnimator = require("@builtin::modules.avatarAnimator")
local v = avatarAnimator.validate(avatarRef:definition()) -- { ok, problems, syncedBits, summary }
local a = avatarRef:animator() -- the same check, plus the cost
local anim = player.avatar.component.get("AvatarAnimator")
anim:set("Hat", false) -- every peer hides the hat
Parameters
"parameters": [
{ "name": "Hat", "type": "bool", "default": true, "saved": true },
{ "name": "Mood", "type": "int", "default": 0, "saved": true },
{ "name": "EarAngle", "type": "float" },
{ "name": "Blink", "type": "float", "synced": false }
]
| Field | Holds |
|---|---|
name | letters, digits and _, starting with a letter, at most 64 characters |
type | bool (1 bit), int (0 to 255, 8 bits) or float (-1 to 1, 8 bits) |
synced | default true: every peer reads it, through the avatar channel's parameter block |
saved | default false: the person's value returns when they come back (below) |
default | the value it starts at; false or 0 when left out |
The synced parameters take at most 256 bits. A built-in that only the owner's engine can
read (Voice, Viseme, TrackingMode) rides the same block when the animator or the
menu reads it, and counts toward the 256; one nothing reads stays on the owner and reads 0
on every other peer. A synced float travels in steps of 1/127, and the owner holds it at
that value too (avatarAnimator.quantize), so every peer evaluates the same number. An avatar past the budget is refused when it is
created and by validate, which states the overrun:
the synced parameters take 264 bits, 8 over the 256 an avatar carries: ....
Built-in parameters are read-only and every peer reads them: Grounded, Speed,
VelocityX / VelocityY / VelocityZ (metres a second in the avatar's own frame, +Z the
way it faces), Voice (how loud the owner speaks, 0 to 1, while their microphone runs),
Viseme (0 silent, 10 aa while the owner speaks), Emote and EmoteTime (the newest
emote's id for the 10 seconds after it starts, 0 after, and the seconds since it started), IsOwner, TrackingMode (how many of a
headset's head and hands are tracked, 0 with none) and Gait (0 standing, 1 walking,
2 running).
Saved parameters are written into the avatar's appearance document (Appearance), so an
outfit saved on the account carries them into every world, and the values the person sets
themselves from the Expressions tab are kept on their device for this avatar. A value a
script sets (a world's, an agent's) is carried in the document but never written to the
person's device. The avatar starts with the document's values, then the device's. To check
it by hand: play, open the Expressions tab, change a saved parameter, leave and come back.
The animator
"animator": { "layers": [
{ "name": "Gestures", "mask": ["rightArm"],
"states": [ { "name": "Rest" }, { "name": "Wave", "motion": { "clip": "A_Wave" } } ],
"transitions": [ { "from": "Rest", "to": "Wave", "when": "Gesture == 1", "duration": 0.2 },
{ "from": "Wave", "to": "Rest", "when": "Gesture != 1", "duration": 0.2 } ] },
{ "name": "Emotes", "mask": ["upperBody"],
"states": [ { "name": "None" }, { "name": "Dance", "motion": { "clip": "A_Dance", "loop": true } } ],
"transitions": [ { "from": "None", "to": "Dance", "when": "Emote == 3", "duration": 0.2 },
{ "from": "Dance", "to": "None", "when": "Emote != 3", "duration": 0.2 } ] },
{ "name": "Hat",
"states": [ { "name": "On", "motion": { "show": ["Hat"] } }, { "name": "Off", "motion": { "hide": ["Hat"] } } ],
"transitions": [ { "from": "On", "to": "Off", "when": "!Hat", "duration": 0 },
{ "from": "Off", "to": "On", "when": "Hat", "duration": 0 } ] },
{ "name": "Face", "default": "Neutral",
"states": [ { "name": "Neutral" }, { "name": "Happy", "motion": { "shapes": { "happy": 1 } } } ],
"transitions": [ { "from": "*", "to": "Happy", "when": "Mood == 1", "duration": 0.2 },
{ "from": "*", "to": "Neutral", "when": "Mood != 1", "duration": 0.2 } ] }
] }
A layer is a state machine: it starts in default (else its first state), and each
frame takes the first transition out of the state it stands in (or "*", any state) whose
conditions all hold, crossfading over duration seconds (0.15 by default). A transition
with exitTime waits until that fraction of the state's motion has played. A condition is
"Hat", "!Hat" or "Name <op> value" with ==, !=, >, <, >=, <=, or
{ parameter, op, value }. An == or != on a synced float compares with the value the
channel carries for the number written (avatarAnimator.quantize), as a menu item's value
on one is. weight is 0 to 1 or the name of a number parameter; a later
layer overrides an earlier one, by its weight, on whatever both drive. mask names what a
layer may move: bone names, humanoid roles (rightHand) and regions (upperBody, arms,
leftArm, rightArm, head, legs, and face for the blend shapes alone), resolved
through the body's rig; head and upperBody take the face's blend shapes too. A layer
with no mask moves the whole body and face.
Every peer evaluates on the session clock, and a state plays from the moment it was entered:
the moment its transition's conditions came to hold, dated as the avatar channel dates the
parameters they read (the frame that first carried each value, multiplayer.avatarState(e) .parametersAt), an emote by its start time (EmoteTime < x by that start too, and
EmoteTime >= x by x seconds after it), an exitTime by the point the motion reached it.
The owner, which sets a parameter before the channel sends it, starts the state again at
the date the channel gives it, within a parameter send interval, so the owner and every
other peer play a clip or keyframes at the same point at every moment. A peer that starts
drawing the avatar while a state already runs starts that state as it reads it.
A state's motion is one of:
- a pose:
shapes({ name = weight }: a blend shape, or a standard expression preset the avatar'sexpressionsmap names),bones({ bone = { rotation = [x, y, z] degrees or { x, y, z, w }, position = [x, y, z] metres } }, added over the animation already moving the bone),showandhide(parts),data({ part, lane 0 to 3, value = [x, y, z, w] }, the shader data lanes of the part's meshes); - keyframes:
{ length, loop?, speed?, keys = { { t, <pose> }, ... } }, interpolated between keys; - a clip:
{ clip = "A_Wave", loop?, speed? }, an.animation(its identity, or{ __ref = guid };A_WaveandA_Dancein these examples stand for clips the world holds, and the engine's own humanoid clips are its locomotion set, such asA_Idle_Standing_MascandA_Jump_Idle_Masc, which play on any humanoid body) played on the body under the layer'smaskandweight, over the locomotion beneath it, bones and blend shapes alike (looptrue by default; false plays it once and holds its last frame;speed1 at its authored timing). It crossfades with the layer's transitions like any motion, stands in a blend beside poses and other clips at its share of the blend, and anexitTimeon its state waits for that fraction of the clip.Emotenames an emote for the 10 seconds after it starts, so an emote clip that plays once bounds its state byEmoteTime: in by{ "Emote == 3", "EmoteTime < 1.5" }, out by"EmoteTime >= 1.5"or"Emote != 3", 1.5 being the clip's length; - a blend:
{ blend = "Param", motions = { { at = 0, motion = ... }, { at = 1, ... } } }between the two motions either side of the parameter, orblend = ["X", "Y"]withat = [x, y]for a 2D blend.
A name in bones, show, hide or data is any entity under the avatar root: a bone of
the body, a part the avatar declares, or anything else seated on it. A bone a running
animation moves (locomotion) turns on top of that animation; any other entity turns and moves
from where it was seated. An attachment point's name (hat, waistBack, ...) names every
item seated there, the appearance's worn items included.
Parts
"parts": [
{ "name": "Hat", "mesh": "@builtin::meshes.cone", "point": "hat", "position": [0, 0.05, 0], "scale": 0.25 },
{ "name": "Tail", "mesh": "@builtin::meshes.cylinder", "point": "waistBack", "rotation": [70, 0, 0], "scale": [0.08, 0.3, 0.08] }
]
The avatar's own pieces beyond its body: each a mesh seated on an attachment point of the
body (hat, faceFront, waistBack, rightGrip, ... see avatarStandard.points), at
position (metres), rotation ([pitch, yaw, roll] degrees) and scale (a number or
[x, y, z]) in the point's frame, drawn with material (an identity or { __ref }) and
tinted color ("#rrggbb" or [r, g, b]). Every peer seats its own copy, and seats it again
when the body changes. The animator drives a part by its name: hide = { "Hat" },
bones = { Tail = { rotation = ... } }. A part turns about the point it is seated on (its
mesh, <name>Mesh, hangs from it at position), so a cylinder placed half its length back
from waistBack swings from the hips like a tail. The point's frame is the body's in a T-pose:
+Y up, +Z the way the body faces, +X its left.
An avatar.json edited while the avatar runs takes effect on it within a second, its
parameters keeping their values.
The expression menu
"menu": [
{ "type": "toggle", "label": { "en": "Hat", "pt-BR": "Chapéu" }, "parameter": "Hat" },
{ "type": "submenu", "label": "Mood", "items": [
{ "type": "toggle", "label": "Happy", "parameter": "Mood", "value": 1 },
{ "type": "button", "label": "Grin", "parameter": "Mood", "value": 1, "hold": 1 } ] },
{ "type": "radial", "label": "Ears", "parameter": "EarAngle" },
{ "type": "axis", "label": "Look", "parameters": ["LookX", "LookY"] }
]
toggle sets value (true or 1 when left out) and back to the default; button sets it
for hold seconds; submenu opens items; radial moves one int or float parameter
from min to max (0 to 1 for a float by default); axis moves two floats from -1 to 1.
A page holds at most 16 items, and sub-menus nest 4 deep. A label is text, or text per
locale tag, shown in the player's language. appMenu.open("expressions") opens the tab; its
rows are the elements expressions-<n> (the n-th item of the page shown, <a>.<b> inside a
sub-menu, -less / -more on a puppet's steps, .a1 / .a2 for an axis puppet's two
sliders), which gui.clickElement presses as a person does.
The cost
avatarRef:animator().cost (and AvatarAnimator:stats().cost) counts layers, states,
transitions, conditions, motions, keys, clips, the channels it drives (shapes,
bones, parts, lanes) and menuItems; units is the work one frame of evaluation does
(the channels of each layer's deepest state, twice for a crossfade, avatarAnimator.clipUnits
for each clip a state plays at once, also twice, plus its transitions).
stats().evaluationMs is the time a frame takes on this engine.