ACT animations and compiled LUB scripts #1418

New issue

Open

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

bsakaguchi commented

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

Owner

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

Problem Statement & Context

Classic isometric MMORPGs utilize a highly structured, proprietary asset packaging and 2.5D rendering pipeline that combines 3D polygonal terrain with 2D animated raster sprites and compiled script tables:

GRF Archive Packages (.grf): Virtual file containers (versions 0x102, 0x103, 0x200) characterized by a 46-byte header signature (Master of Magic), table offsets, file entry counts, Zlib-compressed file tables, and encrypted file blocks (DES or custom byte shuffling).
Terrain & Spatial Meshes (.gnd, .gat, .rsw):
- .rsw (Resource World): Scene definitions, lighting, water height levels, ambient sounds, and placement models (.rsm).
- .gnd (Ground): 3D polygonal tile mesh data, UV texture mappings, lightmaps, and tile surfaces.
- .gat (Ground Altitude Table): Navigational grid and collision map (walkable, non-walkable, water, shootable-through) divided into 0.5x0.5 unit cells.
Sprite & Animation Pairs (.spr, .act):
- .spr: Indexed paletted or 32-bit RGBA sprite sheets with custom RLE compression.
- .act: Animation action tables defining keyframes, directional rotations (8 directions), coordinate offsets, sound cue triggers, and attachment anchor points.
Compiled Lua Client Tables (.lub): Configuration files, UI layouts, item info tables, and quest descriptions compiled into Lua 5.0/5.1 bytecode chunks (.lub).

REA lacks native support for unpacking encrypted GRF archives, parsing GAT collision meshes, and deserializing SPR/ACT animation sequences.

Proposed Architecture

flowchart TD
    A["Game Directory (data.grf / client files)"] --> B["Isometric 2.5D Asset & Map Engine"]
    B --> C["GRF Archive Slicer & Decryptor"]
    B --> D["Spatial & Navigational Mesh Deserializer"]
    B --> E["Sprite & Animation Reconstructor"]
    B --> F["Client Script Parser (.lub)"]
    
    C --> C1["Header Verification (Master of Magic, Version 0x200)"]
    C --> C2["Table Decryption & Zlib Decompression"]
    C --> C3["Extracted Directory Tree"]
    
    D --> D1[".gat Collision Grid (Walkability & Sight Lines)"]
    D --> D2[".gnd 3D Tile Meshes & Lightmaps"]
    D --> D3[".rsw Spatial World Scene & Model References"]
    
    E --> E1[".spr Paletted Sprite Decoder (RLE / RGBA)"]
    E --> E2[".act 8-Directional Keyframe & Sound Cue Reconstructor"]
    
    F --> F1[".lub Decompilation (Lua 5.0 / 5.1 Bytecode)"]
    
    C & D & E & F --> G["Synthesized World Map, Sprite Animation Player & Client Data Graph"]

Technical Capabilities & Modules

GRF Archive Parsing & Decryption:
- Detect header magic (Master of Magic) and parse versions 0x102, 0x103, and 0x200.
- Decrypt obfuscated/DES-encrypted file tables and decompress entry streams using Zlib.
- Extract raw assets preserving directory paths and Korean/CP949 or UTF-8 character encodings.
Navigational Mesh & Map Parsing (.gat, .gnd, .rsw):
- Parse .gat collision grids: decode cell properties (Walkable, Water, Snipable, Wall) and generate 2D walkability bitmap masks.
- Parse .gnd files: extract 3D height vertices, tile textures, and lightmap intensity values.
- Parse .rsw files: extract world object references, light properties, and ambient sound emitter coordinates.
Sprite & Action Animation Reconstruction (.spr, .act):
- Decode .spr paletted images with Run-Length Encoding (RLE) and 32-bit RGBA sprite frames.
- Parse .act animation tables: reconstruct keyframe frames, rotation angles (8 directions), sprite scaling, anchor attach points, and sound index triggers.
- Export animated sprites to standard animated GIF or sprite-sheet PNGs.
Compiled Lua Client Data Decompilation (.lub):
- Utilize REA's Lua decompiler (#3699) to decompile .lub files back to human-readable tables:
  - itemInfo.lub: Item IDs, names, descriptions, and sprite resource mappings.
  - jobname.lub / accessoryid.lub: Sprite attachment IDs and identifiers.

Acceptance Criteria

Successful extraction of assets from encrypted and compressed .grf archives.
Conversion of .gat navigational files into binary walkability masks and collision matrices.
Parsing of .spr and .act pairs and generation of composite sprite animation frames.
Decompilation of .lub client database files into structured JSON or Lua tables.
Export of an integrated spatial manifest linking map geometry, collisions, and model placements.

