Bone Data Section

This section describes the actor's bones, including the hierarchy and pose position.

Header

Bone

Section layout and tree links

Surveyed over all 203 models with an ACT section (2026-09-18). The layout is fully deterministic and has no slack:

0x00                  header (0x20 bytes)
0x20                  bone table: 0x1C x boneCount, in bone id order
0x20 + 0x1C*N         SRT array: 0x34 each, one per bone with a non-null SRT, in bone order
                      geo name, user data, padding (see Section tail)

• Bone id equals table index. Every model has ids 0..N-1 in table order, with no gaps, aliasing or reordering.
• The SRT array starts right after the bone table. Bone table end equals the first SRT offset (chunk 18: both 0xA14; chunk 95: both 0x5D0). The stride is a uniform 0x34, and no two bones share an SRT. So adding a bone shifts every byte after 0x20 + 0x1C*N, and the section has to be rebuilt, not patched.
• The tree lives inside the bone records. Prev/next/parent/first-child (bone +0x04 to +0x13) are header-relative pointers into the bone table itself. Root bones are linked as siblings through the same prev/next fields, and the header's root pointer (+0x0C) acts as the first child of a virtual root.
• The links are reproducible from parent ids alone. Processing bones in ascending id order and appending each one to the end of its parent's child chain (roots to the virtual root) reproduces every player model's prev/next/first-child/root pointers exactly (190 of 190).

GEO ID ownership rules

Surveyed across 721 exported models and confirmed in Dolphin (2026-09-16):

