Drew TBFM-decomp — Brave Fencer Musashi, decompiled
A matching decompilation of Brave Fencer Musashi (PlayStation, Square, 1998 — the USA release, SLUS-00726): C source that, compiled with the game's own 1990s toolchain, rebuilds every shipped code binary byte for byte. It is the first public decompilation of this game, and the whole of its game code is matched: the main executable, the always-resident engine, every location overlay and every code module streamed from the disc — 218 binaries, verified against a redump image of the original disc on every build.
The contract is narrow and machine-checkable. "Matching" means byte-identical output, checked by SHA1 against the
originals; nothing "functionally equivalent" counts. What the repository claims is exactly what make check-all proves.
Where it stands
| Metric | Matched | Of | % |
|---|---|---|---|
| Functions byte-identical (all binaries) | 363,214 | 363,214 | 100.00% |
| Instructions byte-identical (instruction-weighted) | 13,492,113 | 13,492,113 | 100.0% |
| Distinct code byte-identical (each body once) | 5,820,205 | 5,820,205 | 100.0% |
| Main executable game code (excl. Sony objects) | 45,150 | 45,150 | 100.0% |
218 binaries rebuild byte-identical from source · 360,737 functions in C (255,632 of them shared bodies via 2,220 dedup groups) · 1,256 Sony PsyQ library functions linked from the SDK objects, not our C · 5 hand-written-assembly bodies kept verbatim · 0 assembly stubs left · 0 non-matching functions.
Generated by tools/progress.py --readme from docs/progress.json — numbers are never typed by hand.
Two things in those binaries are deliberately not our C, and are stated as such:
- 1,256 functions of the main executable are Sony's PsyQ library code (libcd, libgs, libgte, libgpu, libspu/libsnd, libetc, libapi, libcard…). They link byte-identical from the SDK's own objects when you have the SDK, and are carried as assembly tiles taken from the disc when you do not — either way the executable is byte-identical. Reimplementing Sony's libraries is out of scope.
- Five functions across the fleet are hand-written assembly in the original and are kept as verbatim
__asm__bodies (config/verbatim_manifest.json, audited bytools/verbatim_check.py --strict).
Everything else — every game-code function in all 218 binaries — is C that the pinned compiler turns into the original
bytes. Progress numbers are generated from the sources (tools/progress.py), never typed by hand; the full recipe to
reproduce them is in docs/verification.md.
Build it from your own disc
The repository contains no game data: no executable, no disassembly, no assets, no memory dumps — only source, build
configuration, symbol names and hashes. You need your own redump-layout dump of the USA disc (Track 1 SHA1
b44f0f0a19936f23b26188b658e13201a6a9c211, CRC32 c238191b; the four-track BIN/CUE is ideal, Track 1 alone works).
git clone --recurse-submodules https://github.com/Druthulu/BFM-decomp.git && cd BFM-decomp
make bootstrap # toolchain preflight: venv, submodules, the pinned gcc-2.7.2 cc1 (sha256-checked)
mkdir -p disks && cp '/path/to/Brave Fencer Musashi (USA)'*.{bin,cue} disks/
make disc-extract # extracts the disc and checks all 1,801 files against the committed manifest
make clean && make -j"$(nproc)" extract-all && make -j"$(nproc)" check-all
# -> "check-all: 218 passed, 0 failed of 218"
Linux (WSL2 Ubuntu 24.04 is what the project uses); binutils-mipsel-linux-gnu, cpp-mipsel-linux-gnu, Python 3.12.
The main executable's SHA1 is 143dbb89f34491258bbc27810d0a12ec8b43a8dd. make help lists every target;
docs/verification.md gives each step's expected last line and the record of the last full run.
Toolchain (pinned by fingerprint evidence): gcc-2.7.2-psx cc1 -O2 -G0 -mips1 -mcpu=3000 -mgas -msoft-float -fgnu-linker
→ maspsx --aspsx-version=2.56 --expand-div → mipsel-linux-gnu-as -march=r3000 -mtune=r3000 -no-pad-sections -O1 -G0,
with per-file -O0 modules where the bytes demand it. The Sony PsyQ SDK objects are optional and user-supplied
(tools/fetch_psyq.sh); they are never redistributed.
What is in the repository
| Path | What |
|---|---|
src/ |
The C — one directory per binary (src/ itself is the main executable, src/resident/, src/ov_*/, src/md_*/), src/shared/ for the code shared across binaries via the dedup registry |
config/ |
splat configs, symbol files, per-binary SHA1 contracts (check.*.sha), the dedup registry, the Ghidra annotations as text (config/ghidra/) |
tools/ |
Everything the project built to do this: the byte gate, the extractor, the matching harness, the campaign machinery, the CI audits, the public-flip rewrite tooling; pinned submodules (maspsx, asm-differ, decomp-permuter, m2c) |
docs/ |
The matching cookbook (500+ compiler idioms), the gcc-2.7.2 codegen map, the memory map, the decision log, the accelerators, the runbooks, the story and the retrospective |
phase-ends/ |
The project's own governance record: one PhaseEnd per phase, the digest, the per-phase logs |
include/, extracted/retail/manifest.* |
Headers; the sha1 manifest your disc extraction is checked against |
How it was made
This project was carried out end to end by an AI coding agent — Claude Code — working inside a governance framework:
a static constitution (PROJECT_CONTEXT.md), a session protocol (CLAUDE.md),
two human gates per phase, an append-only record of every phase (phase-ends/), and a growing rule set
distilled from what went wrong. The framework is published separately as
ProjectArchitect; this repository is its largest worked example.
The reverse-engineering side ran on Ghidra driven over MCP, with a PCSX-Redux runtime oracle; the matching side is a byte gate over the whole binary, a permuter, a compiler-idiom cookbook, and — decisively — reading the gcc 2.7.2 source to explain the bytes the compiler emits. Everything that was learned is written down where it can be reused:
docs/matching-cookbook.md— the idioms, each byte-proven, and the compiler-internals lawsdocs/gcc-2.7.2-map/— the codegen map of the pinned compiler, by passdocs/decision-log.md— every strategic pivot with its measurement and its hindsightdocs/accelerators.md— what would have made earlier phases fasterdocs/story.mdanddocs/retrospective.md— the timeline and the retrospectivedocs/public-flip-runbook.md— how a private repository with game bytes in its history became this public one
About the history. The full development history is here — every commit, date and message — but it was rewritten
before publication to remove game-derived files from every revision. Old commit hashes cited inside historical documents
were replaced by inert tokens (commit:NNNN, the commit's ordinal); docs/commit-map.tsv maps
them to the commits you see, and documents at the tip cite the current hashes directly.
License
tools/anddocs/(the project's own work): AGPL-3.0 — seeLICENSE.src/: a reimplementation of copyrighted game code, provided for study and preservation; no license is asserted — seesrc/NOTICE.md.- Third-party components keep their own licenses — see
THIRD_PARTY.md.tools/brave-CUE/(CUE's reference extractor) is GPL-3.0; the Sony PsyQ SDK is never distributed.
Contributing, and the no-ROM policy
Nothing derived from the game may enter the repository: no executable, no disassembly, no assets, no memory image,
no SDK. CI enforces the tracked tree (tools/audit_public.py: no ROM-derived content by hash, no purge path, nothing
over 50 MiB), keeps every source text and portable, and compiles every translation unit with the pinned compiler. Byte
identity itself is verified locally with the disc, and the record of the last full run is committed.
The matching frontier is empty, so contributions that help most are not new matches: readability (structs and names in place of raw addresses), shiftability, tooling, and documentation. Open an issue first if you are unsure whether something is ROM-derived.
Special thanks
In the tradition of sotn-decomp, whose method this project followed from day one — this work stands on:
- splat, spimdisasm and rabbitizer — the split and the disassembly
- maspsx (mkst) — ASPSX's quirks, reproduced
- asm-differ and decomp-permuter (simonlindholm)
- m2c (matt-kempster) — the scaffolds
- old-gcc (decompals) — the compilers, and the gcc 2.7.2 source itself
- Ghidra, ghidra_psx_ldr (lab313ru) and GhidrAssistMCP — the static oracle and its hands
- psyq-obj-parser (decomp.me) — Sony's objects, readable
- PCSX-Redux — the runtime oracle
- brave-CUE (CUE) — the reference extractor ours was validated against
- The Xenogears, Vagrant Story and Tomba! decompilations — sibling PsyQ idioms
- redump, TCRF and gamehacking.org — the ground truth on the disc and in memory
- The Brave Fencer Musashi Archipelago world (AegeusEvander) — the living RAM map
- ProjectArchitect and Claude Code — the method and the hands
Brave Fencer Musashi is © 1998 Square. This project is not affiliated with or endorsed by Square Enix.