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

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.
- The HUD is built like Marvel vs. Capcom's: the point's bar, the partner's bar and the
  X-Power gauge stacked in three stories, names inside the bars, two portraits per side
  that trade places on a tag, and a benched partner's name in darker letters.
- 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.
- v3 also patches four graphics ROMs (xmn.13m, 15m, 17m, 19m) that the clones share with
  the parent. A split clone ZIP (only its own ROMs) is completed from your clean
  xmcota.zip: keep xmcota.zip in the same folder as the clone ZIP. The new ZIP is then a
  complete set that does not 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, by v1 or by the four-player
build), other revisions, and ZIPs with anything else in them.

How to patch
------------
Windows:      drag your clean ZIP onto xcota-tag-v3-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_v3.zip and <set>_tag_v3.zip.receipt.json beside your ZIP. Your ZIP is
only read. Then:
  MAME       Copy <set>_tag_v3.zip into a separate ROM folder and rename the copy to
             <set>.zip (for example xmcotau.zip).
  Fightcade  Fightcade plays xmcota. Back up the xmcota.zip in Fightcade's ROMs folder,
             then put xmcota_tag_v3.zip there renamed to xmcota.zip. For an online match
             both players need the same patched file.
  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 life bars would not show. MAME uses the clone's own copies either way.
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. Both emulators report the changed ROMs as wrong
checksums. That is expected for any patch.

What is in this package
-----------------------
  xcota-tag-v3-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_v3.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 (14,590 bytes in the 05 program ROM, which was empty there) and short
  jumps into it in the 03 program ROM;
- 157 new HUD tiles in the blank end of graphics bank 1 (xmn.13m/15m/17m/19m): the thin
  bars, drawn from scratch, and the game's own A-Z HUD letters redrawn with an outline, in
  a bright and a dark version.
Nothing makes network requests.

How it was tested (and what was not)
------------------------------------
- MAME 0.264 (cloud, unpinned): 37 scripted scenarios pass on each of the four sets: tags
  for all ten X-Men on both sides, KO hand-offs, time over, rounds ending mid-tag, the
  select labels, the attract demo, continues, a challenger, the arcade ladder, Cross Over
  Fever on both sides and both at once, a team super, bench healing and the combo display.
- Fightcade's own emulator: the xmcota build was run headless in Fightcade's FBNeo
  (fightcadeorg/fightcade-fbneo, commit c959501; its CPS-2 driver and 68000 core as in
  Fightcade's release build). The same 37 scenarios pass there, and the HUD through a tag
  is pixel-identical to MAME's.
- 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 (patched, corrupt, wrong revision, missing,
  partial, merged without the parent, a split clone without its parent, and so on) writes
  nothing. The count is in RELEASE.json.
- FBNeo and the parent: with a clean xmcota.zip in the same folder as a patched clone, the
  Fightcade core loaded the parent's graphics ROMs (the new bars disappeared); MAME showed
  the patched HUD either way. Each installer output alone passed the 37 scenarios on the
  Fightcade core, the clones included.
- 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.
- The camera holds still while a fighter is off screen (about half a second).
- Akuma through the secret code was not tested.
