XCOTA TAG v4 (preview) -- 2v2 tag teams for X-Men: Children of the Atom (CPS-2)
==============================================================================

New in v4
---------
- Six colours: the button that confirms a pick picks the colours, as in the MvC1 six-colour
  patch. LP is the game's own colours; LK, MP, HP, MK and HK are Marvel vs. Capcom 2's LK,
  HP, A1, HK and A2 colours for that X-Man. Each partner keeps the colours it was picked
  with, and the HUD portraits wear them too. When the same X-Man in the same colours would
  meet on screen, the second one moves to the next colour (the old mirror rule).
- COMBO BREAKER: while you're being hit, press toward or back + HP or HK (the throw input)
  to break the combo for one bar of X-Power. Both fighters are pushed apart like a throw
  tech, you get a moment of invincibility, and COMBO BREAKER crosses the screen. It only
  works while your side has one X-Man on screen: no breaker during your own Cross Over
  Fever or team super.
- Tag cancels: a normal or special that hits or is blocked can cancel into the tag
  (HP+HK). A whiff can't, and an X-Power can't.
- Full-screen tags: the incoming partner flies across the screen and its kick comes out
  as it reaches the opponent, wherever the opponent stands.
- The same X-Man twice: double Wolverine is fine. Pick them with two different buttons; if
  both wear the same colours, the second one takes the next ones.
- Stage breaks: on Mutant Hunting and Mojo World a partner in play falls with the floor.
  It no longer gets stuck in the ceiling, and Spiral no longer vanishes on Mutant Hunting.
- Cross Over Fever sky: the scrolling X's are back, with calm colours that change slowly
  (no strobe, no white or black flashes) and a platform under the fighters' feet.
- HUD: the partner's bar is darker gold, as in Marvel vs. Capcom. While a benched partner
  heals, its red pulses and green pluses rise over its portrait. POW sits with the X-Power
  gauges.

What it does
------------
- Each player picks two X-Men on the select screen. The first pick starts the fight.
- HP+HK tags, Marvel vs. Capcom style: your fighter leaps off your side of the screen,
  and your partner flies in with a flying kick (a real attack) and says a line on landing.
- At Level Max:
    QCF+HP+HK   team super: your partner flies in beside you and both X-Powers fire at once.
    QCB+HP+HK   Cross Over Fever: your partner joins you and one stick drives both X-Men
                until the TIME bar at the bottom of the screen runs out. X-Powers are free
                while it runs.
- Part of the damage stays red on the bar. A benched partner wins it back.
- A knocked-out fighter is replaced by the partner. One round per match. Time over compares
  team totals.
- Against the CPU, every stage opponent gets a partner, and CPU teams call Cross Over Fever
  and team supers at Level Max. Juggernaut and Magneto fight alone.

Supported sets (clean and unmodified)
-------------------------------------
  xmcota     Euro 950331 (the MAME parent, and the set Fightcade plays)
  xmcotau    USA 950105
  xmcotaj    Japan 950105
  xmcotar1d  Euro 950105, Phoenix Edition
Non-merged, split or merged ZIPs, with or without the key file.
- v4 patches four graphics ROMs (xmn.13m, 15m, 17m, 19m) that the clones share with the
  parent. A split clone ZIP is completed from your clean xmcota.zip: keep xmcota.zip in the
  same folder as the clone ZIP. The new ZIP is a complete set that doesn't need xmcota.zip.
- A merged xmcota.zip (several revisions in one file) gives a patched xmcota. The other
  revisions are left out of the new ZIP.
Refused: files that are already patched (by this version, v3, v1 or a four-player build),
other revisions, and ZIPs with anything else in them. Start from a clean ZIP, not a v3 one.

How to patch
------------
Windows:      drag your clean ZIP onto xcota-tag-v4-preview.cmd
              (or put the ZIP beside the .cmd and double-click the .cmd)
macOS/Linux:  python3 xcota_tag_patch.py /path/to/xmcota.zip
              (split clone with the parent somewhere else: add --parent /path/to/xmcota.zip)

It writes <set>_tag_v4.zip and <set>_tag_v4.zip.receipt.json beside your ZIP. Your ZIP is
only read. Then:
  Fightcade  Fightcade plays xmcota. Back up the xmcota.zip in Fightcade's ROMs folder
             (Fightcade\emulator\fbneo\ROMs), then put xmcota_tag_v4.zip there renamed to
             xmcota.zip. For an online match both players need the same patched file, so
             each of you runs the installer on a clean xmcota.zip.
  MAME       Copy <set>_tag_v4.zip into a separate ROM folder and rename the copy to
             <set>.zip (for example xmcota.zip). MAME's menu refuses patched sets ("the
             required ROM images are missing or incorrect"). Start it from a command
             prompt instead:
                 mame xmcota -rompath "C:\path\to\that\folder"
             It lists the changed ROMs as wrong checksums and runs. MAME also needs
             qsound_hle.zip in the ROM folder.
  FBNeo      A patched clone (xmcotau, xmcotaj, xmcotar1d) must not share its folder with a
             clean xmcota.zip: FBNeo would load the parent's unpatched graphics ROMs and the
             new HUD would not show. MAME uses the clone's own copies either way.
  RetroArch  With the stock FinalBurn Neo core, put the patched xmcota.zip in
             system/fbneo/patched/ and turn on "Allow patched romsets". The XCOTA TAG
             RetroArch core loads it from any ROM folder.
MAME and FBNeo need the key file inside the ZIP (xmcota.key, xmcotau.key, xmcotaj.key, or
phoenix.key for xmcotar1d). If your ZIP had none, the installer says so. Add the one from
your own set to the renamed copy.

Four players
------------
The four-player package (xcota-tag-v4-4p-preview) makes xmcota4p.zip for the XCOTA TAG
RetroArch core: four controllers on one machine, or online with Parsec or RetroArch netplay.
See its README.

What is in this package
-----------------------
  xcota-tag-v4-preview.cmd   Windows installer (runs the embedded PowerShell script)
  xcota_tag_patch.py         the same patch for macOS/Linux/Windows (Python 3.8+)
  xcota_tag_v4.spec.json     the patch itself: clean-member hashes, replacement bytes and
                             offsets, patched-member hashes
No ROM data is included. The replacement bytes are:
- the new code (25,284 bytes in the 05 program ROM, which was empty there) and short jumps
  into it in the 03 program ROM. 8,320 of the new bytes are the colour tables: the five
  extra colours of each X-Man, palette words from Marvel vs. Capcom 2's colour banks, as the
  MvC1 six-colour patch carries them;
- 238 new HUD tiles and three platform tiles in the blank end of graphics bank 1
  (xmn.13m/15m/17m/19m): the thin bars, the gold partner bar, the heal plus, the COMBO
  BREAKER letters, and the game's own A-Z HUD letters redrawn with an outline.
Nothing makes network requests.

How it was tested (and what was not)
------------------------------------
- MAME 0.264 (cloud, unpinned): the scripted regression (54 scenarios, including 17 new v4
  ones: tag cancels on hit, block and special, no cancel on a whiff or an X-Power, the
  full-screen kick landing, COMBO BREAKER with and without a bar, refused during a duo and
  allowed against one, stage falls on Mutant Hunting and Mojo World, the same X-Man twice,
  POW and the platform, and the six colours: a pick button's colours through a tag, the
  mirror rule, one X-Man twice in one team, and the characters' own palette flashes) passes
  on each of the four sets. All 13 X-Men were also looked at in all six colours.
- Fightcade's own emulator (fightcadeorg/fightcade-fbneo, built headless): see RELEASE.json
  for the v4 run.
- Installer gate: every layout above, run through both the Python patcher and the Windows
  installer's own PowerShell code (PowerShell 7.4.6 on Linux), gives the same members as the
  MAME-tested build, and every refusal case writes nothing. The count is in RELEASE.json.
- Not tested: Windows PowerShell 5.1 on a Windows PC, Fightcade online play and real
  hardware.

Known limits in this preview
----------------------------
- HP+HK is also Storm's flight and Iceman's Ice Avalanche. On the ground, with the partner
  standing, it tags instead. In the air, or with the partner knocked out, those moves work
  as before.
- X-Men: Children of the Atom has no tag lines, so the partner says its round-win line.
- COMBO BREAKER uses the throw input. If you hold back and mash HP while being hit, you will
  spend a bar.
- Akuma through the secret code was not tested.
