[MrSapps]

A C++17 tool, heavily inspired by decomp-permuter, that permutes the source of one C++ function until its compiled code matches a target object. It is built for gta2_re and MSVC 6. MIT licensed, like decomp-permuter.

What it does

• Finds the function in the .cpp and parses only its body. There is no preprocessing, so the rest of the file stays byte-identical.
• Applies mutation passes, compiles each candidate with your command, and scores the disassembly (llvm-objdump) against the target. A score of 0 means a byte-for-byte match.
• 31 passes. Most come from gta2_re's docs/matching_quirks.md or from decomp-permuter. Examples: every order of local saves, inline/sink/hoist/merge locals, ternary and if/else forms, one-case switch, inline getters, inequalities, case order and labels, local types and arrays, temporaries.
• docs/passes.md shows an example of every pass. It is generated from the passes themselves, and a unit test keeps it in sync.
• Search:
  • random and exhaustive modes;
  • pass combos (-p a+b), with -p repeatable;
  • PERM_* macros;
  • parallel workers.
• Inline helpers: --inline-callees / --also permute helpers in headers that VC6 inlines. Candidates compile in a per-worker mirror of the source tree, so the checkout is never written to.
• Speed: permuting costs about 0.5 ms per candidate against about 600 ms per compile. examples/gta2/compile.sh and .cmd use VC6 precompiled headers, which halves compile time with identical code. They are turned off while headers are permuted, because VC6 only checks them by timestamp.
• Platforms: Linux, and native Windows (cmd.exe, job objects, and a hard-link or copy fallback for the mirror).

Testing

• Unit tests: lexer, parser, every pass in both directions, combos, macros, scorer, workspace and mirror.
• Clang integration (67 runs): each case starts from a wrong base/ and must match target/, giving back the exact target source where expected. Controls without the pass under test must not match.
• gta2_re parse check: all 4,235 functions parse, and all 144,134 candidates parse back.
• VC6 integration (25 runs, under wine, on matching gta2_re functions):
  • It recovers the original source for: scrambled local saves in PromoteMemberToLeader, including a combo case; RemovePed (ternary_arg); IsTrainOrBoxcar (bool_return); sub_4C9150 (inequalities); and edits to Fix16::Max/Abs inlined into PedGroup.
  • It matches UpdateShortAnim (switch_if) and IsLeaderCloseToTargetCar (use_getter). The latter has a second matching source: it reads the car's x through Car_BC::get_x_41E430() instead of expanding the original getter.
  • VC6 compiled 63 of 63 random candidates.
• CI: Linux (GCC) and Windows (MSVC) run the unit and clang integration tests and upload the binaries as artifacts. The gta2_re and VC6 suites need a checkout and wine, so CI reports them as skipped.

main is a single empty initial commit, so this PR contains the whole tool. After merging, set main as the default branch in the repo settings.

🤖 Generated with Claude Code

---

Generated by Claude Code