Project Nexus — Super Smash Bros. Brawl static recompilation + Project+ (+ REX)

A native static recompilation of Super Smash Bros. Brawl (Wii, USA RSBE01 Rev 2), with the Project+ v3.2.1 mod built in and Super Smash REX (a Project+ based mod) in progress. A launcher picks the version to play. Wii (Broadway PowerPC) code is translated ahead of time to C++ by our own recompiler and runs on a host runtime. Targets: Windows first, then Linux and mobile (Android/iOS, ARM64).

No game data is in this repository. You need your own legally dumped disc (and the Project+ files) to build or run anything.

Status (2026-11-10)

Area	State
Recompiler (Broadway: paired singles, psq_l/st + GQR quantization, MWCC jump tables, pre-linked RELs)	Done. Acceptance clean: 92.6k vanilla functions, 115k Project+
Runtime: boot, OS/threads (fibers), IOS/NAND, DVD, VI, REL linking	Done
Graphics: GX FIFO → Aurora (WebGPU/Dawn)	Menus, CSS, stage select and full matches render at ~60 fps, 1280×720
Audio: AX command list run host-side → SDL3 audio	Done (music, SFX, THP movie audio)
Input: GameCube pads via SDL3 (gamepads + keyboard), XInput fallback	Done (Wii Remote/Classic not yet, see docs/design_wpad.md)
Movies (THP)	Opening and SSE cutscenes play with picture and sound
Vanilla Brawl	Playable: full matches on every stage tested
Project+ v3.2.1	Playable offline: VS (repeated sessions), Training, Classic, All-Star, Events, Target Smash, Home-Run, Multi-Man, Boss Battles, Special Versus, Subspace Emissary (through the first levels)
Super Smash REX 0½	Package analysed (same layout as P+); port next
Launcher	Done: pick Brawl / Project+ / REX, fullscreen option, crash report with log
Regression gate	sh tools/regress.sh: 4 headless scripted runs (vanilla match, P+ VS cycle, Training, SSE)
Portability	Host-OS code isolated (fibers, memory map, crash handler); Linux backend next

Launcher

Project+ v3.2.1: Solo modes, Subspace Emissary, Events, Stadium

Opening movie (THP) with audio

Vanilla Brawl: matches running natively

Project+ v3.2.1: Character Select Screen and a match

How Project+ works here

P+ is a Gecko code list (RSBE01.GCT + BOOST.GCT) plus replacement files and RELs. Patching code at runtime does not reach recompiled code, so the codes are split into a static part and a runtime part:

• Host Gecko engine (runtime/src/hle/gecko.cpp) runs the code lists in guest RAM at their console addresses (0x80566528, 0x80550010). It runs as the guest codehandler at 0x800018A8 and at the Hooktype VBI/AX slots. It applies data writes, ifs, gecko registers, pointers and gotos with real codehandler semantics.
• Static code patches: PM_GECKO_RECORD records every code patch the engine sees. tools/prelink.py --gecko then:
  • bakes the code writes into the image;
  • turns each C2 insert into a splice that the recompiler inlines at its site (EmitSplice, EmitSpliceRaw);
  • turns P+'s custom code into functions (CODE @ regions, embedded snippets, custom function slots);
  • splits functions where P+ jumps into the middle of game code.
• Fixed modules: the 7 shared menu/game modules P+ patches are pre-linked at their console heap addresses (--fixed), so P+'s absolute addresses hit the code that runs.
• Syringe: P+'s plugin loader (sy_core.rel, from P+ common2.pac) is pre-linked with --extra. Its plugins (AsyncRSP, lavaInjectLoader, lavaNeutralSpawns) load from the SD folder; their hooks are recorded once and baked into the recompiled image (tools/syringe_rec.py).
• SD card: the Revolution VF FAT layer (FAFopen/FAFstat/FAFread…) is served from the P+ SD folder (runtime/src/hle/sd.cpp). P+'s own FilePatchCode, sound-bank streaming and MultiGCT therefore run as on console.

Layout

