Merge pull request #615 from bryanthaboi/dev

After the player picks a starter and the rival takes his, every ball on
the lab table fell through to 'Those are POKé BALLs' instead of the
leftover-mon line.  Port the pokered OaksLabSelectedPokeBallScript ->
OaksLabLastMonScript beat: with EVENT_GOT_STARTER set, Oak turns to face
the player and reads 'That's PROF.OAK's last Pokémon!'.  The ROM's
'#MON' ligature is spelled out as Pokémon.

The renumbering also drops the table's nine out-of-range 'jump 21'
rows (run-time 'end' idioms) for explicit "end" targets, so the
script now validates cleanly.

Tests: T2 suite drives the ball talk table through a ScriptRunner-
compatible executor (leftover text, pre-escort text, pre-pick offer)
plus a T3 driver that talks to the leftover ball in a real game.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -40,6 +40,7 @@ body:
         - Windows
         - Linux
         - Android
+        - iOS
         - Multiple platforms
     validations:
       required: true

.github/workflows/release.yml

@@ -1,8 +1,8 @@
 name: Release
 
-# Builds the macOS, Windows, and Linux desktop apps, an Android APK, and the
-# Anbernic RG34XXSP (Stock OS 64-bit MOD / PortMaster) port on the self-hosted
-# Mac runner, and publishes them as a GitHub Release.
+# Builds the macOS, Windows, and Linux desktop apps, an Android APK, an iOS
+# IPA, and the Anbernic RG34XXSP (Stock OS 64-bit MOD / PortMaster) port on
+# the self-hosted Mac runner, and publishes them as a GitHub Release.
 #
 # Versioning:
 #   - First ever release is 0.1.0.
@@ -45,6 +45,12 @@ jobs:
     runs-on: [self-hosted, macOS]
 
     steps:
+      # The self-hosted runner lives under the machine owner's home
+      # directory; mask it first so absolute paths in every later step's
+      # output show up as *** in the public workflow logs.
+      - name: Mask runner paths
+        run: echo "::add-mask::$HOME"
+
       - name: Checkout
         uses: actions/checkout@v4
         with:
@@ -170,6 +176,20 @@ jobs:
           set -euo pipefail
           scripts/build_android.sh --version "${{ steps.ver.outputs.version }}"
 
+      - name: Install xcbeautify
+        run: |
+          set -euo pipefail
+          brew list xcbeautify >/dev/null 2>&1 || brew install xcbeautify
+
+      - name: Build iOS
+        run: |
+          set -euo pipefail
+          # Device Release IPA; signs with the Apple Development identity on
+          # the runner (auto team detection). Users on other Apple IDs still
+          # re-sign or build via docs/ios-install.md.
+          scripts/build_ios.sh --fetch --device --release \
+            --version "${{ steps.ver.outputs.version }}"
+
       - name: Build Anbernic RG34XXSP port
         run: |
           set -euo pipefail
@@ -226,6 +246,10 @@ jobs:
           [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
           cp "$apk" "$outdir/gen1recomp-${v}-android.apk"
 
+          ipa="dist/ios/gen1recomp.ipa"
+          [ -f "$ipa" ] || { echo "::error::$ipa not found (expected from scripts/build_ios.sh --device)"; exit 1; }
+          cp "$ipa" "$outdir/gen1recomp-${v}-ios.ipa"
+
           # Anbernic handheld port (suffix names the CFW it targets, so a
           # future RG35XX/other-CFW pack can ship alongside it).
           rg34="dist/rg34xxsp/gen1recomp-rg34xxsp-stockos64-mod.zip"
@@ -344,6 +368,7 @@ jobs:
             "dist/release/gen1recomp-${v}-windows.zip" \
             "dist/release/gen1recomp-${v}-linux.zip" \
             "dist/release/gen1recomp-${v}-android.apk" \
+            "dist/release/gen1recomp-${v}-ios.ipa" \
             "dist/release/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip" \
             "dist/release/gen1recomp-${v}.love" \
             "dist/release/sha256sums.txt"

.gitignore

@@ -16,6 +16,7 @@ __pycache__/
 .*
 !.github/
 !.gitignore
+!.luacheckrc
 
 # Android build outputs / local SDK path / packaged payload (keep love-android sources)
 mobile/android/app/build/
@@ -39,3 +40,6 @@ mobile/dist/
 # Tiled map-editing workspace (tools/tiled_export.py). Derived from the imported
 # ROM cache exactly like data/generated/, so it is never committable.
 /build/tiled/
+
+# per-machine iOS bundle-id pin (see scripts/build_ios.sh)
+mobile/ios/bundle_id.local

.luacheckrc

@@ -0,0 +1,43 @@
+-- Static-analysis config for `luacheck` (https://luacheck.readthedocs.io).
+--
+-- Run it over the engine with:  luacheck src   (or scripts/lint.sh)
+--
+-- The point is a high-signal baseline: the categories left on are the ones
+-- that catch real defects -- undefined globals/locals (the class that hid a
+-- `music.volume` crash: applyVolume read a `state` that was still the nil
+-- global), unused values, unreachable code, redefinitions. The cosmetic
+-- categories the codebase deliberately lives with (a `self`/`dt` an
+-- interface requires but a given method ignores, documented empty
+-- fall-through branches, the odd long line) are muted so they don't drown
+-- the signal.
+
+std = "luajit"
+
+-- LÖVE exposes `love` as a mutable table: games assign their callbacks onto
+-- it (love.wheelmoved, love.run, ...), so it is a regular global, not
+-- read-only -- otherwise every callback registration reads as a violation.
+globals = { "love" }
+
+read_globals = {
+  "jit",
+  -- LuaJIT 2.1 ships table.unpack even though the bare 5.1 `table` std lacks
+  -- it; without this, every `table.unpack` reads as an undefined field.
+  table = { fields = { "unpack" } },
+}
+
+-- Vendored/native trees and the test suites have their own conventions.
+exclude_files = {
+  "mobile/",
+  "tests/",
+  "tools/save-editor/",
+}
+
+ignore = {
+  "212",  -- unused argument -- self/dt kept for a shared method signature
+  "213",  -- unused loop variable -- `for _, v in` where only v is wanted
+  "421",  -- shadowing a local -- deliberate re-use in a few tight scopes
+  "431",  -- shadowing an upvalue
+  "432",  -- shadowing an argument
+  "542",  -- empty if branch -- documented fall-throughs, not gaps
+  "631",  -- line is too long
+}

README.md

@@ -1,6 +1,6 @@
 # Gen1Recomp
 
-A native LÖVE2D recreation of Poke Red and Blue. The engine and map
+A native LÖVE2D recreation of Poke Red, Blue and Yellow. The engine and map
 behavior are hand-written Lua; game data and graphics are decoded from a ROM
 supplied by the player.
 
@@ -8,33 +8,68 @@ supplied by the player.
 
 **SUPPORT / ANNOUNCEMENTS / MODS:** [Discord](https://bois.icu)
 
-<p align="center"> <a href="https://www.polygon.com/pokemon-red-blue-3d-voxel-mod-battle-pixels-gameplay-footage-remake/"> <img src="https://img.shields.io/badge/AS%20SEEN%20ON-POLYGON-ea2e49?style=for-the-badge" alt="As seen on Polygon"> </a> </p>
+<p align="center">
+
+<a href="https://www.youtube.com/@bryanthaboi">
+  <img src="https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="YouTube">
+</a>
+<a href="https://www.tiktok.com/@bryanthaboi">
+  <img src="https://img.shields.io/badge/TikTok-000000?style=for-the-badge&logo=tiktok&logoColor=white" alt="TikTok">
+</a>
+<a href="https://x.com/bryanthaboi">
+  <img src="https://img.shields.io/badge/X-000000?style=for-the-badge&logo=x&logoColor=white" alt="X">
+</a>
+<a href="https://bsky.app/profile/bryanthaboi.live">
+  <img src="https://img.shields.io/badge/Bluesky-0285FF?style=for-the-badge&logo=bluesky&logoColor=white" alt="Bluesky">
+</a>
+<a href="https://www.instagram.com/bryanthaboi">
+  <img src="https://img.shields.io/badge/Instagram-E4405F?style=for-the-badge&logo=instagram&logoColor=white" alt="Instagram">
+</a>
+
+</p>
+
+
+<p align="center"> <a href="https://www.polygon.com/pokemon-red-blue-3d-voxel-mod-battle-pixels-gameplay-footage-remake/"> <img src="https://img.shields.io/badge/AS%20SEEN%20ON-POLYGON-ea2e49?style=for-the-badge" alt="As seen on Polygon"> </a> 
+<a href="https://kotaku.com/pokemon-red-blue-recompilation-project-voxel-3d-mod-2000720281"> <img src="https://img.shields.io/badge/AS%20SEEN%20ON-KOTAKU-ea2e49?style=for-the-badge" alt="As seen on KOTAKU"> </a> 
+
+  <a href="https://www.digitalfoundry.net/news/2026/07/pokemon-yellow-voxel-mod-turns-the-original-gameboy-code-into-a-stunning-world">
+    <img src="https://img.shields.io/badge/AS%20SEEN%20ON-DIGITAL%20FOUNDRY-ea2e49?style=for-the-badge" alt="As seen on Digital Foundry">
+  </a>
+  <a href="https://www.androidauthority.com/unofficial-android-port-pokemon-red-blue-yellow-3692724/">
+  <img src="https://img.shields.io/badge/AS%20SEEN%20ON-ANDROID%20AUTHORITY-ea2e49?style=for-the-badge" alt="As seen on Android Authority">
+</a>
+
+<a href="https://www.xda-developers.com/this-amazing-pokemon-red-and-blue-voxel-mod-adds-a-3d-perspective-without-an-emulator/">
+  <img src="https://img.shields.io/badge/AS%20SEEN%20ON-XDA%20DEVELOPERS-ea2e49?style=for-the-badge" alt="As seen on XDA Developers">
+</a>
+</p>
 
 ### Watch the latest update video
 
-[![Watch the latest update video](https://img.youtube.com/vi/TbHdJIrKJJU/maxresdefault.jpg)](https://www.youtube.com/watch?v=TbHdJIrKJJU)
+[![Watch the latest update video](https://img.youtube.com/vi/8IOgqbe4YvA/maxresdefault.jpg)](https://www.youtube.com/watch?v=8IOgqbe4YvA)
 
 
 This project does not include a ROM, emulate the Game Boy, transpile assembly,
-or download a disassembly. A canonical US Poke Red or Blue ROM is the only
-game content input.
+or download a disassembly. A canonical US Poke Red, Blue, or Yellow ROM is the
+only game content input.
 
 The ROM is verified, used during import, and then released from memory. It is
 not copied into the cache. Later launches load the private generated cache and
-do not ask for the ROM again. Red and Blue can both be imported and played
-side by side.
+do not ask for the ROM again. Red, Blue, and Yellow can all be imported and
+played side by side.
 
 ## Quick Start
 
-Open the desktop app. On first boot, choose your legally obtained `.gb` file
-or drop it onto the window. Import takes a few seconds and the game starts
-automatically.
+Open the desktop app. On first boot, choose your legally obtained `.gb` /
+`.gbc` file or drop it onto the window. Import takes a few seconds and the
+game starts automatically.
 
-Only the canonical 1 MiB US Red and Blue ROMs are accepted. The importer
-verifies SHA-1 before creating any game data:
+Only the canonical 1 MiB US Red, Blue, and Yellow ROMs are accepted. The
+importer verifies SHA-1 before creating any game data:
 
 - Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
 - Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
+- Yellow: `cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1`
 
 The packaged app contains neither a ROM nor pre-extracted game data. Music,
 sound effects, and cries are synthesized while the game runs from compact
@@ -73,6 +108,17 @@ supported out of the box.
 COLORS, TILT, ZOOM, GBC FX, and VOID FILL are also in the Options menu
 and persist in `options.lua`.
 
+### Low-end devices
+
+**OPTIONS → PERFORMANCE** scales the port's optional extras for weaker
+hardware: **HIGH** (everything on), **BALANCED** (no 3D tilt or GBC FX),
+**LOW** (also no survey zoom, FPS capped), or **AUTO** — the default, which
+picks a tier from your device (ARM handhelds → LOW, phones → BALANCED,
+normal desktops → HIGH, unchanged). It only scales presentation; the
+fixed-step game logic is identical on every tier, and a lower tier hides
+your tilt/zoom/GBC-FX preferences without forgetting them. Details in
+[docs/new-features.md](docs/new-features.md#performance-tier-low-end-devices).
+
 ### Rulesets
 
 **OPTIONS → RULESET** picks which set of Gen 1 battle behaviors to run.
@@ -107,11 +153,11 @@ famous bugs included:
 
 ## Running From Source
 
-Requires LÖVE 11.x. Place a Red or Blue ROM in the project folder and
+Requires LÖVE 11.x. Place a Red, Blue, or Yellow ROM in the project folder and
 double-click `Play-Mac.command` or `Play-Windows.bat`, or run:
 
 ```sh
-scripts/setup.sh --rom "/path/to/Poke Red.gb"   # or Poke Blue.gb
+scripts/setup.sh --rom "/path/to/Poke Red.gb"   # or Blue.gb / Yellow.gbc
 scripts/run.sh
 ```
 
@@ -142,6 +188,13 @@ even on a different computer, as long as the same folder comes along.
 already written to either location is touched automatically, so copy files
 over yourself if you want to carry existing progress across the switch.
 
+## iOS
+
+Every release ships `gen1recomp-*-ios.ipa`. Sideload it with AltStore
+(Windows or Mac) — see [docs/ios-sideload.md](docs/ios-sideload.md). To
+build and install from source on a Mac instead, see
+[docs/ios-install.md](docs/ios-install.md).
+
 ## Handhelds
 
 A PortMaster-style port for the **Anbernic RG34XXSP** on Stock OS 64-bit MOD

conf.lua

@@ -1,4 +1,9 @@
 function love.conf(t)
+  -- PhysFS ignores symlinks unless told otherwise, so a mod dev-linked into
+  -- mods/ (ln -s, matching the mklink /J workflow on Windows) is invisible
+  -- to love.filesystem.getDirectoryItems without this.
+  love.filesystem.setSymlinksEnabled(true)
+
   local editor = os.getenv("POKEPORT_EDITOR") == "1"
   local developer = os.getenv("POKEPORT_DEV") == "1"
   if arg then
@@ -44,7 +49,7 @@ function love.conf(t)
     t.window.minwidth = 480
     t.window.minheight = 360
   end
-  t.version = "11.5"
+  t.version = love._os == "iOS" and "12.0" or "11.5"
   t.window.vsync = 1
   t.modules.joystick = true
   t.modules.physics = false
@@ -62,7 +67,10 @@ function love.conf(t)
     -- the game follow the device.  The renderer letterboxes the 160x144
     -- viewport into whatever size results, and the on-screen touch controls
     -- re-lay themselves out from the new window size, so both orientations
-    -- just work.  iOS follows the Info.plist orientations
+    -- just work.  FULL_SENSOR ignores the device's rotation lock, so
+    -- GameActivity.setOrientationBis remaps it to FULL_USER after SDL has
+    -- run: same orientations allowed, but auto-rotate being off now wins.
+    -- iOS follows the Info.plist orientations
     -- (see mobile/ios/overlays/love-ios.plist, now portrait + landscape).
     t.window.resizable = true
     -- Starting size is a tall portrait hint; the OS resizes to the real
@@ -78,6 +86,14 @@ function love.conf(t)
     -- player to copy their ROM there instead of needing a native file
     -- picker (LOVE 11.5 on Android has none -- see src/import/RomImporter.lua).
     t.externalstorage = osName == "Android"
+    -- LOVE 11.x exposes the phone's accelerometer as a 3-axis joystick by
+    -- default.  Gravity keeps one axis pinned near +/-1.0 whenever the phone
+    -- is held upright, so it streams past-deadzone joystickaxis events that
+    -- both hid the touch overlay every instant (it reads as "a controller is
+    -- in use") and, via the generic-joystick axis mapping (#459), walked the
+    -- player around by tilt.  Nothing in the game reads the accelerometer,
+    -- so drop the device entirely (#468).
+    t.accelerometerjoystick = false
   else
     t.window.resizable = true
   end

data/palettes_yellow.lua

@@ -0,0 +1,686 @@
+-- Generated by tools/build_data.py. DO NOT EDIT.
+-- Pokemon Yellow palettes (COLORS=OG YELLOW): SuperPalettes +
+-- CGBBasePalettes (authentic GBC look) as 4 8-bit RGB colors
+-- per palette (color 0 first), plus MonsterPalettes.
+return {
+  cgbBase = {
+    ["0F"] = {
+      { 255, 255, 255 },
+      { 107, 8, 255 },
+      { 0, 74, 255 },
+      { 8, 8, 8 },
+    },
+    BADGE = {
+      { 255, 255, 255 },
+      { 189, 66, 0 },
+      { 140, 115, 90 },
+      { 25, 25, 25 },
+    },
+    BLACK = {
+      { 255, 255, 255 },
+      { 25, 25, 25 },
+      { 25, 25, 25 },
+      { 25, 25, 25 },
+    },
+    BLUEMON = {
+      { 255, 255, 255 },
+      { 132, 148, 255 },
+      { 0, 8, 206 },
+      { 25, 25, 25 },
+    },
+    BROWNMON = {
+      { 255, 255, 255 },
+      { 239, 148, 82 },
+      { 140, 74, 41 },
+      { 25, 25, 25 },
+    },
+    CAVE = {
+      { 255, 255, 255 },
+      { 189, 66, 0 },
+      { 140, 115, 90 },
+      { 25, 25, 25 },
+    },
+    CELADON = {
+      { 255, 255, 255 },
+      { 41, 255, 41 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CERULEAN = {
+      { 255, 255, 255 },
+      { 41, 66, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CINNABAR = {
+      { 255, 255, 255 },
+      { 255, 66, 66 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CYANMON = {
+      { 255, 255, 255 },
+      { 132, 214, 255 },
+      { 0, 140, 255 },
+      { 25, 25, 25 },
+    },
+    FUCHSIA = {
+      { 255, 255, 255 },
+      { 255, 123, 123 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    GAMEFREAK = {
+      { 255, 255, 255 },
+      { 255, 156, 0 },
+      { 156, 156, 0 },
+      { 25, 25, 25 },
+    },
+    GRAYMON = {
+      { 255, 255, 255 },
+      { 165, 189, 82 },
+      { 90, 90, 41 },
+      { 25, 25, 25 },
+    },
+    GREENBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 0, 255, 0 },
+      { 25, 25, 25 },
+    },
+    GREENMON = {
+      { 255, 255, 255 },
+      { 140, 255, 90 },
+      { 8, 181, 49 },
+      { 25, 25, 25 },
+    },
+    INDIGO = {
+      { 255, 255, 255 },
+      { 90, 66, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    LAVENDER = {
+      { 255, 255, 255 },
+      { 206, 33, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    LOGO1 = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 0, 0 },
+      { 255, 0, 0 },
+    },
+    LOGO2 = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 58, 58, 206 },
+      { 0, 0, 140 },
+    },
+    MEWMON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 8, 8 },
+      { 25, 25, 25 },
+    },
+    PALLET = {
+      { 255, 255, 255 },
+      { 189, 140, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PEWTER = {
+      { 255, 255, 255 },
+      { 148, 148, 123 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PIKACHUS_BEACH = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PIKACHUS_BEACH_TITLE = {
+      { 255, 255, 255 },
+      { 74, 74, 74 },
+      { 255, 173, 0 },
+      { 25, 25, 25 },
+    },
+    PIKACHU_PORTRAIT = {
+      { 255, 255, 255 },
+      { 255, 148, 0 },
+      { 156, 58, 8 },
+      { 25, 25, 25 },
+    },
+    PINKMON = {
+      { 255, 255, 255 },
+      { 255, 123, 148 },
+      { 255, 0, 49 },
+      { 25, 25, 25 },
+    },
+    PURPLEMON = {
+      { 255, 255, 255 },
+      { 206, 123, 255 },
+      { 156, 0, 181 },
+      { 25, 25, 25 },
+    },
+    REDBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    REDMON = {
+      { 255, 255, 255 },
+      { 255, 140, 0 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    ROUTE = {
+      { 255, 255, 255 },
+      { 132, 255, 33 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    SAFFRON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    SLOTS1 = {
+      { 255, 255, 255 },
+      { 206, 8, 255 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS2 = {
+      { 255, 255, 255 },
+      { 255, 33, 156 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS3 = {
+      { 255, 255, 255 },
+      { 66, 255, 0 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS4 = {
+      { 255, 255, 255 },
+      { 0, 255, 255 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    TOWNMAP = {
+      { 255, 255, 255 },
+      { 0, 173, 255 },
+      { 82, 230, 0 },
+      { 8, 8, 8 },
+    },
+    VERMILION = {
+      { 255, 255, 255 },
+      { 255, 156, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    VIRIDIAN = {
+      { 255, 255, 255 },
+      { 156, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    YELLOWBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 148, 0 },
+      { 25, 25, 25 },
+    },
+    YELLOWMON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 230, 115, 0 },
+      { 25, 25, 25 },
+    },
+  },
+  order = {
+    "ROUTE",
+    "PALLET",
+    "VIRIDIAN",
+    "PEWTER",
+    "CERULEAN",
+    "LAVENDER",
+    "VERMILION",
+    "CELADON",
+    "FUCHSIA",
+    "CINNABAR",
+    "INDIGO",
+    "SAFFRON",
+    "TOWNMAP",
+    "LOGO1",
+    "LOGO2",
+    "0F",
+    "MEWMON",
+    "BLUEMON",
+    "REDMON",
+    "CYANMON",
+    "PURPLEMON",
+    "BROWNMON",
+    "GREENMON",
+    "PINKMON",
+    "YELLOWMON",
+    "GRAYMON",
+    "SLOTS1",
+    "SLOTS2",
+    "SLOTS3",
+    "SLOTS4",
+    "BLACK",
+    "GREENBAR",
+    "YELLOWBAR",
+    "REDBAR",
+    "BADGE",
+    "CAVE",
+    "GAMEFREAK",
+    "PIKACHUS_BEACH",
+    "PIKACHU_PORTRAIT",
+    "PIKACHUS_BEACH_TITLE",
+  },
+  palettes = {
+    ["0F"] = {
+      { 255, 255, 247 },
+      { 197, 165, 247 },
+      { 90, 165, 247 },
+      { 25, 16, 16 },
+    },
+    BADGE = {
+      { 255, 255, 247 },
+      { 165, 123, 90 },
+      { 181, 173, 165 },
+      { 49, 49, 49 },
+    },
+    BLACK = {
+      { 255, 255, 247 },
+      { 49, 49, 49 },
+      { 49, 49, 49 },
+      { 49, 49, 49 },
+    },
+    BLUEMON = {
+      { 255, 255, 247 },
+      { 173, 181, 255 },
+      { 74, 82, 165 },
+      { 49, 49, 49 },
+    },
+    BROWNMON = {
+      { 255, 255, 247 },
+      { 214, 189, 148 },
+      { 148, 115, 82 },
+      { 49, 49, 49 },
+    },
+    CAVE = {
+      { 255, 255, 247 },
+      { 165, 123, 90 },
+      { 181, 173, 165 },
+      { 49, 49, 49 },
+    },
+    CELADON = {
+      { 255, 255, 247 },
+      { 181, 255, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CERULEAN = {
+      { 255, 255, 247 },
+      { 181, 189, 255 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CINNABAR = {
+      { 255, 255, 247 },
+      { 255, 123, 115 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CYANMON = {
+      { 255, 255, 247 },
+      { 214, 230, 255 },
+      { 58, 197, 230 },
+      { 49, 49, 49 },
+    },
+    FUCHSIA = {
+      { 255, 255, 247 },
+      { 255, 214, 214 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    GAMEFREAK = {
+      { 255, 255, 247 },
+      { 230, 197, 115 },
+      { 165, 165, 90 },
+      { 49, 49, 49 },
+    },
+    GRAYMON = {
+      { 255, 255, 247 },
+      { 206, 206, 148 },
+      { 132, 132, 115 },
+      { 49, 49, 49 },
+    },
+    GREENBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 0, 173, 0 },
+      { 49, 49, 49 },
+    },
+    GREENMON = {
+      { 255, 255, 247 },
+      { 197, 230, 148 },
+      { 107, 173, 123 },
+      { 49, 49, 49 },
+    },
+    INDIGO = {
+      { 255, 255, 247 },
+      { 140, 140, 206 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    LAVENDER = {
+      { 255, 255, 247 },
+      { 222, 189, 239 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    LOGO1 = {
+      { 255, 255, 247 },
+      { 247, 247, 140 },
+      { 173, 0, 33 },
+      { 173, 0, 33 },
+    },
+    LOGO2 = {
+      { 255, 255, 247 },
+      { 247, 247, 140 },
+      { 148, 148, 197 },
+      { 58, 58, 132 },
+    },
+    MEWMON = {
+      { 255, 255, 247 },
+      { 255, 247, 181 },
+      { 222, 132, 132 },
+      { 49, 49, 49 },
+    },
+    PALLET = {
+      { 255, 255, 247 },
+      { 230, 222, 255 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PEWTER = {
+      { 255, 255, 247 },
+      { 189, 189, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PIKACHUS_BEACH = {
+      { 255, 255, 247 },
+      { 255, 247, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PIKACHUS_BEACH_TITLE = {
+      { 255, 255, 247 },
+      { 132, 132, 132 },
+      { 255, 206, 74 },
+      { 49, 49, 49 },
+    },
+    PIKACHU_PORTRAIT = {
+      { 255, 255, 247 },
+      { 230, 189, 74 },
+      { 148, 115, 82 },
+      { 49, 49, 49 },
+    },
+    PINKMON = {
+      { 255, 255, 247 },
+      { 255, 197, 214 },
+      { 255, 148, 173 },
+      { 49, 49, 49 },
+    },
+    PURPLEMON = {
+      { 255, 255, 247 },
+      { 222, 181, 247 },
+      { 181, 123, 189 },
+      { 49, 49, 49 },
+    },
+    REDBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    REDMON = {
+      { 255, 255, 247 },
+      { 255, 197, 90 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    ROUTE = {
+      { 255, 255, 247 },
+      { 189, 214, 156 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    SAFFRON = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    SLOTS1 = {
+      { 255, 255, 247 },
+      { 222, 181, 247 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    SLOTS2 = {
+      { 255, 255, 247 },
+      { 255, 189, 214 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    SLOTS3 = {
+      { 255, 255, 247 },
+      { 189, 255, 165 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    SLOTS4 = {
+      { 255, 255, 247 },
+      { 189, 239, 255 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    TOWNMAP = {
+      { 255, 255, 247 },
+      { 165, 214, 255 },
+      { 140, 189, 82 },
+      { 25, 16, 16 },
+    },
+    VERMILION = {
+      { 255, 255, 247 },
+      { 255, 206, 132 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    VIRIDIAN = {
+      { 255, 255, 247 },
+      { 214, 255, 173 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    YELLOWBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 230, 189, 74 },
+      { 49, 49, 49 },
+    },
+    YELLOWMON = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 230, 189, 74 },
+      { 49, 49, 49 },
+    },
+  },
+  pokemon = {
+    ABRA = "YELLOWMON",
+    AERODACTYL = "GRAYMON",
+    ALAKAZAM = "YELLOWMON",
+    ARBOK = "PURPLEMON",
+    ARCANINE = "REDMON",
+    ARTICUNO = "BLUEMON",
+    BEEDRILL = "YELLOWMON",
+    BELLSPROUT = "GREENMON",
+    BLASTOISE = "CYANMON",
+    BULBASAUR = "GREENMON",
+    BUTTERFREE = "CYANMON",
+    CATERPIE = "GREENMON",
+    CHANSEY = "PINKMON",
+    CHARIZARD = "REDMON",
+    CHARMANDER = "REDMON",
+    CHARMELEON = "REDMON",
+    CLEFABLE = "PINKMON",
+    CLEFAIRY = "PINKMON",
+    CLOYSTER = "GRAYMON",
+    CUBONE = "GRAYMON",
+    DEWGONG = "BLUEMON",
+    DIGLETT = "BROWNMON",
+    DITTO = "GRAYMON",
+    DODRIO = "BROWNMON",
+    DODUO = "BROWNMON",
+    DRAGONAIR = "BLUEMON",
+    DRAGONITE = "BROWNMON",
+    DRATINI = "GRAYMON",
+    DROWZEE = "YELLOWMON",
+    DUGTRIO = "BROWNMON",
+    EEVEE = "GRAYMON",
+    EKANS = "PURPLEMON",
+    ELECTABUZZ = "YELLOWMON",
+    ELECTRODE = "YELLOWMON",
+    EXEGGCUTE = "PINKMON",
+    EXEGGUTOR = "GREENMON",
+    FARFETCHD = "BROWNMON",
+    FEAROW = "BROWNMON",
+    FLAREON = "REDMON",
+    GASTLY = "PURPLEMON",
+    GENGAR = "PURPLEMON",
+    GEODUDE = "GRAYMON",
+    GLOOM = "REDMON",
+    GOLBAT = "BLUEMON",
+    GOLDEEN = "REDMON",
+    GOLDUCK = "CYANMON",
+    GOLEM = "GRAYMON",
+    GRAVELER = "GRAYMON",
+    GRIMER = "PURPLEMON",
+    GROWLITHE = "BROWNMON",
+    GYARADOS = "BLUEMON",
+    HAUNTER = "PURPLEMON",
+    HITMONCHAN = "BROWNMON",
+    HITMONLEE = "BROWNMON",
+    HORSEA = "CYANMON",
+    HYPNO = "YELLOWMON",
+    IVYSAUR = "GREENMON",
+    JIGGLYPUFF = "PINKMON",
+    JOLTEON = "YELLOWMON",
+    JYNX = "MEWMON",
+    KABUTO = "BROWNMON",
+    KABUTOPS = "BROWNMON",
+    KADABRA = "YELLOWMON",
+    KAKUNA = "YELLOWMON",
+    KANGASKHAN = "BROWNMON",
+    KINGLER = "REDMON",
+    KOFFING = "PURPLEMON",
+    KRABBY = "REDMON",
+    LAPRAS = "CYANMON",
+    LICKITUNG = "PINKMON",
+    MACHAMP = "GRAYMON",
+    MACHOKE = "GRAYMON",
+    MACHOP = "GRAYMON",
+    MAGIKARP = "REDMON",
+    MAGMAR = "REDMON",
+    MAGNEMITE = "GRAYMON",
+    MAGNETON = "GRAYMON",
+    MANKEY = "BROWNMON",
+    MAROWAK = "GRAYMON",
+    MEOWTH = "YELLOWMON",
+    METAPOD = "GREENMON",
+    MEW = "MEWMON",
+    MEWTWO = "MEWMON",
+    MOLTRES = "REDMON",
+    MR_MIME = "PINKMON",
+    MUK = "PURPLEMON",
+    NIDOKING = "PURPLEMON",
+    NIDOQUEEN = "BLUEMON",
+    NIDORAN_F = "BLUEMON",
+    NIDORAN_M = "PURPLEMON",
+    NIDORINA = "BLUEMON",
+    NIDORINO = "PURPLEMON",
+    NINETALES = "YELLOWMON",
+    ODDISH = "GREENMON",
+    OMANYTE = "BLUEMON",
+    OMASTAR = "BLUEMON",
+    ONIX = "GRAYMON",
+    PARAS = "REDMON",
+    PARASECT = "REDMON",
+    PERSIAN = "YELLOWMON",
+    PIDGEOT = "BROWNMON",
+    PIDGEOTTO = "BROWNMON",
+    PIDGEY = "BROWNMON",
+    PIKACHU = "YELLOWMON",
+    PINSIR = "BROWNMON",
+    POLIWAG = "BLUEMON",
+    POLIWHIRL = "BLUEMON",
+    POLIWRATH = "BLUEMON",
+    PONYTA = "REDMON",
+    PORYGON = "GRAYMON",
+    PRIMEAPE = "BROWNMON",
+    PSYDUCK = "YELLOWMON",
+    RAICHU = "YELLOWMON",
+    RAPIDASH = "REDMON",
+    RATICATE = "GRAYMON",
+    RATTATA = "GRAYMON",
+    RHYDON = "GRAYMON",
+    RHYHORN = "GRAYMON",
+    SANDSHREW = "BROWNMON",
+    SANDSLASH = "BROWNMON",
+    SCYTHER = "GREENMON",
+    SEADRA = "CYANMON",
+    SEAKING = "REDMON",
+    SEEL = "BLUEMON",
+    SHELLDER = "GRAYMON",
+    SLOWBRO = "PINKMON",
+    SLOWPOKE = "PINKMON",
+    SNORLAX = "PINKMON",
+    SPEAROW = "BROWNMON",
+    SQUIRTLE = "CYANMON",
+    STARMIE = "GRAYMON",
+    STARYU = "REDMON",
+    TANGELA = "BLUEMON",
+    TAUROS = "GRAYMON",
+    TENTACOOL = "CYANMON",
+    TENTACRUEL = "CYANMON",
+    VAPOREON = "CYANMON",
+    VENOMOTH = "PURPLEMON",
+    VENONAT = "PURPLEMON",
+    VENUSAUR = "GREENMON",
+    VICTREEBEL = "GREENMON",
+    VILEPLUME = "REDMON",
+    VOLTORB = "YELLOWMON",
+    VULPIX = "REDMON",
+    WARTORTLE = "CYANMON",
+    WEEDLE = "YELLOWMON",
+    WEEPINBELL = "GREENMON",
+    WEEZING = "PURPLEMON",
+    WIGGLYTUFF = "PINKMON",
+    ZAPDOS = "YELLOWMON",
+    ZUBAT = "BLUEMON",
+  },
+  source = "pokeyellow data/sgb/sgb_palettes.asm + data/pokemon/palettes.asm",
+}

data/scripts/celadon_eevee.lua

@@ -11,8 +11,70 @@
 -- equivalent, kept for save compatibility: rows 1-4 also self-heal
 -- older saves (flag set before the port hid the ball) by hiding the
 -- leftover ball on the next interaction.
+--
+-- The room's two readables (data/events/hidden_events.asm,
+-- hidden_events_for CELADON_MANSION_ROOF_HOUSE):
+--   hidden_text_predef 3, 0 / 4, 0  PrintBlackboardLinkCableText, LinkCableHelp
+--   hidden_text_predef 3, 4         PrintNotebookText, TMNotebook
+-- tools/extract/field.py only parses `hidden_event` rows, so no
+-- hidden_text_predef row reaches data/generated/field.lua and both tiles
+-- were dead A presses (#391).  Same hook shape as the bedroom SNES in
+-- data/scripts/flavor/reds_house_2f.lua (#135).  hidden_text_predef puts
+-- the predef id in the facing byte, so neither tile gates on facing.
+
+local Menu = require("src.ui.Menu")
+local TextBox = require("src.render.TextBox")
+
+-- TMNotebookText (data/text/text_2.asm) has no leading underscore, so the
+-- extractor never collects it and the pamphlet's text is inlined.
+local TM_NOTEBOOK_TEXT = "It's a pamphlet\non TMs.\f...\f"
+  .. "There are 50 TMs\nin all.\f"
+  .. "There are also 5\nHMs that can be\vused repeatedly.\f"
+  .. "SILPH CO."
+
+-- LinkCableHelp (engine/events/hidden_events/school_blackboard.asm):
+-- HowToLinkText's four headings in the 15x10 box at the top left; picking
+-- a heading prints its LinkCableInfoText and returns to the menu, B or
+-- STOP READING closes.
+local LINK_HEADINGS = { "HOW TO LINK", "COLOSSEUM", "TRADE CENTER" }
+
+local function linkCableHelp(game)
+  local text = game.data.text or {}
+  local items, showMenu, askHeading
+  function showMenu()
+    game.stack:push(Menu.new(game, items,
+      { tx = 0, ty = 0, tw = 15, th = 10, rowStep = 1 }))
+  end
+  function askHeading()
+    game.stack:push(TextBox.new(game,
+      text._LinkCableHelpText2 or "Which heading do\nyou want to read?",
+      showMenu))
+  end
+  items = {}
+  for i, label in ipairs(LINK_HEADINGS) do
+    items[i] = { label = label, onSelect = function()
+      game.stack:push(TextBox.new(game,
+        text["_LinkCableInfoText" .. i] or label, askHeading))
+    end }
+  end
+  items[#items + 1] = { label = "STOP READING" }
+  game.stack:push(TextBox.new(game,
+    text._LinkCableHelpText1 or "TRAINER TIPS\fUsing a Game Link\nCable",
+    askHeading))
+end
 
 return {
+  onInteract = function(game, ow, fx, fy)
+    if fy == 0 and (fx == 3 or fx == 4) then
+      linkCableHelp(game)
+      return true
+    end
+    if fx == 3 and fy == 4 then
+      game.stack:push(TextBox.new(game, TM_NOTEBOOK_TEXT))
+      return true
+    end
+    return false
+  end,
   talk = {
     TEXT_CELADONMANSION_ROOF_HOUSE_EEVEE_POKEBALL = {
       { "check_flag", "EVENT_GOT_EEVEE" },                     -- 1
@@ -22,11 +84,16 @@ return {
       { "jump", 13 },                                          -- 4
       { "give_pokemon", "EEVEE", 25 },                         -- 5
       { "jump_if_false", 12 },                                 -- 6 (party+box full)
-      { "play_sound", "Get_Item1" },                           -- 7 (GotMonText jingle)
-      { "show_text", "_GotMonText", { RAM = "EEVEE" } },       -- 8
-      { "set_flag", "EVENT_GOT_EEVEE" },                       -- 9
+      -- flag + HideObject before the jingle and GotMonText: the nickname
+      -- prompt inside give_pokemon and the text row both yield, and a
+      -- script that dies there would leave the EEVEE taken with the ball
+      -- still on the table and the gift claimable again (#426).  The row
+      -- count is unchanged, so the numeric jump targets still hold.
+      { "set_flag", "EVENT_GOT_EEVEE" },                       -- 7
       { "hide_object", "CELADON_MANSION_ROOF_HOUSE",
-        "CELADONMANSION_ROOF_HOUSE_EEVEE_POKEBALL" },          -- 10
+        "CELADONMANSION_ROOF_HOUSE_EEVEE_POKEBALL" },          -- 8
+      { "play_sound", "Get_Item1" },                           -- 9 (GotMonText jingle)
+      { "show_text", "_GotMonText", { RAM = "EEVEE" } },       -- 10
       { "jump", 13 },                                          -- 11
       { "show_text", "_BoxIsFullText" },                       -- 12
     },

data/scripts/flavor/bike_shop.lua

@@ -1,10 +1,9 @@
 -- BikeShop (BIKE_SHOP) flavor dialogue
 -- Source: pokered/scripts/BikeShop.asm, pokered/text/BikeShop.asm
 --
--- TEXT_BIKESHOP_CLERK is skipped: it drives the actual voucher-for-bicycle
--- exchange (YesNoChoice purchase menu, GiveItem, RemoveItemByID, SetEvent
--- EVENT_GOT_BICYCLE). That is a significant standalone feature outside the
--- scope of these two flavor NPCs and is left unported here.
+-- TEXT_BIKESHOP_CLERK lives in data/scripts/story2.lua (M.BIKE_SHOP): the
+-- voucher exchange and the BICYCLE/CANCEL price window need more than
+-- command rows (#568).
 
 return {
   BIKE_SHOP = {
@@ -20,12 +19,15 @@ return {
       -- CheckEvent EVENT_GOT_BICYCLE ; jr nz, .gotBike
       -- before the player owns a bike -> TheseBikesAreExpensiveText
       -- after the player owns a bike  -> CoolBikeText
+      -- The check reads the bag, not the event: the port hands out the
+      -- BICYCLE itself (a key item, so it cannot be tossed), and that also
+      -- reads right on saves written before the clerk set the event (#567).
       TEXT_BIKESHOP_YOUNGSTER = {
         { "face_player" },                                            -- 1
-        { "check_flag", "EVENT_GOT_BICYCLE" },                        -- 2
-        { "jump_if_true", 5 },                                        -- 3
+        { "check_item", "BICYCLE" },                                  -- 2
+        { "jump_if_true", 6 },                                        -- 3
         { "show_text", "_BikeShopYoungsterTheseBikesAreExpensiveText" }, -- 4
-        { "jump", 6 },                                                -- 5
+        { "jump", "end" },                                            -- 5
         { "show_text", "_BikeShopYoungsterCoolBikeText" },            -- 6
       },
     },

data/scripts/flavor/cerulean_badge_house.lua

@@ -35,13 +35,25 @@ local function middleAgedMan(game, ow, npc, done)
     -- .loop: print WhichBadgeText, then show the badge list menu again
     push(game, t._CeruleanBadgeHouseMiddleAgedManWhichBadgeText, function()
       local ListMenu = require("src.ui.ListMenu")
+      local Strings = require("src.core.Strings")
       local items = {}
       for _, id in ipairs(BADGE_ORDER) do
         local idef = game.data.items[id]
         items[#items + 1] = { label = idef and idef.name or id, value = id }
       end
+      -- PrintListMenuEntries prints ListMenuCancelText once it hits the
+      -- list's $FF terminator (home/list_menu.asm), so every
+      -- DisplayListMenuID list ends in an on-screen CANCEL row; picking it
+      -- takes DisplayListMenuIDLoop's ExitListMenu path, the same .done
+      -- exit as B (#569)
+      items[#items + 1] = { label = Strings("CANCEL") }
       local menu = ListMenu.new(game, "", items, {
         onChoose = function(item)
+          game.stack:pop()
+          if not item.value then
+            push(game, t._CeruleanBadgeHouseMiddleAgedManVisitAnyTimeText, done)
+            return
+          end
           push(game, t[BADGE_TEXT[item.value]], loop)
         end,
         onCancel = function()

data/scripts/flavor/cerulean_city.lua

@@ -3,6 +3,10 @@
 -- Both NPCs use text_asm with an hRandomAdd roll to pick one of several
 -- flavor lines (no flags, no branching outcome) -- ported as a weighted
 -- math.random pick each time the NPC is talked to.
+--
+-- Yellow renames Slowbro -> Electrode in the text labels (see
+-- tools/yellow_symbol_aliases.py); look up both so Red/Blue and Yellow
+-- share this script.
 
 local M = {}
 
@@ -12,6 +16,29 @@ local function push(game, ow, npc, done, text)
   game.stack:push(TextBox.new(game, text, done))
 end
 
+-- CeruleanCitySlowbroText / CeruleanCityElectrodeText
+-- cp 180 -> 76/256 chance of 1st; cp 120 -> 60/256 chance of 2nd;
+-- cp 60 -> 60/256 chance of 3rd; else 60/256 chance of 4th.
+local function talkMon(game, ow, npc, done)
+  local t = game.data.text
+  local roll = math.random(0, 255)
+  local text
+  if roll >= 180 then
+    text = t._CeruleanCitySlowbroTookASnoozeText
+        or t._CeruleanCityElectrodeTookASnoozeText
+  elseif roll >= 120 then
+    text = t._CeruleanCitySlowbroIsLoafingAroundText
+        or t._CeruleanCityElectrodeIsLoafingAroundText
+  elseif roll >= 60 then
+    text = t._CeruleanCitySlowbroTurnedAwayText
+        or t._CeruleanCityElectrodeTurnedAwayText
+  else
+    text = t._CeruleanCitySlowbroIgnoredOrdersText
+        or t._CeruleanCityElectrodeIgnoredOrdersText
+  end
+  push(game, ow, npc, done, text)
+end
+
 M.CERULEAN_CITY = {
   talk = {
     -- CeruleanCityCooltrainerF1Text (scripts/CeruleanCity.asm:362-393)
@@ -23,32 +50,20 @@ M.CERULEAN_CITY = {
       local text
       if roll >= 180 then
         text = t._CeruleanCityCooltrainerF1SlowbroUseSonicboomText
+            or t._CeruleanCityCooltrainerF1ElectrodeUseSonicboomText
       elseif roll >= 100 then
         text = t._CeruleanCityCooltrainerF1SlowbroPunchText
+            or t._CeruleanCityCooltrainerF1ElectrodePunchText
       else
         text = t._CeruleanCityCooltrainerF1SlowbroWithdrawText
+            or t._CeruleanCityCooltrainerF1ElectrodeWithdrawText
       end
       push(game, ow, npc, done, text)
     end,
 
-    -- CeruleanCitySlowbroText (scripts/CeruleanCity.asm:395-436)
-    -- cp 180 -> 76/256 chance of 1st; cp 120 -> 60/256 chance of 2nd;
-    -- cp 60 -> 60/256 chance of 3rd; else 60/256 chance of 4th.
-    TEXT_CERULEANCITY_SLOWBRO = function(game, ow, npc, done)
-      local t = game.data.text
-      local roll = math.random(0, 255)
-      local text
-      if roll >= 180 then
-        text = t._CeruleanCitySlowbroTookASnoozeText
-      elseif roll >= 120 then
-        text = t._CeruleanCitySlowbroIsLoafingAroundText
-      elseif roll >= 60 then
-        text = t._CeruleanCitySlowbroTurnedAwayText
-      else
-        text = t._CeruleanCitySlowbroIgnoredOrdersText
-      end
-      push(game, ow, npc, done, text)
-    end,
+    TEXT_CERULEANCITY_SLOWBRO = talkMon,
+    -- Yellow map object uses TEXT_CERULEANCITY_ELECTRODE
+    TEXT_CERULEANCITY_ELECTRODE = talkMon,
   },
 }
 

data/scripts/flavor/game_corner.lua

@@ -85,6 +85,47 @@ return {
         alreadyGotLabel = "_GameCornerGentlemanCloselyWatchTheReelsText",
         alreadyGotFallback = "The trick is to\nwatch the reels\vclosely!",
       }),
+
+      -- Yellow keeps all three giveaways with the same events and amounts
+      -- but renames the objects and their text labels: FISHING_GURU ->
+      -- FISHING_GURU1, CLERK2 -> MIDDLE_AGED_MAN2, GENTLEMAN ->
+      -- FISHING_GURU2 (pokeyellow/scripts/GameCorner.asm).  The Red/Blue
+      -- keys above never match there, so Yellow needs its own three (#552).
+      TEXT_GAMECORNER_FISHING_GURU1 = coinGiver({
+        event = "EVENT_GOT_10_COINS",
+        amount = 10,
+        askLabel = "_GameCornerFishingGuru1WantToPlayText",
+        askFallback = "Kid, do you want\nto play?",
+        receivedLabel = "_GameCornerFishingGuru1Received10CoinsText",
+        coinCaseFullLabel = "_GameCornerFishingGuru1DontNeedMyCoinsText",
+        coinCaseFullFallback = "You don't need my\ncoins!",
+        alreadyGotLabel = "_GameCornerFishingGuru1WinsComeAndGoText",
+        alreadyGotFallback = "Wins seem to come\nand go.",
+      }),
+
+      TEXT_GAMECORNER_MIDDLE_AGED_MAN2 = coinGiver({
+        event = "EVENT_GOT_20_COINS_2",
+        amount = 20,
+        askLabel = "_GameCornerMiddleAgedMan2WantSomeCoinsText",
+        askFallback = "What's up? Want\nsome coins?",
+        receivedLabel = "_GameCornerMiddleAgedMan2Received20CoinsText",
+        coinCaseFullLabel = "_GameCornerMiddleAgedMan2YouHaveLotsOfCoinsText",
+        coinCaseFullFallback = "You have lots of\ncoins!",
+        alreadyGotLabel = "_GameCornerMiddleAgedMan2INeedMoreCoinsText",
+        alreadyGotFallback = "Darn! I need more\ncoins for the\vPOKéMON I want!",
+      }),
+
+      TEXT_GAMECORNER_FISHING_GURU2 = coinGiver({
+        event = "EVENT_GOT_20_COINS",
+        amount = 20,
+        askLabel = "_GameCornerFishingGuru2ThrowingMeOffText",
+        askFallback = "Hey, what? You're\nthrowing me off!\vHere are some\vcoins, shoo!",
+        receivedLabel = "_GameCornerFishingGuru2Received20CoinsText",
+        coinCaseFullLabel = "_GameCornerFishingGuru2YouGotYourOwnCoinsText",
+        coinCaseFullFallback = "You've got your\nown coins!",
+        alreadyGotLabel = "_GameCornerFishingGuru2CloselyWatchTheReelsText",
+        alreadyGotFallback = "The trick is to\nwatch the reels\vclosely!",
+      }),
     },
   },
 }

data/scripts/flavor/viridian_school_house.lua

@@ -0,0 +1,95 @@
+-- Viridian School House's two readables (data/events/hidden_events.asm,
+-- hidden_events_for VIRIDIAN_SCHOOL_HOUSE):
+--   hidden_text_predef 3, 0  PrintBlackboardLinkCableText, ViridianSchoolBlackboard
+--   hidden_text_predef 3, 4  PrintNotebookText, ViridianSchoolNotebook
+-- tools/extract/field.py only parses `hidden_event` rows, so neither
+-- hidden_text_predef row reaches data/generated/field.lua and both tiles
+-- were dead A presses (#503).  Same hook shape, and the same sibling asm
+-- file, as the Celadon roof house in data/scripts/celadon_eevee.lua (#391);
+-- hidden_text_predef spends the facing byte on the tx_pre id, so neither
+-- tile gates on facing.
+
+local Menu = require("src.ui.Menu")
+local TextBox = require("src.render.TextBox")
+
+-- ViridianSchoolBlackboard (engine/events/hidden_events/school_blackboard.asm):
+-- StatusAilmentText1/2 are the two columns of the 12x8 box at the top left
+-- (hlcoord 0, 0 + `lb bc, 6, 10`); picking a status prints its
+-- ViridianBlackboardStatusPointers entry and jumps back to .blackboardLoop,
+-- QUIT or B falls through to .exitBlackboard.
+local STATUS_LABELS = {
+  { " SLP", "_ViridianBlackboardSleepText" },
+  { " PSN", "_ViridianBlackboardPoisonText" },
+  { " PAR", "_ViridianBlackboardPrlzText" },
+  { " BRN", "_ViridianBlackboardBurnText" },
+  { " FRZ", "_ViridianBlackboardFrozenText" },
+}
+
+local function blackboard(game)
+  local text = game.data.text or {}
+  local items, showMenu, askHeading
+  function showMenu()
+    game.stack:push(Menu.new(game, items,
+      { tx = 0, ty = 0, tw = 12, th = 8, rowStep = 1 }))
+  end
+  -- ViridianSchoolBlackboardText2 is reprinted on every .blackboardLoop
+  -- pass, immediately before HandleMenuInput
+  function askHeading()
+    game.stack:push(TextBox.new(game,
+      text._ViridianSchoolBlackboardText2 or "Which heading do\nyou want to read?",
+      showMenu))
+  end
+  items = {}
+  for i, row in ipairs(STATUS_LABELS) do
+    local label, key = row[1], row[2]
+    items[i] = { label = label, onSelect = function()
+      game.stack:push(TextBox.new(game, text[key] or label, askHeading))
+    end }
+  end
+  -- no onSelect: Menu's own pop closes the box, matching .exitBlackboard
+  items[#items + 1] = { label = " QUIT" }
+  game.stack:push(TextBox.new(game,
+    text._ViridianSchoolBlackboardText1
+      or "The blackboard\ndescribes POKéMON\vSTATUS changes\vduring battles.",
+    askHeading))
+end
+
+-- ViridianSchoolNotebook (engine/events/hidden_events/school_notebooks.asm):
+-- pages 1-3 each end in TurnPageSchoolNotebook (TurnPageText + YesNoChoice)
+-- and NO stops the read; page 4 turns without asking and runs straight into
+-- page 5, the girl catching you at it.
+local function notebook(game)
+  local text = game.data.text or {}
+  local function page(n, after)
+    return TextBox.new(game, text["_ViridianSchoolNotebookText" .. n] or "", after)
+  end
+  local function turnPage(nextPage)
+    return function()
+      game.stack:push(TextBox.new(game, text._TurnPageText or "Turn the page?",
+        nil, { choice = function(yes)
+          if yes then game.stack:push(nextPage()) end
+        end }))
+    end
+  end
+  local function page5() return page(5) end
+  local function page4() return page(4, function() game.stack:push(page5()) end) end
+  local function page3() return page(3, turnPage(page4)) end
+  local function page2() return page(2, turnPage(page3)) end
+  game.stack:push(page(1, turnPage(page2)))
+end
+
+return {
+  VIRIDIAN_SCHOOL_HOUSE = {
+    onInteract = function(game, ow, fx, fy)
+      if fx == 3 and fy == 0 then
+        blackboard(game)
+        return true
+      end
+      if fx == 3 and fy == 4 then
+        notebook(game)
+        return true
+      end
+      return false
+    end,
+  },
+}

data/scripts/flavor_all.lua

@@ -60,6 +60,7 @@ local files = {
   "data.scripts.flavor.victory_road_2f",
   "data.scripts.flavor.viridian_city",
   "data.scripts.flavor.viridian_nickname_house",
+  "data.scripts.flavor.viridian_school_house", -- #503
   "data.scripts.flavor.wardens_house",
 }
 

data/scripts/oaks_lab.lua

@@ -6,6 +6,8 @@
 --   takes it ("I'll take this one, then!") and both balls disappear.
 --   Source: scripts/OaksLab.asm OaksLabCharmanderPokeBallText /
 --   OaksLabRivalTakePokeBallScript.
+-- * Leftover ball (after the pick): Oak turns and reads the last-mon
+--   line instead of re-offering the starter (OaksLabLastMonScript, #601).
 -- * Rival (object 1): before starter -> "go ahead and choose" once Oak
 --   has walked you in, else "gramps isn't around" (#218); with
 --   starter -> taunt + battle OPP_RIVAL1 with the counter-pick party
@@ -23,7 +25,7 @@ local function starterBall(askText, species, choseFlag, ownBall,
     { "jump_if_true", 20 },                       -- 2
     -- no picking until Oak has walked you in (OaksLabScript gating)
     { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB" }, -- 3
-    { "jump_if_false", 20 },                      -- 4
+    { "jump_if_false", 22 },                      -- 4
     -- the Pokédex "new species" entry shows before the ask (predef
     -- StarterDex ahead of OaksLabYouWant...Text).  StarterDex temporarily
     -- sets the owned bits so ShowPokedexData prints height/weight/text;
@@ -31,7 +33,7 @@ local function starterBall(askText, species, choseFlag, ownBall,
     { "push_screen", "DexEntryMenu",
       { species = species, forceOwned = true } }, -- 5
     { "ask", askText },                           -- 6
-    { "jump_if_false", 21 },                      -- 7
+    { "jump_if_false", "end" },                   -- 7
     -- OaksLab.asm prints ReceivedMon then AddPartyMon (AskName lives
     -- inside give_pokemon).  Show the received text first so the
     -- nickname prompt follows "you got X", matching Gen1.
@@ -52,9 +54,16 @@ local function starterBall(askText, species, choseFlag, ownBall,
       { RAM = rivalBall == "OAKSLAB_CHARMANDER_POKE_BALL" and "CHARMANDER"
               or rivalBall == "OAKSLAB_SQUIRTLE_POKE_BALL" and "SQUIRTLE"
               or "BULBASAUR" } },                 -- 17
-    { "jump", 21 },                               -- 18
-    { "jump", 21 },                               -- 19 (spacer)
-    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 20
+    { "jump", "end" },                            -- 18
+    { "jump", "end" },                            -- 19 (spacer)
+    -- a leftover ball after the player's pick: Oak turns to face the
+    -- player and reads the last-mon line instead of re-offering the
+    -- starter (scripts/OaksLab.asm OaksLabSelectedPokeBallScript ->
+    -- OaksLabLastMonScript; #601).  The ROM's "#MON" ligature is spelled
+    -- out as Pokémon here.
+    { "face_object", 5, "down" },                 -- 20
+    { "show_text", "That's PROF.OAK's\nlast Pokémon!" }, -- 21
+    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 22
   }
 end
 

data/scripts/oaks_lab_yellow.lua

@@ -143,17 +143,25 @@ return {
         -- OaksLabRivalExclamationScript: "!" over the rival
         { "emote", RIVAL, "shock" },
       }
-      -- .RivalPushesPlayerAwayFromEeveeBall + the PAD_RIGHT x2 shove:
-      -- the rival cuts across to the ball WHILE the player standing
-      -- below it is bumped two tiles right (both movements run in the
-      -- same beat, so the walk overlaps the shove like the original)
+      -- .RivalPushesPlayerAwayFromEeveeBall is DOWN then RIGHT x3 (the $07
+      -- bytes are Yellow's own step-right encoding, decoded by
+      -- engine/overworld/movement.asm Func_5288 -> Func_532b), and the
+      -- PAD_RIGHT x2 shove is NOT queued alongside it:
+      -- OaksLabRivalTakesPokeballScript .asm_1c564 polls every frame and
+      -- only simulates the pair once wNPCNumScriptedSteps reads 1 -- i.e.
+      -- as the rival begins the LAST byte, the step onto the tile the
+      -- player is standing on.  Starting both on one row had Red stroll
+      -- off the Eevee while the rival was still at the top of the table
+      -- (#559).
       if py == 4 then
-        rows[#rows + 1] = { "walk_npc", RIVAL,
-          { "down", "right", "right", "right" }, { wait = false } }
+        rows[#rows + 1] = { "walk_npc", RIVAL, { "down", "right", "right" } }
+        -- this one runs concurrently with the shove below
+        rows[#rows + 1] = { "walk_npc", RIVAL, { "right" }, { wait = false } }
         rows[#rows + 1] = { "face_player_dir", "left" }
         rows[#rows + 1] = { "move_player", "right", 2 }
-        -- let the rival finish the last stretch to (7,4)
-        rows[#rows + 1] = { "wait", 40 }
+        -- move_player blocks for both tiles, so the rival has already
+        -- landed on (7,4); this is just the beat before he turns up
+        rows[#rows + 1] = { "wait", 20 }
       else
         rows[#rows + 1] = { "move_npc_to", RIVAL, 7, 4 }
       end

data/scripts/story.lua

@@ -183,6 +183,7 @@ M.BILLS_HOUSE = {
                                    overworld = ow },
                                  "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
             game.save.flags.EVENT_BILL_SAID_USE_CELL_SEPARATOR = true
+            require("src.world.PikachuFollower").onBillEnteredMachine(game, ow)
             done()
           end
           if ow.player.facing == "down" then
@@ -273,6 +274,9 @@ M.BILLS_HOUSE = {
       Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL1")
       Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL2")
     end
+    if not flags.EVENT_MET_BILL_2 then
+      require("src.world.PikachuFollower").onBillsHouseEnter(game, ow)
+    end
   end,
 }
 
@@ -643,7 +647,12 @@ M.WARDENS_HOUSE = {
     TEXT_WARDENSHOUSE_WARDEN = {
       { "face_player" },                                             -- 1
       { "check_flag", "EVENT_GOT_HM04" },                            -- 2
-      { "jump_if_true", 13 },                                        -- 3
+      -- #535: previously jumped to the same silent-end target as the
+      -- give-then-thank fallthrough (row 13), so the warden said nothing
+      -- on every visit after the trade. pokered's .got_item branch
+      -- (scripts/WardensHouse.asm) instead prints HM04ExplanationText,
+      -- so route here to the new row 17 that does the same.
+      { "jump_if_true", 17 },                                        -- 3
       { "check_item", "GOLD_TEETH" },                                -- 4
       { "jump_if_false", 15 },                                       -- 5
       { "show_text", "_WardensHouseWardenGaveTheGoldTeethText" },    -- 6
@@ -654,9 +663,15 @@ M.WARDENS_HOUSE = {
       { "give_item", "HM_STRENGTH", 1, false },                      -- 10
       { "show_text", "_WardensHouseWardenReceivedHM04Text" },        -- 11
       { "set_flag", "EVENT_GOT_HM04" },                              -- 12
-      { "jump", 16 },                                                -- 13 (already got it)
-      { "jump", 16 },                                                -- 14 (unused)
+      { "jump", 18 },                                                -- 13 (already got it this convo; jp .done)
+      { "jump", 18 },                                                -- 14 (unused)
       { "show_text", "_WardensHouseWardenGibberish1Text" },          -- 15
+      { "jump", 18 },                                                -- 16 (#535: skip the new explanation row below)
+      -- #535: pokered .got_item branch (scripts/WardensHouse.asm) --
+      -- printed on every subsequent talk once EVENT_GOT_HM04 is set.
+      -- Text is _WardensHouseWardenHM04ExplanationText (text/WardensHouse.asm):
+      -- HM04 teaches Strength, and hints at the Safari Zone secret house.
+      { "show_text", "_WardensHouseWardenHM04ExplanationText" },     -- 17
     },
   },
 }
@@ -666,6 +681,48 @@ M.WARDENS_HOUSE = {
 -- generic OPP_GIOVANNI#2 battle)
 -- -------------------------------------------------------------------
 
+-- SilphCo11FTeamRocketLeavesScript (scripts/SilphCo11F.asm) hides every
+-- ROCKET and rocket-aligned SCIENTIST toggle on 2F-11F the moment Giovanni
+-- falls; the item balls, the 2F/10F rescued workers and the 7F rival keep
+-- theirs.  Names and order are data/maps/toggleable_objects.asm's
+-- TOGGLE_SILPH_CO_<floor>_n entries.  Saffron City's half of the same
+-- script lives in M.SAFFRON_CITY (story4.lua) (#392).
+local SILPH_ROCKET_OBJECTS = {
+  { "SILPH_CO_2F",  { "SILPHCO2F_SCIENTIST1", "SILPHCO2F_SCIENTIST2",
+                      "SILPHCO2F_ROCKET1", "SILPHCO2F_ROCKET2" } },
+  { "SILPH_CO_3F",  { "SILPHCO3F_ROCKET", "SILPHCO3F_SCIENTIST" } },
+  { "SILPH_CO_4F",  { "SILPHCO4F_ROCKET1", "SILPHCO4F_SCIENTIST",
+                      "SILPHCO4F_ROCKET2" } },
+  { "SILPH_CO_5F",  { "SILPHCO5F_ROCKET1", "SILPHCO5F_SCIENTIST",
+                      "SILPHCO5F_ROCKER", "SILPHCO5F_ROCKET2" } },
+  { "SILPH_CO_6F",  { "SILPHCO6F_ROCKET1", "SILPHCO6F_SCIENTIST",
+                      "SILPHCO6F_ROCKET2" } },
+  { "SILPH_CO_7F",  { "SILPHCO7F_ROCKET1", "SILPHCO7F_SCIENTIST",
+                      "SILPHCO7F_ROCKET2", "SILPHCO7F_ROCKET3" } },
+  { "SILPH_CO_8F",  { "SILPHCO8F_ROCKET1", "SILPHCO8F_SCIENTIST",
+                      "SILPHCO8F_ROCKET2" } },
+  { "SILPH_CO_9F",  { "SILPHCO9F_ROCKET1", "SILPHCO9F_SCIENTIST",
+                      "SILPHCO9F_ROCKET2" } },
+  { "SILPH_CO_10F", { "SILPHCO10F_ROCKET", "SILPHCO10F_SCIENTIST" } },
+  { "SILPH_CO_11F", { "SILPHCO11F_GIOVANNI", "SILPHCO11F_ROCKET1",
+                      "SILPHCO11F_ROCKET2" } },
+}
+
+-- hide_object writes save.objectToggles, so the single pass at the win
+-- covers floors the player is not standing on; onlyMap is the per-floor
+-- repair path below.
+local function silphRocketsLeave(game, ow, onlyMap)
+  local Commands = require("src.script.Commands")
+  local ctx = { game = game, save = game.save, overworld = ow }
+  for _, floor in ipairs(SILPH_ROCKET_OBJECTS) do
+    if not onlyMap or onlyMap == floor[1] then
+      for _, name in ipairs(floor[2]) do
+        Commands.hide_object(ctx, floor[1], name)
+      end
+    end
+  end
+end
+
 M.SILPH_CO_11F = {
   -- Giovanni's battle is a COORDINATE TRIGGER, not a talk.
   -- SilphCo11FDefaultScript (scripts/SilphCo11F.asm) checks
@@ -692,13 +749,11 @@ M.SILPH_CO_11F = {
     ow:scriptMove(gio, "down", 3, function()
       gio:facePlayer(ow.player)
       ow:engageTrainer(gio, function()
-        -- SilphCo11FTeamRocketLeavesScript: Giovanni leaves the floor
+        -- SilphCo11FTeamRocketLeavesScript: every Silph rocket leaves
         -- after the loss (the street rockets are handled by
         -- M.SAFFRON_CITY.onEnter in story4.lua).
         if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
-          local Commands = require("src.script.Commands")
-          local ctx = { game = game, save = game.save, overworld = ow }
-          Commands.hide_object(ctx, "SILPH_CO_11F", "SILPHCO11F_GIOVANNI")
+          silphRocketsLeave(game, ow)
         end
       end)
     end)
@@ -706,28 +761,46 @@ M.SILPH_CO_11F = {
   end,
   onEnter = function(game, ow)
     if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
-      local Commands = require("src.script.Commands")
-      local ctx = { game = game, save = game.save, overworld = ow }
-      Commands.hide_object(ctx, "SILPH_CO_11F", "SILPHCO11F_GIOVANNI")
+      silphRocketsLeave(game, ow)
     end
   end,
   talk = {
+    -- SilphCo11FSilphPresidentText branches on EVENT_GOT_MASTER_BALL only:
+    -- the teleport pads reach him without passing Giovanni's trigger, and
+    -- afterwards he describes the ball forever.  The old rows fell off the
+    -- end of the script on both branches, so a second talk was silence
+    -- (#392).
     TEXT_SILPHCO11F_SILPH_PRESIDENT = {
       { "face_player" },                                                     -- 1
-      { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },                      -- 2
-      { "jump_if_false", 10 },                                               -- 3
-      { "check_flag", "EVENT_GOT_MASTER_BALL" },                             -- 4
-      { "jump_if_true", 10 },                                                -- 5
-      { "show_text", "_SilphCo11FSilphPresidentText" },                      -- 6
+      { "check_flag", "EVENT_GOT_MASTER_BALL" },                             -- 2
+      { "jump_if_true", 9 },                                                 -- 3
+      { "show_text", "_SilphCo11FSilphPresidentText" },                      -- 4
       -- give-then-print like scripts/SilphCo11F.asm
-      { "give_item", "MASTER_BALL", 1, false },                              -- 7
-      { "show_text", "_SilphCo11FSilphPresidentReceivedMasterBallText" },    -- 8
-      { "set_flag", "EVENT_GOT_MASTER_BALL" },                               -- 9
-      { "jump", 11 },                                                        -- 10
+      { "give_item", "MASTER_BALL", 1, false },                              -- 5
+      { "show_text", "_SilphCo11FSilphPresidentReceivedMasterBallText" },    -- 6
+      { "set_flag", "EVENT_GOT_MASTER_BALL" },                               -- 7
+      { "jump", "end" },                                                     -- 8
+      { "show_text",
+        "_SilphCo11FSilphPresidentMasterBallDescriptionText" },              -- 9
     },
   },
 }
 
+-- Floors 2F-10F carry no other onEnter, so this repairs saves that beat
+-- Giovanni before the hide list existed (same shape as
+-- M.POKEMON_TOWER_7F.onEnter); 11F hides its own inside the table above.
+for _, floor in ipairs(SILPH_ROCKET_OBJECTS) do
+  local mapId = floor[1]
+  if mapId ~= "SILPH_CO_11F" then
+    M[mapId] = M[mapId] or {}
+    M[mapId].onEnter = function(game, ow)
+      if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
+        silphRocketsLeave(game, ow, mapId)
+      end
+    end
+  end
+end
+
 -- -------------------------------------------------------------------
 -- Victory Road boulder switches (scripts/VictoryRoad1F/2F/3F.asm):
 -- a boulder resting on a switch removes a barrier block; the 3F hole

data/scripts/story2.lua

@@ -413,22 +413,141 @@ M.POKEMON_FAN_CLUB = {
   },
 }
 
+-- BikeShopClerkText (scripts/BikeShop.asm) runs three ways: the BICYCLE is
+-- already yours, you are carrying the BIKE VOUCHER, or you get the sales
+-- pitch.  The pitch draws its own window (TextBoxBorder hlcoord 0,0, b=4
+-- c=15) holding BikeShopMenuText and BikeShopMenuPrice, and leaves it up
+-- while the clerk keeps talking in the bottom box: the original never
+-- erases it before TextScriptEnd (#568).
+local BikeShopWindow = {}
+BikeShopWindow.__index = BikeShopWindow
+
+function BikeShopWindow.new(game, footer, onChoose)
+  local self = setmetatable({}, BikeShopWindow)
+  self.game = game
+  self.onChoose = onChoose
+  self.index = 1
+  self.active = true
+  -- BikeShopClerkDoYouLikeItText stays on screen under the window for as
+  -- long as the menu is up.  The text box pushed on top types it out and
+  -- pops itself; this copy of its last page takes over from there, so the
+  -- bottom box never blanks between the pitch and the answer.  Paginated
+  -- with the themed column budget so the copy breaks where the box did.
+  local TextBox = require("src.render.TextBox")
+  local box = require("src.ui.Theme").textBox or {}
+  local pages = TextBox.paginate(TextBox.substitute(game, footer), box.maxCols)
+  self.footer = pages[#pages]
+  return self
+end
+
+function BikeShopWindow:update()
+  -- one answer only: the boxes pushed by onChoose sit on top of this
+  -- state, but a second A on the same frame must not fire it twice
+  if not self.active then return end
+  local input = self.game.input
+  -- HandleMenuInput with wMenuWrappingEnabled clear: the two rows clamp
+  if input:wasPressed("up") then
+    self.index = 1
+  elseif input:wasPressed("down") then
+    self.index = 2
+  elseif input:wasPressed("a") or input:wasPressed("b") then
+    local cancelled = input:wasPressed("b") -- bit B_PAD_B -> .cancel
+    require("src.core.Sound").play(self.game.data, "Press_AB")
+    self.active = false
+    self.onChoose(not cancelled and self.index == 1)
+  end
+end
+
+function BikeShopWindow:draw()
+  local Font = require("src.render.Font")
+  local Strings = require("src.core.Strings")
+  local Theme = require("src.ui.Theme")
+  Font.drawBox(0, 0, 17, 6)
+  love.graphics.setColor(0, 0, 0, 1)
+  local bike = self.game.data.items.BICYCLE
+  Font.draw(bike and bike.name or "BICYCLE", 16, 16)  -- hlcoord 2, 2
+  Font.draw("¥1000000", 64, 24)                       -- hlcoord 8, 3
+  Font.draw(Strings("CANCEL"), 16, 32)                -- `next` skips a row
+  -- wTopMenuItemX 1, wTopMenuItemY 2, rows two apart
+  Font.drawCode(Theme.cursor, 8, self.index == 1 and 16 or 32)
+  if self.footer then
+    -- same geometry TextBox resolves against, so a themed box matches
+    local box = Theme.textBox or {}
+    local tx, ty = box.tx or 0, box.ty or 12
+    love.graphics.setColor(1, 1, 1, 1)
+    Font.drawBox(tx, ty, box.tw or 20, box.th or 6)
+    love.graphics.setColor(0, 0, 0, 1)
+    for i, line in ipairs(self.footer) do
+      Font.draw(line, (tx + 1) * 8, (ty + 2 * i) * 8)
+    end
+  end
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
 M.BIKE_SHOP = {
   talk = {
     TEXT_BIKESHOP_CLERK = function(game, ow, npc, done)
+      local Bag = require("src.inventory.Bag")
+      local Flags = require("src.script.Flags")
       local TextBox = require("src.render.TextBox")
-      if (game.save.inventory.BICYCLE or 0) > 0 then
-        game.stack:push(TextBox.new(game, "How's the\nBICYCLE treating\nyou?", done))
-      elseif (game.save.inventory.BIKE_VOUCHER or 0) > 0 then
-        game.save.inventory.BIKE_VOUCHER = nil
-        game.save.inventory.BICYCLE = 1
-        game.stack:push(TextBox.new(game,
-          ("Oh, that's a\nBIKE VOUCHER!\f%s exchanged\nit for a BICYCLE!")
-          :format(game.save.player.name), done))
-      else
-        game.stack:push(TextBox.new(game,
-          "A BICYCLE costs\n¥1000000. Sorry,\nno instalments!", done))
+      local t = game.data.text
+      local function say(text, after, opts)
+        game.stack:push(TextBox.new(game, text, after, opts))
       end
+
+      -- CheckEvent EVENT_GOT_BICYCLE.  Saves made before the clerk started
+      -- setting the event still have the bike in the bag, so either counts.
+      if (game.save.inventory.BICYCLE or 0) > 0
+          or Flags.get(game.save, "EVENT_GOT_BICYCLE") then
+        say(t._BikeShopClerkHowDoYouLikeYourBicycleText, done)
+        return
+      end
+
+      -- .dontHaveBike: IsItemInBag BIKE_VOUCHER
+      if (game.save.inventory.BIKE_VOUCHER or 0) > 0 then
+        say(t._BikeShopClerkOhThatsAVoucherText, function()
+          -- GiveItem's `jr nc, .BagFull`: the voucher is only spent once
+          -- the BICYCLE is actually in the bag
+          if not Bag.add(game.save, "BICYCLE", 1) then
+            say(t._BikeShopBagFullText, done)
+            return
+          end
+          Bag.remove(game.save, "BIKE_VOUCHER", 1)
+          Flags.set(game.save, "EVENT_GOT_BICYCLE")
+          -- BikeShopExchangedVoucherText carries sound_get_key_item; the
+          -- map runs EnableAutoTextBoxDrawing, so the box still waits for
+          -- a button once the jingle has played (auto.wait, #247)
+          say(t._BikeShopExchangedVoucherText, done, {
+            auto = { wait = true, sound = function()
+              return require("src.core.Sound").play(game.data, "Get_Key_Item")
+            end },
+          })
+        end)
+        return
+      end
+
+      -- .dontHaveVoucher: welcome, then the BICYCLE/CANCEL window
+      say(t._BikeShopClerkWelcomeText, function()
+        local pitch = t._BikeShopClerkDoYouLikeItText
+        game.stack:push(BikeShopWindow.new(game, pitch, function(bought)
+          local function comeAgain()
+            say(t._BikeShopComeAgainText, function()
+              game.stack:pop() -- the window, still up under the text
+              done()
+            end)
+          end
+          if bought then
+            -- a million is out of anyone's reach: BikeShopCantAffordText
+            say(t._BikeShopCantAffordText, comeAgain)
+          else
+            comeAgain()
+          end
+        end))
+        -- PrintText BikeShopClerkDoYouLikeItText, then straight into
+        -- HandleMenuInput: the box types out and hands over without
+        -- waiting, leaving the window's copy of the line on screen
+        say(pitch, nil, { auto = { delay = 0 } })
+      end)
     end,
   },
 }

data/scripts/story3.lua

@@ -111,8 +111,9 @@ M.POKEMON_TOWER_5F = {
 --
 -- PokemonTower6FDefaultScript starts the RESTLESS SOUL battle with NO
 -- Silph Scope check at the trigger -- the scope only decides whether the
--- battle is disguised (IsGhostBattle -> makeGhost: "too scared to move",
--- balls dodged). An earlier version of this port turned the player back
+-- disguise sticks (IsGhostBattle -> makeGhost: "too scared to move", balls
+-- dodged) or comes off in the unveil (makeUnveiledGhost, #492). An earlier
+-- version of this port turned the player back
 -- without the scope and never opened the battle, which made 6F
 -- impassable on any route that skips Rocket Hideout; vanilla lets the
 -- battle open and a POKE_DOLL end it (see wBattleResult below).
@@ -128,7 +129,18 @@ M.POKEMON_TOWER_6F = {
       t._PokemonTower6FBeGoneText or "Be gone...\nIntruders...", function()
       local BattleState = require("src.battle.BattleState")
       local battle = BattleState.newWild(game, "MAROWAK", 30)
-      if not game.save.inventory.SILPH_SCOPE then
+      -- ItemUseBall .notOldManBattle (item_effects.asm:166-175): a ball
+      -- thrown on POKEMON_TOWER_6F at the RESTLESS SOUL is dodged whether
+      -- or not the scope revealed it, so the "can't be caught" state rides
+      -- the battle instead of IsGhostBattle alone (#444)
+      battle.noCatch = true
+      -- InitWildBattle enters disguised for the RESTLESS SOUL either way
+      -- (core.asm:6698-6700).  The scope does not skip the disguise, it
+      -- buys the unveil PrintBeginningBattleText .isMarowak plays over it
+      -- before the battle proceeds as an ordinary wild one (#492).
+      if game.save.inventory.SILPH_SCOPE then
+        battle:makeUnveiledGhost()
+      else
         battle:makeGhost()
       end
       battle.onFinish = function(result)
@@ -182,17 +194,16 @@ M.POKEMON_TOWER_6F = {
 -- preFrames: the shake's lead-in delays -- ShakeElevator's own Delay3s
 -- come to 9 frames; Silph/Rocket's ...ShakeScript prefixes another
 -- Delay3 (12) while CeladonMartElevatorShakeScript farjps straight in
+-- The panel is a bg_event, not a map-entry script: data/maps/objects/
+-- CeladonMartElevator.asm has `bg_event 3, 0, TEXT_CELADONMARTELEVATOR`
+-- and CeladonMartElevatorText is what runs DisplayElevatorFloorMenu, so
+-- the menu waits for the player to face the panel and press A (#395).
+-- Map entry only stores the car's exit warps (CeladonMartElevator
+-- StoreWarpEntriesScript), which is elevatorSeedExit below.
 -- After the ride the original does NOT jump-cut to the floor: choosing a
--- floor in engine/events/elevator.asm DisplayElevatorFloorMenu rewrites
--- the elevator car's own warp entries (wWarpEntries, via .UpdateWarp) to
--- the chosen floor's exit warp, then the player walks out of the car onto
--- that warp themselves (scripts/SilphCoElevator.asm etc.).  Reproduce
--- that here: rewrite the car's exit warps, then drive a short scripted
--- walk-out onto an exit tile and take the (now rewritten) warp, reusing
--- ow:scriptMove / ow:takeWarp (the Oak-escort primitives).
-local WALK_DIRVEC = { up = { 0, -1 }, down = { 0, 1 }, left = { -1, 0 }, right = { 1, 0 } }
-local WALK_OPP = { up = "down", down = "up", left = "right", right = "left" }
-local WALK_ORDER = { "up", "down", "left", "right" }
+-- floor rewrites the elevator car's own warp entries (wWarpEntries, via
+-- .UpdateWarp) to the chosen floor's exit warp and returns control, and
+-- the player walks out of the car onto that warp themselves.
 
 -- .UpdateWarp: point EVERY car exit warp at the same floor's elevator
 -- door (warp id, map id).  Shared generated map data, but the car's
@@ -205,46 +216,6 @@ local function elevatorSetExit(ow, floor)
   end
 end
 
-local function elevatorWalkOut(ow, floor)
-  local m, p = ow.map, ow.player
-  elevatorSetExit(ow, floor)
-  -- leave by the exit tile under the player (they warped in onto one),
-  -- else the nearest
-  local door
-  for _, w in ipairs(m.def.warps) do
-    if w.x == p.cellX and w.y == p.cellY then door = w break end
-  end
-  if not door then
-    local best
-    for _, w in ipairs(m.def.warps) do
-      local d = math.abs(w.x - p.cellX) + math.abs(w.y - p.cellY)
-      if not best or d < best then best, door = d, w end
-    end
-  end
-  -- the car interior sits on the door's walkable side; "out" is the
-  -- doorway direction (the map edge for Silph/Celadon, the top doorway
-  -- for the Rocket car).  Fixed direction order keeps the step
-  -- deterministic when a door tile has several walkable neighbours
-  -- (Silph/Celadon step up into the car, the Rocket car steps down).
-  local into
-  for _, dir in ipairs(WALK_ORDER) do
-    local v = WALK_DIRVEC[dir]
-    local nx, ny = door.x + v[1], door.y + v[2]
-    if m:inBounds(nx, ny) and m:isWalkableCell(nx, ny) then into = dir break end
-  end
-  into = into or "up"
-  local out = WALK_OPP[into]
-  local function leave()
-    ow:takeWarp(door) -- door SFX + warp to the rewritten floor target
-  end
-  -- step one tile into the car, then walk back through the doorway onto
-  -- the exit tile and take the warp: a visible walk-out on valid tiles
-  -- for either door orientation, instead of a jump cut
-  ow:scriptMove(p, into, 1, function()
-    ow:scriptMove(p, out, 1, leave)
-  end)
-end
-
 local function elevatorFloors(elevatorMapId, game)
   local floors = {}
   for mapId, def in pairs(game.data.maps) do
@@ -272,9 +243,9 @@ local function elevatorFloors(elevatorMapId, game)
 end
 
 local function elevatorSeedExit(ow, floors, fromMapId)
-  -- Seed a walk-out destination before the menu (or key-gate text):
-  -- entry floor when known, else the first listed floor (1F).  Choosing
-  -- a floor still rewrites via elevatorWalkOut; B-cancel / no-key leave
+  -- Seed a walk-out destination on entry (before the panel is ever
+  -- read): entry floor when known, else the first listed floor (1F).
+  -- Choosing a floor rewrites it again; B-cancel / no-key leave
   -- keeps this seed so walking out of the car cannot hit a missing ROM
   -- placeholder (#123) or the car's static default floor (#90: Rocket
   -- Hideout defaults to B1F even when entered from B2F/B4F).
@@ -288,68 +259,68 @@ local function elevatorSeedExit(ow, floors, fromMapId)
   return exitFloor
 end
 
-local function elevator(elevatorMapId, keyGate, preFrames)
+local function elevator(elevatorMapId, panelText, keyGate, preFrames)
+  -- the panel bg_event: DisplayElevatorFloorMenu runs from this text
+  -- script, never from map entry (#395)
+  local function panel(game, ow, npc, done)
+    done = done or function() end
+    local floors = elevatorFloors(elevatorMapId, game)
+    -- Rocket Hideout: without LIFT_KEY the panel only prints the need-
+    -- a-key line and shows no floor menu
+    -- (scripts/RocketHideoutElevator.asm).
+    if keyGate and not game.save.inventory[keyGate.item] then
+      local TextBox = require("src.render.TextBox")
+      game.stack:push(TextBox.new(game,
+        game.data.text[keyGate.text] or "It appears to\nneed a key.", done))
+      return
+    end
+    local items = {}
+    for _, f in ipairs(floors) do
+      table.insert(items, { label = f.token, value = f })
+    end
+    local ListMenu = require("src.ui.ListMenu")
+    game.stack:push(ListMenu.new(game, "WHICH FLOOR?", items, {
+      onChoose = function(item, list)
+        list:close()
+        -- the whole ShakeElevator ride runs in place -- music stop, 100
+        -- collision-thud scroll bounces, the PA chime -- and only then
+        -- does .UpdateWarp's rewrite land, with the player still stood
+        -- at the panel: they walk out to the car door themselves
+        local ElevatorShake = require("src.world.ElevatorShake")
+        game.stack:push(ElevatorShake.new(game, ow, {
+          preFrames = preFrames,
+          onDone = function()
+            elevatorSetExit(ow, item.value)
+            done()
+          end,
+        }))
+      end,
+      onCancel = function()
+        -- DisplayElevatorFloorMenu: `ret c` on B -- no warp, nothing
+        -- happens, the player just stays in the car (exit warps were
+        -- already seeded on entry)
+        done()
+      end,
+    }))
+  end
   return {
     -- fromMapId: the floor the player just left (setMap passes it), so a
     -- B-cancel can still walk out onto a real map.  Silph's ROM car warps
     -- default to UNUSED_MAP_ED, which is not in Data.maps -- Warp.resolve
     -- asserted and hard-crashed (#123).
     onEnter = function(game, ow, fromMapId)
-      local floors = elevatorFloors(elevatorMapId, game)
-      elevatorSeedExit(ow, floors, fromMapId)
-      -- Rocket Hideout: without LIFT_KEY the panel only prints the need-
-      -- a-key line (scripts/RocketHideoutElevator.asm).  Exit warps are
-      -- still seeded above so walking out returns to the entry floor
-      -- instead of the car's ROM default (B1F) -- #90 / #105.
-      if keyGate and not game.save.inventory[keyGate.item] then
-        local TextBox = require("src.render.TextBox")
-        game.stack:push(TextBox.new(game,
-          game.data.text[keyGate.text] or "It appears to\nneed a key."))
-        return
-      end
-      local items = {}
-      for _, f in ipairs(floors) do
-        table.insert(items, { label = f.token, value = f })
-      end
-      local ListMenu = require("src.ui.ListMenu")
-      game.stack:push(ListMenu.new(game, "WHICH FLOOR?", items, {
-        onChoose = function(item, list)
-          list:close()
-          -- the map-entry Transition (startWarpTo) calls onEnter from
-          -- its OWN midpoint callback, so this menu was pushed on top
-          -- of that still-active Transition; only the top state
-          -- updates, so it froze mid-fade instead of finishing.  Left
-          -- alone it would resurface after the ride and play a stray
-          -- fade at the wrong time -- pop it now, before it can happen.
-          local Transition = require("src.render.Transition")
-          if getmetatable(game.stack:top()) == Transition then
-            game.stack:pop()
-          end
-          -- the whole ShakeElevator ride runs in place -- music stop,
-          -- 100 collision-thud scroll bounces, the PA chime -- and only
-          -- then does the player walk out of the car onto the chosen
-          -- floor (elevatorWalkOut rewrites the car's exit warps first)
-          local ElevatorShake = require("src.world.ElevatorShake")
-          game.stack:push(ElevatorShake.new(game, ow, {
-            preFrames = preFrames,
-            onDone = function()
-              elevatorWalkOut(ow, item.value)
-            end,
-          }))
-        end,
-        onCancel = function()
-          -- DisplayElevatorFloorMenu: `ret c` on B -- no warp, nothing
-          -- happens, the player just stays in the car (exit warps were
-          -- already seeded to the entry floor above)
-        end,
-      }))
+      elevatorSeedExit(ow, elevatorFloors(elevatorMapId, game), fromMapId)
     end,
+    talk = { [panelText] = panel },
   }
 end
 
-M.SILPH_CO_ELEVATOR = elevator("SILPH_CO_ELEVATOR")
-M.CELADON_MART_ELEVATOR = elevator("CELADON_MART_ELEVATOR", nil, 9)
+M.SILPH_CO_ELEVATOR = elevator("SILPH_CO_ELEVATOR",
+  "TEXT_SILPHCOELEVATOR_ELEVATOR")
+M.CELADON_MART_ELEVATOR = elevator("CELADON_MART_ELEVATOR",
+  "TEXT_CELADONMARTELEVATOR", nil, 9)
 M.ROCKET_HIDEOUT_ELEVATOR = elevator("ROCKET_HIDEOUT_ELEVATOR",
+  "TEXT_ROCKETHIDEOUTELEVATOR",
   { item = "LIFT_KEY", text = "_RocketHideoutElevatorAppearsToNeedKeyText" })
 
 -- -------------------------------------------------------------------
@@ -389,6 +360,38 @@ M.ROCKET_HIDEOUT_B4F = {
         end))
     end,
 
+    -- Yellow swaps Rocket1/Rocket2 for Jessie & James and keeps a single
+    -- grunt, spelled ROCKETHIDEOUTB4F_ROCKET / TEXT_ROCKETHIDEOUTB4F_ROCKET
+    -- (pokeyellow/scripts/RocketHideoutB4F.asm), so the Red/Blue key above
+    -- never matched there and the LIFT KEY never dropped (#552, a
+    -- regression of #105).  Yellow also moves the drop off the second
+    -- talk: RocketHideoutB4FRocketEndBattleText is text_promptbutton +
+    -- text_asm, so its SetEvent EVENT_ROCKET_DROPPED_LIFT_KEY / ShowObject
+    -- TOGGLE_ROCKET_HIDEOUT_B4F_ITEM_5 run the instant the battle ends.
+    TEXT_ROCKETHIDEOUTB4F_ROCKET = function(game, ow, npc, done)
+      if not ow:trainerDefeated(npc) then
+        ow:engageTrainer(npc, function()
+          -- engageTrainer records the win before it calls back, so this
+          -- is the end-battle text's SetEvent + ShowObject
+          if ow:trainerDefeated(npc)
+             and not game.save.flags.EVENT_ROCKET_DROPPED_LIFT_KEY then
+            game.save.flags.EVENT_ROCKET_DROPPED_LIFT_KEY = true
+            local Commands = require("src.script.Commands")
+            Commands.show_object(
+              { game = game, save = game.save, overworld = ow },
+              "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_LIFT_KEY")
+          end
+          done()
+        end)
+        return
+      end
+      -- RocketHideoutB4FRocketAfterBattleText: later talks only reprint
+      local TextBox = require("src.render.TextBox")
+      game.stack:push(TextBox.new(game,
+        game.data.text._RocketHideoutB4FRocketAfterBattleText
+        or "Oh no! I dropped\nthe LIFT KEY!", done))
+    end,
+
     TEXT_ROCKETHIDEOUTB4F_GIOVANNI = function(game, ow, npc, done)
       -- Giovanni has no trainer-header row (def_trainers 2); his text_asm
       -- owns both the engage and the BeatGiovanniScript aftermath.
@@ -538,45 +541,56 @@ M.GAME_CORNER = {
           end))
       end)
     end,
+    -- GameCornerClerk1Text (scripts/GameCorner.asm): the offer, a
+    -- YesNoChoice, then ¥1000 for 50 coins.  Yellow drops the "1" from the
+    -- object const and from every one of his text labels
+    -- (GameCornerClerkText, pokeyellow/scripts/GameCorner.asm) with an
+    -- identical body, so each line resolves under both spellings and the
+    -- handler is bound to both text ids just below (#552).
     TEXT_GAMECORNER_CLERK1 = function(game, ow, npc, done)
       local TextBox = require("src.render.TextBox")
       local ChoiceBox = require("src.ui.ChoiceBox")
       local t = game.data.text
+      local function line(suffix, fallback)
+        return t["_GameCornerClerk1" .. suffix]
+               or t["_GameCornerClerk" .. suffix]
+               or fallback
+      end
       game.stack:push(TextBox.new(game,
-        (t._GameCornerClerk1DoYouNeedSomeGameCoinsText
-         or "Do you need some\ngame coins?\f¥1000 for 50."), function()
+        line("DoYouNeedSomeGameCoinsText",
+             "Do you need some\ngame coins?\f¥1000 for 50."), function()
         game.stack:push(ChoiceBox.new(game, function(yes)
           if not yes then
             game.stack:push(TextBox.new(game,
-              t._GameCornerClerk1PleaseComePlaySometimeText
-              or "No? Please come\nplay sometime!", done))
+              line("PleaseComePlaySometimeText",
+                   "No? Please come\nplay sometime!"), done))
             return
           end
           -- scripts/GameCorner.asm GameCornerClerk1Text: coins need
           -- the COIN CASE and room for at least 9 coins (Has9990Coins)
           if not game.save.inventory.COIN_CASE then
             game.stack:push(TextBox.new(game,
-              t._GameCornerClerk1DontHaveCoinCaseText
-              or "You don't have a\nCOIN CASE!", done))
+              line("DontHaveCoinCaseText",
+                   "You don't have a\nCOIN CASE!"), done))
             return
           end
           if (game.save.coins or 0) >= 9990 then
             game.stack:push(TextBox.new(game,
-              t._GameCornerClerk1CoinCaseIsFullText
-              or "Oops! Your COIN\nCASE is full.", done))
+              line("CoinCaseIsFullText",
+                   "Oops! Your COIN\nCASE is full."), done))
             return
           end
           if game.save.money < 1000 then
             game.stack:push(TextBox.new(game,
-              t._GameCornerClerk1CantAffordTheCoinsText
-              or "You can't afford\nthe coins!", done))
+              line("CantAffordTheCoinsText",
+                   "You can't afford\nthe coins!"), done))
             return
           end
           game.save.money = game.save.money - 1000
           game.save.coins = math.min(9999, (game.save.coins or 0) + 50)
           game.stack:push(TextBox.new(game,
-            (t._GameCornerClerk1ThanksHereAre50CoinsText
-             or "Thanks! Here are\nyour 50 coins!")
+            line("ThanksHereAre50CoinsText",
+                 "Thanks! Here are\nyour 50 coins!")
             .. ("\fCOINS: %d"):format(game.save.coins), done))
         end))
       end))
@@ -584,6 +598,13 @@ M.GAME_CORNER = {
   },
 }
 
+-- Yellow's coin clerk is GAMECORNER_CLERK / TEXT_GAMECORNER_CLERK where Red
+-- and Blue spell him CLERK1, and the two text_asm bodies are identical, so
+-- one handler answers both ids.  Without the alias the Yellow clerk fell
+-- through to his extracted offer line with no yes/no box behind it (#552).
+M.GAME_CORNER.talk.TEXT_GAMECORNER_CLERK =
+  M.GAME_CORNER.talk.TEXT_GAMECORNER_CLERK1
+
 -- Game Corner prize lists (data/events/prizes.asm, prize_mon_levels.asm).
 -- The six mon prizes differ between Red and Blue; the three TM prizes are
 -- identical, so they are shared and appended to each version's mon list.
@@ -695,6 +716,16 @@ local DOCK_SHIP_BLOCKS = {
   { bx = 7, by = 2, water = 13 }, { bx = 8, by = 2, water = 13 },
 }
 
+-- her four hull columns bow-to-stern (upper-half / lower-half block ids)
+-- and the open-water ids of the rows she sits in
+local DOCK_SHIP_COLUMNS = {
+  { bx = 5, top = 4, bottom = 8 },
+  { bx = 6, top = 5, bottom = 9 },
+  { bx = 7, top = 6, bottom = 10 },
+  { bx = 8, top = 7, bottom = 11 },
+}
+local DOCK_WATER_TOP, DOCK_WATER_BOTTOM = 1, 13
+
 M.VERMILION_DOCK = {
   onEnter = function(game, ow)
     local Flags = require("src.script.Flags")
@@ -729,17 +760,39 @@ M.VERMILION_DOCK = {
         ow:startDustAnim(cx, 1, function() puff(n - 1, cx + 2) end)
       end
       puff(3, 15)
+      -- VermilionDock_EraseSSAnne deliberately leaves the blocks under the
+      -- player alone ("south of the player and won't be redrawn"), so skip
+      -- his own block: he must not spend the walk-out standing on water
+      local pbx = math.floor(ow.player.cellX / 2)
+      local pby = math.floor(ow.player.cellY / 2)
       local rows = {}
-      rows[#rows + 1] = { "wait", 100 }
-      rows[#rows + 1] = { "play_sound", "SS_Anne_Horn" }
-      for _, b in ipairs(DOCK_SHIP_BLOCKS) do
-        rows[#rows + 1] = { "replace_block", b.bx, b.by, b.water }
+      local function setBlock(bx, by, block)
+        if bx < 1 or bx > 8 then return end
+        if bx == pbx and by == pby then return end
+        rows[#rows + 1] = { "replace_block", bx, by, block }
       end
-      rows[#rows + 1] = { "wait", 30 }
+      rows[#rows + 1] = { "wait", 120 }
+      rows[#rows + 1] = { "play_sound", "SS_Anne_Horn" }
+      -- .shift_columns_up slides her tile columns west behind a mid-frame
+      -- rSCX split; with no split scroll here she sails one block per beat
+      -- and the water closes in astern (#360)
+      for step = 1, 8 do
+        for _, col in ipairs(DOCK_SHIP_COLUMNS) do
+          setBlock(col.bx - step, 1, col.top)
+          setBlock(col.bx - step, 2, col.bottom)
+        end
+        setBlock(9 - step, 1, DOCK_WATER_TOP)
+        setBlock(9 - step, 2, DOCK_WATER_BOTTOM)
+        rows[#rows + 1] = { "wait", 20 }
+      end
+      -- the second horn as she clears the dock, then EraseSSAnne's 120
+      -- frames before the walk out
+      rows[#rows + 1] = { "play_sound", "SS_Anne_Horn" }
+      rows[#rows + 1] = { "wait", 120 }
       rows[#rows + 1] = { "move_player", "up", 2 }
-      -- keep Music_Surfing across the city warp (pokered stays on it
-      -- through the exit-ship walk)
-      rows[#rows + 1] = { "play_music", "Music_Surfing", { keep = true } }
+      -- no keepMusic on this warp: Music_Surfing belongs to the dock's
+      -- cutscene, and VERMILION_CITY's own theme has to take over as the
+      -- player crosses in (EnterMap's PlayDefaultMusic)
       rows[#rows + 1] = { "warp", "VERMILION_CITY", 18, 31, "up" }
       rows[#rows + 1] = { "move_player", "up", 2 }
       ow:queueScript(rows)

data/scripts/story4.lua

@@ -171,6 +171,28 @@ local function dojoBall(species, ownBall, otherBall, askKey)
   end
 end
 
+-- FightingDojoDefaultScript does not use the Master's facing direction for
+-- this battle.  It checks exactly the cell left of him, turns both sprites
+-- toward one another, and then displays his trainer text.  Keeping this out
+-- of trainer sight also lets him keep his original downward-facing pose.
+local function dojoMasterGate(game, ow, x, y)
+  if x ~= 4 or y ~= 3 or game.save.flags.EVENT_BEAT_KARATE_MASTER then
+    return false
+  end
+  local master
+  for _, npc in ipairs(ow.npcs) do
+    if npc.def and npc.def.name == "FIGHTINGDOJO_KARATE_MASTER" then
+      master = npc
+      break
+    end
+  end
+  if not master or ow:trainerDefeated(master) then return false end
+  ow.player.facing = "right"
+  master:facePlayer(ow.player)
+  ow:engageTrainer(master)
+  return true
+end
+
 M.FIGHTING_DOJO = {
   talk = {
     TEXT_FIGHTINGDOJO_HITMONLEE_POKE_BALL =
@@ -197,6 +219,7 @@ M.FIGHTING_DOJO = {
     end
     return false
   end,
+  onStep = dojoMasterGate,
 }
 
 -- -------------------------------------------------------------------

data/scripts/story5.lua

@@ -135,6 +135,9 @@ M.SILPH_CO_2F = {
   talk = {
     TEXT_SILPHCO2F_SILPH_WORKER_F = gift({
       flag = "EVENT_GOT_TM36", item = "TM_SELFDESTRUCT",
+      -- the label carries no leading underscore: pokered keeps this one in
+      -- the script bank, not the far-text bank (#393)
+      pre = "SilphCo2FSilphWorkerFPleaseTakeThisText",
       received = "_SilphCo2FSilphWorkerFReceivedTM36Text",
       explain = "_SilphCo2FSilphWorkerFTM36ExplanationText",
       noRoom = "_SilphCo2FSilphWorkerFTM36NoRoomText",
@@ -787,8 +790,19 @@ local function bikeGateGuard(coords, stopText, explainText)
     local t = text(game)
     push(game, t[stopText] or "Hey! Wait up!", function()
       push(game, t[explainText] or "You need a\nBICYCLE for\nCYCLING ROAD!", function()
+        -- pokered's Route16Gate1FGuardScript / Route18Gate1FGuardScript
+        -- (scripts/Route16Gate1F.asm, Route18Gate1F.asm) simulate one
+        -- PAD_RIGHT step after the refusal text, and only clear
+        -- wJoyIgnore / hand control back once that step finishes
+        -- (PlayerMovingRightScript). Without it the player was left
+        -- parked beside the guard's counter with no way past. #518
+        local function shoveRight()
+          ow:scriptMove(ow.player, "right", 1)
+        end
         if dist > 0 then
-          ow:scriptMove(ow.player, "up", dist)
+          ow:scriptMove(ow.player, "up", dist, shoveRight)
+        else
+          shoveRight()
         end
       end)
     end)
@@ -836,6 +850,19 @@ M.SILPH_CO_7F = {
   end,
 }
 
+-- SSAnne2FRivalAfterBattleScript's exit walk is keyed on the player's X,
+-- not on where the rival stopped: from (37,8) the rival stands below him on
+-- (36,8) and takes .RivalDownFourMovement straight down out of the room;
+-- from (36,8) he stands above him on (36,7) and takes
+-- .RivalWalkAroundPlayerMovement, which steps RIGHT and then falls through
+-- into the same four DOWNs, so five downs in all (#360).
+local function ssAnne2FRivalExitDirs(onLeft)
+  if onLeft then
+    return { "right", "down", "down", "down", "down", "down" }
+  end
+  return { "down", "down", "down", "down" }
+end
+
 -- S.S. Anne 2F rival ambush (scripts/SSAnne2F.asm; coords 36/37,8)
 M.SS_ANNE_2F = {
   onStep = function(game, ow, x, y)
@@ -848,11 +875,12 @@ M.SS_ANNE_2F = {
       { "face_object", 2, onLeft and "down" or "right" },      -- 3
       { "show_text", "_SSAnne2FRivalText" },                   -- 4
       { "rival_battle", "OPP_RIVAL2", 1 },                     -- 5
-      { "jump_if_false", 10 },                                 -- 6
+      { "jump_if_false", 11 },                                 -- 6
       { "set_flag", "EVENT_BEAT_SS_ANNE_RIVAL" },              -- 7
       { "show_text", "_SSAnne2FRivalDefeatedText" },           -- 8
-      { "move_npc_to", 2, 36, 4 },                             -- 9
-      { "hide_object", "SS_ANNE_2F", "SSANNE2F_RIVAL" },       -- 10
+      { "show_text", "_SSAnne2FRivalCutMasterText" },          -- 9
+      { "walk_npc", 2, ssAnne2FRivalExitDirs(onLeft) },        -- 10
+      { "hide_object", "SS_ANNE_2F", "SSANNE2F_RIVAL" },       -- 11
     }, onLeft and "up" or "left")
   end,
 }

data/scripts/yellow_gifts.lua

@@ -23,10 +23,15 @@ M.CERULEAN_MELANIES_HOUSE = {
         rows[#rows + 1] = { "jump_if_false", "declined" }
         rows[#rows + 1] = { "give_pokemon", "BULBASAUR", 10 }
         rows[#rows + 1] = { "jump_if_false", "end" } -- party + box full
-        rows[#rows + 1] = { "show_text", "MelanieText3" }
+        -- Event and HideObject before MelanieText3: give_pokemon's nickname
+        -- prompt and the received text both yield, and a script that dies
+        -- in that window used to leave the BULBASAUR given with the event
+        -- clear, so Melanie offered a second one (#426).  The flag is only
+        -- read at script entry, so the order is invisible in play.
+        rows[#rows + 1] = { "set_flag", "EVENT_GOT_BULBASAUR_IN_CERULEAN" }
         rows[#rows + 1] = { "hide_object", "CERULEAN_MELANIES_HOUSE",
                             "CERULEANMELANIESHOUSE_BULBASAUR" }
-        rows[#rows + 1] = { "set_flag", "EVENT_GOT_BULBASAUR_IN_CERULEAN" }
+        rows[#rows + 1] = { "show_text", "MelanieText3" }
         rows[#rows + 1] = { "jump", "end" }
         rows[#rows + 1] = { "label", "declined" }
         rows[#rows + 1] = { "show_text", "MelanieText5" }
@@ -60,8 +65,13 @@ M.ROUTE_24 = {
       { "jump_if_false", "declined" },
       { "give_pokemon", "CHARMANDER", 10 },
       { "jump_if_false", "end" },
-      { "show_text", "_Route24DamianText2" },
+      -- SetEvent hoisted ahead of the received text (Route24.asm writes it
+      -- after Route24Text_515e3, where nothing in between can fail): the
+      -- nickname prompt and the text both yield, and a script death in that
+      -- window left the CHARMANDER given with EVENT_54F clear, so Damian
+      -- handed out a second one on the next talk (#426).
       { "set_flag", "EVENT_54F" },
+      { "show_text", "_Route24DamianText2" },
       { "jump", "end" },
       { "label", "declined" },
       { "show_text", "_Route24DamianText3" },
@@ -87,9 +97,10 @@ M.VERMILION_CITY = {
         rows[#rows + 1] = { "jump_if_false", "declined" }
         rows[#rows + 1] = { "give_pokemon", "SQUIRTLE", 10 }
         rows[#rows + 1] = { "jump_if_false", "end" }
-        rows[#rows + 1] = { "show_text", "_OfficerJennyText3" }
+        -- event before the received text, as above (#426)
         rows[#rows + 1] = { "set_flag",
                             "EVENT_GOT_SQUIRTLE_FROM_OFFICER_JENNY" }
+        rows[#rows + 1] = { "show_text", "_OfficerJennyText3" }
         rows[#rows + 1] = { "jump", "end" }
         rows[#rows + 1] = { "label", "declined" }
         rows[#rows + 1] = { "show_text", "_OfficerJennyText4" }

data/scripts/yellow_jessie_james.lua

@@ -48,7 +48,19 @@ M.MT_MOON_B2F = {
       { "show_object", "MT_MOON_B2F", "MTMOONB2F_JESSIE" },
       { "show_object", "MT_MOON_B2F", "MTMOONB2F_JAMES" },
       { "show_text", "_MtMoonJessieJamesText1" },
-      { "face_player_dir", "right" },
+      { "face_player_dir", "up" },
+      { "emote", "player", "shock", 30 },
+      -- MtMoonB2FScript_49e15 simulates PAD_UP for one player step, then
+      -- Script6/Script9 walk Jessie (object 2, MovementData_f9e65: six
+      -- $06) and James (object 6, f9e66: five $06); both objects' movement
+      -- byte 2 is LEFT, so .determineDirection makes those LEFT steps --
+      -- Jessie (9,3)->(3,3) above the player at (3,4), James (9,4)->(4,4)
+      -- beside him. #423
+      { "walk_npc", "player", { "up" } },
+      { "walk_npc", 2, { "left", "left", "left", "left", "left", "left" } },
+      { "face_object", 2, "down" },
+      { "walk_npc", 6, { "left", "left", "left", "left", "left" } },
+      { "face_object", 6, "left" },
       { "show_text", "_MtMoonJessieJamesText2" },
       { "start_battle", "trainer", "OPP_ROCKET", 42 },
       { "check_battle_result", "win" },
@@ -57,8 +69,10 @@ M.MT_MOON_B2F = {
       { "show_text", "_MtMoonJessieJamesText4" },
       { "stop_music" },
       { "play_music", "Music_MeetJessieJames" },
+      { "fade", "out" },
       { "hide_object", "MT_MOON_B2F", "MTMOONB2F_JESSIE" },
       { "hide_object", "MT_MOON_B2F", "MTMOONB2F_JAMES" },
+      { "fade", "in" },
       { "play_default_music" },
       { "set_flag", "EVENT_BEAT_MT_MOON_3_JESSIE_JAMES" },
     }, {})

docs/anbernic-rg34xxsp.md

@@ -65,6 +65,13 @@ display option — COLORS, TILT, ZOOM, VOID FILL, MAX FPS — works normally. If
 your device turns out to handle the pass, launch with `POKEPORT_GBCFX=1` to
 put the row back.
 
+**PERFORMANCE defaults to LOW here.** The OPTIONS → PERFORMANCE tier defaults
+to AUTO, which reads this device as an ARM Linux handheld and resolves to
+**LOW**: the 3D tilt and survey zoom stay off and the frame rate is capped,
+so the overworld runs smoothly on the H700 out of the box. Bump it to
+BALANCED or HIGH from OPTIONS if you want the extras and your device keeps
+up; see [Performance tier](new-features.md#performance-tier-low-end-devices).
+
 The pack bundles the LÖVE 11.5 aarch64 runtime from
 [PortMaster](https://portmaster.games/), so the device does not need a
 separate `love_11.5` runtime download on first launch. The launcher resolves

docs/gameboy-hardware-limitations.md

@@ -12,7 +12,7 @@ this port.
 
 | # | Mechanic | Value | Why the Game Boy had this limit | Where it lives here |
 |---|---|---|---|---|
-| 1 | Bag capacity | 20 item slots | `wNumBagItems` save block was a fixed 20-entry id/quantity array in SRAM | `src/inventory/Bag.lua:8` (`Bag.CAPACITY = 20`) |
+| 1 | Bag capacity | 20 item slots by default | `wNumBagItems` save block was a fixed 20-entry id/quantity array in SRAM | `Data.constants.bagSize`, read by `src/inventory/Bag.lua` (`Bag.capacity`) |
 | 2 | Party size | 6 Pokémon | `wPartyMon1..6` were 6 fixed save-RAM slots | `src/pokemon/Party.lua:5` (`Party.MAX = 6`) |
 | 3 | PC storage | 12 boxes × 20 Pokémon | `wBoxDataStart` / Bill's PC allocated a fixed 12×20 SRAM block | `src/pokemon/Boxes.lua:7-8` |
 | 4 | Moves per Pokémon | 4 | Fixed 4-move-slot field in the party/box Pokémon struct | `src/pokemon/Pokemon.lua:20`, enforced again in `src/battle/BattleState.lua:1941` |
@@ -38,6 +38,10 @@ this port.
 
 ## Notes
 
+- Mods may patch `constants.bagSize` through the public content registry. The
+  native `save.lua` format keeps every existing item when the configured
+  limit changes; exporting to a cartridge `.sav` still writes only the first
+  20 bag slots because the original SRAM layout has no room for more.
 - PC Box **overflow handling** was deliberately changed even though the
   20×12 box *shape* was kept faithful: instead of Gen 1's "full box discards
   or blocks the deposit," this port spills into the next box with room.

docs/ios-install.md

@@ -0,0 +1,116 @@
+# Build & install on your iPhone — step by step
+
+Don't want to install Xcode? Download the release IPA and sideload it with
+AltStore instead — see [ios-sideload.md](ios-sideload.md).
+
+This guide assumes **zero** programming experience. Follow it top to
+bottom and you'll have the game running on your own iPhone in roughly an
+hour (most of it is waiting for downloads).
+
+## What you need
+
+- A **Mac** (any Apple-silicon or recent Intel Mac on macOS 14 or newer)
+- An **iPhone** and its **charging cable**
+- A free **Apple ID** (the same account you use for the App Store)
+- Your **own, legally obtained** Pokémon Red or Blue ROM file (a 1 MB
+  `.gb` file). This project ships no game data — the app rebuilds
+  everything from *your* cartridge dump and verifies it before use.
+- About **15 GB free disk space** (Xcode is enormous; the game itself is
+  tiny)
+
+> **Free vs. paid Apple account:** a free Apple ID works. The only catch:
+> apps signed with a free account stop launching after **7 days** — just
+> re-run the install command (step 5) to re-sign; your save data is kept.
+> A paid Apple Developer account ($99/yr) extends that to a year.
+
+---
+
+## Step 1 — Install Xcode (once)
+
+1. On the Mac, open the **App Store**, search **Xcode**, click **Get**.
+   It's a ~10 GB download — go make tea.
+2. Open Xcode once. Accept the license. If it offers to install extra
+   components or the **iOS platform**, say yes and let it finish.
+
+## Step 2 — Sign Xcode into your Apple ID (once)
+
+1. In Xcode's menu bar: **Xcode → Settings → Accounts**.
+2. Click the **+** in the bottom-left → **Apple Account** → sign in.
+3. Close the window. (This quietly creates the "signing certificate" the
+   build uses — you never have to touch it again.)
+
+## Step 3 — Get this project onto the Mac
+
+If you received it as a folder, put it somewhere easy like your home
+folder. If it's on GitHub, click the green **Code** button → **Download
+ZIP**, then double-click the zip to unpack it.
+
+## Step 4 — Build it (one command)
+
+1. Open the **Terminal** app (press ⌘-space, type `terminal`, press
+   return).
+2. Type `cd ` (c, d, space — don't press return yet), then **drag the
+   project folder** from Finder onto the Terminal window — it fills in
+   the path — and press **return**.
+3. Paste this and press return:
+
+   ```sh
+   scripts/build_ios.sh --fetch
+   ```
+
+   The first run downloads the LÖVE engine and compiles everything
+   (5–15 minutes). Lines of build output scrolling by is normal. You're
+   done when you see **`==> done`**.
+
+## Step 5 — Put it on your iPhone
+
+1. Plug the iPhone into the Mac with the cable. **Unlock it** and keep it
+   unlocked. If it asks **"Trust This Computer?" → Trust**.
+2. Paste this and press return:
+
+   ```sh
+   scripts/build_ios.sh --device --install
+   ```
+
+   The script finds your signing identity and your phone by itself. If it
+   complains, it tells you exactly what to fix (usually: the phone was
+   locked — unlock and re-run).
+
+3. First time only, the iPhone will want two approvals:
+   - **Developer Mode**: Settings → **Privacy & Security** → scroll to
+     **Developer Mode** → turn on → restart the phone → confirm.
+   - **Trust the developer**: Settings → **General** → **VPN & Device
+     Management** → tap the entry under *Developer App* → **Trust**.
+
+   Then re-run the command in step 5.2 if the install had failed.
+
+## Step 6 — Give it your ROM and play
+
+1. Get your `.gb` file onto the phone — AirDrop it to yourself, or save
+   it in iCloud Drive / Files.
+2. Open the app. On the **RED** tab, tap **Import ROM** and pick your
+   `.gb` file in the file browser that appears. (Alternative: in the
+   **Files** app, drop the `.gb` into **On My iPhone → the game's
+   folder** and just reopen the app — it imports automatically.)
+3. Import takes ~10 seconds, the button turns into **Play Red** — tap it.
+
+## Optional goodies
+
+- **Mods**: launcher → **MODS** tab → **Import mod .zip**.
+- **Save import/export**: buttons on each game's tab, using the normal
+  iOS file picker.
+
+## When things go wrong
+
+| Symptom | Fix |
+|---|---|
+| `xcodebuild not found` | Xcode isn't installed or wasn't opened once — do Step 1 |
+| `no Apple signing identity found` | Do Step 2, then re-run |
+| `no iPhone/iPad found` | Cable in? Phone unlocked? Tapped "Trust"? |
+| Install fails with "locked" | Unlock the phone, keep it unlocked, re-run |
+| App icon appears then won't open | Do the two approvals in Step 5.3 |
+| App stops launching after a week | Free-account 7-day limit — re-run Step 5.2 |
+| "That ROM could not be imported" | The file isn't a canonical 1 MB US Red/Blue dump — the importer checks its fingerprint |
+
+Every build/install command is safe to re-run; your saves live on the
+phone and survive reinstalls.

docs/ios-sideload.md

@@ -0,0 +1,48 @@
+# Sideload the iOS build with AltStore
+
+Every GitHub Release ships an IPA (`gen1recomp-*-ios.ipa`). Install it on
+your iPhone or iPad with [AltStore Classic](https://altstore.io/) — AltStore
+re-signs the app with **your** free Apple ID so you do not need a Mac or
+Xcode.
+
+## 1. Install AltStore
+
+Follow the official guide for your computer:
+
+- [How to Install (Windows)](https://faq.altstore.io/altstore-classic/how-to-install-altstore-windows)
+- [How to Install (macOS)](https://faq.altstore.io/altstore-classic/how-to-install-altstore-macos)
+
+You will install **AltServer** on the computer, then use it to put AltStore
+on the phone. What AltServer is and why it needs to stay running:
+
+- [AltServer](https://faq.altstore.io/altstore-classic/altserver)
+
+Stuck? Start here:
+
+- [Troubleshooting Guide](https://faq.altstore.io/altstore-classic/troubleshooting-guide)
+
+## 2. Install the game
+
+1. Download `gen1recomp-*-ios.ipa` from
+   [Releases](https://github.com/bryanthaboi/gen1recomp/releases).
+2. Open **AltStore** on the phone (AltServer must be running on the same
+   Wi‑Fi, or keep the phone plugged into the computer).
+3. Tap **My Apps → +** (or share the IPA into AltStore) and pick the file.
+4. Sign in with your Apple ID when prompted. Wait for the install to finish.
+5. On first launch: Settings → **Privacy & Security → Developer Mode** (iOS
+   16+), and Settings → **General → VPN & Device Management** → Trust your
+   Apple ID if asked.
+
+Then open the app, import your own legal `.gb` ROM on the Red/Blue tab, and
+play.
+
+## Refresh / 7-day limit
+
+With a free Apple ID, sideloaded apps stop launching after **7 days**. Keep
+AltServer running so AltStore can refresh them, or open AltStore and refresh
+manually before they expire. Saves on the phone are kept across refreshes.
+
+## Prefer building it yourself?
+
+Building from source on a Mac (no AltStore) is covered in
+[ios-install.md](ios-install.md).

docs/modding.md

@@ -167,5 +167,38 @@ The console understands these verbs (anything else is evaluated as Lua):
 - `trace PAT | trace off` — trace events/hooks matching a glob pattern.
 - `help` — list the verbs.
 
+## Tool input and title-menu hooks
+
+Tool mods that need to act once per game logic tick can wrap `input.step`.
+It runs immediately before queued button edges are promoted, so input added by
+the wrapper is visible during that same fixed step. The callback receives
+`(next, game, dt)` and must call `next(game, dt)`.
+
+`ui.title_menu.items` receives `(next, game, items)` and follows the same
+decorate-after-`next` convention as `ui.start_menu.items`. It is the safe place
+for a tool to offer a fresh-session action before gameplay begins.
+
+Ephemeral tools can wrap `save.write(next, game)` and return `false` to veto a
+progress write before world state is captured or any bytes reach disk.
+
+`render.hud` receives `(next, game, viewport)` after the finished game frame is
+composited and before touch controls draw. The window-space viewport contains
+`width`, `height`, `gameX`, `gameY`, `gameWidth`, `gameHeight`, `scale`, `dpiX`,
+and `dpiY`, so a tool can use the letterbox margins without drawing over the
+playfield or pushing an updating game state.
+
+`render.compose` wraps the whole-window composite in `Renderer:endFrame`. It
+receives `(next, renderer, ctx)`; returning `true` without calling `next` hands
+the mod full control of the window, while calling `next` runs the engine's
+normal single-window composite so the mod can decorate around it. `ctx` carries
+the finished `worldCanvas` and `uiCanvas` with their SGB `zones` / `worldZones`,
+`worldActive`, the frame metrics (`ww`, `wh`, `pw`, `ph`, `ox`, `oy`, `vpw`,
+`vph`, `scale`, `Sx`, `Sy`, `dpiX`, `dpiY`), `renderer:blitCanvas(...)` for a
+palette-correct blit of either canvas into an arbitrary screen rect, and the
+`secondScreen` bridge (`available()` / `push(imageData, w, h)` / `setEnabled`)
+for driving a second physical display. This is what lets a mod lay the two
+passes out as two stacked Game Boy screens, or push one onto a second screen,
+without the engine knowing the layout.
+
 Developer mode also arms the mod loader's dev tripwire, which flags mods
 that reach outside their permission set.

docs/new-features.md

@@ -86,14 +86,20 @@ Game Boy equivalent:
 ## Colors mode
 
 The `2` key (and the Options menu COLORS row) cycles the display mode
-through **OG RED → SGB → ADVANCED → OG → OG INV → SGB INV → CLASSIC → OG RED**.
+through **OG RED → SGB → ADVANCED → OG → OG INV → SGB INV → CLASSIC → OG RED**
+(on Blue the first slot labels **OG BLUE**; on Yellow, **OG YELLOW**).
 The first three are the real colorizations; the rest are DMG-shade novelties:
 
-- **OG RED**: the Game Boy Color boot-ROM look for Pokemon Red -- one global
-  red BG palette + one green OBJ palette, every map, no per-map variation
-  (Pokemon Red has no CGB code, so on a GBC the boot ROM colors it globally).
-  The player/NPCs stay green over the red terrain via the OBP bake +
-  post-zone redraw (`PaletteFX.GBC_BG` / `GBC_OBJ`).
+- **OG RED** / **OG BLUE**: the Game Boy Color boot-ROM look for that cart --
+  one global BG palette + one OBJ palette, every map, no per-map variation
+  (Red/Blue ship no CGB code, so on a GBC the boot ROM colors them globally).
+  The player/NPCs keep the boot-ROM OBJ color over the terrain via the OBP
+  bake + post-zone redraw (`PaletteFX.GBC_BG` / `GBC_OBJ`, or Blue's blue/pink
+  pair).
+- **OG YELLOW** (Yellow playthrough, same `ogred` save id): Pokemon Yellow's
+  authentic GBC look from `CGBBasePalettes` (`data/palettes_yellow.lua`,
+  sourced from pret/pokeyellow). Per-map / per-species colors, not a single
+  boot-ROM ramp -- Yellow was CGB-enhanced.
 - **SGB** (default): the per-map Super Game Boy region palettes
   (`data/sgb/sgb_palettes.asm`). Sprites tint with the region palette, as on
   real SGB. (This is the mode formerly mislabeled "GBC".)
@@ -137,6 +143,41 @@ effect, `=1` forces it available. The Anbernic handheld pack exports `0` from
 its launcher because the device reports `"Linux"` while its GPU is in the
 phone class (see [Anbernic RG34XXSP](anbernic-rg34xxsp.md)).
 
+## Performance tier (low-end devices)
+
+The Options **PERFORMANCE** row scales the port's optional presentation
+extras down for weaker hardware. The extras it governs are the three
+heaviest things the port adds on top of the original -- the whole-screen 3D
+**TILT** (transforms the entire map as a ground plane), the **GBC FX**
+post-process shader (a fullscreen pass), and survey **ZOOM** (zooming out
+renders the connected neighbor maps, a lot of extra overdraw) -- plus a hard
+FPS ceiling. None of this touches game logic, which is fixed-step off `dt`
+(`src/core/FixedStep.lua`), so every tier plays identically; they differ
+only in how much eye-candy the renderer is allowed to do.
+
+| Tier         | TILT | GBC FX | Survey ZOOM | Extra FPS ceiling |
+| ------------ | ---- | ------ | ----------- | ----------------- |
+| **HIGH**     | on   | on     | on          | none              |
+| **BALANCED** | off  | off    | on          | none              |
+| **LOW**      | off  | off    | off         | 60                |
+| **AUTO**     | picks a default from the device (below) |||
+
+- **AUTO** (the default) reads the device once at boot: ARM Linux handhelds
+  (e.g. the RG34XXSP) resolve to **LOW**, phones/tablets and very-low-core
+  desktops to **BALANCED**, and everything else -- a normal desktop, and
+  every existing `options.lua` that predates this option -- to **HIGH**,
+  so the common case is unchanged. See `src/core/Performance.detect`.
+- AUTO only chooses the *default*; all four tiers are selectable, so a
+  wrong guess is one row away from being overridden.
+- The clamps are applied **live** against your stored options and never
+  rewrite them (`Game:applyOptions`), so a lower tier hides your TILT / GBC
+  FX / ZOOM without forgetting them -- raising the tier restores exactly
+  what you had. (This is why the TILT / GBC FX / ZOOM rows still show your
+  saved choice on a clamped tier: it's your preference, waiting for a tier
+  that can afford it.)
+- Persisted as `save.options.performance` (`auto` | `high` | `balanced` |
+  `low`); unit-tested in `tests/engine/performance_tiers.lua`.
+
 ## Peer-to-peer link play (lua-enet)
 
 Trades and link battles connect two copies of the game directly over
@@ -151,6 +192,13 @@ tradeoff vs. the relay). Headless tests drive the protocol over an
 in-memory loopback (`Net.loopbackPair`); under LÖVE the same test file
 also exercises real UDP pairing.
 
+Red, Blue, and Yellow copies link with each other, as the real cable
+does. The compatibility fingerprint hashes only data a link mode can
+actually read, so Yellow's Dragonair/Dragonite catch-rate retunes (the
+only R/B/Y link-surface difference) no longer read as different games
+(issue #511). Moving the fingerprint is a link parity change: builds
+from before this fix will refuse to pair with builds after it.
+
 ## Fair play in link and online matches
 
 A link session is decided by the battle and nothing else, so for its
@@ -193,6 +241,11 @@ flushes the live options. Old saves that still embed an `options` table are
 migrated once into `options.lua` on load.
 
 - Music / SFX volume
+- PIKACHU VOL (0-7, Yellow only): trims Pikachu's PCM voice clips under the
+  SFX level, so the follower's constant chatter, the title-screen cry and
+  every in-battle "Pika!" can be pulled down (or muted at 0) without
+  quieting the rest of the sound effects. The row is hidden on Red/Blue,
+  which have no voice clips.
 - Music Filter
 - OG GLITCHES on / off (Gen 1 quirks vs. modern-clean battle rules)
 - BATTLE LAYOUT (OG / WIDE); see "Widescreen battle layout" below
@@ -260,6 +313,14 @@ the last controller restores it immediately. Layout re-derives from the
 window size on rotation. Desktop testing: `POKEPORT_TOUCH=1 love .` forces
 the overlay on and lets the mouse act as a finger (`=0` forces it off).
 
+The launcher's **Touch Controls** button opens a drag editor: move each
+button freely, **Disable** to hide the overlay permanently (for
+controllers / emulation handhelds -- distinct from the temporary
+gamepad auto-hide), **Reset** for defaults, **Done** to save into
+`options.lua` as normalized window fractions so rotation keeps the
+relative placement. In-game, Options → **TOUCH PAD** toggles the same
+on/off flag without leaving a play session.
+
 ## Translation support
 
 Every string the player can read is now reachable from a mod, so a
@@ -319,7 +380,8 @@ semantics - so the two windows read as one app. Six tabs:
   party dock, so deposit and withdraw live in one place. Empty slots are
   clickable and create a mon there.
 - **Items**: money, a searchable item picker (replacing the arrows that
-  cycled one id at a time through ~250 items), the 20-slot bag, PC storage
+  cycled one id at a time through ~250 items), the configurable bag (20 slots
+  by default), PC storage
   with no slot cap, and the eight badges as toggle chips.
 - **Events**: flags, defeated trainers, taken items and per-map object
   toggles, with a real filter field and a two-column paged grid.
@@ -362,3 +424,39 @@ kind, number, height/weight, dex text) to a PNG at 4x scale under
 `prints/` in the save directory, then reports the filename in a dialog.
 No printer hardware or link cable emulation involved; the file is the
 printout.
+
+## Find Mods (community mod indexes)
+
+A FIND MODS tab sits beside MODS in the launcher and browses a published
+mod index: a metadata-only feed listing mods that live in their authors'
+own repositories. No index ships with the launcher and none is ever added
+automatically, so the tab opens on an "Add an index" prompt until you name
+one; paste an index URL or its `owner/repo` and it is remembered in
+`options.lua`. More than one index can be added, and the listings merge.
+
+## Soft reset (all versions)
+
+Holding A, B, START and SELECT together restarts the game the way flicking
+a Game Boy's power switch did, dropping straight back to the title screen.
+It works from anywhere, including mid-battle, which the QUIT entry on the
+start menu cannot do: the original combo is how stationary and gift
+Pokemon get their stats rerolled without sitting through a full relaunch.
+Unsaved progress is discarded, exactly as on hardware.
+
+As on the original, the four buttons have to stay held for 16 straight
+polls (better than a quarter of a second) and any direction in the mix
+cancels it, so it is hard to hit by accident -- including on the on-screen
+touch controls, where it would take four fingers held on four separate
+controls.
+
+## Controls rebinding (CONTROLS screen)
+
+OPTIONS -> CONTROLS lists every Game Boy button with its current keyboard
+key and controller button side by side (Z/A). Press A on a row, then press
+and release the key or pad button you want; the rebind commits on the
+release. If that input already belongs to another row, the two rows swap,
+so no button is ever stranded without an input and no input ever serves
+two buttons. Holding a second key or pad button while the first is still
+down backs out of the capture without touching a keyboard; Escape still