Digimon Story: Sunburst (Japan) (Rev 1) - native PC port, 0.1.0
=====================================================================

This folder contains a static recompilation of the retail Nintendo DS game:
a native Windows program, not an emulator. It ships no game data at all - no
ROM, no BIOS dump, no firmware image, no save. You supply your own cartridge
dump, and the program refuses any dump that is not the one described below.

1. WHAT YOU MUST SUPPLY

  Your own dump of the Japanese retail cartridge:

      file     Digimon Story - Sunburst (Japan) (Rev 1).nds
      size     67,108,864 bytes
      SHA-1    2fa1c272974fdef6b8f2acc3f9f778dd4111a587
      SHA-256  a92788836ddf4fbe00e3f9db7a14ea1f5dc3361cdc4cec088a19a8634838e0fb

  Any other dump is refused before anything is built. If you rip your own
  cartridge, the SHA-1 above is what a known-good Rev 1 image hashes to;
  a trimmed, patched or badly dumped image will not match.

  Optional, and only that: ARM9 + ARM7 BIOS dumps (biosnds9.rom, 4096 bytes,
  and biosnds7.rom, 16384 bytes). They are not required. With no dumps in
  bios\, play.bat sets NDS_FREEBIOS=on and the runner boots from FreeBIOS, a
  free reimplementation it embeds; a real run logs

      [bios] FREEBIOS (opt-in, no dumps): arm9 4096 bytes SHA-1 b85d6afd...
      [firmware] GENERATED image (opt-in, no dump), 131072 bytes

  and reaches the health-and-safety screen. Drop the two files in bios\ only
  if you want the retail BIOS path. Rebuilding this port from source does not
  need them either: with no dumps present the build emits the FreeBIOS banks
  alone and the runner links without the retail ones.

2. FIRST RUN

  Double-click play.bat.

  a. It hashes your dump and compares it with the SHA-1 above before touching
     anything. A mismatch stops there, naming what it expected.
  b. It copies the dump into rom\ (the only copy it keeps).
  c. This release carries runtime\nds_runner.exe, so that binary is installed
     and the first run is finished in seconds - nothing is compiled. It is a
     build of the sources in this folder for exactly this cartridge, so it is
     bound to the SHA-1 above. play.bat marks the folder with game\.build-id
     and only re-runs setup when that stops matching game\.ship-id, which is
     what an update changes.
  d. Without a prebuilt runtime (a sources-only release), setup_kit.py fetches
     the compiler kit into kit\ (clang, CMake, Ninja, SDL3) with a progress
     bar, about 240 MiB, and then compiles the recompiler and the game into
     game\generated\. That is a full C build of the cartridge: tens of
     minutes, not seconds. game\build.log gets a "=== phase ===" block per
     step as it goes.
  e. It starts the game.

  You need the cartridge dump and nothing else: no BIOS dump, no firmware
  image, no toolchain. Every launch after the first is about a second, because
  play.bat compares those two build ids and skips straight to the game. It
  re-runs setup on its own when an update changes the shipped id, so you can
  simply unzip a new release over this folder.

3. WINDOWS MAY BLOCK THE FIRST LAUNCH

  Windows SmartScreen shows "Windows protected your PC" for any unsigned
  program it has not seen before. Click More info, then Run anyway. Windows
  remembers the choice for this version of play.bat.

  Unzip into a folder you can write to - Documents\Sunburst, or anywhere on
  D: - and not into Program Files. Nothing here needs administrator rights,
  and nothing is installed outside this folder.

4. WHERE THINGS LIVE

  rom\                 your cartridge dump (copied here on first run)
  bios\                optional BIOS dumps; also holds the per-install MAC
  saves\sunburst.sav   your in-game save
  savestates\          F1-F12 savestate slots
  settings.ini         display, graphics, audio, mouse and fast-forward settings
  game\build.log       the build log; read this if setup fails
  game\mods\          translation patches (see docs\MODS.md)
  kit\                 the downloaded toolchain cache
  runtime\             the runner executable and its DLLs
  game\, framework\    sources; the game is compiled from these

  Playing also writes runner diagnostics into logs\: hostprof-*.ndshp and
  performance-*.jsonl per session, a few megabytes, plus a coverage manifest
  in saves\. Those are normal, they never land next to your ROM, and they are
  safe to delete.

  settings.ini is next to this file and it is where your settings live. The
  Esc menu writes it, and it is read again on the next launch, so volume,
  window scale, filter, internal resolution, fullscreen, pause-in-menu,
  Color mode and LCD grid all survive a restart. Color mode starts at
  Original and LCD grid starts at off, so out of the box the picture is
  exactly what it was before those two rows existed; they only change when
  you change them. Two things are still launch-time only: the screen layout
  and the view mode. Pass those on the command line (see section 5) - the
  menu does not change them for you.

  Deleting rom\, saves\ or settings.ini is how you start over. Deleting
  kit\ forces the toolchain download again. Unzipping an update over this
  folder keeps your ROM, your save, your savestates and the kit - but it does
  replace settings.ini with the default seed, so copy that file aside first if
  you have tuned it.

5. CONTROLS

  arrows d-pad    Z B    X A    A Y    S X    Q L    W R
  Enter Start     Backspace Select    mouse = stylus
  F1-F12 savestate slots    Esc opens/closes the settings menu
  hold Left Shift = fast forward

  The fast-forward speed is the settings menu's System -> Fast forward row
  (default 2x; 0 turns the key off). It raises the audio pitch while held,
  which is the same trade every DS emulator makes.

  The picture effects are menu rows too, not keys: Settings -> Graphics holds
  Color mode (Original / Light / Moderate / Strong) and LCD grid. Both start
  neutral, so nothing is applied until you pick something.

  Extra runner flags are passed straight through, e.g.
      play.bat --screen-layout single --supersampling 2

6. IF IT DOES NOT WORK

  game\build.log   every phase writes here; the failing phase is the last
                   "=== " block, and the last 40 lines are the reason.
  ROM refusal      your dump does not match the SHA-1 above.
  SmartScreen      More info -> Run anyway (section 3).
  No disk space    the kit plus the build needs about 6 GiB free.
  Still stuck      delete game\generated\ and game\.build-id, then run
                   play.bat again to rebuild from scratch.

No ROM, BIOS, firmware image, save, savestate or generated game code is
included in this release, and none of it is redistributed by us. Your dump
stays on your machine and is transformed into native code there.
