Port the remaining battle items, the stats screen and hBattleTurn at the menu

- Run every non-ball item effect usable in battle from the ROM's
  ItemEffects: Full Restore, revives, bitter medicine, Bitter Berry, Ethers
  and Elixers, X items, X Accuracy, Guard Spec, Dire Hit and Poké Doll.
- Read happiness changes from HappinessChanges, including the larger
  level-up gain where a Pokémon was caught.
- Model hBattleTurn at the battle menu, including the trainer AI's writes,
  and drop the status-heal refusal.
- Port the stats screen for battles and Bill's PC.
- Compare the send-out and withdraw texts, RestoreHealth, RestorePP,
  ChangeHappiness and CalcPlayerStats with the original routines.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/reference-parity.spec.ts

@@ -2,10 +2,18 @@ import { test, expect, type Page } from "@playwright/test";
 import { existsSync, readFileSync } from "node:fs";
 import { CrystalAssets } from "../src/game/rom/assets";
 import { BattleData } from "../src/game/battle/data";
-import { applyTypeMatchups, calculateDamage } from "../src/game/battle/battle";
+import {
+  Battle,
+  applyTypeMatchups,
+  calculateDamage,
+  restoreHealth,
+  restoredPP,
+  sendOutText,
+  withdrawText,
+} from "../src/game/battle/battle";
 import { C } from "../src/game/battle/constants";
 import { NATIVE_MAPS } from "../src/game/rom/profile";
-import { calcStat } from "../src/game/party/pokemon";
+import { calcStat, maxPP } from "../src/game/party/pokemon";
 import { resolve } from "node:path";
 
 const romPath = resolve(
@@ -410,3 +418,260 @@ test("native stats and experience curves match the original routines", async ({
     expect(pokemon.expAtLevel(growth, level), `experience ${growth}/${level}`).toBe(original.exp);
   });
 });
