Log inGet started
World

Builtin Library

Branchmain
Branchesmainpublish
Commit15ce14a4c1

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 side UpperLeg, LowerLeg, Foot, UpperArm, LowerArm, Hand. avatarStandard.roleOf maps 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); neutral is 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's vrc.v_ viseme prefix read); an avatar whose shapes are named otherwise maps them in avatar.json: "expressions": { "aa": "Mouth_A", "blink": { "shape": "Eyes_Closed", "overrideMouth": "block" } } (overrideBlink, overrideLookAt, overrideMouth take none, block or blend).
  • 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.

FieldHolds
standard"humanoid/1"
conformstrue when the body breaks no rule
bones{ [vrmBone] = boneName } for every VRM bone the body fills
chainsthe 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"
expressionsvrm ({ [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, bandthe 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
proportionsmetres, 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)
scale1 for an asset; for a live body, its avatar root's world scale, so it stands height * scale tall in the world
problemsevery 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.