Log inGet started
Package

rig.assetType

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

rig asset type

A skeleton, as a composite asset. A rig is its own primitive — not a mesh and not an animation. The folder <name>.rig/ carries:

  • rig.json — the readable skeleton document, the asset's primary. Consumers reference the .rig asset's guid, never this inner file. It holds:
    • bones — ordered bones, each with a name, a parent index (-1 for a root), the node index it maps to, its rest local transform (translation / rotation / scale relative to the parent — the bone's offset and length), and its inverseBind matrix (16 floats). The inverseBind is what skinning reads.
    • bind — where the rig's bind pose, the pose retargeting reads anatomy from, comes from: "skin" (its inverse binds are a skin's bind, as a model import writes), "rest" (it has none: its inverse binds restate its rest, as an animation-only import's rest is the clip's first frame), or { "__ref": <rig guid> } (a skinned rig of the same skeleton whose bind it shares; an animation-only import names one when the world holds it). A rig with no bind reads its own inverse binds.
    • overrides — what an author set by hand, keyed by avatar type guid: { [typeGuid] = { roles = { [role] = boneName | false } } }. false leaves a role empty. Carried across a re-import of the rig's source file. avatar.map and avatar.unmap write it.

The format is JSON, not binary, because a rig is small structural metadata an agent inspects and corrects — the bulk binary .mesh/.animation carry their own decode paths, but a rig is meant to be read.

How a rig maps onto an avatar type

Which bone is the hips, the left hand, a hair strand, is derived from the bones whenever it is asked for, by the avatar type (see the avatarType asset type) — never stored. The skeleton's structure decides it, for any naming and in any pose the rig rests in, and the author's overrides are laid over the result.

local rig = asset.resolve(rigGuid, "rig")
local q = rig:qualify()              -- the builtin humanoid type; pass another type to ask it
print(q.qualifies, q.reason)         -- whether it is a humanoid, and why not
print(q.mapping.roles.hips)          -- the bone filling a role
print(q.report.verdict, #q.report.stale)
MethodReturns
:doc()The decoded rig.json.
:structure()The skeleton's structure (modules.rigStructure).
:qualify(avatarType?)Whether the rig qualifies as the type, the effective mapping, and the report (confidence per chain, missing chains, ambiguities, name contradictions, overrides naming bones the rig lacks).
:mapping(avatarType?):qualify(avatarType).mapping.
:isHumanoid()Whether the rig qualifies as the builtin humanoid.

Read and correct a mapping

A character that stands still, bends an arm or a leg the wrong way, or twists as it walks is read and corrected with the avatar toolbox, which works on the rig of an avatar, a body bundle or a character standing in the scene:

  • avatar.inspect(target) lists every role with its bone, detected or set by hand (override), and the confidence of its chain; { scores = true } measures how idle, walk and run retarget onto the body.
  • avatar.map(target, role, bone) sets a role by hand (false leaves it empty); avatar.unmap(target, role) clears one, or every role set by hand, back to detection.
  • avatar.detect(target) asks every avatar type again and names where detection and the roles set by hand differ.

modules.avatarMapping is the same from code. guides { path: "core/avatars" } has the whole of it.

A skinned .mesh references a .rig (the mesh keeps only per-vertex skin weights; the skeleton lives here). An .animation references its source .rig. Retargeting maps a clip from its source rig onto a body's rig through the roles both rigs fill.

In the Inspector

Selecting a rig opens its Skeleton section: the bone count, the number of roots, whether the rig qualifies as a humanoid with its verdict and confidence, and the bone hierarchy, indented by depth. Its Mapping section lists every role with its bone, where the bone came from and its chain's confidence, the report's warnings and the secondary chains, with a role and bone picker that sets a role by hand and actions that detect again, clear the roles set by hand and measure the retarget of idle, walk and run.