Rats! source reconstruction with local LLMs

This repository is a work-in-progress reconstruction of the source code for RATS.EXE, the original Windows version of Rats! (1994) by Sean O'Connor. It builds a Win32 executable with Microsoft Visual C++ 4.1 under wibo and can be tested in DREAMM.

The experiment explores how far local LLMs can take source reconstruction on a small but realistic codebase rather than a toy example. Match fidelity remains uneven, which is useful here: the aim is to present a realistic view of the process and its current limitations, not to hide difficult functions.

Function reconstruction is restricted to local LLMs. Codex and Claude are used for repository setup and benchmark orchestration, but they are not allowed to write or edit the reconstructed source.

Unless noted otherwise, all experiments used Qwen3.8 27B BF16 on a 2024 MacBook Pro with an Apple M4 Max (16-core CPU, 40-core GPU) and 128 GB of memory. The approach works—imperfectly, but usefully: the 36 retained functions took an average logged time of 2m 32.1s each to reconstruct.

Setup

Clone with submodules, or initialise them after cloning:

git submodule update --init --recursive

The original executable is not included. Download the free Windows version from the official Rats! page and place its RATS.EXE in the repository root to use the original-executable and binary-comparison targets.

Common commands

make                 # build out/RATS_RE.EXE, .map, .obj, and .asm
make toolchain       # download, extract, and verify Microsoft Visual C++ 4.1
make run             # launch the rebuilt executable in DREAMM
make run-original    # launch the preserved original RATS.EXE
make test            # bounded DREAMM smoke test of the rebuilt executable
make test-original   # bounded DREAMM smoke test of the original executable
make debug           # start the rebuilt executable in DREAMM's debugger
make report          # report similarity for every reconstructed function
make compare-func FUNC=SaveHighScores ADDR=00409092

The checksum-pinned MSVC 4.1 archive, the required MSVC 4.1 libraries, wibo's compatible msvcrt40.dll, and DREAMM 4.0x21 are downloaded on demand. They remain ignored local build dependencies and are not committed.

Reconstruction workflow

The checked-in ghidra/ directory contains assembly and decompiler exports for all 177 internal functions. Assembly is the comparison authority; decompiled C is only a semantic seed.

Install binary-recons once, then run it from the repository root:

python3 -m pip install -e /path/to/binary-recons
binary-recons --next-function           # reconstruct the next safe missing target
binary-recons --address 0x409092        # reconstruct or improve a specific target

The tool discovers Qwen automatically in the standard Hugging Face cache; BINARY_RECONS_MODEL_PATH can override it. binary-recons.toml keeps automatic selection inside the game-code ranges, starts and stops llama.cpp, and defines the transactional files and binary-comp command. Each bounded run seeds one function from Ghidra, asks Qwen for focused compile or assembly-diff repairs, and retains the best safe compiling candidate. Use --target-score 95 for a deeper pass or --dry-run-prompt to inspect the prompt without loading Qwen.

Measured local-model runs are recorded in docs/MODEL_RESULTS.md.

Acknowledgements

Special thanks to:

• Sean O'Connor for creating Rats! and continuing to make its original Windows release available from the official game page.