Contents · Français

Patches

A patch is a small file that only holds the differences between a ROM and a modified version of it: a translation, a bug fix, a hack. It is shared instead of the modified ROM, since sharing the ROM would mean sharing the game; each user applies it to their own copy.

RomSieve applies the patches of a folder to the ROMs of your collection: each patch whose original ROM is identified in the source gives a patched version, written in the destination next to the original version, or in a folder of its own (see A folder for the patched versions). The original ROM is never modified.

A patch only applies to the exact ROM it was made for: same region, same revision, same dump. RomSieve finds it for you by its checksum (CRC32), which needs a DAT file.

Supported formats

Format Extension Original ROM found by Checks
IPS .ips your choice, otherwise the CRC32 written in the name of the patch, or in its readme (see Matching) none: the format records no checksum
IPS32 .ips or .ips32 your choice, otherwise the CRC32 written in the name of the patch, or in its readme none
UPS .ups the CRC32 and the size it records CRC32 of the patch, of the original ROM and of the result
BPS .bps the CRC32 and the size it records CRC32 of the patch, of the original ROM and of the result

The format is read from the content of the file, not only from its extension. UPS and BPS are the safest: they only apply to the right ROM and check their result. A damaged or truncated patch is refused before it is applied.

The other formats (xdelta, PPF, APS, BSDiff…) are not supported: their files are ignored. MAME arcade sets and the software of MAME software lists are never patched.

Folder of the patches

In the Collection step, the Patches card has the Folder of the patches field, with its Browse... button. It is always shown, whatever the convention. Next to its title, Manage patches… opens the Patches window on the last simulation (see The Patches window); it is greyed out until a simulation found patches.

The Apply the patches box, next to the title of the card, is checked by default, and checks itself when you choose a folder with Browse.... Unchecked, no patch is applied, but the folder stays in the settings and the profiles for next time: it is not read, Write the patched versions only and the folder of the patched versions are greyed out, and the log says that applying the patches is turned off. The rest does not change: a folder of the patches inside the source is still not sorted as ROMs, and the destination still may not overlap it, so that a purge never puts your patches in quarantine.

The log of the simulation tells how many patches were found and how many gave a patched version.

Matching

Only a ROM identified in the DAT can receive a patch, whatever its status: a release left out by 1G1R receives its patch like any other. This is often the case of a translation, made for the Japanese release of a game that 1G1R leaves out in favour of the American release.

Readme of an IPS

A readme is a .txt or .nfo text file of at most 1 MB, stored next to the patch: in the same folder of the folder of the patches, or in the same archive, at the same place. A readme on the disk never comes with a patch stored in an archive, nor the reverse.

For the CRC32, RomSieve only reads the lines where the word CRC appears, and on them the CRC32 that follow it. A readme often also gives the CRC32 of the patched result: it designates no ROM of the source, and it is ignored. Your choice, then the name of the patch, always prevail over its readme, and a UPS or a BPS, which records its original ROM itself, never reads its own.

A readme sometimes gives the CRC32 of a ROM with and without its copier header, on two lines (for example File CRC32 and ROM CRC32). An IPS does not tell which of the two forms it expects: RomSieve does not apply it. The readme usually tells which form the patch was made for: then choose that form in the Patches window (see Choosing the ROM of a patch).

The detail panel of a patched version names the readme that gave the CRC32.

A readme often also names the ROM the patch was made for, by its No-Intro name followed by its extension (Make sure to use the "Super Mario Bros. 2 (USA).nes" ROM, Mega Man 2 (USA).nes - NOINTRO, or after Database match:). When no CRC32 designates a ROM of the source, RomSieve proposes the ROM so named in the Patches window ("readme.txt gives the name of this ROM"), never applying it on its own: a readme may name another revision, or a ROM that must be translated first. The name is compared with those of the DAT, case ignored, as a file name and as the name of the game (a readme writes .nes where a DAT without header writes .unh). A GoodTools name ((U) [!]) or an approximate one designates no ROM. When the ROM named is in the DAT but not in the source, the reason of the patch names it.

The patched version

NES, Lynx and Super Nintendo

