samp.directory
← Scripts e bibliotecas

janvrska/amx2pwn

Experimental AMX → PWN decompiler for SA-MP / open.mp

Ferramenta★ 0atualizado há 7 diasSem licençaPython
Abrir no GitHub

Este repositório não tem arquivo de licença. Ele é público para leitura, mas isso sozinho não dá permissão para reutilizar.

README.md

amx2pwn

An experimental decompiler that turns compiled Pawn scripts (.amx) back into readable .pwn source that compiles again. It targets SA-MP / open.mp gamemodes and filterscripts.

About this project

amx2pwn is an experiment, not a maintained product. It was built to test how far an AI coding assistant can get with a niche reverse-engineering task: reading a bytecode format, rebuilding control flow and producing code a human can edit. Almost all of the code was written by Claude (Anthropic). A human supplied the test scripts, ran the checks and steered the work.

Pawn and SA-MP are mostly history by now. The scripts it was tested on date from around 2008–2013. Expect rough edges, and only decompile scripts you have the right to work with.

Example

examples/welcome.pwn was compiled without debug info, so the .amx contains no variable or function names. The decompiler gives back:

new g_0[50];

stock func_8()
{
    new var0;
    for (new i; i < 50; i++)
    {
        if (IsPlayerConnected(i))
        {
            var0++;
        }
    }
    return var0;
}

public OnPlayerConnect(playerid)
{
    new name[24];
    new string[128];
    GetPlayerName(playerid, name, sizeof(name));
    g_0[playerid]++;
    format(string, sizeof(string), "Welcome, %s! Players online: %d", name, func_8());
    SendClientMessage(playerid, 0x33CCFFFF, string);
    if (g_0[playerid] > 1)
    {
        SendClientMessage(playerid, -1, "Welcome back!");
    }
    return 1;
}

The full output is in examples/welcome.decompiled.pwn. Names like playerid, name and string are inferred from how the values are used. Names the decompiler can't infer get placeholders such as g_0 or func_8.

Usage

Requires Python 3.8+ and nothing else.

python -m amx2pwn gamemode.amx

This writes gamemode.pwn (the decompiled source) and gamemode.asm (a disassembly listing). It refuses to overwrite an existing .pwn that it did not write itself.

OptionMeaning
-o out.pwnoutput file (single input only)
--no-asmskip the .asm listing
--emitdon't decompile; print function bodies as #emit assembly
--utf8convert strings from cp1250 to UTF-8 (default: bytes kept 1:1)
--shift Nforce string decoding as char = cell >> N (default: auto-detect)
--forceoverwrite an existing .pwn

You can also install it as a command with pip install . and then run amx2pwn gamemode.amx.

The output declares all natives and float operators itself, so it compiles with pawncc without a_samp.inc or float.inc.

What it handles

  • File format: 16/32/64-bit cells, compact encoding, file versions 1–11, old and new name tables, and debug info (-d1..-d3), which gives real names.
  • Control flow: if / else if / else, while, do … while, for, switch, break / continue, && / || chains, ?:, and assignments inside conditions.
  • Data:
    • local and global variables, plus 1D, 2D, ragged 2D (new names[][] = {…}) and 3D arrays with their initial values;
    • parameters passed by value, by reference and as arrays, including arg[][];
    • variadic functions (func(a, ...));
    • functions that return strings;
    • packed and unpacked strings.
  • Floats: Float: tags are inferred for variables, arrays, parameters and return values. floatadd(a, b) becomes a + b, and floatcmp(a, b) > 0 becomes a > b.
  • Readability:
    • well-known library functions are recognised and named (dini, dudb, dutils, strtok, IsNumeric, …), and so are dcmd_* commands;
    • variable names are inferred from usage (x, y, z, name, len, loop counters i, j, k);
    • natives get proper argument forms: sizeof(array), true / false, 'a' / EOS, enum constants like io_read, and trailing default arguments are dropped;
    • old-compiler quirks are reproduced so the output compiles with a current pawncc.

How well does it work?

