[GH-ISSUE #3631] [Feature] Godot reverse engineering: PCK unpacking, scene/resource deserialization, GDScript bytecode decompilation, and signal graph reconstruction #1356

New issue

Open

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

bsakaguchi commented

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

Owner

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

Summary

Godot Engine (Godot 3.x and Godot 4.x) is the leading open-source game engine, rapidly expanding across indie game development, mobile/desktop gaming, and interactive 2D/3D applications. Packaged Godot games bundle all visual scenes, scripts, shaders, and resources into dedicated PCK package containers or append them directly to the native game executable.

While REA provides specialized reverse engineering for Unity (#3607) and Unreal Engine (#3625), it currently has no coverage for Godot's asset containers, binary serialization formats, or scripting VM. An analyst encountering a Godot application needs to:

Unpack .pck files and embedded package footers;
Deserialize binary scene (.scn) and resource (.res) formats;
Reconstruct node trees, autoload singletons, and project configurations;
Decompile compiled GDScript bytecode (.gdc);
Build the reactive Signal Graph that coordinates gameplay logic;
Trace GDExtension / GDNative boundaries to native C++/Rust plugins.

This feature proposal introduces dedicated Godot Reverse Engineering to REA, enabling end-to-end extraction from raw PCK bytes to human-readable GDScript and scene hierarchies.

Technical Capabilities & Architecture

                                    +-----------------------------------------+
                                    | Input: Godot Binary or .pck Package     |
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | PCK Package Unpacker      |                                   | Project Configuration &   |
           | (GDPC magic v1/v2, AES)   |                                   | Autoloads (project.binary)|
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | Scene & Resource Deserializer         |
                                     | (.tscn/.scn, .tres/.res, RSRC/RSCC)   |
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | GDScript Bytecode         |                                   | Signal Connection Graph   |
           | Decompiler (.gdc, GDSC)   |                                   | (Node Signals -> Callbacks|
           +-------------+-------------+                                   +-------------+-------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | GDExtension / GDNative Mapping        |
                                     | (ClassDB native C++/Rust libraries)   |
                                     +-------------------+-------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence: Reconstructed Project,  |
                                     | GDScript Sources & Node Hierarchy     |
                                     +---------------------------------------+

1. PCK Container Unpacking & Embedded Package Discovery

PCK Header Parser: Parse standalone .pck archives and appended executable packages (detected by the GDPC 0x43504447 magic bytes at the start or seeking back from EOF).
Format Versions: Support PCK version 1 (Godot 3.x) and version 2 (Godot 4.x), parsing engine major/minor/patch numbers, file count, and file entry tables (path, offset, size, md5, flags).
Encryption Support: Support caller-supplied AES-256 keys to decrypt encrypted PCK index headers and individual resource blocks.

2. Scene (`.tscn` / `.scn`) & Resource (`.tres` / `.res`) Deserialization

Binary Resource Parser (RSRC / RSCC): Decode Godot's binary serialization format, extracting string tables, external resource paths (ext_resource), internal sub-resources (sub_resource), and object properties.
Node Tree Hierarchy Reconstruction: Reconstruct the complete hierarchical tree of Node instances (e.g. Node2D, Node3D, Control, CanvasLayer, Camera, CharacterBody), preserving parent-child relationships, transform matrices, and assigned scripts.
Project Manifest & Autoloads: Parse project.godot or binary project configurations, extracting game window dimensions, input action maps, physics layers, and Autoload singleton nodes.

3. GDScript Bytecode (`.gdc`) Decompilation

Bytecode Parser (GDSC): Parse compiled GDScript files across Godot 3 (token-based bytecode) and Godot 4 (register-based VM bytecode).
Table Extraction: Extract constant pools (integers, floats, strings, Vector2/3, Color), identifier tables, and member variable declarations.
Control Flow & Instruction Inversion: Disassemble VM opcodes and reconstruct structured, idiomatic GDScript source code:
- Function definitions (func _ready():, func _process(delta):).
- Control structures (if/elif/else, for, while, match).
- Operators, method invocations, and built-in engine math functions.

4. Reactive Signal Graph Reconstruction

Signal Definition & Connections: Extract custom signals (signal health_changed(new_health)) and identify all active signal connections declared in .tscn/.scn files or established via connect().
Event Flow Graph: Build a directed event graph linking UI signals (e.g. button_up, pressed), physics signals (e.g. body_entered, area_entered), and timer signals (timeout) to their corresponding script callback methods.

5. GDExtension & GDNative Boundary Mapping

Native Module Discovery: Identify .gdextension and .gdnlib configuration files linking Godot nodes to external native shared libraries (.dll, .so, .dylib).
ClassDB Registration: Trace native symbol exports (godot_gdextension_entry_point, ClassDB::register_class), linking high-level GDScript node invocations to native C++/Rust functions in REA's Ghidra/Rizin providers.

Acceptance Criteria

Introduce analyze_godot_project in REA CLI and MCP contracts, accepting standalone .pck files and executables with embedded PCK data.
Safely unpack Godot 3 and Godot 4 PCK test fixtures without memory leaks or buffer overruns.
Deserialize binary .scn and .res files into structured JSON node hierarchies.
Decompile synthetic Godot 3 and Godot 4 .gdc bytecode test fixtures into valid GDScript source code.
Output a complete Signal connection graph mapping event sources to target callback methods in structured evidence.

#3607 [Feature] Comprehensive Unity extraction and reverse engineering
#3625 [Feature] Unreal Engine reverse engineering: Pak/IoStore, UAsset reflection
#3624 [Feature] Native C++ semantic reconstruction

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3631 [![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 Godot Engine (Godot 3.x and Godot 4.x) is the leading open-source game engine, rapidly expanding across indie game development, mobile/desktop gaming, and interactive 2D/3D applications. Packaged Godot games bundle all visual scenes, scripts, shaders, and resources into dedicated PCK package containers or append them directly to the native game executable. While REA provides specialized reverse engineering for Unity (#3607) and Unreal Engine (#3625), it currently has no coverage for Godot's asset containers, binary serialization formats, or scripting VM. An analyst encountering a Godot application needs to: - Unpack `.pck` files and embedded package footers; - Deserialize binary scene (`.scn`) and resource (`.res`) formats; - Reconstruct node trees, autoload singletons, and project configurations; - Decompile compiled GDScript bytecode (`.gdc`); - Build the reactive Signal Graph that coordinates gameplay logic; - Trace GDExtension / GDNative boundaries to native C++/Rust plugins. This feature proposal introduces dedicated **Godot Reverse Engineering** to REA, enabling end-to-end extraction from raw PCK bytes to human-readable GDScript and scene hierarchies. --- ## Technical Capabilities & Architecture ``` +-----------------------------------------+ | Input: Godot Binary or .pck Package | +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | PCK Package Unpacker | | Project Configuration & | | (GDPC magic v1/v2, AES) | | Autoloads (project.binary)| +-------------+-------------+ +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | Scene & Resource Deserializer | | (.tscn/.scn, .tres/.res, RSRC/RSCC) | +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | GDScript Bytecode | | Signal Connection Graph | | Decompiler (.gdc, GDSC) | | (Node Signals -> Callbacks| +-------------+-------------+ +-------------+-------------+ | v +---------------------------------------+ | GDExtension / GDNative Mapping | | (ClassDB native C++/Rust libraries) | +-------------------+-------------------+ | v +---------------------------------------+ | REA Evidence: Reconstructed Project, | | GDScript Sources & Node Hierarchy | +---------------------------------------+ ``` ### 1. PCK Container Unpacking & Embedded Package Discovery - **PCK Header Parser:** Parse standalone `.pck` archives and appended executable packages (detected by the `GDPC` `0x43504447` magic bytes at the start or seeking back from EOF). - **Format Versions:** Support PCK version 1 (Godot 3.x) and version 2 (Godot 4.x), parsing engine major/minor/patch numbers, file count, and file entry tables (`path`, `offset`, `size`, `md5`, `flags`). - **Encryption Support:** Support caller-supplied AES-256 keys to decrypt encrypted PCK index headers and individual resource blocks. ### 2. Scene (`.tscn` / `.scn`) & Resource (`.tres` / `.res`) Deserialization - **Binary Resource Parser (`RSRC` / `RSCC`):** Decode Godot's binary serialization format, extracting string tables, external resource paths (`ext_resource`), internal sub-resources (`sub_resource`), and object properties. - **Node Tree Hierarchy Reconstruction:** Reconstruct the complete hierarchical tree of `Node` instances (e.g. `Node2D`, `Node3D`, `Control`, `CanvasLayer`, `Camera`, `CharacterBody`), preserving parent-child relationships, transform matrices, and assigned scripts. - **Project Manifest & Autoloads:** Parse `project.godot` or binary project configurations, extracting game window dimensions, input action maps, physics layers, and Autoload singleton nodes. ### 3. GDScript Bytecode (`.gdc`) Decompilation - **Bytecode Parser (`GDSC`):** Parse compiled GDScript files across Godot 3 (token-based bytecode) and Godot 4 (register-based VM bytecode). - **Table Extraction:** Extract constant pools (integers, floats, strings, Vector2/3, Color), identifier tables, and member variable declarations. - **Control Flow & Instruction Inversion:** Disassemble VM opcodes and reconstruct structured, idiomatic GDScript source code: - Function definitions (`func _ready():`, `func _process(delta):`). - Control structures (`if/elif/else`, `for`, `while`, `match`). - Operators, method invocations, and built-in engine math functions. ### 4. Reactive Signal Graph Reconstruction - **Signal Definition & Connections:** Extract custom signals (`signal health_changed(new_health)`) and identify all active signal connections declared in `.tscn`/`.scn` files or established via `connect()`. - **Event Flow Graph:** Build a directed event graph linking UI signals (e.g. `button_up`, `pressed`), physics signals (e.g. `body_entered`, `area_entered`), and timer signals (`timeout`) to their corresponding script callback methods. ### 5. GDExtension & GDNative Boundary Mapping - **Native Module Discovery:** Identify `.gdextension` and `.gdnlib` configuration files linking Godot nodes to external native shared libraries (`.dll`, `.so`, `.dylib`). - **ClassDB Registration:** Trace native symbol exports (`godot_gdextension_entry_point`, `ClassDB::register_class`), linking high-level GDScript node invocations to native C++/Rust functions in REA's Ghidra/Rizin providers. --- ## Acceptance Criteria 1. Introduce `analyze_godot_project` in REA CLI and MCP contracts, accepting standalone `.pck` files and executables with embedded PCK data. 2. Safely unpack Godot 3 and Godot 4 PCK test fixtures without memory leaks or buffer overruns. 3. Deserialize binary `.scn` and `.res` files into structured JSON node hierarchies. 4. Decompile synthetic Godot 3 and Godot 4 `.gdc` bytecode test fixtures into valid GDScript source code. 5. Output a complete Signal connection graph mapping event sources to target callback methods in structured evidence. --- ## Related - #3607 [Feature] Comprehensive Unity extraction and reverse engineering - #3625 [Feature] Unreal Engine reverse engineering: Pak/IoStore, UAsset reflection - #3624 [Feature] Native C++ semantic reconstruction

bsakaguchi referenced this issue

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

[PR #1356] [CLOSED] feat(sqlite): inspect database snapshots and selected table rows #2822

bsakaguchi referenced this issue

2026-10-31 01:04:12 +00:00

[PR #2271] [MERGED] feat(sqlite): inspect offline snapshots with selective evidence #5129

bsakaguchi referenced this issue

2026-11-01 21:11:26 +00:00

[GH-ISSUE #8190] [Design] Investigate partial outgoing data-reference evidence for Kuna functions #6474