MSH TAG v1 (preview) -- two-on-two tag teams for Marvel Super Heroes (CPS-2)
============================================================================

Marvel Super Heroes (1995), played the way Marvel vs. Capcom plays: two fighters per side,
tags in and out, team supers, double teams. It's a patch for your own ROM: this download
holds no ROM data.

What it does
------------
- Each player picks two fighters. The first pick starts the fight. The button that confirms
  a pick chooses its colors: LP is the game's own, LK, MP, HP, MK and HK are Marvel vs.
  Capcom 2's colors for that fighter.
- HP+HK tags. Your partner flies in with a jump attack while your fighter finishes its
  move and leaves, so a tag can carry a combo (a tag cancel works out of a normal or a
  special that hit or was blocked).
- Two life bars per side, both the size of the game's own, the second one reaching the
  timer. The fighter on the bench has a darker bar, a gray name and its face, darker, under
  its partner's portrait. Part of the damage stays red, and the bench wins it back.
- One gauge per team under the life bars, up to Level 3 (no Level 5 bars):
    HP+HK                          tag
    HP+HK while being hit          Counter Switch: tag out of a combo for 2 levels. With
                                   less, your red life and a tenth of your life pay for it.
    B, DB, D + HP+HK when blocking crossover counter: the partner comes in attacking (1 level)
    LP+MP+HP while blocking        push block: shoves the attacker away (free, as often as
                                   you like, as in Marvel vs. Capcom)
    QCF + MP+MK                    snapback: a lunging hit. If it lands, the opponent's fighter
                                   is knocked off the screen and its partner is forced in
                                   (1 level)
    QCB + HP+HK                    double team: both fighters on screen, one stick drives both.
                                   The gauge greys out and shows an infinity sign, and a TIME
                                   bar runs along the bottom: supers are free until it runs
                                   out (2 levels)
    QCF + HP+HK                    team super: both supers at once (2 levels)
    HP+HK during a super           hyper tag: the partner comes in with its own super
                                   (1 more level)
