How xeonise/medal2 works
Project Type and Purpose
• This repository is a language-tooling project: a decompiler for Lua bytecode (both Lua 5.1 and Roblox’s Luau dialect). It is organized as a workspace of Cargo crates that implement:
• Bytecode deserialization (lua51-deserializer, luau-lifter/deserializer)
• Bytecode-to-AST lifting (lua51-lifter, luau-lifter)
• AST representation and transformations (ast)
• Control-flow analysis and SSA transformations (cfg)
• Control-flow restructuring back into structured AST (restructure)
• A decompilation server or worker interface (decomp-server, luau-worker)
Top-Level Components
• Crates:
• lua51-deserializer: parse .luac chunk to instruction structures
• lua51-lifter: lift 5.1 instructions into an initial AST
• luau-lifter: parse and lift Luau bytecode into AST
• ast: unified AST node definitions, name resolution, formatting to source code
• cfg: build and analyze control-flow graphs and SSA form
• restructure: restructure SSA/CFG back into structured constructs (if, loops)
• decomp-server: HTTP/CLI server exposing decompilation as a service
• luau-worker: a WASM or edge-worker wrapper around the decompilation pipeline
• Supporting files:
• playermodule.bin, script.lua – sample inputs
• wrangler.toml – Cloudflare Workers config (for luau-worker)
Component Interactions
• Data Flow:
[Bytecode File]
→ (1) Deserializer → Instr. Stream
→ (2) Lifter → Raw AST
→ (3) CFG Builder → SSA/CFG
→ (4) Restructurer → Structured AST
→ (5) Formatter → Decompiled Source
→ (6) Output to Console / HTTP Response / Worker Response
• Server/Worker:
• Accepts bytecode via HTTP or CLI
• Invokes the pipeline above
• Returns decompiled Lua source
Architectural Patterns and Principles
• Modular, single-responsibility crates (each crate focuses on one stage of decompilation)
• Pipeline pattern: chain of transformations from raw bytes to final text
• Clear separation of concerns: parsing, lifter, analysis, restructuring, formatting
• Reusability: ast and cfg crates are shared by both lua51-lifter and luau-lifter