Skip to content

Added patches option to rom Run Menu#18825

Open
Zal0 wants to merge 2 commits intolibretro:masterfrom
Zal0:patches_menu
Open

Added patches option to rom Run Menu#18825
Zal0 wants to merge 2 commits intolibretro:masterfrom
Zal0:patches_menu

Conversation

@Zal0
Copy link
Copy Markdown

@Zal0 Zal0 commented Mar 14, 2026

Guidelines

  1. Rebased before opening this pull request
  2. This PR contains a single feature change
  3. Intended to be squashed into a single commit
  4. Follows existing RetroArch coding and menu patterns

Description

Added support to load patches files from a file that contains a list of patches per line instead of the current way (renaming patches to match the romfilename and have consecutive numbers)

Also added a Patches submenu to the playlist entry action menu to create and maintain the patches file for each rom. The submenu allows the user to add, remove and reorder the list of patches
patches option

When content is launched, the entries listed in the .patches file are applied in order. If no .patches file exists, RetroArch falls back to the existing patch loading behavior.

Patches paths are relative to a new patches folder added to settings directory list, by default set to "retroarch base"/patches. Support to set this directory from the settings->directories menu has also been added. This will open the door to the creation of a patches database that every user could download
patches_dir

Patches files containing the list of patches will be created in the same folder as the rom, changin the extension to .patches

Tested manually on Windows and Switch. Tested on Menu Drivers: ozone, glui, xmb and rgui

Notes:

  • Patches Directory default path handling may need broader cross-platform review
  • the current menu icon is temporary and may be adjusted in a follow-up

Related Issues

Related Pull Requests

  • None

Reviewers

  • N/A

@LibretroAdmin
Copy link
Copy Markdown
Contributor

Hi, this doesn't seem to compile on some platforms. Can you take a look?

@hizzlekizzle
Copy link
Copy Markdown
Collaborator

I asked for some opinions on this from the other contributors in our Discord server but haven't head much back yet.

From my perspective, it seems good, but I'm concerned the patch folder might get very messy very quickly. My preferred workflow would be for the patches to go into a folder named like the ROM, and then the *.patches manifest could go in there, too. However, I know some people like to keep their ROM directories "clean" and free from any additional metadata, etc., which would match up with the current workflow in the PR

@Zal0
Copy link
Copy Markdown
Author

Zal0 commented Mar 19, 2026

The patches folder is only for the patches which is expected to be in the form

/patches
  /playlist0
     /rom0
       patch0.ips
       patch1.ips
       ...
       patchN.ips
     /rom1
       patch0.ips
       patch1.ips
       ...
       patchN.ips
     /rom2
       patch0.ips
       patch1.ips
       ...
       patchN.ips
  /playlist1
  /playlist2
  ...

My first approach was to try to place the .patches file containing the list of patches inside that folder too, but I had problems trying to locate the playlist when launching the rom, it is not stored anywhere and also the same rom could be in two different playlists, etc
So I ended up putting the .patches file next to the rom, which is probably not ideal but I run out of ideas here. I tried the config folder too, but then again I didn't know the system or the playlist and just storing it as .patches could cause collisions between different roms with the same name

@hizzlekizzle
Copy link
Copy Markdown
Collaborator

I think putting it beside the ROM makes good sense.

Re-reading your explanation on how the paths work, I think we can ignore my earlier concerns about organization, since you can put them in subdirectories any way you like. I was thinking all of the actual patch files had to go into the top level, which would be very messy, but that doesn't seem to be the case.

@brianblakely
Copy link
Copy Markdown

I don’t believe this feature treats the patched content as a new content entry? That was something I tried to make happen, failing because it just touched too many systems. The ultimate goal was to have separate saves/states for all the amazing total-conversion mods created by people like Kaze Emanuar.

Still, having a UI for patches is an awesome step forward. May I suggest calling them Mods, instead of Patches, as that has become more common nomenclature the last couple years?

@Zal0
Copy link
Copy Markdown
Author

Zal0 commented Mar 20, 2026

No, this just tries to improve the way patches are selected right now
https://docs.libretro.com/guides/softpatching/
which I thought was a temporal solution until someone could find some time to add the proper menus

