BUILD OR UPDATE

Run python apply.py in a terminal (Windows: py -3.13 apply.py).
Choose Build or update, then select your media and available outputs.
Settings are remembered; intact outputs can be reused safely.
Check requirements is optional. Change settings saves without building.
Enter q at any prompt to quit. Run apply.py --help for the existing
command-line options and specialized workflows described below.

NG+ — arranged Neo Geo CD soundtracks for Neo Geo cartridge games on MiSTer
==========================================================================

Version:     1.1
Hardware:    MiSTer FPGA — the NG+ core (included), a build of the Neo Geo core
Project by:  Steve Gordon (https://x.com/strygo)

NG+ plays the arranged soundtracks recorded for the Neo Geo CD releases
under the original cartridge games (MVS/AES), with no load times and nothing
cut.  The game's own program stays in charge: the core watches the sound
commands the game sends and streams the matching CD track, while the sound
hardware keeps playing every sound effect and voice.  No game code is changed.

  core source:   https://github.com/strygo/NeoGeo_MiSTer/tree/ngplus

WHAT'S IN THIS KIT — AND WHAT ISN'T
-----------------------------------
This kit contains no copyrighted material: no ROMs, no audio.

  builder/          the image builder (Python), each title's published data
                    and checksums, and the NG+ core
  out/mister/       built by the builder, laid out like your SD card.  This is
                    the only folder you copy across.

You supply, per title:
  * the cartridge ROM set: a MAME-named zip, a Darksoft set or a .neo file
  * the Neo Geo CD disc rip: its .cue sheet and images, a .zip holding them,
    or a .chd (a CHD also needs chdman, which comes with MAME)
and once: the Neo Geo BIOS set (neogeo.zip).

Titles in this version:
  aof2       Art of Fighting 2  (disc: Ryuuko no Ken 2 ~ Art of Fighting 2 (World) (En,Ja,Es))
  aof3       Art of Fighting 3  (disc: Art of Fighting - Ryuuko no Ken Gaiden ~ The Path of the Warrior - Art of Fighting 3 (World) (En,Ja,Es,Pt))
  breakers   Breakers  (disc: Breakers (Japan) (En,Ja))
  bstars2    Baseball Stars 2  (disc: Baseball Stars 2 (Japan) (En,Ja))
  fatfursp   Fatal Fury Special  (disc: Garou Densetsu Special ~ Fatal Fury Special (World) (En,Ja) (Rev 1))
  fatfury1   Fatal Fury  (disc: Garou Densetsu - Shukumei no Tatakai ~ Fatal Fury - King of Fighters (Japan) (En,Ja))
  fatfury2   Fatal Fury 2  (disc: Garou Densetsu 2 ~ Fatal Fury 2 (Japan) (En,Ja))
  fatfury3   Fatal Fury 3  (disc: Garou Densetsu 3 - Road to the Final Victory ~ Fatal Fury 3 - Road to the Final Victory (World) (En,Ja,Es,Pt) (Rev 1))
  kabukikl   Kabuki Klash  (disc: Far East of Eden - Tengai Makyou Shinden ~ Far East of Eden - Kabuki Klash (Japan) (En,Ja))
  kof94      The King of Fighters '94  (disc: King of Fighters '94, The (World) (En,Ja) (Rev 1))
  kof95      The King of Fighters '95  (disc: King of Fighters '95, The (World) (En,Ja))
  lresort    Last Resort  (disc: Last Resort (Japan) (En,Ja))
  pgoal      Pleasure Goal  (disc: Futsal - 5 on 5 Mini Soccer ~ PleasureGoal - 5 on 5 Mini Soccer (Japan) (En,Ja))
  quizkof    Quiz King of Fighters  (disc: Quiz King of Fighters (Japan))
  rbff1      Real Bout Fatal Fury  (disc: Real Bout Garou Densetsu ~ Real Bout Fatal Fury (World) (En,Ja,Es,Pt))
  samsho     Samurai Shodown  (disc: Samurai Spirits ~ Samurai Shodown (Japan) (En,Ja))
  samsho2    Samurai Shodown II  (disc: Shin Samurai Spirits - Haoumaru Jigokuhen ~ Samurai Shodown II (World) (En,Ja))
  samsho3    Samurai Shodown III  (disc: Samurai Spirits - Zankurou Musouken ~ Samurai Shodown III (World) (En,Ja,Es,Pt))
  savagere   Savage Reign  (disc: Fuuun Mokushiroku - Kakutou Sousei ~ Savage Reign (World) (En,Ja,Es,Pt))
  ssideki    Super Sidekicks  (disc: Super Sidekicks - Tokuten-ou (Japan) (En,Ja))
  ssideki2   Super Sidekicks 2  (disc: Tokuten-ou 2 ~ Super Sidekicks 2 - The World Championship (Japan) (En,Ja,Es))
  ssideki3   Super Sidekicks 3  (disc: Tokuten-ou 3 - Eikou e no Chousen ~ Super Sidekicks 3 - The Next Glory (World) (En,Ja,Fr,Es,It,Pt))
  stakwin    Stakes Winner  (disc: Stakes Winner - GI Kanzen Seiha e no Michi (Japan))
  tophuntr   Top Hunter  (disc: Top Hunter - Roddy & Cathy (World) (En,Ja))
  tpgolf     Top Player's Golf  (disc: Top Player's Golf (Japan) (En,Ja))

