mirror of
https://github.com/marcrobledo/RomPatcher.js.git
synced 2025-06-27 16:25:54 +00:00
Created Embedding Rom Patcher JS (markdown)
Marc Robledo
parent
2326dfe417
commit
5ba1089794
1 changed files with 209 additions and 0 deletions
209
Embedding-Rom-Patcher-JS.md
Normal file
209
Embedding-Rom-Patcher-JS.md
Normal file
|
|
@ -0,0 +1,209 @@
|
|||
# Embedding Rom Patcher JS in your site
|
||||
If you are self-hosting your own translations and/or hack patches, you can embed Rom Patcher JS and provide a nice solution for your users, allowing them to easily apply your patches to their ROMs without requiring them to download a single file, all thanks to the magic of the web!
|
||||
|
||||
Take a look at [`index_template.html`](https://github.com/marcrobledo/RomPatcher.js/blob/master/index_template.html) for a template. Basically you need to:
|
||||
|
||||
1. [Download the latest version](https://github.com/marcrobledo/RomPatcher.js/releases) and copy the entire `rom-patcher-js/` folder to your site
|
||||
2. Include **all** file imports from the `<header>` into yours:
|
||||
```html
|
||||
<link type="text/css" rel="stylesheet" href="./rom-patcher-js/style.css" media="all" />
|
||||
<script type="text/javascript" src="./rom-patcher-js/modules/BinFile.js"></script>
|
||||
...
|
||||
<script type="text/javascript" src="./rom-patcher-js/RomPatcher.js"></script>
|
||||
<script type="text/javascript" src="./rom-patcher-js/RomPatcher.webapp.js"></script>
|
||||
```
|
||||
3. Copy the needed HTML structure from `index_template.html`:
|
||||
```html
|
||||
<div id="rom-patcher-container">
|
||||
...
|
||||
</div>
|
||||
```
|
||||
4. Build a quick patcher with a simple call to `RomPatcherWeb.initialize`:
|
||||
```html
|
||||
<script type="text/javascript">
|
||||
window.addEventListener('load', function(){
|
||||
const myPatcherSettings={
|
||||
language: 'en',
|
||||
allowDropFiles: false /* if true, it adds drag and drop support,*/
|
||||
};
|
||||
RomPatcherWeb.initialize(myPatcherSettings, 'my_patch.ips');
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Providing additional patch information
|
||||
If you want to improve the user experience, you can provide additional information of your patches.<br/>
|
||||
Instead of a simple file path, you can build a JSON object like this:
|
||||
```js
|
||||
RomPatcherWeb.initialize(myPatcherSettings, {
|
||||
file: 'my_hack.ips',
|
||||
name: 'My game improvement (v2.0)', //patch name that will appear in the dropdown button
|
||||
inputCrc32: 0xdeadbeef, //add checksum validation to patch, will warn user if the ROM is not valid
|
||||
description: 'This patch translates the game and fixes bugs!', //short description that will appear when user picks this patch
|
||||
outputName: 'My game (Hack)' //patched ROM name
|
||||
});
|
||||
```
|
||||
It is recommended, though, to store the patch or patches in a single zip file:
|
||||
```js
|
||||
RomPatcherWeb.initialize(myPatcherSettings, {
|
||||
file: 'my_patches.zip', //zip containing patches
|
||||
patches: [ //information about patches inside the zip
|
||||
{
|
||||
file: 'my_hack.ips', //required, must match the patch file name in the zip
|
||||
name: 'My game improvement hack (v2.0)',
|
||||
inputCrc32: [0xdeadbeef, 0xd0d0cafe], //an array of valid checksums
|
||||
description: 'This patch translates the game and fixes bugs! (Recommended)',
|
||||
outputName: 'My game improvement'
|
||||
},
|
||||
{
|
||||
file: 'my_hack_vanilla.ips',
|
||||
name: 'My game improvement hack (v2.0, no bugfixes)',
|
||||
inputCrc32: [0xdeadbeef, 0xd0d0cafe],
|
||||
description: 'This patch translates the game but keeps the original game\'s bugs untouched for a vanilla experience',
|
||||
outputName: 'My game improvement'
|
||||
},
|
||||
/* ... */
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Events
|
||||
If you want to go further, you can run your own code via events:
|
||||
```js
|
||||
const myPatcherSettings={
|
||||
language: 'en',
|
||||
|
||||
onloadrom: function (romFile) {
|
||||
/* this event is triggered when user provides a ROM and before validating it */
|
||||
/* can be used to: */
|
||||
/* - modify it before validation (e.g. add/remove/fix header, change endianness...) */
|
||||
/* - to switch to another patch file in the dropdown selector */
|
||||
},
|
||||
onvalidaterom: function (romFile, isRomValid) {
|
||||
/* this event is triggered after ROM is validated */
|
||||
/* can be used to show a custom error message if provided ROM is not valid */
|
||||
},
|
||||
onpatch: function (romFile) {
|
||||
/* this event is triggered a ROM is patched */
|
||||
/* can be used to modify it before the patched ROM file is saved */
|
||||
}
|
||||
};
|
||||
```
|
||||
In all events, the `romFile` parameter is an instance of [BinFile.js](https://github.com/marcrobledo/RomPatcher.js/blob/master/rom-patcher-js/modules/BinFile.js), which allows easy file data and name manipulation.
|
||||
|
||||
|
||||
|
||||
|
||||
### Example: Fix ROM endianness
|
||||
N64 ROM files are usually stored in `.z64` (Big Endian) or `.n64` (Little Endian) formats. You can make your patcher compatible with both formats by changing the provided ROM file endianness before patching (and then restoring it after patching).<br/>
|
||||
```js
|
||||
const SSB_LITTE_ENDIAN_CRC32 = 0xf0b7c200;
|
||||
var romIsLittleEndian;
|
||||
|
||||
RomPatcher.initialize(
|
||||
{
|
||||
onloadrom:function(romFile, patch){
|
||||
/* if ROM is little endian */
|
||||
if(romFile.getExtension()==='n64' && romFile.hashMD5()===SSB_LITTE_ENDIAN_CRC32){
|
||||
/* change endianness to big */
|
||||
romFile.swapBytes(4);
|
||||
/* change extension */
|
||||
romFile.setExtension('z64');
|
||||
|
||||
romIsLittleEndian=true;
|
||||
}else{
|
||||
romIsLittleEndian=false;
|
||||
}
|
||||
},
|
||||
onpatch:function(patchedRomFile){
|
||||
/* if ROM was little endian */
|
||||
if(romIsLittleEndian){
|
||||
/* revert endianness to little */
|
||||
romFile.swapBytes(4);
|
||||
/* revert extension */
|
||||
romFile.setExtension('n64');
|
||||
}
|
||||
}
|
||||
}, {
|
||||
file: 'smashremix1.5.2.xdelta',
|
||||
inputCrc32: 0xeb97929e,
|
||||
name: 'Smash Remix v1.5.2',
|
||||
outputName: 'Smash Remix v1.5.2 (Hack)'
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
|
||||
### Example: Choose correct patch automatically
|
||||
If your zip file contains several patches for different ROMs, you can make Rom Patcher JS so it picks automatically the patch for the provided ROM.
|
||||
```js
|
||||
const SML2_CHECKSUM_WORLD = 0xd5ec24e4;
|
||||
const SML2_CHECKSUM_JAPAN = 0xa715daf5;
|
||||
const SML2_CHECKSUMS_INVALID = [0xe6f886e5, 0x635a9112, 0xbf733e10, 0x29e0911a];
|
||||
|
||||
RomPatcher.initialize(
|
||||
{
|
||||
onloadrom: function (romFile) {
|
||||
const crc32 = romFile.hashCRC32();
|
||||
/* if ROM region is USA/Europe */
|
||||
if (crc32 === SML2_CHECKSUM_WORLD)
|
||||
RomPatcherWeb.pickEmbededFile('SML2DXv181.ips');
|
||||
/* if ROM region is Japan */
|
||||
else if (crc32 === SML2_CHECKSUM_JAPAN)
|
||||
RomPatcherWeb.pickEmbededFile('SML2DXv181_jap.ips');
|
||||
},
|
||||
onvalidaterom: function (romFile, isRomValid) {
|
||||
const crc32 = romFile.hashCRC32();
|
||||
/* if ROM is a known SML2 revision that is not compatible with the patch*/
|
||||
if (!isRomValid && SML2_CHECKSUMS_INVALID.indexOf(crc32) !== -1)
|
||||
RomPatcherWeb.setErrorMessage('Please provide a v1.0 SML2 ROM');
|
||||
}
|
||||
}, {
|
||||
file: 'SML2DXv181.zip',
|
||||
patches: [
|
||||
{
|
||||
file: 'SML2DXv181.ips',
|
||||
name: 'Super Mario Land 2 DX - 6 Golden Coins (v1.8.1)',
|
||||
inputCrc32: SML2_CHECKSUM_WORLD,
|
||||
description: 'SML2 colorization hack (USA/Europe) by toruzz',
|
||||
outputName: 'Super Mario Land 2 DX - 6 Golden Coins (Hack)',
|
||||
outputExtension: 'gbc'
|
||||
},
|
||||
{
|
||||
file: 'SML2DXv181_jap.ips',
|
||||
name: 'Super Mario Land 2 DX - 6-tsu no Kinka (v1.8.1)',
|
||||
inputCrc32: SML2_CHECKSUM_JAPAN,
|
||||
description: 'SML2 colorization hack (Japan) by toruzz',
|
||||
outputName: 'Super Mario Land 2 DX - 6-tsu no Kinka (Hack)',
|
||||
outputExtension: 'gbc'
|
||||
}
|
||||
]
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
|
||||
### Example: Remove header
|
||||
SNES ROM files are usually stored in `.sfc` (headerless) or `.smc` (headered) formats. You can make your patcher compatible with both formats by detecting if the ROM is headered and remove the header before the ROM is validated.<br/>
|
||||
```js
|
||||
RomPatcher.initialize(
|
||||
{
|
||||
onloadrom: function (romFile) {
|
||||
const SMC_HEADER_SIZE=512;
|
||||
if(romFile.getExtension()==='smc' && ((romFile.fileSize - SMC_HEADER_SIZE) % 0x20000) === 0){
|
||||
romFile.removeLeadingBytes(SMC_HEADER_SIZE);
|
||||
romFile.setExtension('sfc');
|
||||
console.log('removed SMC header');
|
||||
}
|
||||
}
|
||||
}, {
|
||||
file: 'Tekkaman Blade v1.0.rup',
|
||||
name: 'English translation by D and Near',
|
||||
outputName: 'Uchuu no Kishi Tekkaman Blade (English v1.0)',
|
||||
}
|
||||
);
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue