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

New in v4.1
-----------
- Fixed a reset. A knockout while a team had both X-Men on screen (Cross Over Fever or a
  team super) could reset the game a moment later. Testers saw it in Fightcade on Genosha
  and Mutant Hunting. While a partner is in play only one fighter's combo and message
  display may draw. v4 sent the other one back without a record address, and four stock
  callers still wrote their record through whatever address was left over. On those stages
  that was the other fighter, whose state got overwritten. The display that may not draw
  now writes into a scratch block that nothing draws.
- The four-player installer's closing text now says to keep the name xmcota4p.zip and play
  it in the XCOTA TAG RetroArch core. v4's text said to rename it, which loads the
  two-player game.
Start from your clean ZIP: the installer refuses a file already patched with v4.

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.1-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.1.zip and <set>_tag_v4.1.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.1.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.1.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.1-4p-preview) makes xmcota4p.zip for the XCOTA TAG
RetroArch core: four controllers on one machine, or online with Parsec or RetroArch netplay.
On Windows the XCOTA TAG RetroArch download does it all: put your clean xmcota.zip next to
PLAY XCOTA TAG 4P.cmd and double-click it. See its README.

What is in this package
-----------------------
  xcota-tag-v4.1-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.1.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,302 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: tags for every X-Man,
  KO hand-offs, Cross Over Fever and team supers, time over, and the v4 list: tag cancels, the
  full-screen kick, COMBO BREAKER, the stage falls, POW and the platform, the six colours)
  passes on each of the four sets with the v4.1 build.
- Fightcade's own emulator (fightcadeorg/fightcade-fbneo, built headless), the same scenarios
  on each v4.1 installer output: xmcota 54/54, xmcotau 52/54, xmcotaj 54/54, xmcotar1d 54/54.
  The xmcotau exceptions start from a scripted special that this core turns into a walk on
  that set; v3 and v4 do the same.
- The v4.1 fix: a random-input fight that resets v4 in Fightcade's core (a knockout on Genosha
  during Cross Over Fever) plays through on v4.1. The display writes that hit the other
  fighter in v4 land in the scratch block. See RELEASE.json.
- 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.