+
+test("native switch texts, healing, PP, happiness and CalcPlayerStats match the original routines", async ({
+  page,
+}) => {
+  test.skip(
+    !existsSync(romPath) || !existsSync(symbolsPath),
+    "Requires the local user ROM and the private PRET rebuild.",
+  );
+  const { at, routine } = loadSymbols();
+  const bytes = new Uint8Array(readFileSync(romPath));
+  const assets = new CrystalAssets(bytes);
+  const pokemon = assets.pokemon;
+  let seed = 0xbeef;
+  const next = (limit: number) => {
+    seed = (seed * 1103515245 + 12345) >>> 0;
+    return (seed >>> 8) % limit;
+  };
+  const maxHp = () => (next(4) === 0 ? 4 + next(60) : 4 + next(996));
+  const cheerCases = Array.from({ length: 300 }, () => {
+    const max = maxHp();
+    return { max, hp: next(max + 1), atSwitch: next(max + 1) };
+  });
+  const healthCases = Array.from({ length: 300 }, () => {
+    const max = 1 + next(999);
+    const amounts = [10, 20, 50, 60, 80, 100, 200, 999, next(0x10000)];
+    return { max, hp: next(max + 1), amount: amounts[next(amounts.length)] };
+  });
+  const ppItems = [C.MAX_ELIXER, 0x3f, C.MAX_ETHER, C.ELIXER, C.MYSTERYBERRY];
+  const ppCases = Array.from({ length: 200 }, () => ({
+    move: 1 + next(251),
+    pp: (next(4) << 6) | next(64),
+    item: ppItems[next(ppItems.length)],
+  }));
+  const happinessCases = Array.from({ length: 300 }, () => ({
+    happiness: next(256),
+    action: 1 + next(19),
+    cursor: next(7),
+    mon: next(6),
+    egg: next(8) === 0,
+  }));
+  const statCases = Array.from({ length: 200 }, () => ({
+    levels: Array.from({ length: 5 }, () => 1 + next(13)),
+    stats: Array.from({ length: 5 }, () => 1 + next(999)),
+    status: [0, 1 << 6, 1 << 4, 1 << 3][next(4)],
+    enemyStatus: [0, 1 << 6, 1 << 4][next(3)],
+    enemyStats: Array.from({ length: 5 }, () => 1 + next(999)),
+    turn: next(2),
+  }));
+  await openReference(page);
+  const skipToTextbox = routine("SendOutMonText.skip_to_textbox");
+  const addresses = {
+    // The ROM copy loaded in the page gets `ret` instead of SendOutMonText's
+    // final `jp BattleTextbox`, so the routine returns its text in HL.
+    patch: skipToTextbox.bank * 0x4000 + skipToTextbox.address - 0x4000,
+    sendOut: routine("SendOutMonText"),
+    withdraw: { ...routine("WithdrawMonText.WithdrawMonText"), address: at("WithdrawMonText.WithdrawMonText") + 5 },
+    restoreHealth: routine("RestoreHealth"),
+    restorePP: routine("RestorePP"),
+    changeHappiness: routine("ChangeHappiness"),
+    calcPlayerStats: routine("CalcPlayerStats"),
+    multiplicand: at("hMultiplicand"),
+    enemyHP: at("wEnemyMonHP"),
+    enemyMaxHP: at("wEnemyMonMaxHP"),
+    hpAtSwitch: at("wEnemyHPAtTimeOfPlayerSwitch"),
+    link: at("wLinkMode"),
+    curPartyMon: at("wCurPartyMon"),
+    partyMon1: at("wPartyMon1"),
+    partySpecies: at("wPartySpecies"),
+    partyCount: at("wPartyCount"),
+    menuCursorY: at("wMenuCursorY"),
+    hpBuffer1: at("wHPBuffer1"),
+    ppItem: at("wTempRestorePPItem"),
+    monType: at("wMonType"),
+    battleMode: at("wBattleMode"),
+    partyMenuCursor: at("wPartyMenuCursor"),
+    battleMonHappiness: at("wBattleMonHappiness"),
+    playerLevels: at("wPlayerAtkLevel"),
+    playerStats: at("wPlayerStats"),
+    battleMonStats: at("wBattleMonAttack"),
+    battleMonStatus: at("wBattleMonStatus"),
+    enemyStatus: at("wEnemyMonStatus"),
+    enemyStats: at("wEnemyMonAttack"),
+    johto: at("wJohtoBadges"),
+    turn: at("hBattleTurn"),
+    text: {
+      GoMonText: at("GoMonText"),
+      DoItMonText: at("DoItMonText"),
+      GoForItMonText: at("GoForItMonText"),
+      YourFoesWeakGetmMonText: at("YourFoesWeakGetmMonText"),
+      ThatsEnoughComeBackText: at("ThatsEnoughComeBackText"),
+      ComeBackText: at("ComeBackText"),
+      OKComeBackText: at("OKComeBackText"),
+      GoodComeBackText: at("GoodComeBackText"),
+    },
+  };
+  const results = await page.evaluate(
+    async ({ addresses, cheerCases, healthCases, ppCases, happinessCases, statCases }) => {
+      const { BinjgbEmulator } = await import("/src/emulator/binjgb.ts");
+      const file = (document.querySelector("#reference-fixture") as HTMLInputElement).files![0];
+      const rom = new Uint8Array(await file.arrayBuffer());
+      if (rom[addresses.patch] !== 0xc3) throw new Error("Unexpected SendOutMonText ending.");
+      rom[addresses.patch] = 0xc9;
+      const reference = new BinjgbEmulator();
+      await reference.load(rom, document.createElement("canvas"));
+      const write = (address: number, value: number) => reference.writeMemory(address, value & 0xff);
+      const word = (address: number, value: number) => {
+        write(address, value >> 8);
+        write(address + 1, value);
+      };
+      const readWord = (address: number) => (reference.readMemory(address) << 8) | reference.readMemory(address + 1);
+      // Trampoline: DI; SP=$c7fe; switch banks; set BC and DE; CALL; store
+      // HL at $c6fd; write a sentinel; loop.
+      const call = (target: { bank: number; address: number }, bc = 0, de = 0) => {
+        const program = [
+          0xf3, 0x31, 0xfe, 0xc7, 0x3e, target.bank, 0xe0, 0x9d, 0xea, 0x00, 0x20,
+          0x01, bc & 0xff, bc >> 8, 0x11, de & 0xff, de >> 8,
+          0xcd, target.address & 0xff, target.address >> 8,
+          0x7d, 0xea, 0xfd, 0xc6, 0x7c, 0xea, 0xfe, 0xc6,
+          0x3e, 0x42, 0xea, 0xff, 0xc6, 0x18, 0xfe,
+        ];
+        write(0xc6ff, 0);
+        program.forEach((value, index) => write(0xc000 + index, value));
+        reference.setProgramCounter(0xc000);
+        reference.advanceFrames(2);
+        if (reference.readMemory(0xc6ff) !== 0x42) throw new Error(`Routine at ${target.address.toString(16)} did not return.`);
+        return reference.readMemory(0xc6fd) | (reference.readMemory(0xc6fe) << 8);
+      };
+      write(0xff70, 1);
+      write(addresses.link, 0);
+      write(addresses.johto, 0);
+      const textName = (hl: number) =>
+        Object.entries(addresses.text).find(([, address]) => address === hl)?.[0] ?? `0x${hl.toString(16)}`;
+      const cheers = cheerCases.map((input) => {
+        word(addresses.enemyHP, input.hp);
+        word(addresses.enemyMaxHP, input.max);
+        const sendOut = textName(call(addresses.sendOut));
+        word(addresses.hpAtSwitch, input.atSwitch);
+        write(addresses.multiplicand, 0);
+        const withdraw = textName(call(addresses.withdraw));
+        return { sendOut, withdraw };
+      });
+      const mon = addresses.partyMon1;
+      write(addresses.curPartyMon, 0);
+      const health = healthCases.map((input) => {
+        word(mon + 34, input.hp);
+        word(mon + 36, input.max);
+        // ItemRestoreHP's IsMonFainted loads the maximum into wHPBuffer1
+        // (low byte first), which a full restore copies.
+        write(addresses.hpBuffer1, input.max);
+        write(addresses.hpBuffer1 + 1, input.max >> 8);
+        call(addresses.restoreHealth, 0, input.amount);
+        return readWord(mon + 34);
+      });
+      const pp = ppCases.map((input) => {
+        write(mon + 2, input.move);
+        write(mon + 23, input.pp);
+        write(addresses.menuCursorY, 0);
+        write(addresses.ppItem, input.item);
+        call(addresses.restorePP);
+        return reference.readMemory(mon + 23);
+      });
+      write(addresses.partyCount, 6);
+      write(addresses.battleMode, 1);
+      const happiness = happinessCases.map((input) => {
+        for (let slot = 0; slot < 6; slot++) {
+          write(addresses.partySpecies + slot, input.egg && slot === input.mon ? 0xfd : 155);
+          write(mon + slot * 48 + 27, input.happiness);
+        }
+        write(addresses.curPartyMon, input.mon);
+        write(addresses.partyMenuCursor, input.cursor);
+        write(addresses.battleMonHappiness, 0x55);
+        call(addresses.changeHappiness, input.action);
+        return {
+          party: reference.readMemory(mon + input.mon * 48 + 27),
+          battle: reference.readMemory(addresses.battleMonHappiness),
+        };
+      });
+      const stats = statCases.map((input) => {
+        input.levels.forEach((level, i) => write(addresses.playerLevels + i, level));
+        input.stats.forEach((value, i) => word(addresses.playerStats + i * 2, value));
+        input.enemyStats.forEach((value, i) => word(addresses.enemyStats + i * 2, value));
+        write(addresses.battleMonStatus, input.status);
+        write(addresses.enemyStatus, input.enemyStatus);
+        write(addresses.turn, input.turn);
+        call(addresses.calcPlayerStats);
+        return {
+          player: Array.from({ length: 5 }, (_, i) => readWord(addresses.battleMonStats + i * 2)),
+          enemy: Array.from({ length: 5 }, (_, i) => readWord(addresses.enemyStats + i * 2)),
+          turn: reference.readMemory(addresses.turn),
+        };
+      });
+      reference.dispose();
+      return { cheers, health, pp, happiness, stats };
+    },
+    { addresses, cheerCases, healthCases, ppCases, happinessCases, statCases },
+  );
+  cheerCases.forEach((input, index) => {
+    expect(
+      { sendOut: sendOutText(input.hp, input.max), withdraw: withdrawText(input.atSwitch, input.hp, input.max) },
+      `cheer case ${index}: ${JSON.stringify(input)}`,
+    ).toEqual(results.cheers[index]);
+  });
+  healthCases.forEach((input, index) =>
+    expect(restoreHealth(input.hp, input.max, input.amount), `health case ${index}: ${JSON.stringify(input)}`).toBe(
+      results.health[index],
+    ),
+  );
+  ppCases.forEach((input, index) => {
+    const max = maxPP(pokemon, input.move, input.pp >> 6) & 63;
+    expect(restoredPP(input.pp, max, input.item) ?? input.pp, `PP case ${index}: ${JSON.stringify(input)}`).toBe(
+      results.pp[index],
+    );
+  });
+  // ChangeHappiness and CalcPlayerStats run on a battle's own state.
+  const battle = new Battle({
+    data: pokemon,
+    party: [],
+    pokedex: { seen: new Set(), caught: new Set() },
+    playerId: 1,
+    playerName: "CHRIS",
+    timeOfDay: 1,
+    random: () => 0,
+    text: () => ({}) as never,
+  });
+  const internals = battle as unknown as {
+    options: { party: { species: number; happiness: number }[] };
+    partyMenuCursor: number;
+    turn: number;
+    changeHappiness(index: number, action: number): void;
+    calcPlayerStats(): void;
+  };
+  happinessCases.forEach((input, index) => {
+    internals.options.party = Array.from({ length: 6 }, (_, slot) => ({
+      species: input.egg && slot === input.mon ? C.EGG : 155,
+      happiness: input.happiness,
+    }));
+    internals.partyMenuCursor = input.cursor;
+    battle.player.mon = { happiness: 0x55 } as never;
+    internals.changeHappiness(input.mon, input.action);
+    expect(
+      { party: internals.options.party[input.mon].happiness, battle: battle.player.mon.happiness },
+      `happiness case ${index}: ${JSON.stringify(input)}`,
+    ).toEqual(results.happiness[index]);
+  });
+  statCases.forEach((input, index) => {
+    battle.player.levels = [...input.levels, 7, 7];
+    battle.player.stats = [...input.stats];
+    battle.player.mon = { stats: [0, 0, 0, 0, 0], status: input.status } as never;
+    battle.enemy.mon = { stats: [...input.enemyStats], status: input.enemyStatus } as never;
+    internals.turn = input.turn;
+    internals.calcPlayerStats();
+    expect(
+      { player: battle.player.mon.stats, enemy: battle.enemy.mon.stats, turn: internals.turn },
+      `stat case ${index}: ${JSON.stringify(input)}`,
+    ).toEqual(results.stats[index]);
+  });
+});