A patch made for the whole file of a ROM with a copier header gives a result that has one: it is written as the patch produces it. A patch made for the data without the header gives data alone:

When such a patch changes the size of the data (a patch that enlarges the ROM), the header is written as it is, and may no longer give their right size: the log says so for each patched version concerned. A patch made for the whole file, which can update the header itself, does not have this problem.

The header must still be the one of the original ROM when the patch is applied: a header changed since the simulation puts the patched version in Error, without writing anything.

Old iNES 1.0 header. Current NES ROMs have a NES 2.0 header, which gives details in its last bytes. Older patches, and the CRC32 their readmes and the romhacking.net page of each patch give, were made with the iNES 1.0 header of the time, where these bytes were zero: their CRC32 is that of no current file, nor of any ROM of the DAT. RomSieve thus also looks for each NES ROM under this old header, computed from its own (the data stay the same). A patch made for it then applies to the ROM read this way, and the result is written as the patch produces it, with the header it holds. The detail panel says so ("under an old iNES 1.0 header"). A ROM that already has an iNES 1.0 header does not need this form, and a ROM without a header cannot get it.

Name of the patched version

The name always starts from that of the original ROM, as the DAT gives it: the region and the revision come from the DAT, never from the author of the patch, and each patched version sorts next to its original ROM. The label in square brackets comes from the name of the patch:

Patch Original ROM Patched version
Game (Japan) (T-En).bps Game (Japan).sfc Game (Japan) [T-En].sfc
Game (T-En v1.2).bps Game (Japan).sfc Game (Japan) [T-En v1.2].sfc
Game (T-En) [47E70E08].ips Game (Japan).sfc Game (Japan) [T-En].sfc
SMB3_eng_v1.2.ups Super Mario Bros. 3 (Japan).nes Super Mario Bros. 3 (Japan) [SMB3_eng_v1.2].nes
Alpha (1990)(Ocean)[h Hack].bps Alpha (1990)(Ocean).adf Alpha (1990)(Ocean)[h Hack].adf

Write the patched versions only

Check Write the patched versions only, in the Output step, under the Patched versions field (Directory tree frame), so that a game that has a patched version is only written in that form. With 1G1R, the ROM kept for that game is not written, even when the patch was made for another release of the game: a patch made for Game (World) (Collection).md, which 1G1R leaves out for Game (World).md, gives the only patched version, and Game (World).md is not written. Without 1G1R, each ROM kept is a choice of its own, and only the original ROM of the patch is replaced. The table shows a ROM replaced Excluded, with the reason Replaced by a patched version; a ROM that 1G1R already left out keeps its reason. With the option unchecked, the ROM kept and the patched version are both written. The option is greyed out without a folder of the patches, or with Apply the patches unchecked.

A folder for the patched versions

By default, a patched version goes into the folder of its original ROM. The Patched versions field of the Output step, in the Directory tree frame, under the Pattern, puts it elsewhere, for two uses:

The field is a pattern of folders, like the Pattern (see Variables), but it starts from the root of the destination, even with All at the root: the folders of a lot of DATs are not added to it on their own. Its variables take the values of the original ROM ({title}, {dat}, {publisher}…), even when 1G1R leaves it out, and two variables exist for it alone:

Variable Content
{origin_folder} The whole folder the original ROM goes into: the folder of its DAT in a lot (under the folders of its path when they are mirrored), then the folders of the pattern; none with All at the root
{dat_folder} The folder of the DAT of the original ROM in a lot, under the folders of its path when they are mirrored; none for a single DAT, or without A folder per DAT

Each makes up a folder on its own, between two /: {origin_folder}/Patches is allowed, {origin_folder}-patches is not. Empty, the field (Next to the original ROM) gives the same folder as {origin_folder}.

Examples with Chrono Trigger (Japan).sfc, the pattern {title} and a (T-En) patch:

