# katalash/dsluadecompiler architecture

> Architecture diagram of the GitHub repository katalash/dsluadecompiler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/katalash/dsluadecompiler
- Repository: https://github.com/katalash/dsluadecompiler

## Overview

DSLuaDecompiler converts Lua 5.0, HavokScript, and early Lua 5.3 bytecode into decompiled source, primarily for FromSoft game modding. The documented workflow parses bytecode, translates opcodes into a shared IR, applies reusable analyses and transformation passes to recover expressions and control flow, then prints source. The graph preserves the documented frontends and core recovery stages; the README describes their overall flow, while sampled source excerpts do not show every runtime call, so uncertain orchestration links are dashed.

Main entry points: [`LuaDecompilerCore/IR/Function.cs`](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/IR/Function.cs) (Shared function IR), [`LuaDecompilerCore/LuaFile.cs`](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LuaFile.cs) (Bytecode parser), [`DSLuaDecompiler/Program.cs`](https://github.com/katalash/dsluadecompiler/blob/master/DSLuaDecompiler/Program.cs) (CLI), [`LuaDecompilerCore/LuaDecompiler.cs`](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LuaDecompiler.cs) (Decompilation coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and parsing"]
  node_cli["CLI<br/>[Program.cs]"]
  node_lua_file["Bytecode parser<br/>[LuaFile.cs]"]
  node_core["Decompilation coordinator<br/>[LuaDecompiler.cs]"]
end

subgraph group_frontends["Bytecode frontends"]
  node_lua50["Lua 5.0 frontend<br/>[Lua50Decompiler.cs]"]
  node_hks["HavokScript frontend<br/>[HksDecompiler.cs]"]
  node_lua53["Lua 5.3 frontend<br/>[Lua53Decompiler.cs]"]
end

subgraph group_recovery["IR recovery"]
  node_ir["Shared function IR<br/>[Function.cs]"]
  node_expressions["Expression IR<br/>[Expression.cs]"]
  node_instructions["Instruction IR<br/>[Instruction.cs]"]
  node_cfg["Control-flow graph<br/>[BasicBlock.cs]"]
  node_pass_manager["Pass manager<br/>[PassManager.cs]"]
  node_passes["IR transformation passes"]
  node_analyzers["Recovery analyses"]
  node_ast["AST structuring"]
end

subgraph group_output["Source output"]
  node_printer["Source printer<br/>[FunctionPrinter.cs]"]
  node_result["Decompiled Lua source<br/>[FunctionPrinter.cs]"]
end

node_user(("Decompiler user"))

node_user -->|"runs"| node_cli
node_cli -->|"invokes"| node_core
node_cli -->|"loads bytecode"| node_lua_file
node_lua_file -.->|"supplies bytecode"| node_lua50
node_lua_file -.->|"supplies bytecode"| node_hks
node_lua_file -.->|"supplies bytecode"| node_lua53
node_lua50 -->|"translates opcodes"| node_ir
node_hks -->|"translates opcodes"| node_ir
node_lua53 -->|"translates opcodes"| node_ir
node_ir -->|"represents code"| node_instructions
node_ir -->|"represents expressions"| node_expressions
node_pass_manager -->|"runs passes"| node_passes
node_pass_manager -->|"runs analyses"| node_analyzers
node_passes -->|"builds and transforms"| node_cfg
node_passes -->|"structures control flow"| node_ast
node_analyzers -->|"analyze variables"| node_ir
node_ast -.->|"provides AST"| node_printer
node_printer -->|"prints source"| node_result
node_core -.->|"coordinates recovery"| node_pass_manager
node_core -.->|"requests output"| node_printer

click node_cli "https://github.com/katalash/dsluadecompiler/blob/master/DSLuaDecompiler/Program.cs"
click node_lua_file "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LuaFile.cs"
click node_core "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LuaDecompiler.cs"
click node_lua50 "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LanguageDecompilers/Lua50Decompiler.cs"
click node_hks "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LanguageDecompilers/HksDecompiler.cs"
click node_lua53 "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LanguageDecompilers/Lua53Decompiler.cs"
click node_ir "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/IR/Function.cs"
click node_expressions "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/IR/Expression.cs"
click node_instructions "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/IR/Instruction.cs"
click node_cfg "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/CFG/BasicBlock.cs"
click node_pass_manager "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/PassManager.cs"
click node_passes "https://github.com/katalash/dsluadecompiler/tree/master/LuaDecompilerCore/Passes"
click node_analyzers "https://github.com/katalash/dsluadecompiler/tree/master/LuaDecompilerCore/Analyzers"
click node_ast "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/Passes/AstTransformPass.cs"
click node_printer "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/FunctionPrinter.cs"
click node_result "https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/FunctionPrinter.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_lua_file,node_core,node_user toneBlue
class node_lua50,node_hks,node_lua53 toneAmber
class node_ir,node_expressions,node_instructions,node_cfg,node_pass_manager,node_passes,node_analyzers,node_ast toneMint
class node_printer,node_result toneRose
```

## Components

### Entry and parsing

- [CLI](https://github.com/katalash/dsluadecompiler/blob/master/DSLuaDecompiler/Program.cs): `DSLuaDecompiler/Program.cs`
- [Bytecode parser](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LuaFile.cs): `LuaDecompilerCore/LuaFile.cs`
- [Decompilation coordinator](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LuaDecompiler.cs): `LuaDecompilerCore/LuaDecompiler.cs`

### Bytecode frontends

- [Lua 5.0 frontend](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LanguageDecompilers/Lua50Decompiler.cs): `LuaDecompilerCore/LanguageDecompilers/Lua50Decompiler.cs`
- [HavokScript frontend](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LanguageDecompilers/HksDecompiler.cs): `LuaDecompilerCore/LanguageDecompilers/HksDecompiler.cs`
- [Lua 5.3 frontend](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/LanguageDecompilers/Lua53Decompiler.cs): `LuaDecompilerCore/LanguageDecompilers/Lua53Decompiler.cs`

### IR recovery

- [Shared function IR](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/IR/Function.cs): `LuaDecompilerCore/IR/Function.cs`
- [Expression IR](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/IR/Expression.cs): `LuaDecompilerCore/IR/Expression.cs`
- [Instruction IR](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/IR/Instruction.cs): `LuaDecompilerCore/IR/Instruction.cs`
- [Control-flow graph](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/CFG/BasicBlock.cs): `LuaDecompilerCore/CFG/BasicBlock.cs`
- [Pass manager](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/PassManager.cs): `LuaDecompilerCore/PassManager.cs`
- [IR transformation passes](https://github.com/katalash/dsluadecompiler/tree/master/LuaDecompilerCore/Passes): `LuaDecompilerCore/Passes`
- [Recovery analyses](https://github.com/katalash/dsluadecompiler/tree/master/LuaDecompilerCore/Analyzers): `LuaDecompilerCore/Analyzers`
- [AST structuring](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/Passes/AstTransformPass.cs): `LuaDecompilerCore/Passes/AstTransformPass.cs`

### Source output

- [Source printer](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/FunctionPrinter.cs): `LuaDecompilerCore/FunctionPrinter.cs`
- [Decompiled Lua source](https://github.com/katalash/dsluadecompiler/blob/master/LuaDecompilerCore/FunctionPrinter.cs): `LuaDecompilerCore/FunctionPrinter.cs`

### Other components

- **Decompiler user**

## Connections

- Decompiler user → CLI: runs (evidence: `DSLuaDecompiler/Program.cs`)
- CLI → Decompilation coordinator: invokes (evidence: `DSLuaDecompiler/Program.cs`)
- CLI → Bytecode parser: loads bytecode (evidence: `DSLuaDecompiler/Program.cs`)
- Bytecode parser → Lua 5.0 frontend: supplies bytecode (evidence: `LuaDecompilerCore/LanguageDecompilers/Lua50Decompiler.cs`)
- Bytecode parser → HavokScript frontend: supplies bytecode (evidence: `LuaDecompilerCore/LanguageDecompilers/HksDecompiler.cs`)
- Bytecode parser → Lua 5.3 frontend: supplies bytecode
- Lua 5.0 frontend → Shared function IR: translates opcodes (evidence: `LuaDecompilerCore/LanguageDecompilers/Lua50Decompiler.cs`)
- HavokScript frontend → Shared function IR: translates opcodes (evidence: `LuaDecompilerCore/LanguageDecompilers/HksDecompiler.cs`)
- Lua 5.3 frontend → Shared function IR: translates opcodes
- Shared function IR → Instruction IR: represents code
- Shared function IR → Expression IR: represents expressions (evidence: `LuaDecompilerCore/IR/Expression.cs`)
- Pass manager → IR transformation passes: runs passes (evidence: `LuaDecompilerCore/PassManager.cs`)
- Pass manager → Recovery analyses: runs analyses (evidence: `LuaDecompilerCore/PassManager.cs`)
- IR transformation passes → Control-flow graph: builds and transforms (evidence: `LuaDecompilerCore/Passes/AstTransformPass.cs`)
- IR transformation passes → AST structuring: structures control flow (evidence: `LuaDecompilerCore/Passes/AstTransformPass.cs`)
- Recovery analyses → Shared function IR: analyze variables (evidence: `LuaDecompilerCore/Analyzers/LocalVariablesAnalyzer.cs`)
- AST structuring → Source printer: provides AST
- Source printer → Decompiled Lua source: prints source (evidence: `LuaDecompilerCore/FunctionPrinter.cs`)
- Decompilation coordinator → Pass manager: coordinates recovery (evidence: `LuaDecompilerCore/LuaDecompiler.cs`)
- Decompilation coordinator → Source printer: requests output
