Totk Bfres Model

TOTK BFRES Model Files

Vanilla RomFS Rule

Use a vanilla TOTK romfs path already supplied in the current turn or registered project guidance. Otherwise ask the user for it before inspecting game files. Treat the path as read-only; do not search unrelated folders or guess a location.

Use this skill for low-level Tears of the Kingdom model-file work: BFRES inspection, internal name edits, skeleton/vertex edits, and MCPK compression. It is a mechanics skill, not a task recipe.

For texture container replacement, DDS/ASTC packaging, BNTX/TXTG validation, or non-model texture work, use totk-texture-pipeline. Use this BFRES skill only for model/material context, texture-name bindings, BFRES tables, skeletons, vertices, and resource identity.

Related TOTK Skills

• Use totk-toolkit for shared reusable BFRES/MeshCodec and local inspection scripts before creating one-off tools.
• Use totk-texture-pipeline for BNTX/TXTG, DDS/ASTC, Switch Toolbox texture replacement, texture containers, and texture validation.
• Use totk-local-operator habits for compact inventories, offset summaries, hashes, and validation logs instead of loading binary dumps into context.

Core Rules

• Treat source BFRES and vanilla/reference files as read-only. Write outputs to the requested working/output folder.
• When model outputs will be installed in a mod, ask whether the user wants additive unique paths, vanilla-path replacement, or to supersede another mod's path. Model path/name choices are often priority-sensitive and should follow the user's intent rather than defaulting to uniqueness.
• Prefer parsing the BFRES structure over hardcoded offsets. The weapon files studied here share offsets, but future files may not.
• Never patch counts casually. A Switch-Toolbox crash in MaterialParserV10.LoadStrings was caused by reducing FMAT count while a retained shape still referenced material index 1.
• If output filename/model identity changes, update internal names too. At minimum repoint:
  • BFRES header full resource name pointer at 0x20.
  • FMDL model name pointer at FMDL + 0x08.
  • FMDL model dictionary entry pointing to the same base name.
• If the new name is longer than the old string slot, append a new BFRES string and repoint references. Do not overwrite adjacent string table data.
• For final .bfres.mc, use real MCPK wrapping: MCPK header plus magicless ZSTD payload. Do not merely rename raw BFRES to .bfres.mc.
• For edited TOTK weapon models, do not trust a hand-patched expanded BFRES that merely opens in Switch Toolbox. The game may reject it. Normalize the edited raw BFRES through Switch Toolbox's BFRES save path, then MeshCodec-compress the saved compact BFRES to .bfres.mc.
• For any geometry-affecting edit, recenter serialized FSHP render bounds after the Toolbox save and before MeshCodec compression. Visible vertices and invisible render bounds are separate; stale boxes/spheres can make a correct mesh cull or disappear in camera/frustum tests. Use totk-toolkit/scripts/toolbox_recenter_bfres_render_bounds.ps1 or a pipeline that calls it.
• If a model appears only after camera rotation or disappears at a sharp preview/frustum threshold, inspect the final BFRES render bounds before chasing actor AABB, physics, or material flags. Tested inventory-preview culling did not respond to ActorInfo-style AABB overlays, but was fixed by recentering serialized FSHP boxes/spheres on the edited geometry.
• For geometry edits, prefer Toolbox object-model edits over byte-stream surgery: load the expanded BFRES through FirstPlugin.BFRES, edit the selected FSHP.vertices, call FSHP.SaveVertexBuffer(), save through Toolbox, recenter serialized render bounds, then MeshCodec-compress.
• Binding-looking failures can come from model-layer state, not only actor AttachmentParam or RSDB bind-bone fields. If a fused model aligns on a bare hilt but misbinds on an intact weapon where Bind_A/Bind_B/Bind_C/Bind_W are separated from Bind_Z, inspect the final merged model BFRES before changing rotations. Compare against a working peer for Shape.VertexSkinCount, Shape.SkinBoneIndices, VertexBuffer.VertexSkinCount, VertexBuffer.Attributes such as _i0/_w0, StrideArray, VertexBufferSizeArray, and Buffers. Treat skinning or extra skin-index attributes as an investigation axis, not a proven standalone fix; one validated case showed that removing _i0 and clearing skin counts changed the BFRES correctly but did not change the in-game bind behavior.
• Treat weapon visuals as state-specific evidence. Loose-world item view, inventory fused preview, wielded fused world view, and dropped/loose fused weapon view can each apply different render, hide-material, attachment, animation, or culling paths. A model that looks correct in one state does not prove the BFRES, bind policy, or rotation is correct in the others; record which state was tested before changing geometry or rotations.
• TKVSC-derived tooling does not replace this BFRES/MCPK workflow yet. Its public beta surface is useful for archive browsing and BNTX/TXTG texture preview, but .bfres and .mc support were still unfinished when reviewed. Use TKVSC-derived code only as read-only reconnaissance around models until it proves MeshCodec-equivalent expanded BFRES output.

