avatarStandard.module
This package holds more than this page lists. See all of its files in its world.
README.md
avatarStandard
The humanoid avatar standard every carried avatar is built around, so a game can rely on the avatar a visitor arrives with: where a hat or a held item goes, where the eyes are, which expressions the face has, and how tall the body is.
local avatarStandard = require("@builtin::modules.avatarStandard")
local d = asset.resolve("my_hero", "avatar"):descriptor() -- an avatar asset
local d2 = entity(playerId).component.get("Humanoid"):descriptor() -- a live player's body
local v = asset.resolve("my_hero", "avatar"):validate()
for _, p in v.problems do print(p.rule, p.name, p.message) end
The standard
- Bones: the 55 VRM 1.0 humanoid bones (
avatarStandard.bones), each filled through the humanoid avatar type's structural detection whatever the rig names its bones. 15 are required:hips,spine,head, and per sideUpperLeg,LowerLeg,Foot,UpperArm,LowerArm,Hand.avatarStandard.roleOfmaps a VRM name to the humanoid role (rightHand->righthand). The eyes and the jaw are found by name among the head's own bones. - Attachment points: 19 (
avatarStandard.points):origin,hat,hair,faceFront,faceCenter,neckBase,leftCollar,rightCollar,leftShoulderTop,rightShoulderTop,bodyFront,bodyBack,waistFront,waistCenter,waistBack,leftGrip,rightGrip,leftSole,rightSole. Each is placed from the body's own proportions, and its frame is the avatar's axes on the body standing in a T-pose with its palms down (+Y up, +Z forward, +X the body's left), carried by the anatomy of the bone under it. A grip's +Z leaves the fist on the thumb's side; a sole's +Z points toward the toes. - Viewpoint: between the eyes when the body has eye bones, else in front of the head at eye level.
- Expressions (
avatarStandard.expressions): the VRM presets are the required face tier (aa ih ou ee oh,blink blinkLeft blinkRight,lookUp lookDown lookLeft lookRight,happy angry sad relaxed surprised,neutral);neutralis the face at rest and the look presets are met by eye bones too. The Oculus 15 visemes and ARKit's 52 shapes are optional tiers. A blend shape answers a preset by its name (case and separators ignored, VRChat'svrc.v_viseme prefix read); an avatar whose shapes are named otherwise maps them inavatar.json:"expressions": { "aa": "Mouth_A", "blink": { "shape": "Eyes_Closed", "overrideMouth": "block" } }(overrideBlink,overrideLookAt,overrideMouthtakenone,blockorblend). - Height band:
avatarStandard.heightBand, 0.5 to 3 m.
The descriptor
Positions and rotations are in the avatar's own space: metres, +Y up, +Z the way the body faces, +X its left, from the ground beneath its hips. Up is the body's own vertical (an avatar asset's bundle stands it on +Y; a live avatar stands on its root's up), so a spine that leans in the rig leans in the descriptor too.
| Field | Holds |
|---|---|
standard | "humanoid/1" |
conforms | true when the body breaks no rule |
bones | { [vrmBone] = boneName } for every VRM bone the body fills |
chains | the body's optional chains by class (hair, ear, tail, chest, skirt, face, attachment, ...), each { root, bones } |
points | { [point] = { role, bone, position, rotation, local } }; local is the same frame in the carrying bone's own space |
viewpoint | { role, bone, position, rotation, local, source }, source "eyes" or "estimate" |
expressions | vrm ({ [preset] = { shape?, source, override } }), visemes, arkit ({ [name] = shape }), missing (the VRM presets nothing answers), tiers ({ vrm, visemes, arkit }, each true when the body has the whole tier) |
height, bounds, band | the body's height (ground to crown), the extent of its skeleton, and the band the standard takes; height and bounds are nil for a body with no humanoid frame |
proportions | metres, for sizing what the body wears: head (crown above the head joint), shoulderWidth, hipWidth (between the upper-arm and upper-leg joints), torso (hips to the base of the neck), arm (shoulder joint to wrist), leg (hip joint to the ground) |
scale | 1 for an asset; for a live body, its avatar root's world scale, so it stands height * scale tall in the world |
problems | every rule broken, each { rule, name, message }, rule one of type, bone, point, expression, height |
validate answers { ok, problems, summary }; summary says the problems in
one line per broken rule ("missing 3 required bones: rightUpperArm,
rightLowerArm, rightHand"), in the player's language, for showing a player why
their avatar was turned away. The lines come from the library's
avatar_standard catalog; a world words them its own way with an
avatar_standard.json of its own (summary.bone_one, summary.bone_other,
summary.height, ...). A live body is held to the height band at the height it stands in the
world (height * scale).
validate(body, { rules }) holds a body to the rules a game relies on
(avatarStandard.rules: type, bone, point, expression, height; all of
them by default). A game whose players need no faces leaves out expression:
local v = h:validate({ rules = { "type", "bone", "point", "height" } })
describe(body) takes an avatar asset or a live avatar entity, which both state
the body's units; validate(body) answers { ok, problems }. A bare rig states
no units (the built-in Synty rigs are in centimetres), so describe one through an
avatar that wears its body, or with describeStructure(structure, opts) (opts:
qualification, unit in metres per rig unit, up the body's vertical in the
structure's space, morphTargets, expressions). Without up the avatar's
space stands on the humanoid frame's up, from the hips toward the chest.
Seat items on the points with Humanoid:attach(point, itemId, opts) (the
Humanoid component's README); Humanoid:attach("viewpoint", cameraId) seats a
first-person camera at the eyes.