Patcher Generation Tool

A tool that helps you quickly and easily make a patching webpage for your mod, which automatically detects the ROM a user loads and applies the proper version of your patch. No knowledge of web development is required on your part. This only works for SNES ROM mods at the moment.


Why make on online patcher
How to generate a patcher
Putting a patcher on Github
Integrating with an existing webpage
Other stuff

Why make an online patcher?

Applying ips files can be a pain in the ass, especially for people who haven't done it before. First they need to find an ips patcher and figure out how to use it. Then they'll often end up with a bad patch because the ROM header was missing (or present), or because they've patched the wrong version (and if they're lucky the patched ROM simply won't start; otherwise they'll get 5-30 minutes into playing before it starts glitching out).

This generator was made to alleviate all those problems. Once you've generated a patcher for your mod and put it online, someone who wants to play your mod can just go to your webpage, load their ROM, and the patcher does the rest. It'll automatically add or remove the header if necessary for the patch. If the user loads a zipped version of the ROM, it'll still be patched properly. If they load an unsupported version of the ROM, they'll get an error that tells them what version they have and what version they need. The patcher also performs a redundant integrity check when it finishes; if the modified ROM it produces contains a single byte with an incorrect value, the patcher emits an error instead of giving the user a glitchy ROM that appears to work when they first load it.

How to generate a patcher

Step 1:

In the generator, load any ROMs that you want the patcher to recognize & patch, by clicking the "Browse..." button in the "Base ROMs" column in the top table. To add more than one ROM, click the "Add supported ROM" button. (ROM data is not saved in the patcher; see the Other stuff section below for more info).

For each ROM, load the ips file used to patch it by clicking the "Browse..." button in the "Patch File" column; if you have a single ips file that will patch multiple ROM versions, load that same ips file on each row. Also add a version descriptor in the "Version" column (e.g. "1.0 US", or "1.1 JP").

If you have ips files for both unheadered and headered versions of the same ROM, you only need to load one of them (you won't be able to add both, since the patcher automatically adds or removes headers when necessary). Just make sure that that ips file works with the Base ROM you loaded (headering doesn't matter for your users, but it does matter here, since the headering of the ROM is used to determine if the ips requires a header or not).

Step 2:

If there are ROMs that your players are likely to mistakenly try patching (e.g. the EU version or version 1.1, when your patch only works on the US 1.0 version of the game), you can load these in the "Unsupported ROM" table, so your players will get specific errors telling them what version they have. This isn't strictly necessary for the patcher to work, but it will help prevent confusion as to why a player's ROM won't patch when their ROM "works perfectly fine".

Step 3:

Fill in the title of the game that you're patching, and the title of your mod. You can also set options pertaining to the patched ROM files that your patcher produces (e.g. the name of the file, if the file is headered, if it's zipped).

Step 4:

Hit the "Generate Patcher" button. If there aren't any errors, a "Save Patcher" button should pop up after a few seconds; hitting that will prompt you to save a .zip containing all the files for the patcher.

If you want to test the patcher out, extract all the contents of the zip and then double click the index.html file to see it in your browser (though if Chrome is your default browser, try opening it in Firefox or another browser; Chrome throws errors if you test locally with it, though once the patcher is online it will work fine with Chrome). Also, make sure you've actually unzipped everything: if you open the index.html file from within your zipping program or you only extracted index.html, it probably won't work.

Step 5:

Put it online. If you don't have a website or you know jack-shit about web development, don't worry; just scroll down to the Putting a patcher on Github section below for a walkthrough.

If you've got a website and want to put the patcher on there, see the Integrating with an existing webpage section.

You can play with the style of the patcher by modifying the patcher.css file in the patcher folder.

Putting a patcher on GitHub

You can host static websites for free on Github. The first step is to create an account (you'll need an email address for this; if you don't want to use your real one, you can create a quick burner account on Protonmail).

Once you've got a Github account, login and hit the "Start a Project" button. Once you're on the "Create a New Repository" page, set the Repository Name to be "" (where YourUserNameHere is your github user name), and then hit the "Create Repository" button at the bottom. Then in the "Quick Setup" section you should see a little link that says "uploading an existing file": click that, and then drag & drop in the index.html file, the file ending with cfg.js, and the patcher and patches folders (you should be dragging & dropping in these 4 items: if they're all inside a single folder, don't drag that folder in; grab those 4 things from within the folder). Then hit the "commit changes" button.

Wait a minute or so for github to get your page live, and then you should be able to go to and see the patcher. Then you can share that page with anyone who wants to play your mod.

Integrating with an existing webpage

First, unzip the zip that the generator produced, and then upload the patcher and patches folders to your server, along with the xxxcfg.js file (the xxx being some semi-randomly characters the generator chose).

Then in the html of the page you're adding the patcher to, you'll need to import all the contents of the patcher folder, along with that xxxcfg.js file. This should be a total of 5 javascript imports and 1 css import (ips.js, csmd5.js, jszipmin.js, main.js, xxxcfg.js, and patcher.css).

Finally, in the spot on your webpage where you'd like the patcher, put a div with a script tag in it that calls the injectPatcher function, like this:

The injectPatcher function takes two arguments, both of which you'll have to set. The first is a reference to an object called "xxxcfg"; replace the xxx with the same letters that precede the "cfg.js" in the name of that xxxcfg.js file. The second argument is a string specifying the relative path to the patches folder; this is similar to what you'd put for the src attribute of a script import, but make sure this path includes the patches folder itself and ends with a backslash, or else it won't be able to fetch the patches properly.

That should do it. You'll probably want to test the patcher out afterwards, to make sure that it's working properly. It might be a good idea to have your browser console open when you do this: if any of the imports are screwed up then your browser will print any related errors to the console (if you get any "Invalid CORS request" errors related to .ips files, it probably means that the path to the patches folder in the injectPatcher call is off).

If you'd like to add multiple patchers to the same page, you'll just need to upload the additional patcher's patches folder and it's yyycfg.js file, import the yyycfg.js file on the webpage, and then put in another div with the injectPatcher script (passing it the new "yyycfg" object and the relative path to the new patches folder).

Other stuff

Note that the ROMs are NOT stored in the patcher- they're only used right now by the generator to get metadata that's used to recognize the ROM when a user loads it, and to ensure that the the patches were applied correctly. ROM data is also never transmitted over the internet, neither now when you are using the generator or later when your users are using the patcher. All of the patching code is executed locally on each user's own machine.

If you end up changing your ips file later, don't just swap out the ips file in the patches folder; that'll cause errors. Rerun the generator and create a new patcher (I know, this is kind of a pain in the ass. I might add a way to make this easier in the future).