model serialization, scripts, remotes and Instance graph reconstruction #1404

New issue

Open

opened 2026-10-16 21:05:08 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:05:08 +00:00

Owner

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

Problem Statement & Context

Luau is a fast, embeddable, type-annotated language derived from Lua 5.1, developed and maintained by Roblox and increasingly adopted across external gaming runtimes (e.g., Alan Wake 2, Farming Simulator 2025). The Roblox ecosystem represents a massive software ecosystem where entire games, systems, and network protocols are built using Luau scripts embedded within proprietary binary/XML containers.

Analyzing Roblox experiences, models, and plugins requires specialized reverse engineering capabilities:

Luau Bytecode: Distinct from standard Lua 5.1 / LuaJIT bytecode. Luau utilizes custom opcode matrices, vector register types, inline caching, built-in function opcodes (LOP_FASTCALL), and specialized constant pools.
Container Serialization (.rbxl / .rbxm binary & .rbxlx / .rbxmx XML): Chunks (PROP, INST, PRNT, SIGN, META) packing instances, properties, parent-child relationships, and compressed string/float/vector arrays.
Script Hierarchy & Types: Script (server-side), LocalScript (client-side), and ModuleScript (shared modules with dependency require trees).
Client-Server Remotes (RemoteEvent, RemoteFunction): Network boundaries defining client-server IPC.
Services & DataModel Tree: Core services (Workspace, ReplicatedStorage, ServerScriptService, ServerStorage, Players, HttpService).

REA lacks dedicated support for Luau bytecode decompilation and Roblox instance graph reconstruction.

Proposed Architecture

flowchart TD
    A["Roblox File (.rbxl, .rbxm, .rbxlx, .rbxmx) / Compiled Luau Binary"] --> B["Roblox / Luau Reverse Engineering Engine"]
    B --> C["RBX Binary & XML Deserializer"]
    B --> D["Luau Bytecode Decompiler"]
    B --> E["Experience Architecture & Remote Reconstructor"]
    
    C --> C1["Chunk Parsing (INST, PROP, PRNT, META)"]
    C --> C2["Instance Hierarchy & Property Deserialization"]
    C --> C3["LZ4 / Zlib Decompression"]
    
    D --> D1["Luau Bytecode Header & Vector Opcode Disassembly"]
    D --> D2["Constant Table & Upvalue Recovery"]
    D --> D3["Control Flow Reconstruction & Luau Source Decompilation"]
    
    E --> E1["ModuleScript Dependency Graph (require)"]
    E --> E2["RemoteEvent & RemoteFunction Network Boundary Map"]
    E --> E3["Security Boundary (Server vs Client vs Replicated)"]
    
    C & D & E --> F["Synthesized Roblox Experience Architecture & Decompiled Scripts"]

Technical Capabilities & Modules

Roblox Container Parsing (.rbxl, .rbxm, .rbxlx, .rbxmx):
- Parse binary header signature (<roblox!).
- Decode binary chunks:
  - META: Experience and model metadata.
  - INST: Instance class registrations and Referent ID mappings.
  - PROP: Compressed property data (strings, integers, floats, CFrames, Color3, vectors).
  - PRNT: Parent-child relationship tables.
- Decompress LZ4 chunk streams.
Luau Bytecode Disassembly & Decompilation:
- Parse Luau bytecode format: version header, string table, proto metadata, line info, and bytecode instructions.
- Disassemble Luau-specific opcodes: FASTCALL, CAPTURE, NAMECALL, GETVARG, vector operations.
- Reconstruct control flow structures (if-then-else, while, for-in, repeat-until).
- Emit clean, idiomatically typed Luau source code.
Script Context & Replication Boundary Analysis:
- Identify script execution environments based on container placement:
  - Server-only: ServerScriptService, ServerStorage.
  - Client-only: StarterPlayerScripts, StarterGui.
  - Replicated: ReplicatedStorage, ReplicatedFirst.
- Distinguish Script, LocalScript, and ModuleScript.
Network & Remote Interface Mapping:
- Map all RemoteEvent and RemoteFunction instances across the DataModel.
- Correlate FireServer / OnServerEvent and FireClient / OnClientEvent calls across client and server scripts.
- Infer message parameter types and payload schemas.
Module Dependency Graph Reconstruction:
- Parse require(script.Parent.Module) calls.
- Construct a directed acyclic graph (DAG) of module dependencies and shared services.

Acceptance Criteria

Ingestion and deserialization of .rbxl (places) and .rbxm (models) in both binary and XML formats.
Clean extraction and decompilation of Luau bytecode into readable source code.
Attribution of scripts to server, client, or replicated execution contexts.
Extraction of the complete Instance hierarchy with all properties preserved.
Bidirectional mapping of client-server remote events and functions.

