cLuaDecompiler.lpr

program cLuaDecompiler;

{
  By Coldzer0 - Copyright 2019 - 2026.

  cLuaDecompiler - Lua bytecode disassembler and decompiler.
  Supports Lua 5.1, 5.2, 5.3, 5.4, and 5.5 bytecode.
}

{$mode objfpc}{$H+}

uses
  SysUtils,
  LuaChunk,
  LuaDis,
  LuaSSA,
  LuaDecomp,
  LuaOpcodes;

{ ======================================================================
  Argument parsing
  ====================================================================== }

type
  TMode = (mdHelp, mdDis, mdDec, mdSSA);

  TOptions = record
    Mode           : TMode;
    Annotate       : Boolean;
    Debug          : Boolean;
    FileName       : AnsiString;
    LuaVersion     : Byte;       { 0 = auto-detect from header }
    OpcodeTableFile: AnsiString;  { '' = use built-in table }
  end;

procedure PrintHelp;
begin
  WriteLn('cLuaDecompiler - Lua bytecode disassembler / decompiler By Coldzer0 (c) 2019 - 2026');
  WriteLn('Contact: Coldzer0@protonmail.ch | Discord : Coldzer0');
  WriteLn('Supports Lua 5.1, 5.2, 5.3, 5.4, and 5.5 bytecode.');
  WriteLn;
  WriteLn('Usage:');
  WriteLn('  cLuaDecompiler [options] <file.luac>');
  WriteLn;
  WriteLn('Options:');
  WriteLn('  --dis              Disassemble bytecode');
  WriteLn('  --dec              Decompile to pseudo Lua source (default)');
  WriteLn('  --ssa-dump         Dump SSA IR (for debugging)');
  WriteLn('  --annotate         Add disassembly comments when decompiling');
  WriteLn('  --debug            Emit debug trace to stderr');
  WriteLn('  --lua-version VER  Override Lua version detection (51/52/53/54/55)');
  WriteLn('  --opcode-table F   Load custom opcode mapping from text file F');
  WriteLn('  --help             Show this message');
  WriteLn;
  WriteLn('Examples:');
  WriteLn('  cLuaDecompiler script.luac              -- disassemble (auto-detect version)');
  WriteLn('  cLuaDecompiler --dec script.luac        -- decompile');
  WriteLn('  cLuaDecompiler --ssa-dump script.luac   -- SSA dump');
  WriteLn('  cLuaDecompiler --dec --annotate x.luac  -- annotated decompile');
  WriteLn('  cLuaDecompiler --opcode-table map.txt obfuscated.luac');
  WriteLn('  cLuaDecompiler --lua-version 51 --opcode-table map.txt patched.luac');
end;

function ParseArgs(out Opts: TOptions): Boolean;
var
  I: Integer;
  Arg, VerStr: AnsiString;
  VerNum: Integer;
begin
  Opts.Mode           := mdDec;
  Opts.Annotate       := False;
  Opts.Debug          := False;
  Opts.FileName       := '';
  Opts.LuaVersion     := 0;
  Opts.OpcodeTableFile := '';
  Result              := True;

  I := 1;
  while I <= ParamCount do begin
    Arg := ParamStr(I);
    if Arg = '--help' then begin
      Opts.Mode := mdHelp; Exit;
    end else if Arg = '--dis' then
      Opts.Mode := mdDis
    else if Arg = '--dec' then
      Opts.Mode := mdDec
    else if Arg = '--ssa-dump' then
      Opts.Mode := mdSSA
    else if Arg = '--annotate' then
      Opts.Annotate := True
    else if Arg = '--debug' then
      Opts.Debug := True
    else if Arg = '--lua-version' then begin
      Inc(I);
      if I > ParamCount then begin
        WriteLn(StdErr, 'Error: --lua-version requires a version number (51/52/53/54/55).');
        Result := False; Exit;
      end;
      VerStr := ParamStr(I);
      VerNum := StrToIntDef(VerStr, 0);
      case VerNum of
        51: Opts.LuaVersion := $51;
        52: Opts.LuaVersion := $52;
        53: Opts.LuaVersion := $53;
        54: Opts.LuaVersion := $54;
        55: Opts.LuaVersion := $55;
      else
        WriteLn(StdErr, 'Error: unsupported version "', VerStr, '". Use 51/52/53/54/55.');
        Result := False; Exit;
      end;
    end
    else if Arg = '--opcode-table' then begin
      Inc(I);
      if I > ParamCount then begin
        WriteLn(StdErr, 'Error: --opcode-table requires a filename.');
        Result := False; Exit;
      end;
      Opts.OpcodeTableFile := ParamStr(I);
    end
    else if (Length(Arg) > 0) and (Arg[1] <> '-') then begin
      if Opts.FileName <> '' then begin
        WriteLn(StdErr, 'Error: multiple input files specified.');
        Result := False; Exit;
      end;
      Opts.FileName := Arg;
    end else begin
      WriteLn(StdErr, 'Error: unknown option: ', Arg);
      Result := False; Exit;
    end;
    Inc(I);
  end;

  if (Opts.Mode <> mdHelp) and (Opts.FileName = '') then begin
    WriteLn(StdErr, 'Error: no input file specified.');
    Result := False;
  end;
