zipatch-rs

A Rust library for parsing and applying FFXIV ZiPatch files (.patch).

ZiPatch is the binary patch format Square Enix ships Final Fantasy XIV game updates in. A patch is a chunked binary log of file additions, deletions, SqPack .dat/.index mutations, and binary diffs that an applier walks against an existing game installation to bring it to a new version.

Quick start

[dependencies]
zipatch-rs = "1.5"

Apply a patch to an existing install:

use zipatch_rs::{ApplyContext, ZiPatchReader};

let reader = ZiPatchReader::from_path("D2024.05.31.0000.0000.patch")?;
let mut ctx = ApplyContext::new("/path/to/ffxiv/game");
reader.apply_to(&mut ctx)?;

See docs.rs for the indexed-apply path (Plan / Verifier / IndexApplier), post-apply hash verification (HashVerifier), dry-run mode, observer hooks, and resume entry points.

Features

• Streaming chunk parser — bounded memory, one chunk in flight at a time.
• Sequential apply — chunk-by-chunk, in-place writes to the install tree.
• Dry-run mode — ApplyMode::DryRun walks every chunk, resolves every path, decompresses every DEFLATE block, and validates every chunk CRC32 without opening files for write. Sanity-checks a downloaded patch before touching the install.
• Indexed verify-and-repair — build a Plan describing every byte of every target, verify an install against it, and re-apply only the regions that drift via RepairManifest.
• Post-apply hash verification — HashVerifier reads the resulting .index / .dat files back from disk and compares against caller-supplied SHA1s (whole-file or 50 MiB block-mode). Catches silent on-disk corruption the per-chunk CRC32s can't see.
• Parallel verify — both HashVerifier::execute and index::Verifier::execute fan out across rayon's global pool. SHA1 hashing scales near-linearly with cores.
• Multi-patch chains — a single Plan spans the patch chain end-to-end; mid-chain RemoveAll / DeleteFile / AddFile @ 0 retroactively drop superseded regions.
• Resumable apply — checkpoint emission at every chunk and every DEFLATE block inside SqpkFile::AddFile; resume entry points fast-forward to the recorded position.
• Progress + cancellation — ApplyObserver fires per chunk; should_cancel is polled mid-block on long DEFLATE streams.
• Optional CRC32 verification — Plan::compute_crc32 populates expected CRCs so the verifier catches single-byte damage the size-only policy would miss.
• Alternate DEFLATE backends — opt into zlib-rs or zlib-ng for faster DEFLATE; the default is pure-Rust miniz_oxide with no system dependencies.
• Fuzz harness — eight cargo-fuzz targets cover the full parse + apply surface; weekly cron in CI.

Cargo features

Where it fits

zipatch-rs is a library, not a launcher. It does no network I/O — patch fetch, authentication, version negotiation, and progress UI all live somewhere else. The companion gaveloc workspace is the full launcher product that consumes this crate as a path dependency.

If all you want to do is apply a .patch file you already have on disk to an install you already have on disk, this crate alone is enough.

Reference implementation

The primary reference for the ZiPatch binary format is XIVLauncher's C# implementation in FFXIVQuickLauncher. This crate is not a port — the parser and applier are independently implemented — but the C# tree is authoritative for chunk semantics when the spec is ambiguous.

Stability

• MSRV: Rust 1.85 (the minimum that supports edition 2024). Bumps land as a major version bump.
• SemVer: public API changes follow semantic versioning. The test_utils module is explicitly excluded.
• License: MIT — see LICENSE.

Contributing

See CONTRIBUTING.md. Security issues go through the private advisory form; see SECURITY.md.

Supported chunks

Chunk types

SQPK sub-commands