I think treating patched roms as new entries is a different problem that need to be treated apart (see all the comments in #16378)

There are a few workarounds right now:

  • using hardlinks, which is not supported in all platforms and it's a bit tedious
  • Having a 7zip with all the patched roms which is already supported, like we did in the old days of goodroms goodmerged

For the second option we didn't even need a patching solution.

I still think patching is a good thing and that this PR opens the door to finally have a database that could be downloaded to have all the common patches in one place: like translations, fastrooms, bugfixes... etc

@i30817
Copy link
Copy Markdown
Contributor

i30817 commented Mar 28, 2026

Multiple patches should use the current retroarch softpatch naming scheme so users dont have to rename them if they want to try this and there aren't two enumerated softpatch schemes in the emulator

rom.format (ups, bps, ips, xdelta if you build with xdelta which is off by default), rom.format1..., rom.formatN

The softpatch directory should be in the game folder, not system or similar because one of the ways to run retroarch roms is remotely (SAF links can point to a local webdav for instance) and doing it like that is just asking to have different results on different devices or to accidentally delete patches.

Generally I won't use this system myself because of a few reasons.

  1. I use linux as the roms server, so I can hardlink if I want
    1.b. Unfortunately you can't softpatch (I hardpatch and keep a revert patch) cds (at least by default, since xdelta isn't enabled and all cd cores have a setting that disables cd softpatch even if it worked otherwise (needs_fullpath="false" iirc), so hardlinks aren't that useful. Chd child parent support may change this in a different way but it requires core agreement on a common strategy to find the "parent" which I'm pessimistic about (sanest is looking under the same dir or the parent dir for chd files holding the memorized header sha1 of the parent - which is part of the child chd header - so game hacks would be in the same directory as the parent or a directory immediately beneath it).
  2. I keep a rom per set of hacks I want anyway, so its a easy 1 game 1 entry in the the playlist even if a entry uses multiple softpatches. So I don't need to enable or disable patches. In fact I think that will cause trouble with save states and save files. To be fair, so do patch update.
  3. I have my own tool to check for patch updates and renaming roms when their nointro/redump names change that needs softpatches in the same directory as usual to also rename those. As data for the patch update I already have a simple 2 line per patch file format (version, url, repeated) with a link to the rom romhacking.net patch page so I can already Id softpatches. As a aside, for translations if you keep the original rom filename¹, you still get the original language thumbnails.
  4. Retroarch/libretro doesn't actually id patches, even if I used the automatic scanner (I use the manual scanner). So trying to systematize or integrate a patch collection file format has limited utility on retroarch-as-is-right-now. Their names or checksums aren't in the databases and so isnt any info about them.

¹ My renaming tool recognizes that rom filenames without "(" on them are likely softpatch hacks and gently reminds you might not want to change them. Translations as mentioned, keep the original name so likely have "(", so get renamed when the set dat filename changes.

@Zal0
Copy link
Copy Markdown
Author

Zal0 commented Mar 28, 2026

Thanks for your comments, really appreciate them. Let me discuss them a little bit :)

The current patch system still works for people who prefer it (mostly backwards compatibility). The main reason I worked on this is because I think it was just a workaround to avoid adding menus to properly selecting the patches. I see no advantage at all on forcing people to rename the patches.You lost track of what patch0 is for or why it needs to go before patch1

Patches are in a separate folder for people who prefer having this separated from their rom collections. But since you can select the folder you can easily place roms and patches together

  1. I read about your hard link system on discord. I understand it works for you but I don't think is a solution that works for everyone. I use retroarch on switch for instance. I think I prefer the 7z system mentioned above. It's just more portable. But 7z roms were replaced with nointro roms long ago... I don't think most people will want to go back there
  2. Yes, patching the roms will cause problems with savestates. This PR doesn't try to solve this
  3. I never rename my roms. If I do the thumbnails will stop working and probably savestates and more stuff will lost track of them. Again, it's a solution that works for you, with your script... But I try to think on the average user
  4. I could share my patches folder right now with you and you will have access to all my patches without having to do any extra work. Just download, place it in the patches folder and select which ones you want in the order you want. In the future it could be posible to share a collection of patches in retroarch same as we have a cheats collection, thumbnails, free content.. etc

One of the main issue I see with retroarch is that sometimes is not very user friendly. Solutions that require external scripts, hard links, etc will work. But I try to think on the average user who just want to play a japanesse rom in its own language and make things easier for him. I worked in this PR because I saw a lot of potential on the patching system but the current was just not the best

If this PR gets merged into retroarch I will happily work on improving the selection of patches with screenshots, a full description, link to authors, etc

@i30817
Copy link
Copy Markdown
Contributor

i30817 commented Mar 28, 2026

About 3.

Thumbnails in retroarch (those that are not manually placed there by users ofc) follow the naming scheme of the main set dat (redump, nointro mostly).

When those dats change a rom filename, often a few weeks or months later, the thumbnails also change their name on the libretro thumbnails server. So name changes are actually necessary to keep thumbnails, at least if you're downloading new. Since I keep translations with the original names (which do have thumbnails in retroarch) this is actually relevant for softpatches.

About saves and savestates, I could probably rename those too, that's a good idea.

About 4. This only matters if the user doesnt have the right name, which, true, users often dont or dont have the knowhow to realize the problem is the naming. I dont care about it really, except that if there is any chance of I using it, it must use the same extensions scheme softpatches already do (the rest of the name can be ignored for this scheme), so I can just move the softpatches.

However the way you try to organize them all into a single directory hierarchy following playlists is a deal breaker.

I dont care if you have a grand plan to share a patches directory of tens of hundreds of gb translations (impractical) which is the only reason why I think you'd bother unifying these, the same concerns about losing the patches accidentally (my roms aren't even in the same device as the retroarch running them and I really don't like how mesen hd packs pollute the system directory and get lost on retroarch reinstalls too) or getting lost in the maze apply.

