# Soulsilver.Recomp

An in-development project to statically recompile the US version of Pokémon SoulSilver (`IPGE`, Rev 0) using ndsrecomp.

## Source layout

The runner, recompiler, oracle shim, and comparison tools are maintained in one repository.
ndsrecomp, arm-recomp-core, FreeBIOS, and recomp-ui are included as ordinary tracked files; no submodule initialization is required.
See [docs/SOURCE_IMPORTS.md](docs/SOURCE_IMPORTS.md) for imported revisions and component licenses.

- `ndsrecomp/recompiler/`: C++ recompiler
- `ndsrecomp/runner/`: C/C++ native runtime
- `ndsrecomp/oracle/`: melonDS comparison shim and patches
- `ndsrecomp/external/arm-recomp-core/`: ARM decoding, interpretation, and code generation
- `external/recomp-ui/`: user interface
- `regions/`: region-specific configuration
- `tools/`: PowerShell build scripts and Python comparison tools

## Development environment and build

Run commands below from the repository root in PowerShell. Prepare these dependencies yourself;
the build script does not install packages or download files:

- MSYS2 mingw64 GCC, CMake, and Ninja in `C:\msys64\mingw64\bin` (MSVC and clang-cl are not supported).
- The SDL3 3.4.18 MinGW development package at `deps/SDL3-3.4.18/x86_64-w64-mingw32`,
  or pass its existing root directory with `-Sdl3Dir`. It must contain `lib/cmake/SDL3/SDL3Config.cmake` and `bin/SDL3.dll`.
- An existing toml++ v3.4.0 single header, supplied with `-TomlHeader`.
  The pinned upstream SHA-256 is `6b5172ad4dd6519aec67b919181fa7a38a2234131e5b2afa232dfe444819783e`.
- Python 3 for oracle setup and comparison tools (development uses Python 3.14).

External binaries and retail inputs are excluded. The UI source is already included at
`external/recomp-ui`; the script passes its absolute path to CMake. Licensed FreeBIOS replacement images are included.
Prepare your own retail BIOS dumps at the following paths. Both are needed to generate the four
BIOS/FreeBIOS banks linked by the current runner, even when selecting FreeBIOS at runtime:

| Input | Size | Required SHA-1 |
|---|---:|---|
| `ndsrecomp/bios/biosnds9.rom` | 4,096 bytes | `bfaac75f101c135e32e2aaf541de6b1be4c8c62d` |
| `ndsrecomp/bios/biosnds7.rom` | 16,384 bytes | `24f67bdea115a2c847c8813a262502ee1607b7df` |

```powershell
powershell -ExecutionPolicy Bypass -File tools/build_ndsrecomp.ps1 -TomlHeader C:\local-deps\toml.hpp
```

Replace the example header path with your existing file. The script stops if prerequisites are missing,
configures and builds the recompiler, generates all four banks, then builds the runner and copies SDL3.dll.
Stop a running `nds_runner.exe` before rebuilding. It produces `ndsrecomp/runner/build/nds_runner.exe`.
Use `-SkipBanks` only after generating all four banks; it is not a first-checkout build option.
`-Clean` removes only the two local build directories and is normally unnecessary.
The default `NDS_BOOTSTRAP_FIRMWARE=ON` omits captured firmware-menu banks.
`-FirmwareBanks` requires separately prepared `generated/fw_*` banks matching the upstream pinned firmware;
it is not needed for the direct-boot procedure below. Retail firmware is not required for that procedure.

Direct CMake configuration retains upstream's automatic toml++ download when no staged header or override exists.
For an offline direct CMake build, pass `-DNDSRECOMP_TOMLPP_HEADER=<absolute path to an existing toml.hpp>`
to both recompiler and runner configurations. The PowerShell script checks the local header before invoking CMake.

## Local direct boot and validation scope

Place your own US SoulSilver ROM at `roms/us/soulsilver.nds` (`IPGE`, Rev 0, SHA-1
`f8dc38ea20c17541a43b58c5e6d18c1732c7e582`). No ROM download is provided.
After building, launch from the repository root:

```powershell
$env:PATH = "C:\msys64\mingw64\bin;$env:PATH"
ndsrecomp/runner/build/nds_runner.exe ndsrecomp/bios 0 --rom roms/us/soulsilver.nds --config regions/us/game.toml --freebios --generated-firmware --boot direct --no-save --interactive
```

The runner creates its synthetic firmware locally. Keep retail inputs, generated banks, saves,
identity files, and diagnostics out of commits and distribution.
This base runner has no generated title banks; game code runs through Tier 3.
CPU instruction comparisons reached `fifo9to7=16384` with ARM9 276,920,779 and ARM7 234,187,308
instructions, zero timing drift, and matching cumulative fingerprints. The final 262,144 instructions
per CPU also matched directly. This is not a claim of complete gameplay or unobserved device-state agreement.
Later events and title-bank execution with the current corrections remain unverified;
AOT LDM/POP-to-PC timing remains unresolved. New gameplay runs are not part of source publication checks.

Oracle source pinning, patch setup and build instructions are in [oracle/README.md](ndsrecomp/oracle/README.md).
Use `python ndsrecomp/oracle/setup_melonds.py --check` to verify the prepared source.
Comparison procedures and the current validation scope are recorded in [docs/WORK_PLAN.md](docs/WORK_PLAN.md).
The arm-recomp-core source already includes the STM corrections; no additional patch application is needed.

## Licensing and distribution

Independently authored Soulsilver.Recomp code, configuration, and documentation are licensed under the [MIT License](LICENSE).
Imported sources in `ndsrecomp/` and `external/`, along with third-party assets, retain their own licenses.
The root MIT license does not relicense those components.

Game ROMs, retail BIOS and firmware dumps, game-derived generated code, saves, and instruction dumps are excluded.
Component license notices are retained in their respective directories; see [docs/SOURCE_IMPORTS.md](docs/SOURCE_IMPORTS.md) for their scope.
See [docs/THIRD_PARTY_NOTICES.md](docs/THIRD_PARTY_NOTICES.md) for the license texts, asset credits, and modification notices.
The current runner build also links retail BIOS-derived banks and is not ready for redistribution. See [docs/LICENSE_AUDIT.md](docs/LICENSE_AUDIT.md) for details.