SMW Central BPS patching library

The JavaScript BPS patching library used by SMW Central, most notably for its Online Tools section.

Installation

NodeJS

Install from NPM using your favorite package manager:

$ npm install @smwcentral/bps
$ pnpm add @smwcentral/bps
$ yarn add @smwcentral/bps

You can then import the library as an ES module:

import * as bps from "@smwcentral/bps";

TypeScript declarations are built in.

Browser (CDN)

You can import the module directly from a CDN:

<script type="module">
    import * as bps from "https://cdn.jsdelivr.net/npm/@smwcentral/[email protected]/dist/index.js";
</script>

For convenience, use an import map:

<script type="importmap">
    {
        "imports": {
            "@smwcentral/bps": "https://cdn.jsdelivr.net/npm/@smwcentral/[email protected]/dist/index.js"
        }
    }
</script>

<script type="module">
    import * as bps from "@smwcentral/bps";
</script>

Usage

Apply BPS patch

The applyBPS function directly applies a BPS patch, with the base file and patch represented as a Uint8Array or equivalent.

import {readFileSync, writeFileSync} from "node:fs";
import {applyBPS} from "@smwcentral/bps";

const base = readFileSync("base.bin");
const patch = readFileSync("patch.bps");

const result = applyBPS(base, patch);

writeFileSync("result.bin", result);

If patching fails, PatchError will be thrown:

• MalformedPatchError: The patch is not a BPS patch
• WrongInputSizeError: The input file has a wrong size
• WrongInputChecksumError: The input file has a wrong checksum

Apply BPS patch adaptively

The adaptiveApplyBPS function applies a BPS patch and attempts to make adaptations to the input file. The optional 3rd arguments allows you to tweak which adaptations are enabled (by default, everything is enabled).

import {readFileSync, writeFileSync} from "node:fs";
import {adaptiveApplyBPS} from "@smwcentral/bps";

const base = readFileSync("base.bin");
const patch = readFileSync("patch.bps");

const result = adaptiveApplyBPS(base, patch, {
    trySMC: true,
    trySMB2: true,
});

writeFileSync("result.bin", result);

The following adaptations are currently supported:

• trySMC: If enabled, a patch made for a headerless SNES ROM (.sfc) can be applied to a headered input ROM (.smc). In this case, the result will be a headered ROM (.smc). Note that patches generated by Flips (such as most BPS patches on SMW Central) are typically based on a headerless ROM, even if the original base ROM was headered.
• trySMB2: If enabled, patches made for Super Mario Bros. 2 can be applied to any commonly used ROM (Rev 0, Rev 0 in NES 2.0 format, and Rev A), no matter the combination of patch and input ROM.

Tests

Complete tests are available in the tests directory. Run with:

$ npm test

Some tests require commercial ROM files to be available in order to run. These tests will be skipped by default. In order to run the full test suite, you need to supply the following the ROM files, which are presumably personal backups of the copies of the respective games that you already own:

47ba60fad332fdea5ae44b7979fe1ee78de1d316ee027fea2ad5fe3c0d86f25a  Super Mario Bros. 2 (U) (PRG0) [!].nes
41300bc4942a8a4f9b53148b404dd5cae3dd708ebdd9b617888d290a51a83e43  Super Mario Bros. 2 (USA).nes
6ca47e9da206914730895e45fef4f7393e59772c1c80e9b9befc1a01d7ecf724  Super Mario Bros. 2 (USA) (Rev A).nes
0838e531fe22c077528febe14cb3ff7c492f1f5fa8de354192bdff7137c27f5b  Super Mario World (U) [!].sfc
d70c9c7716ad12c674fc7dd744736aa48d4d7b4237f58066be620fda26024872  Super Mario World (U) [!].smc

Place any ROMs you have in the tests/roms directory with exactly the filenames listed above. The test suite will automatically detect the ROMs, validate their checksum, and enable any tests that use them.

License

Released under the MIT License.

Credits

Built and maintained by Telinc1. Original JavaScript BPS patcher by Sir_Walrus. SMC support by trillian. Super Mario Bros. 2 support by CircleFriendo.