rig.assetType
- README.md4.5 KB
- about.yaml433 B
- behavior.luau9.2 KB
- inspector.luau4.5 KB
- type.yaml1.9 KB
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.rigasset's guid, never this inner file. It holds:bones— ordered bones, each with aname, aparentindex (-1 for a root), thenodeindex it maps to, itsrestlocal transform (translation / rotation / scale relative to the parent — the bone's offset and length), and itsinverseBindmatrix (16 floats). TheinverseBindis 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 nobindreads its own inverse binds.overrides— what an author set by hand, keyed by avatar type guid:{ [typeGuid] = { roles = { [role] = boneName | false } } }.falseleaves a role empty. Carried across a re-import of the rig's source file.avatar.mapandavatar.unmapwrite 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)
| Method | Returns |
|---|---|
: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,detectedor 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 (falseleaves 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.