rompatcher.js

The Docker setup relies on a specific directory structure to manage inputs and outputs via volumes. Files placed in input/ and output/ are visible on your host machine.

project-root/
└── docker/
  ├── .gitignore
  ├── .dockerignore
  ├── docker-compose.yml
  ├── Dockerfile
  ├── entrypoint.sh
  ├── input/   # Place ROMs and patches here
  └── output/  # Patched ROMs will appear here

Rom Patcher JS can be run in a Node.js environment via the command line. This allows for automated patching and patch creation processes.

Installation

First, install the necessary dependencies:

npm install

Patching a ROM

To apply a patch to an existing ROM file:

node index.js patch "my_rom.bin" "my_patch.ips"

Creating an IPS patch

To generate a new IPS patch by comparing an original ROM with a modified version:

node index.js create "original_rom.bin" "modified_rom.bin"

CLI Help

To view all available options and flags for the patch or create commands:

node index.js patch --help
node index.js create --help

You can embed Rom Patcher JS into your own website to provide an online ROM patching service. This allows users to patch ROMs directly in their browser without downloading patch files locally.

To get started, use the index_template.html file provided in the repository as a functional baseline for your implementation. For more complex integration requirements, refer to the project's wiki.

<!-- Use index_template.html as a starting point for your implementation -->

You can run RomPatcher.js inside a Node.js container to patch ROM files without installing Node.js on your host machine. The setup uses Docker volumes to manage files:

• Input: Place your ROMs and patch files (*.bps or *.zip) in the docker/input folder.
• Output: Patched ROMs are automatically saved to the docker/output folder.

ZIP patch files are automatically extracted by the container during the process.

# From inside the docker/ directory
docker-compose up --build

You can run Rom Patcher JS using Docker Compose. The configuration defines a service named rompatcher that builds from the repository root using the Dockerfile located at docker/Dockerfile.

To manage input and output files, the following host directories are mapped to the container:

• ./input maps to /app/input inside the container.
• ./output maps to /app/output inside the container.

Ensure you have created these local directories before running the container to avoid permission issues or unexpected behavior.

services:
  rompatcher:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    container_name: rompatcher
    volumes:
      - ./input:/app/input
      - ./output:/app/output
    restart: "no"

To patch a specific game, follow these steps:

1. Place your ROM file (e.g., MyGame.v64) into the docker/input directory.
2. Place your patch files (supporting *.bps or *.zip formats) into the docker/input directory.
3. Navigate to the docker folder and run the build command.
4. Retrieve your patched ROM from the docker/output directory.

cd docker
docker-compose up --build

Rom Patcher JS supports a wide variety of patch formats for different consoles and use cases, including:

• IPS
• UPS
• APS (N64/GBA)
• BPS
• RUP
• PPF
• EBP
• BSDiff (.bdf, .bspatch)
• Paper Mario Star Rod (.mod)
• VCDiff (.xdelta, .vcdiff)

The following options are available when using the create command to specify the output patch format.

-f, --format <format>       patch format (allowed values: ips [default], bps, ppf, ups, aps, rup, ebp)

The following options are available when using the patch command to control how the ROM is processed and validated.

-v, --validate-checksum    should validate checksum
-h1, --add-header           adds a temporary header to the provided ROM for patches that require headered ROMs
-h0, --remove-header        removes ROM header temporarily for patches that require headerless ROMs
-f, --fix-checksum         fixes any known ROM header checksum if possible
-s, --output-suffix        add a (patched) suffix to output ROM file name

Use the patch command to apply a patch file (e.g., IPS, BPS, etc.) to a target ROM file. The command requires the path to the ROM and the path to the patch file as arguments.

node index.js patch "my_rom.bin" "my_patch.ips"

Use the create command to generate a patch file by comparing an original ROM with a modified ROM. You can specify the desired patch format using the --format option.

node index.js create "original_rom.bin" "modified_rom.bin"