BOF3 reverse-engineering workspace

A reverse-engineering project that recovers independently loaded Breath of Fire III binaries as readable C89, backed by target-qualified evidence and byte checks.

Prerequisites

• Linux on x86_64 — the supported host. First-time setup downloads Linux-only managed binaries: the canonical compiler is a statically linked Linux ELF (toolchains/gcc-2.7.2-psx/gcc), PSn00b ships *-linux.zip artifacts, and the compiler-variant catalog is pinned to linux-x86_64. macOS and Windows are not supported; a compatibility layer (for example WSL or a VM) may work but is not tested.
• just and uv (used by just setup to create the Python 3.12+ virtual environment)
• git (fetches submodules), cargo (builds the local bof3-disk/emi-ex tools), and meson (>= 0.58.0) with a host C compiler (gcc or clang) and ninja (>= 1.8.2) — Meson's native build backend compiles the Rizin toolchain and fails closed without either
• cmake (>= 3.20) — every lift verification rebuilds the authored object through CMake; bin/harness lift asm-diff and bin/harness build fail closed without it
• 7z — first-time setup downloads and extracts a staged PsyQ .7z, and the same host tool extracts the BreathOfFireIIIv1.1.7z media archive when no already-extracted CUE/BIN set exists
• A licensed CUE/BIN set of Breath of Fire III (US release) under inputs/external/
• Internet access for the first-time toolchain download

Quick start

just setup
just doctor

just setup initializes retained dependencies, user-authorized media, and local toolchains. just doctor verifies the result. See Tool usage for the complete ordered workflow.

Work on an extracted executable image or EMI entry — never the EMI archive. Original bytes and target manifests are the source of truth.

Observe PS1 behavior

The managed emulator is PCSX-Redux Agentic, our fork for bounded reverse-engineering missions. It embeds the Lua mission library and owns the psx-emulator skill.

just setup --component pcsx-redux
bin/harness runtime missions
bin/harness runtime run --bios inputs/external/bios/scph5501.bin --mission frames --argument target=0xbfc00004 --argument frames=1 --output out/runtime/frames --timeout 30

The example captures one frame after the first BIOS instruction. Supply licensed inputs and the mission arguments listed by the skill. Each run records its emulator, inputs, limits, completion, and captures in its output receipt. See Runtime setup.

Lift one function

bin/harness source splat TARGET
bin/harness lift m2ctx TARGET@0xADDRESS
bin/harness lift m2c TARGET@0xADDRESS -o out/candidate.c
# Edit the metadata-owned lift source under src/bof3/<subsystem>/.
bin/harness lift asm-diff TARGET@0xADDRESS
bin/harness lift byte-match TARGET@0xADDRESS

Lift identity and target ownership come from explicit manifest claims, maps, Splat, and parsable @source/@behavior metadata — never directory ancestry or filenames. Read Function matching before proposing a lift.

Status

bin/harness lift status [TARGET...]   # live matching status of tracked lifts
bin/harness source symbols check               # symbol maps and naming debt
just check                      # full practical validation gate

Documentation

Start with docs/INDEX.md for the request-oriented documentation map.

Task	Reference
Complete ordered tool workflow	Tool usage
Build and run PS1 emulator missions	Emulator integration
Lift and match one function	Function matching
Resolve asm-diff symptoms	Matching playbook
Memory macros and qualifiers	Memory API
Understand target identity and ownership	Context
Read reviewed format/runtime/data findings	Specs
Avoid known reverse-engineering mistakes	Lessons

Run --help or --example on commands. Want to help? Read CONTRIBUTING.md.