Complements #3621 (Unknown binary file-format inference)
Complements #3699 (Lua and LuaJIT bytecode reverse engineering)
Complements #3698 (Interactive entertainment runtime and asset reverse engineering tracker)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3707 [![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 Classic isometric MMORPGs utilize a highly structured, proprietary asset packaging and 2.5D rendering pipeline that combines 3D polygonal terrain with 2D animated raster sprites and compiled script tables: 1. **GRF Archive Packages (`.grf`)**: Virtual file containers (versions 0x102, 0x103, 0x200) characterized by a 46-byte header signature (`Master of Magic`), table offsets, file entry counts, Zlib-compressed file tables, and encrypted file blocks (DES or custom byte shuffling). 2. **Terrain & Spatial Meshes (`.gnd`, `.gat`, `.rsw`)**: - `.rsw` (Resource World): Scene definitions, lighting, water height levels, ambient sounds, and placement models (`.rsm`). - `.gnd` (Ground): 3D polygonal tile mesh data, UV texture mappings, lightmaps, and tile surfaces. - `.gat` (Ground Altitude Table): Navigational grid and collision map (walkable, non-walkable, water, shootable-through) divided into 0.5x0.5 unit cells. 3. **Sprite & Animation Pairs (`.spr`, `.act`)**: - `.spr`: Indexed paletted or 32-bit RGBA sprite sheets with custom RLE compression. - `.act`: Animation action tables defining keyframes, directional rotations (8 directions), coordinate offsets, sound cue triggers, and attachment anchor points. 4. **Compiled Lua Client Tables (`.lub`)**: Configuration files, UI layouts, item info tables, and quest descriptions compiled into Lua 5.0/5.1 bytecode chunks (`.lub`). REA lacks native support for unpacking encrypted GRF archives, parsing GAT collision meshes, and deserializing SPR/ACT animation sequences. ### Proposed Architecture ```mermaid flowchart TD A["Game Directory (data.grf / client files)"] --> B["Isometric 2.5D Asset & Map Engine"] B --> C["GRF Archive Slicer & Decryptor"] B --> D["Spatial & Navigational Mesh Deserializer"] B --> E["Sprite & Animation Reconstructor"] B --> F["Client Script Parser (.lub)"] C --> C1["Header Verification (Master of Magic, Version 0x200)"] C --> C2["Table Decryption & Zlib Decompression"] C --> C3["Extracted Directory Tree"] D --> D1[".gat Collision Grid (Walkability & Sight Lines)"] D --> D2[".gnd 3D Tile Meshes & Lightmaps"] D --> D3[".rsw Spatial World Scene & Model References"] E --> E1[".spr Paletted Sprite Decoder (RLE / RGBA)"] E --> E2[".act 8-Directional Keyframe & Sound Cue Reconstructor"] F --> F1[".lub Decompilation (Lua 5.0 / 5.1 Bytecode)"] C & D & E & F --> G["Synthesized World Map, Sprite Animation Player & Client Data Graph"] ``` ### Technical Capabilities & Modules 1. **GRF Archive Parsing & Decryption:** - Detect header magic (`Master of Magic`) and parse versions `0x102`, `0x103`, and `0x200`. - Decrypt obfuscated/DES-encrypted file tables and decompress entry streams using Zlib. - Extract raw assets preserving directory paths and Korean/CP949 or UTF-8 character encodings. 2. **Navigational Mesh & Map Parsing (`.gat`, `.gnd`, `.rsw`):** - Parse `.gat` collision grids: decode cell properties (Walkable, Water, Snipable, Wall) and generate 2D walkability bitmap masks. - Parse `.gnd` files: extract 3D height vertices, tile textures, and lightmap intensity values. - Parse `.rsw` files: extract world object references, light properties, and ambient sound emitter coordinates. 3. **Sprite & Action Animation Reconstruction (`.spr`, `.act`):** - Decode `.spr` paletted images with Run-Length Encoding (RLE) and 32-bit RGBA sprite frames. - Parse `.act` animation tables: reconstruct keyframe frames, rotation angles (8 directions), sprite scaling, anchor attach points, and sound index triggers. - Export animated sprites to standard animated GIF or sprite-sheet PNGs. 4. **Compiled Lua Client Data Decompilation (`.lub`):** - Utilize REA's Lua decompiler (#3699) to decompile `.lub` files back to human-readable tables: - `itemInfo.lub`: Item IDs, names, descriptions, and sprite resource mappings. - `jobname.lub` / `accessoryid.lub`: Sprite attachment IDs and identifiers. ### Acceptance Criteria - [ ] Successful extraction of assets from encrypted and compressed `.grf` archives. - [ ] Conversion of `.gat` navigational files into binary walkability masks and collision matrices. - [ ] Parsing of `.spr` and `.act` pairs and generation of composite sprite animation frames. - [ ] Decompilation of `.lub` client database files into structured JSON or Lua tables. - [ ] Export of an integrated spatial manifest linking map geometry, collisions, and model placements. ### Related Issues & Dependencies - Complements #3621 (Unknown binary file-format inference) - Complements #3699 (Lua and LuaJIT bytecode reverse engineering) - Complements #3698 (Interactive entertainment runtime and asset reverse engineering tracker)

bsakaguchi referenced this issue

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

[PR #1418] [CLOSED] fix(cli): describe native command options accurately in help #2872

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#1418

No description provided.

Rows
Columns