# BeetleRecomp

A work-in-progress **native PC port of _Beetle Adventure Racing!_ (N64, USA)** built by
**static recompilation** with the [N64Recomp][N64Recomp] toolchain — the same approach
behind [Zelda 64: Recompiled](https://github.com/Zelda64Recomp/Zelda64Recomp).

> **Status (2026-07-01): playable.** Boots through the intros and menus into races and renders at
> 60 fps, with keyboard + gamepad input and audio working. Ships an in-app launcher / settings /
> cheats / pause menu (RmlUi over RT64), internal-resolution scaling (defaults to display-native),
> MSAA + a VI "divot" seam filter, and high-FPS interpolation (phase 1). A handful of polish items
> remain — see **[docs/TODO.md](docs/TODO.md)** for the roadmap and **[docs/STATUS.md](docs/STATUS.md)**
> to resume.

> **No game data is included.** You must supply your own legally-dumped USA ROM
> (SHA-1 `e5ab4d226c08d22f68a2edcc48870203e67454b8`). No ROM, assets, or other copyrighted
> material may ever be committed to this repo.

## What this is

Static recompilation translates the N64's MIPS machine code into C automatically, then links
it against a modern runtime (CPU via [librecomp], graphics via [RT64], OS/audio/input via
[ultramodern]). It is **not** a manual rewrite and does **not** require a finished
decompilation.

This port is a sibling to the **[BeetleDecomp](https://github.com/bryankruman/BeetleDecomp)**
decompilation. The decomp is *not* a prerequisite for the recomp, but it is the source of the
**symbol-rich ELF** and the **module/relocation metadata** the recompiler consumes — which is
what makes this port tractable.

## Relationship to the decomp

This repo vendors the **[BeetleDecomp](https://github.com/bryankruman/BeetleDecomp)** project as a
submodule at `lib/bar-decomp`. Two things are worth knowing up front:

**The recomp does *not* compile the decomp's C.** Static recompilation translates the original
ROM's MIPS *machine code* into C automatically; the decomp's hand-written C is never built into the
port. What the port takes from the decomp is:

| From the decomp | What for |
|---|---|
| The **symbol-rich ELF** that rebuilds the ROM byte-for-byte | Input to N64Recomp (built in WSL, never committed) |
| **Headers + symbol tables** | Readable names + typed interfaces for generated code and patches |
| **Segmentation / module + reloc layout** | Overlay handling for BAR's ~130 relocatable modules |

Because the decomp is *byte-matching*, its matching progress doesn't change the port — recompiling a
function yields identical output whether it started as hand-written C or raw asm. What flows
downstream from decomp work is better **names and types** (readability of generated code and patches)
and the **module layout** that makes the port tractable.

**Changes never go in the decomp** — keep it a faithful mirror of the original. Modifications live in
two recomp-owned layers:

- **`patches/`** — C cross-compiled to MIPS that **overrides** (`RECOMP_PATCH`) or **hooks**
  (`RECOMP_HOOK`) game functions by name. This is the game-logic layer: bug fixes, widescreen, new
  features. Patches link *before* the recompiled output, so they win.
- **`src/`** — the native C++ host: rendering (RT64), input, audio, saves, config, and the in-app UI.

See [BUILDING.md](BUILDING.md) for how the ELF is produced and how to pull decomp updates.

## Technical profile

The properties that made BAR a good recomp candidate, and which shape the runtime:

| Aspect | Detail |
|---|---|
| **Graphics microcode** | Stock **`gspF3DEX2_fifo`** (decomp `gfx_ucode: f3dex2`) — *not* a custom Paradigm ucode. RT64 supports F3DEX2 directly. |
| **Audio** | Standard libultra (`alAudioFrame`/`alSeqFileNew`/ALSndPlayer) wrapped in Paradigm's "UV" middleware. |
| **Saves** | Controller Pak only (`osPfs*`); no EEPROM/SRAM/Flash. The port emulates a Controller Pak. |
| **Memory** | 4 MB; **no Expansion Pak**, no TLB-mapped code (flat KSEG0). |
| **Entry point** | `0x80000400` (ROM header offset 0x8 == splat `entry` segment vram). |
| **Module layout** | The **~130 relocatable code modules** (`ai`, `battle`, `race`, …, `uv*_rom`) were the crux of the port; the uv module overlay bridge (`src/main/overlay_bridge.cpp`) registers them at load. |

The toolchain license analysis and research sources are in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## How it fits together

```
your ROM ─┐
          ├─► BeetleDecomp (WSL) ──► symbol-rich ELF ──► N64Recomp ──► RecompiledFuncs/*.c ─┐
recomp.ld ┘   (per-module layout)                       (BeetleRecomp.toml)                 ├─► CMake ─► BeetleRecomp(.exe)
                                                                                            │
 patches/*.c ─► clang -target mips ─► patches.elf ─► N64Recomp (patches.toml) ─► RecompiledPatches/*.c ┘
                                                            │
            runtime: librecomp + ultramodern + RT64 ───────┘
```

## Repository layout

```
BeetleRecomp/
├── BeetleRecomp.toml      # main N64Recomp config (entrypoint 0x80000400, ELF, overlays)
├── patches.toml           # config for the C patches (MIPS override/hook layer)
├── overlays.us.txt        # relocatable module/overlay section list
├── CMakeLists.txt         # host-app build (clang-cl + Ninja)
├── COPYING                # AGPL-3.0 (inherited from the decomp)
├── THIRD_PARTY_NOTICES.md # dependency licenses + research sources
├── BUILDING.md            # full build instructions (Windows + Linux/macOS)
├── docs/                  # STATUS.md (resume guide), TODO.md (roadmap), design notes
├── src/
│   ├── main/              # native host: RT64 render context, input, audio, overlay bridge, config
│   ├── game/              # game-facing config schema (graphics.json)
│   └── ui/                # in-app RmlUi launcher / settings / cheats / pause menu + renderer
├── patches/               # C compiled to MIPS that overrides/hooks game functions
├── include/               # port headers
├── rsp/                   # RSP microcode glue
├── scripts/               # setup / fetch-elf / gen-overlays / fix-recompiled helpers
├── assets/  icons/        # bundled app assets
├── elf/  syms/            # decomp ELF + patch symbol TOMLs land here (git-ignored)
└── lib/                   # git submodules:
    ├── bar-decomp                 # BeetleDecomp — symbols, headers, module/reloc layout (source ref)
    ├── N64Recomp                  # the static recompiler (MIPS → C)
    ├── N64ModernRuntime           # librecomp (CPU) + ultramodern (OS/audio/input)   [bryankruman fork]
    ├── rt64                       # RT64 renderer (D3D12 / Vulkan / Metal)            [bryankruman fork]
    ├── RmlUi                      # HTML/CSS UI toolkit for the in-app menus
    ├── lunasvg                    # SVG rasterizer (RmlUi dependency)
    └── freetype-windows-binaries  # prebuilt Freetype for RmlUi text (Windows)
```

## Quickstart

> Full details and prerequisites: **[BUILDING.md](BUILDING.md)**.

```bash
# 1. Fetch dependencies and build the recompiler (N64Recomp + RSPRecomp).
scripts/setup.sh                  # or scripts/setup.ps1 on Windows PowerShell

# 2. Build the decomp ELF (in WSL), then copy it in.
#    (WSL) cd ~/projects/bar-decomp && source .venv/bin/activate && make recomp
scripts/fetch-elf.sh              # or scripts/fetch-elf.ps1

# 3. Recompile the game to C.
./N64Recomp BeetleRecomp.toml     # emits RecompiledFuncs/*.c
scripts/fix-recompiled.sh         # REQUIRED codegen fixup — re-run after every regeneration

# 4. Configure + build the port (clang-cl on Windows, clang on Linux/macOS).
cmake -S . -B build-cmake -G Ninja -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_BUILD_TYPE=Release
cmake --build build-cmake -j
```

## Status & roadmap

The bring-up milestones — the per-module recomp ELF, overlay wiring, first boot, F3DEX2 rendering,
input, audio, and Controller Pak saves — are **done**, and the game is playable. Current work is
polish and features:

- **Rendering** — internal-resolution scaling (defaults to display-native), MSAA + a VI "divot"
  seam filter, and high-FPS interpolation (phase 1 live; throughput/artifact phases pending).
- **Known issues** — skippable legal/logo screens, a one-frame menu-transition flash, choppy
  track-map preview, audio latency-vs-clip tuning.
- **Features** — controller rebind UI, mod-manager UI, an app icon, and more settings surfaced in
  the in-app menu.

The live checklist is **[docs/TODO.md](docs/TODO.md)**; per-item status and resume detail is in
**[docs/STATUS.md](docs/STATUS.md)**.

## License

**AGPL-3.0**, inherited from the BeetleDecomp data this port derives from. See
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the dependency-license analysis and why
AGPL is the correct umbrella. Vendored dependencies in `lib/` retain their own licenses.
**Distribute no game assets.**

## Credits

- **SynaMax / synamaxmusic** and **LLONSIT** — original
  [bar-decomp](https://github.com/synamaxmusic/bar-decomp) / RE work this builds on.
- **Wiseguy** and contributors — [N64Recomp], [N64ModernRuntime], Zelda 64: Recompiled.
- **RT64 contributors** — the renderer.
- **RmlUi** and **lunasvg** — the in-app menu toolkit and SVG rasterizer.

[N64Recomp]: https://github.com/N64Recomp/N64Recomp
[N64ModernRuntime]: https://github.com/N64Recomp/N64ModernRuntime
[librecomp]: https://github.com/N64Recomp/N64ModernRuntime/tree/main/librecomp
[ultramodern]: https://github.com/N64Recomp/N64ModernRuntime/tree/main/ultramodern
[RT64]: https://github.com/rt64/rt64