Edit: this objection is withdrawn, I didn't notice you could configure the patches dir, that would allow a remote dir.

At the very least, if youre ride or die about a unified softpatch rom directory, well, I guess I won't use this, since there is really little point if you already require a patches file in the rom directory anyway (no plug and play download with a single step). For the creator of those patches files (which would be me most likely when I tried to use this) its just another layer of indirection that obfuscates which roms are actually being used.

Btw if your patch file format doesn't support it yet, I suggest you add "groups" of patches that can be used all at once or not, if the ideal is the patches option to load up a "complete hack" of a base rom always in the playlist.

That's the main use of the numeric ips1, ips2 extension from retroarch, keep the addendum patches seperate so they can be updated separately and dont force the user to hardpatch addendum hacks.

Btw, I really think if you can merge this you should make it so the patches file is part of the patches dir, not the rom dir. The maintaners of your hypothetical grand rom softpatches directory are the ones that should create those files because they would have the knowhow.

Ie translation abc can be ran alone or with addendum patch zxy, and a 3rd patch can be applied whenever. You'd never get all combinations this way but the majority of the useful ones are possible

For instance shin megami tensei has the original aeon genesis translation, a addendum patch that fixes some demon names and spells to modern names and a patch to enable a minimap button like SMT2.

4 useful combinations. Then "simply" disable the entries where you dont have at least one patch when the user enters the patches menu.

Duplicate games in different playlists can be symlinked directories or the git equivalent, or the zipped up equivalent if zipped megapatches roms are in the table. For running roms direct from the cmd line you'd probably could search for combinations of playlists with the core and game if soft patching was on.

You'll have more success with this if you only have 1 step for the final user.

Though for users like me that would never download a entire huge collection of patches I'd never use I still say that a rom directory fallback should be a possibility to download individual games patch collections, ie I used git archive --format zip --remote ssh://server.org/path/to/patches HEAD "Sony - PlayStation/Final Fantasy VII" > ff7.zip to download all ff7 softpatches if there were any and unzip them directly as a subdir "patches" of the ff7 folder.

The above is just a example you dont have to be the one to "fix" soft patching for multiple files (although it would be nice, for diskettes at least and if it didn't break with m3u files).

@Zal0
Copy link
Copy Markdown
Author

Zal0 commented Mar 29, 2026

The patches file is not mean to be dristributed. It just the current config of your patches for a given rom. It's up to the user to select which patches he want to use and in which order

I don't like that this file is stored within the roms either, but I did a few attempts and nothing else worked. I was now thinking that maybe I could access the current system from the current core and use that to store them in the config folder (something like config/patches)

@i30817
Copy link
Copy Markdown
Contributor

i30817 commented Mar 29, 2026

If there is no ambition to distribute sets of files or to recognize valid patch combinations there is no reason and plenty of reason against (obfuscation) to have a parallel patches directory that isn't even in the game directory.

Centralization is usually required by distribution. If youre going to make the users do all the work anyway might as well ditch the file and let it be a directory in the game folder with a subdir per patch set and single files for single hacks.

Changing extensions is easier than creating a text file and copy over the filenames.

Like so:

Patches
-------------Patch set dir user choose name/
-----------------patchrandomname.ips
-----------------Another.ips1
-----------------YetAnother.ips2
-------------standalonepatch.bps

The whole point of a index file is to do this organization by third parties that would update it show off new possible hacks to see (or only those the user has depending on what the user wants) and (maybe) warn when the file changed or needs a update (with various ways possible, from silent updates changing the names, to a checksum check, to a file size check, to storing a version local number and check against the "new" file). Without those 3rd parties it makes little to no sense. If the idea is just having a source url, or a bit of 'description' in addition so it can appear in Retroarch, again, users will not do that sort of thing by themselves.

@hizzlekizzle
Copy link
Copy Markdown
Collaborator

I think we should be careful not to let perfection be the enemy of good. It also doesn't need to be fully formed right out of the gate.

That is, once the initial feature is in place, we can see how people use it (or why they can't/don't) and tweak/improve it from there to better suit the prevailing or emergent use-cases.

@i30817
Copy link
Copy Markdown
Contributor

i30817 commented Mar 29, 2026

At least nail down how are multiple medium patches going to work, for the future. Not so much for cds and cd tracks, since I still hope chd parent-child wins because its generic and only requires core agreement on the search strategy and a library with chd support, but floppies.

Also if you want readme available inside retroarch, well most of the patches come with them. Might want to require subdirs for even standalone patches then, so retroarch can search the .txt files in subdirs and know they refer to patches in that hack (set). For multiple patches sets, the same extension trick could be used (or just show all .txt files/allow the user to cycle them).

This would kind of appeal to the laziness of users. Doesnt get any simpler for 98% of (non cd, non multiple floppies, non "optional patches", non "convert the patch or file first") than "unzip in the patches directory in the rom directory and let the unzip tool create the dir with the text file you can read for you".

Or even "just put the zip in the patches directory", if you treat a zip as a directory.

Plenty of room for user error here, but isn't there always

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants