Add the TM/HM pocket, Egg screens and Violet's remaining scripts

The pack's TM/HM pocket lists TMs and HMs with their moves, gives TMs and teaches either through the ABLE/NOT ABLE party menu, the compatibility and "already knows" checks and LearnMove; a TM is used up and makes the Pokémon happier. Eggs show no level or HP in the party menus, get the Egg stats page with its hatching hint, and are skipped by HealParty. Bug Catcher Wade's number registers (VAR_CALLERID and RandomPhoneMon).

The playthrough now runs through Falkner's ZEPHYRBADGE, the Togepi Egg, Kyle's Onix, Flash in Dark Cave, Wade's number and Earl's blackboard. With MAKE_TEST_SAVES it writes a Violet City backup for the manual checks.

Validated with 610 unit tests, 157 browser tests (including all 256 badge bytes against the original BadgeStatBoosts), native/reference builds and reference/vendor/release checks. Egg hatching (#29) and trainer calls (#30) remain on their cards.

Closes #31

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

tests/playthrough.test.ts

@@ -1,5 +1,7 @@
 import { beforeEach, describe, expect, it, onTestFailed } from "vitest";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { encodeSave } from "../src/storage/saves";
+import { CRYSTAL_ROM } from "../src/rom/validate";
 import { CrystalAssets } from "../src/game/rom/assets";
 import { GameWorld } from "../src/game/world/world";
 import type { Direction } from "../src/game/world/types";
@@ -23,13 +25,21 @@ const NEW_BARK = "24:4",
   VIOLET_GYM = "10:7",
   SPROUT_1F = "3:1",
   SPROUT_2F = "3:2",
-  SPROUT_3F = "3:3";
+  SPROUT_3F = "3:3",
+  KYLES_HOUSE = "10:11";
+const DARK_CAVE = "3:78",
+  EARLS_ACADEMY = "10:8";
+const PHONE_BUG_CATCHER_WADE = 16;
+const FLASH = 148,
+  HM05 = 0xf7;
+const TOGEPI = 175,
+  BELLSPROUT = 69,
+  ONIX = 95;
 const EVENT_TALKED_TO_MOM_AFTER_MYSTERY_EGG_QUEST = 0x40,
   EVENT_GOT_HM05_FLASH = 0x14,
-  EVENT_BEAT_FALKNER = 0x2bd,
+  EVENT_BEAT_FALKNER = 0x4bd,
   EVENT_GOT_TM31_MUD_SLAP = 0x8,
   EVENT_GOT_TOGEPI_EGG_FROM_ELMS_AIDE = 0x2d,
-  EVENT_ELMS_AIDE_IN_VIOLET_POKEMON_CENTER = 0x48c,
   ENGINE_ZEPHYRBADGE = 0x1b;
 
 /** The acceptance run for PLAN section 2: a new game played from the
@@ -53,8 +63,20 @@ describe.skipIf(!existsSync(romPath))(
     let world: GameWorld;
     const log: string[] = [];
 
+    /** A wild species to throw Poké Balls at instead of fighting. */
+    let wanted = 0;
+    /** The usable move with the most power, or the first with PP. */
+    const strongest = (mon: { moves: readonly number[]; pp: readonly number[] }) => {
+      let best = -1;
+      mon.moves.forEach((move, i) => {
+        if (!move || !(mon.pp[i] & 63)) return;
+        if (best < 0 || assets!.pokemon.move(move).power > assets!.pokemon.move(mon.moves[best]).power)
+          best = i;
+      });
+      return Math.max(0, best);
+    };
     /** Run scripts and battles until the player is free again. Battles use
-     * the first move with PP; a wild battle below half HP is run from, as
+     * the strongest move with PP; a wild battle below half HP is run from, as
      * a cautious player would. New moves are learned when there is room,
      * and other questions take the queued answers or their defaults. */
     const play = (answers: (number | string)[] = []) => {
@@ -68,17 +90,27 @@ describe.skipIf(!existsSync(romPath))(
           if (prompt?.kind === "action") {
             const { engine } = battle,
               mon = engine.player.mon;
-            if (engine.battleMode === C.WILD_BATTLE && mon.hp * 2 < mon.maxHp)
+            const ball = world.state.bag.balls.findIndex((slot) => slot.item === C.POKE_BALL);
+            if (
+              engine.battleMode === C.WILD_BATTLE &&
+              engine.enemy.mon.species === wanted &&
+              !world.state.party.some((member) => member.species === wanted) &&
+              ball >= 0
+            )
+              world.battleAction({ action: "item", item: C.POKE_BALL, slot: ball });
+            else if (engine.battleMode === C.WILD_BATTLE && mon.hp * 2 < mon.maxHp)
               world.battleAction({ action: "run" });
             else
-              world.battleAction({
-                action: "fight",
-                move: Math.max(
-                  0,
-                  mon.pp.findIndex((pp, i) => mon.moves[i] && pp & 63),
-                ),
-              });
+              world.battleAction({ action: "fight", move: strongest(mon) });
           } else if (prompt?.kind === "yesno") world.battleChoose(1);
+          // SHIFT's party menu: keep the Pokémon out (or send the first
+          // that can fight when one must go).
+          else if (prompt?.kind === "party")
+            world.battleChoose(
+              prompt.cancel
+                ? -1
+                : world.state.party.findIndex((mon, i) => i !== battle.engine.curBattleMon && !mon.egg && mon.hp > 0),
+            );
           else if (prompt?.kind === "forget") world.battleChoose(4);
           else if (prompt?.kind === "name") world.battleName("");
           else if (prompt?.kind === "stats" || battle.message?.prompt)
@@ -213,6 +245,22 @@ describe.skipIf(!existsSync(romPath))(
     };
 
     const lead = () => world.state.party[0];
+    /** With MAKE_TEST_SAVES, a backup for the board's manual checks, as
+     * tests/human-test-saves.test.ts writes them (kept out of git). */
+    const writeTestSave = (name: string) => {
+      if (!process.env.MAKE_TEST_SAVES) return;
+      mkdirSync("test-saves", { recursive: true });
+      writeFileSync(
+        `test-saves/${name}.crystal-save.json`,
+        encodeSave({
+          version: 1,
+          romHash: CRYSTAL_ROM.sha1,
+          coreId: "crystal-native-world-v1",
+          savedAt: new Date().toISOString(),
+          state: new TextEncoder().encode(JSON.stringify(world.save())),
+        }),
+      );
+    };
     /** PokecenterNurseScript from in front of the counter, then back out. */
     const heal = (center: string, city: string) => {
       enter(center, "up");
@@ -268,8 +316,22 @@ describe.skipIf(!existsSync(romPath))(
     };
     /** Find a way through warps among `maps` to `target`, as a player
      * trying staircases would: depth first, backing out of dead ends. */
-    const route = (target: string, maps: string[], depth = 6): boolean => {
-      if (world.mapId === target) return true;
+    const route = (
+      target: string,
+      maps: string[],
+      depth = 6,
+      goal?: { x: number; y: number },
+    ): boolean => {
+      const reachable = () => {
+        if (!goal) return true;
+        try {
+          findPath(world, goal.x, goal.y);
+          return true;
+        } catch {
+          return false;
+        }
+      };
+      if (world.mapId === target && reachable()) return true;
       if (!depth) return false;
       const here = world.save();
       for (const warp of world.map.warps) {
@@ -281,11 +343,43 @@ describe.skipIf(!existsSync(romPath))(
         }
         const from = world.mapId;
         walk(warp.x, warp.y);
-        if (world.mapId !== from && route(target, maps, depth - 1)) return true;
+        if (world.mapId !== from && route(target, maps, depth - 1, goal)) return true;
         world.restore(here);
       }
       return false;
     };
+    /** Advance to the next menu choice, keeping its pages in the log. */
+    const toChoice = () => {
+      for (let tick = 0; tick < 2000; tick++) {
+        const dialogue = world.dialogue;
+        if (dialogue) {
+          const page = dialogue.pages[dialogue.index];
+          if (log.at(-1) !== page) log.push(page);
+          if (dialogue.index === dialogue.pages.length - 1 && dialogue.choice) return dialogue.choice;
+          if (dialogue.holdTicks !== undefined) world.tick();
+          else world.advanceDialogue();
+        } else world.tick();
+      }
+      throw new Error(`No choice appeared: ${world.diagnostic}`);
+    };
+    /** Choose a menu item by its label (or a pattern). */
+    const choose = (label: string | RegExp) => {
+      const choice = toChoice();
+      if (choice.kind !== "menu") throw new Error(`Expected a menu, got ${choice.kind}`);
+      const index = choice.items.findIndex((item) => (typeof label === "string" ? item === label : label.test(item)));
+      expect(index, `${label} in ${choice.items.join(", ")}`).toBeGreaterThanOrEqual(0);
+      world.choose(index);
+    };
+    /** Choose an item in the pack. */
+    const choosePack = (item: number) => {
+      const choice = toChoice();
+      if (choice.kind !== "pack") throw new Error(`Expected the pack, got ${choice.kind}`);
+      for (const [pocket, { entries }] of choice.pockets.entries()) {
+        const index = entries.findIndex((entry) => entry.item === item);
+        if (index >= 0) return world.choosePackEntry(pocket, index);
+      }
+      throw new Error(`Item ${item} is not in the pack.`);
+    };
     /** From Route 31: through the gate to Violet's Pokémon Center and back. */
     const restInViolet = () => {
       exit(ROUTE_31_GATE, "left");
@@ -438,7 +532,8 @@ describe.skipIf(!existsSync(romPath))(
       exit(VIOLET, "left");
       expect(world.state.flags.size).toBeGreaterThan(0);
       reload();
-    });
+      writeTestSave("violet-city");
+    }, 120_000);
 
     it("trains on Route 31 and earns Flash from Elder Li in Sprout Tower", () => {
       traceFailures();
@@ -458,6 +553,186 @@ describe.skipIf(!existsSync(romPath))(
       expect(pages).toContain("FLASH");
       expect(world.state.events.has(EVENT_GOT_HM05_FLASH)).toBe(true);
       reload();
+    }, 120_000);
+
+    it("beats Falkner for the ZEPHYRBADGE and TM31, then hears from Elm's aide", () => {
+      traceFailures();
+      expect(route(SPROUT_1F, [SPROUT_1F, SPROUT_2F, SPROUT_3F], 6, { x: 9, y: 15 })).toBe(true);
+      exit(VIOLET);
+      heal(VIOLET_CENTER, VIOLET);
+      enter(VIOLET_GYM, "up");
+      walk(5, 2);
+      world.move("up"); // Falkner: this only turns the player
+      world.interact();
+      play();
+      expect(world.state.events.has(EVENT_BEAT_FALKNER), log.join("|")).toBe(true);
+      expect(world.state.flags.has(ENGINE_ZEPHYRBADGE)).toBe(true);
+      expect(world.state.events.has(EVENT_GOT_TM31_MUD_SLAP)).toBe(true);
+      expect(world.state.bag.tmsHms[30]).toBe(1); // TM31
+      reload();
+      exit(VIOLET);
+      // SPECIALCALL_ASSISTANT rings on a step: the aide waits in the
+      // Pokémon Center with the Egg.
+      enter(VIOLET_CENTER, "up");
+      expect(log.join("\n").replace(/\n/g, " ")).toContain("POKéMON CENTER");
+      // The aide's object flag (EVENT_ELMS_AIDE_IN_VIOLET_POKEMON_CENTER).
+      const aide = world.assets.map(VIOLET_CENTER).objects[4];
+      expect(world.state.events.has(aide.eventFlag)).toBe(false);
+      reload();
+    }, 120_000);
+
+    it("takes the Egg from Elm's aide", () => {
+      traceFailures();
+      walk(4, 4);
+      world.move("up"); // the aide: this only turns the player
+      world.interact();
+      play([1]);
+      expect(world.state.events.has(EVENT_GOT_TOGEPI_EGG_FROM_ELMS_AIDE)).toBe(true);
+      const egg = world.state.party.at(-1)!;
+      expect(egg).toMatchObject({
+        species: TOGEPI,
+        egg: true,
+        nickname: "EGG",
+        hp: 0,
+        happiness: world.assets.pokemon.baseData(TOGEPI).eggCycles,
+      });
+      // An Egg is neither seen nor caught.
+      expect(world.state.pokedex.caught.has(TOGEPI)).toBe(false);
+      reload();
     });
+
+    it("catches a Bellsprout on Route 31 and trades it to Kyle for Onix", () => {
+      traceFailures();
+      exit(VIOLET);
+      exit(ROUTE_31_GATE, "right");
+      exit(ROUTE_31, "right");
+      wanted = BELLSPROUT;
+      try {
+        for (let round = 0; round < 400 && !world.state.party.some((mon) => mon.species === BELLSPROUT); round++) {
+          if (!world.state.bag.balls.length) break;
+          train(lead().level + 1, restInViolet);
+        }
+      } finally {
+        wanted = 0;
+      }
+      const bellsprout = world.state.party.findIndex((mon) => mon.species === BELLSPROUT);
+      expect(bellsprout, log.slice(-20).join("|")).toBeGreaterThan(0);
+      exit(ROUTE_31_GATE, "left");
+      exit(VIOLET, "left");
+      enter(KYLES_HOUSE, "up");
+      const kyle = world.objects().find((object) => object.sprite === world.assets.map(KYLES_HOUSE).objects[1].sprite && object.id === world.assets.map(KYLES_HOUSE).objects[1].id)!;
+      walk(kyle.x - 1, kyle.y);
+      world.move("right");
+      world.interact();
+      play([1, bellsprout]);
+      const onix = world.state.party.at(-1)!;
+      expect(onix).toMatchObject({ species: ONIX, nickname: "ROCKY", ot: "KYLE", otId: 48926, dvs: 0x9666 });
+      expect(world.state.party.some((mon) => mon.species === BELLSPROUT && !mon.egg)).toBe(false);
+      expect(world.state.tradeFlags).toBe(1 << 1);
+      expect(world.state.pokedex.caught.has(ONIX)).toBe(true);
+      reload();
+    }, 120_000);
+
+    it("teaches HM05 to a new Bellsprout and lights up Dark Cave with FLASH", () => {
+      traceFailures();
+      exit(VIOLET);
+      exit(ROUTE_31_GATE, "right");
+      exit(ROUTE_31, "right");
+      wanted = BELLSPROUT;
+      try {
+        for (let round = 0; round < 400 && !world.state.party.some((mon) => mon.species === BELLSPROUT); round++)
+          train(lead().level + 1, restInViolet);
+      } finally {
+        wanted = 0;
+      }
+      const slot = world.state.party.findIndex((mon) => mon.species === BELLSPROUT);
+      expect(slot).toBeGreaterThan(0);
+      const nickname = world.state.party[slot].nickname;
+      // PACK, the TM/HM pocket's HM05, USE, YES, then the Bellsprout.
+      expect(world.openStartMenu()).toBe(true);
+      choose("PACK");
+      choosePack(HM05);
+      choose("USE");
+      expect(toChoice().kind).toBe("yesno");
+      world.choose(1);
+      const party = toChoice();
+      expect(party.kind === "menu" && party.details?.[slot]).toBe("ABLE");
+      world.choose(slot);
+      if (world.state.party[slot].moves.every(Boolean)) {
+        // A full move list asks which move to forget: the first one.
+        expect(toChoice().kind).toBe("yesno");
+        world.choose(1);
+        toChoice();
+        world.choose(0);
+      }
+      for (let i = 0; i < 10 && world.dialogue?.choice?.kind !== "pack"; i++) toChoice();
+      expect(log.join("\n").replace(/\n/g, " ")).toContain("learned FLASH!");
+      // The menus work on a draft that is kept once they close.
+      for (let i = 0; i < 10 && world.busy; i++) {
+        if (world.dialogue?.choice) world.advanceDialogue();
+        else world.tick();
+      }
+      play();
+      expect(world.state.party[slot].moves).toContain(FLASH);
+      expect(world.state.bag.tmsHms[50 + 4]).toBe(1); // an HM is kept
+      // Dark Cave is dark until FLASH, which the ZEPHYRBADGE allows.
+      enter(DARK_CAVE, "up");
+      expect(world.state.flash).toBe(false);
+      expect(world.openStartMenu()).toBe(true);
+      choose("POKéMON");
+      choose(nickname);
+      choose("FLASH");
+      play();
+      expect(world.state.flash, log.slice(-6).join("|")).toBe(true);
+      reload();
+    }, 120_000);
+
+    it("registers Bug Catcher Wade's number and reads Earl's blackboard", () => {
+      traceFailures();
+      exit(ROUTE_31);
+      // Talk to Wade wherever he stands (he walks up to battle on sight).
+      // A trainer who spots the player on the way battles and moves, so
+      // the approach is planned again.
+      const talkTo = (id: number) => {
+        for (let attempt = 0; attempt < 4; attempt++)
+          for (const [dx, dy, face] of [[-1, 0, "right"], [1, 0, "left"], [0, 1, "up"], [0, -1, "down"]] as const) {
+            const target = world.objects().find((object) => object.id === id)!;
+            const x = target.x + dx,
+              y = target.y + dy;
+            try {
+              if (!(world.x === x && world.y === y)) walk(x, y);
+            } catch {
+              continue;
+            }
+            const now = world.objects().find((object) => object.id === id)!;
+            if (now.x !== target.x || now.y !== target.y) break;
+            world.move(face);
+            world.interact();
+            return;
+          }
+        throw new Error(`No way to talk to object ${id}`);
+      };
+      talkTo(world.map.objects[2].id);
+      play([1]);
+      const pages = log.join("\n").replace(/\n/g, " ");
+      expect(pages).toContain("BUG CATCHER WADE");
+      expect(world.state.phone).toContain(PHONE_BUG_CATCHER_WADE);
+      reload();
+      restInViolet();
+      exit(ROUTE_31_GATE, "left");
+      exit(VIOLET, "left");
+      enter(EARLS_ACADEMY, "up");
+      walk(3, 1);
+      world.move("up");
+      world.interact();
+      choose("PSN");
+      toChoice();
+      expect(log.join("\n").replace(/\n/g, " ")).toContain("steadily loses HP");
+      // B leaves the blackboard.
+      world.choose(-1);
+      play();
+      expect(world.busy).toBe(false);
+      reload();
+    }, 120_000);
   },
 );