It was tested on a private archive of 332 distinct .amx files from around 2008–2013: filterscripts, gamemodes up to 2.4 MB and compiled includes. Every output was compiled with pawncc 3.10.10.

  • 309 of 332 decompile into source that compiles with 0 errors. Warnings remain, mostly about unused variables and parameters that were in the original code.
  • The other 23:
    • 10 are damaged or not AMX files at all (truncated, run through a text conversion, or encrypted);
    • 9 are compiled includes without any public function, so there is nothing to compile them into (8 of them are empty);
    • 2 rely on YSI, whose hand-written #emit code jumps to computed addresses;
    • 2 use constructs that can't be written without the original enum declarations or that the decompiler doesn't recognise yet (an enum-indexed sub-array assignment and a ragged 3D string array).
  • Round trip: 17 of the scripts (about 2,000 functions, from tiny filterscripts to 300-function gamemodes) were also compiled again, decompiled again and compared with the first output. About 99% of functions come back with the same structure. In the rest, the operands of a comparison are swapped, the branches of a ?: are in the other order, or a temporary variable is left over. None of the differences we checked changed behaviour.
  • Speed: a typical script takes a second or less; the largest 2.4 MB gamemodes take about 12 seconds.

What it does not do:

  • Comments, macros, #defines, enum names and original names can't come back without debug info, because the compiler throws them away.
  • goto and odd control flow: code the compiler produced from goto or unusual jumps can come out as goto / labels or as #emit blocks.
  • Hand-written #emit code that reads the return address, changes the stack or jumps to computed addresses (as YSI does) has no plain Pawn equivalent. Such a function is written as a comment that points to the .asm listing, and the rest of the file is still produced.
  • Anti-decompiler tricks from the SA-MP days are handled where the code is still valid: calls with missing arguments, memory accesses outside the data section (kept as #emit), calls into code that is not a function (an empty stub is declared). A damaged file is reported, not guessed at.

Comparison with other AMX decompilers

amx2pwnPyDeAMXDeAMX
RuntimePython 3.8+Python 3.10+Lua 5.1
Interfacecommand linecommand line, GUIcommand line
Needsonly the .amxthe .amx and matching includesonly the .amx
AMX formats16/32/64-bit, versions 1–1132-bit, versions 6–1132-bit, newer versions
Debug infousedusedignored
Goalreadable sourceprovably equivalent rebuildreadable source
Outputone self-contained .pwn.pwn + support include + JSON reportone .pwn
Built-in result checknoyes, with a compilerno
Last update202620262021

On six SA-MP gamemodes from around 2008–2010, compiled with pawncc 3.10.10:

amx2pwnPyDeAMXDeAMX
Decompiled6 of 66 of 65 of 6
Functions as readable Pawnallabout 60%all
Output compiles6 of 60 of 60 of 5

In short: amx2pwn suits older scripts and source you want to read and edit. PyDeAMX suits modern scripts when you have the original includes and want the tool to verify the rebuild. DeAMX is the original 2008 tool and a small code base to learn from.

The full comparison covers control flow, floats, naming, libraries, licenses and the test details.

Code layout

amx2pwn/
  amxfile.py      .amx parser: header, tables, code/data, debug info, strings
  opcodes.py      Pawn opcode table
  listing.py      disassembler (.asm listing and --emit output)
  decompiler.py   bytecode simulation -> expression tree -> structured statements
  nodes.py        expression / statement tree and its helpers
  render/         turns the tree into Pawn source (one mixin per concern)
    floats.py       Float: tag inference
    readability.py  library recognition, naming, default arguments
    layout.py       layout of global arrays (1D/2D/3D/ragged)
    expressions.py  expression output
    statements.py   statement output
    output.py       whole-file output, declarations, naming passes
  natives.py      loads the native tables; Pawn core natives with default arguments
  omp_natives.py  SA-MP / open.mp natives and callbacks (generated, MPL-2.0)
  libraries.py    signatures of well-known library functions, naming tables
  literals.py     formatting of strings, floats and numbers
  cli.py          command line interface
tools/
  gen_natives.py  regenerates omp_natives.py from the open.mp includes

Adding a library

Many scripts bundled the same include files. To teach the decompiler a new function, add a line to LIBSIGS in amx2pwn/libraries.py. Each entry gives the function's name, its parameter names, and the features that identify its compiled code: number of parameters, natives it calls, string literals, constants and so on. For example:

("IsNumeric", ["string"], dict(nat=["strlen"], np=1, ret_arr=False,
                               natonly=["strlen"], const=[48, 57], nocalls=True)),

Tests

python -m unittest discover tests

The test decompiles the bundled example and compares the result with the expected output. The broader checks described above (compiling and round-tripping real scripts) need pawncc and the scripts themselves, so they aren't part of the repository.

Credits

decompileropen-mppawnsa-mp

Esta página é montada com o que o GitHub publica sobre o repositório. O samp.directory não hospeda o código. Avisar de um problema com esta página

janvrska/amx2pwn: Ferramenta de SA-MP | samp.directory