rom-weaver

Apply patches from the CLI

Apply one patch or an ordered chain in the terminal, handle headers and byte order, verify checksums, and validate patches without keeping an output ROM. New to the CLI? Start with your first apply. Each recipe uses only the flags its task needs; the patching flags are catalogued in the reference.

Apply one or more patches

Apply one patch, or several in order, each on the result of the last:

rom-weaver patch apply \
  --input original.sfc \
  --patch translation.bps \
  --output translated.sfc

rom-weaver patch apply \
  --input original.sfc \
  --patch base.ips \
  --patch fixes.ups \
  --output patched.zip

patch apply is the canonical spelling; weave remains accepted for compatibility.

An output extension matching the selected ROM leaf writes a plain ROM, so translated.sfc does not need --no-compress. A registered container extension such as .zip still compresses the result. Use --no-compress to force raw bytes. The output reference lists compression overrides and aliases.

For an ordinary file apply, omit --output to write a sibling such as original-patched.sfc. Existing names are preserved by adding a numeric suffix. Weave applies keep their weave-provided output name; a weave without one still requires --output.

Formats that carry their own checksums are verified strictly, so a wrong original ROM stops the run - see Fix a checksum error when that happens.

Apply a Dreamcast DCP patch

  1. Keep the Dreamcast .gdi or .cue sheet with every referenced track at its recorded path.
  2. Check that the disc matches the DCP author's required release before applying, for example with rom-weaver checksum. DCP apply cannot verify it for you.
  3. Apply the .dcp alone, using the sheet as the input:
rom-weaver patch apply --input game.gdi --patch hack.dcp --output patched.chd

For a CUE-based disc, replace game.gdi with the .cue path. DCP rebuilds the high-density data track's filesystem and selects that track automatically.

DCP cannot run in a patch chain or with cheats, an explicit target, or byte-level header, checksum-repair, and N64 byte-order transforms. It also rejects the checksum guards --expect-in, --expect-out, --patch-input-check, and --patch-output-check, and fails before writing output. A weave's optional cheats are skipped with a warning; its required cheats fail the apply unless you pass --without-cheats. Browser Apply does not support this disc-sheet workflow.

Test the resulting CHD in a compatible Dreamcast emulator. Keep the original disc and tracks until you check the result.

Pipe the patched ROM to another program

Use --output - and --no-compress to send the patched ROM to a compressor:

rom-weaver patch apply \
  --input original.sfc \
  --patch translation.bps \
  --no-compress --output - | gzip > translated.sfc.gz

To have rom-weaver produce the archive itself, replace --no-compress with --compress-format zip and redirect stdout to a ZIP file. The operation finishes in temporary storage before it writes stdout. See the binary pipeline reference for storage requirements and restrictions.

Pick one patch out of an archive

Point --patch at an archive and --patch-select at the file inside it:

rom-weaver patch apply \
  --input game.chd \
  --select '*.bin' \
  --patch quality-of-life.7z \
  --patch-select 'Game (USA)/Quality of Life.ppf' \
  --no-compress \
  --output patched.bin

--select chooses the payload inside the input, --patch-select the file inside the patch archive. Without the second flag, --select applies to both, and no single pattern can match a .bin in the input and a .ppf in the patch.

Match on the path when the archive nests its patches in folders: '*USA*/*.ppf' works, a bare '*USA*' does not.

Repeat --patch-select once per --patch, in order; each binds to the --patch before it:

rom-weaver patch apply \
  --input game.sfc \
  --patch base.zip --patch-select base-v2.bps \
  --patch extras.zip --patch-select widescreen.bps \
  --output patched.sfc

Verify the ROM before and after

When a patch page publishes the expected checksums, pin them so the run fails loudly instead of producing a broken ROM:

rom-weaver patch apply \
  --input original.sfc \
  --patch translation.bps \
  --output translated.sfc \
  --expect-in crc32=ABCD1234 \
  --expect-out sha1=0123456789abcdef0123456789abcdef01234567

--expect-in stops before patching unless the input matches; --expect-out fails the run unless the finished ROM matches.

Apply a patch made for a headerless ROM

--patch-header auto uses available checksums and first-patch inference to choose between headered and headerless input. When the evidence is inconclusive, it keeps the existing form. --output-header auto keeps required format headers and recognized NSRT dump metadata. Override the defaults when the patch author specifies a layout. Add --repair-checksum only when the output needs internal checksum repair:

rom-weaver patch apply \
  --input game.smc \
  --patch hack.ips \
  --output patched.sfc \
  --patch-header strip \
  --output-header strip \
  --repair-checksum

Apply an N64 patch regardless of byte order

N64 ROMs circulate in three interleavings, and a patch only applies to the one it was made against. The default --n64-byte-order auto matches your ROM to the patch's source CRC32 and writes the output back in the order the input arrived in, so usually there is nothing to do. An IPS patch carries no checksum; auto then reads the shape of its changes, and says so in the report when that settles it. Set a specific patch-input order only when the author documents it:

rom-weaver patch apply \
  --input game.n64 \
  --patch fix.bps \
  --output fixed.n64 \
  --n64-byte-order big-endian

The output keeps the input's byte order. The .n64 extension above reflects that; --n64-byte-order big-endian selects the patch input, not the output format.

Validate a patch chain

patch validate checks the chain without keeping an output ROM. It can create temporary files while applying the patches:

rom-weaver patch validate \
  --input original.sfc \
  --patch base.ips \
  --patch fixes.ups

Patches default to automatic checksum inference. Pass --default-patch-basis base for patches made from the original ROM, or previous for a dependent chain.

Pass --independent to check each patch separately and report every verdict. The command exits 1 if any patch fails. Use --expect-in ALGO=HEX to check the ROM itself.

Undo a PPF patch

Use the patched ROM and the exact PPF3 patch that changed it. The patch must include undo data. Create one with rom-weaver patch create original.bin modified.bin -o change.ppf --ppf-undo.

rom-weaver tools ppf-undo -i patched.bin --patch change.ppf -o restored.bin --no-compress

To restore from archived ROM and patch inputs and compress the result:

rom-weaver tools ppf-undo \
  -i patched.zip --select game.bin \
  --patch change.zip --patch-select change.ppf \
  -o restored.zip

See compression overrides for other formats and codecs.

Compare the restored file with the original's known checksum before you use it. If the patch lacks undo data, restore your backup instead.

The tools reference lists the inputs and limits.

Where next

  • A checksum mismatch is almost always a wrong starting file; see Fix a checksum error.
  • Record a finished run as a shareable recipe with Weaves from the CLI.
  • Bake cheat codes into a ROM (--code), write a weave alongside the patched ROM (--emit-weave, --tui), or patch straight from a rom-weaver-weave.json: the patching flags cover every option, and rom-weaver patch apply --help is authoritative.