Observed Switch BFRES FMDL Layout

For the TOTK weapon BFRES files validated in this project:

FMDL + 0x20 = FVTX array pointer
FMDL + 0x28 = FSHP array pointer
FMDL + 0x30 = FSHP dictionary pointer
FMDL + 0x38 = FMAT array pointer
FMDL + 0x40 = FMAT dictionary pointer
FMDL + 0x68 = FVTX count
FMDL + 0x6a = FSHP count
FMDL + 0x6c = FMAT count

When selecting one visible shape without rebuilding all tables, patch only the FSHP array pointer, FSHP count, and FSHP dictionary. Preserve FVTX and FMAT counts unless rebuilding/remapping those tables too.

BFRES Strings

BFRES strings are length-prefixed:

uint16_le byteLength
ascii/utf8 bytes
nul terminator
alignment padding as needed by containing data

Pointers in these files are absolute offsets to the two-byte length field, not to the first text character.

Renaming pattern learned from validated resaves:

Header full name: Custom_Model_Example.Custom_Model_Example
FMDL/model name: Custom_Model_Example
Model dictionary entry: Custom_Model_Example
Shape names may remain source-derived unless the task requires visible shape renames

MCPK / MeshCodec Compression

Validated MCPK details:

• Header magic: MCPK.
• Bytes 4 and 5 are 0x01 0x01 in known-good files.
• Payload is a ZSTD frame with the standard ZSTD magic bytes stripped.
• Compression should disable content-size, checksum, and dictionary-ID metadata. ZSTD payloads in known-good files begin like 00 20..., 00 28..., or 00 30..., not Node's default 60... descriptor.
• Compression level 20 matched Switch-Toolbox-style output well enough for tools to load.

MCPK flags used in this project follow:

aligned = ((-decompressedLength % 0x1000) + 0x1000) % 0x1000
decompAligned = decompressedLength + aligned
flags = ((decompAligned >> 12) << 5) + 0x0c

Important distinction:

• A raw MCPK/ZSTD unwrap can produce a compact BFRES useful for inspection, but it is not an expanded edit source for vertex-buffer surgery.
• Geometry edits that read or rewrite vertex buffers require FirstPlugin.MeshCodec.DecompressMeshCodec(Stream) or an equivalent expanded MeshCodec-decompressed .bfres.
• If an edit script reports out-of-range vertex data, tiny compact BFRES size, missing usable FVTX buffers, or "expanded MeshCodec BFRES required", stop and fix decompression. Do not keep retrying the compact file or debug actor packs.
• Do not promote a new .mc decompressor to proven unless final expanded outputs have non-collapsed vertex buffers, survive Toolbox normalization, compress back to MCPK, and match the existing validation checklist.

Switch Toolbox Normalization

Validated on Weapon_Sword_125: direct binary BFRES edits produced files that opened in Switch Toolbox but did not spawn in game. Opening and immediately saving in Toolbox fixed them. The automated equivalent is:

