rom-weaver documentation
rom-weaver applies BPS, IPS, UPS, and xdelta ROM patches, converts discs to and from CHD and RVZ, compresses 3DS ROMs to Z3DS, identifies ROMs, and tests games you already have. Your files stay on your device.
What rom-weaver supports explains every feature in plain words, with links to exact support limits.
These pages are organised by what you need right now: learning, doing, looking up, or understanding.
New here?
Start in the browser. No account, installation, or commercial game is needed for the practice run.
- Follow your first patch with the supplied homebrew files.
- Check the result against the tutorial's checksum.
- Choose your own task below. Keep a clean backup of your files.
Prefer the terminal? Start with Install the CLI, then your first CLI apply.
Guided runs in the app: Apply, Create, Weave, and Test, plus cheat runs for Apply and Create. Guided Apply waits for you to add files, and its Continue uses the practice files when you have none. Guided practice runs lists what each run covers and where it starts.
Choose a task
| I want to… | Browser guide |
|---|---|
| Add a translation or other game change | Apply a patch |
| Add a patch recipe to my release page | Add an Apply button |
| Share changes I made | Create a patch or weave a recipe |
| Find which game or revision a file contains | Identify a ROM by checksum |
| Find a ROM from an existing CRC32, MD5, or SHA-1 hash | Search ROM checksums |
| Check a file against an expected checksum | Checksum a file |
| Take files out of an archive | Extract files |
| Package files or compress a disc image | Compress files |
| Make a game's file smaller | Compress files, or trim padding |
| Decompress RVZ to ISO | Extract an ISO from RVZ |
| Compress ISO or BIN/CUE to CHD | Create a CHD |
| Decompress CHD to ISO, BIN/CUE, or GDI | Extract a disc from CHD |
| Compress a GameCube or Wii ISO | Compress ISO to RVZ |
| Compress a Nintendo 3DS ROM | Create a Z3DS file |
| Decompress Z3DS, ZCCI, ZCXI, ZCIA, or Z3DSX | Extract a Nintendo 3DS file |
| Use cheat codes | Add cheats |
| Play a game or back up progress | Test a ROM |
| Change saved progress | Edit a save or create a fresh save |
| Work without an internet connection | Set up offline use |
| Connect an AI agent | Use MCP and browser agents |
For terminal equivalents and availability limits, use the feature map.
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.
- Patch a compressed CHD disc: apply two supplied patches and verify the decompressed result.
- Your first apply in the terminal: the same job, plus creating a patch and a weave, from a command line.
How-to guides
Procedures for specific tasks.
In the browser
- Add an Apply button to a release
- Apply a ROM patch
- Use cheats in the browser
- Convert BPS to IPS and other patch formats
- Create a ROM patch
- Share multiple ROM patches as one weave
- Identify a ROM by checksum
- Search ROM checksums
- Checksum a file
- Extract files from an archive or disc image
- Compress files or disc images
- Decompress RVZ to ISO
- Decompress CHD to ISO, BIN/CUE, or GDI
- Compress ISO or BIN/CUE to CHD
- Compress GameCube or Wii ISO to RVZ
- Compress 3DS ROMs to Z3DS or ZCCI
- Decompress Z3DS or ZCCI to CCI
- Trim a ROM
- Undo a PPF patch
- Use the online ROM tester
- Fix a source ROM checksum mismatch
- Edit a game save
- Create game saves in the browser
- Settings, beta tools, and offline use
- Use MCP and browser agents
From the terminal
- Install the CLI
- Verify a download
- Apply patches from the CLI
- Create patches from the CLI
- Weaves from the CLI
- Identify and hash files
- Bake cheat codes into a ROM
- Edit a game save from the CLI
- Create game saves with the CLI
- Trim a ROM from the CLI
- Make an M3U playlist 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
?weave=...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.
- What rom-weaver supports: every feature in plain words, browser and CLI availability, and links to exact limits.
- Cheat database: supported systems, delivery classes, matching, storage, and licensing.
- Guided practice runs: every guided browser run, its steps and practice files, where it starts, and every way files get into Apply.
- CLI reference: every command, global flag, patching flag, JSON output, exit code, and permission check.
- Save Editor support: supported games, editable fields, recognition rules, and integrity checks.
- Man pages: generate
rom-weaver(1)and one page per visible command from Clap. rom-weaver-weave.jsonschema: the machine-readable weave format.- Runtime configuration: environment variables and browser diagnostic handles.
- Webapp masthead metadata: version, SHA, thread, PWA, and service-worker labels.
Explanation
Background on the engine, formats, and design decisions.
- How ROM patching works: why the exact starting file matters, what a checksum proves, why order matters, and what every term means.
- ROM cheats: why rom-weaver bakes cheats into the ROM instead of running them at emulation time.
- Why your files stay on your device: the benefits and limits of local processing.
- BPS vs IPS, UPS, xdelta and PPF: checksum protection, size limits, and suitable uses for BPS, IPS, UPS, xdelta, and PPF.
- Choosing a compression format: CHD, RVZ, Z3DS, ZIP, 7z, and when trimming beats compressing.
- What a weave 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.
- ROM patcher comparison: 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.
- About: who makes rom-weaver, its licence, and what it is built on.
- 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.
Save Editor development: shared handler architecture, integrity boundary, and the eight-step contributor flow.
ROM patch and disc format specifications: format specifications and upstream reference implementations.
Commit conventions and the release guide.
CHD, RVZ, ZIP, and 7z speed benchmarks, browser concurrency, and Mobile Safari verification.
CLA, code of conduct, security policy, and commercial licensing.