Path	Contents
recomp/	Recompiler (XenonRecomp fork + Broadway backend XenonRecomp/broadway.inl, C2 splicing)
runtime/	Host runtime: memory map, loader, scheduler, HLE (src/hle/), GX bridge (src/gpu/), audio
tools/	prelink.py (DOL+REL → pre-linked ELF), relfuncs.py (function discovery for symbol-less RELs), gct.py, brawl_arc.py, build scripts
config/	Recompiler configs (brawl_config.toml, pplus_config.toml)
runtime/launcher/	Launcher (SDL3 + Dear ImGui)
docs/	Design docs (design_runtime.md, design_projectplus.md, design_wpad.md), recompile logs
STATE.md	Detailed progress log and next steps

Building (Windows)

Requirements: VS 2022 Build Tools, LLVM (clang-cl), CMake, Ninja, Python 3.

1. Extract the disc's DATA partition to Disc/DATA (e.g. wit). Get the decomp symbols into external/brawl-decomp (config RSBE01_02).
2. Vanilla:

   python -I tools/prelink.py Disc/DATA external/brawl-decomp/config/RSBE01_02 assets/brawl.elf
   tools\build_recomp.bat
   recomp\build\XenonRecomp\XenonRecomp.exe config\brawl_config.toml recomp\XenonUtils\ppc_context.h
   tools\build_runtime.bat
   

3. Project+: put the P+ v3.2.1 package in Project+.v3.2.1.Wii/, extract the Syringe RELs into Project+.v3.2.1.Wii/extra_rels (see tools/prelink_pplus.sh), then:

   sh tools/prelink_pplus.sh
   tools\build_runtime_pplus.bat
   

   Output: runtime/build_pplus/projectm.exe.
4. Launcher: tools\build_runtime.bat --target launcher, then run runtime\build\launcher.exe (--play brawl|pplus starts a version directly). Optional local art (not in git): runtime/res/launcher_bg.jpg (launcher background) and runtime/res/local/ (app icon, from py tools/gen_icon.py <image> runtime/res/local/icon.ico runtime/res/local/icon_rgba.h).
5. After any runtime or recompiler change: sh tools/regress.sh (about 13 minutes).

Controls (keyboard, port 1): WASD stick, numpad C-stick, arrows D-pad, J/K/L/Space = A/B/X/Y, I = Z, Q/E = L/R, Enter = Start. Gamepads work through SDL3.

Legal

• Not affiliated with Nintendo. This is a fan-made, non-commercial preservation and research project. It is not affiliated with, endorsed by or sponsored by Nintendo, HAL Laboratory, Sora Ltd., Game Freak, Creatures Inc. or any other rights holder. Super Smash Bros. Brawl, Wii and all related characters, names and marks are trademarks of their respective owners.
• No game content is distributed. This repository contains only original tools and source code. It ships no ROMs, disc images, executables (DOL/REL), assets, audio, textures or code derived from the game's binaries, and no Project+ files. The recompiled C++ (generated*/), pre-linked images (assets/) and extracted data are produced locally from the user's own copy and must never be committed or shared.
• Bring your own copy. You must own a legitimate copy of Super Smash Bros. Brawl and dump it yourself from your own console and disc. Downloading game images you do not own is piracy, and this project does not support or help with it.
• Project+. Project+ is a separate community mod by the Project+ team, obtained from them and used under their terms. Super Smash REX is by the REX Development Team. This project only provides a way to run them natively and ships none of their files.
• Screenshots in docs/screenshots/ show the software running and are included for documentation (commentary/progress reporting). They remain the property of their owners.
• Third-party code keeps its own licenses: XenonRecomp (MIT), Aurora (MIT), SDL3 (zlib), and the libraries listed in recomp/THIRDPARTY.txt. GPL-licensed projects were consulted only as reference; none of their code is included.
• No warranty. Provided "as is", without warranty of any kind. Use at your own risk.
• Rights holders: if you have a concern about this project, open an issue or contact the maintainer, and it will be addressed promptly.

Credits

The recompiler and runtime were written for this project. References only, no code copied: the Brawl decompilation (symbols), BrawlRecompiled (GPLv3, read-only reference). Libraries used: XenonRecomp (base of the recompiler fork), Aurora (MIT, GX on WebGPU), SDL3, Dear ImGui (MIT), stb_image (public domain). Project+ is by the Project+ team; Super Smash REX is by the REX Development Team.