Ips::Patcher

A Ruby library for applying IPS (International Patching System) patches to video game ROM files. IPS is a binary patch format commonly used to distribute patches for ROM images, such as translation patches, bug fixes, or game modifications.

• ✅ Apply IPS patch files to ROM images
• ✅ Support for standard IPS records (byte replacement)
• ✅ Support for RLE (Run-Length Encoding) records (efficient byte filling)
• ✅ Non-destructive patching (creates new file, original remains unchanged)
• ✅ Comprehensive error handling
• ✅ Pure Ruby implementation with no external dependencies

Add this gem to your application's Gemfile:

bundle add ips-patcher

Or install it directly:

gem install ips-patcher

• Ruby >= 3.1.0

The simplest way to apply an IPS patch to a ROM file:

require 'ips/patcher'

# Apply a patch to a ROM file
Ips::Patcher.apply("game.rom", "patch.ips")
# Creates: game.patched.rom

The patcher reads the ROM file and the IPS patch file, applies all patch records, and creates a new patched file. The output filename is automatically generated by inserting .patched before the file extension.

You can also specify a custom output path:

# Apply a patch with a custom output filename
Ips::Patcher.apply("game.rom", "patch.ips", output: "custom_output.rom")
# Creates: custom_output.rom

require 'ips/patcher'

# Apply a translation patch to a Super Nintendo ROM
Ips::Patcher.apply("super_metroid.sfc", "translation_jp_to_en.ips")
# Output: super_metroid.patched.sfc

1. Reads the ROM file and IPS patch file as binary data
2. Validates the patch file has a valid "PATCH" header
3. Processes each patch record:
   • Standard records: Replace bytes at a specific offset
   • RLE records: Fill bytes with a repeated value (when size is 0)
4. Creates a new patched ROM file. If no output path is specified, .patched is inserted before the file extension
5. The original ROM file remains unchanged

The IPS format is a simple binary patch format that stores:

• A "PATCH" header (5 bytes)
• One or more patch records containing:
  • Offset (3 bytes, 24-bit big-endian)
  • Size (2 bytes, 16-bit big-endian)
  • Data bytes (if size > 0) or RLE size and value (if size == 0)
• An "EOF" marker (3 bytes)

For more information about the IPS format specification, see: https://zerosoft.zophar.net/ips.php

The library raises Ips::Patcher::Error for patcher-specific errors:

begin
  Ips::Patcher.apply("game.rom", "patch.ips")
rescue Ips::Patcher::Error => e
  puts "Error applying patch: #{e.message}"
end

Common errors include:

• Invalid patch file (missing or incorrect "PATCH" header)
• File not found
• Permission errors
• IO errors

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

API documentation is available and can be generated using YARD.

To generate the documentation:

bundle exec rake doc

Or using YARD directly:

bundle exec yard doc

To view the documentation locally:

bundle exec yard server

Then open your browser to http://localhost:8808.

The generated documentation will be available in the doc/ directory.

Bug reports and pull requests are welcome on GitHub at https://github.com/meruen/ips-patcher. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Ips::Patcher project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.