Rats!* (1994) source code reconstruction using Qwen 3.8

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

wiboand 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.

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.

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.

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 Qwen.

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

Model results: 36 retained functions and 3 deferred addresses #

Most retained candidates were generated with Unsloth's Qwen3.8 27B GGUF in BF16 (Qwen3.8-27B-BF16

, served as qwen3.8-27b-bf16

) through llama.cpp with a 32,768-token context and the qwen

model preset. The current workflow uses Ghidra's decompilation as a mechanical seed, asks Qwen only for a meaningful contract and bounded source edits, follows valid edits as a repair trajectory, and retains the best result measured by binary-comp

. Gemma 4 31B IT BF16 was also benchmarked, but none of its candidates is retained in the source tree.

The scores below were remeasured from the current source tree with MSVC 4.1 and binary-comp

on 2026-08-16. Logged time includes managed-server startup, generation or repair, build, and comparison for the retained candidate. It excludes unsuccessful exploratory runs and repair turns made after a resumable candidate had already been produced; those remain available in the run logs.

Reconstruction attempts for the following addresses were exhausted without retaining a source implementation. Time spent is cumulative across all logged attempts.

Special thanks to:

Sean O'Connorfor creatingand continuing to make its original Windows release available from theRats!official game page.