MeshCodecSharp 1.0.0

McSharp

A C# library for decoding and encoding Nintendo's MeshCodec — the compression format used by .bfres.mc model files and .chunk terrain files in The Legend of Zelda: Tears of the Kingdom.

Re-encoding a decoded retail file reproduces the original byte for byte, so mods built with McSharp stay binary-identical to vanilla where they don't intentionally differ.

Install

dotnet add package MeshCodecSharp

The package id is MeshCodecSharp; the assembly and namespace are McSharp.

Usage

Decode

using McSharp;

byte[] mc = File.ReadAllBytes("Animal_Bass.Bass.bfres.mc");
byte[]? bfres = MeshCodec.DecompressMc(mc);

DecompressMc(ReadOnlySpan<byte>) allocates its own output and scratch buffers. In a loop, reuse them instead:

byte[] work = new byte[MeshCodec.DefaultWorkBufferSize];

MeshCodec.TryReadPackageHeader(mc, out var header);
byte[] dst = new byte[header.GetDecompressedSize()];
bool ok = MeshCodec.DecompressMc(dst, mc, work);

DecompressChunk and DecompressQuad handle .chunk terrain and quad-tree payloads, and DecompressFmsh decodes a bare mesh section.

Encode

// A BFRES with no mesh section.
byte[] mc = McEncoder.CompressMc(bfres);

// A BFRES whose mesh section must be preserved: pass the original FMSH bytes through.
MeshCodec.TryReadPackageHeader(original, out var header);
int fmsh = McEncoder.FindFmshOffset(original);
byte[] mc = McEncoder.CompressMcWithFmsh(bfres, original.AsSpan(fmsh), header.GetDecompressedSize());

CompressMc throws if handed a BFRES that declares a mesh section, since writing it as a plain package would silently drop the geometry — use CompressMcWithFmsh for those. Check with McEncoder.DeclaresMeshSection or MeshCodec.HasFmshSection.

Encoder settings live on EncoderOptions:

byte[] mc = McEncoder.CompressMc(bfres, new EncoderOptions { ZstdLevel = 8 });

ZstdLevel defaults to 8, which is what retail TOTK files were built with — changing it breaks byte-identical round-tripping. Raise it only if you want smaller files and don't care about matching vanilla. CompressPayload lets you substitute your own zstd implementation entirely.

Encoding the mesh section

McSharp decodes the FMSH vertex/index streams but does not re-encode them; CompressMcWithFmsh copies the existing mesh section through verbatim. That is enough to round-trip retail files and to edit anything in the BFRES body, but not to author new geometry.

Notes

zstd

McSharp depends on BladesawStudios.ZstdSharp, a fork of ZstdSharp that reverts two upstream changes postdating the zstd build Nintendo shipped. Stock ZstdSharp decodes correctly but will not reproduce vanilla bytes on re-encode.

Denormal floats

The reference implementation ran with x86 FTZ/DAZ set, which flushes subnormal half-floats to zero. One retail file depends on this. Set MeshCodec.FlushDenormalHalves = true to match that behaviour.

Credit

MeshCodec — original C++ implementation
ZstdSharp.Port — zstd library

License

MIT — see LICENSE.