morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 07:47:29 +00:00

[GH-ISSUE #3632] [Feature] GameMaker reverse engineering: data.win, GML bytecode, objects/events, and room reconstruction #1358

New issue

Open

opened 2026-10-16 21:04:38 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

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

Owner

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

Summary

GameMaker (spanning GameMaker: Studio, GMS2, and modern GameMaker 2024+) is one of the most celebrated and prolific 2D game engines in video game history, powering iconic titles such as Undertale, Deltarune, Hotline Miami, Risk of Rain, Katana ZERO, Spelunky, and Nuclear Throne.

In standard GameMaker Virtual Machine (VM) exports, the entire game—including all compiled GML scripts, event tables, game objects, sprites, audio, and room layouts—is bundled into a single Electronic Arts IFF container: data.win (Windows), game.unx (Linux), game.droid (Android), game.ios (iOS), or embedded directly within the game executable.

Currently, REA has specialized game engine reverse engineering capabilities for Unity (#3607), Unreal Engine (#3625), and Godot (#3631), but zero coverage for GameMaker. When analyzing a GameMaker application, reverse engineers need to parse the IFF chunk container, decompile the stack-based GML bytecode, map object event handlers, and reconstruct rooms and texture pages.

This feature proposal introduces dedicated GameMaker Reverse Engineering to REA, enabling automated extraction of data.win, decompilation of GML bytecode, and reconstruction of object event graphs and level rooms.

Technical Capabilities & Architecture

                                    +-----------------------------------------+
                                    | Input: data.win, game.unx, or GM Binary |
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | IFF FORM Chunk Parser     |                                   | Texture & Sprite Carving  |
           | (GEN8, OPTN, STRG, AUDO)  |                                   | (TXTR, TPAG, SPRT, PNG)   |
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | Game Object & Event Handler Model     |
                                     | (OBJT: Create, Step, Draw, Alarms)    |
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | GML Bytecode Decompiler   |                                   | Room & Level Layout       |
           | (CODE, VARI, FUNC, VM ops)|                                   | Reconstruction (ROOM)     |
           +-------------+-------------+                                   +-------------+-------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | YYC Native Binary Correlation         |
                                     | (Ghidra/Rizin native GML function map)|
                                     +-------------------+-------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence: Reconstructed GML,      |
                                     | Object Event Graph, and Room Layouts  |
                                     +---------------------------------------+

1. IFF FORM Chunk Parser & Resource Carving

Container Ingestion: Parse the outer Electronic Arts IFF FORM container and its constituent 4-byte subchunks across GMS1, GMS2, and GameMaker 2024 format revisions.
Core Metadata Chunks:
- GEN8: Game display name, target configuration flags, window dimensions, room execution order.
- STRG: Global string table pool (mapping all string literals across the game).
- AUDO & SOND: Audio file streams (WAV, OGG Vorbis, MP3) and volume/pitch/group definitions.
Graphics & Texture Sheets:
- TXTR & TPAG: Extract packed texture atlas sheets into standard PNG/QOI images.
- SPRT: Sprite records: bounding box collision masks, frame durations, sub-image UV coordinates, and origin anchor points (x, y).
- FONT: Font glyph metrics, character ranges, and texture page coordinates.

2. Game Object (`OBJT`) & Event Handler Architecture

Object Inheritance & Properties: Parse OBJT records to extract object names, parent object pointers (parent_index), physics flags, solid/visible properties, and default sprite assignments.
Event Table Extraction: Map GameMaker's event-driven dispatch table:
- Event 0: Create event (instance initialization).
- Event 1: Destroy / Clean Up events.
- Event 2: Step events (Begin Step, Step, End Step).
- Event 3: Alarm events (Alarms 0 through 11).
- Event 4: Collision events (paired with target colliding object index).
- Event 5 & Event 6: Keyboard and Mouse input events.
- Event 8: Draw events (Pre-Draw, Draw, Draw GUI, Post-Draw).
- Event 7: Other events (Room Start, Room End, Game Start, Animation End).
Code Binding: Link each registered event subtype directly to its associated code block index in the CODE chunk.

3. GML Bytecode Disassembly & Decompilation

GML Virtual Machine Architecture:
- Parse the CODE chunk (bytecode instructions, local variable counts, argument counts).
- Parse the VARI chunk (variable resolution: instance variables, global variables, local variables) and FUNC chunk (engine built-in API functions).
Opcode Disassembly: Disassemble stack-based GML instructions (conv, mul, div, add, sub, and, or, xor, neg, not, push, pop, call, b, bt, bf, pushenv, popenv, ret, exit).
High-Level Decompilation to GML:
- Reconstruct control flow structures: if/else, while, for, repeat(n), do...until, switch/case, break, continue.
- Invert instance environment scopes: with (target_instance) { ... } blocks.
- Reconstruct complex variable expressions, array indexing, and calls to built-in functions (e.g. instance_create_depth, draw_sprite, audio_play_sound).

4. Room & Level Layout Reconstruction

Room Deserialization (ROOM chunk):
- Extract room dimensions (width, height), target framerate, background color, and persistent state.
- Parse camera views and viewport configuration.
- Parse tilemap layers, background asset layers, and path curves.
- Extract placed object instances: instance ID, object type, (x, y) world coordinates, custom creation code scripts, scale (x, y), rotation angle, and color blend values.
Structured Export: Export room layouts into structured JSON schemas for level editing and structural analysis.

5. YYC (YoYo Compiler) Native Binary Correlation

Native Build Analysis: In YYC builds where GML was compiled into native C++ (PE/ELF), correlate script names and object symbols from the companion data.win chunk with native subroutine entrypoints in REA's Ghidra and Rizin providers.

Acceptance Criteria

Introduce analyze_gamemaker_game in REA CLI and MCP contracts, accepting data.win, game.unx, and GameMaker executables.
Safely parse all major IFF chunks (GEN8, STRG, TXTR, SPRT, OBJT, ROOM, CODE) from synthetic test fixtures.
Disassemble GML VM bytecode and decompile control flow (if, while, with, repeat) into valid GML source code.
Map object event tables, linking Create, Step, and Draw events to decompiled scripts.
Extract placed room instances with coordinates and instance IDs in structured JSON evidence.

#3607 [Feature] Comprehensive Unity extraction and reverse engineering
#3625 [Feature] Unreal Engine reverse engineering: Pak/IoStore, UAsset reflection
#3631 [Feature] Godot reverse engineering: PCK unpacking, scene/resource deserialization

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3632 [![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 GameMaker (spanning GameMaker: Studio, GMS2, and modern GameMaker 2024+) is one of the most celebrated and prolific 2D game engines in video game history, powering iconic titles such as *Undertale*, *Deltarune*, *Hotline Miami*, *Risk of Rain*, *Katana ZERO*, *Spelunky*, and *Nuclear Throne*. In standard GameMaker Virtual Machine (VM) exports, the entire game—including all compiled GML scripts, event tables, game objects, sprites, audio, and room layouts—is bundled into a single Electronic Arts IFF container: `data.win` (Windows), `game.unx` (Linux), `game.droid` (Android), `game.ios` (iOS), or embedded directly within the game executable. Currently, REA has specialized game engine reverse engineering capabilities for Unity (#3607), Unreal Engine (#3625), and Godot (#3631), but zero coverage for GameMaker. When analyzing a GameMaker application, reverse engineers need to parse the IFF chunk container, decompile the stack-based GML bytecode, map object event handlers, and reconstruct rooms and texture pages. This feature proposal introduces dedicated **GameMaker Reverse Engineering** to REA, enabling automated extraction of `data.win`, decompilation of GML bytecode, and reconstruction of object event graphs and level rooms. --- ## Technical Capabilities & Architecture ``` +-----------------------------------------+ | Input: data.win, game.unx, or GM Binary | +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | IFF FORM Chunk Parser | | Texture & Sprite Carving | | (GEN8, OPTN, STRG, AUDO) | | (TXTR, TPAG, SPRT, PNG) | +-------------+-------------+ +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | Game Object & Event Handler Model | | (OBJT: Create, Step, Draw, Alarms) | +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | GML Bytecode Decompiler | | Room & Level Layout | | (CODE, VARI, FUNC, VM ops)| | Reconstruction (ROOM) | +-------------+-------------+ +-------------+-------------+ | v +---------------------------------------+ | YYC Native Binary Correlation | | (Ghidra/Rizin native GML function map)| +-------------------+-------------------+ | v +---------------------------------------+ | REA Evidence: Reconstructed GML, | | Object Event Graph, and Room Layouts | +---------------------------------------+ ``` ### 1. IFF FORM Chunk Parser & Resource Carving - **Container Ingestion:** Parse the outer Electronic Arts IFF `FORM` container and its constituent 4-byte subchunks across GMS1, GMS2, and GameMaker 2024 format revisions. - **Core Metadata Chunks:** - `GEN8`: Game display name, target configuration flags, window dimensions, room execution order. - `STRG`: Global string table pool (mapping all string literals across the game). - `AUDO` & `SOND`: Audio file streams (WAV, OGG Vorbis, MP3) and volume/pitch/group definitions. - **Graphics & Texture Sheets:** - `TXTR` & `TPAG`: Extract packed texture atlas sheets into standard PNG/QOI images. - `SPRT`: Sprite records: bounding box collision masks, frame durations, sub-image UV coordinates, and origin anchor points ($x, y$). - `FONT`: Font glyph metrics, character ranges, and texture page coordinates. ### 2. Game Object (`OBJT`) & Event Handler Architecture - **Object Inheritance & Properties:** Parse `OBJT` records to extract object names, parent object pointers (`parent_index`), physics flags, solid/visible properties, and default sprite assignments. - **Event Table Extraction:** Map GameMaker's event-driven dispatch table: - `Event 0`: Create event (instance initialization). - `Event 1`: Destroy / Clean Up events. - `Event 2`: Step events (Begin Step, Step, End Step). - `Event 3`: Alarm events (Alarms 0 through 11). - `Event 4`: Collision events (paired with target colliding object index). - `Event 5` & `Event 6`: Keyboard and Mouse input events. - `Event 8`: Draw events (Pre-Draw, Draw, Draw GUI, Post-Draw). - `Event 7`: Other events (Room Start, Room End, Game Start, Animation End). - **Code Binding:** Link each registered event subtype directly to its associated code block index in the `CODE` chunk. ### 3. GML Bytecode Disassembly & Decompilation - **GML Virtual Machine Architecture:** - Parse the `CODE` chunk (bytecode instructions, local variable counts, argument counts). - Parse the `VARI` chunk (variable resolution: instance variables, global variables, local variables) and `FUNC` chunk (engine built-in API functions). - **Opcode Disassembly:** Disassemble stack-based GML instructions (`conv`, `mul`, `div`, `add`, `sub`, `and`, `or`, `xor`, `neg`, `not`, `push`, `pop`, `call`, `b`, `bt`, `bf`, `pushenv`, `popenv`, `ret`, `exit`). - **High-Level Decompilation to GML:** - Reconstruct control flow structures: `if/else`, `while`, `for`, `repeat(n)`, `do...until`, `switch/case`, `break`, `continue`. - Invert instance environment scopes: `with (target_instance) { ... }` blocks. - Reconstruct complex variable expressions, array indexing, and calls to built-in functions (e.g. `instance_create_depth`, `draw_sprite`, `audio_play_sound`). ### 4. Room & Level Layout Reconstruction - **Room Deserialization (`ROOM` chunk):** - Extract room dimensions (width, height), target framerate, background color, and persistent state. - Parse camera views and viewport configuration. - Parse tilemap layers, background asset layers, and path curves. - Extract placed object instances: instance ID, object type, $(x, y)$ world coordinates, custom creation code scripts, scale $(x, y)$, rotation angle, and color blend values. - **Structured Export:** Export room layouts into structured JSON schemas for level editing and structural analysis. ### 5. YYC (YoYo Compiler) Native Binary Correlation - **Native Build Analysis:** In YYC builds where GML was compiled into native C++ (PE/ELF), correlate script names and object symbols from the companion `data.win` chunk with native subroutine entrypoints in REA's Ghidra and Rizin providers. --- ## Acceptance Criteria 1. Introduce `analyze_gamemaker_game` in REA CLI and MCP contracts, accepting `data.win`, `game.unx`, and GameMaker executables. 2. Safely parse all major IFF chunks (`GEN8`, `STRG`, `TXTR`, `SPRT`, `OBJT`, `ROOM`, `CODE`) from synthetic test fixtures. 3. Disassemble GML VM bytecode and decompile control flow (`if`, `while`, `with`, `repeat`) into valid GML source code. 4. Map object event tables, linking Create, Step, and Draw events to decompiled scripts. 5. Extract placed room instances with coordinates and instance IDs in structured JSON evidence. --- ## Related - #3607 [Feature] Comprehensive Unity extraction and reverse engineering - #3625 [Feature] Unreal Engine reverse engineering: Pak/IoStore, UAsset reflection - #3631 [Feature] Godot reverse engineering: PCK unpacking, scene/resource deserialization

bsakaguchi referenced this issue

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

[PR #1358] [MERGED] fix(process): keep unobserved file contents unknown #2824

bsakaguchi commented

2026-10-31 00:30:44 +00:00

Author

Owner

@matbrgz commented on GitHub (Oct 20, 2026):

Cross-referencing with canonical issue #3614 ([Feature] Adobe Flash & SWF Reverse Engineering) and sibling #3631 (Godot reverse engineering). All relate to game engine binary and bytecode extraction, asset deserialization, and runtime reconstruction. Cataloged under Cluster BZ in consolidation tracker #4330.

@matbrgz commented on GitHub (Oct 20, 2026): Cross-referencing with canonical issue #3614 (`[Feature] Adobe Flash & SWF Reverse Engineering`) and sibling #3631 (Godot reverse engineering). All relate to game engine binary and bytecode extraction, asset deserialization, and runtime reconstruction. Cataloged under Cluster BZ in consolidation tracker #4330.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#1358

No description provided.

Rows
Columns