RPGMakerXP-Tools (C++ Edition)

A collection of C++ utilities for extracting, inspecting, editing, and rebuilding Scripts.rxdata files used by RPG Maker XP.

These tools allow you to work with your game's scripts directly from the command line — view them, search through them, and even rebuild a new rxdata file from edited files.

---

Features

• Extract all scripts from an .rxdata file to individual .rb source files.
• Display a single script's contents directly in your terminal.
• Search for functions across all scripts by name.
• Export a specific script to a standalone Ruby file.
• Recompile modified .rb scripts back into a valid .rxdata file.
• Works fully offline — no need for RPG Maker itself.
• Fast native performance with no runtime dependencies.

---

Repository layout

RPGMakerXP-Tools/
├─ include/
│  ├─ utils.hpp                          # Shared utility declarations
│  ├─ script_processor.hpp               # Script processing function declarations
│  └─ ruby_marshal.hpp                   # Ruby Marshal format reader/writer
├─ src/
│  ├─ utils.cpp                          # Shared helpers for loading/decompressing data
│  ├─ script_processor.cpp               # Script processing implementations
│  ├─ ruby_marshal.cpp                   # Ruby Marshal format implementation
│  ├─ extract_all_scripts.cpp            # Dump every script into separate .rb files
│  ├─ display_script.cpp                 # Print a single script's source
│  ├─ function_search.cpp                # Locate which scripts define a given function
│  ├─ save_script.cpp                    # Export one named script to ./saved/
│  └─ compile_rxdata.cpp                 # Rebuild Scripts.rxdata from .rb sources
├─ Makefile                              # Build configuration
└─ README.md

---

Requirements

• C++17 compatible compiler (g++, clang++)
• zlib development library
• POSIX environment (Linux, macOS, WSL)

Installing dependencies

macOS (with Homebrew):

brew install zlib

Debian/Ubuntu:

sudo apt-get install build-essential zlib1g-dev

Fedora/RHEL:

sudo dnf install gcc-c++ zlib-devel

Arch Linux:

sudo pacman -S base-devel zlib

---

Building

make

This creates executables in the bin/ directory with the rmxp_ prefix.

Installation

To install the tools system-wide:

sudo make install

This installs all binaries to /usr/local/bin. You can specify a different prefix:

sudo make install PREFIX=/opt

Uninstallation

sudo make uninstall

Cleaning build files

make clean

---

Quick start

1. Place your RPG Maker project's Scripts.rxdata (or whatever you have called it) file in the data/ directory.
2. Build the tools with make.
3. Use one of the CLI tools as shown below.

---

View a specific script

./bin/rmxp_display_script data/[your_scripts].rxdata "Main"

Prints the decompressed Ruby code of the script named Main.

---

Search for a function

./bin/rmxp_function_search data/[your_scripts].rxdata "update_graphics"

Lists all script names that contain a function called update_graphics.

---

Export a single script

./bin/rmxp_save_script data/[your_scripts].rxdata "Scene_Title"

Writes the script to ./saved/Scene_Title.rb, creating the folder if necessary.

---

Extract all scripts

./bin/rmxp_extract_all_scripts data/[your_scripts].rxdata

Extracts every script into separate .rb files, named according to their script titles. The output folder is a datetime snapshot string (so you don't accidentally overwrite old extractions).

---

Rebuild Scripts.rxdata

After editing your exported .rb scripts, you can recompile them back into a new [filename]_updated.rxdata (usually Scripts_updated.rxdata) using (for example):

./bin/rmxp_compile_rxdata data/Scripts.rxdata saved/Main.rb

You can also pass multiple scripts or enter entire directories at once:

Recompile specific scripts

./bin/rmxp_compile_rxdata data/Scripts.rxdata saved/Main.rb saved/UI_Bag.rb saved/Battlers.rb

Recompile every .rb script in a folder

./bin/rmxp_compile_rxdata data/Scripts.rxdata saved/*

Or use a glob pattern

./bin/rmxp_compile_rxdata data/Scripts.rxdata "saved/*.rb"

The compiler will:

• Read each .rb file as raw bytes.
• Match it to its original entry in the Scripts.rxdata (or whatever it's called for you).
• Replace that entry's contents if found.
• Skip any .rb files that don't exist in the original archive (without stopping the process).
• After rebuilding, a new file Scripts_updated.rxdata is created in the same directory as the original rxdata file.

To use it in RPG Maker XP, rename it to Scripts.rxdata and place it in your project's Data/ folder, replacing the old one.

---

Usage after installation

If you've run sudo make install, you can use the tools from anywhere:

rmxp_display_script data/Scripts.rxdata "Main"
rmxp_function_search data/Scripts.rxdata "update_graphics"
rmxp_save_script data/Scripts.rxdata "Scene_Title"
rmxp_extract_all_scripts data/Scripts.rxdata
rmxp_compile_rxdata data/Scripts.rxdata saved/*.rb

---

For developers

All tools share common interfaces defined in the header files.
You can include them in your own C++ projects:

#include "utils.hpp"
#include "script_processor.hpp"

int main() {
   auto scripts = loadScripts("data/[your_scripts].rxdata");
   
   for (const auto& entry : scripts) {
       std::cout << entry.name << std::endl;
       std::cout << entry.code.substr(0, 200) << std::endl;  // print first 200 chars
   }
   
   return 0;
}

---

Data format notes

• [your_scripts].rxdata is a Ruby Marshal–encoded array.
• Each entry is [id, name, zlib_compressed_bytes].
• The utilities decompress and decode the bytes to plain UTF-8 Ruby code.
• Recompilation reverses this process.

---

Troubleshooting

• Build errors about zlib → ensure zlib development headers are installed.
• Unicode errors → some scripts use non-UTF-8 encodings; they're skipped with a warning.
• File not found → ensure you pass the correct path to the rxdata file.
• No output → check script name case sensitivity.
• Glob patterns not expanding → ensure you're running on a POSIX system or quote the pattern for shell expansion.
• Permission denied during install → use sudo make install.