Complements #2383 (Romhacking and game asset reverse engineering)
Complements #3631 (Godot reverse engineering)
Complements #3632 (GameMaker reverse engineering)
Complements #3647 (RPG Maker reverse engineering)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3692 [![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) ### Problem Statement & Context Luau is a fast, embeddable, type-annotated language derived from Lua 5.1, developed and maintained by Roblox and increasingly adopted across external gaming runtimes (e.g., Alan Wake 2, Farming Simulator 2025). The Roblox ecosystem represents a massive software ecosystem where entire games, systems, and network protocols are built using Luau scripts embedded within proprietary binary/XML containers. Analyzing Roblox experiences, models, and plugins requires specialized reverse engineering capabilities: 1. **Luau Bytecode**: Distinct from standard Lua 5.1 / LuaJIT bytecode. Luau utilizes custom opcode matrices, vector register types, inline caching, built-in function opcodes (`LOP_FASTCALL`), and specialized constant pools. 2. **Container Serialization (`.rbxl` / `.rbxm` binary & `.rbxlx` / `.rbxmx` XML)**: Chunks (`PROP`, `INST`, `PRNT`, `SIGN`, `META`) packing instances, properties, parent-child relationships, and compressed string/float/vector arrays. 3. **Script Hierarchy & Types**: `Script` (server-side), `LocalScript` (client-side), and `ModuleScript` (shared modules with dependency `require` trees). 4. **Client-Server Remotes (`RemoteEvent`, `RemoteFunction`)**: Network boundaries defining client-server IPC. 5. **Services & DataModel Tree**: Core services (`Workspace`, `ReplicatedStorage`, `ServerScriptService`, `ServerStorage`, `Players`, `HttpService`). REA lacks dedicated support for Luau bytecode decompilation and Roblox instance graph reconstruction. ### Proposed Architecture ```mermaid flowchart TD A["Roblox File (.rbxl, .rbxm, .rbxlx, .rbxmx) / Compiled Luau Binary"] --> B["Roblox / Luau Reverse Engineering Engine"] B --> C["RBX Binary & XML Deserializer"] B --> D["Luau Bytecode Decompiler"] B --> E["Experience Architecture & Remote Reconstructor"] C --> C1["Chunk Parsing (INST, PROP, PRNT, META)"] C --> C2["Instance Hierarchy & Property Deserialization"] C --> C3["LZ4 / Zlib Decompression"] D --> D1["Luau Bytecode Header & Vector Opcode Disassembly"] D --> D2["Constant Table & Upvalue Recovery"] D --> D3["Control Flow Reconstruction & Luau Source Decompilation"] E --> E1["ModuleScript Dependency Graph (require)"] E --> E2["RemoteEvent & RemoteFunction Network Boundary Map"] E --> E3["Security Boundary (Server vs Client vs Replicated)"] C & D & E --> F["Synthesized Roblox Experience Architecture & Decompiled Scripts"] ``` ### Technical Capabilities & Modules 1. **Roblox Container Parsing (`.rbxl`, `.rbxm`, `.rbxlx`, `.rbxmx`):** - Parse binary header signature (`<roblox!`). - Decode binary chunks: - `META`: Experience and model metadata. - `INST`: Instance class registrations and Referent ID mappings. - `PROP`: Compressed property data (strings, integers, floats, CFrames, Color3, vectors). - `PRNT`: Parent-child relationship tables. - Decompress LZ4 chunk streams. 2. **Luau Bytecode Disassembly & Decompilation:** - Parse Luau bytecode format: version header, string table, proto metadata, line info, and bytecode instructions. - Disassemble Luau-specific opcodes: `FASTCALL`, `CAPTURE`, `NAMECALL`, `GETVARG`, vector operations. - Reconstruct control flow structures (`if-then-else`, `while`, `for-in`, `repeat-until`). - Emit clean, idiomatically typed Luau source code. 3. **Script Context & Replication Boundary Analysis:** - Identify script execution environments based on container placement: - Server-only: `ServerScriptService`, `ServerStorage`. - Client-only: `StarterPlayerScripts`, `StarterGui`. - Replicated: `ReplicatedStorage`, `ReplicatedFirst`. - Distinguish `Script`, `LocalScript`, and `ModuleScript`. 4. **Network & Remote Interface Mapping:** - Map all `RemoteEvent` and `RemoteFunction` instances across the DataModel. - Correlate `FireServer` / `OnServerEvent` and `FireClient` / `OnClientEvent` calls across client and server scripts. - Infer message parameter types and payload schemas. 5. **Module Dependency Graph Reconstruction:** - Parse `require(script.Parent.Module)` calls. - Construct a directed acyclic graph (DAG) of module dependencies and shared services. ### Acceptance Criteria - [ ] Ingestion and deserialization of `.rbxl` (places) and `.rbxm` (models) in both binary and XML formats. - [ ] Clean extraction and decompilation of Luau bytecode into readable source code. - [ ] Attribution of scripts to server, client, or replicated execution contexts. - [ ] Extraction of the complete Instance hierarchy with all properties preserved. - [ ] Bidirectional mapping of client-server remote events and functions. ### Related Issues & Dependencies - Complements #2383 (Romhacking and game asset reverse engineering) - Complements #3631 (Godot reverse engineering) - Complements #3632 (GameMaker reverse engineering) - Complements #3647 (RPG Maker reverse engineering)

bsakaguchi referenced this issue

2026-10-17 21:11:08 +00:00

[PR #1404] [MERGED] perf(native): record pwntools diagnostics once in their Evidence #2860

bsakaguchi referenced this issue

2026-10-17 21:11:08 +00:00

[PR #1405] [MERGED] perf(hopper): stop repeating Hopper replies as raw_result #2861

bsakaguchi referenced this issue

2026-10-17 21:11:22 +00:00

[PR #1430] [MERGED] perf(native): record macOS command provenance once in its Evidence #2882