# MegaManX2SNESRecomp

Static recompilation of **Mega Man X2 (USA)** built on
[snesrecomp](https://github.com/mstan/snesrecomp), sharing the
[recomp-ui](https://github.com/mstan/recomp-ui) pre-boot launcher with the
other SNES recomp ports.

You must supply your own legally-obtained ROM. Nothing ROM-derived is
committed here.

## ROM identity

| | |
|---|---|
| file | `mmx2.sfc` at the repo root |
| size | 1,572,864 bytes (12 Mbit LoROM) |
| CRC32 | `0x947B0355` |
| SHA-256 | `f3246755f608a1e1dc9c848b61da3b824c7853b29b3be40df6fc7f2793a887ed` |

A 512-byte SMC copier header is stripped automatically by both the recompiler
and the launcher, so headered dumps verify against the same digest.

## Status

**Bring-up skeleton — boots through the interpreter tier.** The host layer,
identity glue and `recomp/bank00.cfg` LLE-first seed are in place; the title
boots and runs entirely on the LLE interpreter with the instruction-level Cx4
core confirmed live (`firmware=1`, offrails=0 at first boot). AOT coverage
from `recomp/*.cfg` + profile manifests is the next milestone — the
interpreter stays the failsafe until targets are proven.

Execution is **LLE-first**, exactly as in the sibling X3 port:

* `src/x2_rtl.c` boots the real RESET vector through the interpreter bridge,
  injects NMI only once the game arms NMITIMEN, delivers IRQs only when `P.I`
  is clear, and caps each host frame at one NTSC frame of master clocks. AOT
  coverage from `recomp/*.cfg` is layered on later as an optimization.
* `recomp/bank00.cfg` is the generic seed (`auto_vectors` +
  `tier_down_stubs`). Profile-manifest roots and interpreter-only boundaries
  (`force_lle`) get added as boot findings demand them.

**Do not assume X3 findings hold here.** This tree is a fresh skeleton: WRAM
layouts, NMI/IRQ driver addresses, HUD OAM slots, level-streamer tables, and
Cx4 command sites must each be re-derived against the X2 ROM during bring-up.

### Cx4 — no firmware dump required

Mega Man X2 carries Capcom's **Cx4** (Hitachi HG51B S169 DSP), the same chip
family as X3. The engine emulates it at the **instruction level**
(`snesrecomp/runner/src/snes/cx4.c`, from ares, ISC), auto-detected from the
LoROM internal header (`coprocessor == 0xF`, ex-coprocessor == 0x10). Because
the core is instruction-exact, pointer/loop changes in the game's Cx4
program (executed out of cartridge ROM) cannot drift from real hardware
timing.

The chip's internal 1024-entry data ROM is synthesized from six closed-form
mathematical tables and has been verified bit-exact against a real dump. No
firmware file is needed. An optional 3072-byte `cx4.rom`, supplied beside the
executable or through `$SNESRECOMP_CX4_ROM`, only cross-checks the synthesis.

### Widescreen — intentionally absent for now

The X3 widescreen implementation was carried into this tree as **inert,
compiled-out-by-default plumbing**: the frame gate in `RunOneFrameOfGame`
keeps the X3-derived ROM-signature patching dormant until widescreen is
actually active, the WRAM anchor tables are marked X3-surveyed, and no
widescreen package is preloaded. Everything in `src/mods/` must be
re-derived against the X2 ROM before the feature can ship. `main.c` documents
this caveat at the identity layer.

## Debugging

The trace build carries a TCP debug server on port **4385** plus the
always-on observability rings. Probes QUERY the rings; they never arm a
recorder and then run a workload.

```bash
python tools/dbgprobe.py ppu        # live PPU state
python tools/dbgprobe.py offrails   # out-of-range cart access ring
python tools/dbgprobe.py shot x.bmp # screenshot through the debug surface
```

`tools/dbgprobe.py` uses port 4385 for this title.

## Build

```bash
bash tools/bootstrap.sh              # verify the junctioned/submodule layout
cp /path/to/your/dump mmx2.sfc
bash tools/regen.sh --no-tests      # emit src/gen/*.c + recomp/funcs.h
cmake -S . -B build -G Ninja -DSNESRECOMP_ENABLE_TRACE=ON
cmake --build build
```

`-DSNESRECOMP_ENABLE_TRACE=ON` builds the TCP debug server and the always-on
observability rings — the bring-up configuration. Omit it for a release build.