# Lumines Live! — native PC recompilation

**The Xbox 360 puzzle classic, recompiled to a native x86-64 executable.** No
emulator, no interpreter, no JIT — the original PowerPC code is statically
recompiled to C++ with the [ReXGlue SDK](https://github.com/rexglue/rexglue-sdk)
**v0.8.0** and linked against its runtime. It boots, it renders, and the blocks
fall to the beat.

![Lumines Live! title screen](images/title_screen.png)

## Status: **playable** 🎮

Boots straight through to in-game Lumines: **splash → title → gameplay**. Blocks
respond to input, the timeline sweep clears them, and the music-synced background
animates. No crashes through extended play.

![In-game Lumines](images/gameplay_active.png)

*Falling blocks, the "next" queue, the timeline sweep bar, and the animated skin —
all running natively. `A → Enter → Start` from the title drops you in.*

## How it got here

The whole pipeline — from a downloaded package to a playable `.exe` — in one sitting:

```
LIVE package ──▶ STFS extract ──▶ XEX triage ──▶ rexglue init + codegen
                (171 files)      (base 0x82000000)   (PowerPC → C++)
      │
      └──▶ cmake build ──▶ boot ──▶ Q splash ──▶ title ──▶ 🎮 gameplay
```

The recompiler and build were minutes of work. The craft was **runtime bring-up** —
getting the recompiled code to actually run:

- **Kernel stubs.** The link failed on `XUsbcam*` (the Vision Camera API — imported
  by ~26% of XBLA titles, never used by most). Stubbed from the toolkit template.
- **Static-init thunks.** First guest-code crash was a table of 26 tiny
  constructor thunks (`0x82361C78..E18`) that discovery had merged into one blob.
  Split them back out.
- **The vtable wall.** Then a whole *class* of crashes — C++ virtual adjustor
  thunks reachable only through vtables, which branch-following discovery can't
  see. `extract_pe.py` couldn't decode this title's LZX variant, so we dumped the
  image the runtime had *already* decompressed (via a one-shot `OnPostLoadXexImage`
  hook reading guest memory), scanned it for vtable clusters, and batch-registered
  **179 functions** in a single codegen pass. That one move took it from
  crash-on-first-thunk to the rendering title screen.

See [PROGRESS.md](PROGRESS.md) for the full blow-by-blow.

## Binary facts

| | |
|---|---|
| Title | Lumines Live! (XBLA, ID `584107F8`) |
| Image base | `0x82000000` (standard XBLA) |
| Image size | `0x8A0000` (8.6 MB) |
| Imports | `xam.xex`, `xboxkrnl.exe` |
| Recompiled functions | ~9,500 |

## Build & run

You **bring your own** copy of the game — the package, extracted assets, and
recompiled C++ are all git-ignored. This repo tracks the project, not the game.
Prereqs: Clang 20+, CMake 3.25+, Ninja, VS2022, and a built ReXGlue SDK v0.8.0.

```bash
# 1. Extract your LIVE package (title 584107F8) with the 360tools kit
python /path/to/360tools/tools/extract_stfs.py <PACKAGE> extracted/
#    flatten if the STFS nested a dir:  mv extracted/extracted/* extracted/

# 2. Regenerate the recompiled C++ (git-ignored, ~58 MB)
cd project && rexglue codegen

# 3. Build
cmake --preset win-amd64-release "-DCMAKE_PREFIX_PATH=<rexglue-sdk>/out/install/win-amd64"
cmake --build out/build/win-amd64-release

# 4. Run
./out/build/win-amd64-release/lumines.exe --game_data_root=../extracted
```

**Controls** (SDL3 keyboard-as-gamepad; polled per frame, so hold briefly rather
than tap): move = arrow keys, rotate = **A**/Space & **B**/Shift, Start = Esc.
From the title screen, **A → Enter → Start** enters gameplay.

## Layout

```
project/
  lumines_manifest.toml   # codegen config + function-entry hints (the bring-up work)
  src/main.cpp            # ReXApp entry point
  src/stubs.cpp           # kernel stubs (XUsbcam*)
  generated/              # codegen output — default/ is git-ignored, regenerable
extracted/                # game data — bring your own (git-ignored)
```

## Credits

Built on the [ReXGlue SDK](https://github.com/rexglue/rexglue-sdk) (recompiler +
runtime, D3D12/Vulkan backends derived from [Xenia](https://github.com/xenia-project/xenia))
and the [360tools](https://github.com/sp00nznet/360tools) toolkit. Lumines Live! and
all game assets are © Q Entertainment / the respective rights holders — this project
contains **none** of them; the screenshots are captured from the running port for
documentation. Every game recompiled is a game preserved.

## License

This project's own code (the ReXApp entry, stubs, manifest, and scripts) is
[MIT](LICENSE). It does **not** cover the game (bring your own) or the ReXGlue SDK
and its dependencies, which carry their own licenses.