- The double team sky: during a double team the stage gives way to Marvel vs. Capcom's
  meteor sky, if the installer finds your clean Marvel vs. Capcom ZIP (see "The double team
  sky" below). Without it the stage stays.
- A knocked-out fighter lies down and the partner drops in, untouchable until it lands.
  One round per match; time over compares team totals.
- Against the CPU, every opponent brings a partner, and CPU teams tag too.
- The Infinity Gems, dashes, super jumps and throws work as in the original.

Supported sets (clean and unmodified, the 951024 revision)
----------------------------------------------------------
  msh      Euro 951024 (the MAME parent, and the set Fightcade plays)
  mshu     USA 951024
  msha     Asia 951024
  mshjr1   Japan 951024
  mshud    US 951024 Phoenix Edition
Non-merged, split or merged ZIPs. A split clone ZIP is completed from your clean msh.zip in
the same folder. A merged msh.zip gives a patched msh.
The key file (msh.key, mshu.key, msha.key, mshj.key) is copied from your ZIP, or from next
to it. Fightcade's and MAME's ZIPs have it inside. mshud's phoenix.key is written for you if
it's missing.
Refused: the 951117 revision (mshj, mshh, mshb: different code), files that are already
patched, and anything that isn't the clean dump MAME lists, such as ROM files taken out of
Marvel vs. Capcom Fighting Collection. Every set is checked against the complete MAME
member hashes and at every place the patch touches or relies on. See the testing notes
below for the exact installer and gameplay coverage.

Retail installer correction (September 27, 2026)
------------------------------------------------
An earlier v1 download rejected clean retail sets at $005E38 (life bar tiles).
This download corrects the table reads and compatibility checks; it does not bypass them.
If you saw that exact message, download this installer again and use your clean original
ZIP. ZIP size alone does not identify a set. Nothing in your original ZIP is changed.

How to patch
------------
Windows:      drag your clean ZIP onto msh-tag-v1-preview.cmd
              (or put the ZIP next to the .cmd and double-click the .cmd)
macOS/Linux:  python3 msh_tag_patch.py /path/to/msh.zip
              (a split clone with the parent somewhere else: add --parent /path/to/msh.zip)

It writes <set>_tag_v1.zip and <set>_tag_v1.zip.receipt.json beside your ZIP. Your ZIP is
only read. Then:
  Fightcade  Fightcade plays msh. Back up the msh.zip in Fightcade's ROMs folder
             (Fightcade\emulator\fbneo\ROMs), then put msh_tag_v1.zip there renamed to
             msh.zip. For an online match both players need the same patched file, so each
             of you runs the installer on a clean msh.zip (both with mvsc.zip, or both
             without).
  MAME       Copy <set>_tag_v1.zip into a folder of its own and rename the copy to <set>.zip
             (for example msh.zip). MAME's menu refuses patched sets ("the required ROM images
             are missing or incorrect"). Start it from a command prompt instead:
                 mame msh -rompath "C:\path\to\that\folder"
             It lists the changed ROMs as wrong checksums and runs. That folder also needs
             qsound_hle.zip. On Windows, PLAY MSH TAG MAME.cmd does all of this: put it in
             your MAME folder with <set>_tag_v1.zip and double-click it.
  FBNeo      Keep a patched clone (mshu, msha, mshjr1, mshud) away from a clean msh.zip:
             FBNeo would load the parent's clean msh.06b and the game would not start. MAME
             uses the clone's own copy either way.
  RetroArch  The MSH TAG RetroArch core loads it from any folder. The stock FinalBurn Neo
             core needs it in system/fbneo/patched/ with "Allow patched romsets" on.

The double team sky
-------------------
Nothing from Marvel vs. Capcom is in this download: the installer reads the sky from your own
clean Marvel vs. Capcom ZIP (mvsc.zip, the MAME parent) and puts it into the patched file.
To get it:
  Windows:      put mvsc.zip next to your MSH ZIP, or drag both ZIPs onto the .cmd together
  macOS/Linux:  put mvsc.zip next to your MSH ZIP, or add --mvc /path/to/mvsc.zip
A clone ZIP (mvscu.zip, say) works too when you drop it with your MSH ZIP or give it with
--mvc (a split clone needs mvsc.zip in its folder). The installer says at the end whether
the sky is in. Without mvsc.zip (or with --no-sky) the stage stays. For an
online match both players need the same file: both with the sky, or both without.

Four players
------------
The four-player package (msh-tag-v1-4p-preview) makes msh4p.zip for the MSH TAG RetroArch
core: four controllers on one machine, or online with Parsec or RetroArch netplay. On
Windows, the MSH TAG RetroArch download does it all; see its README.

What's in this package
----------------------
  msh-tag-v1-preview.cmd      Windows installer (runs its own PowerShell part)
  msh_tag_patch.py            the same patch for macOS, Linux and Windows (Python 3.8+)
  msh_tag_v1.spec.json        the patch itself: clean-member hashes, the check hashes, the
                              replacement bytes and offsets for each set
  PLAY MSH TAG MAME.cmd     starts the patched game from your MAME folder
No ROM data is included. The replacement bytes are MSH TAG's own code (23 KB in the free
end of msh.06b) and the jumps into it, encrypted for each set's key where the set needs it.
The sky's graphics and colors come from your Marvel vs. Capcom ZIP when you install.

RETAIL COMPATIBILITY CORRECTION -- September 27, 2026
----------------------------------------------------
- Actual clean msh, mshu, msha, mshjr1 and mshud sets pass complete MAME member
  identity checks and both the two-player and four-player installers (10 cases).
- Python and the exact Windows installer's PowerShell body, run under PowerShell 7
  on macOS, produce identical members, including the matching key, in all 10 cases.
- Every replacement hook is checked in its correct DATA or decrypted opcode view.
  Changing a dependency byte is still refused (380 controls). Wrong-only keys,
  modified programs and unsupported revisions are refused without writing output
  in Python and PowerShell. Original clean ZIP hashes remain unchanged.
- A fresh macOS build of the published MSH TAG core booted actual Euro msh and
  Phoenix mshud outputs in both modes. Ordinary inputs selected two heroes per side
  and tagged out and back on both teams. Four-player return tags used ports 3 and 4.
  All five copied DATA tables matched the clean ROM at fight start and after tags.
- This is bounded compatibility/HUD/tag coverage. The old v1 feature videos and
  broader Phoenix feature tests predate this correction; they are not a complete
  new retail gameplay test matrix.
- Still unverified: Windows PowerShell 5.1/cmd.exe/drag-and-drop, the Windows core on
  Windows, the RetroArch UI, Fightcade online play, four physical controllers,
  real hardware, and native gameplay of USA/Asia/Japan retail builds.

Thanks
------
To the testers on Discord whose notes on MvC1, XCOTA TAG and SSF2T TAG shaped this one:
blockable incoming partners, color select, four players, installers that explain
themselves.
