# JackieChanRecomp — Jackie Chan Stuntmaster (USA)

Native PC recompilation of **Jackie Chan Stuntmaster** (SLUS-00684) built on
[psxrecomp](https://github.com/mstan/psxrecomp) (MIPS R3000A → C → native x64,
LLE recompiled BIOS) with the [recomp-ui](https://github.com/mstan/recomp-ui)
launcher for end-user options (video, controller, saves).

This is a **single-game recomp repository**, following the psxrecomp
per-game-repo model (like [TombaRecomp](https://github.com/mstan/TombaRecomp) /
[ApeEscapeRecomp](https://github.com/mstan/ApeEscapeRecomp)): it holds only this
title's config, seeds, and disc identity, and links the framework in as a
submodule. Other games live in their own repos.

## Status — playable 🎮, full 16:9 widescreen (2026-07-22)

Boots through the real recompiled BIOS → logos → FMV intro (MDEC) → **3D
gameplay with sound and image at a steady 60 fps**, with **full 16:9 widescreen**
(3D world + menus + cutscenes). First-ever bring-up of this title in the
psxrecomp ecosystem. Details + known issues: [ISSUES.md](ISSUES.md).

### Framework dependency (important — read before building)

This game needed several **framework** changes, contributed upstream to
`mstan/psxrecomp`:

| Feature | Upstream status |
|---|---|
| COP0 software interrupts (fixes the post-logo black screen) | **merged** (PR #63) |
| `[widescreen.cull] vxrange_sites` (3D edge widen) | already in upstream master |
| `[widescreen] stretch_2d` / `stretch_fmv` (16:9 menus/FMV) | PR #70 (open) |
| `[widescreen.cull] bltz_sites` (left-edge cull) | PR #71 (open) |

Until PRs #70/#71 merge, this repo's `psxrecomp` submodule must point at a branch
that contains them. **Once they merge, the submodule pins clean upstream master**
and no fork is needed. The transition-stall QoL question is tracked upstream as
issue #72.

### Phase progress

- [x] 1 — Generation & identity (EXE extraction, game.toml, seeds, DISC.md)
- [x] 2 — Build against submodule framework
- [x] 3 — First boot (LLE BIOS → gameplay; sw-interrupt fix)
- [x] 4 — Gameplay & overlay capture (user-played; captures accumulating)
- [x] 5 — Overlay promotion (N/A — game doesn't stream overlays; `compile_overlays.py` pipeline validated)
- [x] 6 — Config polish (DualShock/hybrid, memcard→`saves/`, vsync, 4:3)
- [x] 7 — Launcher & options UI (built-in RmlUi launcher enabled)
- [ ] 8 — Release packaging

## Launcher

The build uses the framework's built-in **RmlUi launcher** (video / controller /
memory-card / disc-verification / key-rebinding options; settings persist to
`settings.toml` next to the exe). It's enabled via `PSX_LAUNCHER=ON` in the
generated project. Because `psxrecomp build` regenerates that project with the
launcher **off**, re-enable it after any regen:

```sh
tools/enable_launcher.sh        # flips PSX_LAUNCHER on, then: rm build/CMakeCache.txt && sh JackieChanRecomp/build.sh
```

Boot straight into the game (skip the launcher): add `--no-launcher`.

## Layout

| Path | Purpose |
|---|---|
| `psxrecomp/` | Framework submodule (recompiler + runtime), pinned to our fix branch |
| `recomp-ui/` | Launcher/options UI submodule (Phase 7) |
| `game/` | Your legally dumped disc (`.cue`+`.bin`) — never committed |
| `bios/` | Your legally dumped `SCPH1001.BIN` — never committed |
| `JackieChanRecomp/` | Generated recompilation project — never committed |
| `game.toml`, `seeds/` | Committed copies of the generation config/seeds |
| `DISC.md` | Disc identity + verification hashes |
| `ISSUES.md` | Findings log (root causes, fixes, open items) |

## Quickstart (Fedora)

```sh
sudo dnf install cmake ninja-build gcc-c++ pkgconf SDL2-devel git python3
git clone --recurse-submodules <this-repo> JackieChanRecomp
cd JackieChanRecomp
# supply game/…/*.cue+bin and bios/SCPH1001.BIN (md5 924e392ed05558ffdb115408c263dccf)

# 1. build the framework recompiler
cmake -S psxrecomp/recompiler -B psxrecomp/recompiler/build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build psxrecomp/recompiler/build

# 2. recompile the BIOS from your dump
(cd psxrecomp && PSXRECOMP_BIOS_ROM=../bios/SCPH1001.BIN bash tools/regen_bios.sh)

# 3. generate the game project from the disc
./psxrecomp/recompiler/build/psxrecomp build \
  --disc "game/Jackie Chan Stuntmaster (USA)/Jackie Chan Stuntmaster (USA).cue" \
  --bios bios/SCPH1001.BIN --output JackieChanRecomp --name "Jackie Chan Stuntmaster"

# 4. link generated project to the submodule (instead of its bundled copy) and build
rm -rf JackieChanRecomp/psxrecomp JackieChanRecomp/bios-generated
ln -s ../psxrecomp JackieChanRecomp/psxrecomp
ln -s ../psxrecomp/generated JackieChanRecomp/bios-generated
sh JackieChanRecomp/build.sh

# 5. play
cd JackieChanRecomp
./build/Jackie_Chan_Stuntmaster_Recompiled --game game.toml \
  --disc "../game/Jackie Chan Stuntmaster (USA)/Jackie Chan Stuntmaster (USA).cue"
```

Debug build with TCP inspection server (port 4370):
`cmake -S JackieChanRecomp -B JackieChanRecomp/build-dbg -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DPSX_LAUNCHER=OFF`

## Legal

No BIOS, disc images, game assets, or generated game code are committed to this
repository. You must supply your own legally obtained dumps. Upstream framework
license: PolyForm Noncommercial 1.0.0.