CPS+ — arranged CD-era soundtracks for CPS1/CPS2 arcade games on MiSTer
=======================================================================

Version:     1.3b
Hardware:    MiSTer FPGA — CPS-1.0, CPS-1.5 and CPS-2 cores
Project by:  Steve Gordon (https://x.com/strygo)
Website:     https://strygo.github.io/arcade-patches/cps-plus/

CPS+ adds the arranged (CD-quality) soundtracks Capcom recorded for its
console releases to the original arcade games, running on real FPGA
recreations of the arcade hardware.  The game's own sound engine stays
live — the core passively watches the sound commands the game issues and
streams the matching arranged track, while sound effects keep playing
through the original QSound/OKI hardware path.  No game code is modified.

  core source:   https://github.com/strygo/jtcores/tree/cpsplus   (GPL-3.0)

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

  builder/           the pack generator (Python), the per-game trigger maps,
                     the three CPS+ cores, the MRA definitions, the X68000
                     render tools and the PlayStation sound-test recorder
                     (builder/tools/, see X68000.md and PSX.md)
  out/mister/        built by the generator, laid out like your SD card.
                     This is the only folder you copy across.

You supply, as with any MiSTer arcade setup:
  * the arcade ROM zips (MAME naming) in games/mame/ or games/hbmame/
  * disc rips of the Capcom releases that carry each arranged soundtrack
    (see builder/discs.toml for the exact list per pack)
  * for the three X68000 MIDI packs: the games' X68000 disk images and
    your SC-55 ROM set -- the soundtrack is rendered on your machine
    (builder/X68000.md explains what that involves)
  * for the Double Impact and HD Remix packs: the albums themselves, both
    free official downloads -- Capcom's Final Fight: Double Impact remixed
    soundtrack (http://www.finalfightgame.com/remix) and OC ReMix's SSF2T
    HD Remix soundtrack (https://ocremix.org/album/12); discs.toml has the
    direct links
  * for the Strider (PSX Soundtrack) pack: your Strider (USA) PlayStation
    disc, MAME, and MAME's PlayStation ROM sets -- the kit records the
    game's own sound test (builder/PSX.md explains what that involves)

QUICK START
-----------
  1. Edit builder/discs.toml — point it at the disc rips you own.
     Windows paths can be pasted as they are (C:\Rips\...).
     Or skip the file and pass discs on the command line:
       python3 builder/make_packs.py --disc mtwins_pce_disc=/discs/chiki.7z
     Run make_packs.py --list to see every pack and the disc it wants.
  2. python3 builder/make_packs.py
       (needs Python 3.11+, numpy, ffmpeg on PATH; the X68000 packs also
       need git, cmake and a C/C++ compiler, and take up to an hour each
       to render -- see builder/X68000.md; the Strider pack needs MAME and
       takes about five minutes to record -- see builder/PSX.md)
     Each built pack is verified byte-for-byte against the published hash,
     so your build is exactly the authored, hardware-tested pack.
  3. Copy the contents of out/mister/ onto your MiSTer SD card
     (/media/fat/), merging with what's already there.  It holds the
     cores, your packs, and the MRAs those packs can load.  See
     INSTALL.md for details.

IF A PACK DOES NOT VERIFY
-------------------------
The album and CD-audio packs (Final Fight OST, UN Squadron SNES, Mega
Twins, Forgotten Worlds, Muscle Bomber) check your rip before encoding:
one row per track with its length, CRC32 and MATCH / ALIGNED / DIFFERENT /
MISSING.  ALIGNED means the exact audio was found in your rip but not
where the track list put it (another read offset, other gap handling,
other numbering) and was re-cut from where it is -- that still builds the
published pack.  DIFFERENT and MISSING rows say what the difference points
at; a pack with such a track is not built.  To see the table without
building anything:
       python3 builder/make_packs.py --check-inputs
If a pack's inputs match but its hash still differs, the message names the
first stage that did (loop/fade processing or ffmpeg's ADX encoder), and
builder/work/packs/<pack>.audit.json has the per-track record -- include it
if you report the problem.

FIVE SPECIAL SETS: GOLD, GRAND MASTER CHALLENGE, SSF2 EX, FINAL FIGHT EX
AND 30TH ANNIVERSARY MRAS
------------------------------------------------------------------------
Most MRAs here target the stock arcade ROM sets.  Five groups pair CPS+
audio with sets that are not stock:

  * "Street Fighter Alpha 2 Gold (Arrange)" + the other Gold MRAs load
    the SFA2 Gold 8 MiB sets — reconstructed from your own game data by
    the SFA2 Gold kit:  https://strygo.github.io/arcade-patches/sfa2-gold/

  * "Super Street Fighter II Turbo: Grand Master Challenge (Arrange)" and
    "(HD Remix)" load the English restoration of Japan's Super Turbo
    (ssf2tgmc.zip in games/hbmame/), built by its kit:
    https://strygo.github.io/arcade-patches/ssf2t-gmc/ -- that zip holds
    only the seven changed files, so keep your stock ssf2xj, ssf2t and
    qsound zips in games/mame/; the MRA reads the rest of the set there.

  * "Super Street Fighter II EX: The Ultimate Championship (Arrange)" and
    "(HD Remix)", plus their Japan versions, load SSF2 EX (ssf2tuc.zip or
    ssf2xuc.zip in games/hbmame/), built by its kit:
    https://strygo.github.io/arcade-patches/ssf2-ex/ -- like Grand Master
    Challenge, keep the stock ssf2xj, ssf2t and qsound zips in games/mame/.
    The bonus stages keep the board's own music.

  * "Final Fight EX (Arrange)" loads Final Fight EX, the Sega CD
    cutscene backport set (ffightus01 in games/hbmame/), built by its kit:
    https://strygo.github.io/arcade-patches/final-fight-ex/

  * "Final Fight 30th Anniversary CPS2 Edition (Arrange)" loads the CPS2
    conversion of Final Fight by grego2d and rotwang (ffightae_cps2.zip),
    distributed through the Arcade Offset project for MiSTer:
    https://github.com/Toryalai1/Arcade_Offset  -- its pack is built from
    the same US Final Fight CD as the CPS-1 arrange pack.

Without those sets installed, these specific MRAs will not load; every
other MRA works with stock MAME-naming ROM sets.

MAKING YOUR OWN PACKS
---------------------
Everything you need is in builder/: PACK_FORMAT.md specifies the trigger
contract and the pack binary layout, builder/pack/README.md is the manual
for the build modes, and build_pack.py is the tool (init <game> →
pack.toml → build → embed into an MRA).  Community packs for any QSound
CPS2 title are a first-class goal of the format.

LICENSES
--------
Cores: GPL-3.0 (see builder/cores/SOURCE_AND_LICENSE.txt).  MRAs, trigger
manifests and the builder are configuration/metadata and code from the
CPS+ project.  The X68000 render path fetches and builds two open-source
projects at pinned revisions (ValleyBell's X68000 decoders and the
Nuked-SC55 emulator, each under its own licence in its checkout), and the
Strider pack runs your own installation of MAME; none of their code is
bundled here.  The arranged recordings remain (c) Capcom —
which is why they are never distributed and always built from your own
discs, disks and ROMs.
