RVZSharp Documentation

RVZSharp is a .NET 8 / 9 / 10 library and command-line tool for GameCube and Wii disc images. It reads the modern RVZ container (and its predecessor WIA), decodes the classic legacy formats (GCZ, CISO/WBI, WBFS, TGC, NFS) into a canonical ISO view, and writes RVZ, WIA and GCZ files from any of them — mirroring the behaviour of the reference implementations in Dolphin (C++) and the Go rvz reader.

Target frameworks	net8.0, net9.0, net10.0
Solution file	CSharp_RVZSharp.sln
Tests	609 fast library tests (every framework, ~1 min) + 57 CLI tests + 276 real-file slow tests — the solution runs fast-only by default (dotnet test CSharp_RVZSharp.sln -c Release); run the slow suite explicitly with dotnet test RVZSharp.Slow.Tests -c Release
Read support	RVZ, WIA, GCZ, CISO/WBI, WBFS, TGC, NFS, plain ISO
Write support	RVZ (None, Zstd, Bzip2, LZMA1, LZMA2; optional PRNG-junk packing), WIA (None, PURGE, Bzip2, LZMA1, LZMA2) and GCZ (zlib deflate)
Reference sources	References/dolphin-master/ (C++), References/rvz-1.0.3/ (Go)

Documentation map

Page	What it covers
What’s new	Release highlights (1.1.0, 1.0.0)
Getting started	Prerequisites, build, test, first commands
Packaging & distribution	NuGet package contents, build, publish, versioning
CLI reference	convert, header, verify, extract (+ legacy info/decode) — options and examples
Library API	Blob, RvzReader, RvzWriter, WiaWriter, GczWriter, DiscFileSystem, DiscHasher, codecs, packing API
Architecture	Module map, read/write pipelines, design decisions
RVZ container format	File head, disc struct, tables, groups, chunking
Compression & packing	Codec details and the Lagged-Fibonacci junk packing
Wii partitions	Encryption, hash tree, hash exceptions, tickets
Legacy formats	GCZ, CISO/WBI, WBFS, TGC, NFS byte layouts
Testing	Test strategy and synthetic image builders
Release notes	1.1.0 and 1.0.0 announcement content (GitHub release posts)
Roadmap & status	Milestones, limitations, open questions
FAQ	Common questions

Conventions used in this wiki

• Byte offsets and sizes are hexadecimal unless stated otherwise (0x…).
• Multi-byte integers are big-endian (network order) unless a page says otherwise.
• The format pages describe the on-disk layout as implemented by Dolphin and verified by this project’s tests; they are an implementation companion to References/dolphin-master/docs/WiaAndRvz.md.

Wiki and Pages

These pages are published twice from the same files, automatically:

• GitHub Pages (.github/workflows/pages.yml) builds this folder with Jekyll on every master push touching docs/; index.md renders this page as the home page and the side menu comes from _data/nav.yml rendered by _layouts/default.html. Internal links use the .md form, which Jekyll converts to .html.
• GitHub Wiki (.github/workflows/wiki.yml) mirrors these pages to the wiki root on the same trigger (README.md → Home.md, format/*.md → format/… subpages, _Sidebar.md kept as the wiki sidebar, Jekyll-only files dropped); relative links are rewritten to the extensionless wiki form. The wiki is fully generated — edit these files, never the wiki pages.

Releases (bundled CLI zips, NuGet publishing) and the automation setup are documented in Packaging & distribution.

Feature overview

• Blob abstraction — every format is opened through the same IBlobReader interface; the format is auto-detected from its magic bytes, so info, decode and convert accept any supported file.
• Canonical ISO view — all readers expose the decoded disc as a random-access stream of ISO bytes, so a GCZ, a WIA and an RVZ of the same disc are interchangeable inputs.
• RVZ/WIA/GCZ writing — the RVZ/WIA writer stores Wii partition data decrypted with hash exceptions (the same space-saving trick Dolphin uses), detects and packs PRNG junk with a recovered seed (RVZ), and emits fully checksummed tables (SHA-1 everywhere Dolphin puts them); GCZ is written as Dolphin-compatible zlib blocks with per-block Adler-32s.
• File system access — DiscFileSystem parses the GameCube/Wii FST (case-insensitive lookup, file streaming through decrypted partition views), and the CLI extract command lists/extracts the tree and the standard system data per partition.
• Parallel and async — RVZ/WIA chunk decoding and group compression run on bounded worker pools (--threads; output byte-identical for any thread count), and the async API (CopyToAsync/ReadFullyAsync/WriteAsync) wraps the CPU-bound work for UI consumers.
• Verifiable — every conversion is byte-exact: the test suite round-trips synthetic discs through every codec, packing setting and chunk size, decodes 90 real GameCube/Wii RVZ files byte-for-byte against their official No-Intro SHA-1s, re-encodes real GC/Wii images back to RVZ, and DiscHasher/the CLI can verify decoded output (--sha1, verify).