# futari_recomp

Static recompilation of **Mushihimesama Futari** (Xbox 360, 2006/2012) for native
PC execution, built on the [ReXGlue SDK](https://github.com/rexglue/rexglue-sdk).

> **No game data here.** No game executable, no `media/`, no audio, no artwork
> off the disc — you supply all of it yourself, from a copy you own; see
> [Game data](#game-data) and [docs/DUMPING.md](docs/DUMPING.md). The two
> exceptions are named in [NOTICE.md](NOTICE.md): a title screenshot and the
> application icon, both game-derived and both kept for identification only.

> ⚠️ **Built with heavy use of AI.** Code, tooling, and docs in this repo were
> written largely with LLM assistance. Hobby project — verify before relying on
> it, expect rough edges, no warranty.

![Mushihimesama Futari title screen](screenshots/title.png)

**Latest release:** v1.5.2 (Windows, macOS, Steam Deck). See
[CHANGELOG.md](CHANGELOG.md). Per-OS build and packaging details:
[PORTS.md](PORTS.md). Prebuilt bundles are not published here, so the path below
is to build it yourself.

**Status:** title, menus, audio, controller, and saves work, and all 8 game modes
load, run, and mode-switch cleanly. Deeper gameplay can still hit rare recompiler
edge cases — see [Known issues](#known-issues).

## How it works

The Xbox 360 PowerPC code is translated ahead-of-time to C++ and linked against
the ReXGlue runtime (a Xenia-derived layer providing the kernel, a D3D12/Vulkan
GPU, XMA audio, input, and a virtual filesystem). `default.xex` is the shell and
menu; each of the 8 game modes is a separate module XEX, recompiled into its own
DLL and loaded on demand.

Almost none of that C++ is in this repo — it's generated into `generated/` by
`scripts/regen.sh` from your own game dump, and gitignored. What's tracked here is
the host app (`src/main.cpp`), the codegen inputs (`*.toml`), and the build.

## Game data

You supply the game yourself, from a copy you own. Two pieces:

**`assets/` — the disc (required).** The extractor takes either a **Ver 1.5**
disc ISO or the install folder copied straight off your console's storage
(hash-verified, no conversion tools needed — see DUMPING.md):

```sh
python scripts/extract_iso.py "Mushihimesama Futari Ver 1.5.iso" --out assets/
# or, from a console disc install (also installs your DLC into dlc/):
python scripts/extract_iso.py "path/to/435A07D7" --out assets/ --dlc-out dlc/
```

On Windows you can drag the `.iso` — or that console folder — onto
[`extract_assets.bat`](extract_assets.bat) instead. You should end up with
`assets/default.xex` and an `assets/media/` tree containing the 8 module XEXs.
The game reads `assets/` next to the exe; `--game_data_root <path>` points
elsewhere.

**`dlc/` — the marketplace DLC (optional).** The extractor installs these
automatically when it finds them next to a console install; or drop the Xbox 360
STFS packages into a `dlc/` folder next to the exe yourself, filenames unchanged.
They install themselves on first launch
(`DLC: InstallContent(...) -> 0x00000000` in the log). No `dlc/` folder just
means no extra content — the game runs fine without it.

📖 **[docs/DUMPING.md](docs/DUMPING.md)** walks through getting both off your own
console, and lists checksums to verify the result.

## Build

Needs CMake 3.25+, Ninja, **LLVM/clang-cl** 20+ (at `C:\Program Files\LLVM`),
**Visual Studio 2022 Build Tools** with the Desktop C++ workload (clang-cl targets
the MSVC ABI, so it needs those headers and libs — plus `rc.exe` from the bundled
Windows SDK), Python 3.8+, and git + bash.

The SDK at `thirdparty/rexglue-sdk` is **vendored** — this port owns and
maintains its own copy, taken from a fork of the
[upstream SDK](https://github.com/rexglue/rexglue-sdk) at v0.9.3.1 and carrying
the clang-cl and macOS fixes this port needs; see
[thirdparty/rexglue-sdk/VENDORED.md](thirdparty/rexglue-sdk/VENDORED.md) and
[PORTS.md](PORTS.md#sdk). Only the SDK's third-party dependencies are git
submodules, all pointing at their public upstreams.

```sh
# 1. Clone with the SDK's third-party submodules (~1 GB of dependency history;
#    do NOT add --shallow-submodules — several pins are not branch tips, and a
#    shallow clone silently leaves those submodules on the wrong commit).
#    The -c options go BEFORE `clone` so they reach the submodule clones too —
#    `git clone -c ...` only configures the parent repo.
git -c core.symlinks=true -c core.longpaths=true clone --recurse-submodules https://github.com/springah/futari_recomp
cd futari_recomp

# 2. Build the ReXGlue CLI
cmake -S thirdparty/rexglue-sdk -B thirdparty/rexglue-sdk/build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_C_COMPILER="C:/Program Files/LLVM/bin/clang-cl.exe" \
  -DCMAKE_CXX_COMPILER="C:/Program Files/LLVM/bin/clang-cl.exe"
cmake --build thirdparty/rexglue-sdk/build --target rexglue

# 3. Provide the game data — see "Game data" above (assets/, and dlc/ if you have it)
python scripts/extract_iso.py "Mushihimesama Futari Ver 1.5.iso" --out assets/

# 4. Generate the recompiled C++ into generated/
bash scripts/regen.sh

# 5. Configure
cmake -S . -B out/build/win-amd64 -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_C_COMPILER="C:/Program Files/LLVM/bin/clang-cl.exe" \
  -DCMAKE_CXX_COMPILER="C:/Program Files/LLVM/bin/clang-cl.exe" \
  -DCMAKE_RC_COMPILER="C:/Program Files (x86)/Windows Kits/10/bin/<sdk-ver>/x64/rc.exe"

# 6. Build everything — the exe plus all 8 module DLLs
cmake --build out/build/win-amd64

# 7. Run (GUI app; logs to logs/futari_NNN.log next to the exe)
out/build/win-amd64/futari.exe --game_data_root assets
```

<details>
<summary><b>Gotchas worth knowing before you hit them</b></summary>

- **clang-cl, not clang++.** This builds against the MSVC ABI. The CMake presets
  default to `clang++`, which is why the configure line above is explicit — and why
  Windows releases don't come from a preset.
- **`git -c core.symlinks=true` (before `clone`) matters.** The SDK's libmspack submodule uses
  git symlinks. Without it (plus Developer Mode), those files check out as text
  stubs and the SDK build fails with `lzxd.c(1,1): error: expected identifier`. Fix
  an affected checkout with `git -C <submodule> config core.symlinks true`, then
  re-checkout the files.
- **Don't pass `-DCMAKE_CXX_FLAGS=...`.** It clobbers CMake's default `/EHsc` and
  breaks exception handling in dependencies. The SSE baseline and `char8_t` flags
  are set inside the SDK's own CMake.
- **Build with no `--target`.** Naming only `futari` skips the 8 module DLLs, which
  then keep whatever flags they were last built with.
- **Codegen runs per-module in isolation.** All 8 modes load at `0x88000000`, and
  the SDK analyzer corrupts cross-module analysis if they share one manifest.
  `regen.sh` already handles this; don't collapse it into a single codegen pass.
- **The SDK is vendored, not pinned.** Builds use the `thirdparty/rexglue-sdk`
  tree in this repo. Pass `-DREXSDK_DIR=<path>` to build against a separate
  checkout instead.
- **`generated/` must exist before you configure.** `CMakeLists.txt` includes
  `generated/rexglue.cmake`, which step 4 produces. Configuring a fresh clone
  without running `scripts/regen.sh` first fails immediately, by design.

</details>

## Layout

```
assets/                 # gitignored — your extracted game files
generated/              # gitignored — codegen output (scripts/regen.sh)
futari_manifest.toml    # entrypoint + the 8 game-mode modules
futari_functions.toml   # function-entry hints for the shell
src/main.cpp            # host app: ReXApp subclass + futari.ini config
scripts/                # extract_iso.py, analyse_xex.py, regen.sh
dist/RUN.txt            # the readme that ships inside release zips
thirdparty/rexglue-sdk/ # the SDK, vendored (VENDORED.md); its deps are submodules
```

## Known issues

None currently known. Two earlier ones, for the record:

- **The shell's one inexpressible branch (fixed).** Codegen used to split the
  block at `0x82081778` into its own function, though it is really an interior
  continuation of `sub_82081658` — register restores that rejoin the parent's
  loop at `0x820816EC`, a branch that cannot be expressed from a separate
  function, so it compiled to the shell's only `REX_FATAL`. The split turned
  out to be a pointer-scan false positive: the only "pointer" to that address
  in the whole image is a `lwz r16,0x1778(r8)` instruction, whose encoding
  happens to equal `0x82081778`. The address is now declared a chunk of its
  parent in `futari_functions.toml` (the SDK's function config `parent` field,
  whose semantics were completed for this), no standalone function or dispatch
  entry is emitted, and the fatal is gone.
- Historically, entering a game mode host-crashed via under-sized jump tables.
  Fixed in the SDK: index-register copy tracing, manual `[[switch_tables]]`
  support, and out-of-range cases now fall back to faithful indirect dispatch
  rather than `__builtin_trap()`.

## Credits

- [ReXGlue SDK](https://github.com/rexglue/rexglue-sdk) — Xbox 360 runtime + recompiler (Xenia-derived)
- [XenonRecomp](https://github.com/hedge-dev/XenonRecomp) — reference PPC → C++ recompiler
- [Xenia](https://github.com/xenia-project) — the emulator ReXGlue's runtime is rooted in
- [UnleashedRecomp](https://github.com/hedge-dev/UnleashedRecomp) — recomp reference project

Also worth a look: [SDOJ-Recomp](https://github.com/eandis/SDOJ-Recomp) — a recomp
of another CAVE Xbox 360 shooter, DoDonPachi SaiDaiOuJou.

## Legal

Mushihimesama Futari, and all of its code, data, audio, and artwork, are the
property of Cave Interactive Co., Ltd. This project is not affiliated with,
endorsed by, or connected to Cave in any way.

Nothing here is a substitute for owning the game:

- **No game data is distributed.** No disc image, no game executable, no
  `media/`, no audio, no artwork off the disc — not here and not in the release
  bundles. The port is inert without a dump you provide. The only game-derived
  files in this repository are the title screenshot and the application icon,
  both for identification; see [NOTICE.md](NOTICE.md).
- **The recompiled C++ is produced on your machine, from your own disc.** It is
  a translation of Cave's executable code, so it belongs to you no more than the
  disc does. Don't redistribute it. The release bundles necessarily contain it,
  compiled — which is why they go only to people who already own the game, and
  are not published here.
- **Do not ask for game files.** Requests for dumps, links, or "where do I get
  the ISO" will be closed. [docs/DUMPING.md](docs/DUMPING.md) covers the only
  supported route: your own disc, read with your own console.

## Licence

The contents of this repository — the host app, the tooling, the codegen inputs,
the build files, and the docs — are under the
[BSD 3-Clause licence](LICENSE), matching the SDK's own licence and the Xenia
lineage behind it. That licence covers **this repository only**; it grants no
rights whatsoever to the game, or to the recompiled code generated from it.
[NOTICE.md](NOTICE.md) spells out exactly what is and is not covered.

Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).