rom-weaver documentation

rom-weaver applies and creates ROM patches without uploading your files. It runs in your browser with nothing to install, and as a command-line tool for scripts and large jobs.

These pages are organised by what you need right now: learning, doing, looking up, or understanding.

New here?

Start in the browser. Nothing to install, your files stay on your device, and the guided tours let you practise on tiny homebrew ROMs before you touch a game you care about.

Take your first patch, or open a tour directly: apply two practice patches, build a patch from two ROMs, or package one as a release.

Tutorials

Guided practice runs. Follow them start to finish; everything you need is supplied.

• Your first patch in the browser: patch a homebrew ROM and verify the result byte for byte.
• Your first apply in the terminal: the same job, plus creating and bundling a patch, from a command line.

How-to guides

Recipes for a real job you already have in front of you.

In the browser

• Apply a ROM patch
• Create a ROM patch
• Create and share a patch bundle
• Test a ROM in the browser
• Fix a checksum error

From the terminal

• Install the CLI
• Verify a download
• Apply patches from the CLI
• Create patches from the CLI
• Bundles from the CLI
• Identify and hash files
• Bake cheat codes into a ROM
• Trim a ROM from the CLI
• Extract, convert, and compress archives
• Fix a permission error

Deploying and integrating

• Self-hosting: Docker, static deployment, reverse proxies, subpaths, HTTPS, and COOP/COEP.
• Webapp integration: preload ?bundle=... and ?rom=...&patch=... URLs, or feed same-origin OPFS files into the pipeline.
• Hosted deployment channels: production, beta, nightly, and pull-request previews.

Reference

Facts to look up. No advice, no steps.

• Supported formats: the full patch, container, codec, checksum, trim, and header support tables.
• CLI reference: every command, global flag, patching flag, JSON output, exit code, and permission check.
• Man pages: generate rom-weaver(1) and one page per visible command from Clap.
• rom-weaver-bundle.json schema: the machine-readable bundle format.
• Runtime configuration: environment variables and browser diagnostic handles.
• Webapp masthead metadata: version, SHA, thread, PWA, and service-worker labels.

Explanation

Background that makes the rest make sense.

• How ROM patching works: why the exact starting file matters, what a checksum proves, why order matters, and what every term means.
• Why your files stay on your device: what local-first buys you and what it costs.
• Choosing a patch format: what actually separates BPS, IPS, xdelta, PPF, and the rest.
• Choosing a compression format: CHD, RVZ, Z3DS, ZIP, 7z, and when trimming beats compressing.
• What a bundle is: the portable patch recipe.
• Browser and CLI: one engine, two front ends, and how to pick.
• Where identify data comes from: Libretro metadata, OpenGood fallback records, and local lookup.
• Release provenance: what download verification proves and why the checks are shaped the way they are.
• Comparison with similar tools: where rom-weaver overlaps with RomPatcher.js, Flips, MultiPatch, xdelta3, chdman, and Dolphin tool, and which one fits your job.

Quick answers

• FAQ: common questions, each pointing at the page that owns the answer.
• Privacy: browser storage, logs, analytics, and network requests.
• Notices: licensing and third-party components.

Develop and contribute

• Contribution guide: reporting bugs, proposing changes, validation, and contribution licensing.

• Development guide: prerequisites, setup, native and WASM builds, the dev server, tests, generated files, and worktrees.

• Architecture: workspace layout, crate graph, command core, browser boundary, OPFS, workers, and test organization.

• ROM identify data: rebuild the Libretro and OpenGood packs.

• References: format specifications and upstream reference implementations.

• CI workflows and local CI checks.

• Commit conventions and the release guide.

• Performance, browser concurrency, and Mobile Safari verification.

• Vendored code, trim footer format, and screenshots.

• CLA, code of conduct, security policy, and commercial licensing.