IPS Patcher

A Python utility for applying International Patching System (IPS) patches to ROM files, particularly useful for ROM hacking and homebrew development.

Features

• ✅ Apply IPS patches to ROM files
• ✅ Support for both normal and RLE (Run-Length Encoding) patches
• ✅ Automatic ROM size extension when needed
• ✅ Verbose debugging output
• ✅ Command-line interface with argparse
• ✅ Proper error handling and validation
• ✅ Cross-platform compatibility

Installation

Clone this repository:

git clone <repository-url>
cd ips-patcher

No additional dependencies required - uses only Python standard library.

Usage

Basic Usage

python ips_patcher.py original_rom.gba patch.ips patched_rom.gba

With Verbose Output

python ips_patcher.py --verbose original_rom.gba patch.ips patched_rom.gba

Show Help

python ips_patcher.py --help

Show Version

python ips_patcher.py --version

Examples

Pokemon ROM Hacking

# Apply a Pokemon Emerald ROM hack patch
python ips_patcher.py "Pokemon Emerald.gba" "seaglass_v3.ips" "Pokemon Emerald - Seaglass v3.gba"

# With verbose output to see patch details
python ips_patcher.py -v "Pokemon Emerald.gba" "seaglass_v3.ips" "Pokemon Emerald - Seaglass v3.gba"

IPS Format Support

This tool supports the complete IPS format specification:

• Normal patches: Direct byte replacement at specified addresses
• RLE patches: Run-length encoded patches for efficient large area modifications
• ROM extension: Automatically extends ROM size when patches write beyond current file size
• EOF marker: Proper handling of IPS EOF termination

Development

Project Structure

ips-patcher/
├── ips_patcher.py     # Main patcher script
├── README.md          # This file
├── requirements.txt   # Python dependencies (none currently)
└── tests/            # Unit tests (planned)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Future Enhancements

• GUI interface
• Batch processing support
• UPS patch format support
• Patch creation functionality
• ROM checksum validation
• Unit tests
• CI/CD pipeline

Technical Details

IPS Format

The International Patching System (IPS) is a binary format for describing differences between two files. It consists of:

1. Header: 5-byte "PATCH" identifier
2. Records: Variable-length records containing:
   • 3-byte address (big-endian)
   • 2-byte length (big-endian)
   • Data bytes (or RLE specification if length = 0)
3. EOF: 3-byte "EOF" terminator

RLE Encoding

When a record has length = 0, it indicates RLE encoding:

• 2-byte RLE length (big-endian)
• 1-byte value to repeat

License

MIT License - See LICENSE file for details

Changelog

v1.0.0 (2025-08-25)

• Initial release
• Complete IPS format support
• Command-line interface
• Verbose debugging mode
• Cross-platform compatibility

Acknowledgments

• Developed for ROM hacking workflow
• Tested with Pokemon Emerald Seaglass v3.0 patch
• Thanks to the ROM hacking community for the IPS format specification