avatarType

An avatar type describes a kind of body: a humanoid, a quadruped, a vehicle. It names the roles and chains a rig of that kind maps onto, and it finds them in a skeleton. The builtin library ships one, @builtin::avatarTypes.humanoid. A world adds its own the same way, as a <name>.avatarType/ folder.

A rig can be mapped for more than one type; its author's corrections are stored on the rig, keyed by the type's guid, so mapping a skeleton for one type never overwrites another.

The module

init.luau returns:

Field	What it is
name	The type's name, e.g. "humanoid".
vocabulary.roles	Every role the type can assign (hips, lefthand, ...).
vocabulary.chains	Every chain the type can assign (spine, leftArm, ...).
vocabulary.required	The roles and chains a rig must have for the type to claim it.
qualify(structure)	Maps a skeleton. structure comes from modules.rigStructure.

qualify returns:

{
    qualifies = true,              -- the rig is this kind of body
    confidence = 0.94,             -- 0..1
    reason = nil,                  -- one line, when qualifies is false
    mapping = {
        roles = { hips = "Hips", ... },            -- role -> bone name
        chains = { leftArm = { "Clavicle_L", ... } },
        secondary = { { root = "Hair_01", tip = nil, class = "hair", bones = { ... } } },
    },
    report = {
        chains = { leftArm = { confidence = 0.97, bones = { ... } } },
        missing = { "rightArm" },
        ambiguities = { { role = "hips", candidates = { { bone = "Hips", score = 0.9 } } } },
        contradictions = { "..." },
        stale = { { role = "leftforearm", bone = "Elbow_L" } },
        verdict = "humanoid: every required chain found",
        rolesMapped = 52,          -- how many roles the mapping fills
        reasonCode = nil,          -- when qualifies is false: the code of the reason
        reasonValues = nil,        -- the values that reason is written from
    },
}

Using one

local humanoid = asset.resolve("@builtin::avatarTypes.humanoid", "avatarType")
local rig = asset.resolve("PolygonSyntyCharacter", "rig")
local q = rig:qualify(humanoid)        -- the rig's effective mapping for this type
print(q.qualifies, q.mapping.roles.hips)