Patched versions Single DAT Lot, a folder per DAT Lot, folders of the DATs mirrored (No-Intro/)
(empty) Chrono Trigger/ Nintendo - SNES/Chrono Trigger/ No-Intro/Nintendo - SNES/Chrono Trigger/
Patches/{title} Patches/Chrono Trigger/ Patches/Chrono Trigger/ (every DAT together) Patches/Chrono Trigger/
Patches/{dat}/{title} Patches/Nintendo - SNES/Chrono Trigger/ Patches/Nintendo - SNES/Chrono Trigger/ Patches/Nintendo - SNES/Chrono Trigger/
{dat_folder}/Patches Patches/ Nintendo - SNES/Patches/ No-Intro/Nintendo - SNES/Patches/
{origin_folder}/Patches Chrono Trigger/Patches/ Nintendo - SNES/Chrono Trigger/Patches/ No-Intro/Nintendo - SNES/Chrono Trigger/Patches/

The file keeps its name there, Chrono Trigger (Japan) [T-En].sfc (a .zip archive in ZIP mode). The _unmatched folder of the non-conforming files stays at the root: a patched version never goes there, since its original ROM is identified.

Nothing is written outside the destination. A folder that would leave it, or write into the folders RomSieve keeps for itself, is refused: a path that starts with / or \, a drive (C:), a .. folder, a character forbidden in a name (< > : " | ? *), _purged or .romsieve as first folder, {origin_folder} or {dat_folder} that is not a folder on its own. The preview says why, a line says so under the Output step (Patched folder refused), and both the simulation and the sort are refused before anything is written. An unknown variable, a brace without its pair or an _unmatched folder are only a warning of the preview, as for the pattern.

Changing the folder of the patched versions makes the last simulation out of date; the next one marks the patched versions alone Changed. Undo Last Sort deletes them, and the folders it empties.

Transfer modes

Mode Patched version
Copy A file, written next to the original ROM or in its folder
Move A file, written before the original ROM leaves the source. With Write the patched versions only, the ROM it replaces stays in the source.
Hard link, Symlink A copy: a link cannot hold modified data. The log says so.
ZIP An archive of its own, in the TorrentZip format, like that of any other game, in the same folder

An original ROM stored in an archive is extracted next to the target while the patch is applied, then deleted. The archive is never modified.

The writing follows the same safety rules as any other (see Safety, purge and undo): the file only appears under its name once complete, and a stopped or failed sort leaves no truncated file. The CRC32 of the original ROM is checked while the patch is applied: a ROM modified since it was identified is refused, even for an IPS. For a UPS or a BPS, the CRC32 of the result is checked too: a wrong result puts the patched version in Error, leaving nothing in the destination. With Verify copied files, the patched version is read again once written.

Patches not applied

A patch that gives no patched version has its line in the log, with its reason:

Reason What to do
The original ROM, name, is missing from the source (or: a readme designates the original ROM, name, …) The DAT knows this ROM, but the source does not have it: add it to the source. In a lot, the DAT of the ROM follows its name
A readme names the original ROM, name, which is missing from the source The readme gives no known CRC32, but names a ROM of the DAT: add it to the source, or check the revision the readme expects
No ROM of the DAT has this CRC32: the patch was made for another dump or for a hack Look for the ROM the readme of the patch asks for; for an IPS, choose a ROM for it in the Patches window
No ROM of the DAT has this CRC32: … or for another form of the ROM than the one the DAT describes (with another copier header, or without) For the NES, the Lynx or the Super Nintendo, the patch may have been made for the ROM with a header (or another header) when the DAT describes it without, or the reverse: a DAT of the other form will name it. For an IPS, choose its ROM and its Form in the Patches window
Neither the name of the IPS patch nor a text that comes with it gives the CRC32 of the original ROM Choose its ROM in the Patches window (see Choosing the ROM of a patch)
Unreadable patch The file is truncated, damaged, or of another format
The name of the patch gives the CRC32 of several ROMs of the source Choose the right ROM in the Patches window
A readme gives the CRC32 of several ROMs of the source Choose the right ROM in the Patches window
A readme gives the CRC32 of a ROM with and without its copier header Choose in the Patches window the form it was made for
The ROM you chose for this patch is not identified in the source It left the source, or the DAT no longer identifies it: choose another one, or go back to the automatic choice
The original ROM is part of a game in several files A .cue and its tracks, or a game on several disks: these games are not patched
The ROM does not have the size the patch expects It is not the ROM the patch was made for

A patch you set aside is not among them: the log says so apart (Patch set aside at your request). To silence a patch nothing fixes, set it aside (see Not applying a patch).

Without a DAT, the patches are not read: the log says so.

The Patches window

The Patches window shows every patch of the last simulation, and it is where you tell RomSieve what to do with them. It opens after a simulation:

The Patches window

On the left, the patches are grouped by state:

The search above the list keeps the patches whose name or folder holds every word, in any order (-word leaves out): FF3 extra only shows the patches of the Extra & Visual Patches folder of FF3. The groups, their counts and See the suggestions keep only the patches found. The cross clears the search.

On the right, the detail of the patch selected says in plain words where it stands (for a patch applied: what designates its ROM, and the name of its patched version), then gives its actions: Apply to this ROM and Do not apply this patch. Once you made a choice for the patch, its state line ends with a link that forgets it (see Not applying a patch). Under it, a line says your last change ("ROM chosen: …", "Patch set aside", "File renamed to …") and offers Undo (see Your choices).

The footer counts the patches modified. Run the simulation again runs the simulation again, which follows your choices: the window stays open and shows its results, on the same patch. If you close the window with choices the simulation has not seen yet, it runs again: the table always shows what your choices give.

Choosing the ROM of a patch

A UPS or a BPS designates its own ROM and checks it: no other one is chosen for it. For an IPS, the detail asks Which ROM is this patch for?:

Apply to this ROM saves your choice: the next simulation applies the patch to that ROM, whatever its name and its readme say. The file of the patch is not changed, and a patch stored in an archive is chosen like any other. While the current ROM of a patch applied is chosen, the button is greyed out. The Enter key never saves anything.

If a patched version does not work, because the patch was made for another ROM, choose the right one for it the same way: your choice wins over the CRC32 of its name and over its readme.

See the suggestions (n)…, on the title of the ROM proposed group, applies nothing: it shows for each patch the ROM chosen, then the folder of the patch and why the ROM is proposed ("The name of the patch starts with the title of this ROM"…), enough to judge each suggestion. Nothing is checked beforehand. Check those to apply (or Check all), then Apply (n); Back returns to the detail without saving anything.

Not applying a patch

Do not apply this patch sets the patch selected aside, whatever its format: the next simulation does not apply it, nor counts it among the patches not applied. It is also the way to silence a patch that applies to nothing and that you want to keep in the folder. The context menu of a patched version of the table offers the same action, which runs the simulation again at once.

To set aside at once the patches that will never apply (those that apply to a ROM already patched, for example), search for them, then click Do not apply the patches shown (n)…, under the search. The button is greyed out without a search, which would show every patch. It shows the list of the patches found, all checked, with their folder: uncheck those to keep, then Do not apply (n); Back saves nothing. Each patch set aside can then be taken back.

Back to the automatic choice, at the end of the state line of a patch you chose a ROM for, forgets your choice: the next simulation applies it again from what it records, its name or its readme. For a patch set aside, the link reads Take this patch back and does the same; Do not apply this patch is then no longer shown.

The patched version a sort already wrote in a destination stays in place: Undo Last Sort deletes it, if that sort is the last one.

Your choices

In the results

Undo

Each patched version is recorded in the journal of the sort: Undo Last Sort deletes it, unless it was modified since the sort. Your choices for the patches are not recorded in the journal: Undo Last Sort does not undo them (see Your choices).

On the command line

--patches <folder> gives the folder of the patches and applies them, even when Apply the patches is unchecked in the settings; --no-patches applies none, without changing the settings; --patch-only only writes the patched versions (see Command line). The folder of the patched versions comes from the settings file or the profile; a folder refused stops run as well as patches, with code 3. The summary counts the patched versions and the patches not applied.

romsieve-cli patches simulates the sort and lists all its patches: those it does not apply, with the ROMs proposed, those it applies and what designates their ROM, and those you set aside. The choices of the window are made there too, saved with --yes: --link <patch> --rom <ROM> applies an IPS to a ROM (its name, or the CRC32 of the form the patch was made for, required for a ROM with a copier header), --ignore <patch> sets a patch aside, --auto <patch> forgets your choice. --name-from-notes --yes writes the CRC32 in the name of the IPS applied thanks to their readme, for other tools.