QUICK START
-----------
  1. Edit builder/titles.toml and point it at your BIOS set, ROM sets and
     disc rips.  Or pass them on the command line:
       python3 builder/make_ngplus.py --bios neogeo.zip --rom samsho2=samsho2.zip --disc samsho2=ssii.cue
     Run make_ngplus.py --list to see every title and the disc it wants.
  2. python3 builder/make_ngplus.py
       (needs Python 3.11+ and FFmpeg fetched on demand; on Windows that is python.org's
        installer and a release ffmpeg build, run as py builder\make_ngplus.py)
     Every ROM, every disc track and every finished pack is checked against
     its published checksum, so your build is exactly the tested build.
  3. Copy the contents of out/mister/ onto your MiSTer SD card (/media/fat/),
     merging with what's already there.  See INSTALL.md.

Each title then appears in the MiSTer menu under
Arcade > Arcade Patches > Arrangements > NG+, and starts as the US arcade
release (arcade mode, US MVS BIOS).  The core's menu has an Arranged Volume
for the CD music and the usual System Type and BIOS choices (console mode,
UniBIOS).

MEDIA TOOLS UPDATE — 2026-10-24

Use --tools-cache to choose the verified helper cache. For offline builds,
add --tools-bundle cpsplus-tools-v3-offline.zip --offline. Helpers are pinned;
no game inputs are downloaded. Other declared Python packages and
source-specific tools remain required. Game files are unchanged.

PYTHON PACKAGES

When a build needs NumPy or Pillow and it is not already installed, the kit
downloads its pinned prebuilt package from PyPI into your user cache. No pip,
compiler, administrator rights or changes to system Python are needed.
Patch-only builds and --help do not download Python packages.

Automatic package installation is qualified for CPython 3.12 on Apple Silicon
Macs and CPython 3.13 x64 on Windows (including x64 Python on Windows ARM).
Other interpreters can still use manually installed NumPy/Pillow. There is
no automatic source compilation or selection of an unqualified package.

Cache: ~/Library/Caches/ArcadePatches/python on Mac, or
%LOCALAPPDATA%/ArcadePatches/python on Windows. You can choose another location
with --python-cache PATH (or ARCADE_PYTHON_CACHE). --tools-cache PATH places
the Python cache under PATH/python unless --python-cache is also supplied.
You may delete this cache when no installer is running; it is recreated later.

Offline: add --python-wheels PATH --offline. PATH may name the matching
python-wheels-v1-*.zip, a folder of unzipped wheels, or a folder containing
the wheel ZIPs. The existing wheel bundles work without modification.
You can also supply --tools-bundle for the other helpers in the same command.
ARCADE_PYTHON_WHEELS is the equivalent environment variable. A warm cache
works offline without a bundle. --offline prohibits package downloads too.
Every wheel is checked against the kit's hash; cached extracted files are
verified before use. Existing manually installed packages remain supported.

The installer and its Python subprocesses share the cache. Your shell profile,
global site-packages and unrelated Python applications are not changed.
