events, plugins and encrypted asset reconstruction #1367

New issue

Open

opened 2026-10-16 21:04:43 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:04:43 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3647

Summary

The RPG Maker engine family (spanning legacy RPG Maker 2000/2003, Ruby-based XP/VX/VX Ace, and modern HTML5/Chromium-based MV/MZ) has powered thousands of commercial games, indie cult classics (To the Moon, Omori, OFF, Yume Nikki, Lisa: The Painful), and extensive modding communities.

Across generations, RPG Maker games package game logic, state machines, battle systems, event commands, maps, and multimedia into proprietary binary archives and encrypted data containers:

RGSS / Ruby Data (.rxdata, .rvdata, .rvdata2): Serialized using Ruby Marshal format containing complex object graphs (RPG::Map, RPG::Event, RPG::CommonEvent, RPG::Item).
Encrypted Archives (.rgssad, .rgss2a, .rgss3a): XOR-based key-scrambled game containers.
Modern MV/MZ: Chromium / NW.js runtime, JSON data files (Map001.json, CommonEvents.json), JavaScript plugins, and XOR-masked image/audio assets (.rpgmvp, .rpgmvm, .rpgmvo, .png_, .ogg_).

While REA covers JavaScript bundles (#3608) and game engines like GameMaker (#3632), it currently has no parser for Ruby Marshal serialization, RGSS containers, or RPG Maker event sheets.

This feature proposal introduces dedicated RPG Maker Reverse Engineering to REA, enabling archive unpacking, Ruby Marshal deserialization, MV/MZ asset decryption, event code graph reconstruction, and plugin interface analysis.

Technical Capabilities & Architecture

                                    +-----------------------------------------+
                                    | Input: RPG Maker Game Directory / File  |
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | Classic RGSS Engine       |                                   | Modern MV/MZ Engine       |
           | (XP, VX, VX Ace, RGSS3A)  |                                   | (NW.js, .rpgmvp, JSON)    |
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | Archive Unpacker & Asset Decryptor    |
                                     | (.rgssad/.rgss3a XOR, MV/MZ header XOR|
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | Ruby Marshal Deserializer |                                   | Map & Event Code Graph    |
           | (.rxdata, .rvdata, AST)   |                                   | (Switches, Variables, Cmds|
           +-------------+-------------+                                   +-------------+-------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | JavaScript Plugin & Script Analyzer   |
                                     | (plugins.js, Yanfly, VisuStella)      |
                                     +-------------------+-------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence: Game Logic Dossier,     |
                                     | Dialogue Trees & Reconstructed Maps   |
                                     +---------------------------------------+

1. Encrypted Asset & Archive Unpacking

RGSS Archive Unpacker (.rgssad, .rgss2a, .rgss3a):
- Parse RGSS archive headers and extract file tables.
- Implement rolling multi-byte XOR decryption algorithms across RGSS1, RGSS2, and RGSS3 specifications, restoring original assets.
MV/MZ Asset Decryption (.rpgmvp, .rpgmvm, .rpgmvo):
- Parse System.json to extract the 16-byte hex encryption key (encryptionKey).
- Strip the 16-byte fake header and XOR-decrypt the first 16 bytes of the file, restoring standard PNG and OGG/M4A files.

2. Ruby Marshal Binary Deserializer (`.rxdata`, `.rvdata`, `.rvdata2`)

Pure Ruby Marshal Parser: Implement an inert parser for Ruby Marshal binary format (version 4.8) without requiring a Ruby runtime:
- Integers (i), floats (f), strings ("), symbols (:, ;), arrays ([), hashes ({), bignums (l), objects (o), user classes (u, U).
RGSS Class Schema Recovery: Deserialize core RPG Maker classes:
- RPG::Map: dimensions, tilesets, BGM, BGS, encounter lists, and event tables.
- RPG::Event: event pages, conditions (switch, variable, item, actor), graphics, move routes, and event commands.
- RPG::CommonEvent: global background scripts and triggers.
- RPG::System: initial party, variables, switches, sound effects, terms.
- Scripts.rxdata: extract embedded Ruby script sections (decompiling zlib-compressed script text blocks).

3. Event Code Graph & Narrative Flow Inversion

Event Command Decoding: Translate numeric event command opcodes into structured, human-readable logic:
- Dialogue & Messages (Codes 101, 102 Show Choices, 103 Input Number).
- Game State (Codes 121 Control Switches, 122 Control Variables, 123 Control Self Switch).
- Flow Control (Codes 111 Conditional Branch, 112 Loop, 113 Break Loop, 115 Exit Event Processing, 117 Common Event).
- Movement & Scene (Codes 201 Transfer Player, 205 Set Movement Route, 221 Fadeout Screen).
- Combat & Inventory (Codes 125 Change Gold, 126 Change Items, 301 Battle Processing).
Interactive Narrative Tree: Construct dialogue trees and quest state graphs mapping required switches and variables to advance story chapters.

4. Modern MV / MZ Plugin & Script Analysis

Plugin Registry (plugins.js): Parse plugin manifests (name, status, description, parameters).
Major Ecosystem Support: Recognize and extract parameters from standard framework plugins (e.g. Yanfly Engine Plugins, VisuStella, Community Plugins).
Script Call Extraction: Statically extract inline JavaScript code blocks embedded within event command 355 (Script).

Acceptance Criteria

Introduce analyze_rpgmaker_game in REA CLI and MCP contracts, accepting project directories, .rxdata, .rvdata2, or .rgss3a archives.
Successfully unpack synthetic .rgssad and .rgss3a archives with verified SHA-256 integrity.
Decrypt .rpgmvp and .rpgmvo assets using keys recovered from System.json.
Parse Ruby Marshal binary .rvdata2 files into structured JSON schemas.
Invert event command streams into readable dialogue trees and switch/variable control flow graphs.

#3632 [Feature] GameMaker reverse engineering: data.win, GML bytecode
#3631 [Feature] Godot reverse engineering: PCK unpacking, scene/resource deserialization
#3608 [RFC/Feature] React Semantic Reconstruction & Decompiler Engine

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3647 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Game & Engine RE](https://img.shields.io/badge/domain-game_&_engine_RE-green.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Summary The RPG Maker engine family (spanning legacy RPG Maker 2000/2003, Ruby-based XP/VX/VX Ace, and modern HTML5/Chromium-based MV/MZ) has powered thousands of commercial games, indie cult classics (*To the Moon*, *Omori*, *OFF*, *Yume Nikki*, *Lisa: The Painful*), and extensive modding communities. Across generations, RPG Maker games package game logic, state machines, battle systems, event commands, maps, and multimedia into proprietary binary archives and encrypted data containers: - **RGSS / Ruby Data (`.rxdata`, `.rvdata`, `.rvdata2`):** Serialized using Ruby Marshal format containing complex object graphs (`RPG::Map`, `RPG::Event`, `RPG::CommonEvent`, `RPG::Item`). - **Encrypted Archives (`.rgssad`, `.rgss2a`, `.rgss3a`):** XOR-based key-scrambled game containers. - **Modern MV/MZ:** Chromium / NW.js runtime, JSON data files (`Map001.json`, `CommonEvents.json`), JavaScript plugins, and XOR-masked image/audio assets (`.rpgmvp`, `.rpgmvm`, `.rpgmvo`, `.png_`, `.ogg_`). While REA covers JavaScript bundles (#3608) and game engines like GameMaker (#3632), it currently has no parser for Ruby Marshal serialization, RGSS containers, or RPG Maker event sheets. This feature proposal introduces dedicated **RPG Maker Reverse Engineering** to REA, enabling archive unpacking, Ruby Marshal deserialization, MV/MZ asset decryption, event code graph reconstruction, and plugin interface analysis. --- ## Technical Capabilities & Architecture ``` +-----------------------------------------+ | Input: RPG Maker Game Directory / File | +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | Classic RGSS Engine | | Modern MV/MZ Engine | | (XP, VX, VX Ace, RGSS3A) | | (NW.js, .rpgmvp, JSON) | +-------------+-------------+ +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | Archive Unpacker & Asset Decryptor | | (.rgssad/.rgss3a XOR, MV/MZ header XOR| +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | Ruby Marshal Deserializer | | Map & Event Code Graph | | (.rxdata, .rvdata, AST) | | (Switches, Variables, Cmds| +-------------+-------------+ +-------------+-------------+ | v +---------------------------------------+ | JavaScript Plugin & Script Analyzer | | (plugins.js, Yanfly, VisuStella) | +-------------------+-------------------+ | v +---------------------------------------+ | REA Evidence: Game Logic Dossier, | | Dialogue Trees & Reconstructed Maps | +---------------------------------------+ ``` ### 1. Encrypted Asset & Archive Unpacking - **RGSS Archive Unpacker (`.rgssad`, `.rgss2a`, `.rgss3a`):** - Parse RGSS archive headers and extract file tables. - Implement rolling multi-byte XOR decryption algorithms across RGSS1, RGSS2, and RGSS3 specifications, restoring original assets. - **MV/MZ Asset Decryption (`.rpgmvp`, `.rpgmvm`, `.rpgmvo`):** - Parse `System.json` to extract the 16-byte hex encryption key (`encryptionKey`). - Strip the 16-byte fake header and XOR-decrypt the first 16 bytes of the file, restoring standard PNG and OGG/M4A files. ### 2. Ruby Marshal Binary Deserializer (`.rxdata`, `.rvdata`, `.rvdata2`) - **Pure Ruby Marshal Parser:** Implement an inert parser for Ruby Marshal binary format (version 4.8) without requiring a Ruby runtime: - Integers (`i`), floats (`f`), strings (`"`), symbols (`:`, `;`), arrays (`[`), hashes (`{`), bignums (`l`), objects (`o`), user classes (`u`, `U`). - **RGSS Class Schema Recovery:** Deserialize core RPG Maker classes: - `RPG::Map`: dimensions, tilesets, BGM, BGS, encounter lists, and event tables. - `RPG::Event`: event pages, conditions (switch, variable, item, actor), graphics, move routes, and event commands. - `RPG::CommonEvent`: global background scripts and triggers. - `RPG::System`: initial party, variables, switches, sound effects, terms. - `Scripts.rxdata`: extract embedded Ruby script sections (decompiling zlib-compressed script text blocks). ### 3. Event Code Graph & Narrative Flow Inversion - **Event Command Decoding:** Translate numeric event command opcodes into structured, human-readable logic: - Dialogue & Messages (Codes `101`, `102` Show Choices, `103` Input Number). - Game State (Codes `121` Control Switches, `122` Control Variables, `123` Control Self Switch). - Flow Control (Codes `111` Conditional Branch, `112` Loop, `113` Break Loop, `115` Exit Event Processing, `117` Common Event). - Movement & Scene (Codes `201` Transfer Player, `205` Set Movement Route, `221` Fadeout Screen). - Combat & Inventory (Codes `125` Change Gold, `126` Change Items, `301` Battle Processing). - **Interactive Narrative Tree:** Construct dialogue trees and quest state graphs mapping required switches and variables to advance story chapters. ### 4. Modern MV / MZ Plugin & Script Analysis - **Plugin Registry (`plugins.js`):** Parse plugin manifests (name, status, description, parameters). - **Major Ecosystem Support:** Recognize and extract parameters from standard framework plugins (e.g. Yanfly Engine Plugins, VisuStella, Community Plugins). - **Script Call Extraction:** Statically extract inline JavaScript code blocks embedded within event command `355` (`Script`). --- ## Acceptance Criteria 1. Introduce `analyze_rpgmaker_game` in REA CLI and MCP contracts, accepting project directories, `.rxdata`, `.rvdata2`, or `.rgss3a` archives. 2. Successfully unpack synthetic `.rgssad` and `.rgss3a` archives with verified SHA-256 integrity. 3. Decrypt `.rpgmvp` and `.rpgmvo` assets using keys recovered from `System.json`. 4. Parse Ruby Marshal binary `.rvdata2` files into structured JSON schemas. 5. Invert event command streams into readable dialogue trees and switch/variable control flow graphs. --- ## Related - #3632 [Feature] GameMaker reverse engineering: data.win, GML bytecode - #3631 [Feature] Godot reverse engineering: PCK unpacking, scene/resource deserialization - #3608 [RFC/Feature] React Semantic Reconstruction & Decompiler Engine

bsakaguchi referenced this issue

2026-10-17 21:01:31 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-17 21:10:49 +00:00

[PR #1372] [MERGED] fix(javascript): decline source-map UNC references with an unusable host #2834