end;

{ ======================================================================
  SSA dump: recurse over all protos
  ====================================================================== }

procedure DumpSSAProto(Proto: PProto; Depth: Integer; const OT: POpcodeTable);
var
  SF : PSSAFunction;
  I  : Integer;
begin
  if Proto = nil then Exit;
  WriteLn('=== SSA for proto at depth ', Depth,
          ' [', Proto^.Source, ':', Proto^.LineDefined, '] ===');
  SF := BuildSSAFunction(Proto, OT);
  try
    DumpSSA(SF);
  finally
    FreeSSAFunction(SF);
  end;
  for I := 0 to High(Proto^.P) do
    DumpSSAProto(Proto^.P[I], Depth + 1, OT);
end;

{ ======================================================================
  Main
  ====================================================================== }

var
  Opts     : TOptions;
  Chunk    : TLuaChunk;
  DOpts    : TDecompOptions;
  CustomOT : TOpcodeTable;
  OTPtr    : POpcodeTable;
  ErrMsg   : AnsiString;

{$R *.res}

begin
  if not ParseArgs(Opts) then begin
    PrintHelp;
    Halt(1);
  end;

  if Opts.Mode = mdHelp then begin
    PrintHelp;
    Halt(0);
  end;

  { Load the binary chunk }
  if not LoadChunkFromFile(Opts.FileName, Chunk) then
    Halt(2);

  { Apply version override if specified }
  if Opts.LuaVersion <> 0 then begin
    Chunk.Header.Version := Opts.LuaVersion;
    { Rebuild opcode table for the overridden version }
    if not GetBuiltinTable(Opts.LuaVersion, Chunk.OpTable) then begin
      WriteLn(StdErr, 'Error: no built-in opcode table for version override.');
      Halt(1);
    end;
  end;

  { Load custom opcode table if specified }
  if Opts.OpcodeTableFile <> '' then begin
    ErrMsg := '';
    if not LoadOpcodeTableFromFile(Opts.OpcodeTableFile, CustomOT, ErrMsg) then begin
      WriteLn(StdErr, 'Error: failed to load opcode table from "',
              Opts.OpcodeTableFile, '": ', ErrMsg);
      Halt(1);
    end;
    Chunk.OpTable := CustomOT;
  end;

  { Determine opcode table pointer for version-aware paths }
  if Chunk.OpTable.NumOpcodes > 0 then
    OTPtr := @Chunk.OpTable
  else
    OTPtr := nil;

  try
    DOpts.FileName := ExtractFileName(Opts.FileName);
    case Opts.Mode of

      mdDis: begin
        DisassembleChunk(Chunk);
      end;

      mdDec: begin
        DOpts.Annotate := Opts.Annotate;
        DOpts.Debug    := Opts.Debug;
        DOpts.Indent   := '  ';
        DOpts.OT       := OTPtr;
        DecompileChunk(Chunk, DOpts);
      end;

      mdSSA: begin
        DumpSSAProto(Chunk.Root, 0, OTPtr);
      end;

      mdHelp: ;

    end;
  finally
    FreeProto(Chunk.Root);
  end;
  WriteLn();
end.