# Rayman 2: The Great Escape — static recompilation

A native build of the Dreamcast release (USA, `17707N`), produced by
[dream-recomp](https://github.com/phobos665/dream-recomp) lifting the game's SH-4 code to C++
ahead of time. The tool is a submodule, pinned to a SHA.

**No disc data is in this repository, and none ever will be.** Everything here is configuration
written by reading a disc you supply, plus notes. See `.gitignore`.

## Status

Boots and runs. 898 frames in 15 seconds with no fault, no untranslated call targets and no
unmapped accesses. Nothing has been checked beyond "it does not crash" — the title has never been
looked at for correctness past the fault that used to stop it.

That fault, at frame 19, was in the tool rather than here: a game's stack was being started where
the BIOS leaves it before the disc bootstrap runs, rather than where the bootstrap leaves it, and
Rayman 2 keeps a memory-region descriptor in exactly those bytes at the top of RAM. Fixed in
`dream-recomp/docs/boot-state.md`; nothing in `game/rayman2.toml` changed for it.

## Setting up

You need your own dump of the disc as a CHD.

```
git clone --recurse-submodules <this repo>
cd Raymanian-2-recomp
mkdir -p game/disc && cp /path/to/your/dump.chd game/disc/rayman2.chd

PYTHONPATH=dream-recomp/tools/dcdisc python3 -m dcdisc extract game/disc/rayman2.chd game/extracted
```

The extraction writes `game/extracted/`, which is gitignored. Without it the build produces no
game target at all — `dream_add_game` returns quietly when the extracted binary is absent, so a
checkout with no disc still configures and builds the tool.

## Building and running

```
cmake -S . -B build -DDREAM_DEV_INTERPRETER=ON
cmake --build build --target rayman2_boot -j
./build/game/rayman2_boot --config game/rayman2.toml --no-audio --rtc-seed 1 --max-seconds 20
```

`--rtc-seed` is not optional for anything you intend to compare against another run: without a
pinned console clock two runs diverge within about 24 frames. The frame-19 fault in particular
only reproduces with `--rtc-seed 1`.

Add `--interpret` to run everything through the development interpreter instead of the translated
code. It is much slower and is the reference the translated build is checked against — with the
caveat recorded in `dream-recomp/docs/crazytaxi-divergence.md` that the two paths can legitimately
differ where overlays or the HLE are involved.

## What is actually game-specific here

`game/rayman2.toml`, and within it four `[[relocations]]` entries: the SH-4 exception vectors,
which the startup code copies into RAM and runs from there, so the translator has to be told to
lift those bytes as if they lived at the address they run from. They were found by
`--suggest-config`.

Everything else in that file is either identity read off the disc or the standard Katana layout
that every title shares. `[functions].extra` is empty: discovery reaches this title without help.

## Layout

```
dream-recomp/     the tool, a submodule pinned to a SHA
game/
  rayman2.toml    the configuration: identity, layout, relocations
  CMakeLists.txt  one line, dream_add_game
  disc/           your dump goes here (gitignored)
  extracted/      written by dcdisc extract (gitignored)
docs/progress.md  what has been established, what was retracted, what is next
```