1. Load the edited raw BFRES with Switch Toolbox assemblies.
2. Preconfigure Toolbox.Library.Runtime.ExecutableDir and Runtime.TotkGamePath before load, because headless use bypasses normal GUI config loading and can otherwise prompt for romfs.
3. Load Newtonsoft.Json.dll, Syroot.NintenTools.Bfres.dll, Syroot.NintenTools.NSW.Bfres.dll, Syroot.NintenTools.NSW.Bntx.dll, FirstPlugin.Plg.dll, and the matching System.Runtime.CompilerServices.Unsafe required by ZstdSharp.
4. Create a dummy Toolbox.Library.Forms.ObjectEditor and set Runtime.MainForm so BFRES.Load() can build its node tree.
5. Save the loaded FirstPlugin.BFRES back to raw .bfres.
6. Compress that saved raw BFRES with FirstPlugin.MeshCodec.CompressMeshCodec(Stream).

Geometry edits require one extra step between 5 and 6:

• Recenter serialized FSHP.boundingBoxes and the related center/radius records to the edited shape vertices. Do this on the saved raw BFRES, not only on the in-memory Toolbox wrapper fields; wrapper edits can read as changed during the same process but fail to persist through BFRES.Save().

The headless loader must include format dependencies so Toolbox.Library.IO.STFileLoader.OpenFileFormat() can open .txtg textures. Without those dependencies, MeshCodec.PrepareTexToGo() may add null texture nodes and TexToGoFolder will throw ArgumentNullException: node.

Known dependency blocker:

• Some Switch Toolbox/ZstdSharp setups require System.Runtime.CompilerServices.Unsafe, Version=4.0.4.1 exactly. Unsafe assemblies with versions 5.0.0.0, 6.0.0.0, or 8.0.0.0 may not satisfy the binding.
• When that happens, ask for a working Toolbox setup, the exact compatible Unsafe DLL, or already expanded MeshCodec-decompressed .bfres files. A task-local MCPK/ZSTD decompressor is not an acceptable substitute for vertex editing.

Expected normalized geometry-edit signs:

• Selected model has FVTX count = 1 and FSHP count = 1.
• _RLT is near the end of the BFRES, not left at the source external-buffer offset.
• Internal BFRES header and FMDL names match the output file.
• For every live edited FSHP, serialized render boxes/spheres reopen centered on the actual vertex bounds, not on the source model's old geometry location.
• MCPK flags match the compact decompressed length.
• No stale physically present non-selected FSHP record is needed after normalization.

Validation Checklist

After editing a model:

• Decompress .bfres.mc and confirm MCPK magic and readable BFRES payload.
• For edited weapon models, confirm the final file is Toolbox-normalized/compact, not a one-frame compressed expanded BFRES.
• Confirm FMDL name and BFRES header full name match the output filename.
• Confirm the selected FSHP pointer and dictionary entry match the intended visible shape.
• Confirm FSHP count is correct.
• For geometry edits, reopen the saved raw BFRES or MeshCodec-decompressed final .bfres.mc and confirm FSHP render boxes/spheres are centered on the edited vertex bounds. Do not trust a same-process wrapper-field edit as proof.
• Confirm FMAT count still includes every material index referenced by retained shapes.
• Confirm skeleton bind translations changed only when intended.
• For fuse-position or wrong-bone symptoms, confirm the final installed or merged .bfres.mc round-trips to the expected BFRES state before blaming a proposed model fix. A source mod can be correct while the launched merged output is stale, and a BFRES-level discrepancy can be real without being the runtime lever.
• Open in Switch-Toolbox or another BFRES-aware viewer when available. If it crashes in material parsing, inspect material count/pointers first.

More Detail

Read references/bfres-field-notes.md when you need the project-specific discoveries, known failure modes, and examples from Weapon_Sword_106, 112, 113, and 124.