• Rigid submeshes are placed by their owner bone. Every rigid (CompCount 3) submesh is named by at least one bone's GEO ID, and its vertices are stored in that bone's local space. Skinned (CompCount 6) submeshes are never named by a GEO ID.
• An unowned submesh crashes the game. A GPL submesh appended without a bone that names it crashes on load (Invalid read from 0x00000008, PC = 0x804FF694). A new submesh and its owner's GEO ID must always be written together.
• A GEO ID never exceeds the GPL submesh count.
• One bone owns at most one mesh, because the field is a single uint16. In player models no two bones share a GEO ID. Seven effect and map-object models do give several bones the same GEO ID, so sharing is legal.
• A bone that drives skinning may also own a rigid mesh. None does in vanilla data, but giving Mario's hand bone 28 a mesh worked: the mesh follows the hand and skinning is unaffected.
• Submesh order doesn't have to follow bone order. Vanilla rigid submeshes are in ascending owner-bone order, but a submesh appended at the end on a lower-numbered bone draws correctly. Appending keeps every existing submesh index, and so every existing GEO ID and ptr7 facial SubmeshIndex, unchanged.
• Moving a rigid submesh to another bone is a GEO ID change, and its vertices stay in the old bone's space. Writing the submesh index into a free bone's GEO ID (and FFFF into the old owner's) makes the mesh keep its local offset, now relative to the new bone: Mario's cap moved this way sat at the new bone's offset and followed it: from bone 54 to finger bone 49 through hammerspace, and to bone 7 through the in-place patcher (Dolphin, 2026-10-07). To keep the mesh where it was in the rest pose instead, its positions and normals must be re-baked into the new bone's local space (p_new = B_new-1 · B_old · p with the bind matrices); the re-baked cap stayed on the head in the rest pose and followed the hand when animated (Dolphin, same day). Restoring the two GEO IDs restores the original placement.
• A single-bone prop can take a second bone and a second mesh. A bat (one bone that owns the bat mesh, no SKN section, ACT user data present) was given a new bone 1 under bone 0, with an appended rigid submesh owned by it. It drew correctly in game (Dolphin, 2026-09-29). Several new bones on the same prop also work: multiple new leaf bones and a chain of new bones, each owning its own appended submesh with its own texture (Dolphin, 2026-09-29).
• In a stadium, a mesh hangs on a root bone: a free vanilla one or a new one. Every stadium bone is a root (no parent). Each bone that owns a mesh sits at the mesh's pivot with a translation-only SRT; the free roots are markers with their own SRT, or have none and sit at the origin (sta03 bone 0, sta03b bone 21). Free vanilla roots are few: one in Yoshi Park day (sta03 bone 0), 19 in its night model, two in Daisy Cruiser day (sta08 bones 6 and 7, after every mesh in draw order), none in any Mario Stadium model (sta01/b/c: every bone owns a mesh). Dolphin results:
  • On a vanilla root bone, the add-on's default output draws correctly in Yoshi Park day and night: the builtin:rigid_spec_v1 list with Spec, s16 positions, white RGBA4444 vertex colours and normals, as a cube or a flat plane (2026-10-01).
  • A new root bone works. Vanilla sta03 submesh 5 (the field markings) moved from bone 6 onto a new root bone 7 with bone 6's SRT drew unchanged, and raised with that bone it floated above the field, so it is drawn from the new bone (2026-10-18). A custom cube on a new root bone draws solid in Yoshi Park day and Daisy Cruiser day, from the Blender add-on workflow too (2026-10-18).
  • The earlier failures were a colour bug, not the bones. A custom submesh on a new child bone drew nearly transparent (2026-10-01), and planes on new root bones did not show (2026-10-02). The custom submeshes carried a single colour entry while their vertex format reads a colour per vertex, so they used the colour array of the mesh drawn before them (see Color Data). Fixed in the patcher on 2026-10-18; the same cube on the same new bone then drew solid. A new child bone in a stadium has not been re-tested since.
  The tools take new root bones in stadium models (dirs 7-16) and refuse new child bones there (see Appending bones).

The bone table is reached through the tree: the tree header sits at header+0x08 and its root pointer at header+0x0C. Each node address is the bone's start, relative to the ACT header. BlockValidator walks it to check the rules above.

How the game builds and draws the bones

From main.dol (US; function names from the external tool's symbol list, 2026-10-14). Stadiums are built exactly like characters: nothing outside the model block lists their bones. No DOL table (stadium archive, object lists, options, time of day) names bones, and the GPL mesh names do not occur in the DOL.

• Construction (fn_804EFD24). fn_804EF3FC relocates the ACT pointers and overwrites header +0x08 with 4 (the prev/next/parent/child links start at bone +4), so the vanilla 0xC or stale-looking value there does not matter. It makes boneCount (header +6) bone objects of 0x190 bytes and fills them by walking the tree from the root pointer through next and child links (fn_804F08D8), so a new root linked at the end of the root chain is found like any other.
• Bone +0x1A is a flag word, not padding. Its bit 0x8000 gives the bone two extra matrices that the game multiplies into its draw matrix (fn_804ED670). It is set on 15 vanilla bones in the whole dt_na.dat, never in a stadium; new bones write 0.
• Draw order is bone id order. For every bone id 0..boneCount-1 whose GEO ID is not 0xFFFF, construction pushes a 6-byte draw entry {u16 geo, u16 bone, u8 visible = 1, u8} (vector at actor +0x7C). The render function fn_804F43A8 draws the entries in that order, so a mesh on a new bone always draws last. No game code writes the visible byte or the display object's flag after construction.
• Per frame, bones update by index (fn_804F2BB8): each local matrix from its SRT, times the parent's; roots use the actor matrix. A mesh is drawn with its bone's world matrix and skipped only when its visible byte or display-object flag is 0, or when it has culling bounds and fails the frustum test (see GPL user data).

High- and low-poly pairs share one skeleton

Each player character has a high-poly model and a low-poly L_* model, stored as file indices n and n + 1 of the same chunk. Their ACT geo names match once the L_ prefix and the extension are removed; names are compared after cleaning (see the GEO name pointer above; the Mii pairs read as .gpl/.gplp without it). All 66 vanilla pairs have the same bone count, and 56 have identical parent, track and mirror tables.

The game poses the low-poly model with the high-poly model's bones. Confirmed in Dolphin with Mario (2026-09-27), after appending a bone 91 to one or both models:

• A low-poly model may only draw on bones the high-poly model has. L_mario with a mesh on its new bone 91 crashed on model load while HP Mario had 91 bones (0-90). The same mesh on existing bone 49 loaded, even with the unused bone 91 still present. Adding bone 91 to HP Mario as well made the mesh on bone 91 load. An extra bone that owns no mesh is harmless.
• The low-poly model's own placement of a bone is ignored. With HP Mario's bone 91 parented to the arm and L_mario's bone 91 still parented to the head, L_mario's mesh followed the arm.
• The reverse is fine. HP Mario drawing on a new bone 91 while L_mario had only 91 bones worked (Dolphin, 2026-09-18).

The hammerspace patcher checks the pair against the partner's currently patched state. It refuses a patch or unpatch that would leave the low-poly model drawing on a bone the high-poly model lacks. It warns when an appended bone's parent or SRT differs between the two models.

User data

Found while investigating (2026-09-18) what silently counts bones outside the header's own boneCount. The header's user data pointer (0x1c) is null when userDataSize (0x18) is 0 — dozens of models ship no user data at all with a perfectly working bone tree. When present, it points at a chain of descriptors, each read until the header's total userDataSize is consumed:

Three kinds are seen across the corpus:

• Kind 3 — bone-to-track table. uint16[boneCount], indexed by bone id, giving the ANM track id that bone's animation reads from. 0xFFFF means "no track" — a normal, shipped state (every player model has some: 13-14 trackless bones on Mario). This is the one kind act_section.html previously alluded to as "linking information between bones and animation tracks."
• Kind 2 — the mirror table. (uint8 mirror_bone_id, uint8 role)[boneCount], indexed by bone id. Almost certainly the left/right mirroring used for lefty/righty batting stances. On every player model checked, this table is a perfect involution: table[table[i]] == i for every bone. role values seen: 1 = the main root, 2 = one of five extra root bones, 3 = an ordinary bone (a bone that mirrors itself, i.e. a centreline bone, is simply (own_id, 3) — 23-38 of these per model), 0/4 = rare one-offs of unknown meaning (chunk 18 bone 54 is role 0; chunk 95 bone 17 is role 4). Two donors (chunk 37/1 and 51/1, plus three Magikoopa recolor siblings 52/1, 53/1, 54/1) have oversized, non-involution mirror tables with (0,0) holes and duplicate bone ids — these do not fit this model and are treated as out of scope by tooling that rebuilds this section. Because mirror ids are stored as uint8, bone ids in a rebuilt skeleton must stay <= 255; a corrupt mirror table was confirmed in Dolphin to fail silently (no crash, no visible glitch), so there is no in-game signal to catch a bad table after the fact.
• Kind 4 — opaque, bone-independent. Seen on nine models. Each entry is (uint16 track_id, uint16 = 2), with the descriptor's own count field matching (size - 0x0C) / 4. It references animation tracks, not bones, so it is unaffected by the bone count and can be treated as an opaque blob to copy through verbatim.

The kinds are independent: some models carry only a kind-3 table and no mirror table (chunks 130/18, 137/74, 137/139, 142/129). Models without any user data include chunks 5, 7, 9-12, 15, 16, 126-129, 137, 142 and 159.

Every player model's bone table is exactly boneCount entries, ids 0..boneCount-1 in table order with no gaps — the mirror and track tables are the only place a bone count appears outside the header, and this is why extending the bone table (e.g. appending new bones) requires rebuilding kinds 2 and 3 alongside it, while any kind-4 entry can simply be carried through unchanged.

SRT

SRT stands for scale, rotation, transform.

SRT type byte

The type byte says which components the game reads. Bit 0x4 means "rotation is live", bit 0x8 means "translation is live". The game ignores any component whose bit is not set. Surveyed over the player corpus (about 4,000 bones with an SRT, 2026-09-19):

There are no exceptions in either direction. Types with bit 0x1 set (1, 5, 9, 13) have identity scale, rotation and translation everywhere and mean something else. No vanilla bone has a non-unit scale, so no scale bit is known.

So a new bone's type byte must be derived from the values written, never copied from its parent. Found in game: a new bone that copied its translation-only parent's 8 lost its own rotation, and the mesh on it rendered at Mario's chest instead of above his cap, rotated 180 degrees about the bone. The Blender exporter now computes the mask from the bone's rotation and translation, and warns about a non-unit scale.

Appending bones

New bones can be appended to a skeleton as long as nothing about the existing bones changes. Confirmed in Dolphin (2026-09-18 to 2026-09-20):

• An inert leaf changes nothing. Mario with bone 91 appended under the spine (bone 3), with no mesh, no track and self-mirrored, played an at-bat with no visible or behavioural change.
• A new bone is live. A rigid submesh owned by the new bone followed the spine through every animation. A chain of four new bones, each parented to the previous one and each with its own cube, also followed Mario correctly.
• No bone-matrix cap was found up to 115 bones. Mario with 24 appended bones (91 to 115) played normally. The largest vanilla skeleton has 131 bones (chunk 66); player characters have 52 to 107.
• A new bone can be animated and can drive skinning. A new bone given its own kind-3 track id (0xC0, an id no stock bank uses) and a bank-7 sequence keyed for it in Blender, with Mario's belly weighted to it, bent the belly as keyed (Dolphin, 2026-10-13). The order matters for the tools: the model carries the track id, so the bank is checked against the patched model and must be written after it.
• Different donors work. King Boo (different bone count and root layout), Noki (chunk 42, with a kind-4 user data entry copied through unchanged) and a donor with no user data at all (chunk 136 sta03_yoshi_train02, 3 bones) all worked with a submesh on a new bone.
• A wrong mirror entry fails silently. Bone 91 mirrored to bone 1 instead of itself caused no crash and no visible glitch.

Why appending is safe: nothing outside the ACT counts bones. Player models have ptr6 = ptr8 = 0, and ptr7 (facial poses) indexes submeshes, not bones. GPL, TEX and SKN have no bone counter. SKN refers to bones by id (and a new bone may be skinned to, 2026-10-12), ANM is looked up by track id (a new bone has track 0xFFFF and is skipped unless it is given one), and the bat/glove attach points in main.dol use bone ids too. Keeping every existing id keeps all of these valid. The one exception is the high-/low-poly pair, see above.

Changing existing topology is not safe, and the result is silently wrong rather than a crash:

• Reparenting an existing bone changes its bind matrix while its ANM track still drives the old animated matrix. The mismatch shows as a shear at bind pose.
• Inserting a new bone between two existing bones is a reparent of the child. ANM translation keys are parent-relative (24 of 24 characters checked), so the limb animates against the wrong parent.
• Reordering a sibling chain changes tree evaluation order. Whether the game cares is unknown, possibly through the draw-priority byte at bone +0x19.

Appending a new bone at the end of its parent's child chain adds a link without disturbing any existing one, so it is the only topology change allowed.

New root bones, for stadiums. A new root bone is written with a null parent pointer and linked after the last root in the root sibling chain, which starts at the header's root pointer (+0x0C). That adds a link at the end of an existing chain, like a leaf append. The header word at +0x08 is left alone: across all exported models it is 0xC or a stale-looking address, and the game overwrites it with 4 at load (see How the game builds and draws the bones). act_rebuild.append_leaf_bone(parent_id=None) builds this layout. Meshes on new root bones draw correctly in Yoshi Park and Daisy Cruiser (Dolphin, 2026-10-18; see GEO ID ownership rules). The patcher takes new root bones only in stadium models (dirs 7-16), whose bones are all roots, and refuses them elsewhere.

The hammerspace patcher enforces this before writing:

• Every existing bone keeps its id, parent and mirror pair. Its GEO ID stays unchanged unless a custom submesh claims it.
• New bone ids continue contiguously from the donor's count, the total stays <= 255 (the mirror table stores uint8 ids), and every new bone has a parent. In stadium models (dirs 7-16) it is the other way round: a new bone must be a root, and new child bones are refused (untested there).
• No existing bone may be parented to a new bone.
• A new bone has track 0xFFFF, or a track id of its own from 0xC0-0xFF (no stock skeleton or bank uses these: ids in use are 0x00-0x8C, 0x100-0x127, 0x180-0x199 and flag-style 0x4xxx/0x8xxx/0xCxxx; survey 2026-10-12), and mirrors itself with role 3.
• An SKN record may name a donor bone or a new bone, nothing else. New bones may drive skinning: Mario's hand SK1 entry on a new leaf bone under the hand deformed as vanilla (Dolphin, 2026-10-12; see SKN runtime limits). The low-poly model may only skin to bones the high-poly model has (LOD pairs).
• The donor's mirror table must be absent or a clean boneCount-long involution.

Section tail and alignment

The ACT section starts on a 32-byte boundary, like every section (see overview). Its inside has no single alignment formula. The geo-name strings follow the SRT blob directly, with no reserved null-terminator byte in the layout. The padding after the names and user data, up to the section end, varies per donor. It depends on the section that follows ACT in the model block, not on anything inside ACT (185 player models rebuilt byte-identical this way).

act_rebuild therefore recomputes the bone table and SRT blob, which shift when the bone count changes. It carries the name/tail region through verbatim and leaves section alignment to BuildHEADERModelBlock.