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.3"

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), 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.
• 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.
• 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