Enhance Surfing Pikachu minigame assets and functionality

- Updated .gitignore to include new generated assets for the Surfing Pikachu minigame.
- Added new image assets for the minigame, including title background and intro frames.
- Implemented extraction of Surfing Pikachu title art in RomExtractor.
- Updated CacheContract to include new asset paths.
- Enhanced SurfingMinigame with new constants and functions for improved gameplay mechanics.
- Added unit tests for new features and ensured existing tests pass.

tools/build_rom_data.py

@@ -2064,10 +2064,14 @@ def extract_field(rom, symbols, manifest, out_dir, assets_dir):
         raw_2bpp("SurfingPikachu1Graphics2", 128, 128, "minigame/surf_1b.png", transparent=True)
         raw_2bpp("SurfingPikachu1Graphics3", 96, 96, "minigame/surf_1c.png", transparent=True)
 
-        beach_intro = rom.bytes(62, 0x50bc, 240)
-        use_ctrl_pad = rom.bytes(62, 0x51ac, 15)
-        to_surf_rad = rom.bytes(62, 0x51bb, 13)
-        title_map = rom.bytes(62, 0x51c8, 72)
+        beach_sym = _symbol(symbols, "SurfingMinigame_BeachIntroTilemap")
+        use_ctrl_sym = _symbol(symbols, "SurfingMinigame_UseControlPadTilemap")
+        to_surf_sym = _symbol(symbols, "SurfingMinigame_ToSurfRadTilemap")
+        title_sym = _symbol(symbols, "SurfingMinigame_TitleTilemap")
+        beach_intro = rom.bytes(beach_sym.bank, beach_sym.address, 240)
+        use_ctrl_pad = rom.bytes(use_ctrl_sym.bank, use_ctrl_sym.address, 15)
+        to_surf_rad = rom.bytes(to_surf_sym.bank, to_surf_sym.address, 13)
+        title_map = rom.bytes(title_sym.bank, title_sym.address, 72)
         screen = [0xff] * (20 * 18)
         for i in range(240):
             screen[6 * 20 + i] = beach_intro[i]

tools/make_yellow_manifest.py

@@ -98,6 +98,12 @@ YELLOW_EXTRA_SYMBOLS = (
     "SurfingPikachu1Graphics1",
     "SurfingPikachu1Graphics2",
     "SurfingPikachu1Graphics3",
+    # Surfing Pikachu title screen tilemaps
+    # (engine/minigame/surfing_pikachu.asm DrawSurfingPikachuMinigameIntroBackground)
+    "SurfingMinigame_BeachIntroTilemap",
+    "SurfingMinigame_TitleTilemap",
+    "SurfingMinigame_ToSurfRadTilemap",
+    "SurfingMinigame_UseControlPadTilemap",
     # Oak's own battle back pic.  LoadPlayerBackPic (engine/battle/core.asm)
     # picks OldManPicBack for BATTLE_TYPE_OLD_MAN but ProfOakPicBack for
     # BATTLE_TYPE_PIKACHU, the Pallet Town catch scene (#557).
@@ -505,6 +511,41 @@ def derive(red, pokeyellow, symbols_path):
     if "SUMMER_BEACH_HOUSE" not in locations and "ROUTE_19" in locations:
         locations["SUMMER_BEACH_HOUSE"] = dict(locations["ROUTE_19"])
 
+    # Surfing Pikachu minigame asset index (src/ui/SurfingMinigame.lua).
+    yellow["field"]["surfingPikachu"] = {
+        "music": "Music_SurfingPikachu",
+        "sheets": {
+            "bg": {
+                "path": "assets/generated/minigame/surf_1a.png",
+                "width": 40, "height": 104,
+            },
+            "oam": {
+                "path": "assets/generated/minigame/surf_1b.png",
+                "width": 128, "height": 128,
+            },
+            "intro": {
+                "path": "assets/generated/minigame/surf_1c.png",
+                "width": 96, "height": 96,
+                "introPikaFrames": [
+                    "assets/generated/minigame/intro_pika_0.png",
+                    "assets/generated/minigame/intro_pika_1.png",
+                    "assets/generated/minigame/intro_pika_2.png",
+                    "assets/generated/minigame/intro_pika_3.png",
+                ],
+                "source": "data/sprite_anims/surfing_pikachu_oam.asm .IntroPikachu",
+            },
+            "titleBg": {
+                "path": "assets/generated/minigame/title_bg.png",
+                "width": 160, "height": 144,
+            },
+        },
+        "source": (
+            "engine/minigame/surfing_pikachu.asm "
+            "(DrawSurfingPikachuMinigameIntroBackground), "
+            "gfx/surfing_pikachu.asm"
+        ),
+    }
+
     meta = {
         "aliasCount": alias_hits,
         "omittedIntro": list(OMIT_INTRO_SYMBOLS),

tools/rom_manifest_yellow.json

@@ -8861,6 +8861,39 @@
         }
       ]
     },
+    "surfingPikachu": {
+      "music": "Music_SurfingPikachu",
+      "sheets": {
+        "bg": {
+          "height": 104,
+          "path": "assets/generated/minigame/surf_1a.png",
+          "width": 40
+        },
+        "intro": {
+          "height": 96,
+          "introPikaFrames": [
+            "assets/generated/minigame/intro_pika_0.png",
+            "assets/generated/minigame/intro_pika_1.png",
+            "assets/generated/minigame/intro_pika_2.png",
+            "assets/generated/minigame/intro_pika_3.png"
+          ],
+          "path": "assets/generated/minigame/surf_1c.png",
+          "source": "data/sprite_anims/surfing_pikachu_oam.asm .IntroPikachu",
+          "width": 96
+        },
+        "oam": {
+          "height": 128,
+          "path": "assets/generated/minigame/surf_1b.png",
+          "width": 128
+        },
+        "titleBg": {
+          "height": 144,
+          "path": "assets/generated/minigame/title_bg.png",
+          "width": 160
+        }
+      },
+      "source": "engine/minigame/surfing_pikachu.asm (DrawSurfingPikachuMinigameIntroBackground), gfx/surfing_pikachu.asm"
+    },
     "tilePairs": {
       "land": [
         {
@@ -26288,6 +26321,22 @@
       32,
       25380
     ],
+    "SurfingMinigame_BeachIntroTilemap": [
+      62,
+      20668
+    ],
+    "SurfingMinigame_TitleTilemap": [
+      62,
+      20936
+    ],
+    "SurfingMinigame_ToSurfRadTilemap": [
+      62,
+      20923
+    ],
+    "SurfingMinigame_UseControlPadTilemap": [
+      62,
+      20908
+    ],
     "SurfingPikachuSprite": [
       63,
       28143