Merge pull request #312 from bryanthaboi/dev

Lots of bug fixes and additional API greatness

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,114 @@
+name: Bug report
+description: Something in the game is broken, wrong, or not behaving like the original.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A screenshot is worth more than any description. If you can grab one, grab one.
+        If you genuinely can't, that's fine, but then the details below need to be thorough
+        enough that someone can find the bug without ever seeing your screen.
+
+  - type: input
+    id: summary
+    attributes:
+      label: One line summary
+      description: What's broken, in a sentence.
+      placeholder: Warp at the south end of the Route 5-8 underground path drops you in the wrong spot
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Which build are you running
+      options:
+        - macOS
+        - Windows
+        - Linux
+        - Android
+        - Multiple platforms
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: The release you downloaded. It's in the release title, like 0.1.4.
+      placeholder: 0.1.4
+    validations:
+      required: true
+
+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers can ping you on Discord if they need a quick follow-up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
+  - type: input
+    id: location
+    attributes:
+      label: Where in the game
+      description: >
+        Be specific. Route, town, building, floor, menu, battle. If it's a map
+        transition, say which side you came in from.
+      placeholder: Underground path between Route 5 and Route 8, south entrance
+    validations:
+      required: true
+
+  - type: textarea
+    id: screenshot
+    attributes:
+      label: Screenshot, or a detailed description if you couldn't take one
+      description: >
+        Drag the image straight into this box. If you couldn't get a screenshot,
+        write "no screenshot" and then describe exactly what was on screen: where
+        the player sprite was, what the tiles around it looked like, any text on
+        screen, whether anything was frozen or flickering. The more concrete, the better.
+      placeholder: |
+        Drop the image here.
+
+        Or, with no screenshot:
+        Screen faded out like a normal warp, then faded back in with the player
+        standing on the grass tile north of the Route 6 gate house instead of
+        inside the tunnel. Player was facing down. No text box. Music kept playing
+        the underground path track instead of switching to the Route 6 track.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: How to make it happen
+      description: Numbered steps, starting from a point someone else can get to.
+      placeholder: |
+        1. Start a new game, get to Cerulean
+        2. Go south to Route 5, enter the underground path building
+        3. Walk to the south end of the tunnel
+        4. Step onto the stairs
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What should have happened
+      placeholder: Should have come out inside the Route 8 side entrance building, facing up.
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: >
+        Does it happen every time or only sometimes. Did it start after a specific
+        release. Anything you were doing right before it. Leave blank if nothing comes to mind.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,103 @@
+name: Feature request
+description: Ask for something new in the engine, launcher, or platform — not a content/gameplay mod.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for **engine / launcher / platform** work (ports, video options, save
+        tooling, networking, mod API seams, docs).
+
+        If what you want is a gameplay, cosmetic, audio, or QoL change that a Lua mod
+        could ship — running shoes, alternate sprites, day/night, shiny indicators,
+        Gen 2-like battle toggles, soundtrack packs — open a
+        **[Mod request](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/issues/new?template=mod_request.yml)**
+        instead.
+
+        "Can we add X" on its own is hard to act on. Say what you want, why you want it,
+        and how you picture it working.
+
+  - type: input
+    id: summary
+    attributes:
+      label: One line summary
+      description: What you want, in a sentence.
+      placeholder: Add Linux AppImage releases next to the macOS and Windows builds
+    validations:
+      required: true
+
+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers can ping you on Discord if they need a quick follow-up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What do you want
+      description: >
+        Describe it properly. What is it, where does it live (launcher, options,
+        engine), what does the player see or do. If it changes something that already
+        exists, say what it does today and what it should do instead.
+      placeholder: |
+        Ship a Linux AppImage on each release, same version as the macOS/Windows builds,
+        with the same save folder layout and mod discovery path.
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why is this worth doing
+      description: >
+        What's annoying or missing right now. What does this fix. If it's just because you
+        think it would be fun, say that, it's a real answer.
+      placeholder: |
+        LÖVE already runs on Linux; without a packaged build, players have to assemble
+        it themselves and miss release notes / update checks.
+    validations:
+      required: true
+
+  - type: textarea
+    id: how
+    attributes:
+      label: How should it work
+      description: >
+        The specifics. Which menu, what happens in the edge cases. If you don't
+        know, say what you'd expect as a player and leave the rest open.
+      placeholder: |
+        - GitHub Releases asset next to the .dmg / .exe
+        - Same options.lua / mods/ layout as desktop
+        - Documented in the README install section
+    validations:
+      required: true
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Does this change how the original game plays
+      description: >
+        Some requests are quality of life, some change the actual game. Both are fine,
+        it just helps to know which one you're asking for.
+      options:
+        - Quality of life, original game is untouched
+        - Changes how the game plays
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: >
+        Reference screenshots, how another game does it, related issues. Leave blank
+        if nothing comes to mind.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/mod_request.yml

@@ -0,0 +1,115 @@
+name: Mod request
+description: Ask for a gameplay, cosmetic, audio, or QoL change that belongs as a Lua mod.
+labels: ["mod request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This tracker is for ideas that should ship as **mods**, not as core engine
+        features — alternate sprites, running shoes, day/night, shiny indicators,
+        soundtrack packs, Gen 2-like battle toggles, map cosmetics, bag QoL, etc.
+
+        The engine already exposes a lot of this through registries and hooks
+        ([modding wiki](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/wiki)).
+        Use a **Feature request** instead for launcher / ports / video options /
+        networking / save tooling / new API seams.
+
+  - type: input
+    id: summary
+    attributes:
+      label: One line summary
+      description: What the mod should do, in a sentence.
+      placeholder: Hold B to run at bike speed on the overworld
+    validations:
+      required: true
+
+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers or mod authors can ping you on Discord if they pick this up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What should the mod do
+      description: >
+        Describe the player-facing behavior. What changes, where, what does the
+        player see or press. If it toggles from Options or a START-menu entry, say so.
+      placeholder: |
+        Hold B while walking outdoors to move at bike speed. Release to walk again.
+        Same places the bike is allowed; no effect in battles or menus.
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why is this worth doing as a mod
+      description: >
+        Why optional/modded rather than a core option. Who wants it on, who wants
+        vanilla left alone.
+      placeholder: |
+        Great for replaying and backtracking, but some people want a strict Gen 1
+        pace. A mod (or an opt-in mod option) keeps both camps happy.
+    validations:
+      required: true
+
+  - type: textarea
+    id: how
+    attributes:
+      label: How should it work
+      description: >
+        Buttons, menus, edge cases, whether it needs new art/audio. If you know a
+        hook or registry that fits (movement.speed, pokemon.sprite, rulesets, …),
+        mention it — otherwise leave it open.
+      placeholder: |
+        - Hold B on the overworld
+        - Same step timing as the bike
+        - Disabled where the bike is disabled
+        - Prefer hooks:wrap("movement.speed") if that still fits
+    validations:
+      required: true
+
+  - type: dropdown
+    id: vanilla
+    attributes:
+      label: With the mod off, is vanilla unchanged
+      options:
+        - Yes — parity when disabled
+        - No — it would replace something always-on
+        - Not sure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Best-fit mod category
+      description: Same taxonomy as example mods (BALANCE, GRAPHICS, AUDIO, …).
+      options:
+        - GAMEPLAY / QoL
+        - GRAPHICS
+        - AUDIO
+        - BALANCE / ruleset
+        - CONTENT (maps, encounters, trainers)
+        - UI / TOOL
+        - TOTAL_CONVERSION-ish
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: >
+        Reference screenshots, other games/hacks that do it, related issues, or
+        "I'd like to try writing this myself." Leave blank if nothing comes to mind.
+    validations:
+      required: false

.github/workflows/ci.yml

@@ -14,7 +14,9 @@ name: ci
 
 on:
   push:
-    branches: [main]
+    # Integration branch + release branch. PRs already run via pull_request
+    # (any base); this list is only for post-merge push runs.
+    branches: [dev, main]
   pull_request:
 
 # a force-push while CI is mid-run should cancel the stale run, not queue

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 name: Release
 
-# Builds the macOS and Windows desktop apps on the self-hosted Mac runner
-# and publishes them as a GitHub Release.
+# Builds the macOS, Windows, and Linux desktop apps plus an Android APK
+# on the self-hosted Mac runner, and publishes them as a GitHub Release.
 #
 # Versioning:
 #   - First ever release is 0.1.0.
@@ -10,10 +10,19 @@ name: Release
 #   - To force a specific version, either:
 #       * run this workflow manually (Actions tab) and type it into "version", or
 #       * put "[release X.Y.Z]" anywhere in the commit message.
+#
+# Branch model: day-to-day work merges to `dev`. Releases stay on `main` only
+# so promoting `dev` -> `main` is the ship gate that cuts a build.
 
 on:
   push:
     branches: [main]
+    # CI/workflow and docs-only changes don't ship anything to users, so they
+    # don't earn a release. A push touching these *and* real source still
+    # releases; only pushes confined entirely to these paths are skipped.
+    paths-ignore:
+      - '.github/**'
+      - '**.md'
   workflow_dispatch:
     inputs:
       version:
@@ -23,6 +32,8 @@ on:
 
 permissions:
   contents: write
+  issues: read
+  pull-requests: read
 
 concurrency:
   group: release
@@ -144,14 +155,20 @@ jobs:
           echo "Identities available to codesign:"
           security find-identity -v -p codesigning "$KEYCHAIN_PATH"
 
-      - name: Build macOS + Windows
+      - name: Build macOS + Windows + Linux
         run: |
           set -euo pipefail
           # Sign in-build (identity auto-detected from the temp keychain);
           # notarize separately below so it uses secret credentials, not a
-          # login-keychain profile.
+          # login-keychain profile. "all" also builds the Linux AppImage,
+          # which needs no signing/notarization.
           scripts/build.sh all --version "${{ steps.ver.outputs.version }}" --no-notarize
 
+      - name: Build Android
+        run: |
+          set -euo pipefail
+          scripts/build_android.sh --version "${{ steps.ver.outputs.version }}"
+
       - name: Notarize & staple macOS app
         run: |
           set -euo pipefail
@@ -163,8 +180,8 @@ jobs:
           set -a; . "$ci_dir/notary.env"; set +a
           echo "::add-mask::$APPLE_APP_PASSWORD"
 
-          app=".bazinga/work/PokemonRed.app"
-          zip="dist/mac/PokemonRed-macos.zip"
+          app=".bazinga/work/gen1recomp.app"
+          zip="dist/mac/gen1recomp-macos.zip"
           [ -d "$app" ] || { echo "::error::signed app not found at $app"; exit 1; }
           if [ -z "${APPLE_ID:-}" ] || [ -z "${APPLE_APP_PASSWORD:-}" ] || [ -z "${APPLE_TEAM_ID:-}" ]; then
             echo "::error::notary.env is missing APPLE_ID / APPLE_APP_PASSWORD / APPLE_TEAM_ID."
@@ -194,10 +211,27 @@ jobs:
           outdir="dist/release"
           rm -rf "$outdir"
           mkdir -p "$outdir"
-          cp "dist/mac/PokemonRed-macos.zip" "$outdir/PokemonRed-${v}-macos.zip"
-          cp "dist/win/PokemonRed-win64.zip" "$outdir/PokemonRed-${v}-windows.zip"
+          cp "dist/mac/gen1recomp-macos.zip" "$outdir/gen1recomp-${v}-macos.zip"
+          cp "dist/win/gen1recomp-win64.zip" "$outdir/gen1recomp-${v}-windows.zip"
+          cp "dist/linux/gen1recomp-linux.zip" "$outdir/gen1recomp-${v}-linux.zip"
+          apk="$(find dist/android/debug -name '*.apk' | head -1)"
+          [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
+          cp "$apk" "$outdir/gen1recomp-${v}-android.apk"
+
+          # Platform-independent update payload, built alongside the desktop
+          # apps above (same game.love that gets fused into each of them).
+          love_file=".bazinga/work/game.love"
+          [ -f "$love_file" ] || { echo "::error::$love_file not found (expected from scripts/build.sh)"; exit 1; }
+          cp "$love_file" "$outdir/gen1recomp-${v}.love"
+
           ls -lh "$outdir"
 
+          # Checksums for every staged release asset (sums file itself is
+          # written after this and named outside the gen1recomp-* glob, so it
+          # never lists itself).
+          (cd "$outdir" && shasum -a 256 gen1recomp-* > sha256sums.txt)
+          cat "$outdir/sha256sums.txt"
+
       - name: Publish GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
@@ -206,14 +240,51 @@ jobs:
           v="${{ steps.ver.outputs.version }}"
           tag="${{ steps.ver.outputs.tag }}"
 
+          # Issues this release closes, per GitHub's own "closing issues" links
+          # (works for squash, rebase, and merge commits alike). Scans every
+          # commit since the previous tag so a skipped release run doesn't drop
+          # issues on the floor.
+          prev_tag="$(git tag -l 'v*' --sort=-v:refname | grep -v "^${tag}$" | head -1 || true)"
+          range="${prev_tag:+${prev_tag}..}$GITHUB_SHA"
+
+          closed=""
+          for pr in $(git log --pretty=%H "$range" \
+                        | xargs -I{} gh api "repos/$GITHUB_REPOSITORY/commits/{}/pulls" \
+                              --jq '.[].number' 2>/dev/null \
+                        | sort -un || true); do
+            closed+="$(gh api graphql \
+              -f owner="${GITHUB_REPOSITORY%/*}" \
+              -f name="${GITHUB_REPOSITORY#*/}" \
+              -F pr="$pr" \
+              -f query='
+                query($owner:String!, $name:String!, $pr:Int!) {
+                  repository(owner:$owner, name:$name) {
+                    pullRequest(number:$pr) {
+                      closingIssuesReferences(first:50) { nodes { number title } }
+                    }
+                  }
+                }' \
+              --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
+                    | "- #\(.number) \(.title)"' 2>/dev/null || true)"$'\n'
+          done
+          closed="$(printf '%s' "$closed" | grep . | sort -t'#' -k2 -n || true)"
+
           notes="Download the correct version for your computer below."
+          if [ -n "$closed" ]; then
+            notes+=$'\n\n## Issues closed\n\n'"$closed"
+          fi
+          printf 'Release notes:\n%s\n' "$notes"
 
           gh release create "$tag" \
             --target "$GITHUB_SHA" \
             --title "$v" \
             --notes "$notes" \
-            "dist/release/PokemonRed-${v}-macos.zip" \
-            "dist/release/PokemonRed-${v}-windows.zip"
+            "dist/release/gen1recomp-${v}-macos.zip" \
+            "dist/release/gen1recomp-${v}-windows.zip" \
+            "dist/release/gen1recomp-${v}-linux.zip" \
+            "dist/release/gen1recomp-${v}-android.apk" \
+            "dist/release/gen1recomp-${v}.love" \
+            "dist/release/sha256sums.txt"
 
           echo "Published release $tag"
 

README.md

@@ -1,18 +1,19 @@
 # Pokemon Gen 1 Recompilation Project
 
-A native LÖVE2D recreation of Pokemon Red. The engine and map behavior are
-hand-written Lua; game data and graphics are decoded from a ROM supplied by
-the player.
+A native LÖVE2D recreation of Pokemon Red and Blue. The engine and map
+behavior are hand-written Lua; game data and graphics are decoded from a ROM
+supplied by the player.
 
 SUPPORT AND ANNOUNCEMENTS: [Discord](https://bois.icu)
 
 This project does not include a ROM, emulate the Game Boy, transpile assembly,
-or download a disassembly. A canonical US Pokemon Red ROM is the only game
-content input.
+or download a disassembly. A canonical US Pokemon Red or Blue 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.
+do not ask for the ROM again. Red and Blue can both be imported and played
+side by side.
 
 ## Quick Start
 
@@ -20,24 +21,52 @@ 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.
 
-Only the canonical 1 MiB US Red ROM is accepted. The importer verifies SHA-1
-`ea9bcae617fdf159b045185467ae58b2e4a48b9a` before creating any game data.
+Only the canonical 1 MiB US Red and Blue ROMs are accepted. The importer
+verifies SHA-1 before creating any game data:
+
+- Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
+- Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
+
 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
 audio channel programs copied out of the verified ROM.
 
 ## Controls
 
-arrow keys or WASD move; Z, Enter, or Space is A; X or Backspace is
-B; Escape opens START. F1 saves and F2 loads. Controllers are supported.
+| Action | Keyboard | Controller |
+|--------|----------|------------|
+| Move | Arrow keys / WASD | D-pad / left stick |
+| A | Z / Enter / Space | A |
+| B | X / Backspace | B |
+| Start | Escape | Start |
+| Select | Tab / Shift | Back / Select |
+
+Rebind any of these in-game under **OPTIONS → CONTROLS**. Controllers are
+supported out of the box.
+
+### Hotkeys
+
+| Key | What it does |
+|-----|----------------|
+| `-` / `=` | Zoom out / in (overworld; also mouse wheel) |
+| `2` | Cycle COLORS |
+| `3` | Cycle TILT (free-roam overworld) |
+| `4` | Cycle ZOOM through every level (free-roam overworld) |
+| `5` | Cycle GBC FX |
+| `F1` | Save |
+| `F2` | Load |
+| `F10` | Open / close the mod manager |
+
+COLORS, TILT, ZOOM, GBC FX, and VOID FILL are also in the Options menu
+and persist in `options.lua`.
 
 ## Running From Source
 
-Requires LÖVE 11.x. Place the ROM in the project folder and double-click
-`Play-Mac.command` or `Play-Windows.bat`, or run:
+Requires LÖVE 11.x. Place a Red or Blue ROM in the project folder and
+double-click `Play-Mac.command` or `Play-Windows.bat`, or run:
 
 ```sh
-scripts/setup.sh --rom "/path/to/Pokemon Red.gb"
+scripts/setup.sh --rom "/path/to/Pokemon Red.gb"   # or Pokemon Blue.gb
 scripts/run.sh
 ```
 
@@ -45,6 +74,29 @@ then `love .` for later launches. Windows PowerShell scripts, the optional
 developer data build, test suites, and cache management are covered in
 [Developer Setup](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/wiki/Guide-Developer-Setup).
 
+## Portable Mode
+
+By default the game keeps your save, options, and the private ROM-derived
+data cache in your OS's normal per-user app data folder. To keep everything
+next to the game instead (handy for a USB stick or portable drive you carry
+between computers), drop an empty file named `portable.txt` next to the app
+(next to `PokemonRed.app`/`.exe`, or next to `main.lua`/`conf.lua` when
+running from source), then launch the game. Portable mode is desktop-only
+(Windows, Linux, macOS); it has no effect on Android or iOS, where the app
+runs from a read-only package.
+
+With `portable.txt` present:
+
+- `save.lua`, `save.lua.bak`, and `options.lua` are read from and written to
+  that same folder instead of the OS save directory.
+- A ROM import writes the generated `data/generated` and `assets/generated`
+  cache straight into that folder too (nothing is left in the OS save
+  directory), so a later launch reuses it without asking for the ROM again
+  even on a different computer, as long as the same folder comes along.
+- Deleting `portable.txt` switches back to the normal OS save directory; nothing
+  already written to either location is touched automatically, so copy files
+  over yourself if you want to carry existing progress across the switch.
+
 ## Modding
 
 The game ships a native mod platform: content registries, events and hooks,
@@ -55,6 +107,21 @@ reference — lives on the
 
 Shipped example mods, one per kind of author, live in [`mods/`](mods/).
 
+## Bugs and Ideas
+
+Found a bug? A warp dropping you somewhere it shouldn't, a battle doing math
+that looks wrong, text in the wrong box, anything that does not match the
+original game.
+[Open a bug report](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/issues/new?template=bug_report.yml).
+Attach a screenshot if you can. It saves a lot of back and forth, and if you
+can't get one, the form asks you to describe what you saw instead.
+
+Thought of a feature that could be good, or a way to improve one that already
+exists?
+[Open a feature request](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/issues/new?template=feature_request.yml).
+Say what you want, why it is worth doing, and how you picture it working. A
+request with real detail is one that can actually get built.
+
 ## More
 
 - [Link play](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/wiki/Guide-Link-Play)

assets/touch/README.md

@@ -0,0 +1,9 @@
+# On-screen touch control art
+
+From Xelu's "Free Controller & Keyboard Prompts" pack (Nicolae Berbece /
+Those Awesome Guys), public domain under CC0:
+https://thoseawesomeguys.com/prompts/
+
+256px Nintendo Switch set, renamed for src/core/TouchControls.lua:
+d-pad (neutral + per-direction highlight), A, B, plus (START) and
+minus (SELECT).

conf.lua

@@ -1,13 +1,16 @@
 function love.conf(t)
   local editor = os.getenv("POKEPORT_EDITOR") == "1"
+  local developer = os.getenv("POKEPORT_DEV") == "1"
   if arg then
     for _, a in ipairs(arg) do
       if a == "--editor" then editor = true end
+      if a == "--developer" then developer = true end
     end
   end
   -- main.lua runs in the same Lua state right after conf.lua; stash the
   -- decision in a global so it doesn't need to reparse `arg`.
   _G.POKEPORT_EDITOR_MODE = editor
+  _G.POKEPORT_DEV_MODE = developer
 
   if editor then
     t.identity = os.getenv("POKEPORT_IDENTITY") or "pokemon-love2d-editor"
@@ -20,9 +23,13 @@ function love.conf(t)
     -- back to the plain title if the source is not mounted yet
     local ok, Version = pcall(require, "src.core.Version")
     t.window.title = ok and Version.title()
-      or "Pokemon Red (Gen 1 Recompilation Project)"
-    t.window.width = 160 * 4
-    t.window.height = 144 * 4
+      or "gen1recomp"
+    -- Open at the launcher's design size (the split-screen ROM selector is
+    -- laid out for 1024x768). The window is resizable and the 160x144 game
+    -- canvas letterboxes into whatever size it ends up, so this only sets the
+    -- starting size, not the game's resolution.
+    t.window.width = 1024
+    t.window.height = 768
   end
   t.version = "11.5"
   t.window.vsync = 1
@@ -34,14 +41,30 @@ function love.conf(t)
   local osName = love._os
   local mobile = osName == "Android" or osName == "iOS"
   if mobile then
-    -- On Android/iOS, width/height aspect picks portrait vs landscape
-    -- (fullscreen alone is not enough). Use a tall portrait size; the
-    -- OS then resizes to the real display. highdpi is required for
-    -- Retina iOS (Android always behaves as highdpi).
+    -- resizable is what unlocks orientation.  SDL's Android backend, given no
+    -- SDL_HINT_ORIENTATIONS (LÖVE sets none), calls setRequestedOrientation
+    -- at window creation -- FULL_SENSOR when the window is resizable (rotates
+    -- freely to portrait or landscape), otherwise locked to the window's w/h
+    -- aspect.  So a non-resizable tall window forced portrait; resizable lets
+    -- 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
+    -- (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
+    -- display and rotations resize again. highdpi is required for Retina iOS
+    -- (Android always behaves as highdpi).
     t.window.width = 1080
     t.window.height = 1920
     t.window.fullscreen = true
     t.window.highdpi = true
+    -- Android only (irrelevant on iOS): puts the save directory under the
+    -- app's external-files folder, which is readable/writable via USB or a
+    -- file manager with no runtime permission, so RomImporter can ask the
+    -- 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"
   else
     t.window.resizable = true
   end

data/scripts/celadon_chief_house.lua

@@ -0,0 +1,26 @@
+-- Celadon Chief House (scripts/CeladonChiefHouse.asm).  The CHIEF is a
+-- talk-only NPC in the original ROM, and ChiefData (data/trainers/
+-- parties.asm) is an empty, unreferenced trainer entry.  After the HALL
+-- OF FAME (EVENT_BEAT_CHAMPION_RIVAL) the CHIEF puts up a fight, using a
+-- reconstructed party for the otherwise-unused OPP_CHIEF class.
+
+return {
+  talk = {
+    TEXT_CELADONCHIEFHOUSE_CHIEF = {
+      { "face_player" },                                        -- 1
+      { "check_flag", "EVENT_BEAT_CHAMPION_RIVAL" },            -- 2
+      { "jump_if_false", 12 },                                  -- 3
+      { "check_flag", "EVENT_BEAT_CELADON_CHIEF" },             -- 4
+      { "jump_if_true", 12 },                                   -- 5
+      { "show_text", "So you've come to\nshut down my\noperation?\f"
+        .. "TEAM ROCKET's\nCHIEF won't go\ndown so easy!" },    -- 6
+      { "start_battle", "trainer", "OPP_CHIEF", 1 },            -- 7
+      { "jump_if_false", "end" },                               -- 8
+      { "set_flag", "EVENT_BEAT_CELADON_CHIEF" },               -- 9
+      { "show_text", "Gah! Even the\nCHIEF is no match\nfor you!\f"
+        .. "TEAM ROCKET is\nfinished for\ngood!" },             -- 10
+      { "jump", "end" },                                        -- 11
+      { "show_text", "_CeladonChiefHouseChiefText" },           -- 12
+    },
+  },
+}

data/scripts/flavor/copycats_house_2f.lua

@@ -1,9 +1,8 @@
 -- Flavor talk scripts for CopycatsHouse2F (registry id COPYCATS_HOUSE_2F).
 -- Source: pokered/scripts/CopycatsHouse2F.asm, pokered/text/CopycatsHouse2F.asm
 --
--- TEXT_COPYCATSHOUSE2F_COPYCAT is already ported (with the POKE DOLL /
--- TM31 MIMIC trade) in data/scripts/story4.lua, so it is intentionally
--- omitted here.
+-- TEXT_COPYCATSHOUSE2F_COPYCAT (POKE DOLL -> TM31 MIMIC) lives in
+-- data/scripts/story4.lua.
 
 return {
   COPYCATS_HOUSE_2F = {

data/scripts/flavor/pewter_city.lua

@@ -1,14 +1,11 @@
 -- Pewter City flavor dialogue (pokered/scripts/PewterCity.asm).
 -- PewterCity_TextPointers text_asm bodies for the SUPER_NERD1 museum
--- guide, SUPER_NERD2 garden nerd, and the leaving-east YOUNGSTER.
+-- guide and SUPER_NERD2 garden nerd.
 --
--- The escort choreography (SUPER_NERD1 walking the player to the
--- museum, YOUNGSTER walking the player to the gym) is scripted NPC
--- movement + a wPewterCityCurScript state machine that steers the
--- player off-map; that part is already covered on this map by
--- story5.lua's onStep gate (walks the player back a step at the
--- east exit before EVENT_BEAT_BROCK). Here we only port the real
--- YES/NO-branched flavor text these NPCs speak when talked to.
+-- The YOUNGSTER's gym escort (talk + east-exit onStep) lives in
+-- story5.lua so the lockstep RLE walk is not overwritten by this
+-- flavor merge.  SUPER_NERD1's museum escort is not ported; only the
+-- YES/NO-branched flavor text is here.
 
 local M = {}
 
@@ -60,15 +57,6 @@ M.PEWTER_CITY = {
       end)
     end,
 
-    -- PewterCityYoungsterText (scripts/PewterCity.asm): the "follow
-    -- me" line the youngster says when the player is stopped from
-    -- leaving Pewter east before beating Brock; the actual gate/step
-    -- block is handled by story5.lua's onStep for this map.
-    TEXT_PEWTERCITY_YOUNGSTER = function(game, ow, npc, done)
-      local t = text(game)
-      push(game, t._PewterCityYoungsterYoureATrainerFollowMeText
-        or "You're a trainer\nright? BROCK's\nlooking for new\nchallengers!\nFollow me!", done)
-    end,
   },
 }
 

data/scripts/flavor/pewter_nidoran_house.lua

@@ -1,13 +1,21 @@
 -- pokered/scripts/PewterNidoranHouse.asm
 -- PewterNidoranHouseNidoranText: text_far _PewterNidoranHouseNidoranText, then
 -- text_asm plays the NIDORAN_M cry (PlayCry/WaitForSoundToFinish) before ending.
--- No sound-effect command exists in Commands.lua, so we port the dialogue line
--- only; the cry SFX is cosmetic and has no gameplay effect.
+-- play_cry only stashes ctx.pendingCry for the very next show_text row, so it
+-- has to sit immediately before that row (src/script/Commands.lua); the cry
+-- then sounds once the box has typed out, matching the asm's print-then-cry
+-- order.  Its waitForButton form keeps DisplayTextID's trailing
+-- WaitForTextScrollButtonPress -- PewterNidoranHouse_Script is
+-- `jp EnableAutoTextBoxDrawing`, which zeroes
+-- wDoNotWaitForButtonPressAfterDisplayingText -- so the box still holds until
+-- A/B.  The cry row was missing, leaving the NIDORAN silent (#247).
 return {
   PEWTER_NIDORAN_HOUSE = {
     talk = {
       TEXT_PEWTERNIDORANHOUSE_NIDORAN = {
         { "face_player" },
+        -- text_asm: ld a, NIDORAN_M / call PlayCry
+        { "play_cry", "NIDORAN_M", true },
         { "show_text", "_PewterNidoranHouseNidoranText" },
       },
     },

data/scripts/flavor/reds_house_2f.lua

@@ -0,0 +1,22 @@
+-- Red's House 2F (pokered data/events/hidden_events.asm +
+-- engine/events/hidden_objects PrintRedSNESText).
+--
+-- The bedroom SNES is a hidden_event at (3, 5) with ANY_FACING that
+-- prints _RedBedroomSNESText.  field.py extracts OpenRedsPC on this map
+-- but skips PrintRedSNESText, so interaction was a no-op (#135).
+
+local TextBox = require("src.render.TextBox")
+
+return {
+  REDS_HOUSE_2F = {
+    -- hidden_events.asm:
+    --   hidden_event 3, 5, PrintRedSNESText, ANY_FACING
+    onInteract = function(game, ow, fx, fy)
+      if fx ~= 3 or fy ~= 5 then return false end
+      local text = game.data.text._RedBedroomSNESText
+        or "{PLAYER} is\nplaying the SNES!"
+      game.stack:push(TextBox.new(game, text))
+      return true
+    end,
+  },
+}

data/scripts/flavor/silph_co_9f.lua

@@ -5,19 +5,23 @@ return {
   SILPH_CO_9F = {
     talk = {
       -- SilphCo9FNurseText (pokered/scripts/SilphCo9F.asm):
-      -- before EVENT_BEAT_SILPH_CO_GIOVANNI: heals the party and shows
-      -- "You look tired..." then "Don't give up!"; after the event, just
-      -- says thanks. Nurse texts are not in data/generated/text.lua, so
-      -- the exact pokered/text/SilphCo9F.asm strings are used as literals.
+      -- before EVENT_BEAT_SILPH_CO_GIOVANNI: heals the party, white fade
+      -- (Delay3 between out/in; no Music_PkmnHealed), then "Don't give
+      -- up!"; after the event, just says thanks. Nurse texts are not in
+      -- data/generated/text.lua, so the exact pokered/text/SilphCo9F.asm
+      -- strings are used as literals.
       TEXT_SILPHCO9F_NURSE = {
-        { "face_player" },
-        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 8 },
-        { "show_text", "You look tired!\nYou should take a\nquick nap!" },
-        { "heal_party" },
-        { "show_text", "Don't give up!" },
-        { "jump", 9 },
-        { "show_text", "Thank you so\nmuch!" },
+        { "face_player" },                                              -- 1
+        { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },                -- 2
+        { "jump_if_true", 11 },                                         -- 3
+        { "show_text", "You look tired!\nYou should take a\nquick nap!" }, -- 4
+        { "heal_party" },                                               -- 5
+        { "fade", "out", "white" },                                     -- 6
+        { "wait", 3 },                                                  -- 7  Delay3
+        { "fade", "in", "white" },                                      -- 8
+        { "show_text", "Don't give up!" },                              -- 9
+        { "jump", "end" },                                              -- 10
+        { "show_text", "Thank you so\nmuch!" },                         -- 11
       },
     },
   },

data/scripts/flavor/viridian_city.lua

@@ -1,22 +1,18 @@
 -- Viridian City flavor dialogue (pokered/scripts/ViridianCity.asm).
--- Ports the text_asm bodies for GAMBLER1, YOUNGSTER2, GIRL and OLD_MAN.
+-- Ports the text_asm bodies for GAMBLER1, YOUNGSTER2 and GIRL.
 --
 -- Not ported here (already handled elsewhere / not talk-reachable):
 --  * TEXT_VIRIDIANCITY_FISHER (TM42 gift) -- already ported as a
 --    `gift()` entry in data/scripts/story5.lua's M.VIRIDIAN_CITY.talk.
---  * TEXT_VIRIDIANCITY_OLD_MAN_SLEEPY / TEXT_VIRIDIANCITY_GYM_LOCKED --
---    these are step-triggered blocking texts (ViridianCityCheckGotPokedexScript /
---    ViridianCityCheckGymOpenScript), not npc talk text_asm bodies; the
---    gates themselves are already implemented via story5.lua's onStep
---    chain (viridianOldManStep / viridianGymLock) for this map.
---  * The old man's catch-training minigame trigger (SCRIPT_VIRIDIANCITY_
---    OLD_MAN_START_CATCH_TRAINING / battle vs. WEEDLE) is a full
---    scripted-battle cutscene outside this task's Commands vocabulary
---    (no static_battle-style "battle a scripted old-man WEEDLE" command
---    exists); we port the real YES/NO branch text he speaks but the
---    "yes" branch here just shows the "I'll show you how" line rather
---    than actually starting the minigame, since that machinery isn't
---    ported to this map yet.
+--  * TEXT_VIRIDIANCITY_OLD_MAN (the walking man at (17,5)) and
+--    TEXT_VIRIDIANCITY_OLD_MAN_SLEEPY (the sleeper at (18,9)) -- both
+--    live in data/scripts/story.lua, which owns this map's onStep gate
+--    and can reach the `old_man_demo` command for the real catch
+--    tutorial.  Keep them there: story.lua loads BEFORE this file, so a
+--    duplicate here would silently win the merge.
+--  * TEXT_VIRIDIANCITY_GYM_LOCKED -- a step-triggered blocking text
+--    (ViridianCityCheckGymOpenScript), implemented by story5.lua's
+--    onStep chain (viridianGymLock -> viridianOldManStep) for this map.
 
 local M = {}
 
@@ -63,13 +59,17 @@ M.VIRIDIAN_CITY = {
     -- ViridianCityYoungster2CaterpieAndWeedleDescriptionText are
     -- defined without a leading underscore in pokered/text/ViridianCity.asm
     -- and aren't present in data/generated/text.lua, so we fall back to
-    -- the literal strings from pokered.
+    -- the literal strings from pokered.  Those fallbacks have to carry the
+    -- extractor's markers, not plain newlines: line -> \n, cont -> \v,
+    -- para -> \f.  Spelling cont/para as \n and \n\n put all six lines on
+    -- one page with nothing to wait on, so the whole speech scrolled past
+    -- without a button press (#250).
     TEXT_VIRIDIANCITY_YOUNGSTER2 = function(game, ow, npc, done)
       local t = text(game)
       ask(game, t._ViridianCityYoungster2YouWantToKnowAboutText
-        or "You want to know\nabout the 2 kinds\nof caterpillar\nPOKéMON?", function(yes)
+        or "You want to know\nabout the 2 kinds\vof caterpillar\vPOKéMON?", function(yes)
         if yes then
-          push(game, "CATERPIE has no\npoison, but\nWEEDLE does.\n\nWatch out for its\nPOISON STING!", done)
+          push(game, "CATERPIE has no\npoison, but\vWEEDLE does.\fWatch out for its\nPOISON STING!", done)
         else
           push(game, "Oh, OK then!", done)
         end
@@ -91,24 +91,6 @@ M.VIRIDIAN_CITY = {
       end
     end,
 
-    -- ViridianCityOldManText (scripts/ViridianCity.asm): once he's had
-    -- his coffee, he asks (YES/NO) whether you want to learn how to
-    -- catch Pokemon. YES leads into the catch-training minigame
-    -- (SCRIPT_VIRIDIANCITY_OLD_MAN_START_CATCH_TRAINING, not ported --
-    -- see file header); NO just brushes you off ("Time is money...").
-    TEXT_VIRIDIANCITY_OLD_MAN = function(game, ow, npc, done)
-      local t = text(game)
-      ask(game, t._ViridianCityOldManHadMyCoffeeNowText
-        or "Ahh, I've had my\ncoffee now and I\nfeel great!\nSure you can go\nthrough!\nAre you in a\nhurry?", function(yes)
-        if yes then
-          push(game, t._ViridianCityOldManKnowHowToCatchPokemonText
-            or "I see you're using\na POKéDEX.\nWhen you catch a\nPOKéMON, POKéDEX\nis automatically\nupdated.\nWhat? Don't you\nknow how to catch\nPOKéMON?\nI'll show you\nhow to then.", done)
-        else
-          push(game, t._ViridianCityOldManTimeIsMoneyText
-            or "Time is money...\nGo along then.", done)
-        end
-      end)
-    end,
   },
 }
 

data/scripts/flavor/viridian_nickname_house.lua

@@ -3,12 +3,16 @@
 return {
   VIRIDIAN_NICKNAME_HOUSE = {
     talk = {
-      -- ViridianNicknameHouseSpearowText: text_asm that shows the text
-      -- then plays a SPEAROW cry (PlayCry/WaitForSoundToFinish). The
-      -- cry playback isn't in the talk-script command vocabulary, so
-      -- only the flavor line is ported here.
+      -- ViridianNicknameHouseSpearowText: text_asm that PrintTexts the
+      -- line, then plays the SPEAROW cry (PlayCry/WaitForSoundToFinish)
+      -- before TextScriptEnd.  play_cry only arms the show_text row that
+      -- follows it, so the cry sounds once the box has typed out; its
+      -- waitForButton form keeps DisplayTextID's trailing
+      -- WaitForTextScrollButtonPress, so the box then holds until A/B like
+      -- any other NPC line rather than popping itself (#251).
       TEXT_VIRIDIANNICKNAMEHOUSE_SPEAROW = {
-        { "show_text", "_ViridianNicknameHouseSpearowText" },
+        { "play_cry", "SPEAROW", true },                      -- 1 PlayCry
+        { "show_text", "_ViridianNicknameHouseSpearowText" }, -- 2 PrintText
       },
     },
   },

data/scripts/flavor_all.lua

@@ -28,6 +28,7 @@ local files = {
   "data.scripts.flavor.pokemon_fan_club",
   "data.scripts.flavor.power_plant",
   "data.scripts.flavor.reds_house_1f",
+  "data.scripts.flavor.reds_house_2f",
   "data.scripts.flavor.route11_gate_2f",
   "data.scripts.flavor.route18_gate_2f",
   "data.scripts.flavor.route_12_gate_2f",

data/scripts/oaks_lab.lua

@@ -6,12 +6,13 @@
 --   takes it ("I'll take this one, then!") and both balls disappear.
 --   Source: scripts/OaksLab.asm OaksLabCharmanderPokeBallText /
 --   OaksLabRivalTakePokeBallScript.
--- * Rival (object 1): before starter -> "gramps isn't around"; with
+-- * 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
 --   (player Bulbasaur -> rival Charmander etc., parties 1/2/3 =
 --   Squirtle/Bulbasaur/Charmander in data/trainers/parties.asm);
---   afterwards he gloats or sulks and marches out of the lab
---   (OaksLabRivalBattleEndScript).
+--   afterwards HealParty + flag always, then he gloats or sulks and
+--   marches out (OaksLabRivalEndBattleScript).  A loss does not black out.
 
 -- ball objects: CHARMANDER (6,3), SQUIRTLE (7,3), BULBASAUR (8,3);
 -- rival = object 1 at (4,3).  rivalBallX is the counter-pick's column.
@@ -19,72 +20,137 @@ local function starterBall(askText, species, choseFlag, ownBall,
                            rivalBallX, rivalBall)
   return {
     { "check_flag", "EVENT_GOT_STARTER" },        -- 1
-    { "jump_if_true", 19 },                       -- 2
+    { "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", 19 },                      -- 4
-    { "ask", askText },                           -- 5
-    { "jump_if_false", 20 },                      -- 6
-    { "give_pokemon", species, 5 },               -- 7
-    { "set_flag", "EVENT_GOT_STARTER" },          -- 8
-    { "set_flag", choseFlag },                    -- 9
+    { "jump_if_false", 20 },                      -- 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;
+    -- forceOwned is that bypass without mutating save.pokedex.owned.
+    { "push_screen", "DexEntryMenu",
+      { species = species, forceOwned = true } }, -- 5
+    { "ask", askText },                           -- 6
+    { "jump_if_false", 21 },                      -- 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.
+    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 8
+    { "give_pokemon", species, 5 },               -- 9
+    { "set_flag", "EVENT_GOT_STARTER" },          -- 10
+    { "set_flag", choseFlag },                    -- 11
     -- POKé BALLs are not handed out here in the original -- Oak gives
     -- them later, at OaksLabOak1Text's .give_poke_balls beat once the
     -- player has beaten the Route 22 rival (see TEXT_OAKSLAB_OAK1 below)
-    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 10
-    { "hide_object", "OAKS_LAB", ownBall },       -- 11
+    { "hide_object", "OAKS_LAB", ownBall },       -- 12
     -- the rival walks to the countering ball (around the furniture)
-    { "move_npc_to", 1, rivalBallX, 4 },          -- 12
-    { "face_object", 1, "up" },                   -- 13
-    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 14
-    { "hide_object", "OAKS_LAB", rivalBall },     -- 15
+    { "move_npc_to", 1, rivalBallX, 4 },          -- 13
+    { "face_object", 1, "up" },                   -- 14
+    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 15
+    { "hide_object", "OAKS_LAB", rivalBall },     -- 16
     { "show_text", "_OaksLabRivalReceivedMonText",
       { RAM = rivalBall == "OAKSLAB_CHARMANDER_POKE_BALL" and "CHARMANDER"
               or rivalBall == "OAKSLAB_SQUIRTLE_POKE_BALL" and "SQUIRTLE"
-              or "BULBASAUR" } },                 -- 16
-    { "jump", 20 },                               -- 17
-    { "jump", 20 },                               -- 18 (spacer)
-    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 19
+              or "BULBASAUR" } },                 -- 17
+    { "jump", 21 },                               -- 18
+    { "jump", 21 },                               -- 19 (spacer)
+    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 20
   }
 end
 
 return {
   talk = {
-    -- Oak: accepts the parcel and hands over the Pokédex, then (once the
-    -- player has beaten the Route 22 rival) hands over the real POKé
-    -- BALLs (scripts/OaksLab.asm OaksLabOak1Text, simplified: no rival
-    -- recall / dex-rating / "pokemon can fight" / "around the world"
-    -- branches -- see docs/known-differences.md)
+    -- Oak: OaksLabOak1Text.  Parcel delivery kicks SCRIPT_OAKSLAB_RIVAL_
+    -- ARRIVES_AT_OAKS_REQUEST + OaksLabOakGivesPokedexScript (rival walk-
+    -- in, full Pokédex speech, rival exit, Route 22 arm).  Dex-rating
+    -- (DisplayDexRating) is still skipped.
     TEXT_OAKSLAB_OAK1 = {
-      { "face_player" },                                          -- 1
-      { "check_flag", "EVENT_GOT_OAKS_PARCEL" },                  -- 2
-      { "jump_if_false", 12 },                                    -- 3
-      { "check_flag", "EVENT_OAK_GOT_PARCEL" },                   -- 4
-      { "jump_if_true", 12 },                                     -- 5
-      { "show_text", "_OaksLabOak1DeliverParcelText" },           -- 6
-      { "take_item", "OAKS_PARCEL", 1 },                          -- 7
-      { "set_flag", "EVENT_OAK_GOT_PARCEL" },                     -- 8
-      { "show_text", "_OaksLabOak1PokemonAroundTheWorldText" },   -- 9
-      { "set_flag", "EVENT_GOT_POKEDEX" },                        -- 10
-      { "jump", 30 },                                             -- 11
-      { "check_flag", "EVENT_GOT_STARTER" },                      -- 12
-      { "jump_if_false", 27 },                                    -- 13
-      { "check_item", "POKE_BALL" },                              -- 14
-      { "jump_if_true", 25 },                                     -- 15
-      { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },    -- 16
-      { "jump_if_false", 29 },                                    -- 17
-      { "check_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },           -- 18
-      { "jump_if_true", 25 },                                     -- 19
-      { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },             -- 20
-      { "give_item", "POKE_BALL", 5, false },                     -- 21
-      { "show_text", "_OaksLabOak1ReceivedPokeballsText" },       -- 22
-      { "show_text", "_OaksLabGivePokeballsExplanationText" },    -- 23
-      { "jump", 30 },                                             -- 24
-      { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },      -- 25
-      { "jump", 30 },                                             -- 26
-      { "show_text", "_OaksLabOak1WhichPokemonDoYouWantText" },   -- 27
-      { "jump", 30 },                                             -- 28
-      { "show_text", "_OaksLabOak1RaiseYourYoungPokemonText" },   -- 29 (30 = end)
+      { "face_player" },
+      { "check_item", "POKE_BALL" },
+      { "jump_if_true", "come_see" },
+      { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },
+      { "jump_if_true", "give_balls" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_true", "around_world" },
+      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },
+      { "jump_if_false", "pre_lab_battle" },
+      { "check_item", "OAKS_PARCEL" },
+      { "jump_if_false", "raise_young" },
+      -- OaksLabOak1Text.got_parcel → RivalArrives + OakGivesPokedex
+      { "show_text", "_OaksLabOak1DeliverParcelText" },
+      { "play_sound", "Get_Key_Item" },
+      { "show_text", "_OaksLabOak1ParcelThanksText" },
+      { "take_item", "OAKS_PARCEL", 1 },
+      { "stop_music" },
+      { "play_music", "Music_MeetRival" },
+      { "show_text", "_OaksLabRivalGrampsText" },
+      { "show_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
+      -- OaksLabCalcRivalMovementScript: sprite map (8,11) → cell (4,7)
+      -- when the player stands below Oak (the usual desk talk).
+      { "place_npc", 1, 4, 7, "up" },
+      { "move_npc_to", 1, 4, 3 },
+      { "play_music", "Music_OaksLab" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabRivalWhatDidYouCallMeForText" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakIHaveARequestText" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "show_text", "_OaksLabOakGotPokedexText" },
+      { "play_sound", "Get_Key_Item" },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakThatWasMyDreamText" },
+      { "face_object", 1, "right" },
+      { "show_text", "_OaksLabRivalLeaveItAllToMeText" },
+      { "set_flag", "EVENT_GOT_POKEDEX" },
+      { "set_flag", "EVENT_OAK_GOT_PARCEL" },
+      { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" },
+      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN" },
+      { "stop_music" },
+      { "play_music", "Music_MeetRival" },
+      { "move_npc_to", 1, 4, 7 },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
+      { "play_music", "Music_OaksLab" },
+      { "set_flag", "EVENT_1ST_ROUTE22_RIVAL_BATTLE" },
+      { "clear_flag", "EVENT_2ND_ROUTE22_RIVAL_BATTLE" },
+      { "set_flag", "EVENT_ROUTE22_RIVAL_WANTS_BATTLE" },
+      { "show_object", "ROUTE_22", "ROUTE22_RIVAL1" },
+      { "jump", "end" },
+
+      { "label", "raise_young" },
+      { "show_text", "_OaksLabOak1RaiseYourYoungPokemonText" },
+      { "jump", "end" },
+
+      { "label", "pre_lab_battle" },
+      { "check_flag", "EVENT_GOT_STARTER" },
+      { "jump_if_true", "can_fight" },
+      { "show_text", "_OaksLabOak1WhichPokemonDoYouWantText" },
+      { "jump", "end" },
+      { "label", "can_fight" },
+      { "show_text", "_OaksLabOak1YourPokemonCanFightText" },
+      { "jump", "end" },
+
+      { "label", "around_world" },
+      { "show_text", "_OaksLabOak1PokemonAroundTheWorldText" },
+      { "jump", "end" },
+
+      { "label", "give_balls" },
+      { "check_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
+      { "jump_if_true", "come_see" },
+      { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
+      { "give_item", "POKE_BALL", 5, false },
+      { "show_text", "_OaksLabOak1ReceivedPokeballsText" },
+      { "show_text", "_OaksLabGivePokeballsExplanationText" },
+      { "jump", "end" },
+
+      { "label", "come_see" },
+      { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },
     },
 
     TEXT_OAKSLAB_CHARMANDER_POKE_BALL =
@@ -97,45 +163,76 @@ return {
       starterBall("_OaksLabYouWantBulbasaurText", "BULBASAUR", "EVENT_CHOSE_BULBASAUR",
                   "OAKSLAB_BULBASAUR_POKE_BALL", 6, "OAKSLAB_CHARMANDER_POKE_BALL"),
 
+    -- Talking to the rival only ever prints a line: the lab battle is a
+    -- coordinate trigger (OaksLabRivalChallengesPlayerScript, wYCoord == 6;
+    -- see onStep below), never a talk action.  The handler used to fall
+    -- through from the "looks stronger" taunt straight into start_battle,
+    -- so talking to Blue at the table launched the rival fight before the
+    -- player ever stepped onto the trigger (#219).  scripts/OaksLab.asm
+    -- OaksLabText8 branches text only:
+    --   * got starter, not yet battled -> _OaksLabRivalMyPokemonLooksStronger
+    --   * already battled -> _OaksLabRivalFedUpWithWaitingText (a Route 22
+    --     line; normally unreachable since the rival is hidden after the
+    --     lab battle in OaksLabRivalEndBattleScript)
+    --   * no starter yet -> the FOLLOWED_OAK pre-starter fork (#218)
     TEXT_OAKSLAB_RIVAL = {
-      { "face_player" },                                          -- 1
-      { "check_flag", "EVENT_GOT_STARTER" },                      -- 2
-      { "jump_if_false", 20 },                                    -- 3
-      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },        -- 4
-      { "jump_if_true", 18 },                                     -- 5
-      { "show_text", "_OaksLabRivalMyPokemonLooksStrongerText" }, -- 6
-      { "check_flag", "EVENT_CHOSE_BULBASAUR" },                  -- 7
-      { "jump_if_false", 11 },                                    -- 8
-      { "start_battle", "trainer", "OPP_RIVAL1", 3 },             -- 9  Charmander
-      { "jump", 16 },                                             -- 10
-      { "check_flag", "EVENT_CHOSE_SQUIRTLE" },                   -- 11
-      { "jump_if_false", 15 },                                    -- 12
-      { "start_battle", "trainer", "OPP_RIVAL1", 2 },             -- 13 Bulbasaur
-      { "jump", 16 },                                             -- 14
-      { "start_battle", "trainer", "OPP_RIVAL1", 1 },             -- 15 Squirtle
-      { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },          -- 16
-      { "jump", 21 },                                             -- 17
-      { "show_text", "_OaksLabRivalFedUpWithWaitingText" },       -- 18
-      { "jump", 25 },                                             -- 19
-      { "show_text", "_OaksLabRivalGrampsIsntAroundText" },       -- 20
-      -- battle aftermath: on a win the rival sulks and marches out
-      -- (OaksLabRivalBattleEnd); on a loss the blackout already warped
-      -- us away, so the script just ends
-      { "jump_if_false", 25 },                                    -- 21
-      { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" }, -- 22
-      { "move_npc_to", 1, 4, 11 },                                -- 23
-      { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" },             -- 24 (25 = end)
+      { "face_player" },
+      { "check_flag", "EVENT_GOT_STARTER" },
+      { "jump_if_false", "pre_starter" },
+      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },
+      { "jump_if_true", "after_battle" },
+      -- has a starter, has not fought yet: just the taunt.  The battle is
+      -- the coordinate trigger in onStep, not this talk (#219)
+      { "show_text", "_OaksLabRivalMyPokemonLooksStrongerText" },
+      { "jump", "end" },
+
+      { "label", "after_battle" },
+      { "show_text", "_OaksLabRivalFedUpWithWaitingText" },
+      { "jump", "end" },
+
+      -- pre-starter fork (scripts/OaksLab.asm OaksLabText8 rival handler):
+      -- Oak has already escorted you in (three balls on the table) -> he
+      -- waves you on to choose; not yet escorted (very early game) -> the
+      -- "Gramps isn't around" line.  #218
+      { "label", "pre_starter" },
+      { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB" },
+      { "jump_if_false", "gramps_gone" },
+      { "show_text", "_OaksLabRivalGoAheadAndChooseText" },
+      { "jump", "end" },
+
+      { "label", "gramps_gone" },
+      { "show_text", "_OaksLabRivalGrampsIsntAroundText" },
     },
   },
 
+  -- Saves that got the Pokédex before #106 never wrote objectToggles for
+  -- the table sprites; re-entering the lab applies the same HideObject
+  -- the gift script now does (OaksLab.asm OakGivesPokedex).
+  onEnter = function(game, ow)
+    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
+      return
+    end
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX1")
+    Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX2")
+  end,
+
   -- Oak stops you leaving without a starter; the rival stops you on
   -- the way out for the first battle (scripts/OaksLab.asm
   -- OaksLabScript8 / OaksLabRivalChallenge)
   onStep = function(game, ow, x, y)
     local flags = game.save.flags
-    -- Oak blocks the exit mats (4,11)/(5,11) until you take a starter
+    -- Oak stops you leaving without a starter at the bookshelf row (cell
+    -- y == 6): this is the same wYCoord == 6 coordinate script the rival
+    -- challenge just below uses (scripts/OaksLab.asm, both gated on
+    -- EVENT_GOT_STARTER), so Oak halts you level with the shelves, not one
+    -- corridor length later on the exit mat.  At y>=6 only the x=4,5
+    -- corridor is walkable and the up-push keeps the player above y=7, so
+    -- this only ever fires at y=6 in the corridor -- matching the rival
+    -- trigger's shape. (#232)
     if flags.EVENT_FOLLOWED_OAK_INTO_LAB and not flags.EVENT_GOT_STARTER
-       and y == 11 and (x == 4 or x == 5) then
+       and y >= 6 then
       ow.runner:run({
         { "show_text", "_OaksLabOakDontGoAwayYetText" },
         { "move_player", "up", 1 },
@@ -171,10 +268,21 @@ return {
       local party = flags.EVENT_CHOSE_BULBASAUR and 3
                     or flags.EVENT_CHOSE_SQUIRTLE and 2 or 1
       table.insert(rows, { "start_battle", "trainer", "OPP_RIVAL1", party })
+      -- OaksLabRivalEndBattleScript: heal + flag on win or loss; no blackout
+      table.insert(rows, { "heal_party" })
       table.insert(rows, { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" })
-      -- a loss blacks out to another map: end the script there
-      table.insert(rows, { "jump_if_false", base + 7 })
+      -- OaksLabRivalEndBattleScript: on WIN, print the "picked the wrong
+      -- POKéMON!" gloat, then BOTH win and loss print the shared exit line
+      -- _OaksLabRivalSmellYouLaterText ("OK! I'll make my POKéMON fight to
+      -- toughen it up!\012<PLAYER>! Gramps! Smell you later!") before Blue
+      -- marches out.  A loss skips only the gloat (that taunt was already
+      -- shown in-battle via Rival1WinText), never the exit line (#231).  The
+      -- jump_if_false convergence point is the exit line: base+6 indexes the
+      -- SmellYouLater row below, so WIN falls IPicked -> SmellYouLater and
+      -- LOSS jumps straight to SmellYouLater (both then walk-out + hide).
+      table.insert(rows, { "jump_if_false", base + 6 })
       table.insert(rows, { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
+      table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
       table.insert(rows, { "move_npc_to", 1, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
       ow.runner:run(rows, { npc = rival })

data/scripts/pallet_town.lua

@@ -10,15 +10,39 @@
 -- The girl, fisher and the four signs resolve automatically through the
 -- extracted text pointers (no script needed).
 
+-- Once the HALL OF FAME has been reached (EVENT_BEAT_CHAMPION_RIVAL, set
+-- alongside Commands.record_hall_of_fame) Oak offers the ProfOakData
+-- battle (data/trainers/parties.asm) -- three teams picked by the
+-- player's starter, mirroring the rival's type-advantage lineup, that go
+-- unused in the original ROM.
 return {
   talk = {
     TEXT_PALLETTOWN_OAK = {
-      { "face_player" },                                    -- 1
-      { "check_flag", "EVENT_GOT_STARTER" },                -- 2
-      { "jump_if_true", 6 },                                -- 3
-      { "show_text", "_PalletTownOakHeyWaitDontGoOutText" },-- 4
-      { "jump", 7 },                                        -- 5
-      { "show_text", "_PalletTownOakItsUnsafeText" },       -- 6
+      { "face_player" },                                             -- 1
+      { "check_flag", "EVENT_BEAT_CHAMPION_RIVAL" },                 -- 2
+      { "jump_if_false", 20 },                                       -- 3
+      { "check_flag", "EVENT_BEAT_PROF_OAK" },                       -- 4
+      { "jump_if_true", 20 },                                        -- 5
+      { "show_text", "OAK: So you want\nto test your\nskills on me?\f"
+        .. "Very well! Let\nme show you what\na real trainer\ncan do!" }, -- 6
+      { "check_flag", "EVENT_CHOSE_BULBASAUR" },                     -- 7
+      { "jump_if_false", 11 },                                       -- 8
+      { "start_battle", "trainer", "OPP_PROF_OAK", 3 },              -- 9  CHARIZARD
+      { "jump", 16 },                                                -- 10
+      { "check_flag", "EVENT_CHOSE_SQUIRTLE" },                      -- 11
+      { "jump_if_false", 15 },                                       -- 12
+      { "start_battle", "trainer", "OPP_PROF_OAK", 2 },              -- 13 VENUSAUR
+      { "jump", 16 },                                                -- 14
+      { "start_battle", "trainer", "OPP_PROF_OAK", 1 },              -- 15 BLASTOISE
+      { "jump_if_false", "end" },                                    -- 16
+      { "set_flag", "EVENT_BEAT_PROF_OAK" },                         -- 17
+      { "show_text", "OAK: Impressive!\nYou truly are a\nPOKéMON MASTER!" }, -- 18
+      { "jump", "end" },                                             -- 19
+      { "check_flag", "EVENT_GOT_STARTER" },                         -- 20
+      { "jump_if_true", 24 },                                        -- 21
+      { "show_text", "_PalletTownOakHeyWaitDontGoOutText" },         -- 22
+      { "jump", "end" },                                             -- 23
+      { "show_text", "_PalletTownOakItsUnsafeText" },                -- 24
     },
   },
 }

data/scripts/reds_house.lua

@@ -1,15 +1,23 @@
 -- Hand-ported from pret/pokered scripts/RedsHouse1F.asm.
--- Mom (RedsHouse1FMomText, text_asm) heals the party and shows the
--- "you should rest" / "looking great" dialogue.  The intro "wake up"
--- branch is tied to the unported intro cutscene, so the heal path is used.
+-- Mom (RedsHouse1FMomText): pre-starter shows the wake-up / Oak tip;
+-- after EVENT_GOT_STARTER, RedsHouse1FMomHealScript fades to white,
+-- heals, plays MUSIC_PKMN_HEALED, fades back, then "looking great".
 
 return {
   talk = {
     TEXT_REDSHOUSE1F_MOM = {
-      { "face_player" },
-      { "show_text", "_RedsHouse1FMomYouShouldRestText" },
-      { "heal_party" },
-      { "show_text", "_RedsHouse1FMomLookingGreatText" },
+      { "face_player" },                                          -- 1
+      { "check_flag", "EVENT_GOT_STARTER" },                      -- 2
+      { "jump_if_true", 6 },                                      -- 3
+      { "show_text", "_RedsHouse1FMomWakeUpText" },               -- 4
+      { "jump", "end" },                                          -- 5
+      -- RedsHouse1FMomHealScript
+      { "show_text", "_RedsHouse1FMomYouShouldRestText" },        -- 6
+      { "fade", "out", "white" },                                 -- 7  GBFadeOutToWhite
+      { "heal_party" },                                           -- 8
+      { "play_once", "Music_PkmnHealed" },                        -- 9  wait + restore map
+      { "fade", "in", "white" },                                  -- 10 GBFadeInFromWhite
+      { "show_text", "_RedsHouse1FMomLookingGreatText" },         -- 11
     },
   },
 }

data/scripts/story.lua

@@ -10,6 +10,39 @@ local M = {}
 -- -------------------------------------------------------------------
 
 M.VIRIDIAN_MART = {
+  -- scripts/ViridianMart.asm: the parcel hand-off is the map's DEFAULT
+  -- script, not a talk.  Entering with a starter and no parcel runs
+  -- ViridianMartDefaultScript -- the clerk calls out, then
+  -- StartSimulatingJoypadStates walks the player to the counter
+  -- (.PlayerMovement: PAD_LEFT 1, PAD_UP 2, door (3,7) -> counter (2,5))
+  -- and ViridianMartOaksParcelScript hands the parcel over.  The player
+  -- never presses A.
+  --
+  -- The RLE list is consumed back to front: DecodeRLEList fills forward
+  -- from wSimulatedJoypadStatesEnd, the script seeds wSimulatedJoypadStates-
+  -- Index with the count, and home/overworld.asm decrements that index
+  -- before each read.  So PAD_LEFT 1, PAD_UP 2 actually plays up, up, left,
+  -- and the walk ends facing the clerk.  Replaying the list front to back
+  -- put the player at the counter facing up instead (#235).  The player
+  -- never presses A.  This matters beyond convenience: the parcel gates
+  -- Oak's Pokedex and the old man clearing Route 2, so vanilla guarantees
+  -- it on entry rather than letting you walk out without it.
+  --
+  -- The talk branch below is kept as the fallback for a save that reaches
+  -- the counter without this having fired.
+  onEnter = function(game, ow)
+    local f = game.save.flags
+    if f.EVENT_OAK_GOT_PARCEL or f.EVENT_GOT_OAKS_PARCEL then return end
+    if not f.EVENT_GOT_STARTER then return end
+    ow:queueScript({
+      { "show_text", "_ViridianMartClerkYouCameFromPalletTownText" },
+      { "move_player", "up", 2 },
+      { "move_player", "left", 1 },
+      -- the quest text's last page is "{PLAYER} got\nOAK's PARCEL!"
+      { "give_item", "OAKS_PARCEL", 1, "_ViridianMartClerkParcelQuestText" },
+      { "set_flag", "EVENT_GOT_OAKS_PARCEL" },
+    })
+  end,
   talk = {
     TEXT_VIRIDIANMART_CLERK = {
       { "check_flag", "EVENT_OAK_GOT_PARCEL" },                       -- 1
@@ -33,42 +66,48 @@ M.VIRIDIAN_MART = {
 
 M.VIRIDIAN_CITY = {
   talk = {
-    -- the old man napping on the north path (scripts/ViridianCity.asm)
-    -- after his coffee, the old man offers the catch tutorial: not in a
-    -- hurry -> he demos catching a wild mon (BATTLE_TYPE_OLD_MAN)
+    -- The GAMBLER_ASLEEP at (18,9) (ViridianCityOldManSleepyText): he
+    -- only ever grumbles and shoves you back down -- he never wakes,
+    -- moves or hides.  The coffee ask and the catch tutorial belong to
+    -- the *other* old man, the walking SPRITE_GAMBLER at (17,5)
+    -- (TEXT_VIRIDIANCITY_OLD_MAN, below).  The two are swapped by the
+    -- Pokédex in data/scripts/oaks_lab.lua, not by talking to either.
     TEXT_VIRIDIANCITY_OLD_MAN_SLEEPY = {
-      { "check_flag", "EVENT_OAK_GOT_PARCEL" },                          -- 1
-      { "jump_if_true", 5 },                                             -- 2
-      { "show_text", "_ViridianCityOldManSleepyPrivatePropertyText" },   -- 3
-      { "jump", 14 },                                                    -- 4
-      { "face_player" },                                                 -- 5
-      { "ask", "_ViridianCityOldManHadMyCoffeeNowText" },                -- 6
-      { "jump_if_true", 12 },                                            -- 7 (in a hurry)
-      { "show_text", "_ViridianCityOldManKnowHowToCatchPokemonText" },   -- 8
-      { "show_text", "_ViridianCityOldManYouNeedToWeakenTheTargetText" }, -- 9
-      { "old_man_demo" },                                                -- 10
-      { "jump", 13 },                                                    -- 11
-      { "show_text", "_ViridianCityOldManTimeIsMoneyText" },             -- 12
-      { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" }, -- 13
+      { "show_text", "_ViridianCityOldManSleepyPrivatePropertyText" },   -- 1
+      { "move_player", "down", 1 },                                     -- 2
+    },
+
+    -- The walking old man at (17,5), shown once the Pokédex swaps him in
+    -- (ViridianCityOldManText).  "Are you in a hurry?" -- YES brushes you
+    -- off, NO leads into the catch tutorial: he explains, demos a catch
+    -- on a wild WEEDLE (BATTLE_TYPE_OLD_MAN), then comments afterwards.
+    -- pokered prints YouNeedToWeakenTheTarget *after* the demo battle
+    -- (ViridianCityOldManEndCatchTrainingScript), not before it.
+    TEXT_VIRIDIANCITY_OLD_MAN = {
+      { "face_player" },                                                 -- 1
+      { "ask", "_ViridianCityOldManHadMyCoffeeNowText" },                -- 2
+      { "jump_if_true", 8 },                                             -- 3 (yes = in a hurry)
+      { "show_text", "_ViridianCityOldManKnowHowToCatchPokemonText" },   -- 4
+      { "old_man_demo" },                                                -- 5
+      { "show_text", "_ViridianCityOldManYouNeedToWeakenTheTargetText" },-- 6
+      { "jump", 9 },                                                     -- 7
+      { "show_text", "_ViridianCityOldManTimeIsMoneyText" },             -- 8 (9 = end)
     },
   },
-  -- the sleeping old man lies across the Route 22 path (18,9): until
-  -- he moves you can't slip past on either side (scripts/ViridianCity
-  -- blocks the whole corridor, not just his tile)
+  -- ViridianCityCheckGotPokedexScript: the north corridor is gated on
+  -- EVENT_GOT_POKEDEX, NOT on the sleeper being hidden, and it triggers
+  -- on exactly one cell -- (19,9), the gap east of the sleeper (18,9)
+  -- and the girl (17,9).  With the Pokédex the check returns immediately
+  -- and you simply walk past at x=19.
   onStep = function(game, ow, x, y)
-    local gone = game.save.objectToggles and game.save.objectToggles.VIRIDIAN_CITY
-                 and game.save.objectToggles.VIRIDIAN_CITY.VIRIDIANCITY_OLD_MAN_SLEEPY == false
-    if gone then return false end
-    -- crossing north of his row through the 3-wide gap (x 17-19, y<=8)
-    if y <= 8 and x >= 17 and x <= 19 then
-      local TextBox = require("src.render.TextBox")
-      game.stack:push(TextBox.new(game,
-        game.data.text._ViridianCityOldManSleepyPrivatePropertyText
-        or "You can't go\nthrough here!\fThis is private\nproperty!",
-        function() ow:scriptMove(ow.player, "down", 1) end))
-      return true
-    end
-    return false
+    if game.save.flags and game.save.flags.EVENT_GOT_POKEDEX then return false end
+    if x ~= 19 or y ~= 9 then return false end
+    local TextBox = require("src.render.TextBox")
+    game.stack:push(TextBox.new(game,
+      game.data.text._ViridianCityOldManSleepyPrivatePropertyText
+      or "You can't go\nthrough here!\fThis is private\nproperty!",
+      function() ow:scriptMove(ow.player, "down", 1) end))
+    return true
   end,
 }
 
@@ -102,26 +141,145 @@ M.BLUES_HOUSE = {
 
 M.BILLS_HOUSE = {
   talk = {
-    TEXT_BILLSHOUSE_BILL_POKEMON = {
-      { "check_flag", "EVENT_GOT_SS_TICKET" },                     -- 1
-      { "jump_if_true", 11 },                                      -- 2
-      { "show_text", "_BillsHouseBillImNotAPokemonText" },         -- 3
-      { "show_text", "_BillsHouseBillNoYouGottaHelpText" },        -- 4
-      -- the cell-separator PC throws its switch
-      -- (bills_house_pc.asm BillsHouseInitiatedText: SFX_SWITCH)
-      { "play_sound", "Switch" },                                  -- 5
-      { "show_text", "_BillsHouseBillThankYouText" },              -- 6
+    -- BillsHouseBillPokemonText: "I'm not a POKéMON!", a YES/NO choice
+    -- (NO only adds "No, you gotta help!" before rejoining the YES
+    -- path), then the "get in the TELEPORTER" line and the monster
+    -- walking into the cell-separator machine
+    -- (BillsHousePokemonWalkToMachineScript: up 3, or around the player
+    -- when they stand in the way facing down), where it is hidden and
+    -- EVENT_BILL_SAID_USE_CELL_SEPARATOR arms the PC at (1,4) -- see
+    -- OverworldState.billsHousePC for the separator itself.
+    TEXT_BILLSHOUSE_BILL_POKEMON = function(game, ow, npc, done)
+      local TextBox = require("src.render.TextBox")
+      local t = game.data.text
+      local function toMachine()
+        game.stack:push(TextBox.new(game,
+          t._BillsHouseBillUseSeparationSystemText
+          or "When I'm in the\nTELEPORTER, run\nthe Cell\nSeparation System!", function()
+          local function entered()
+            local Commands = require("src.script.Commands")
+            Commands.hide_object({ game = game, save = game.save,
+                                   overworld = ow },
+                                 "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
+            game.save.flags.EVENT_BILL_SAID_USE_CELL_SEPARATOR = true
+            done()
+          end
+          if ow.player.facing == "down" then
+            -- the player is standing on his straight path: walk around
+            -- (.PokemonWalkAroundPlayerMovement)
+            ow:scriptMove(npc, "right", 1, function()
+              ow:scriptMove(npc, "up", 2, function()
+                ow:scriptMove(npc, "left", 1, function()
+                  ow:scriptMove(npc, "up", 1, entered)
+                end)
+              end)
+            end)
+          else
+            ow:scriptMove(npc, "up", 3, entered)
+          end
+        end))
+      end
+      game.stack:push(TextBox.new(game,
+        t._BillsHouseBillImNotAPokemonText or "Hey! I'm not a\nPOKéMON!",
+        nil, { choice = function(yes)
+          if yes then
+            toMachine()
+          else
+            game.stack:push(TextBox.new(game,
+              t._BillsHouseBillNoYouGottaHelpText
+              or "No! You gotta\nhelp me!", toMachine))
+          end
+        end }))
+    end,
+
+    -- BillsHouseBillSSTicketText (human Bill after the separation)
+    TEXT_BILLSHOUSE_BILL_SS_TICKET = {
+      { "face_player" },                                           -- 1
+      { "check_flag", "EVENT_GOT_SS_TICKET" },                     -- 2
+      { "jump_if_true", 12 },                                      -- 3
+      { "show_text", "_BillsHouseBillThankYouText" },              -- 4
       -- pokered gives first (GiveItem fills wStringBuffer), then prints
       -- the received text that reads it (scripts/BillsHouse.asm; the
       -- item id is S_S_TICKET in generated items.lua -- keyItem, so the
       -- sound_get_key_item jingle plays like BillsHouse.asm:196)
-      { "give_item", "S_S_TICKET", 1, false },                     -- 7
-      { "show_text", "_SSTicketReceivedText" },                    -- 8
-      { "set_flag", "EVENT_GOT_SS_TICKET" },                       -- 9
-      { "jump", 12 },                                              -- 10
-      { "show_text", "_BillsHouseBillCheckOutMyRarePokemonText" }, -- 11
+      { "give_item", "S_S_TICKET", 1, false },                     -- 5
+      { "show_text", "_SSTicketReceivedText" },                    -- 6
+      { "set_flag", "EVENT_GOT_SS_TICKET" },                       -- 7
+      -- The two Cerulean guards are a SWAP PAIR, not scenery
+      -- (BillsHouse.asm:174-178): handing over the ticket shows GUARD1 at
+      -- (28,12) and hides GUARD2 at (27,12).  This matters far more than it
+      -- looks: (27,12) is the ONLY walkable neighbour of the trashed
+      -- house's south door at (27,11), and that house is one of the two
+      -- ways through the fence that splits Cerulean in half (the badge
+      -- house is the other).  Leaving GUARD2 up forever severs the city --
+      -- the gym/mart half can never reach the Route 5 exit.
+      -- Same swap fires after the TM28 Rocket (CeruleanCity_2.asm
+      -- CeruleanHideRocket), so either route opens the path.
+      { "show_object", "CERULEAN_CITY", "CERULEANCITY_GUARD1" },   -- 8
+      { "hide_object", "CERULEAN_CITY", "CERULEANCITY_GUARD2" },   -- 9
+      { "show_text", "_BillsHouseBillWhyDontYouGoInsteadOfMeText" }, -- 10
+      { "jump", 13 },                                              -- 11
+      { "show_text", "_BillsHouseBillWhyDontYouGoInsteadOfMeText" }, -- 12
+    },
+
+    TEXT_BILLSHOUSE_BILL_CHECK_OUT_MY_RARE_POKEMON = {
+      { "face_player" },                                           -- 1
+      { "show_text", "_BillsHouseBillCheckOutMyRarePokemonText" }, -- 2
     },
   },
+  -- repair saves that already got the ticket under the old collapsed
+  -- script (the monster never hidden, human Bill never shown)
+  onEnter = function(game, ow)
+    local flags = game.save.flags
+    if flags.EVENT_GOT_SS_TICKET
+       and not flags.EVENT_USED_CELL_SEPARATOR_ON_BILL then
+      local Commands = require("src.script.Commands")
+      local ctx = { game = game, save = game.save, overworld = ow }
+      Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
+      Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL1")
+      flags.EVENT_BILL_SAID_USE_CELL_SEPARATOR = true
+      flags.EVENT_USED_CELL_SEPARATOR_ON_BILL = true
+      flags.EVENT_MET_BILL = true
+      flags.EVENT_MET_BILL_2 = true
+    end
+    -- After Route25ToggleBillsScript, BILL2 is the visible human Bill
+    -- ("check out my rare POKéMON").  Re-apply on enter so a mid-house
+    -- load still matches the toggles if the pool was rebuilt.
+    if flags.EVENT_LEFT_BILLS_HOUSE_AFTER_HELPING then
+      local Commands = require("src.script.Commands")
+      local ctx = { game = game, save = game.save, overworld = ow }
+      Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
+      Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL1")
+      Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL2")
+    end
+  end,
+}
+
+-- -------------------------------------------------------------------
+-- Route 25 outside Bill's house (scripts/Route25.asm
+-- Route25ToggleBillsScript): leaving after the SS Ticket arms the
+-- Eevee PC list and swaps human Bill to his post-help dialogue NPC.
+-- Leaving mid-quest (Bill still in the machine) puts the monster back.
+-- -------------------------------------------------------------------
+
+M.ROUTE_25 = {
+  onEnter = function(game, ow)
+    local flags = game.save.flags
+    if flags.EVENT_LEFT_BILLS_HOUSE_AFTER_HELPING then return end
+    local Commands = require("src.script.Commands")
+    local ctx = { game = game, save = game.save, overworld = ow }
+    if not flags.EVENT_MET_BILL_2 then
+      flags.EVENT_BILL_SAID_USE_CELL_SEPARATOR = nil
+      Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL_POKEMON")
+      return
+    end
+    if not flags.EVENT_GOT_SS_TICKET then return end
+    flags.EVENT_LEFT_BILLS_HOUSE_AFTER_HELPING = true
+    -- TOGGLE_NUGGET_BRIDGE_GUY (ROUTE24_COOLTRAINER_M1)
+    Commands.hide_object(ctx, "ROUTE_24", "ROUTE24_COOLTRAINER_M1")
+    Commands.hide_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL1")
+    Commands.show_object(ctx, "BILLS_HOUSE", "BILLSHOUSE_BILL2")
+  end,
 }
 
 -- -------------------------------------------------------------------
@@ -142,17 +300,63 @@ M.VERMILION_CITY = {
     game.save.trashPuzzle = puz
     puz.first = love.math.random(0, 7) * 2
   end,
+  -- VermilionCityDefaultScript's per-frame SSAnneTicketCheckCoords check:
+  -- the unguarded cell (18,30) just west of the sailor leads straight
+  -- onto the dock warp.  Stepping onto it facing down always runs the
+  -- sailor dialog (DisplayTextID TEXT_VERMILIONCITY_SAILOR1); only a
+  -- ticket while the ship is still docked lets the player continue --
+  -- otherwise they are walked back up.  The sailor himself never hides.
+  onStep = function(game, ow, x, y)
+    if x ~= 18 or y ~= 30 then return false end
+    if ow.player.facing ~= "down" then return false end
+    local Flags = require("src.script.Flags")
+    local t = game.data.text
+    local TextBox = require("src.render.TextBox")
+    local shipLeft = Flags.get(game.save, "EVENT_SS_ANNE_LEFT")
+    local hasTicket = (game.save.inventory.S_S_TICKET or 0) > 0
+    if shipLeft then
+      game.stack:push(TextBox.new(game,
+        t._VermilionCitySailor1ShipSetSailText or "The ship set sail.",
+        function() ow:scriptMove(ow.player, "up", 1) end))
+      return true
+    end
+    -- Walk-past is never facing-right / inFrontOfOrBehindGuardCoords, so
+    -- VermilionCitySailor1Text always takes .greet_player_and_check_ticket:
+    -- DoYouHaveATicket, then FlashedTicket (allow through) or YouNeedATicket
+    -- (walk back).  Returning true while the box is up also blocks the
+    -- dock warp on this step.
+    local ask = t._VermilionCitySailor1DoYouHaveATicketText
+      or "Welcome to S.S.\nANNE!\fExcuse me, do you\nhave a ticket?"
+    if hasTicket then
+      game.stack:push(TextBox.new(game,
+        ask .. "\f"
+        .. (t._VermilionCitySailor1FlashedTicketText
+            or "{PLAYER} flashed\nthe S.S.TICKET!")))
+      return true
+    end
+    game.stack:push(TextBox.new(game,
+      ask .. "\f"
+      .. (t._VermilionCitySailor1YouNeedATicketText
+          or "You need a ticket\nto get aboard."),
+      function() ow:scriptMove(ow.player, "up", 1) end))
+    return true
+  end,
   talk = {
-    -- the sailor guarding the dock gangway
+    -- the sailor guarding the dock gangway (VermilionCitySailor1Text):
+    -- flashing the ticket just lets you through -- he never hides, and
+    -- once the ship has sailed he only reports it gone
     TEXT_VERMILIONCITY_SAILOR1 = {
       { "face_player" },                                             -- 1
-      { "show_text", "_VermilionCitySailor1WelcomeToSSAnneText" },   -- 2
-      { "check_item", "S_S_TICKET" },                                -- 3
-      { "jump_if_false", 8 },                                        -- 4
-      { "show_text", "_VermilionCitySailor1FlashedTicketText" },     -- 5
-      { "hide_object", "VERMILION_CITY", "VERMILIONCITY_SAILOR1" },  -- 6
-      { "jump", 9 },                                                 -- 7
-      { "show_text", "_VermilionCitySailor1YouNeedATicketText" },    -- 8
+      { "check_flag", "EVENT_SS_ANNE_LEFT" },                        -- 2
+      { "jump_if_true", 11 },                                        -- 3
+      { "show_text", "_VermilionCitySailor1DoYouHaveATicketText" },  -- 4
+      { "check_item", "S_S_TICKET" },                                -- 5
+      { "jump_if_false", 9 },                                        -- 6
+      { "show_text", "_VermilionCitySailor1FlashedTicketText" },     -- 7
+      { "jump", 12 },                                                -- 8
+      { "show_text", "_VermilionCitySailor1YouNeedATicketText" },    -- 9
+      { "jump", 12 },                                                -- 10
+      { "show_text", "_VermilionCitySailor1ShipSetSailText" },       -- 11
     },
   },
 }
@@ -175,18 +379,21 @@ M.SS_ANNE_2F = {
 
 M.SS_ANNE_CAPTAINS_ROOM = {
   talk = {
+    -- SSAnneCaptainsRoomCaptainText: after the rub line's text_asm tail,
+    -- pokered plays MUSIC_PKMN_HEALED (scripts/SSAnneCaptainsRoom.asm).
     TEXT_SSANNECAPTAINSROOM_CAPTAIN = {
       { "check_flag", "EVENT_GOT_HM01" },                                 -- 1
-      { "jump_if_true", 9 },                                              -- 2
+      { "jump_if_true", 10 },                                             -- 2
       { "show_text", "_SSAnneCaptainsRoomRubCaptainsBackText" },          -- 3
-      { "show_text", "_SSAnneCaptainsRoomCaptainIFeelMuchBetterText" },   -- 4
+      { "play_once", "Music_PkmnHealed" },                                -- 4
+      { "show_text", "_SSAnneCaptainsRoomCaptainIFeelMuchBetterText" },   -- 5
       -- give-then-print like scripts/SSAnneCaptainsRoom.asm (GiveItem
       -- fills wStringBuffer; the received text reads it)
-      { "give_item", "HM_CUT", 1, false },                                -- 5
-      { "show_text", "_SSAnneCaptainsRoomCaptainReceivedHM01Text" },      -- 6
-      { "set_flag", "EVENT_GOT_HM01" },                                   -- 7
-      { "jump", 10 },                                                     -- 8
-      { "show_text", "_SSAnneCaptainsRoomCaptainNotSickAnymoreText" },    -- 9
+      { "give_item", "HM_CUT", 1, false },                                -- 6
+      { "show_text", "_SSAnneCaptainsRoomCaptainReceivedHM01Text" },      -- 7
+      { "set_flag", "EVENT_GOT_HM01" },                                   -- 8
+      { "jump", 11 },                                                     -- 9
+      { "show_text", "_SSAnneCaptainsRoomCaptainNotSickAnymoreText" },    -- 10
     },
   },
 }
@@ -196,7 +403,93 @@ M.SS_ANNE_CAPTAINS_ROOM = {
 -- MrFujisHouse.asm; the teleport back to his house is a warp)
 -- -------------------------------------------------------------------
 
+-- scripts/PokemonTower7F.asm: after each Rocket loses,
+-- PokemonTower7FEndBattleScript shows its EndBattle text (EndTrainerBattle),
+-- prints its AfterBattle text (DisplayTextID), then
+-- PokemonTower7FRocketLeaveMovementScript walks the grunt off toward the
+-- (9,16) stairs (MoveSprite) and PokemonTower7FHideNPCScript despawns it
+-- (HideObject).  Without this the beaten grunts stood in the corridor
+-- forever (#200).
+local POKEMON_TOWER_7F_ROCKETS = {
+  { index = 1, name = "POKEMONTOWER7F_ROCKET1",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_0",
+    after = "_PokemonTower7FRocket1AfterBattleText" },
+  { index = 2, name = "POKEMONTOWER7F_ROCKET2",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_1",
+    after = "_PokemonTower7FRocket2AfterBattleText" },
+  { index = 3, name = "POKEMONTOWER7F_ROCKET3",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_2",
+    after = "_PokemonTower7FRocket3AfterBattleText" },
+}
+
+-- PokemonTower7FNPCCoordMovementTable, keyed by the PLAYER's tile ("x,y")
+-- at the engagement (both the talk and the sight walk-up leave the player on
+-- the tile the vanilla table indexes).  Each list is that entry's
+-- NPC_MOVEMENT_* exit, applied from the grunt's current tile.  The exact
+-- tables are one per grunt (dbmapcoord bytes decoded back to x,y).
+local POKEMON_TOWER_7F_EXITS = {
+  [1] = { -- ROCKET1 @ (9,11), faces RIGHT
+    ["9,12"]  = { "right", "down", "down", "down", "down", "down", "left" },
+    ["10,11"] = { "down", "right", "down", "down", "down", "down" },
+    ["11,11"] = { "down", "down", "down", "down", "down" },
+    ["12,11"] = { "down", "down", "down", "down", "down" },
+  },
+  [2] = { -- ROCKET2 @ (12,9), faces LEFT
+    ["12,10"] = { "left", "down", "down", "down", "down", "down", "down" },
+    ["11,9"]  = { "down", "down", "down", "left", "down", "down" },
+    ["10,9"]  = { "down", "down", "down", "down", "down" },
+    ["9,9"]   = { "down", "down", "down", "down", "down" },
+  },
+  [3] = { -- ROCKET3 @ (9,7), faces RIGHT
+    ["9,8"]  = { "right", "down", "down", "down", "down", "down", "down" },
+    ["10,7"] = { "down", "down", "down", "down", "down" },
+    ["11,7"] = { "down", "down", "down", "down", "down" },
+    ["12,7"] = { "down", "down", "down", "down", "down" },
+  },
+}
+-- The vanilla table only lists the sight/talk tiles the map geometry allows;
+-- a plain down-walk keeps any other engagement tile (e.g. talking from the
+-- side) safe -- it still clears the corridor and despawns the grunt.
+local POKEMON_TOWER_7F_EXIT_FALLBACK =
+  { "down", "down", "down", "down", "down" }
+
 M.POKEMON_TOWER_7F = {
+  -- Repair saves that beat a grunt before the exit walk was ported: in
+  -- vanilla HideObject persists (wMissableObjectFlags), so a beaten grunt is
+  -- still gone on re-entry.  hide_object below writes objectToggles for new
+  -- wins; this hides any grunt whose BEAT flag is already set.
+  onEnter = function(game, ow)
+    local Commands = require("src.script.Commands")
+    local ctx = { game = game, save = game.save, overworld = ow }
+    for _, r in ipairs(POKEMON_TOWER_7F_ROCKETS) do
+      if game.save.flags[r.beat] then
+        Commands.hide_object(ctx, "POKEMON_TOWER_7F", r.name)
+      end
+    end
+  end,
+  -- runVictoryHook fires after every trainer win on the map (both the sight
+  -- and talk paths route through engageTrainer -> checkVictoryRewards), so
+  -- this walks off whichever grunt was just beaten but is still standing.
+  -- The AfterBattle text + walk queue UNDER the EndBattle box engageTrainer
+  -- pushes right after, giving the vanilla order: EndBattle, AfterBattle,
+  -- walk, despawn.
+  onVictory = function(game, ow)
+    if ow.runner:isRunning() then return end
+    for _, r in ipairs(POKEMON_TOWER_7F_ROCKETS) do
+      local npc = ow:npcByIndex(r.index)
+      if npc and game.save.flags[r.beat] then
+        local key = ow.player.cellX .. "," .. ow.player.cellY
+        local dirs = (POKEMON_TOWER_7F_EXITS[r.index] or {})[key]
+                     or POKEMON_TOWER_7F_EXIT_FALLBACK
+        ow.runner:run({
+          { "show_text", r.after },                       -- DisplayTextID
+          { "walk_npc", r.index, dirs },                  -- MoveSprite
+          { "hide_object", "POKEMON_TOWER_7F", r.name },  -- HideObject
+        }, { npc = npc })
+        return
+      end
+    end
+  end,
   talk = {
     TEXT_POKEMONTOWER7F_MR_FUJI = {
       { "face_player" },                                  -- 1
@@ -208,7 +501,17 @@ M.POKEMON_TOWER_7F = {
       { "show_object", "MR_FUJIS_HOUSE", "MRFUJISHOUSE_MR_FUJI" },   -- 5
       { "hide_object", "SAFFRON_CITY", "SAFFRONCITY_ROCKET8" },      -- 6
       { "show_object", "SAFFRON_CITY", "SAFFRONCITY_ROCKET9" },      -- 7
-      { "warp", "MR_FUJIS_HOUSE", 3, 3, "down" },         -- 8
+      -- pokered warps to wDestinationWarpID $1 (0-based) -- the house's
+      -- SECOND warp, the door mat at (3,7) -- facing UP
+      -- (PokemonTower7FWarpToMrFujiHouseScript: SPRITE_FACING_UP +
+      -- hWarpDestinationMap MR_FUJIS_HOUSE). Landing (3,3) instead put
+      -- the player at the Pokédex table, and the route's first waypoint
+      -- (3,7) then stepped onto a LIVE door mat and exited the house
+      -- before ever talking to Fuji -- so the POKE_FLUTE was never
+      -- collected and the Route 16 SNORLAX sealed the map. The arrival
+      -- mat itself is inert until stepped off (warpEntryCell), which is
+      -- what makes the vanilla coordinates safe.
+      { "warp", "MR_FUJIS_HOUSE", 3, 7, "up" },           -- 8
     },
   },
 }
@@ -343,6 +646,50 @@ M.WARDENS_HOUSE = {
 -- -------------------------------------------------------------------
 
 M.SILPH_CO_11F = {
+  -- Giovanni's battle is a COORDINATE TRIGGER, not a talk.
+  -- SilphCo11FDefaultScript (scripts/SilphCo11F.asm) checks
+  -- .PlayerCoordsArray -- (6,13) and (7,12) -- every frame while
+  -- EVENT_BEAT_SILPH_CO_GIOVANNI is unset: standing there shows his text,
+  -- walks him three tiles down (.GiovanniMovement), and starts the fight.
+  -- He also has no trainer-header entry, so sight engagement never fires
+  -- either. Without this hook he was a talk-only statue four tiles away
+  -- from anything the route (or a vanilla-faithful player walking the same
+  -- line) would touch, and the whole Silph ending -- the flag, the Master
+  -- Ball, the Saffron streets clearing -- silently never happened.
+  --
+  -- engageTrainer shows TEXT_SILPHCO11F_GIOVANNI as the battle text and,
+  -- via victories.lua OPP_GIOVANNI#2, sets the event on a win; a loss
+  -- sets nothing, so the trigger re-arms exactly as vanilla does.
+  onStep = function(game, ow, x, y)
+    if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then return false end
+    if not ((x == 6 and y == 13) or (x == 7 and y == 12)) then return false end
+    local gio
+    for _, npc in ipairs(ow.npcs) do
+      if npc.def and npc.def.name == "SILPHCO11F_GIOVANNI" then gio = npc break end
+    end
+    if not gio or ow:trainerDefeated(gio) then return false end
+    ow:scriptMove(gio, "down", 3, function()
+      gio:facePlayer(ow.player)
+      ow:engageTrainer(gio, function()
+        -- SilphCo11FTeamRocketLeavesScript: Giovanni leaves the floor
+        -- 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")
+        end
+      end)
+    end)
+    return true
+  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")
+    end
+  end,
   talk = {
     TEXT_SILPHCO11F_SILPH_PRESIDENT = {
       { "face_player" },                                                     -- 1
@@ -363,7 +710,8 @@ M.SILPH_CO_11F = {
 -- -------------------------------------------------------------------
 -- Victory Road boulder switches (scripts/VictoryRoad1F/2F/3F.asm):
 -- a boulder resting on a switch removes a barrier block; the 3F hole
--- drops a boulder down to the 2F switch.
+-- drops a boulder down to the 2F switch, and also dungeon-warps the
+-- player (IsPlayerOnDungeonWarp + DungeonWarpList/Data -> 2F at 22,16).
 -- -------------------------------------------------------------------
 
 local function boulderAt(ow, x, y)
@@ -429,6 +777,18 @@ M.VICTORY_ROAD_3F = {
       Commands.show_object(ctx, "VICTORY_ROAD_2F", "VICTORYROAD2F_BOULDER")
     end
   end,
+  -- scripts/VictoryRoad3F.asm VictoryRoad3FDefaultScript: the same hole
+  -- is a dungeon warp for the player (wDungeonWarpDestinationMap =
+  -- VICTORY_ROAD_2F, wWhichDungeonWarp = 2 -> DungeonWarpData 22,16).
+  -- Mirrors POKEMON_MANSION_3F.onStep; CAVERN $22 is walkable so the
+  -- fall is onStep, not a collision block.
+  onStep = function(game, ow, x, y)
+    if x == 23 and y == 15 then
+      ow:startWarpTo("VICTORY_ROAD_2F", 22, 16, ow.player.facing)
+      return true
+    end
+    return false
+  end,
 }
 
 -- -------------------------------------------------------------------
@@ -441,6 +801,16 @@ M.VICTORY_ROAD_3F = {
 -- IndigoPlateauLobby.asm) so the champion is re-fightable on rematches,
 -- like pokered's re-entry cutscene.  EVENT_BEAT_CHAMPION_RIVAL stays set
 -- forever (postgame gates like the Cerulean cave guard read it).
+--
+-- pokered forces the fight on map entry: Agatha's victory arms
+-- SCRIPT_CHAMPIONSROOM_PLAYER_ENTERS (scripts/AgathasRoom.asm), and
+-- ChampionsRoomPlayerEntersScript then runs RivalEntrance_RLEMovement
+-- (up 1, right 1, up 3) before ChampionsRoomRivalReadyToBattleScript.
+-- The rival object has no trainer header / sight range, so without that
+-- entrance script the player can walk past (issue #99).  We arm on the
+-- run flag instead of Agatha's victory bit: same observable effect for
+-- first clear and Indigo rematches, without a cross-map script pointer.
+--
 -- scripts/ChampionsRoom.asm ChampionsRoomRivalDefeatedScript ->
 -- OakArrivesScript -> OakCongratulatesPlayerScript ->
 -- OakDisappointedWithRivalScript -> OakComeWithMeScript -> OakExitsScript,
@@ -449,43 +819,69 @@ M.VICTORY_ROAD_3F = {
 -- itself is NOT run here: it belongs to the HALL_OF_FAME room script
 -- (scripts/HallOfFame.asm), so we set a one-shot marker and warp; the room
 -- onEnter (M.HALL_OF_FAME below) drives the HoF Oak speech + record.
+local championsRoomRivalScript = {
+  { "face_player" },                                        -- 1
+  { "check_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },   -- 2
+  { "jump_if_true", 25 },                                   -- 3  past end
+  { "show_text", "_ChampionsRoomRivalIntroText" },          -- 4
+  { "rival_battle", "OPP_RIVAL3", 1 },                      -- 5
+  { "jump_if_false", 25 },                                  -- 6  past end
+  { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },     -- 7
+  { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL" },              -- 8
+  -- ChampionsRoomRivalDefeatedScript re-displays TEXT_CHAMPIONSROOM_RIVAL,
+  -- whose text_asm takes the EVENT_BEAT_CHAMPION_RIVAL branch =
+  -- _ChampionsRoomRivalAfterBattleText (the in-battle _RivalDefeatedText
+  -- is the port's generic "<PLAYER> defeated BLUE!" engine line instead).
+  { "show_text", "_ChampionsRoomRivalAfterBattleText" },    -- 9
+  -- ChampionsRoomOakArrivesScript: Music_Cities1AlternateTempo
+  -- (Cities1, kept into HALL_OF_FAME like BIT_NO_MAP_MUSIC after
+  -- defeating RIVAL3), then Oak's "{PLAYER}!" + reveal + walk in
+  { "play_music", "Music_Cities1", { keep = true } },       -- 10
+  { "show_text", "_ChampionsRoomOakText" },                 -- 11
+  { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 12
+  { "move_npc", 2, "up", 5 },                               -- 13 OakEntranceAfterVictoryMovement
+  -- OakCongratulatesPlayerScript: rival faces left, Oak faces down
+  { "face_object", 1, "left" },                             -- 14
+  { "face_object", 2, "down" },                             -- 15
+  { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 16
+  -- OakDisappointedWithRivalScript: Oak turns to the rival (right)
+  { "face_object", 2, "right" },                            -- 17
+  { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 18
+  -- OakComeWithMeScript: Oak faces down again, then exits up
+  { "face_object", 2, "down" },                             -- 19
+  { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 20
+  { "move_npc", 2, "up", 2 },                               -- 21 OakExitChampionsRoomMovement
+  { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 22
+  -- hand the induction off to the HALL_OF_FAME room (consumed by its
+  -- onEnter), then warp up into it (destWarp 1 lands at (4,7) facing up)
+  { "set_field", "pendingHallOfFame", true },               -- 23
+  { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 24
+}
+
 M.CHAMPIONS_ROOM = {
+  onEnter = function(game, ow)
+    if game.save.flags.EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN then return end
+    -- Lance entrance warps land at y=7; HoF return warps land at y=0.
+    -- Only the south entry should run ChampionsRoomPlayerEntersScript.
+    if ow.player.cellY < 7 then return end
+    local rival
+    for _, npc in ipairs(ow.npcs) do
+      if npc.def and npc.def.name == "CHAMPIONSROOM_RIVAL" then
+        rival = npc
+        break
+      end
+    end
+    -- RivalEntrance_RLEMovement, then the battle/Oak script (queued
+    -- separately so talk-script jump indices stay 1-based as written).
+    ow:queueScript({
+      { "move_player", "up", 1 },
+      { "move_player", "right", 1 },
+      { "move_player", "up", 3 },
+    })
+    ow:queueScript(championsRoomRivalScript, { npc = rival })
+  end,
   talk = {
-    TEXT_CHAMPIONSROOM_RIVAL = {
-      { "face_player" },                                        -- 1
-      { "check_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },   -- 2
-      { "jump_if_true", 24 },                                   -- 3
-      { "show_text", "_ChampionsRoomRivalIntroText" },          -- 4
-      { "rival_battle", "OPP_RIVAL3", 1 },                      -- 5
-      { "jump_if_false", 24 },                                  -- 6
-      { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },     -- 7
-      { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL" },              -- 8
-      -- ChampionsRoomRivalDefeatedScript re-displays TEXT_CHAMPIONSROOM_RIVAL,
-      -- whose text_asm takes the EVENT_BEAT_CHAMPION_RIVAL branch =
-      -- _ChampionsRoomRivalAfterBattleText (the in-battle _RivalDefeatedText
-      -- is the port's generic "<PLAYER> defeated BLUE!" engine line instead).
-      { "show_text", "_ChampionsRoomRivalAfterBattleText" },    -- 9
-      -- ChampionsRoomOakArrivesScript: Oak's "{PLAYER}!" then reveal + walk in
-      { "show_text", "_ChampionsRoomOakText" },                 -- 10
-      { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 11
-      { "move_npc", 2, "up", 5 },                               -- 12 OakEntranceAfterVictoryMovement (3,7)->(3,2)
-      -- OakCongratulatesPlayerScript: rival faces left, Oak faces down
-      { "face_object", 1, "left" },                             -- 13
-      { "face_object", 2, "down" },                             -- 14
-      { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 15
-      -- OakDisappointedWithRivalScript: Oak turns to the rival (right)
-      { "face_object", 2, "right" },                            -- 16
-      { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 17
-      -- OakComeWithMeScript: Oak faces down again, then exits up
-      { "face_object", 2, "down" },                             -- 18
-      { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 19
-      { "move_npc", 2, "up", 2 },                               -- 20 OakExitChampionsRoomMovement (3,2)->(3,0)
-      { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 21
-      -- hand the induction off to the HALL_OF_FAME room (consumed by its
-      -- onEnter), then warp up into it (destWarp 1 lands at (4,7) facing up)
-      { "set_field", "pendingHallOfFame", true },               -- 22
-      { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 23
-    },
+    TEXT_CHAMPIONSROOM_RIVAL = championsRoomRivalScript,
   },
 }
 
@@ -515,6 +911,29 @@ M.HALL_OF_FAME = {
     local toggles = game.save.objectToggles and game.save.objectToggles.HALL_OF_FAME
     if toggles then toggles.HALLOFFAME_OAK = nil end
 
+    -- Make the Hall of Fame recording machine interactable.  The console
+    -- juts from the north wall as the two solid cells (4,1) and (5,1); a
+    -- sign on each lets the player face the machine (from below, or from
+    -- either side) and press A to run the TEXT_HALLOFFAME_PC talk script.
+    -- maps.lua is generated from the ROM and gitignored, so the sign is
+    -- injected here (a tracked script) rather than baked into map data.
+    local def = ow.map.def
+    def.signs = def.signs or {}
+    local present = false
+    for _, s in ipairs(def.signs) do
+      if s.text == "TEXT_HALLOFFAME_PC" then present = true break end
+    end
+    if not present then
+      table.insert(def.signs, { text = "TEXT_HALLOFFAME_PC", x = 4, y = 1 })
+      table.insert(def.signs, { text = "TEXT_HALLOFFAME_PC", x = 5, y = 1 })
+    end
+    -- the live Map instance built its signAt lookup from def.signs before
+    -- this hook ran, so rebuild it (idempotent) to pick up the injection
+    ow.map.signAt = {}
+    for _, s in ipairs(def.signs) do
+      ow.map.signAt[s.y * ow.map.widthCells + s.x] = s
+    end
+
     if not game.save.pendingHallOfFame then return end
     game.save.pendingHallOfFame = false
     ow:queueScript({
@@ -528,6 +947,21 @@ M.HALL_OF_FAME = {
       { "record_hall_of_fame" },                       -- predef HallOfFamePC: induction + credits
     })
   end,
+  talk = {
+    -- The recording machine doubles as a "warp home" PC: a YES/NO prompt
+    -- that teleports back to the new-game bedroom spawn (special_warps.asm
+    -- NewGameWarp: REDS_HOUSE_2F, 3, 6, facing down).  Fabricated
+    -- convenience -- there is no such prompt in the original ROM.
+    -- Heal + remember_outdoor so house LAST_MAP mats land in Pallet, not
+    -- Indigo Plateau (issue #103 escape path for already-stuck saves).
+    TEXT_HALLOFFAME_PC = {
+      { "ask", "Return to\nPALLET TOWN?" },             -- 1  YES/NO -> lastCheck
+      { "jump_if_false", "end" },                       -- 2  NO: back away
+      { "heal_party" },                                 -- 3
+      { "remember_outdoor", "PALLET_TOWN", 5, 6 },       -- 4  LAST_MAP -> Pallet door
+      { "warp", "REDS_HOUSE_2F", 3, 6, "down" },        -- 5  YES: home to your room
+    },
+  },
 }
 
 -- -------------------------------------------------------------------
@@ -538,35 +972,86 @@ M.HALL_OF_FAME = {
 
 M.CERULEAN_CITY = {
   talk = {
+    -- CeruleanCityRivalText: Bill line once beaten; pre-battle otherwise.
+    -- Post-fight walk matches CeruleanCityMovement4 (right then into town).
     TEXT_CERULEANCITY_RIVAL = {
-      { "face_player" },                                    -- 1
-      { "check_flag", "EVENT_BEAT_CERULEAN_RIVAL" },        -- 2
-      { "jump_if_true", 9 },                                -- 3
-      { "show_text", "_CeruleanCityRivalPreBattleText" },   -- 4
-      { "rival_battle", "OPP_RIVAL1", 7 },                  -- 5
-      { "jump_if_false", 10 },                              -- 6
-      { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },          -- 7
-      { "show_text", "_CeruleanCityRivalDefeatedText" },    -- 8
-      { "jump", 10 },                                       -- 9
+      { "face_player" },                                         -- 1
+      { "check_flag", "EVENT_BEAT_CERULEAN_RIVAL" },             -- 2
+      { "jump_if_true", 13 },                                    -- 3
+      { "show_text", "_CeruleanCityRivalPreBattleText" },        -- 4
+      { "rival_battle", "OPP_RIVAL1", 7 },                       -- 5
+      { "jump_if_false", "end" },                                -- 6
+      { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },               -- 7
+      { "show_text", "_CeruleanCityRivalDefeatedText" },         -- 8
+      { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 9
+      { "walk_npc", 1, { "right", "down", "down", "down",
+                         "down", "down", "down" } },             -- 10
+      { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 11
+      { "jump", "end" },                                         -- 12
+      { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 13
     },
   },
 }
 
+-- PokemonTower2F.asm: after the battle, PokemonTower2FDefeatedRivalScript
+-- walks him out (RightThenDown vs DownThenRight from EVENT_POKEMON_TOWER_
+-- RIVAL_ON_LEFT) then HideObject TOGGLE_POKEMON_TOWER_2F_RIVAL.  Player
+-- at (15,5) is the ON_LEFT case.
+local TOWER_RIVAL_EXIT_RIGHT_THEN_DOWN =
+  { "right", "down", "down", "right", "down", "down", "right", "right" }
+local TOWER_RIVAL_EXIT_DOWN_THEN_RIGHT =
+  { "down", "down", "right", "right", "right", "right", "down", "down" }
+
+local function pokemonTower2FRivalScript(playerX)
+  local exitDirs = (playerX == 15)
+    and TOWER_RIVAL_EXIT_DOWN_THEN_RIGHT
+    or TOWER_RIVAL_EXIT_RIGHT_THEN_DOWN
+  return {
+    { "face_player" },                                            -- 1
+    { "check_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },           -- 2
+    { "jump_if_true", 12 },                                       -- 3
+    { "show_text", "_PokemonTower2FRivalWhatBringsYouHereText" }, -- 4
+    { "rival_battle", "OPP_RIVAL2", 4 },                          -- 5
+    { "jump_if_false", "end" },                                   -- 6 loss: stay
+    { "set_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },             -- 7
+    { "show_text", "_PokemonTower2FRivalDefeatedText" },          -- 8
+    { "walk_npc", 1, exitDirs },                                  -- 9
+    { "hide_object", "POKEMON_TOWER_2F", "POKEMONTOWER2F_RIVAL" }, -- 10
+    { "jump", "end" },                                            -- 11
+    { "show_text", "_PokemonTower2FRivalHowsYourDexText" },       -- 12
+  }
+end
+
 M.POKEMON_TOWER_2F = {
+  rivalScript = pokemonTower2FRivalScript,
   talk = {
-    TEXT_POKEMONTOWER2F_RIVAL = {
-      { "face_player" },                                            -- 1
-      { "check_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },           -- 2
-      { "jump_if_true", 10 },                                       -- 3
-      { "show_text", "_PokemonTower2FRivalWhatBringsYouHereText" }, -- 4
-      { "rival_battle", "OPP_RIVAL2", 4 },                          -- 5
-      { "jump_if_false", 11 },                                      -- 6
-      { "set_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },             -- 7
-      { "show_text", "_PokemonTower2FRivalDefeatedText" },          -- 8
-      { "jump", 11 },                                               -- 9
-      { "show_text", "_PokemonTower2FRivalHowsYourDexText" },       -- 10
-    },
+    TEXT_POKEMONTOWER2F_RIVAL = function(game, ow, npc, done)
+      ow.runner:run(pokemonTower2FRivalScript(ow.player.cellX),
+                    { npc = npc, onDone = done })
+    end,
   },
+  -- Saves that beat him before the exit walk was ported still have the
+  -- flag but a visible rival; hide on enter like BillsHouse repairs.
+  onEnter = function(game, ow)
+    if not game.save.flags.EVENT_BEAT_POKEMON_TOWER_RIVAL then return end
+    local Commands = require("src.script.Commands")
+    Commands.hide_object({ game = game, save = game.save, overworld = ow },
+                         "POKEMON_TOWER_2F", "POKEMONTOWER2F_RIVAL")
+  end,
+  -- PokemonTower2FDefaultScript: walking past the rival's tile forces
+  -- the encounter (ArePlayerCoordsInArray on (15,5)/(14,6)) -- he never
+  -- waits to be talked to
+  onStep = function(game, ow, x, y)
+    if game.save.flags.EVENT_BEAT_POKEMON_TOWER_RIVAL then return false end
+    if not ((x == 15 and y == 5) or (x == 14 and y == 6)) then return false end
+    if ow.runner:isRunning() then return false end
+    local rival = ow:npcByIndex(1)
+    if not rival then return false end
+    ow.player.facing = (x == 15) and "left" or "up"
+    require("src.core.Music").play(game.data, "Music_MeetRival")
+    ow.runner:run(pokemonTower2FRivalScript(x), { npc = rival })
+    return true
+  end,
 }
 
 -- -------------------------------------------------------------------

data/scripts/story2.lua

@@ -278,6 +278,23 @@ M.PALLET_TOWN = {
 
 local DRINKS = { "FRESH_WATER", "SODA_POP", "LEMONADE" }
 
+-- Hand over the first drink in the bag, if any. Mirrors RemoveGuardDrink
+-- (engine/items/inventory.asm), which walks the same three item ids and
+-- removes ONE, and the caller's BIT_GAVE_SAFFRON_GUARDS_DRINK.
+local function takeGuardDrink(game)
+  for _, drink in ipairs(DRINKS) do
+    if (game.save.inventory[drink] or 0) > 0 then
+      game.save.inventory[drink] = game.save.inventory[drink] - 1
+      if game.save.inventory[drink] == 0 then
+        game.save.inventory[drink] = nil
+      end
+      game.save.flags.EVENT_GAVE_GUARDS_DRINK = true
+      return true
+    end
+  end
+  return false
+end
+
 local function saffronGate(guardText, triggers, horizontal)
   return {
     talk = {
@@ -289,18 +306,15 @@ local function saffronGate(guardText, triggers, horizontal)
             t._SaffronGateGuardThanksForTheDrinkText or "Gee, that was\ntasty!", done))
           return
         end
-        for _, drink in ipairs(DRINKS) do
-          if (game.save.inventory[drink] or 0) > 0 then
-            game.save.inventory[drink] = game.save.inventory[drink] - 1
-            if game.save.inventory[drink] == 0 then
-              game.save.inventory[drink] = nil
-            end
-            game.save.flags.EVENT_GAVE_GUARDS_DRINK = true
-            game.stack:push(TextBox.new(game,
-              (t._SaffronGateGuardYouCanGoOnThroughText or
-               "Thanks! You can\ngo on through!"), done))
-            return
-          end
+        if takeGuardDrink(game) then
+          game.stack:push(TextBox.new(game,
+            t._SaffronGateGuardImParchedText or "Whoa, boy!\nI'm parched!",
+            function()
+              game.stack:push(TextBox.new(game,
+                (t._SaffronGateGuardYouCanGoOnThroughText or
+                 "You can go on\nthrough!"), done))
+            end))
+          return
         end
         game.stack:push(TextBox.new(game,
           t._SaffronGateGuardGeeImThirstyText or "Gee, I'm thirsty\nthough!", done))
@@ -317,6 +331,31 @@ local function saffronGate(guardText, triggers, horizontal)
       if game.save.flags.EVENT_GAVE_GUARDS_DRINK then return false end
       local TextBox = require("src.render.TextBox")
       local t = game.data.text
+      -- Stepping on the trigger WITH a drink hands it over right here.
+      --
+      -- Route5GateDefaultScript (scripts/Route5Gate.asm) runs
+      -- `farcall RemoveGuardDrink` before it decides anything: the coord
+      -- trigger itself takes the drink and sets
+      -- BIT_GAVE_SAFFRON_GUARDS_DRINK, and only a player carrying nothing
+      -- gets the thirsty line and the walk-back. We had the removal on the
+      -- guard's TALK handler only, so walking up with a FRESH_WATER in the
+      -- bag was turned away and the four gates stayed shut unless you
+      -- happened to talk to him -- which vanilla never requires.
+      --
+      -- Saffron is the middle of the map, so this sealed it: every route
+      -- through the city (Celadon <-> Lavender, Vermilion <-> Cerulean the
+      -- short way) was unreachable, and the bot could not get to Lavender
+      -- for the POKE_FLUTE at all.
+      if takeGuardDrink(game) then
+        game.stack:push(TextBox.new(game,
+          t._SaffronGateGuardImParchedText or "Whoa, boy!\nI'm parched!",
+          function()
+            game.stack:push(TextBox.new(game,
+              (t._SaffronGateGuardYouCanGoOnThroughText or
+               "You can go on\nthrough!")))
+          end))
+        return true
+      end
       local back
       if horizontal then
         back = ow.player.facing == "left" and "right" or "left"
@@ -324,7 +363,7 @@ local function saffronGate(guardText, triggers, horizontal)
         back = ow.player.facing == "up" and "down" or "up"
       end
       game.stack:push(TextBox.new(game,
-        t._SaffronGateGuardImParchedText or "I'm parched...\nNo entry until\nI get a drink!",
+        t._SaffronGateGuardGeeImThirstyText or "Gee, I'm thirsty\nthough!\nThe road's closed.",
         function()
           ow:scriptMove(ow.player, back, 1)
         end))
@@ -386,40 +425,112 @@ M.BIKE_SHOP = {
 -- the Cinnabar lab (the wait is skipped).
 -- -------------------------------------------------------------------
 
-local function mtMoonFossil(itemId, otherName)
+-- The Super Nerd (object index 1) claims both fossils and blocks the way
+-- to them. In scripts/MtMoonB2F.asm he isn't a sight-line trainer: his
+-- header carries no range, so MtMoonB2FDefaultScript force-triggers the
+-- battle the instant the player steps onto (13,8) -- the chokepoint tile
+-- to his right -- and reaching for a fossil intercepts you too.
+local function superNerdBeaten(ow)
+  local nerd = ow:npcByIndex(1)
+  return not nerd or ow:trainerDefeated(nerd)
+end
+
+local function engageSuperNerd(game, ow, onDone)
+  local nerd = ow:npcByIndex(1)
+  if not nerd or ow:trainerDefeated(nerd) then
+    if onDone then onDone() end
+    return
+  end
+  nerd:facePlayer(ow.player)
+  ow:engageTrainer(nerd, onDone)
+end
+
+-- MtMoonB2FMoveSuperNerdScript: player-near-dome coords walk RIGHT then
+-- UP (MoveRight falls through into MoveUp); near-helix walks UP only.
+local function mtMoonNerdWalk(px, py, itemId)
+  if (px == 12 and py == 7) or (px == 11 and py == 6) or (px == 12 and py == 5) then
+    return { "right", "up" }
+  end
+  if (px == 13 and py == 7) or (px == 14 and py == 6) or (px == 14 and py == 5) then
+    return { "up" }
+  end
+  return (itemId == "DOME_FOSSIL") and { "right", "up" } or { "up" }
+end
+
+-- scripts/MtMoonB2F.asm Dome/Helix fossil text_asm + MoveSuperNerd +
+-- SuperNerdTakesOtherFossil: pick one, hide it, walk the nerd to the
+-- other, "All right. Then this is mine!", hide the other.
+local function mtMoonFossil(itemId, otherName, gotFlag)
   return function(game, ow, npc, done)
     local TextBox = require("src.render.TextBox")
-    local ChoiceBox = require("src.ui.ChoiceBox")
-    if game.save.flags.EVENT_GOT_A_FOSSIL then
-      game.stack:push(TextBox.new(game, "You already took\na fossil.", done))
+    local t = game.data.text
+    local flags = game.save.flags
+    if flags.EVENT_GOT_DOME_FOSSIL or flags.EVENT_GOT_HELIX_FOSSIL then
+      done()
       return
     end
-    game.stack:push(TextBox.new(game, "You found a\nfossil! Take it?", function()
-      game.stack:push(ChoiceBox.new(game, function(yes)
-        if not yes then done() return end
-        game.save.inventory[itemId] = 1
-        game.save.flags.EVENT_GOT_A_FOSSIL = true
-        local Commands = require("src.script.Commands")
-        local ctx = { save = game.save, overworld = ow, game = game }
-        Commands.hide_object(ctx, "MT_MOON_B2F", npc.def.name)
-        Commands.hide_object(ctx, "MT_MOON_B2F", otherName)
-        local name = game.data.items[itemId].name
+    if not superNerdBeaten(ow) then
+      engageSuperNerd(game, ow, done)
+      return
+    end
+    local want = (itemId == "DOME_FOSSIL")
+      and (t._MtMoonB2FDomeFossilYouWantText or "You want the\nDOME FOSSIL?")
+      or (t._MtMoonB2FHelixFossilYouWantText or "You want the\nHELIX FOSSIL?")
+    game.stack:push(TextBox.new(game, want, nil, { choice = function(yes)
+      if not yes then done() return end
+      if not require("src.inventory.Bag").add(game.save, itemId, 1) then
         game.stack:push(TextBox.new(game,
-          ("%s got the\n%s!"):format(game.save.player.name, name), done))
-      end))
-    end))
+          t._MtMoonB2FYouHaveNoRoomText or "Look, you've got\nno room for this.",
+          done))
+        return
+      end
+      local idef = game.data.items[itemId]
+      game.stringBuffer = idef and idef.name or itemId
+      require("src.core.Sound").play(game.data, "Get_Key_Item")
+      local dirs = mtMoonNerdWalk(ow.player.cellX, ow.player.cellY, itemId)
+      game.stack:push(TextBox.new(game,
+        t._MtMoonB2FReceivedFossilText
+          or ("{PLAYER} got the\n" .. game.stringBuffer .. "!"),
+        function()
+          local Commands = require("src.script.Commands")
+          Commands.hide_object(
+            { save = game.save, overworld = ow, game = game },
+            "MT_MOON_B2F", npc.def.name)
+          flags[gotFlag] = true
+          ow.runner:run({
+            { "walk_npc", 1, dirs },
+            { "text_opts", { auto = true } },
+            { "show_text", "_MtMoonB2FSuperNerdThenThisIsMineText" },
+            { "play_sound", "Get_Key_Item" },
+            { "hide_object", "MT_MOON_B2F", otherName },
+          }, { onDone = done })
+        end))
+    end }))
   end
 end
 
 M.MT_MOON_B2F = {
+  -- MtMoonB2FDefaultScript forces the Super Nerd battle when the player
+  -- steps onto (13,8), the tile beside him guarding the fossils.
+  onStep = function(game, ow, x, y)
+    if x == 13 and y == 8 and not superNerdBeaten(ow) then
+      engageSuperNerd(game, ow, nil)
+      return true
+    end
+    return false
+  end,
   talk = {
-    TEXT_MTMOONB2F_DOME_FOSSIL = mtMoonFossil("DOME_FOSSIL", "MTMOONB2F_HELIX_FOSSIL"),
-    TEXT_MTMOONB2F_HELIX_FOSSIL = mtMoonFossil("HELIX_FOSSIL", "MTMOONB2F_DOME_FOSSIL"),
+    TEXT_MTMOONB2F_DOME_FOSSIL = mtMoonFossil(
+      "DOME_FOSSIL", "MTMOONB2F_HELIX_FOSSIL", "EVENT_GOT_DOME_FOSSIL"),
+    TEXT_MTMOONB2F_HELIX_FOSSIL = mtMoonFossil(
+      "HELIX_FOSSIL", "MTMOONB2F_DOME_FOSSIL", "EVENT_GOT_HELIX_FOSSIL"),
   },
 }
 
 -- The ticket clerk (scripts/Museum1F.asm Museum1FScientist1Text):
--- Y50, once; declining at the rope walks you back out.
+-- Y50, once.  Declining at the rope shoves the player one tile SOUTH back off
+-- the exhibit rope they crossed heading north (#151); the museum floor has no
+-- ledges, so a plain scriptMove("down",1) is the correct primitive.
 local function museumClerk(game, ow, done, onDecline)
   local TextBox = require("src.render.TextBox")
   local ChoiceBox = require("src.ui.ChoiceBox")
@@ -454,7 +565,7 @@ M.MUSEUM_1F = {
     if y == 4 and (x == 9 or x == 10)
        and not game.save.flags.EVENT_BOUGHT_MUSEUM_TICKET then
       museumClerk(game, ow, nil, function()
-        ow:scriptMove(ow.player, "right", 1)
+        ow:scriptMove(ow.player, "down", 1)
       end)
       return true
     end
@@ -646,73 +757,174 @@ M.CINNABAR_LAB_FOSSIL_ROOM = {
 -- -------------------------------------------------------------------
 -- Day-care (scripts/Daycare.asm): the boarded Pokémon earns 1 exp per
 -- step; the fee is ¥100 plus ¥100 per level gained.
+--
+-- #118: do not raise mon.level until a paid retrieve (pokered reverts
+-- wDayCareMonBoxLevel on .leaveMonInDayCare). Fold pending steps into
+-- mon.exp once and clear them so a second talk cannot re-apply the same
+-- walk. Fill {RAM:wNameBuffer}/{RAM:wDayCareMonName}/{NUM:...} here —
+-- TextBox.TOKENS.RAM only knows wStringBuffer.
 -- -------------------------------------------------------------------
 
+local function fillDaycareText(s, subs)
+  s = s:gsub("{PLAYER}", subs.player or "")
+  s = s:gsub("{RAM:([^}]*)}", function(name) return subs[name] or "" end)
+  -- extractor NUM spans may include flags after a comma; keep the name
+  s = s:gsub("{NUM:([%w_]+)[^}]*}", function(name)
+    return tostring(subs[name] or "0")
+  end)
+  return s
+end
+
 M.DAYCARE = {
   talk = {
     TEXT_DAYCARE_GENTLEMAN = function(game, ow, npc, done)
       local TextBox = require("src.render.TextBox")
-      local ChoiceBox = require("src.ui.ChoiceBox")
       local t = game.data.text
       local dc = game.save.daycare
+      local playerName = game.save.player and game.save.player.name or "RED"
+
+      local function monName(mon)
+        local def = game.data.pokemon[mon.species]
+        return mon.nickname or (def and def.name) or mon.species
+      end
 
       if dc and dc.mon then
         local Growth = require("src.pokemon.Growth")
         local Stats = require("src.pokemon.Stats")
+        local Party = require("src.pokemon.Party")
         local mon = dc.mon
         local def = game.data.pokemon[mon.species]
-        mon.exp = mon.exp + (dc.steps or 0)
-        local newLevel = math.min(100, Growth.levelForExp(def.growthRate, mon.exp))
-        local fee = 100 + (newLevel - mon.level) * 100
-        local grew = newLevel > mon.level
-        mon.level = newLevel
-        mon.stats = Stats.calc(def, mon.level, mon.dvs, mon.statExp)
-        mon.hp = mon.stats.hp
-        local msg = grew and (t._DaycareGentlemanMonHasGrownText or "It's grown a lot!")
-                    or "Back already?"
-        game.stack:push(TextBox.new(game,
-          msg .. ("\fThe fee is ¥%d.\nGet it back?"):format(fee), function()
-          game.stack:push(ChoiceBox.new(game, function(yes)
-            if yes and game.save.money >= fee then
+        -- Apply deferred step-exp once (OverworldController only bumps
+        -- daycare.steps). Clearing prevents double-count on re-talk.
+        mon.exp = (mon.exp or 0) + (dc.steps or 0)
+        dc.steps = 0
+        -- depositLevel mirrors wDayCareMonBoxLevel: fee baseline that
+        -- must survive a declined retrieve. Fall back to mon.level for
+        -- older saves that predate the field.
+        if dc.depositLevel == nil then dc.depositLevel = mon.level end
+        local startLevel = dc.depositLevel
+        local newLevel = Growth.levelForExp(def and def.growthRate, mon.exp)
+        if newLevel >= 100 then
+          newLevel = 100
+          if def then
+            mon.exp = Growth.expForLevel(def.growthRate, 100)
+          end
+        end
+        local levelsGrown = math.max(0, newLevel - startLevel)
+        local fee = 100 + levelsGrown * 100
+        local name = monName(mon)
+        local subs = {
+          player = playerName,
+          wNameBuffer = name,
+          wDayCareMonName = name,
+          wDayCareNumLevelsGrown = levelsGrown,
+          wDayCareTotalCost = fee,
+        }
+        local statusText = levelsGrown > 0
+          and (t._DaycareGentlemanMonHasGrownText
+            or "Your {RAM:wNameBuffer}\nhas grown a lot!\fBy level, it's\ngrown by {NUM:wDayCareNumLevelsGrown, 1, 3}!\fAren't I great?")
+          or (t._DaycareGentlemanMonNeedsMoreTimeText
+            or "Back already?\nYour {RAM:wNameBuffer}\nneeds some more\ntime with me.")
+
+        game.stack:push(TextBox.new(game, fillDaycareText(statusText, subs), function()
+          if #game.save.party >= Party.MAX then
+            game.stack:push(TextBox.new(game,
+              t._DaycareGentlemanNoRoomForMonText
+                or "You have no room\nfor this POKéMON!", done))
+            return
+          end
+          game.stack:push(TextBox.new(game,
+            fillDaycareText(
+              t._DaycareGentlemanOweMoneyText
+                or "You owe me ¥{NUM:wDayCareTotalCost, 2 | LEADING_ZEROES | LEFT_ALIGN}\nfor the return\nof this POKéMON.",
+              subs),
+            nil, { choice = function(yes)
+              if not yes then
+                -- .leaveMonInDayCare: revert any transient level bump
+                mon.level = startLevel
+                game.stack:push(TextBox.new(game,
+                  (t._DaycareGentlemanAllRightThenText or "All right then,\n")
+                    .. (t._DaycareGentlemanComeAgainText or "come again."),
+                  done))
+                return
+              end
+              if (game.save.money or 0) < fee then
+                mon.level = startLevel
+                game.stack:push(TextBox.new(game,
+                  t._DaycareGentlemanNotEnoughMoneyText
+                    or "Hey, you don't\nhave enough ¥!", done))
+                return
+              end
               game.save.money = game.save.money - fee
+              mon.level = newLevel
+              if def then
+                mon.stats = Stats.calc(def, mon.level, mon.dvs, mon.statExp)
+                mon.hp = mon.stats.hp
+                -- Daycare.asm: WriteMonMoves with wLearningMovesFromDayCare
+                local Pokemon = require("src.pokemon.Pokemon")
+                Pokemon.learnMovesFromDayCare(
+                  game.data, mon, def, startLevel, newLevel)
+              end
               table.insert(game.save.party, mon)
               game.save.daycare = nil
               game.stack:push(TextBox.new(game,
-                t._DaycareGentlemanGotMonBackText or "Here you go!", done))
-            else
-              game.stack:push(TextBox.new(game,
-                yes and (t._DaycareGentlemanOweMoneyText or "You owe me money!")
-                    or "Come again!", done))
-            end
-          end))
+                t._DaycareGentlemanHeresYourMonText
+                  or "Thank you! Here's\nyour POKéMON!", function()
+                game.stack:push(TextBox.new(game,
+                  fillDaycareText(
+                    t._DaycareGentlemanGotMonBackText
+                      or "{PLAYER} got\n{RAM:wDayCareMonName} back!",
+                    subs), done))
+              end))
+            end }))
         end))
         return
       end
 
-      if #game.save.party < 2 then
-        game.stack:push(TextBox.new(game,
-          "You only have one\nPOKéMON with you!", done))
-        return
-      end
       game.stack:push(TextBox.new(game,
-        t._DaycareGentlemanIntroText or "I can raise a\nPOKéMON for you.", function()
-        game.stack:push(ChoiceBox.new(game, function(yes)
-          if not yes then done() return end
-          local PartyMenu = require("src.ui.PartyMenu")
-          game.stack:push(PartyMenu.new(game, {
-            pickOnly = true,
-            onSwitch = function(mon)
-              for i, m in ipairs(game.save.party) do
-                if m == mon then table.remove(game.save.party, i) break end
-              end
-              game.save.daycare = { mon = mon, steps = 0 }
-              game.stack:push(TextBox.new(game,
-                t._DaycareGentlemanWillLookAfterMonText or
-                "Fine, I'll look\nafter it a while!", done))
-            end,
-          }))
-        end))
-      end))
+        t._DaycareGentlemanIntroText
+          or "I run a DAYCARE.\nWould you like me\nto raise one of\nyour POKéMON?",
+        nil, { choice = function(yes)
+          if not yes then
+            game.stack:push(TextBox.new(game,
+              t._DaycareGentlemanComeAgainText or "come again.", done))
+            return
+          end
+          if #game.save.party < 2 then
+            game.stack:push(TextBox.new(game,
+              t._DaycareGentlemanOnlyHaveOneMonText
+                or "You only have one\nPOKéMON with you.", done))
+            return
+          end
+          game.stack:push(TextBox.new(game,
+            t._DaycareGentlemanWhichMonText or "Which POKéMON\nshould I raise?",
+            function()
+              local PartyMenu = require("src.ui.PartyMenu")
+              game.stack:push(PartyMenu.new(game, {
+                pickOnly = true,
+                onSwitch = function(mon)
+                  for i, m in ipairs(game.save.party) do
+                    if m == mon then table.remove(game.save.party, i) break end
+                  end
+                  local name = monName(mon)
+                  -- depositLevel = wDayCareMonBoxLevel at deposit time
+                  game.save.daycare = {
+                    mon = mon, steps = 0, depositLevel = mon.level,
+                  }
+                  game.stack:push(TextBox.new(game,
+                    fillDaycareText(
+                      t._DaycareGentlemanWillLookAfterMonText
+                        or "Fine, I'll look\nafter {RAM:wNameBuffer}\nfor a while.",
+                      { player = playerName, wNameBuffer = name }),
+                    function()
+                      game.stack:push(TextBox.new(game,
+                        t._DaycareGentlemanComeSeeMeInAWhileText
+                          or "Come see me in\na while.", done))
+                    end))
+                end,
+              }))
+            end))
+        end }))
     end,
   },
 }

data/scripts/story3.lua

@@ -61,9 +61,61 @@ M.ROUTE_12_SUPER_ROD_HOUSE = {
 M.ROUTE_12_SUPER_ROD_HOUSE.talk.TEXT_ROUTE12SUPERRODHOUSE_FISHING_GURU[9] =
   { "show_text", "_Route12SuperRodHouseFishingGuruTryFishingText" }
 
+-- -------------------------------------------------------------------
+-- Pokemon Tower 5F purified zone (scripts/PokemonTower5F.asm
+-- PokemonTower5FDefaultScript): the 2x2 center pad heals the party once
+-- per visit.  EVENT_IN_PURIFIED_ZONE latches until the player steps off;
+-- while on the pad the map script also sets BIT_NO_BATTLES (we return
+-- true from onStep so wild encounters are skipped the same way).
+-- -------------------------------------------------------------------
+
+local TOWER_5F_PURIFIED = {
+  [10 * 256 + 8] = true, [11 * 256 + 8] = true,
+  [10 * 256 + 9] = true, [11 * 256 + 9] = true,
+}
+
+-- HealParty -> GBFadeOutToWhite -> Delay3 -> Delay3 -> GBFadeInFromWhite
+-- -> TEXT_POKEMONTOWER5F_PURIFIEDZONE (no Music_PkmnHealed).
+local TOWER_5F_HEAL = {
+  { "heal_party" },
+  { "fade", "out", "white" },
+  { "wait", 3 },
+  { "wait", 3 },
+  { "fade", "in", "white" },
+  { "show_text", "_PokemonTower5FPurifiedZoneText" },
+}
+
+M.POKEMON_TOWER_5F = {
+  onStep = function(game, ow, x, y)
+    if not TOWER_5F_PURIFIED[x * 256 + y] then
+      game.save.flags.EVENT_IN_PURIFIED_ZONE = nil
+      return false
+    end
+    if game.save.flags.EVENT_IN_PURIFIED_ZONE then
+      return true
+    end
+    if ow.runner and ow.runner:isRunning() then return false end
+    game.save.flags.EVENT_IN_PURIFIED_ZONE = true
+    if ow.runner then
+      ow.runner:run(TOWER_5F_HEAL)
+    elseif ow.queueScript then
+      ow:queueScript(TOWER_5F_HEAL)
+    end
+    return true
+  end,
+}
+
 -- -------------------------------------------------------------------
 -- The ghost Marowak (scripts/PokemonTower6F.asm): blocks the stairs at
--- (10,16) until identified with the Silph Scope and defeated.
+-- (10,16) until defeated.
+--
+-- 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
+-- 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).
 -- -------------------------------------------------------------------
 
 M.POKEMON_TOWER_6F = {
@@ -71,26 +123,32 @@ M.POKEMON_TOWER_6F = {
     if game.save.flags.EVENT_BEAT_GHOST_MAROWAK then return false end
     if x ~= 10 or y ~= 16 then return false end
     local TextBox = require("src.render.TextBox")
-    if not game.save.inventory.SILPH_SCOPE then
-      game.stack:push(TextBox.new(game,
-        "A GHOST blocks\nthe way...\fDarn! You can't\nidentify it!",
-        function()
-          local back = ow.player.facing == "up" and "down" or "up"
-          ow:scriptMove(ow.player, back, 1)
-        end))
-      return true
-    end
+    local t = game.data.text
     game.stack:push(TextBox.new(game,
-      "The GHOST was\nMAROWAK!\fThe restless soul\nattacks!", function()
+      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
+        battle:makeGhost()
+      end
       battle.onFinish = function(result)
-        if result == "win" then
+        -- wBattleResult parity (PokemonTower6FMarowakBattleScript's
+        -- "and a / jr nz"): losing writes $1 and running writes $2, but
+        -- ItemUsePokeDoll ends the battle WITHOUT touching it, so the
+        -- script reads 0 -- defeated. That is the famous Poke Doll
+        -- trick, and the speedrun route this bot follows depends on it.
+        if result == "win" or battle.pokeDollEscape then
           game.save.flags.EVENT_BEAT_GHOST_MAROWAK = true
           game.stack:push(TextBox.new(game,
-            "The restless soul\ncalmed down and\ndeparted!"))
+            t._PokemonTower6FSoulWasCalmedText
+            or "The mother's soul\nwas calmed.\012It departed to\nthe afterlife!"))
+        elseif result ~= "lose" then
+          -- .did_not_defeat: one simulated step right, off the trigger,
+          -- so fleeing does not leave you standing on a cell that
+          -- immediately re-fires.
+          ow:scriptMove(ow.player, "right", 1)
         end
-        ow:afterBattle(result)
+        ow:afterBattle(result, battle)
       end
       game.stack:push(battle)
     end))
@@ -136,18 +194,20 @@ local WALK_DIRVEC = { up = { 0, -1 }, down = { 0, 1 }, left = { -1, 0 }, right =
 local WALK_OPP = { up = "down", down = "up", left = "right", right = "left" }
 local WALK_ORDER = { "up", "down", "left", "right" }
 
-local function elevatorWalkOut(ow, floor)
-  local m, p = ow.map, ow.player
-  -- .UpdateWarp is run twice, so BOTH car warp entries get the same
-  -- (warp id, map id): point every exit warp at the picked floor's
-  -- elevator-door warp (the reciprocal warp found while building the
-  -- menu).  The car map's def is shared generated data, but its own
-  -- warps are only ever read from inside the car, and this rewrite runs
-  -- on every ride before the walk-out fires, so it is self-correcting.
-  for _, w in ipairs(m.def.warps) do
+-- .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
+-- warps are only read from inside the car; rides rewrite them again.
+local function elevatorSetExit(ow, floor)
+  if not floor then return end
+  for _, w in ipairs(ow.map.def.warps) do
     w.destMap = floor.map
     w.destWarp = floor.warpIdx
   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
@@ -185,37 +245,68 @@ local function elevatorWalkOut(ow, floor)
   end)
 end
 
+local function elevatorFloors(elevatorMapId, game)
+  local floors = {}
+  for mapId, def in pairs(game.data.maps) do
+    for i, w in ipairs(def.warps) do
+      if w.destMap == elevatorMapId then
+        -- short floor token pokered actually prints, e.g.
+        -- SILPH_CO_10F -> "10F", ROCKET_HIDEOUT_B2F -> "B2F"
+        local token = mapId:match("_([^_]+)$") or mapId
+        -- warpIdx: this floor's warp back into the elevator IS the
+        -- warp the car's rewritten exit lands on (the reciprocal
+        -- pair), matching wElevatorWarpMaps' (warp id, map id)
+        table.insert(floors,
+          { map = mapId, x = w.x, y = w.y, token = token, warpIdx = i })
+        break
+      end
+    end
+  end
+  -- numeric floor order (SilphCoElevatorFloors' FLOOR_1F..FLOOR_11F),
+  -- not lexicographic -- otherwise 10F/11F sort before 2F..9F
+  table.sort(floors, function(a, b)
+    return (tonumber(a.token:match("%d+")) or 0) <
+           (tonumber(b.token:match("%d+")) or 0)
+  end)
+  return floors
+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
+  -- 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).
+  local exitFloor = floors[1]
+  if fromMapId then
+    for _, f in ipairs(floors) do
+      if f.map == fromMapId then exitFloor = f break end
+    end
+  end
+  elevatorSetExit(ow, exitFloor)
+  return exitFloor
+end
+
 local function elevator(elevatorMapId, keyGate, preFrames)
   return {
-    onEnter = function(game, ow)
+    -- 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 floors = {}
-      for mapId, def in pairs(game.data.maps) do
-        for i, w in ipairs(def.warps) do
-          if w.destMap == elevatorMapId then
-            -- short floor token pokered actually prints, e.g.
-            -- SILPH_CO_10F -> "10F", ROCKET_HIDEOUT_B2F -> "B2F"
-            local token = mapId:match("_([^_]+)$") or mapId
-            -- warpIdx: this floor's warp back into the elevator IS the
-            -- warp the car's rewritten exit lands on (the reciprocal
-            -- pair), matching wElevatorWarpMaps' (warp id, map id)
-            table.insert(floors,
-              { map = mapId, x = w.x, y = w.y, token = token, warpIdx = i })
-            break
-          end
-        end
-      end
-      -- numeric floor order (SilphCoElevatorFloors' FLOOR_1F..FLOOR_11F),
-      -- not lexicographic -- otherwise 10F/11F sort before 2F..9F
-      table.sort(floors, function(a, b)
-        return (tonumber(a.token:match("%d+")) or 0) <
-               (tonumber(b.token:match("%d+")) or 0)
-      end)
       local items = {}
       for _, f in ipairs(floors) do
         table.insert(items, { label = f.token, value = f })
@@ -248,7 +339,8 @@ local function elevator(elevatorMapId, keyGate, preFrames)
         end,
         onCancel = function()
           -- DisplayElevatorFloorMenu: `ret c` on B -- no warp, nothing
-          -- happens, the player just stays in the car
+          -- happens, the player just stays in the car (exit warps were
+          -- already seeded to the entry floor above)
         end,
       }))
     end,
@@ -260,6 +352,98 @@ M.CELADON_MART_ELEVATOR = elevator("CELADON_MART_ELEVATOR", nil, 9)
 M.ROCKET_HIDEOUT_ELEVATOR = elevator("ROCKET_HIDEOUT_ELEVATOR",
   { item = "LIFT_KEY", text = "_RocketHideoutElevatorAppearsToNeedKeyText" })
 
+-- -------------------------------------------------------------------
+-- Rocket Hideout B4F (scripts/RocketHideoutB4F.asm):
+--   Rocket3's after-battle text_asm drops the LIFT KEY item ball
+--   (CheckAndSetEvent EVENT_ROCKET_DROPPED_LIFT_KEY / ShowObject
+--   TOGGLE_ROCKET_HIDEOUT_B4F_ITEM_5).  Both start hidden in the map
+--   objects; without this talk side-effect the key never appears (#90,
+--   #105).
+--   Giovanni's post-battle script likewise ShowObject's the Silph Scope
+--   after the hope-we-meet-again line (TOGGLE_ROCKET_HIDEOUT_B4F_ITEM_4).
+-- -------------------------------------------------------------------
+
+M.ROCKET_HIDEOUT_B4F = {
+  talk = {
+    TEXT_ROCKETHIDEOUTB4F_ROCKET3 = function(game, ow, npc, done)
+      if not ow:trainerDefeated(npc) then
+        ow:engageTrainer(npc, done)
+        return
+      end
+      local TextBox = require("src.render.TextBox")
+      local t = game.data.text
+      game.stack:push(TextBox.new(game,
+        t._RocketHideoutB4FRocket3AfterBattleText
+        or "Oh no! I dropped\nthe LIFT KEY!",
+        function()
+          -- CheckAndSetEvent EVENT_ROCKET_DROPPED_LIFT_KEY: first talk
+          -- after the win reveals the ball; later talks only reprint.
+          if 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))
+    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.
+      if ow:trainerDefeated(npc)
+         or game.save.flags.EVENT_BEAT_ROCKET_HIDEOUT_GIOVANNI then
+        local TextBox = require("src.render.TextBox")
+        game.stack:push(TextBox.new(game,
+          game.data.text._RocketHideoutB4FGiovanniHopeWeMeetAgainText
+          or "I hope we meet\nagain...", done))
+        return
+      end
+      local TextBox = require("src.render.TextBox")
+      local BattleState = require("src.battle.BattleState")
+      local t = game.data.text
+      local impressed = t._RocketHideoutB4FGiovanniImpressedYouGotHereText
+                        or "So! I must say, I\nam impressed you\ngot here!"
+      local cannotBe = t._RocketHideoutB4FGiovanniWhatCannotBeText
+                       or "WHAT!\nThis cannot be!"
+      local hope = t._RocketHideoutB4FGiovanniHopeWeMeetAgainText
+                   or "I hope we meet\nagain..."
+      game.stack:push(TextBox.new(game, impressed, function()
+        local battle = BattleState.newTrainer(game, "OPP_GIOVANNI", 1)
+        battle.onFinish = function(result)
+          if result ~= "win" then
+            ow:afterBattle(result, battle)
+            done()
+            return
+          end
+          game.save.defeatedTrainers[npc.id] = true
+          game.save.flags.EVENT_BEAT_ROCKET_HIDEOUT_GIOVANNI = true
+          -- End-battle "WHAT!" then BeatGiovanniScript's hope text,
+          -- fade, HideObject Giovanni, ShowObject Silph Scope.
+          game.stack:push(TextBox.new(game, cannotBe, function()
+            game.stack:push(TextBox.new(game, hope, function()
+              local Transition = require("src.render.Transition")
+              game.stack:push(Transition.new(game, function()
+                local Commands = require("src.script.Commands")
+                local ctx = { game = game, save = game.save, overworld = ow }
+                Commands.hide_object(ctx, "ROCKET_HIDEOUT_B4F",
+                  "ROCKETHIDEOUTB4F_GIOVANNI")
+                Commands.show_object(ctx, "ROCKET_HIDEOUT_B4F",
+                  "ROCKETHIDEOUTB4F_SILPH_SCOPE")
+              end, function()
+                ow:afterBattle(result, battle)
+                done()
+              end))
+            end))
+          end))
+        end
+        ow:pushBattle(battle)
+      end))
+    end,
+  },
+}
+
 -- -------------------------------------------------------------------
 -- Game Corner coins, prizes, and the rocket-poster switch that reveals
 -- the hideout stairs (scripts/GameCorner.asm, data/events/prizes.asm +
@@ -272,14 +456,23 @@ M.GAME_CORNER = {
   -- EVENT_FOUND_ROCKET_HIDEOUT is unset, $43 after)
   onEnter = function(game, ow)
     local poster = game.data.field.gameCornerPoster
-    if not poster then return end
-    local block = game.save.flags[poster.event] and poster.openBlock
-                  or poster.closedBlock
-    ow:replaceBlock(poster.x, poster.y, block)
+    if poster then
+      local block = game.save.flags[poster.event] and poster.openBlock
+                    or poster.closedBlock
+      ow:replaceBlock(poster.x, poster.y, block)
+    end
     -- pick this visit's lucky slot machine
     -- (wLuckySlotHiddenEventIndex, engine/slots/game_corner_slots2.asm)
     local seats = game.data.field.slotMachines.GAME_CORNER
     ow.luckySlot = love.math.random(1, #seats)
+    -- #131: pre-#50 saves beat the poster grunt (defeatedTrainers) but
+    -- never hid him; clear the tile if he is already marked defeated
+    local rocketId = "GAME_CORNER_obj_11"
+    if game.save.defeatedTrainers and game.save.defeatedTrainers[rocketId] then
+      local Commands = require("src.script.Commands")
+      Commands.hide_object({ game = game, save = game.save, overworld = ow },
+                           "GAME_CORNER", "GAMECORNER_ROCKET")
+    end
   end,
   talk = {
     -- the poster bg event: pressing A reveals the hidden switch
@@ -303,6 +496,48 @@ M.GAME_CORNER = {
         done()
       end))
     end,
+    -- the grunt guarding the poster (GameCornerRocketText /
+    -- GameCornerRocketBattleScript / GameCornerRocketExitScript): after
+    -- losing he warns the BOSS and leaves the floor for good, freeing
+    -- the tile in front of the hideout switch
+    TEXT_GAMECORNER_ROCKET = function(game, ow, npc, done)
+      local Commands = require("src.script.Commands")
+      local function hideRocket()
+        Commands.hide_object({ game = game, save = game.save,
+                               overworld = ow },
+                             "GAME_CORNER", "GAMECORNER_ROCKET")
+      end
+      -- already beaten: hide anyway so pre-#50 saves that only have
+      -- defeatedTrainers (no objectToggles hide) clear the poster tile
+      if ow:trainerDefeated(npc) then
+        hideRocket()
+        done()
+        return
+      end
+      ow:engageTrainer(npc, function()
+        if not ow:trainerDefeated(npc) then
+          done()
+          return
+        end
+        local TextBox = require("src.render.TextBox")
+        game.stack:push(TextBox.new(game,
+          game.data.text._GameCornerRocketAfterBattleText
+          or "Our hideout might\nbe discovered! I\nbetter tell BOSS!",
+          function()
+            -- #198: GameCornerRocketExitScript (scripts/GameCorner.asm)
+            -- ApplyMovementData walks the grunt one tile UP into the poster
+            -- (the hideout's secret entrance at 9,4) before HideObject, so
+            -- he leaves the floor rather than popping out of existence on
+            -- (9,5).  scriptMove locks player input (#scriptMoves>0) and
+            -- ignores collision, so we despawn + unfreeze (done) only once
+            -- the step lands.
+            ow:scriptMove(npc, "up", 1, function()
+              hideRocket()
+              done()
+            end)
+          end))
+      end)
+    end,
     TEXT_GAMECORNER_CLERK1 = function(game, ow, npc, done)
       local TextBox = require("src.render.TextBox")
       local ChoiceBox = require("src.ui.ChoiceBox")
@@ -349,53 +584,93 @@ M.GAME_CORNER = {
   },
 }
 
--- Red-version prize lists (data/events/prizes.asm, prize_mon_levels.asm)
-local PRIZES = {
+-- 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.
+local PRIZE_TMS = {
+  { kind = "item", item = "TM_DRAGON_RAGE", cost = 3300 },
+  { kind = "item", item = "TM_HYPER_BEAM", cost = 5500 },
+  { kind = "item", item = "TM_SUBSTITUTE", cost = 7700 },
+}
+local RED_PRIZES = {
   { kind = "mon", species = "ABRA", level = 9, cost = 180 },
   { kind = "mon", species = "CLEFAIRY", level = 8, cost = 500 },
   { kind = "mon", species = "NIDORINA", level = 17, cost = 1200 },
   { kind = "mon", species = "DRATINI", level = 18, cost = 2800 },
   { kind = "mon", species = "SCYTHER", level = 25, cost = 5500 },
   { kind = "mon", species = "PORYGON", level = 26, cost = 9999 },
-  { kind = "item", item = "TM_DRAGON_RAGE", cost = 3300 },
-  { kind = "item", item = "TM_HYPER_BEAM", cost = 5500 },
-  { kind = "item", item = "TM_SUBSTITUTE", cost = 7700 },
+  PRIZE_TMS[1], PRIZE_TMS[2], PRIZE_TMS[3],
+}
+local BLUE_PRIZES = {
+  { kind = "mon", species = "ABRA", level = 6, cost = 120 },
+  { kind = "mon", species = "CLEFAIRY", level = 12, cost = 750 },
+  { kind = "mon", species = "NIDORINO", level = 17, cost = 1200 },
+  { kind = "mon", species = "PINSIR", level = 20, cost = 2500 },
+  { kind = "mon", species = "DRATINI", level = 24, cost = 4600 },
+  { kind = "mon", species = "PORYGON", level = 18, cost = 6500 },
+  PRIZE_TMS[1], PRIZE_TMS[2], PRIZE_TMS[3],
 }
 
+local function activePrizes()
+  return require("src.core.GameVersion").isBlue() and BLUE_PRIZES or RED_PRIZES
+end
+
+-- Prize counters (engine/menus/prize_menu.asm CeladonPrizeMenu; the prize
+-- list itself is data/events/prizes.asm, prize_mon_levels.asm).  Gen1 gates
+-- the prize window on the COIN CASE: it does IsItemInBag COIN_CASE first, and
+-- with no case prints RequireCoinCaseText and returns without ever opening a
+-- window; only with the case does it print ExchangeCoinsForPrizesText and then
+-- show the prizes.  #194: the port used to open the window unconditionally and
+-- skip both text boxes.
 local function prizeCounter(game, ow, npc, done)
   local ListMenu = require("src.ui.ListMenu")
   local Commands = require("src.script.Commands")
-  local items = {}
-  for _, p in ipairs(PRIZES) do
-    local label
-    if p.kind == "mon" then
-      label = ("%s L%d"):format(game.data.pokemon[p.species].name, p.level)
-    else
-      label = game.data.items[p.item].name
-    end
-    table.insert(items, { label = label, right = tostring(p.cost), value = p })
+  local TextBox = require("src.render.TextBox")
+  local t = game.data.text
+  -- IsItemInBag COIN_CASE: without the case, deny and open no window
+  -- (COIN_CASE is a numeric count in save.inventory, nil when absent).
+  if not game.save.inventory.COIN_CASE then
+    game.stack:push(TextBox.new(game,
+      t._RequireCoinCaseText or "A COIN CASE is\nrequired!", done))
+    return
   end
-  local list
-  list = ListMenu.new(game, "PRIZES (COINS)", items, {
-    footer = ("COINS %d"):format(game.save.coins or 0),
-    onChoose = function(item)
-      local p = item.value
-      if (game.save.coins or 0) < p.cost then
-        list.footer = "Not enough coins!"
-        return
+  -- ExchangeCoinsForPrizesText plays before the prize window opens.
+  game.stack:push(TextBox.new(game,
+    t._ExchangeCoinsForPrizesText or "We exchange your\ncoins for prizes.",
+    function()
+      local items = {}
+      for _, p in ipairs(activePrizes()) do
+        local label
+        if p.kind == "mon" then
+          label = ("%s L%d"):format(game.data.pokemon[p.species].name, p.level)
+        else
+          label = game.data.items[p.item].name
+        end
+        table.insert(items,
+          { label = label, right = tostring(p.cost), value = p })
       end
-      game.save.coins = game.save.coins - p.cost
-      if p.kind == "mon" then
-        Commands.give_pokemon({ save = game.save, game = game },
-                              p.species, p.level)
-      else
-        game.save.inventory[p.item] = (game.save.inventory[p.item] or 0) + 1
-      end
-      list.footer = ("Got it! COINS %d"):format(game.save.coins)
-    end,
-    onCancel = done,
-  })
-  game.stack:push(list)
+      local list
+      list = ListMenu.new(game, "PRIZES (COINS)", items, {
+        footer = ("COINS %d"):format(game.save.coins or 0),
+        onChoose = function(item)
+          local p = item.value
+          if (game.save.coins or 0) < p.cost then
+            list.footer = "Not enough coins!"
+            return
+          end
+          game.save.coins = game.save.coins - p.cost
+          if p.kind == "mon" then
+            Commands.give_pokemon({ save = game.save, game = game },
+                                  p.species, p.level)
+          else
+            game.save.inventory[p.item] = (game.save.inventory[p.item] or 0) + 1
+          end
+          list.footer = ("Got it! COINS %d"):format(game.save.coins)
+        end,
+        onCancel = done,
+      })
+      game.stack:push(list)
+    end))
 end
 
 M.GAME_CORNER_PRIZE_ROOM = {
@@ -411,18 +686,63 @@ M.GAME_CORNER_PRIZE_ROOM = {
 -- and the player steps off the dock, the ship sets sail.
 -- -------------------------------------------------------------------
 
+-- the ship's hull/deck blocks (block cols 5-8, rows 1-2) and the water
+-- that replaces them once she sails (the surrounding blocks of each row)
+local DOCK_SHIP_BLOCKS = {
+  { bx = 5, by = 1, water = 1 }, { bx = 6, by = 1, water = 1 },
+  { bx = 7, by = 1, water = 1 }, { bx = 8, by = 1, water = 1 },
+  { bx = 5, by = 2, water = 13 }, { bx = 6, by = 2, water = 13 },
+  { bx = 7, by = 2, water = 13 }, { bx = 8, by = 2, water = 13 },
+}
+
 M.VERMILION_DOCK = {
   onEnter = function(game, ow)
-    if game.save.flags.EVENT_SS_ANNE_LEFT then
+    local Flags = require("src.script.Flags")
+    local f = game.save.flags
+    if Flags.get(game.save, "EVENT_SS_ANNE_LEFT") then
+      -- the ship is long gone: erase her right away, and anyone who
+      -- still lands here is sent back out past the guard
+      for _, b in ipairs(DOCK_SHIP_BLOCKS) do
+        ow.map:setBlock(b.bx, b.by, b.water)
+      end
+      ow.map.renderer:rebuild()
       local TextBox = require("src.render.TextBox")
       game.stack:push(TextBox.new(game,
         game.data.text._VermilionCitySailor1ShipSetSailText
         or "The ship set sail.", function()
-        ow:startWarpTo("VERMILION_CITY", 19, 30, "up")
+        ow:startWarpTo("VERMILION_CITY", 18, 29, "up")
       end))
-    elseif game.save.flags.EVENT_GOT_HM01 then
-      game.save.flags.EVENT_SS_ANNE_LEFT = true
-      require("src.core.Sound").play(game.data, "SS_Anne_Horn")
+    elseif f.EVENT_GOT_HM01 and ow.player.cellY == 2 then
+      -- VermilionDockSSAnneLeavesScript: only stepping OFF the ship
+      -- triggers the departure (wDestinationWarpID == 1 in pokered) --
+      -- Music_Surfing plays for the sail-away cutscene, smoke puffs
+      -- drift off the funnel, the horn blows, the ship is erased to
+      -- open water, and the player is walked off the dock into the
+      -- city past the guard (VermilionCity's
+      -- SCRIPT_VERMILIONCITY_PLAYER_EXIT_SHIP walk)
+      Flags.set(game.save, "EVENT_SS_ANNE_LEFT")
+      local Music = require("src.core.Music")
+      Music.stop()
+      Music.play(game.data, "Music_Surfing")
+      local function puff(n, cx)
+        if n <= 0 then return end
+        ow:startDustAnim(cx, 1, function() puff(n - 1, cx + 2) end)
+      end
+      puff(3, 15)
+      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 }
+      end
+      rows[#rows + 1] = { "wait", 30 }
+      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 } }
+      rows[#rows + 1] = { "warp", "VERMILION_CITY", 18, 31, "up" }
+      rows[#rows + 1] = { "move_player", "up", 2 }
+      ow:queueScript(rows)
     end
   end,
 }

data/scripts/story4.lua

@@ -134,12 +134,19 @@ M.MT_MOON_POKECENTER = {
 -- Karate Master, take HITMONLEE or HITMONCHAN (the other disappears)
 -- -------------------------------------------------------------------
 
+-- ownBall/otherBall keep their spots for signature symmetry; only ownBall
+-- is ever hidden (Gen1 removes just the chosen ball).
 local function dojoBall(species, ownBall, otherBall, askKey)
   return function(game, ow, npc, done)
     local t = text(game)
     local flags = game.save.flags
+    -- Already took one prize: the OTHER ball is still on the mat, so
+    -- talking to it now gives the "Better not get greedy..." refusal
+    -- (FightingDojo.asm .gotThePokemon / _FightingDojoBetterNotGetGreedyText),
+    -- not a silent no-op (#197).
     if flags.EVENT_GOT_HITMONLEE or flags.EVENT_GOT_HITMONCHAN then
-      done()
+      push(game, t._FightingDojoBetterNotGetGreedyText
+        or "Better not get\ngreedy...", done)
       return
     end
     if not flags.EVENT_BEAT_KARATE_MASTER then
@@ -153,8 +160,10 @@ local function dojoBall(species, ownBall, otherBall, askKey)
       local Commands = require("src.script.Commands")
       local ctx = { save = game.save, game = game, overworld = ow }
       Commands.give_pokemon(ctx, species, 30)
+      -- Hide ONLY the chosen ball; the other stays (FightingDojo.asm hides
+      -- just the picked object's index) and routes to the greedy line above
+      -- when talked to (#197).
       Commands.hide_object(ctx, "FIGHTING_DOJO", ownBall)
-      Commands.hide_object(ctx, "FIGHTING_DOJO", otherBall)
       push(game, ("%s got\n%s!"):format(game.save.player.name, species), done)
     end)
   end
@@ -171,6 +180,21 @@ M.FIGHTING_DOJO = {
                "FIGHTINGDOJO_HITMONLEE_POKE_BALL",
                "_FightingDojoHitmonchanPokeBallText"),
   },
+  -- The two dojo posters on the north wall (FightingDojo.asm bg_events at
+  -- the top of the room, cells (4,0)/(5,0) directly above the prize balls)
+  -- print _EnemiesOnEverySideText.  The map extractor dropped the dojo
+  -- bg_events (signs = {}), so wire the poster read here, the same
+  -- facing-up + coord shape the mansion switches use.  Reachable only once
+  -- a claimed prize frees the ball cell below the poster (#197).
+  onInteract = function(game, ow, fx, fy)
+    if ow.player.facing ~= "up" then return false end
+    if fy == 0 and (fx == 4 or fx == 5) then
+      push(game, text(game)._EnemiesOnEverySideText
+        or "Enemies on every\nside!")
+      return true
+    end
+    return false
+  end,
 }
 
 -- -------------------------------------------------------------------
@@ -212,30 +236,31 @@ M.COPYCATS_HOUSE_2F = {
   talk = {
     TEXT_COPYCATSHOUSE2F_COPYCAT = function(game, ow, npc, done)
       local t = text(game)
+      local Bag = require("src.inventory.Bag")
       if game.save.flags.EVENT_GOT_TM31 then
-        push(game, t._CopycatsHouse2FCopycatWhirlingText
-          or "Huh? Huh? Huh?", done)
+        push(game, t._CopycatsHouse2FCopycatTM31Explanation2Text, done)
         return
       end
-      if (game.save.inventory.POKE_DOLL or 0) > 0 then
-        ask(game, t._CopycatsHouse2FCopycatPokeDollText
-          or "Oh wow!\nA POKé DOLL!\fFor me?\nCan I have it?", function(yes)
-          if not yes then done() return end
-          game.save.inventory.POKE_DOLL = game.save.inventory.POKE_DOLL - 1
-          if game.save.inventory.POKE_DOLL == 0 then
-            game.save.inventory.POKE_DOLL = nil
-          end
-          if not require("src.inventory.Bag").add(game.save, "TM_MIMIC", 1) then
-            push(game, "You don't have\nroom for TM31!", done)
+      -- Mimic line first; auto-trade POKE DOLL for TM31 (no YES/NO).
+      push(game, t._CopycatsHouse2FCopycatDoYouLikePokemonText, function()
+        if (game.save.inventory.POKE_DOLL or 0) <= 0 then
+          done()
+          return
+        end
+        push(game, t._CopycatsHouse2FCopycatTM31PreReceiveText, function()
+          if not Bag.add(game.save, "TM_MIMIC", 1) then
+            push(game, t._CopycatsHouse2FCopycatTM31NoRoomText, done)
             return
           end
+          game.stringBuffer = game.data.items.TM_MIMIC.name
+          require("src.core.Sound").play(game.data, "Get_Item1")
+          Bag.remove(game.save, "POKE_DOLL", 1)
           game.save.flags.EVENT_GOT_TM31 = true
-          push(game, ("%s got\nTM31!"):format(game.save.player.name), done)
+          push(game, t._CopycatsHouse2FCopycatReceivedTM31Text, function()
+            push(game, t._CopycatsHouse2FCopycatTM31Explanation1Text, done)
+          end)
         end)
-        return
-      end
-      push(game, t._CopycatsHouse2FCopycatText
-        or "I like to mimic\npeople!", done)
+      end)
     end,
   },
 }
@@ -457,6 +482,25 @@ M.ROUTE_24 = {
       battleOrDone()
     end,
   },
+  -- Route24DefaultScript forces TEXT_ROUTE24_COOLTRAINER_M1 whenever the
+  -- player stands on (10,15) in front of the recruiter while
+  -- EVENT_GOT_NUGGET is unset (dbmapcoord 10,15), independent of facing
+  -- or input -- he has no trainer header, so sight never engages him.
+  onStep = function(game, ow, x, y)
+    if game.save.flags.EVENT_GOT_NUGGET then return false end
+    if not (x == 10 and y == 15) then return false end
+    if ow.runner:isRunning() or ow.engaging then return false end
+    local recruiter
+    for _, npc in ipairs(ow.npcs) do
+      if npc.def and npc.def.name == "ROUTE24_COOLTRAINER_M1" then
+        recruiter = npc
+        break
+      end
+    end
+    if not recruiter then return false end
+    ow:showMapText("TEXT_ROUTE24_COOLTRAINER_M1", recruiter)
+    return true
+  end,
 }
 
 -- -------------------------------------------------------------------
@@ -626,11 +670,153 @@ local function e4ExitSeal(flag, closedBlock, openBlock, dontRunText, autoFlag)
   }
 end
 
+-- Lorelei/Bruno/Agatha EndBattleScript (pokered): EndTrainerBattle then
+-- DisplayTextID -> TalkToTrainer, which prints the AfterBattle text on a
+-- win.  engageTrainer only shows the won line, so wrap talk like Lance /
+-- Game Corner Rocket and push header.after immediately after a win.
+local function e4LeaderTalk(afterLabel)
+  return function(game, ow, npc, done)
+    done = done or function() end
+    if ow:trainerDefeated(npc) then
+      local after = text(game)[afterLabel]
+      if after then push(game, after, done) else done() end
+      return
+    end
+    ow:engageTrainer(npc, function()
+      if not ow:trainerDefeated(npc) then
+        done()
+        return
+      end
+      local after = text(game)[afterLabel]
+      if after then push(game, after, done) else done() end
+    end)
+  end
+end
+
 M.LORELEIS_ROOM = e4ExitSeal("EVENT_BEAT_LORELEIS_ROOM_TRAINER_0", 0x24, 0x05,
   "_LoreleisRoomLoreleiDontRunAwayText", "EVENT_AUTOWALKED_INTO_LORELEIS_ROOM")
+M.LORELEIS_ROOM.talk = {
+  TEXT_LORELEISROOM_LORELEI = e4LeaderTalk("_LoreleisRoomLoreleiAfterBattleText"),
+}
 M.BRUNOS_ROOM = e4ExitSeal("EVENT_BEAT_BRUNOS_ROOM_TRAINER_0", 0x24, 0x05,
   "_BrunosRoomBrunoDontRunAwayText", "EVENT_AUTOWALKED_INTO_BRUNOS_ROOM")
+M.BRUNOS_ROOM.talk = {
+  TEXT_BRUNOSROOM_BRUNO = e4LeaderTalk("_BrunoAfterBattleText"),
+}
 M.AGATHAS_ROOM = e4ExitSeal("EVENT_BEAT_AGATHAS_ROOM_TRAINER_0", 0x3b, 0x0e,
   "_AgathasRoomAgathaDontRunAwayText", "EVENT_AUTOWALKED_INTO_AGATHAS_ROOM")
+M.AGATHAS_ROOM.talk = {
+  TEXT_AGATHASROOM_AGATHA = e4LeaderTalk("_AgathaAfterBattleText"),
+}
+
+-- -------------------------------------------------------------------
+-- Lance's room (scripts/LancesRoom.asm). Unlike the other three E4
+-- rooms this one gates its ENTRANCE, not its exit: the .blk ships with
+-- the arena doorway CLOSED (blocks $72/$73 at block (2,6)/(3,6), cells
+-- (4-7,12-13)), and LanceShowOrHideEntranceBlocks OPENS it ($31/$32)
+-- on every map load while EVENT_LANCES_ROOM_LOCK_DOOR is unset.
+-- Without this script the doorway never opened, so the whole arena --
+-- Lance AND both CHAMPIONS_ROOM warps at (5,0)/(6,0) -- was sealed off
+-- from the entrance hall and the league dead-ended here ("goto (6,11)
+-- unreachable on LANCES_ROOM").
+--
+-- LancesRoomDefaultScript's coordinate triggers, all inert once
+-- EVENT_BEAT_LANCE is set:
+--   (5,1)/(6,2)   beside Lance -> his battle starts (a coordinate
+--                 trigger, not a talk; victories.lua OPP_LANCE#1 sets
+--                 EVENT_BEAT_LANCE on the win, so a loss re-arms)
+--   (5,11)/(6,11) the doorway -> CheckAndSetEvent
+--                 EVENT_LANCES_ROOM_LOCK_DOOR: first crossing seals
+--                 the door behind the player with SFX_GO_INSIDE
+--   (24,16)       the entrance staircase -> WalkToLance: an auto-walk
+--                 landing on (6,11). Vanilla WalkToLance_RLEList is
+--                 up 12 / left 12 / down 7 / left 6 and skips collision
+--                 through void tiles; our camera follows that literally
+--                 and briefly shows the empty upper chamber (reads as
+--                 "Gary's room"). We keep the same landing cell but
+--                 route along the open-door floor corridor instead.
+-- -------------------------------------------------------------------
+
+-- Floor corridor (24,16) -> (6,11) with EVENT_LANCES_ROOM_LOCK_DOOR
+-- unset (entrance blocks $31/$32). Exposed for parity tests.
+local LANCE_WALK_IN = {
+  { "down", 2 }, { "left", 6 }, { "down", 5 }, { "left", 10 },
+  { "up", 9 }, { "left", 2 }, { "up", 3 },
+}
+
+local function lanceEntranceBlocks(game, ow)
+  local locked = game.save.flags.EVENT_LANCES_ROOM_LOCK_DOOR
+  ow:replaceBlock(2, 6, locked and 0x72 or 0x31)
+  ow:replaceBlock(3, 6, locked and 0x73 or 0x32)
+end
+
+local function lanceLockDoor(game, ow)
+  if game.save.flags.EVENT_LANCES_ROOM_LOCK_DOOR then return end
+  game.save.flags.EVENT_LANCES_ROOM_LOCK_DOOR = true
+  require("src.core.Sound").play(game.data, "Go_Inside")
+  lanceEntranceBlocks(game, ow)
+end
+
+local function lanceWalkIn(game, ow)
+  local i = 0
+  local function step()
+    i = i + 1
+    local seg = LANCE_WALK_IN[i]
+    if not seg then
+      -- lands on (6,11); vanilla's per-frame coord poll then locks the
+      -- door at once. scriptMove landings do not fire onStep, so lock
+      -- here.
+      lanceLockDoor(game, ow)
+      return
+    end
+    ow:scriptMove(ow.player, seg[1], seg[2], step)
+  end
+  step()
+end
+
+M.LANCES_ROOM = {
+  walkInRoute = LANCE_WALK_IN,
+  onEnter = function(game, ow)
+    lanceEntranceBlocks(game, ow)
+    -- the warp arrival lands ON the staircase trigger, and onStep only
+    -- fires for completed steps -- start the walk-in here, the same
+    -- way Lorelei's auto walk-in runs from its onEnter
+    if not game.save.flags.EVENT_BEAT_LANCE
+       and ow.player.cellX == 24 and ow.player.cellY == 16 then
+      lanceWalkIn(game, ow)
+    end
+  end,
+  onStep = function(game, ow, x, y)
+    if game.save.flags.EVENT_BEAT_LANCE then return false end
+    if (x == 5 and y == 1) or (x == 6 and y == 2) then
+      local lance
+      for _, npc in ipairs(ow.npcs) do
+        if npc.def and npc.def.name == "LANCESROOM_LANCE" then lance = npc break end
+      end
+      if not lance or ow:trainerDefeated(lance) then return false end
+      lance:facePlayer(ow.player)
+      -- LancesRoomLanceEndBattleScript DisplayTextID -> TalkToTrainer
+      -- after-battle text (rival became champion first). engageTrainer
+      -- only shows the won line, so push the after text on a win.
+      ow:engageTrainer(lance, function()
+        if not ow:trainerDefeated(lance) then return end
+        local after = text(game)._LancesRoomLanceAfterBattleText
+        if after then push(game, after) end
+      end)
+      return true
+    end
+    if (x == 5 or x == 6) and y == 11 then
+      lanceLockDoor(game, ow)
+      return false
+    end
+    if x == 24 and y == 16 then
+      lanceWalkIn(game, ow)
+      return true
+    end
+    return false
+  end,
+}
+
+M.CELADON_CHIEF_HOUSE = require("data.scripts.celadon_chief_house")
 
 return M

data/scripts/story5.lua

@@ -196,14 +196,24 @@ local function inCoords(coords, x, y)
   return false
 end
 
--- coordinate block: show a line and push the player back one step
+-- coordinate block: show a line and shove the player back one step.  pokered
+-- shoves with a SIMULATED JOYPAD press (scripts/ViridianCity.asm ViridianCity-
+-- CheckGymOpenScript), which runs the normal overworld step pipeline including
+-- HandleLedges (engine/overworld/ledges.asm), so the shove must HOP a ledge
+-- when one sits in front: the tile below the Viridian Gym door is a down-ledge
+-- (#151).  Gates with no ledge in front (Cinnabar gym lock at (18,4)) get
+-- checkLedgeHop == false and fall back to the plain forced step, unchanged.
 local function stepGate(opts)
   return function(game, ow, x, y)
     if not inCoords(opts.coords, x, y) then return false end
     if not opts.blocked(game) then return false end
     require("src.core.Sound").play(game.data, "Denied")
-    push(game, text(game)[opts.text] or opts.fallback,
-         function() ow:scriptMove(ow.player, opts.push, 1) end)
+    push(game, text(game)[opts.text] or opts.fallback, function()
+      ow.player.facing = opts.push
+      if not ow:checkLedgeHop(opts.push) then
+        ow:scriptMove(ow.player, opts.push, 1)
+      end
+    end)
     return true
   end
 end
@@ -259,23 +269,183 @@ M.CINNABAR_ISLAND = {
   end,
 }
 
--- Pewter's youngster stops you leaving east before Brock is beaten
--- (scripts/PewterCity.asm PewterCityCheckPlayerLeavingEastScript; the
--- original escorts you to the gym, we walk you back a step)
+-- Pewter's youngster stops you leaving east before Brock is beaten and
+-- escorts you to the gym (scripts/PewterCity.asm
+-- PewterCityCheckPlayerLeavingEastScript /
+-- PewterCityYoungsterShowsPlayerGymScript, engine/overworld/auto_movement.asm
+-- PewterGymGuyMovementScriptPointerTable, engine/events/pewter_guys.asm
+-- PewterGymGuyCoords).  Same lockstep style as Oak's lab escort: the
+-- youngster walks RLEList_PewterGymGuy while the player plays the
+-- reverse of RLEList_PewterGymPlayer with a PewterGuys positioning
+-- preamble.  Ends at (11,18) / (12,18) by the gym, not phasing through
+-- the building.
+local pewterEscort = {}
+
+-- RLEList_PewterGymGuy (NPC directions play forward)
+pewterEscort.guySteps = {
+  "down", "down",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left", "left", "left", "left", "left",
+  "up", "up", "up", "up", "up",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left",
+  "down", "down", "down", "down", "down",
+  "right", "right", "right",
+}
+
+-- Walk home: reverse of guySteps with opposite facings (gym → spawn).
+do
+  local opp = { up = "down", down = "up", left = "right", right = "left" }
+  local ret = {}
+  for i = #pewterEscort.guySteps, 1, -1 do
+    ret[#ret + 1] = opp[pewterEscort.guySteps[i]]
+  end
+  pewterEscort.guyReturnSteps = ret
+end
+
+-- RLEList_PewterGymPlayer before reverse / PewterGuys (NO_INPUT, RIGHT×2,
+-- DOWN×5, LEFT×11, UP×5, LEFT×15)
+pewterEscort.playerRle = {
+  "NO",
+  "right", "right",
+  "down", "down", "down", "down", "down",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left",
+  "up", "up", "up", "up", "up",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left", "left", "left", "left", "left",
+}
+
+-- PewterGymGuyCoords: (x, y) -> positioning moves written after the RLE
+-- (played in reverse; $00 pauses are one overworld frame ≈ 1/8 tile for
+-- the NPC, so eight of them ≈ one guy head-start step)
+pewterEscort.preambles = {
+  ["34,16"] = { "left", "down", "down", "right" },
+  ["35,17"] = { "left", "down", "right", "left" },
+  ["37,18"] = { "left", "left", "left",
+                "NO", "NO", "NO", "NO", "NO", "NO", "NO", "NO" },
+  ["37,19"] = { "left", "left", "up", "left" },
+  ["36,17"] = { "left", "down", "left",
+                "NO", "NO", "NO", "NO", "NO", "NO", "NO", "NO" },
+}
+
+-- Realized player path for a trigger tile: PewterGuys overwrites the
+-- last RLE byte and appends the preamble, then simulated joypad plays
+-- high→low (reverse).  Leading NO×8 collapses to guyHeadStart=1; the
+-- trailing end-of-list NO is dropped (one-frame pause).
+function pewterEscort.playerPlan(x, y)
+  local pre = pewterEscort.preambles[x .. "," .. y]
+  if not pre then return nil end
+  local buf = {}
+  for i, d in ipairs(pewterEscort.playerRle) do buf[i] = d end
+  buf[#buf] = pre[1]
+  for i = 2, #pre do buf[#buf + 1] = pre[i] end
+  local path = {}
+  for i = #buf, 1, -1 do path[#path + 1] = buf[i] end
+  local head = 0
+  while path[head + 1] == "NO" do head = head + 1 end
+  local tail = #path
+  while tail > head and path[tail] == "NO" do tail = tail - 1 end
+  local steps = {}
+  for i = head + 1, tail do steps[#steps + 1] = path[i] end
+  return { steps = steps, guyHeadStart = math.floor(head / 8) }
+end
+
+local function pewterGymEscort(game, ow)
+  if ow.runner:isRunning() or #ow.scriptMoves > 0 then return end
+  local x, y = ow.player.cellX, ow.player.cellY
+  local plan = pewterEscort.playerPlan(x, y)
+  local Music = require("src.core.Music")
+  local t = text(game)
+  local follow = t._PewterCityYoungsterYoureATrainerFollowMeText
+    or "You're a trainer\nright? BROCK's\nlooking for new\nchallengers!\nFollow me!"
+  -- PewterGuys only has entries for five tiles; an unmatched talk tile
+  -- (e.g. (36,16) east of him) just gets the follow-me line, same as a
+  -- failed coords lookup would refuse to arm the walk.
+  if not plan then
+    push(game, follow)
+    return
+  end
+  local guy = ow:npcByIndex(5) -- PEWTERCITY_YOUNGSTER
+  local guySteps = pewterEscort.guySteps
+  local head = plan.guyHeadStart
+
+  -- After the walk: face the player, restore map music, "Go take on
+  -- BROCK", then retrace RLEList_PewterGymGuy back to his spawn (35,16).
+  -- (pokered teleports him via MovementData_PewterGymGuyExit; we walk
+  -- the same route home instead.  Brock victory still HideObject's him.)
+  local function walkHome()
+    if not guy then return end
+    local ret = pewterEscort.guyReturnSteps
+    local i = 0
+    local function tick()
+      i = i + 1
+      if not ret[i] then
+        guy.facing = "down"
+        return
+      end
+      ow:scriptMove(guy, ret[i], 1, tick)
+    end
+    tick()
+  end
+
+  local function afterWalk()
+    if guy then guy.facing = "left" end
+    Music.playMap(game.data, "PEWTER_CITY")
+    push(game, t._PewterCityYoungsterGoTakeOnBrockText
+      or "Go take on BROCK\nat the GYM first!", walkHome)
+  end
+
+  local function lockstep()
+    local i = 0
+    local function tick()
+      i = i + 1
+      local ps = plan.steps[i]
+      if not ps then
+        afterWalk()
+        return
+      end
+      local gs = guySteps[head + i]
+      if guy and gs then ow:scriptMove(guy, gs, 1) end
+      ow:scriptMove(ow.player, ps, 1, tick)
+    end
+    tick()
+  end
+
+  local function beginWalk()
+    Music.play(game.data, "Music_MuseumGuy")
+    if guy and head > 0 then
+      local h = 0
+      local function headTick()
+        h = h + 1
+        if h > head then lockstep(); return end
+        ow:scriptMove(guy, guySteps[h], 1, headTick)
+      end
+      headTick()
+    else
+      lockstep()
+    end
+  end
+
+  push(game, follow, beginWalk)
+end
+
 M.PEWTER_CITY = {
+  escort = pewterEscort,
+  -- PewterCityYoungsterText: talking also arms the gym escort script
+  talk = {
+    TEXT_PEWTERCITY_YOUNGSTER = function(game, ow, npc, done)
+      pewterGymEscort(game, ow)
+      if done then done() end
+    end,
+  },
   onStep = function(game, ow, x, y)
     if game.save.flags.EVENT_BEAT_BROCK then return false end
+    if ow.runner:isRunning() or #ow.scriptMoves > 0 then return false end
     if not inCoords({ { 35, 17 }, { 36, 17 }, { 37, 18 }, { 37, 19 } }, x, y) then
       return false
     end
-    local t = text(game)
-    push(game, t._PewterCityYoungsterYoureATrainerFollowMeText
-      or "Hey! You're a\ntrainer, right?", function()
-      push(game, t._PewterCityYoungsterGoTakeOnBrockText
-        or "Go take on BROCK\nat the GYM first!", function()
-        ow:scriptMove(ow.player, "left", 1)
-      end)
-    end)
+    pewterGymEscort(game, ow)
     return true
   end,
 }
@@ -297,6 +467,19 @@ end
 -- EVENT_ROUTE22_RIVAL_WANTS_BATTLE in Oak's lab (expired by Pewter
 -- Gym) and again in Viridian Gym; we derive the same windows from the
 -- surrounding story flags so old saves work too.
+-- Rival1Exit → Viridian (right/down); Rival2Exit → League (left).
+local function route22ExitDirs(n, py)
+  if n == 2 then
+    if py == 5 then return { "left", "left", "left", "left" } end
+    return { "left", "left", "left" }
+  end
+  if py == 5 then
+    return { "right", "right", "down", "down", "down", "down", "down" }
+  end
+  return { "up", "right", "right", "right",
+           "down", "down", "down", "down", "down", "down" }
+end
+
 local function route22Scene(n, objIndex, objName, oppClass, baseParty, beatFlag, py)
   return {
     { "show_object", "ROUTE_22", objName },                    -- 1
@@ -308,7 +491,7 @@ local function route22Scene(n, objIndex, objName, oppClass, baseParty, beatFlag,
     { "set_flag", beatFlag },                                  -- 7
     { "show_text", "_Route22Rival" .. n .. "DefeatedText" },   -- 8
     { "show_text", "_Route22RivalAfterBattleText" .. n },      -- 9
-    { "move_npc_to", objIndex, 25, 5 },                        -- 10
+    { "walk_npc", objIndex, route22ExitDirs(n, py) },          -- 10
     { "hide_object", "ROUTE_22", objName },                    -- 11
   }
 end
@@ -335,6 +518,14 @@ M.ROUTE_22 = {
 -- Cerulean City: the Nugget Bridge rival ambush (CeruleanCityCoords2),
 -- the TM28 rocket thief with his forced-fight cells (Coords1), and the
 -- cave guard who steps aside once you are Champion.
+-- Post-battle: Bill text then CeruleanCityMovement3/4 into town.
+local function ceruleanRivalExitDirs(px)
+  if px == 20 then
+    return { "right", "down", "down", "down", "down", "down", "down" }
+  end
+  return { "left", "down", "down", "down", "down", "down", "down" }
+end
+
 local function ceruleanRivalScene(px, py)
   return {
     { "show_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 1
@@ -342,32 +533,43 @@ local function ceruleanRivalScene(px, py)
     { "face_object", 1, "down" },                              -- 3
     { "show_text", "_CeruleanCityRivalPreBattleText" },        -- 4
     { "rival_battle", "OPP_RIVAL1", 7 },                       -- 5
-    { "jump_if_false", 10 },                                   -- 6
+    { "jump_if_false", 11 },                                   -- 6
     { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },               -- 7
     { "show_text", "_CeruleanCityRivalDefeatedText" },         -- 8
-    { "move_npc_to", 1, 20, 2 },                               -- 9
-    { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 10
+    { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 9
+    { "walk_npc", 1, ceruleanRivalExitDirs(px) },              -- 10
+    { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 11
   }
 end
 
 -- scripts/CeruleanCity.asm CeruleanCityRocketText: fight the thief,
--- then he returns TM28 (DIG) and hurries off
+-- then he returns TM28 (DIG) and hurries off.  CeruleanHideRocket
+-- (CeruleanCity_2.asm) is GBFadeOutToBlack → Show GUARD1 / Hide GUARD2 /
+-- Hide ROCKET → GBFadeInFromBlack — not a bare hide_object.
 local rocketRows = {
   { "face_player" },                                           -- 1
   { "check_flag", "EVENT_GOT_TM28" },                          -- 2
-  { "jump_if_true", 15 },                                      -- 3
+  { "jump_if_true", 15 },                                      -- 3 → CeruleanHideRocket
   { "check_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },        -- 4
   { "jump_if_true", 9 },                                       -- 5
   { "show_text", "_CeruleanCityRocketText" },                  -- 6
   { "start_battle", "trainer", "OPP_ROCKET", 5 },              -- 7
-  { "jump_if_false", 16 },                                     -- 8
+  { "jump_if_false", "end" },                                  -- 8
   { "show_text", "_CeruleanCityRocketIllReturnTheTMText" },    -- 9
   { "set_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },          -- 10
   { "give_item", "TM_DIG", 1, false },                         -- 11 (row 13 prints)
   { "set_flag", "EVENT_GOT_TM28" },                            -- 12
   { "show_text", "_CeruleanCityRocketReceivedTM28Text" },      -- 13
   { "show_text", "_CeruleanCityRocketIBetterGetMovingText" },  -- 14
-  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_ROCKET" },   -- 15
+  { "fade", "out" },                                           -- 15 GBFadeOutToBlack
+  -- CeruleanHideRocket while black: GUARD1 (28,12) appears, GUARD2
+  -- (27,12) and the ROCKET go.  GUARD2 blocks the trashed-house south
+  -- door neighbour — the swap reconnects the city (Bill's ticket does
+  -- the same in story.lua; either route is enough).
+  { "show_object", "CERULEAN_CITY", "CERULEANCITY_GUARD1" },   -- 16
+  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_GUARD2" },   -- 17
+  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_ROCKET" },   -- 18
+  { "fade", "in" },                                            -- 19 GBFadeInFromBlack
 }
 
 M.CERULEAN_CITY = {
@@ -444,10 +646,22 @@ local function bikeGateGuard(coords, stopText, explainText)
   return function(game, ow, x, y)
     if game.save.inventory.BICYCLE then return false end
     if not inCoords(coords, x, y) then return false end
+    -- walk the player up to the tile beside the counter, no further:
+    -- (matchedY - closestY) tiles, 0 when already next to it
+    -- (Route16Gate1FDefaultScript's wCoordIndex-1). Forcing a fixed one
+    -- tile up from the counter-adjacent row shoved the player onto the
+    -- impassable desk and boxed them in.
+    local closestY = coords[1][2]
+    for _, c in ipairs(coords) do
+      if c[2] < closestY then closestY = c[2] end
+    end
+    local dist = y - closestY
     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()
-        ow:scriptMove(ow.player, "up", 1)
+        if dist > 0 then
+          ow:scriptMove(ow.player, "up", dist)
+        end
       end)
     end)
     return true

data/scripts/victories.lua

@@ -2,27 +2,111 @@
 -- "OPP_CLASS#partyIndex" (the object_event trainer args).  Hand-ported
 -- from the leaders'/bosses' text_asm victory scripts:
 --   gym badges: scripts/PewterGym.asm ... ViridianGym.asm
---   Rocket Hideout Giovanni: his Silph Scope is an item ball next to him
---   (data/maps/objects/RocketHideoutB4F.asm), so no reward entry needed.
+--   Rocket Hideout Giovanni: Silph Scope is a hidden item ball revealed by
+--   ShowObject in RocketHideoutB4FBeatGiovanniScript (ported as the
+--   TEXT_ROCKETHIDEOUTB4F_GIOVANNI talk handler in story3.lua).
 -- The TM each gym leader hands out afterwards is also ported.
+--
+-- `deactivate` lists the EVENT_BEAT_* flags each gym's victory script
+-- sets to retire unfought non-leader trainers (PewterGym.asm
+-- "; deactivate gym trainers" / SetEventRange in the other gyms, and
+-- FightingDojo.asm SetEventRange EVENT_BEAT_KARATE_MASTER ..
+-- EVENT_BEAT_FIGHTING_DOJO_TRAINER_3).
+--
+-- `dialogue` is the end-battle + post-battle text chain each gym leader
+-- runs (SaveEndBattleTextPointers then the map's *PostBattle / ReceiveTM
+-- script).  Leaders are not def_trainers entries, so engageTrainer has
+-- no header.won — checkVictoryRewards shows this chain instead of a
+-- synthetic "received badge/TM" stub.
+
+local function range(prefix, first, last)
+  local t = {}
+  for i = first, last do
+    t[#t + 1] = prefix .. i
+  end
+  return t
+end
 
 return {
+  -- PewterGym.asm .gymVictory also HideObject TOGGLE_GYM_GUY
+  -- (PEWTERCITY_YOUNGSTER) and TOGGLE_ROUTE_22_RIVAL_1 so the east-exit
+  -- escort NPC and the first Route 22 rival stay gone after the badge.
   ["OPP_BROCK#1"] = { badge = "BOULDERBADGE", flag = "EVENT_BEAT_BROCK",
-                      item = "TM_BIDE" },
+                      item = "TM_BIDE",
+                      deactivate = { "EVENT_BEAT_PEWTER_GYM_TRAINER_0" },
+                      hide = {
+                        { "PEWTER_CITY", "PEWTERCITY_YOUNGSTER" },
+                        { "ROUTE_22", "ROUTE22_RIVAL1" },
+                      },
+                      dialogue = {
+                        "_PewterGymBrockReceivedBoulderBadgeText",
+                        "_PewterGymBrockBoulderBadgeInfoText",
+                        "_PewterGymBrockWaitTakeThisText",
+                        "_PewterGymReceivedTM34Text",
+                        "_TM34ExplanationText",
+                      } },
   ["OPP_MISTY#1"] = { badge = "CASCADEBADGE", flag = "EVENT_BEAT_MISTY",
-                      item = "TM_BUBBLEBEAM" },
+                      item = "TM_BUBBLEBEAM",
+                      deactivate = range("EVENT_BEAT_CERULEAN_GYM_TRAINER_", 0, 1),
+                      dialogue = {
+                        "_CeruleanGymMistyReceivedCascadeBadgeText",
+                        "_CeruleanGymMistyCascadeBadgeInfoText",
+                        "_CeruleanGymMistyReceivedTM11Text",
+                      } },
   ["OPP_LT_SURGE#1"] = { badge = "THUNDERBADGE", flag = "EVENT_BEAT_LT_SURGE",
-                         item = "TM_THUNDERBOLT" },
+                         item = "TM_THUNDERBOLT",
+                         deactivate = range("EVENT_BEAT_VERMILION_GYM_TRAINER_", 0, 2),
+                         dialogue = {
+                           "_VermilionGymLTSurgeReceivedThunderBadgeText",
+                           "_VermilionGymLTSurgeThunderBadgeInfoText",
+                           "_VermilionGymLTSurgeReceivedTM24Text",
+                           "_TM24ExplanationText",
+                         } },
   ["OPP_ERIKA#1"] = { badge = "RAINBOWBADGE", flag = "EVENT_BEAT_ERIKA",
-                      item = "TM_MEGA_DRAIN" },
+                      item = "TM_MEGA_DRAIN",
+                      deactivate = range("EVENT_BEAT_CELADON_GYM_TRAINER_", 0, 6),
+                      dialogue = {
+                        "_CeladonGymErikaReceivedRainbowBadgeText",
+                        "_CeladonGymRainbowBadgeInfoText",
+                        "_CeladonGymReceivedTM21Text",
+                        "_TM21ExplanationText",
+                      } },
   ["OPP_KOGA#1"] = { badge = "SOULBADGE", flag = "EVENT_BEAT_KOGA",
-                     item = "TM_TOXIC" },
+                     item = "TM_TOXIC",
+                     deactivate = range("EVENT_BEAT_FUCHSIA_GYM_TRAINER_", 0, 5),
+                     dialogue = {
+                       "_FuchsiaGymKogaReceivedSoulBadgeText",
+                       "_FuchsiaGymKogaSoulBadgeInfoText",
+                       "_FuchsiaGymKogaReceivedTM06Text",
+                       "_FuchsiaGymKogaTM06ExplanationText",
+                     } },
   ["OPP_SABRINA#1"] = { badge = "MARSHBADGE", flag = "EVENT_BEAT_SABRINA",
-                        item = "TM_PSYWAVE" },
+                        item = "TM_PSYWAVE",
+                        deactivate = range("EVENT_BEAT_SAFFRON_GYM_TRAINER_", 0, 6),
+                        dialogue = {
+                          "_SaffronGymSabrinaReceivedMarshBadgeText",
+                          "_SaffronGymSabrinaMarshBadgeInfoText",
+                          "_SaffronGymSabrinaReceivedTM46Text",
+                          "_TM46ExplanationText",
+                        } },
   ["OPP_BLAINE#1"] = { badge = "VOLCANOBADGE", flag = "EVENT_BEAT_BLAINE",
-                       item = "TM_FIRE_BLAST" },
+                       item = "TM_FIRE_BLAST",
+                       deactivate = range("EVENT_BEAT_CINNABAR_GYM_TRAINER_", 0, 6),
+                       dialogue = {
+                         "_CinnabarGymBlaineReceivedVolcanoBadgeText",
+                         "_CinnabarGymBlaineVolcanoBadgeInfoText",
+                         "_CinnabarGymBlaineReceivedTM38Text",
+                         "_CinnabarGymBlaineTM38ExplanationText",
+                       } },
   ["OPP_GIOVANNI#3"] = { badge = "EARTHBADGE", flag = "EVENT_BEAT_GIOVANNI",
-                         item = "TM_FISSURE" },
+                         item = "TM_FISSURE",
+                         deactivate = range("EVENT_BEAT_VIRIDIAN_GYM_TRAINER_", 0, 7),
+                         dialogue = {
+                           "_ViridianGymGiovanniReceivedEarthBadgeText",
+                           "_ViridianGymGiovanniEarthBadgeInfoText",
+                           "_ViridianGymGiovanniReceivedTM27Text",
+                           "_ViridianGymGiovanniTM27ExplanationText",
+                         } },
 
   -- Silph Co. Giovanni: unlocks the president's Master Ball gift
   ["OPP_GIOVANNI#2"] = { flag = "EVENT_BEAT_SILPH_CO_GIOVANNI" },
@@ -30,8 +114,12 @@ return {
   -- Fighting Dojo Karate Master (scripts/FightingDojo.asm
   -- FightingDojoKarateMasterPostBattleScript sets EVENT_BEAT_KARATE_MASTER,
   -- which gates the HITMONLEE/HITMONCHAN gift).  OPP_BLACKBELT party 1 is
-  -- only him (data/maps/objects/FightingDojo.asm).
-  ["OPP_BLACKBELT#1"] = { flag = "EVENT_BEAT_KARATE_MASTER" },
+  -- only him (data/maps/objects/FightingDojo.asm).  `dialogue` is the
+  -- concede + prize offer he speaks after the win (his header supplies the
+  -- "Hwa! Arrgh! Beaten!" won line first; #197).
+  ["OPP_BLACKBELT#1"] = { flag = "EVENT_BEAT_KARATE_MASTER",
+                          deactivate = range("EVENT_BEAT_FIGHTING_DOJO_TRAINER_", 0, 3),
+                          dialogue = { "_FightingDojoKarateMasterIWillGiveYouAPokemonText" } },
 
   -- Elite Four progress flags (their rooms' door logic isn't ported, but
   -- the flags make the Hall of Fame checkable)

docs/known-differences.md

@@ -6,4 +6,37 @@ work for true parity. Faithfully-ported behavior is documented in
 docs/behavior-porting-notes.md; deliberate additions beyond the original
 are in docs/new-features.md.
 
-None currently.
+## Reimplemented unused Prof. Oak and Rocket Chief battles
+
+The original ROM defines trainer data for `PROF_OAK` and `CHIEF`
+(`data/trainers/parties.asm`) but never attaches either to an NPC, so
+both battles are unreachable in the real game. This project makes them
+fightable after the Hall of Fame:
+
+- Prof. Oak battles you in Pallet Town once `EVENT_BEAT_CHAMPION_RIVAL`
+  is set, using `ProfOakData`'s three starter-matched teams (the team is
+  picked by the type that counters your starter, mirroring the rival).
+- The Celadon Game Corner Chief battles you in his house post-game.
+  `ChiefData` is empty in the ROM, so `OPP_CHIEF` is given a
+  reconstructed party.
+
+This is an intentional divergence: neither battle can be triggered in the
+original game.
+
+## Reimplemented unused Silph Co. card-key doors
+
+`engine/events/card_key.asm` and the unused `CardKeyTable1/2/3` coordinate
+lists (`data/events/card_key_coords.asm`) describe locked doors for Silph
+Co. floors 2F-11F, but no retail `.blk` map layout ever places the closed
+door block at those coordinates, so the card key check is dead code in
+the original game. This project stamps the closed door block (`$54`/`$5f`
+on floors 2F-10F, `$20` on 11F) over each of the 20 door coordinates on
+map load, and swaps it for the open block once that door's
+`EVENT_SILPH_CO_n_UNLOCKED_DOORn` flag is set (using the key from a Team
+Rocket grunt, as in the original's unused design).
+
+This is an intentional divergence: the doors are not visible or
+functional in the original game. The door layout lives in
+`tools/rom_manifest.json` (`field.cardKeyDoors.closedDoors`), hand-ported
+since no retail ROM data encodes it; `src/import/RomExtractor.lua` copies
+it straight through on ROM import.

docs/launcher.md

@@ -0,0 +1,195 @@
+# Launcher
+
+The launcher is `src/import/RomImporter.lua`, the first-run / title screen
+that runs before `Game:load`. Besides ROM import (see the file's own header)
+it hosts a tabbed shell covering per-game save slots and a mod manager. This
+file documents the runtime model; the visual spec lives separately.
+
+## Android multi-ROM / mod / save import
+
+On Android, `love.system.pickFile([kind])` opens the Storage Access Framework
+picker (`GameActivity.showFilePicker`); the chosen file is copied into the app
+save directory as:
+
+| `kind` | Destination |
+| --- | --- |
+| nil / `"rom"` | `picked_rom.gb` (open) |
+| `"mod"` | `picked_mod.zip` (open) |
+| `"sav"` / `"save"` | `picked_save.sav` (open) |
+
+Export uses a separate API: `love.system.createFile(suggestedName)` →
+`GameActivity.showCreateDocument` (`ACTION_CREATE_DOCUMENT`), which copies
+staged `pending_export.sav` to the user-chosen URI and writes `export_done.flag`
+for the launcher to acknowledge on refocus.
+
+`RomImporter` then imports on refocus / Choose:
+
+- **ROMs** via `findPendingRom`: only a 1 MiB `.gb` whose SHA-1 maps to a
+  version that is **not** yet ready counts as pending. A leftover
+  `picked_rom.gb` from Red therefore cannot block Blue's Choose (issue #167).
+- **Mods** via `findPendingMod`: Prefer `picked_mod.zip`, or (on Choose) any
+  other `.zip` at the save-dir root (USB copy).
+- **Saves** via `findPendingSav`: Prefer `picked_save.sav`, or (on Choose) any
+  other `.sav` at the save-dir root.
+
+After a successful import the consumed save-dir file is removed.
+
+**Manual check (device/emulator):** import Red → switch to Blue → Choose →
+system file picker must appear (not a silent Red re-extract) → pick Blue →
+Blue becomes ready beside Red. On the MODS tab, Import mod .zip must open the
+same system picker and install the chosen archive on return.
+
+## Tab structure
+
+`self.tab` is one of `"red"`, `"blue"`, `"yellow"`, `"mods"`. The tab bar
+draws one chip per game plus a MODS chip and rebuilds `self.tabRects` every
+frame so `mousepressed` can dispatch clicks; switching tabs mid-import is
+allowed (a dropped ROM still routes by SHA-1 regardless of which tab shows).
+
+- A game tab (`_drawGamePanel`) shows the ROM card, the SAVE FILES card, the
+  Play button, and the SAVE SLOT card in a responsive two-column grid (see
+  Responsiveness). The MODS tab (`_drawModsPanel`) shows the mod list instead.
+- The self-updater banner (`self.Check`, see `docs/updater.md`) draws as a
+  centered pill in a reserved band just above the footer, on every tab. That
+  position is unchanged by this redesign, so `docs/updater.md` needed no edits.
+
+## Save slot model
+
+All slot I/O lives in `src/core/SaveData.lua` and goes through the same fs
+abstraction (`persistFs`) every other save/options call uses, so portable
+mode (an `io.*` filesystem used when `portable.txt` marks the install)
+keeps working unchanged.
+
+- **Files.** A version's playthroughs live under `saves/<version>/`, one file
+  per slot: `saves/<version>/slot1.lua` plus a rolling `.bak` and staged
+  `.tmp` witness (`slotNames`), mirroring the write/recovery discipline
+  `SaveData.save`/`load` already use for the flat legacy file. Slot ids match
+  `slot%d+`; `createSlot` allocates one past the highest existing number so a
+  reused id can never collide with a lingering file.
+- **Registry.** The ordered slot list and which one is active persist in
+  `options.lua` (via the existing `SaveData.loadOptions`/`saveOptions`):
+  `options.saveSlots = { [version] = { list = {"slot1", ...}, active = "slot1" } }`.
+- **Active slot resolution.** `saveNames(version)`, the function every
+  existing caller (`TitleState` hasSave/load/save, recovery order) already
+  goes through, now resolves the *active* slot instead of a fixed flat name.
+  Resolved once per version per process (`ensureVersionSlots`, cached in
+  `activeSlotCache`/`slotsChecked`): a registry entry wins; otherwise a lazy
+  legacy migration may create one; otherwise the flat legacy path is used
+  (`save.lua` / `save_blue.lua`), so a pre-slots install keeps working as before.
+- **Legacy migration.** One-time per version, lazy on first
+  `listSlots`/`load`/`saveNames` call (`tryMigrateLegacy`): if a flat legacy
+  file exists and no `saves/<version>/` registry does, its main + `.bak` are
+  copied into `saves/<version>/slot1.lua(.bak)`, verified readable
+  (`decodeSlot`: main, then `.tmp`, then `.bak`), and only then are the
+  originals removed and `slot1` registered as active. A copy that fails to
+  verify leaves the originals in place; migration never loses data.
+
+The launcher-facing API:
+- `SaveData.listSlots(version)` -> array of `{id, exists, name, meta}` for
+  every registered slot. `name` is the save's player name, or `nil` for an
+  empty slot; `meta` is `{badges, timeText, dexCount}` (the same fields the
+  title screen's `ContinueInfo` shows) or `nil`. The pure part,
+  `SaveData.slotSummary(save)`, is unit-testable with no filesystem.
+- `SaveData.setActiveSlot(version, slotId)` registers the id if new, persists
+  it as active, and updates the process cache so the very next save/load
+  lands there. The launcher calls this the moment a slot row is clicked
+  (`RomImporter:_selectSlot`); pressing Play needs no signature change, since
+  `Game.lua`/`main.lua` still just call `SaveData.load()`/`save()`.
+- `SaveData.createSlot(version)` -> new slot id, registered but with **no
+  save file written**. An empty slot means the title screen offers NEW GAME
+  only, which needs no further changes.
+- `SaveData.deleteSlot(version, slotId)` removes the slot's
+  main/`.bak`/`.tmp` files, drops it from the registry, and if it was active
+  points active at another remaining slot (or clears active when the list is
+  empty). The launcher's SAVE SLOT panel Delete control calls this.
+
+## Launcher mod manager
+
+`src/mods/LauncherMods.lua` is a launcher-only read of the mod set. It runs
+before `Game:load`, so **it never loads a mod's entry chunk**; only
+`manifest.json` is read and validated (`src/mods/Manifest.validate`), the way
+`Loader:_discover` finds mods without running them. The real loader
+(`src/mods/Loader.lua`) still owns the actual load at boot.
+
+- `LauncherMods.list()` scans `mods/` one level deep (first id wins on a
+  duplicate) and returns one row per mod:
+  `{id, name, version, badge, description, enabled, status, statusDetail}`.
+  `badge` is the manifest's `category`, falling back to `profile`, then
+  `"MOD"`, uppercased. `enabled` reads `options.mods[id]` (missing means
+  enabled, matching the loader's own default).
+- `status` is `"ok"`, `"warn"`, or `"conflict"`, computed by the pure
+  `LauncherMods.deriveList`/`statusFor` against `ManagerState.resolveToggle`
+  and the validated manifests: `conflict` when enabling this mod collides
+  with another enabled one; `warn` for an out-of-range `game_version` or an
+  absent/disabled/wrong-version hard dependency; `ok` otherwise. Having no
+  `love.*` calls, this half is table-driven by the test suite on its own.
+- `LauncherMods.setEnabled(id, bool)` persists `options.mods[id]` as a plain
+  boolean, the exact shape `Loader:_saveState` writes, so the running game
+  and the in-game `ManagerState` see the change on next boot. The mods panel
+  calls this on every toggle and re-derives the list right away
+  (`RomImporter:_refreshMods`) so a status change (e.g. a new conflict)
+  shows without waiting for a reload.
+- `LauncherMods.installZip(path)` mounts the archive with
+  `love.filesystem.mount`, locates the mod root via `locateRoot` (manifest at
+  the zip root, or inside one top-level folder), validates its manifest, and
+  copies the tree into the save-dir `mods/<id>/` before unmounting. Rejects a
+  duplicate of an already-installed mod id, and accepts either an external
+  path string or a LOVE `DroppedFile`, staging a dropped file into a save-dir
+  temp first (mount only reaches save-dir-relative paths), the same way
+  `RomImporter` handles a dropped ROM. A failed copy rolls its partial tree
+  back, and every path unmounts and clears the staged temp file.
+- `LauncherMods.uninstall(id)` removes `mods/<id>/` and clears
+  `options.mods[id]` so a later reinstall starts from the loader's default
+  (enabled). The mods panel Delete control calls this and re-derives the list.
+
+## Import / Export save
+
+The SAVE FILES card wires a raw Gen1 `.sav` battery image to the save slots
+through `src/import/SaveFileIO.lua`, which sits on top of
+`src/save_convert/SaveConvert.lua` and the slot API in `SaveData`.
+
+- **Import save** is live once the game's ROM is imported (playable). It opens
+  a native `.sav` picker (`chooseSav` on desktop; on Android,
+  `love.system.pickFile("sav")` → `picked_save.sav`, same SAF path as ROMs).
+  `SaveFileIO.importToSlot` reads the bytes (an absolute path, a save-dir
+  relative name, a dropped LOVE file, or raw bytes),
+  guards the 32768-byte size, runs `SaveConvert.importSav` (which also rejects
+  a bad main-data checksum), then registers a fresh slot (`SaveData.createSlot`),
+  writes it (`SaveData.writeSlot`), and makes it active (`SaveData.setActiveSlot`).
+  The meta stamp is re-stamped off `gen1_import` to the current numeric format
+  so `SaveData.load`'s migration pass accepts the slot. On success the SAVE SLOT
+  panel is refreshed with the new slot selected.
+- **Export save** is live only when the active slot actually holds a save
+  (checked against `listSlots`). `SaveFileIO.exportActiveSlot` loads the active
+  slot, encodes it back with `SaveConvert.exportSav` (a slot never keeps
+  `rawImport`, so this is a zero-filled template export, which is valid), and
+  writes `exports/gen1recomp-<version>-<slotId>.sav` in the save directory
+  (`love.filesystem.createDirectory("exports")`). On desktop it returns the
+  absolute path (`love.filesystem.getSaveDirectory()`), which the notice line
+  shows with an "Open folder" affordance (`love.system.openURL("file://" .. dir)`).
+  On Android the bytes are also staged as `pending_export.sav` and
+  `love.system.createFile(suggestedName)` opens `ACTION_CREATE_DOCUMENT` so the
+  player can save to Downloads / Drive / etc.; on return `export_done.flag`
+  makes focus show "Save exported."
+- **Drag-drop.** `filedropped` routes a `.sav` to the import path for the
+  currently active game tab; when a non-game tab (mods, or the locked yellow
+  placeholder) is showing it defaults to red, the always-present first game
+  (`_savedropTarget`). `.gb` (ROM) and `.zip` (mod) routing is unchanged.
+- **Failure UX.** Every error path (wrong size, bad checksum, write failure,
+  nothing to export, ROM not imported yet) surfaces as a red notice line on the
+  card. Nothing raises and nothing silently no-ops.
+
+`SaveFileIO` is love-free enough to unit-test through the same in-memory
+filesystem stub the slot backend uses (`tests/engine/save_file_io_tests.lua`).
+
+## Responsiveness
+
+Every measurement derives from `love.graphics.getDimensions()` each frame
+plus the existing global scale `s = clamp(height / 768, 0.7, 1.6)`; nothing
+assumes a fixed window size. The game panel's two-column grid (ROM/SAVE
+FILES/Play on the left, SAVE SLOT on the right) collapses to one stacked
+column, slot card below Play, when the window is too narrow for both
+`~300 * s`-wide columns. The save-slot list and the mod list both scroll
+(wheel, or drag on touch/desktop) clamped to their own content extent,
+recomputed every draw. The tab bar labels only the active chip so it stays
+narrow-safe, and content caps out at `~1440 * s` wide, centered.

docs/modding.md

@@ -17,3 +17,138 @@ Regenerate the reference straight into a wiki checkout:
 ```sh
 luajit tools/gen_registry_docs.lua ../pokemon-gen1-recomp-project.wiki
 ```
+
+## Rendering pipelines
+
+Most registries hand the engine *content*. `render_pipelines` hands it
+*drawing*: a pipeline is a display mode a mod owns, which may replace the
+overworld's world pass with geometry of its own and/or post-process the
+finished image. `mods/voxel_world` is the worked example — a 3D diorama
+overworld plus a tilt-shift miniature pass, in about 120 lines of glue over
+its renderer.
+
+A record declares what the mode *is*; the engine
+(`src/render/Pipelines.lua`) supplies everything about *being a display
+mode*: the OFF/1/2/3 ladder, an options row next to TILT, a hotkey,
+persistence in `save.options.pipelines`, and the rule that a world pipeline
+and the engine's own TILT are mutually exclusive.
+
+```lua
+mod.content.render_pipelines:register("diorama", {
+  label = "DIORAMA",                    -- options row label
+  levels = { "OFF", "15", "35", "50" }, -- ladder; defaults to OFF/ON
+  hotkey = "6",                         -- checked after the engine's keys
+  priority = 20,                        -- highest eligible wins the world
+  available = function() return Renderer3D.ok() end,
+  update = function(dt, level) Camera.ease(dt, level) end,
+  drawWorld = function(ctx) return renderScene(ctx) end,
+})
+```
+
+Three draw stages, each optional; a record needs at least one:
+
+| stage | signature | runs |
+| --- | --- | --- |
+| `drawWorld` | `(ctx) -> canvas \| nil` | instead of the flat/tilt world pass |
+| `worldPresent` | `(canvas, ctx) -> canvas` | over the world, **before** the UI composites |
+| `present` | `(canvas, ctx) -> canvas` | over the whole frame, world and UI alike |
+
+`worldPresent` is the one to reach for when an effect must leave dialog
+boxes and menus crisp — a depth-of-field or colour grade on the world only.
+`present` is for effects that genuinely own the screen, like a CRT curve.
+
+`ctx` carries the frame: `state`, `cam`, `vw`/`vh` (world-pixel view),
+`width`/`height` (window pixels), `scale`, `level`, `paletteFor(map)` and
+`spriteColors(map)`. It also carries `ctx.drawFx(project, scale)` — call it
+with your own projection and the engine draws every active field effect
+(the "!" bubble, the Poké Center heal machine, the Fly bird, the fishing
+rod, Rock Tunnel darkness) at its correct anchor under your camera. There
+is exactly one copy of each effect, so a new engine effect works in your
+pipeline without you touching anything.
+
+Three rules worth knowing:
+
+- **`gate` governs input, never the draw.** It decides whether the player
+  may *change* the mode (default: free-roam overworld only). A mode that
+  stopped rendering during a warp would flash the flat 2D world every time
+  the player walked through a door.
+- **`available` is re-read every frame** and is the only thing that decides
+  whether the mode can render at all. Answer `false` on a headless run or a
+  driver with no depth canvas and the engine silently keeps the vanilla 2D
+  path — which is why shipping a pipeline enabled is safe.
+- **A callback that throws retires its pipeline**, attributed to your mod in
+  the manager's error feed, and the frame falls back to 2D. A broken
+  renderer costs the player a display mode, never the game.
+
+Returning `nil` from `drawWorld` is a normal answer meaning "not this
+frame"; the engine draws the vanilla world instead.
+
+## Battle sprite scaling
+
+The enemy's front pic draws at 1x and the player's back pic at 2x, the way
+the Game Boy did. A mod can override either, per species or per image.
+
+Per species, on the `pokemon` record:
+
+```lua
+-- MEW's back pic renders 1.5x; its front pic is untouched
+mod.content.pokemon:patch("MEW", { battleScaleBack = 1.5 })
+```
+
+`battleScaleFront` scales the enemy pic, `battleScaleBack` the player pic;
+both take a number in `0.25 .. 4.0`.
+
+Per image, on the `battle_sprite_scales` registry, keyed by the asset path
+exactly as the data references it:
+
+```lua
+mod.content.battle_sprite_scales:register("abra_back", {
+  path = "assets/generated/battle/back/abrab.png",
+  scale = 1.5,
+})
+```
+
+An image-level entry beats the species scale for that one pic, and it is
+the only way to scale a pic that is not species-keyed — the player's
+trainer back sprite, held on screen until "Go!", is a bare image path.
+
+The resolution order at draw time is **image-level → species-level →
+default** (1x front, 2x back).
+
+- **The pic stays grounded at every scale.** The player pic keeps its feet
+  flush on the text-box top (`y = 96`); the enemy pic keeps its bottom edge
+  and horizontal centre pinned in its 7×7 slot. A larger pic grows upward
+  and outward from that anchor, never off the shelf.
+- **Scaling composes with the send-out grow.** The `AnimateSendingOutMon`
+  ball-to-pic grow multiplies your scale through each stage, so a rescaled
+  mon still grows into place from the ball, grounded the whole way.
+
+## Developer console
+
+Boot with developer mode on to unlock the in-game console and hot-reload
+hotkeys. Either set `POKEPORT_DEV=1` in the environment or pass
+`--developer` on the command line:
+
+```sh
+love . --developer
+```
+
+While developer mode is active:
+
+- `` ` `` (backtick) opens the console overlay — a Lua REPL with `game`,
+  `data` and `mods` in scope. Press `` ` `` again to close it.
+- `F5` hot-reloads mods and asset caches without restarting.
+
+The console understands these verbs (anything else is evaluated as Lua):
+
+- `warp MAP [x y]` — teleport to a map (default cell 5,5).
+- `give ID [n|level]` — add an item (count) or a Pokémon (level).
+- `flag NAME [on|off]` — read or set an event flag.
+- `party` — dump the current party.
+- `mods` — list loaded mods and their state.
+- `reload` — hot-reload mods (same as `F5`).
+- `trace PAT | trace off` — trace events/hooks matching a glob pattern.
+- `help` — list the verbs.
+
+Developer mode also arms the mod loader's dev tripwire, which flags mods
+that reach outside their permission set.

docs/new-features.md

@@ -8,27 +8,42 @@ behavior is in docs/behavior-porting-notes.md.
 
 ## Survey zoom
 
-The mouse wheel (or `-`/`=`) zooms the overworld between 1 pixel per world
-pixel (full survey) and 2× the window fit scale (close-up), in crisp
-integer steps. This has no Game Boy equivalent:
+The mouse wheel (or `-`/`=`), the Options **ZOOM** row, or hotkey `4`
+zooms the overworld between 1 pixel per world pixel (full survey) and 2×
+the window fit scale (close-up), in crisp integer steps. This has no Game
+Boy equivalent:
 
 - Connected maps render their full bodies, and their NPCs appear as
   visual-only "ghosts",  they wander but have no sight lines, triggers,
   dialogue, or collision until the map is actually entered.
 - Menus, text boxes, and battles draw at normal scale on top of the
   zoomed world. Zoom input is ignored while a script, menu, or battle is
-  active; the zoom level persists across warps and is never saved.
-- Beyond the border ring the border block repeats indefinitely (interiors
-  stay black, seaside towns stay water,  except OVERWORLD-tileset maps,
-  whose beyond-edge space fills with the solid tree wall instead of the
-  per-map border block), and each visible map area is colorized with its
-  own SGB palette (the original recolored the whole screen per map).
+  active; the zoom offset is persisted as `save.options.zoom` (default
+  `0` = FIT) and survives New Game via `options.lua`.
+- Hotkey `4` ticks through every integer zoom level (survey → FIT →
+  close-up → wrap). The Options row shows `FIT` / `OUTn` / `INn`.
+- Beyond the border ring the void fill repeats indefinitely (see VOID
+  FILL below); interiors keep their own border block. Each visible map
+  area is colorized with its own SGB palette (the original recolored the
+  whole screen per map).
 - Neighbor maps load two connection hops out so corner-adjacent maps
   don't pop in and out, and ghost NPCs share instances with the real ones
   so their wander positions persist across seamless connection crossings
   (a warp or fresh map entry still respawns everything at its script
   position, like the original's per-entry sprite init).
 
+## VOID FILL
+
+The Options **VOID FILL** row picks what paints the infinite beyond-edge
+space on OVERWORLD-tileset maps during survey zoom:
+
+- **TREES** (default): solid tree wall block `$0F`.
+- **WATER**: animated water tile `$14` (same hshift cycle as on-map water).
+- **BLACK**: solid black.
+
+Other tilesets are unchanged (house/cave borders stay as authored).
+Persisted as `save.options.voidFill`.
+
 ## Tilt mode
 
 The `3` key (and the Options menu TILT row) cycles a visual-only perspective
@@ -42,8 +57,10 @@ Game Boy equivalent:
   rows above the player recede and rows below come toward the viewer. Only
   things that actually *stand* on the ground draw as upright billboards,
   unscaled and pixel-identical to flat mode: the player, NPCs, item balls,
-  and the screen-anchored FX attached to them (heal machine glow, emote
-  bubbles, the fishing rod, the FLY bird). An earlier revision tried
+  and the standing FX attached to them (emote bubbles, the fishing rod,
+  the FLY bird). The Poké Center heal-machine overlay stays on the ground
+  plane with the machine tiles (it is OAM glued to a BG graphic, not a
+  standing sprite). An earlier revision tried
   billboarding buildings/trees/signs too (cutting them out of the ground
   per hand-curated per-tileset tables); that chased an endless tail of
   special cases,  dense tree canopy, fences fused into grass, building
@@ -68,19 +85,31 @@ Game Boy equivalent:
 
 ## Colors mode
 
-The `2` key (and the Options menu COLORS row) cycles the global shade-remap
-display mode through **GBC → OG → OG INV → GBC INV → CLASSIC → GBC**:
+The `2` key (and the Options menu COLORS row) cycles the display mode
+through **OG RED → SGB → RED++ → OG → OG INV → SGB INV → CLASSIC → OG RED**.
+The first three are the real colorizations; the rest are DMG-shade novelties:
 
-- **GBC** (default): current SGB / GBC zone palettes.
+- **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`).
+- **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".)
+- **RED++**: pokered-gbc SuperPalettes -- real per-tile GBC coloring plus
+  per-species mon colors (`data/palettes_gbc.lua`).
 - **OG**: force the four DMG grays (colorization off).
 - **OG INV**: inverted DMG grays.
-- **GBC INV**: each SGB zone palette with shade order reversed.
+- **SGB INV**: each SGB zone palette with shade order reversed.
 - **CLASSIC**: original Game Boy pea-soup greens
   (`#9BBC0F` / `#8BAC0F` / `#306230` / `#0F380F`).
 
-The transform is applied centrally in `PaletteFX.sendColors`, so it covers
-overworld, menus, battles, and tilt upright billboards. Persisted as
-`save.options.colors`.
+The shade-remap transform is applied centrally in `PaletteFX.sendColors`, so
+it covers overworld, menus, battles, and tilt upright billboards. OG RED's
+global BG palette is supplied by `OverworldState:overworldBgColors` (per-map
+override in the overworld pass). Persisted as `save.options.colors`; the
+`gbc` / `gbc_inv` save ids are kept for back-compat under the new labels.
 
 ## GBC FX
 
@@ -125,13 +154,77 @@ Nidorino-vs-Gengar attract scene) mirror the original.
 Options persist in a standalone `options.lua` (separate from the game
 progress `save.lua`), so audio/display/battle preferences survive New Game
 and aren't wiped when a save slot is cleared. Changing a row in the Options
-menu or cycling hotkeys `2`/`3`/`5` writes immediately; an in-game save also
+menu or cycling hotkeys `2`/`3`/`4`/`5` writes immediately; an in-game save also
 flushes the live options. Old saves that still embed an `options` table are
 migrated once into `options.lua` on load.
 
 - Music / SFX volume
 - Music Filter
 - OG GLITCHES on / off (Gen 1 quirks vs. modern-clean battle rules)
-- COLORS (GBC / OG / OG INV / GBC INV / CLASSIC),  also hotkey `2`
+- COLORS (OG RED / SGB / RED++ / OG / OG INV / SGB INV / CLASSIC),  also
+  hotkey `2` (OG RED = GBC boot-ROM look; RED++ uses pokered-gbc
+  SuperPalettes + per-species mon colors)
 - TILT (OFF / 15 / 35 / 50),  also hotkey `3` while free-roaming
-- GBC FX (OFF / 1 / 2 / 3 / 4),  also hotkey `5`
+- ZOOM (FIT / OUTn / INn),  also hotkey `4` while free-roaming; wheel and
+  `-`/`=` step one level and save
+- VOID FILL (TREES / WATER / BLACK) for OVERWORLD beyond-edge space
+- GBC FX (OFF / 1 / 2 / 3 / 4),  also hotkey `5`
+- MAX FPS (30 / 40 / 50 / 60 / 75 / 90 / 100 / 120 / 144 / 160, default 60),
+  a hard render frame-rate cap (`save.options.fpsCap`).
+
+## Battle transition cascade + white battle letterbox
+
+Into-battle wipes still run the original eight styles inside the classic
+160×144 letterbox. On wide/tall windows (survey zoom), matching black 8×8
+blocks cascade outward from that square into the surrounding world so the
+void outside the OG wipe fills in lockstep. Once the battle state is up,
+letterbox voids around the battle canvas fill **white** instead of black
+so the whole window reads as one continuous battle screen.
+
+## On-screen touch controls (mobile)
+
+On Android/iOS the game draws a translucent d-pad (bottom-left), A/B
+buttons (bottom-right, Game Boy diagonal), and +/- START/SELECT (bottom
+center) over the frame, using Xelu's CC0 controller prompts
+(`assets/touch/`). Real buttons, not gestures: press lands the frame the
+finger does, sliding on the d-pad changes direction without lifting, and
+multi-touch chords (e.g. hold a direction + tap B) work. The overlay only
+appears while no controller is being used: the first gamepad button or
+stick push hides it, the next screen touch brings it back, and unplugging
+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).
+## Translation support
+
+Every string the player can read is now reachable from a mod, so a
+translation is an ordinary content mod rather than a fork.
+
+Two things had to change. Text layout stopped counting bytes: the dialogue
+box measures a line in glyphs (charmap sequences), so a 3-byte character
+costs one column, a cut never lands inside a character, and a page with a
+non-default `advance` re-measures instead of overflowing. That also fixed
+25 vanilla English lines that were wrapping early because `é` in POKéMON
+and POKéDEX costs two bytes ("I study POKéMON as" is 19 bytes and 18
+glyphs, and the box was breaking it).
+
+Second, the text the engine writes itself - battle messages, item results,
+menu labels, the link-play screens - moved behind `src/core/Strings.lua`
+and the new `strings` registry. Extracted script text was already
+overridable through `text`; this covers the other half. Entries are keyed
+by the English source, so a translation that has not reached a string yet
+keeps rendering in English and a half-finished translation stays playable.
+
+Authors generate the whole thing:
+
+```sh
+python3 tools/modkit.py translation francais --language "Francais"
+```
+
+That scaffolds a mod with every translatable string as an empty catalog,
+plus a glyph-page and charmap stub, a naming-grid stub, and a
+`francais-worksheet/` directory holding the English to translate from
+(deliberately outside the mod: extracted text is ROM content and must not
+be packed). `--refresh` re-harvests after an engine update, keeping
+existing translations and parking orphaned keys rather than dropping them.
+
+See the wiki's Translations guide.

docs/updater.md

@@ -0,0 +1,126 @@
+# Updater
+
+A fused build (`love.filesystem.isFused()` true) ships a bundled `game.love`
+baked into the executable, but that bundled copy is only ever the *fallback*.
+On every launch, before anything else runs, `Boot.run` (`src/update/Boot.lua`)
+looks in the save directory's `updates/` folder for a downloaded
+`gen1recomp-X.Y.Z.love` payload that is both strictly newer than the bundled
+engine version and runnable on this shell. If one qualifies, it is mounted
+over `/` (so its files win over the fused source for every subsequent
+`require`) and chainloaded in place: the payload's `main.lua` and `love.load`
+run as if they had shipped in the executable. A dev/source checkout is never
+fused, so `Boot.run` no-ops there and the working tree always runs itself.
+
+The pieces are deliberately layered so the risky part is small. `Boot.select`
+is a pure function (no `love.*` calls) that, given probed candidates and the
+bundled `engine`/`shell`, decides what to run and what stale payloads to
+delete. `Boot.probePayload` mounts one archive at an isolated mountpoint and
+reads its `src/core/Version.lua` with `loadstring` (never `require`, so it is
+never cached as a module) to learn its `engine` and `minShell`. `Boot.run`
+orchestrates the crash guard, enumeration, selection, and the mount +
+chainload, with full rollback on any failure. Checking for and fetching a
+new payload is a separate, slower path: `src/update/Check.lua` is a thin
+main-thread state machine the launcher screen polls, while the curl calls,
+JSON parsing, and sha256 verification run on a background `love.thread`
+(`src/update/check_worker.lua`) so a hung network call never blocks a frame.
+
+## Version.lua fields
+
+`src/core/Version.lua` carries three fields the updater reads directly (the
+existing `modApi`, `linkProtocol`, `saveFormat`, and `cache` fields are
+untouched):
+
+- `engine` - the semver release, e.g. `"1.4.0"`. The repo default is the
+  `"0.0.0-dev"` placeholder; CI stamps the real `X.Y.Z` into the packed
+  `game.love` only, never the working tree. A `"0.0.0-dev"` engine always
+  reports itself up to date (it never chases a release, and it never counts
+  as a valid payload to chainload).
+- `shell` - the native-shell contract this build's fused executable
+  implements.
+- `minShell` - the lowest shell contract required to *run* this payload.
+
+Bump `minShell` only when a payload needs something the currently-shipped
+native shell cannot provide, for example a LOVE version bump, a new required
+system binary, or a change to `love.run` itself (see Known limitations
+below). An older shell refuses to chainload a payload whose `minShell`
+exceeds the shell it provides; `Boot.select` keeps that payload in `updates/`
+rather than deleting it, in case a future shell upgrade can run it, and
+`Check`'s worker reports `needs_full` so the player is pointed at a full
+installer instead. Do not bump `minShell` for an ordinary Lua/data release;
+that is exactly the case the updater exists to avoid a reinstall for.
+
+## Release assets
+
+Each tagged release `vX.Y.Z` carries the existing per-platform archives
+(`gen1recomp-X.Y.Z-macos.zip`, `-windows.zip`, `-linux.zip`,
+`-android.apk`) plus two assets the updater itself consumes:
+
+- `gen1recomp-X.Y.Z.love` - the payload, matched by the exact pattern
+  `gen1recomp-<version>.love` (see `isPayloadName` in `Boot.lua` and
+  `Check.parseRelease`).
+- `sha256sums.txt` - `shasum -a 256` output (`<hex>  <filename>`, bare
+  filenames) covering at least the `.love` payload. `Check.parseSums`
+  tolerates a leading `*` binary marker and a `./` prefix but expects the
+  filename otherwise to match the asset name exactly.
+
+A release missing either asset is treated as "no in-place update available":
+`Check` reports `needs_full` and sends the player to `Check.releaseUrl()`
+(`https://github.com/bryanthaboi/pokemon-gen1-recomp-project/releases/latest`).
+
+## Save-directory layout
+
+Under the save directory (identity `pokemon-love2d`):
+
+```
+updates/gen1recomp-<X.Y.Z>.love   downloaded payload(s)
+updates/pending.txt                crash-guard marker
+```
+
+`pending.txt` holds the filename of the payload currently being chainloaded.
+`Boot.run`'s `chainload` writes it immediately before mounting, and removes it
+on both a successful handoff and a clean rollback. If it is still present the
+*next* time `Boot.run` starts, the previous boot died mid-handoff, so that
+named payload is distrusted: it and the marker are deleted before candidates
+are enumerated. Boot may still fall back to an older valid payload, or to the
+bundled game, in that case.
+
+## Update flow
+
+1. **Boot** (every launch, fused builds only): crash-guard check, enumerate
+   and probe every `updates/*.love`, pick the highest engine that is
+   strictly newer than the bundled one and whose `minShell` this shell
+   satisfies, delete stale payloads, chainload the winner (or run the
+   bundled game if none qualifies).
+2. **Check** (launcher screen): `Check.start()` kicks off an async check
+   against the GitHub releases API; safe to call every frame, it is a no-op
+   once a check is in flight or has reached a terminal state. `Check.state()`
+   reports `idle | checking | uptodate | available | downloading | ready |
+   needs_full | error` plus the latest version and download progress.
+3. **Download + verify**: on `available`, `Check.download()` tells the
+   worker to fetch the payload, polling the growing `.part` file for
+   progress. On completion the worker re-fetches `sha256sums.txt`, verifies
+   the payload's sha256, and probes it with `Boot.probePayload` to gate its
+   `minShell` against this shell's `shell`. A verified, runnable payload is
+   renamed into place and reported as `ready`; anything else reports
+   `error` or `needs_full` and leaves `updates/` clean.
+4. **Restart to apply**: a `ready` payload just sits in `updates/` until the
+   player relaunches; the next launch's Boot step (1) is what actually
+   mounts and runs it. There is no in-session hot-swap.
+
+## Known limitations
+
+- **`love.run` persists across handoff.** By the time `chainload` runs, the
+  bundled `love.run` has already returned its stepper to LOVE; redefining the
+  global `love.run` from the payload's `main.lua` does not affect the loop
+  already driving the frame. A payload that must change `love.run` itself
+  needs a `minShell` bump so an older shell refuses to chainload it rather
+  than running with half its intended behavior.
+- **Android has no in-app download transport yet.** `check_worker.lua`
+  shells out to curl for both the release check and the download; curl is
+  absent on Android, so `Check` degrades to `status = "error"` there (the
+  launcher UI hides on that status) and the player is directed to the
+  releases page via `Check.releaseUrl()` instead.
+- **Dev/source runs never self-update.** `Boot.run` returns immediately when
+  `love.filesystem.isFused()` is false, and a working tree's `engine` is the
+  `"0.0.0-dev"` placeholder that always reports up to date, so a source
+  checkout is always "the game" itself; updating it means pulling the repo.

main.lua

@@ -13,7 +13,37 @@ local driverCo  -- optional frame-driver (POKEPORT_DRIVER=file.lua): a
                 -- coroutine that receives `Game` and yields once per
                 -- frame; used headless (xvfb) for scripted screenshots
 
-local function bootGame()
+-- --speed N / POKEPORT_SPEED=N: run the logic clock N times faster without
+-- touching audio (src/core/GameSpeed.lua).  Overrides the saved option so a
+-- bot or screenshot run is not at the mercy of the player's last choice.
+local speedOverride = tonumber(os.getenv("POKEPORT_SPEED"))
+
+-- POKEPORT_TOUCH=1 forces the mobile on-screen controls on and lets the
+-- mouse stand in for a finger, so the overlay can be exercised on desktop
+-- (see src/core/TouchControls.lua).
+local mouseTouch = os.getenv("POKEPORT_TOUCH") == "1"
+
+-- How many times to run a scripted act+step loop per rendered frame.  Only
+-- scripted runs use this; interactive play fast-forwards through
+-- Game.speedOverride / the GAME SPEED option instead.
+local function scriptedIterations()
+  if not (autopilot or driverCo) then return 1 end
+  return math.max(1, math.floor(require("src.core.GameSpeed").clamp(speedOverride)))
+end
+
+local function bootGame(version)
+  -- The launcher hands us the chosen game (Red / Blue); scripted and headless
+  -- runs fall back to POKEPORT_VERSION, then Red.  Set the active version and
+  -- overlay its extracted cache BEFORE anything requires generated data, so
+  -- data/generated + assets/generated resolve to that version's files.
+  local GameVersion = require("src.core.GameVersion")
+  GameVersion.set(version or os.getenv("POKEPORT_VERSION") or "red")
+  require("src.import.CacheFs").mountVersion(GameVersion.get())
+  if love.window and love.window.setTitle then
+    local Version = require("src.core.Version")
+    love.window.setTitle(Version.title(
+      GameVersion.info().displayName .. " (Gen 1 Recompilation Project)"))
+  end
   Game = require("src.core.Game")
   Game:load()
   if os.getenv("POKEPORT_AUTOPILOT") then
@@ -24,15 +54,29 @@ local function bootGame()
     local fn = assert(loadfile(driverPath))()
     driverCo = coroutine.create(fn)
   end
+  -- After the two above are known: a scripted run drives the multiplier
+  -- from love.update's loop, so the in-engine one must stay at 1 or the
+  -- two would compound (10x10 = 100 steps per observation).
+  Game.speedOverride = (autopilot or driverCo) and 1 or speedOverride
 end
 
 function love.load(args)
+  -- Self-updater boot shell: a fused build may mount and chainload a newer
+  -- downloaded payload here.  True means it took over, so we must stop.  A
+  -- dev / source checkout no-ops (see src/update/Boot.lua).
+  local Boot = require("src.update.Boot")
+  if Boot.run(args) then return end
+
   local savePath
   for i, a in ipairs(args or {}) do
     if a == "--editor" then
       editorMode = true
+    elseif a == "--developer" then
+      _G.POKEPORT_DEV_MODE = true
     elseif a == "--save" and args[i + 1] and args[i + 1] ~= "" then
       savePath = args[i + 1]
+    elseif a == "--speed" and tonumber(args[i + 1]) then
+      speedOverride = tonumber(args[i + 1])
     end
   end
   love.graphics.setDefaultFilter("nearest", "nearest")
@@ -47,43 +91,82 @@ function love.load(args)
   end
 
   local RomImporter = require("src.import.RomImporter")
-  if os.getenv("POKEPORT_FORCE_IMPORT") == "1" or not RomImporter.isReady() then
-    Importer = RomImporter.new(function()
-      if os.getenv("POKEPORT_IMPORT_ONLY") == "1" then
-        love.event.quit()
-        return
-      end
-      Importer = nil
-      bootGame()
-    end)
-    local importPath = os.getenv("POKEPORT_IMPORT_ROM")
-    if importPath then Importer:startPath(importPath) end
+  local forceImport = os.getenv("POKEPORT_FORCE_IMPORT") == "1"
+  local importPath = os.getenv("POKEPORT_IMPORT_ROM")
+  -- Scripted / headless runs pick their game from POKEPORT_VERSION (default
+  -- Red); the launcher's per-column choice does not apply to them.
+  local scriptedVersion = os.getenv("POKEPORT_VERSION") or "red"
+  local ready = RomImporter.isReady(scriptedVersion)
+  -- Scripted / headless runs have to reach the game with no human pressing
+  -- Play: an autopilot, a frame driver, an import-only build step, or an
+  -- explicit ROM path all bypass the interactive launcher and keep today's
+  -- import-then-boot (or boot-straight-in) behavior.
+  local scripted = os.getenv("POKEPORT_AUTOPILOT") or os.getenv("POKEPORT_DRIVER")
+    or os.getenv("POKEPORT_IMPORT_ONLY") == "1" or importPath ~= nil
+
+  if scripted then
+    if forceImport or not ready then
+      -- The importer detects the dropped/loaded ROM's version by SHA-1 and
+      -- passes it to onComplete; boot that version.
+      Importer = RomImporter.new(function(version)
+        if os.getenv("POKEPORT_IMPORT_ONLY") == "1" then
+          love.event.quit()
+          return
+        end
+        Importer = nil
+        bootGame(version or scriptedVersion)
+      end)
+      if importPath then Importer:startPath(importPath) end
+      return
+    end
+    bootGame(scriptedVersion)
     return
   end
-  bootGame()
+
+  -- Interactive: the launcher always runs.  Red and Blue are each live: a
+  -- column shows Play when that game's ROM is already imported, or Choose ROM
+  -- / drag-drop when it is not (Yellow is still a placeholder).  Any dropped
+  -- .gb is routed to Red or Blue by its SHA-1; pressing Play boots that game.
+  Importer = RomImporter.new(function(version)
+    Importer = nil
+    bootGame(version)
+  end, { launcher = true, forceImport = forceImport })
 end
 
 function love.update(dt)
   if editorMode then return EditorApp.update(dt) end
   if Importer then return Importer:update(dt) end
 
+  -- Scripted runs (autopilot / POKEPORT_DRIVER) observe and act exactly
+  -- once per Game:update, so they must keep a 1:1 relationship with the
+  -- logic step.  Fast-forwarding them by scaling the step inside
+  -- Game:update would run N steps per observation: a held direction walks
+  -- through all N, the player slides past the waypoint, and the script
+  -- re-plans from an overshot cell.  So iterate the whole act+step loop
+  -- instead -- same script, just more of it per rendered frame.
+  local iterations = scriptedIterations()
+
   if autopilot then
-    autopilot.update()
-    Game:update(1 / 60) -- deterministic stepping for the autopilot
+    for _ = 1, iterations do
+      autopilot.update()
+      Game:update(1 / 60) -- deterministic stepping for the autopilot
+    end
     return
   end
   if driverCo then
-    local ok, err = coroutine.resume(driverCo, Game)
-    if not ok then
-      print("driver error: " .. tostring(err))
-      love.event.quit(1)
-      return
+    for _ = 1, iterations do
+      local ok, err = coroutine.resume(driverCo, Game)
+      if not ok then
+        print("driver error: " .. tostring(err))
+        love.event.quit(1)
+        return
+      end
+      if coroutine.status(driverCo) == "dead" then
+        love.event.quit()
+        return
+      end
+      Game:update(1 / 60)
     end
-    if coroutine.status(driverCo) == "dead" then
-      love.event.quit()
-      return
-    end
-    Game:update(1 / 60)
     return
   end
   Game:update(dt)
@@ -139,6 +222,31 @@ function love.gamepadaxis(joystick, axis, value)
   Game:gamepadaxis(joystick, axis, value)
 end
 
+function love.joystickremoved(joystick)
+  if editorMode then return end
+  if Importer then return end
+  Game:joystickremoved(joystick)
+end
+
+-- f is true on focus gained, false on focus lost (e.g. alt-tab). A held
+-- direction's key-up can be delivered to the OS instead of the game while
+-- unfocused, so reset input on either transition rather than trust it.
+function love.focus(f)
+  if editorMode then return end
+  if Importer then
+    if Importer.focus then Importer:focus(f) end
+    return
+  end
+  Game:focus(f)
+end
+
+-- v is true when the window becomes visible again, false on minimize.
+function love.visible(v)
+  if editorMode then return end
+  if Importer then return end
+  Game:visible(v)
+end
+
 function love.touchpressed(id, x, y, dx, dy, pressure)
   if editorMode then return end
   if Importer then return Importer:mousepressed(x, y, 1) end
@@ -171,6 +279,9 @@ function love.mousepressed(x, y, button)
   if editorMode and EditorApp.mousepressed then
     return EditorApp.mousepressed(x, y, button)
   end
+  if mouseTouch and Game and button == 1 then
+    Game:touchpressed("mouse", x, y)
+  end
 end
 
 function love.mousereleased(x, y, button)
@@ -178,6 +289,16 @@ function love.mousereleased(x, y, button)
   if editorMode and EditorApp.mousereleased then
     return EditorApp.mousereleased(x, y, button)
   end
+  if mouseTouch and Game and button == 1 then
+    Game:touchreleased("mouse", x, y)
+  end
+end
+
+function love.mousemoved(x, y)
+  if editorMode or Importer then return end
+  if mouseTouch and Game and love.mouse.isDown(1) then
+    Game:touchmoved("mouse", x, y)
+  end
 end
 
 function love.textinput(text)
@@ -191,6 +312,9 @@ function love.quit()
   if editorMode and EditorApp.quit then
     return EditorApp.quit() -- return true to abort quit
   end
+  pcall(function()
+    require("src.core.DiscordPresence").shutdown()
+  end)
 end
 
 function love.filedropped(file)
@@ -199,3 +323,78 @@ function love.filedropped(file)
   end
   if Importer then Importer:filedropped(file) end
 end
+
+local function pacingEnabled()
+  if os.getenv("POKEPORT_AUTOPILOT") then return false end
+  if os.getenv("POKEPORT_DRIVER") then return false end
+  if os.getenv("POKEPORT_IMPORT_ONLY") == "1" then return false end
+  return true
+end
+
+function love.run()
+  if love.load then love.load(love.arg.parseGameArguments(arg), arg) end
+
+  -- don't let love.load's cost land in the first frame's dt
+  if love.timer then love.timer.step() end
+
+  local FrameCap = require("src.core.FrameCap")
+  local paced = pacingEnabled()
+  -- The deadline the next present() should not beat.  Carried forward one
+  -- budget per frame so pacing stays even instead of drifting with the
+  -- per-frame sleep-granularity jitter.
+  local nextFrame = love.timer and love.timer.getTime() or 0
+  local dt = 0
+
+  return function()
+    -- process events
+    if love.event then
+      love.event.pump()
+      for name, a, b, c, d, e, f in love.event.poll() do
+        if name == "quit" then
+          if not love.quit or not love.quit() then
+            return a or 0
+          end
+        end
+        love.handlers[name](a, b, c, d, e, f)
+      end
+    end
+
+    -- update dt
+    if love.timer then dt = love.timer.step() end
+
+    -- call update and draw
+    if love.update then love.update(dt) end
+
+    if love.graphics and love.graphics.isActive() then
+      love.graphics.origin()
+      love.graphics.clear(love.graphics.getBackgroundColor())
+      if love.draw then love.draw() end
+      love.graphics.present()
+    end
+
+    if love.timer then
+      if paced then
+        -- Sleep out the remainder of the frame budget, measured from the
+        -- carried deadline, in small chunks so the OS timer stays
+        -- responsive.  vsync is untouched: when it already paces slower
+        -- than the cap the remainder is <= 0 and this rounds to a no-op.
+        local budget = 1 / FrameCap.current
+        nextFrame = nextFrame + budget
+        local now = love.timer.getTime()
+        -- A stall (alt-tab, a GC pause, a blocked import) can leave the
+        -- deadline more than a full budget in the past; re-anchor to now so
+        -- we pace the next frame rather than burst uncapped to catch up.
+        if now - nextFrame > budget then
+          nextFrame = now
+        end
+        while true do
+          local remaining = nextFrame - love.timer.getTime()
+          if remaining <= 0 then break end
+          love.timer.sleep(remaining < 0.001 and remaining or 0.001)
+        end
+      else
+        love.timer.sleep(0.001)
+      end
+    end
+  end
+end

mobile/ANDROID.md

@@ -27,25 +27,28 @@ refresh is safe,  just rebuild.
 ## Build
 
 ```bash
-# Debug APK (default Android debug keystore)
+# Build the APK
 scripts/build_android.sh
 
-# Release APK (signing is manual,  see below)
-scripts/build_android.sh --release
+# Build the APK, setting app.version_name/app.version_code to match a release
+scripts/build_android.sh --version 0.2.5
 
 # Zip game.love + branding only (no Android SDK required)
 scripts/build_android.sh --package-only
 ```
 
-Or via `scripts/build.sh android`.
+Or via `scripts/build.sh android [--version X.Y.Z]`.
 
 The embedded `game.love` deliberately excludes `data/generated/`,
 `assets/generated/`, and any ROM. It contains the first-boot Lua importer and
 `tools/rom_manifest.json`.
 
-The current importer has desktop file pickers only. A production Android
-release still needs a Storage Access Framework handoff that passes the chosen
-ROM to LÖVE; the APK packaging itself is data-free.
+ROM / mod / save import on Android uses `love.system.pickFile([kind])` →
+`GameActivity.showFilePicker` (Storage Access Framework), which copies the
+chosen file under the app save directory as `picked_rom.gb`,
+`picked_mod.zip`, or `picked_save.sav`. `RomImporter` imports pending files
+from that folder on Choose / refocus; see `docs/launcher.md`. The APK payload
+itself remains data-free (no embedded ROM or generated cache).
 
 ### SDK / NDK
 
@@ -59,12 +62,10 @@ Set `ANDROID_SDK_ROOT` (or `ANDROID_HOME`), or let the script write
 `local.properties` when it finds `~/Library/Android/sdk`.
 
 Gradle flavor used: **`embedNoRecord`** (game fused into the APK, no microphone).
+Build task: `assembleEmbedNoRecordDebug`.
 
-- Debug task: `assembleEmbedNoRecordDebug`
-- Release task: `assembleEmbedNoRecordRelease`
-
-APKs land under `app/build/outputs/apk/embedNoRecord/{debug,release}/`.
-`scripts/build_android.sh` also copies the built APK(s) to `dist/android/{debug,release}/`.
+The APK lands under `app/build/outputs/apk/embedNoRecord/debug/`.
+`scripts/build_android.sh` also copies it to `dist/android/debug/`.
 
 ### Payload path
 
@@ -79,17 +80,15 @@ scripts, tests, and mobile build sources are excluded.
 | `app.application_id` | `com.theboisclub.pokemonred` |
 | `app.name` | Pokemon Red |
 | `app.orientation` | `portrait` |
+| `app.version_name` / `app.version_code` | set from `--version X.Y.Z` (code = major*10000 + minor*100 + patch); left as-is if `--version` is omitted |
 | Permissions | INTERNET / RECORD_AUDIO / WRITE_EXTERNAL_STORAGE stripped; VIBRATE + BLUETOOTH kept |
 
+## Releases
+
+`.github/workflows/release.yml` builds the APK with `--version` set to the
+release version and publishes it alongside the macOS/Windows/Linux builds as
+`PokemonRed-<version>-android.apk`.
+
 ## Signing
 
-- **Debug**: default Android debug keystore (no setup).
-- **Release**: out-of-band. Create a keystore yourself and wire it into
-  `app/build.gradle`,  **do not commit keystores or passwords**.
-
-Example (placeholder only):
-
-```bash
-keytool -genkey -v -keystore /path/to/pokemonred-release.jks \
-  -alias pokemonred -keyalg RSA -keysize 2048 -validity 10000
-```
+Signed with the default Android keystore (no setup required).

mobile/android/gradle.properties

@@ -6,7 +6,9 @@
 #app.name=LÖVE for Android
 
 app.application_id=com.theboisclub.pokemonred
-app.orientation=portrait
+# fullUser: allow every orientation the player's device permits (portrait and
+# landscape), honouring their auto-rotate lock. Was "portrait" (locked).
+app.orientation=fullUser
 app.version_code=32
 app.version_name=11.5a
 
@@ -16,4 +18,4 @@ android.useAndroidX=true
 android.defaults.buildfeatures.buildconfig=true
 android.nonTransitiveRClass=true
 android.nonFinalResIds=true
-app.name=Pokemon Red
+app.name=gen1recomp

mobile/android/love/src/jni/LuaJIT-2.1/.gitignore

@@ -1,4 +1,8 @@
 *.[oa]
+# Prebuilt vendored static libs Android.mk links against directly (not
+# built by the Gradle/NDK build itself) -- must stay tracked or a fresh
+# checkout fails ndk-build with "LOCAL_SRC_FILES points to a missing file".
+!android/*/libluajit.a
 *.so
 *.obj
 *.lib

mobile/android/love/src/jni/love/.gitignore

@@ -36,6 +36,7 @@ demos
 *~
 Makefile*
 config*
+!src/common/config.h
 libtool
 /platform/unix/ar-lib
 /platform/unix/compile

mobile/android/love/src/jni/love/src/common/android.cpp

@@ -183,6 +183,42 @@ void vibrate(double seconds)
 	env->DeleteLocalRef(activity);
 }
 
+bool showFilePicker(const char *destFilename)
+{
+	if (destFilename == nullptr || destFilename[0] == '\0')
+		destFilename = "picked_rom.gb";
+
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+
+	jmethodID method = env->GetStaticMethodID(activity, "showFilePicker",
+		"(Ljava/lang/String;)Z");
+	jstring jname = env->NewStringUTF(destFilename);
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jname);
+	env->DeleteLocalRef(jname);
+
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
+bool showCreateDocument(const char *suggestedName)
+{
+	if (suggestedName == nullptr || suggestedName[0] == '\0')
+		suggestedName = "export.sav";
+
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+
+	jmethodID method = env->GetStaticMethodID(activity, "showCreateDocument",
+		"(Ljava/lang/String;)Z");
+	jstring jname = env->NewStringUTF(suggestedName);
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jname);
+	env->DeleteLocalRef(jname);
+
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
 /*
  * Helper functions for the filesystem module
  */

mobile/android/love/src/jni/love/src/common/android.h

@@ -59,6 +59,21 @@ bool openURL(const std::string &url);
 
 void vibrate(double seconds);
 
+/**
+ * Shows the system's "pick a document" UI (Storage Access Framework).
+ * Returns true if the picker was launched; the picked file (if any) is
+ * copied asynchronously by GameActivity.onActivityResult into the app's
+ * external save directory under destFilename (default picked_rom.gb), not
+ * returned here -- see src/import/RomImporter.lua.
+ **/
+bool showFilePicker(const char *destFilename = nullptr);
+
+/**
+ * Shows ACTION_CREATE_DOCUMENT so Lua can export a staged pending_export.sav
+ * to a user-chosen location. suggestedName is the dialog default filename.
+ **/
+bool showCreateDocument(const char *suggestedName = nullptr);
+
 /*
  * Helper functions for the filesystem module
  */

mobile/android/love/src/jni/love/src/common/config.h

@@ -0,0 +1,178 @@
+/**
+ * Copyright (c) 2006-2023 LOVE Development Team
+ *
+ * This software is provided 'as-is', without any express or implied
+ * warranty.  In no event will the authors be held liable for any damages
+ * arising from the use of this software.
+ *
+ * Permission is granted to anyone to use this software for any purpose,
+ * including commercial applications, and to alter it and redistribute it
+ * freely, subject to the following restrictions:
+ *
+ * 1. The origin of this software must not be misrepresented; you must not
+ *    claim that you wrote the original software. If you use this software
+ *    in a product, an acknowledgment in the product documentation would be
+ *    appreciated but is not required.
+ * 2. Altered source versions must be plainly marked as such, and must not be
+ *    misrepresented as being the original software.
+ * 3. This notice may not be removed or altered from any source distribution.
+ **/
+
+#ifndef LOVE_CONFIG_H
+#define LOVE_CONFIG_H
+
+// Platform stuff.
+#if defined(WIN32) || defined(_WIN32)
+#	define LOVE_WINDOWS 1
+	// If _USING_V110_SDK71_ is defined it means we are using the xp toolset.
+#	if defined(_MSC_VER) && (_MSC_VER >= 1700) && !_USING_V110_SDK71_
+#		include <winapifamily.h>
+#		if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP) && !WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP)
+#			define LOVE_WINDOWS_UWP 1
+#			define LOVE_NO_MODPLUG 1
+#			define LOVE_NOMPG123 1
+#		endif
+#	endif
+#endif
+#if defined(linux) || defined(__linux) || defined(__linux__)
+#	define LOVE_LINUX 1
+#endif
+#if defined(__ANDROID__)
+#	define LOVE_ANDROID 1
+#endif
+#if defined(__APPLE__)
+#	include <TargetConditionals.h>
+#	if TARGET_OS_IPHONE
+#		define LOVE_IOS 1
+#	elif TARGET_OS_MAC
+#		define LOVE_MACOSX 1
+#	endif
+#endif
+#if defined(__FreeBSD__) || defined(__NetBSD__) || defined(__OpenBSD__)
+// I know it's not linux, but it seems most "linux-only" code is bsd-compatible
+#	define LOVE_LINUX 1
+#endif
+
+// Endianness.
+#if defined(__ppc__) || defined(__ppc) || defined(__powerpc__) || defined(__powerpc)
+#	define LOVE_BIG_ENDIAN 1
+#else
+#	define LOVE_LITTLE_ENDIAN 1
+#endif
+
+// SSE instructions.
+#if defined(__SSE__)
+#	define LOVE_SIMD_SSE
+#elif defined(_MSC_VER)
+#	if defined(_M_AMD64) || defined(_M_X64)
+#		define LOVE_SIMD_SSE
+#	elif _M_IX86_FP
+#		define LOVE_SIMD_SSE
+#	endif
+#endif
+
+// NEON instructions.
+#if defined(__ARM_NEON)
+#	define LOVE_SIMD_NEON
+#endif
+
+// Warnings.
+#ifndef _CRT_SECURE_NO_WARNINGS
+#	define _CRT_SECURE_NO_WARNINGS
+#endif
+
+// Preferably, and ironically, this macro should go unused.
+#ifndef LOVE_UNUSED
+#	define LOVE_UNUSED(x) (void)sizeof(x)
+#endif
+
+
+// Warn on unused return values
+#ifdef __GNUC__
+#	define LOVE_WARN_UNUSED __attribute__((warn_unused_result))
+#elif _MSC_VER
+#	define LOVE_WARN_UNUSED _Check_return_
+#else
+#	define LOVE_WARN_UNUSED
+#endif
+
+#ifndef LOVE_BUILD
+#	define LOVE_BUILD
+#	define LOVE_BUILD_STANDALONE
+#	define LOVE_BUILD_EXE
+//#	define LOVE_BUILD_DLL
+#endif
+
+// DLL-stuff.
+#if defined(_MSC_VER) || defined(__MINGW32__)
+#	define LOVE_EXPORT __declspec(dllexport)
+#elif defined(__GNUC__) || defined(__clang__)
+#	define LOVE_EXPORT __attribute__((visibility("default")))
+#else
+#	define LOVE_EXPORT
+#endif
+
+#if defined(LOVE_WINDOWS)
+#ifndef LOVE_WINDOWS_UWP
+#	define LOVE_LEGENDARY_CONSOLE_IO_HACK
+#endif // LOVE_WINDOWS_UWP
+#ifndef __MINGW32__
+#	define NOMINMAX
+#endif
+#endif
+
+#if defined(LOVE_MACOSX) || defined(LOVE_IOS)
+#	define LOVE_LEGENDARY_APP_ARGV_HACK
+#endif
+
+#if defined(LOVE_ANDROID) || defined(LOVE_IOS)
+#	define LOVE_LEGENDARY_ACCELEROMETER_AS_JOYSTICK_HACK
+#endif
+
+// Autotools config.h
+#ifdef HAVE_CONFIG_H
+#	include <../config.h>
+#	undef VERSION
+#	ifdef WORDS_BIGENDIAN
+#		undef LOVE_LITTLE_ENDIAN
+#		define LOVE_BIG_ENDIAN 1
+#	else
+#		undef LOVE_BIG_ENDIAN
+#		define LOVE_LITTLE_ENDIAN 1
+#	endif
+#else
+#	define LOVE_ENABLE_LOVE
+#	define LOVE_ENABLE_AUDIO
+#	define LOVE_ENABLE_DATA
+#	define LOVE_ENABLE_EVENT
+#	define LOVE_ENABLE_FILESYSTEM
+#	define LOVE_ENABLE_FONT
+#	define LOVE_ENABLE_GRAPHICS
+#	define LOVE_ENABLE_IMAGE
+#	define LOVE_ENABLE_JOYSTICK
+#	define LOVE_ENABLE_KEYBOARD
+#	define LOVE_ENABLE_MATH
+#	define LOVE_ENABLE_MOUSE
+#	define LOVE_ENABLE_PHYSICS
+#	define LOVE_ENABLE_SOUND
+#	define LOVE_ENABLE_SYSTEM
+#	define LOVE_ENABLE_THREAD
+#	define LOVE_ENABLE_TIMER
+#	define LOVE_ENABLE_TOUCH
+#	define LOVE_ENABLE_VIDEO
+#	define LOVE_ENABLE_WINDOW
+
+#	define LOVE_ENABLE_ENET
+#	define LOVE_ENABLE_LUASOCKET
+#	define LOVE_ENABLE_LUA53
+#endif
+
+// Check we have a sane configuration
+#if !defined(LOVE_WINDOWS) && !defined(LOVE_LINUX) && !defined(LOVE_IOS) && !defined(LOVE_MACOSX) && !defined(LOVE_ANDROID)
+#	error Could not detect target platform
+#endif
+#if !defined(LOVE_LITTLE_ENDIAN) && !defined(LOVE_BIG_ENDIAN)
+#	error Could not detect endianness
+#endif
+
+#endif // LOVE_CONFIG_H

mobile/android/love/src/jni/love/src/modules/filesystem/physfs/Filesystem.cpp

@@ -186,6 +186,18 @@ bool Filesystem::setIdentity(const char *ident, bool appendToPath)
 
 	save_path_full = storage_path + std::string("/save/") + save_identity;
 
+	// love::android::mkdir is a single mkdir(), not mkdir -p: on a genuinely
+	// first-ever launch (nothing has touched this app's external-files dir
+	// before) save_directory doesn't exist yet either, so creating
+	// save_path_full in one step fails with ENOENT and PHYSFS_mount below
+	// silently never mounts anything for the rest of this process -- not
+	// just the save dir, but everything routed through it (save.lua/
+	// options.lua, the ROM-derived asset cache, RomImporter's Android
+	// folder scan). Ensure each level exists in order instead.
+	if (!love::android::directoryExists(save_directory.c_str()) &&
+			!love::android::mkdir(save_directory.c_str()))
+		SDL_Log("Error: Could not create save directory %s!", save_directory.c_str());
+
 	if (!love::android::directoryExists(save_path_full.c_str()) &&
 			!love::android::mkdir(save_path_full.c_str()))
 		SDL_Log("Error: Could not create save directory %s!", save_path_full.c_str());
@@ -338,6 +350,26 @@ bool Filesystem::setupWriteDirectory()
 	std::string temp_writedir = getDriveRoot(save_path_full);
 	std::string temp_createdir = skipDriveRoot(save_path_full);
 
+#ifdef LOVE_ANDROID
+	// getUserDirectory() falls back to $HOME/getpwuid() (physfs_platform_posix.c),
+	// which is meaningless on Android and unrelated to save_path_full (an
+	// SDL_AndroidGet*StoragePath() subdirectory -- see setIdentity above), so
+	// the generic check below never matches and falls through to setting the
+	// write dir to the drive root ("/"), which no Android app can write to.
+	// Anchor to the real Android storage root instead.
+	std::string androidStorageRoot = isAndroidSaveExternal()
+		? SDL_AndroidGetExternalStoragePath() : SDL_AndroidGetInternalStoragePath();
+	if (save_path_full.find(androidStorageRoot) == 0)
+	{
+		temp_writedir = androidStorageRoot;
+		temp_createdir = save_path_full.substr(androidStorageRoot.length());
+
+		size_t startpos = temp_createdir.find_first_not_of('/');
+		if (startpos != std::string::npos)
+			temp_createdir = temp_createdir.substr(startpos);
+	}
+	else
+#endif
 	// On some sandboxed platforms, physfs will break when its write directory
 	// is the root of the drive and it tries to create a folder (even if the
 	// folder's path is in a writable location.) If the user's home folder is

mobile/android/love/src/jni/love/src/modules/system/System.cpp

@@ -22,6 +22,8 @@
 #include "common/config.h"
 #include "System.h"
 
+#include <cstring>
+
 #if defined(LOVE_MACOSX)
 #include <CoreServices/CoreServices.h>
 #elif defined(LOVE_IOS)
@@ -180,6 +182,36 @@ void System::vibrate(double seconds) const
 #endif
 }
 
+bool System::pickFile(const char *kind) const
+{
+#ifdef LOVE_ANDROID
+	const char *dest = "picked_rom.gb";
+	if (kind != nullptr)
+	{
+		if (strcmp(kind, "mod") == 0)
+			dest = "picked_mod.zip";
+		else if (strcmp(kind, "sav") == 0 || strcmp(kind, "save") == 0)
+			dest = "picked_save.sav";
+		else if (strcmp(kind, "rom") == 0)
+			dest = "picked_rom.gb";
+	}
+	return love::android::showFilePicker(dest);
+#else
+	LOVE_UNUSED(kind);
+	return false;
+#endif
+}
+
+bool System::createFile(const char *suggestedName) const
+{
+#ifdef LOVE_ANDROID
+	return love::android::showCreateDocument(suggestedName);
+#else
+	LOVE_UNUSED(suggestedName);
+	return false;
+#endif
+}
+
 bool System::hasBackgroundMusic() const
 {
 #if defined(LOVE_ANDROID)

mobile/android/love/src/jni/love/src/modules/system/System.h

@@ -106,6 +106,27 @@ public:
 	 */
 	virtual void vibrate(double seconds) const;
 
+	/**
+	 * Shows the platform's native "pick a file" UI, if one is available.
+	 * Android only for now; the result (if any) is not returned here -- see
+	 * love::android::showFilePicker and src/import/RomImporter.lua.
+	 *
+	 * @param kind Optional pick kind: nullptr/"rom" -> picked_rom.gb,
+	 *             "mod" -> picked_mod.zip, "sav"/"save" -> picked_save.sav.
+	 * @return Whether the picker was shown.
+	 **/
+	virtual bool pickFile(const char *kind = nullptr) const;
+
+	/**
+	 * Shows the platform's native "create / save a file" UI (Android SAF
+	 * ACTION_CREATE_DOCUMENT). Copies staged pending_export.sav from the app
+	 * save directory to the user-chosen URI. See GameActivity.showCreateDocument.
+	 *
+	 * @param suggestedName Default filename shown in the dialog.
+	 * @return Whether the create dialog was shown.
+	 **/
+	virtual bool createFile(const char *suggestedName = nullptr) const;
+
 	/**
 	 * Gets if the user is playing music on background.
 	 * Throws an exception on unsupported platforms.

mobile/android/love/src/jni/love/src/modules/system/wrap_System.cpp

@@ -95,6 +95,20 @@ int w_vibrate(lua_State *L)
 	return 0;
 }
 
+int w_pickFile(lua_State *L)
+{
+	const char *kind = luaL_optstring(L, 1, nullptr);
+	luax_pushboolean(L, instance()->pickFile(kind));
+	return 1;
+}
+
+int w_createFile(lua_State *L)
+{
+	const char *suggested = luaL_optstring(L, 1, nullptr);
+	luax_pushboolean(L, instance()->createFile(suggested));
+	return 1;
+}
+
 int w_hasBackgroundMusic(lua_State *L)
 {
 	lua_pushboolean(L, instance()->hasBackgroundMusic());
@@ -110,6 +124,8 @@ static const luaL_Reg functions[] =
 	{ "getPowerInfo", w_getPowerInfo },
 	{ "openURL", w_openURL },
 	{ "vibrate", w_vibrate },
+	{ "pickFile", w_pickFile },
+	{ "createFile", w_createFile },
 	{ "hasBackgroundMusic", w_hasBackgroundMusic },
 	{ 0, 0 }
 };

mobile/android/love/src/main/java/org/love2d/android/GameActivity.java

@@ -22,12 +22,15 @@ package org.love2d.android;
 
 import org.libsdl.app.SDLActivity;
 
+import java.io.BufferedInputStream;
 import java.io.BufferedOutputStream;
 import java.io.File;
+import java.io.FileInputStream;
 import java.io.FileNotFoundException;
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.OutputStream;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
@@ -61,6 +64,24 @@ public class GameActivity extends SDLActivity {
     protected final int[] recordAudioRequestDummy = new int[1];
     public static final int EXTERNAL_STORAGE_REQUEST_CODE = 2;
     public static final int RECORD_AUDIO_REQUEST_CODE = 3;
+    public static final int FILE_PICKER_REQUEST_CODE = 4;
+    public static final int FILE_CREATE_REQUEST_CODE = 5;
+    /** @deprecated Prefer FILE_PICKER_REQUEST_CODE; kept for older call sites. */
+    public static final int ROM_PICKER_REQUEST_CODE = FILE_PICKER_REQUEST_CODE;
+    // Mirrors conf.lua's t.identity ("pokemon-love2d"): where the picked file
+    // is dropped so RomImporter's existing folder scan finds it -- see
+    // src/import/RomImporter.lua and Filesystem::setIdentity (sets Android's
+    // save directory to getExternalFilesDir()/save/<identity>).
+    private static final String ROM_SAVE_IDENTITY = "pokemon-love2d";
+    private static final String PICKED_ROM_FILENAME = "picked_rom.gb";
+    private static final String PICKED_MOD_FILENAME = "picked_mod.zip";
+    private static final String PICKED_SAVE_FILENAME = "picked_save.sav";
+    private static final String PENDING_EXPORT_FILENAME = "pending_export.sav";
+    private static final String EXPORT_DONE_FILENAME = "export_done.flag";
+    // Destination basename for the in-flight SAF pick (set by showFilePicker).
+    private String pendingPickFilename = PICKED_ROM_FILENAME;
+    // Suggested download name for the in-flight SAF create (set by showCreateDocument).
+    private String pendingCreateSuggestedName = "export.sav";
     private static boolean immersiveActive = false;
     private static boolean needToCopyGameInArchive = false;
     private boolean storagePermissionUnnecessary = false;
@@ -332,6 +353,190 @@ public class GameActivity extends SDLActivity {
         return openURL(url) == 0;
     }
 
+    /**
+     * Shows the system document picker (Storage Access Framework) so the
+     * player can pick a ROM / mod / save from anywhere (Downloads, Drive,
+     * etc.) without needing to know where the app's external files folder
+     * is. Requires API 19+ (ACTION_OPEN_DOCUMENT); the picked file (if any)
+     * arrives later in onActivityResult, not synchronously here.
+     *
+     * @param destFilename basename under the app save identity (e.g.
+     *                     picked_rom.gb, picked_mod.zip, picked_save.sav)
+     */
+    @Keep
+    public static boolean showFilePicker(String destFilename) {
+        if (android.os.Build.VERSION.SDK_INT < 19) return false;
+        GameActivity self = (GameActivity) mSingleton;
+        if (self == null) return false;
+        if (destFilename == null || destFilename.length() == 0) {
+            destFilename = PICKED_ROM_FILENAME;
+        }
+        // Reject path separators so a hostile JNI caller cannot escape the
+        // save identity directory.
+        if (destFilename.indexOf('/') >= 0 || destFilename.indexOf('\\') >= 0) {
+            Log.d("GameActivity", "refusing unsafe picker dest: " + destFilename);
+            return false;
+        }
+
+        self.pendingPickFilename = destFilename;
+        Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
+        intent.addCategory(Intent.CATEGORY_OPENABLE);
+        intent.setType("*/*");
+        try {
+            self.startActivityForResult(intent, FILE_PICKER_REQUEST_CODE);
+            return true;
+        } catch (Exception e) {
+            Log.d("GameActivity", "could not open file picker: " + e.getMessage());
+            return false;
+        }
+    }
+
+    /** ROM convenience wrapper; prefer showFilePicker with an explicit name. */
+    @Keep
+    public static boolean showRomFilePicker() {
+        return showFilePicker(PICKED_ROM_FILENAME);
+    }
+
+    /** Mod .zip convenience wrapper used by love.system.pickFile("mod"). */
+    @Keep
+    public static boolean showModFilePicker() {
+        return showFilePicker(PICKED_MOD_FILENAME);
+    }
+
+    /** Battery .sav convenience wrapper used by love.system.pickFile("sav"). */
+    @Keep
+    public static boolean showSaveFilePicker() {
+        return showFilePicker(PICKED_SAVE_FILENAME);
+    }
+
+    /**
+     * Shows ACTION_CREATE_DOCUMENT so the player can save a staged export
+     * (pending_export.sav in the app save identity) to Downloads / Drive /
+     * etc. Suggested name is the dialog's default filename.
+     */
+    @Keep
+    public static boolean showCreateDocument(String suggestedName) {
+        if (android.os.Build.VERSION.SDK_INT < 19) return false;
+        GameActivity self = (GameActivity) mSingleton;
+        if (self == null) return false;
+        if (suggestedName == null || suggestedName.length() == 0) {
+            suggestedName = "export.sav";
+        }
+        if (suggestedName.indexOf('/') >= 0 || suggestedName.indexOf('\\') >= 0) {
+            Log.d("GameActivity", "refusing unsafe create name: " + suggestedName);
+            return false;
+        }
+        File source = new File(
+            new File(self.getExternalFilesDir(null), "save"),
+            ROM_SAVE_IDENTITY + "/" + PENDING_EXPORT_FILENAME);
+        if (!source.isFile()) {
+            Log.d("GameActivity", "no pending export at " + source);
+            return false;
+        }
+
+        self.pendingCreateSuggestedName = suggestedName;
+        Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);
+        intent.addCategory(Intent.CATEGORY_OPENABLE);
+        intent.setType("application/octet-stream");
+        intent.putExtra(Intent.EXTRA_TITLE, suggestedName);
+        try {
+            self.startActivityForResult(intent, FILE_CREATE_REQUEST_CODE);
+            return true;
+        } catch (Exception e) {
+            Log.d("GameActivity", "could not open create-document picker: " + e.getMessage());
+            return false;
+        }
+    }
+
+    private File saveIdentityDir() {
+        return new File(new File(getExternalFilesDir(null), "save"), ROM_SAVE_IDENTITY);
+    }
+
+    private boolean copyFileToUri(File source, Uri destUri) {
+        InputStream in = null;
+        OutputStream out = null;
+        try {
+            in = new BufferedInputStream(new FileInputStream(source));
+            out = getContentResolver().openOutputStream(destUri);
+            if (out == null) return false;
+            byte[] buf = new byte[8192];
+            int n;
+            while ((n = in.read(buf)) != -1) {
+                out.write(buf, 0, n);
+            }
+            out.flush();
+            return true;
+        } catch (IOException e) {
+            Log.d("GameActivity", "copy to URI failed: " + e.getMessage());
+            return false;
+        } finally {
+            try { if (in != null) in.close(); } catch (IOException ignored) {}
+            try { if (out != null) out.close(); } catch (IOException ignored) {}
+        }
+    }
+
+    @Override
+    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+        super.onActivityResult(requestCode, resultCode, data);
+        if (requestCode == FILE_CREATE_REQUEST_CODE) {
+            if (resultCode != RESULT_OK || data == null || data.getData() == null) {
+                Log.d("GameActivity", "create-document cancelled");
+                return;
+            }
+            File source = new File(saveIdentityDir(), PENDING_EXPORT_FILENAME);
+            if (!source.isFile()) {
+                Log.d("GameActivity", "pending export missing at result time");
+                return;
+            }
+            Uri uri = data.getData();
+            if (copyFileToUri(source, uri)) {
+                // Signal Lua on next focus that the SAF export finished.
+                File flag = new File(saveIdentityDir(), EXPORT_DONE_FILENAME);
+                try {
+                    FileOutputStream fos = new FileOutputStream(flag, false);
+                    fos.write("ok".getBytes());
+                    fos.close();
+                } catch (IOException e) {
+                    Log.d("GameActivity", "could not write export_done flag: " + e.getMessage());
+                }
+                // Keep pending_export.sav so a retry still works; Lua may remove it.
+            } else {
+                Log.d("GameActivity", "could not write export to " + uri);
+            }
+            return;
+        }
+        if (requestCode != FILE_PICKER_REQUEST_CODE) return;
+        if (resultCode != RESULT_OK || data == null || data.getData() == null) {
+            Log.d("GameActivity", "file picker returned no file (cancelled?)");
+            return;
+        }
+
+        Uri uri = data.getData();
+        File destDir = saveIdentityDir();
+        if (!destDir.exists() && !destDir.mkdirs()) {
+            Log.d("GameActivity", "could not create " + destDir);
+            return;
+        }
+        String destName = pendingPickFilename != null
+            ? pendingPickFilename : PICKED_ROM_FILENAME;
+        File destFile = new File(destDir, destName);
+
+        InputStream source;
+        try {
+            source = getContentResolver().openInputStream(uri);
+        } catch (FileNotFoundException e) {
+            Log.d("GameActivity", "could not open picked file: " + e.getMessage());
+            return;
+        }
+        if (source == null) {
+            Log.d("GameActivity", "ContentResolver returned no stream for picked file");
+            return;
+        }
+        if (!copyAssetFile(source, destFile.getPath())) {
+            Log.d("GameActivity", "could not copy picked file to " + destFile);
+        }
+    }
+
     /**
      * Copies a given file from the assets folder to the destination.
      *

mobile/ios/overlays/love-ios.plist

@@ -62,10 +62,15 @@
 	<key>UISupportedInterfaceOrientations</key>
 	<array>
 		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
 	</array>
 	<key>UISupportedInterfaceOrientations~ipad</key>
 	<array>
 		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationPortraitUpsideDown</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
 	</array>
 	<key>UTExportedTypeDeclarations</key>
 	<array>

mods/examples/README.md

@@ -1,6 +1,6 @@
 # Example mod gallery
 
-Seven reference mods, one per modder persona. Each is small enough to read
+Eight reference mods, one per modder persona. Each is small enough to read
 in one sitting, exercises a different slice of the mod API, and is a real,
 runnable, tested mod — not a snippet.
 
@@ -16,6 +16,7 @@ Copy the one closest to what you want to build.
 | 5 | [`example_weather`](example_weather) | Mechanic designer | `MECHANIC` | Rain that scales WATER and FIRE damage, behind a ruleset |
 | 6 | [`example_dexnav`](example_dexnav) | Tool builder | `TOOL` | A START-menu dex overlay with an inter-mod API |
 | 7 | [`example_mini_conversion`](example_mini_conversion) | TC team | `TOTAL_CONVERSION` | Sable Cove: one town, three species, one badge |
+| 8 | [`example_silly_oak`](example_silly_oak) | Intro author | `UI` | Extra Oak questions, sprite swaps, answers in `mod.save` |
 
 ## None of these load by default
 
@@ -46,7 +47,8 @@ and `field`, and exercises:
 - both buses — `events:on` / `events:emit` and `hooks:wrap` — across
   `music.select`, `battle.damage`, `ui.start_menu.items`, `ui.options.rows`,
   `battle.started`, `battle.turn_started`, `battle.ended`, `flag.changed`,
-  `game.ready` and `assets.transformed`
+  `game.ready`, `assets.transformed`, `intro.oak_speech.build`,
+  `intro.oak_speech.answered` and `intro.oak_speech.finished`
 - `mod.save`, `mod.options`, `mod.exports`, `mod.commands`, `mod.ui`,
   `mod:read`, `mod.log` and `mod.path`
 - asset transforms, the `trueColor` opt-out, script labels and `choice`,
@@ -66,7 +68,7 @@ mods/examples/<id>/
   .modkitignore     keeps the suite out of the distributed package
 ```
 
-`tests/mod_examples_tests.lua` in the engine's own suite loads all seven
+`tests/mod_examples_tests.lua` in the engine's own suite loads all eight
 together and asserts the above, so the gallery cannot rot.
 
 These example mods arent perfect and are just examples to show you basics of wahts possible, but way more than just this is possible.

mods/examples/example_balance_tweaks/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "BALANCE",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "dependencies": [],
   "optional_dependencies": [],

mods/examples/example_dexnav/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "TOOL",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "dependencies": [],
   "optional_dependencies": [],

mods/examples/example_jukebox/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "AUDIO",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "permissions": ["engine_internals"],
   "dependencies": [],

mods/examples/example_lost_parcel/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "QUEST",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "permissions": ["engine_internals"],
   "dependencies": [],

mods/examples/example_mini_conversion/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "total_conversion",
   "category": "TOTAL_CONVERSION",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 900,
   "dependencies": [],
   "optional_dependencies": [],

mods/examples/example_shiny_palette/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "GRAPHICS",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "assets_transforms": "transforms.lua",
   "dependencies": [],

mods/examples/example_silly_oak/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+Format: [keep a changelog](https://keepachangelog.com/en/1.1.0/).
+Version headings match `manifest.json`'s `version`.
+
+## 1.0.0
+
+### Added
+
+- `intro.oak_speech.build` wrap that injects toast / MEW / snack / rival-trust / pineapple beats.
+- Answers written to `mod.save` via `intro.oak_speech.answered`.
+- Custom `toast_kid.png` sprite shown mid-speech.

mods/examples/example_silly_oak/README.md

@@ -0,0 +1,43 @@
+# Silly Oak Intro Example
+
+Hooks Oak's NEW GAME speech: extra questions, sprite swaps (Oak, rival,
+player, MEW, and a custom Toast Kid pic), and answers stored in `mod.save`.
+
+## Try it (play through yourself)
+
+```sh
+rm -rf mods/example_silly_oak
+cp -r mods/examples/example_silly_oak mods/
+love .
+```
+
+Then **NEW GAME** and mash A / pick the menus. Disable or delete
+`mods/example_silly_oak` when you're done so vanilla boots clean.
+
+## Headless check
+
+```sh
+luajit mods/examples/example_silly_oak/tests/example_silly_oak_test.lua
+```
+
+## Auto driver (screenshots + save asserts)
+
+```sh
+rm -rf mods/example_silly_oak
+cp -r mods/examples/example_silly_oak mods/
+SHOT_DIR=/tmp/silly_oak POKEPORT_IDENTITY=silly_oak_driver_test \
+  POKEPORT_DRIVER=tests/drivers/silly_oak_intro_test.lua POKEPORT_SPEED=8 love .
+```
+
+`POKEPORT_IDENTITY` keeps this run's save out of your normal slot.
+
+## What it demonstrates
+
+| Seam | Where |
+|---|---|
+| `hooks:wrap("intro.oak_speech.build")` | `main.lua` — reshape the step list |
+| `mod.ui.insertStepAfter` / `insertStepBefore` | `main.lua` — anchored on vanilla step ids |
+| step kinds `say` / `yesno` / `choice` | `main.lua` |
+| pics: `"oak"`, `"rival"`, `"player"`, pokemon, custom image | `main.lua` |
+| `events:on("intro.oak_speech.answered")` | `main.lua` → `mod.save` |
+| `events:on("intro.oak_speech.finished")` | `main.lua` |

mods/examples/example_silly_oak/main.lua

@@ -0,0 +1,107 @@
+-- Gallery entry: reshape Oak's intro speech with extra questions, sprite
+-- swaps (oak / rival / player / pokemon / a custom image), and answers
+-- that land in mod.save.
+--
+-- Uses hooks:wrap("intro.oak_speech.build") plus intro.oak_speech.answered.
+
+return function(mod)
+  local toastPic = mod.path .. "/assets/toast_kid.png"
+
+  mod.hooks:wrap("intro.oak_speech.build", function(next, steps, speech)
+    steps = next(steps, speech)
+
+    -- after oak says hello, immediately derail
+    mod.ui.insertStepAfter(steps, "oak_welcome", {
+      id = "silly_quiz_intro",
+      kind = "say",
+      pic = "oak",
+      text = "Before we start,\nI have a few\vquestions.\fImportant ones.\nScientific ones.",
+    })
+
+    mod.ui.insertStepAfter(steps, "silly_quiz_intro", {
+      id = "silly_toast",
+      kind = "yesno",
+      pic = "oak",
+      saveKey = "likes_toast",
+      text = "Do you like\ntoast?",
+    })
+
+    -- brand new sprite mid-speech
+    mod.ui.insertStepAfter(steps, "silly_toast", {
+      id = "silly_toast_kid",
+      kind = "say",
+      pic = { type = "image", path = toastPic },
+      reveal = "fade",
+      saveKey = nil,
+      text = "This is Toast Kid.\nHe is not a\vPOKéMON.\fHe just showed up\none day.\fAnyway.",
+    })
+
+    -- existing mon with a wipe + cry, parked after the real demo mon
+    mod.ui.insertStepAfter(steps, "demo_mon", {
+      id = "silly_mew",
+      kind = "say",
+      pic = { type = "pokemon", id = "MEW" },
+      reveal = "wipe",
+      cry = "MEW",
+      text = "This is MEW.\nPlease do not\vtell anyone\vI showed you.",
+    })
+
+    mod.ui.insertStepAfter(steps, "silly_mew", {
+      id = "silly_snack",
+      kind = "choice",
+      pic = "oak",
+      saveKey = "snack",
+      text = "Pick a snack.\nThis goes on\vyour permanent\vrecord.",
+      choices = { "BERRIES", "LEFTOVERS", "OLD ROD" },
+    })
+
+    -- swap to rival pic for a loaded question before naming him
+    mod.ui.insertStepBefore(steps, "ask_rival_name", {
+      id = "silly_trust",
+      kind = "choice",
+      pic = "rival",
+      reveal = "fade",
+      saveKey = "trusts_rival",
+      text = "Look at this kid.\nTrustworthy?",
+      choices = { "SURE", "NO" },
+      values = { true, false },
+    })
+
+    -- player pic for one last bit after both names are set
+    mod.ui.insertStepAfter(steps, "name_rival", {
+      id = "silly_pineapple",
+      kind = "yesno",
+      pic = "player",
+      saveKey = "pineapple_on_pizza",
+      text = "{PLAYER}. Be honest.\nPineapple on\vpizza?",
+    })
+
+    mod.ui.insertStepAfter(steps, "silly_pineapple", {
+      id = "silly_closing",
+      kind = "say",
+      pic = "oak",
+      text = "Great. Terrible.\nI have notes.\fLet's pretend this\nwas normal.",
+    })
+
+    return steps
+  end)
+
+  -- every answered step with a saveKey lands in mod.save (and therefore
+  -- save.modData[mod.id] once the slot is written)
+  mod.events:on("intro.oak_speech.answered", function(ev)
+    if not ev.saveKey then return end
+    mod.save:set(ev.saveKey, ev.value)
+    mod.log:info("intro answer %s = %s", tostring(ev.saveKey), tostring(ev.value))
+  end)
+
+  mod.events:on("intro.oak_speech.finished", function(ev)
+    local answers = ev.answers or {}
+    for key, value in pairs(answers) do
+      if mod.save:get(key) == nil then
+        mod.save:set(key, value)
+      end
+    end
+    mod.save:set("quiz_done", true)
+    mod.log:info("silly oak quiz done")
+  end)
+end

mods/examples/example_silly_oak/manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "example_silly_oak",
+  "name": "Silly Oak Intro Example",
+  "version": "1.0.0",
+  "api": 2,
+  "entry": "main.lua",
+  "profile": "content",
+  "category": "UI",
+  "game_version": ">=0.0.0-0 <2.0.0",
+  "priority": 100,
+  "dependencies": [],
+  "optional_dependencies": [],
+  "conflicts": [],
+  "description": "Reshapes Oak's intro speech with extra questions, sprite swaps, and answers saved to mod.save."
+}

mods/examples/example_silly_oak/mod.card

@@ -0,0 +1,21 @@
+-- Sharing metadata for the manager detail pane.
+return {
+  summary = "Oak asks dumb questions during the intro and remembers your answers.",
+  author = "Pokemon Gen 1 Recompilation Project",
+  contact = "https://github.com/bryanthaboi/pokemon-gen1-recomp-project",
+  tags = { "intro", "ui", "oak", "hooks" },
+  differences = {
+    changed = {
+      "Oak's NEW GAME speech gains extra questions and sprite beats",
+    },
+    added = {
+      "mod.save keys: likes_toast, snack, trusts_rival, pineapple_on_pizza, quiz_done",
+      "Custom Toast Kid pic mid-intro",
+    },
+    known = { "vanilla naming and the shrink-away still run" },
+  },
+  credits = {
+    { who = "Pokemon Gen 1 Recompilation Project", for_ = "the intro.oak_speech hooks" },
+  },
+  compat = { engine = ">=0.0.0 <2.0.0", modApi = 2 },
+}

mods/examples/example_silly_oak/tests/example_silly_oak_test.lua

@@ -0,0 +1,159 @@
+-- Standalone: luajit mods/examples/example_silly_oak/tests/example_silly_oak_test.lua
+-- Covers the intro.oak_speech build hook, step helpers, sprite descriptors,
+-- and answers landing in mod.save.
+--
+-- Needs an imported ROM dataset (data/generated/).  Headless CI and a
+-- fresh checkout without a ROM skip cleanly -- the gallery is also
+-- covered by tests/mod_examples_tests.lua when generated data is present.
+package.path = "./?.lua;./?/init.lua;" .. package.path
+
+local function hasGenerated()
+  local handle = io.open("data/generated/constants.lua", "r")
+  if handle then handle:close() return true end
+  return false
+end
+if not hasGenerated() then
+  print("example_silly_oak_test skipped (needs data/generated/)")
+  os.exit(0)
+end
+
+local T = require("tests.modkit")
+local Runtime = require("src.mods.Runtime")
+local OakSpeech = require("src.ui.OakSpeech")
+local Data = require("src.core.Data")
+Data:load()
+
+local run = T.sdk.loadMod("mods/examples/example_silly_oak", { data = Data })
+T.eq(#run.errors, 0, "loads clean (" .. tostring(run.errors[1]) .. ")")
+
+local mod = run.mod
+T.check(mod ~= nil and mod.state == "loaded", "mod reached the loaded state")
+local ModUI = require("src.ui.ModUI")
+local bucket = function()
+  return run.loader.modSave.example_silly_oak or {}
+end
+local toastPath = (mod.path or "mods/examples/example_silly_oak")
+  .. "/assets/toast_kid.png"
+
+-- ------- build hook injects every silly beat around vanilla anchors
+
+local speech = OakSpeech.new({
+  data = Data,
+  save = { player = { name = "RED", rival = "BLUE" } },
+  stack = { push = function() end, pop = function() end },
+}, nil)
+local steps = speech:buildSteps()
+
+local ids = {}
+for _, step in ipairs(steps) do ids[#ids + 1] = step.id end
+local function has(id)
+  for _, x in ipairs(ids) do if x == id then return true end end
+  return false
+end
+
+T.check(has("oak_welcome") and has("name_player") and has("shrink"),
+  "vanilla anchors still present")
+T.check(has("silly_quiz_intro") and has("silly_toast") and has("silly_toast_kid"),
+  "toast quiz beats injected")
+T.check(has("silly_mew") and has("silly_snack"),
+  "MEW reveal and snack choice injected")
+T.check(has("silly_trust") and has("silly_pineapple") and has("silly_closing"),
+  "rival trust + pineapple beats injected")
+
+-- order: toast kid before demo_mon, mew after demo_mon, trust before rival ask
+local function indexOf(id)
+  for i, x in ipairs(ids) do if x == id then return i end end
+  return 0
+end
+T.check(indexOf("silly_toast_kid") < indexOf("demo_mon"),
+  "Toast Kid shows before the demo mon")
+T.check(indexOf("demo_mon") < indexOf("silly_mew"),
+  "MEW shows after the demo mon")
+T.check(indexOf("silly_trust") < indexOf("ask_rival_name"),
+  "trust question is before rival naming")
+T.check(indexOf("name_rival") < indexOf("silly_pineapple")
+        and indexOf("silly_pineapple") < indexOf("legend"),
+  "pineapple lands between rival name and the legend beat")
+
+-- ------- step shapes cover choice / yesno / custom image / pokemon
+
+local byId = {}
+for _, step in ipairs(steps) do byId[step.id] = step end
+
+T.eq(byId.silly_toast.kind, "yesno", "toast is a yes/no")
+T.eq(byId.silly_toast.saveKey, "likes_toast", "toast writes likes_toast")
+T.eq(byId.silly_snack.kind, "choice", "snack is a multi choice")
+T.eq(#byId.silly_snack.choices, 3, "snack has three options")
+T.check(byId.silly_toast_kid.pic and byId.silly_toast_kid.pic.type == "image",
+  "Toast Kid uses a custom image pic")
+T.check(byId.silly_mew.pic and byId.silly_mew.pic.type == "pokemon"
+        and byId.silly_mew.pic.id == "MEW" and byId.silly_mew.cry == "MEW",
+  "MEW beat uses pokemon pic + cry")
+T.eq(byId.silly_trust.pic, "rival", "trust question shows the rival pic")
+
+-- ------- resolvePic covers trainer / pokemon / player / image shorthand
+
+local oakImg = OakSpeech.resolvePic({ data = Data }, "oak", speech)
+local rivalImg = OakSpeech.resolvePic({ data = Data }, "rival", speech)
+local playerImg = OakSpeech.resolvePic({ data = Data }, "player", speech)
+local mewImg, mewFlip = OakSpeech.resolvePic({ data = Data },
+  { type = "pokemon", id = "MEW", flip = true }, speech)
+local customImg = OakSpeech.resolvePic({ data = Data },
+  { type = "image", path = toastPath }, speech)
+-- headless love stub may return nil images; the call itself must not throw
+T.check(oakImg == speech.oakPic or oakImg == nil or type(oakImg) == "userdata"
+        or type(oakImg) == "table",
+  "oak shorthand resolves without error")
+T.check(rivalImg == speech.rivalPic or rivalImg == nil or type(rivalImg) == "userdata"
+        or type(rivalImg) == "table",
+  "rival shorthand resolves without error")
+T.check(playerImg == speech.playerPic or playerImg == nil
+        or type(playerImg) == "userdata" or type(playerImg) == "table",
+  "player shorthand resolves without error")
+T.check(mewFlip == true, "pokemon flip flag is honored")
+T.check(customImg ~= nil or true, "custom image path is accepted")
+
+-- ------- answered event writes mod.save (loader.modSave bucket)
+
+Runtime.emit("intro.oak_speech.answered", {
+  saveKey = "likes_toast", value = true, label = "YES", index = 1,
+  step = byId.silly_toast, speech = speech,
+})
+Runtime.emit("intro.oak_speech.answered", {
+  saveKey = "snack", value = "OLD ROD", label = "OLD ROD", index = 3,
+  step = byId.silly_snack, speech = speech,
+})
+Runtime.emit("intro.oak_speech.answered", {
+  saveKey = "trusts_rival", value = false, label = "NO", index = 2,
+  step = byId.silly_trust, speech = speech,
+})
+Runtime.emit("intro.oak_speech.answered", {
+  saveKey = "pineapple_on_pizza", value = true, label = "YES", index = 1,
+  step = byId.silly_pineapple, speech = speech,
+})
+Runtime.emit("intro.oak_speech.finished", {
+  speech = speech, answers = speech.answers,
+})
+
+local saved = bucket()
+T.eq(saved.likes_toast, true, "likes_toast saved")
+T.eq(saved.snack, "OLD ROD", "snack saved")
+T.eq(saved.trusts_rival, false, "trusts_rival saved")
+T.eq(saved.pineapple_on_pizza, true, "pineapple_on_pizza saved")
+T.eq(saved.quiz_done, true, "quiz_done stamped on finish")
+
+-- ------- ModUI step helpers (public surface)
+
+local tiny = {
+  { id = "a", kind = "say" },
+  { id = "b", kind = "say" },
+}
+ModUI.insertStepAfter(tiny, "a", { id = "mid", kind = "choice" })
+T.eq(tiny[2].id, "mid", "insertStepAfter lands behind the anchor")
+ModUI.insertStepBefore(tiny, "b", { id = "pre_b", kind = "yesno" })
+T.eq(tiny[3].id, "pre_b", "insertStepBefore lands ahead of the anchor")
+ModUI.removeStep(tiny, "mid")
+T.check(tiny[2].id ~= "mid", "removeStep drops by id")
+
+run.release()
+T.finish("example_silly_oak")

mods/examples/example_weather/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "overhaul",
   "category": "MECHANIC",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "dependencies": [],
   "optional_dependencies": [],

scripts/build.sh

@@ -1,17 +1,19 @@
 #!/usr/bin/env bash
-# Packages the LÖVE2D Pokémon Red port into distributable macOS and
-# Windows builds. Runs entirely on macOS (no cross-compiling needed, 
-# the Windows build reuses LÖVE's prebuilt win64 binaries).
+# Packages the LÖVE2D Pokémon Red port into distributable macOS, Windows,
+# and Linux builds. Runs entirely on macOS (no cross-compiling needed,
+# the Windows and Linux builds reuse LÖVE's prebuilt win64 / AppImage
+# binaries, fusing our game.love onto them the same way love.exe does).
 #
-# Usage: scripts/build.sh [mac|win|android|ios|all] [--version X.Y.Z] [--identity "Developer ID Application: ..."]
+# Usage: scripts/build.sh [mac|win|linux|android|ios|all] [--version X.Y.Z] [--identity "Developer ID Application: ..."]
 #                          [--notary-profile NAME] [--no-notarize]
-#                          [--release]   # android/ios: release config instead of debug
+#                          [--release]   # ios only: release config instead of debug
 #
-# Output: dist/mac/PokemonRed-macos.zip
-#         dist/win/PokemonRed-win64.zip
-#         dist/android/{debug,release}/*.apk (full gradle output stays under
+# Output: dist/mac/gen1recomp-macos.zip
+#         dist/win/gen1recomp-win64.zip
+#         dist/linux/gen1recomp-linux.zip (fused x86_64 AppImage)
+#         dist/android/debug/*.apk (full gradle output stays under
 #           mobile/android/app/build/outputs/apk/embedNoRecord/)
-#         dist/ios/<Config>-<sdk>/PokemonRed.app (full xcodebuild output stays
+#         dist/ios/<Config>-<sdk>/gen1recomp.app (full xcodebuild output stays
 #           under mobile/ios/build/Build/Products/)
 
 set -euo pipefail
@@ -23,15 +25,15 @@ WORK="$HERE/work"
 DIST="$ROOT/dist"
 ENTITLEMENTS="$ROOT/scripts/macos-entitlements.plist"
 
-APP_NAME="PokemonRed"
+APP_NAME="gen1recomp"
 BUNDLE_ID="com.theboisclub.pokemonred"
 LOVE_VERSION="11.5"
 VERSION="$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || echo dev)"
+VERSION_EXPLICIT=false
 IDENTITY=""
 TARGET="all"
 NOTARY_PROFILE="notary-profile"
 NOTARIZE=true
-ANDROID_RELEASE=false
 IOS_RELEASE=false
 
 say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
@@ -40,25 +42,25 @@ fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    mac|win|android|ios|all) TARGET="$1" ;;
-    --version) VERSION="$2"; shift ;;
+    mac|win|linux|android|ios|all) TARGET="$1" ;;
+    --version) VERSION="$2"; VERSION_EXPLICIT=true; shift ;;
     --identity) IDENTITY="$2"; shift ;;
     --notary-profile) NOTARY_PROFILE="$2"; shift ;;
     --no-notarize) NOTARIZE=false ;;
-    --release) ANDROID_RELEASE=true; IOS_RELEASE=true ;;
+    --release) IOS_RELEASE=true ;;
     *) fail "unknown argument: $1" ;;
   esac
   shift
 done
 
-mkdir -p "$CACHE" "$WORK" "$DIST/mac" "$DIST/win"
+mkdir -p "$CACHE" "$WORK" "$DIST/mac" "$DIST/win" "$DIST/linux"
 
 # --------------------------------------------------------------- game.love
 say "packing game.love"
 LOVE_FILE="$WORK/game.love"
 rm -f "$LOVE_FILE"
 (cd "$ROOT" && zip -q -9 -r "$LOVE_FILE" \
-  main.lua conf.lua src data assets tools/rom_manifest.json \
+  main.lua conf.lua src data assets tools/rom_manifest.json tools/rom_manifest_blue.json \
   -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
 if unzip -Z1 "$LOVE_FILE" \
     | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/'; then
@@ -66,6 +68,31 @@ if unzip -Z1 "$LOVE_FILE" \
 fi
 say "game.love: $(du -h "$LOVE_FILE" | cut -f1)"
 
+# ------------------------------------------------------- stamp release version
+# The working tree ships Version.lua with engine "0.0.0-dev"; the real release
+# number only ever lives inside the packed archive. When --version is a strict
+# X.Y.Z, patch a copy of Version.lua (engine set to that number) under a staging
+# dir and replace the entry inside game.love in place -- never the source tree.
+# Short-hash / "dev" builds are left with the "-dev" default so they cannot be
+# mistaken for a release. The stamp is then read back out of the archive and the
+# build fails if it did not take.
+if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  say "stamping engine version $VERSION into game.love"
+  stamp_dir="$WORK/stamp"
+  rm -rf "$stamp_dir"
+  mkdir -p "$stamp_dir/src/core"
+  sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+    "$ROOT/src/core/Version.lua" > "$stamp_dir/src/core/Version.lua"
+  (cd "$stamp_dir" && zip -q "$LOVE_FILE" src/core/Version.lua)
+  version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+  unzip -p "$LOVE_FILE" src/core/Version.lua \
+    | grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+    || fail "version stamp failed: game.love does not report engine $VERSION"
+  say "stamped engine version: $VERSION"
+else
+  say "version '$VERSION' is not X.Y.Z,  shipping default engine (no stamp)"
+fi
+
 # --------------------------------------------------------------- macOS
 build_mac() {
   say "building macOS app"
@@ -139,11 +166,20 @@ build_win() {
   say "building Windows (win64) app"
   local zip_name="love-$LOVE_VERSION-win64.zip"
   local love_zip="$CACHE/$zip_name"
+  # A cache hit only checks existence, not validity -- a prior run truncated
+  # by a network drop mid-download (curl still leaves the partial file if
+  # the exit code slips through) would otherwise be reused forever.
+  if [ -f "$love_zip" ] && ! unzip -tqq "$love_zip" >/dev/null 2>&1; then
+    warn "cached $zip_name is not a valid zip,  removing and re-downloading"
+    rm -f "$love_zip"
+  fi
   if [ ! -f "$love_zip" ]; then
     say "downloading LÖVE $LOVE_VERSION win64 binaries"
     curl -fL --progress-bar \
       "https://github.com/love2d/love/releases/download/$LOVE_VERSION/$zip_name" \
       -o "$love_zip" || fail "download failed,  check LOVE_VERSION or your network"
+    unzip -tqq "$love_zip" >/dev/null 2>&1 \
+      || fail "downloaded $zip_name is not a valid zip (truncated download?)"
   fi
 
   local extract_dir="$WORK/love-win64"
@@ -167,12 +203,82 @@ build_win() {
   say "Windows build: $zip_out"
 }
 
+# --------------------------------------------------------------- Linux
+build_linux() {
+  say "building Linux (x86_64 AppImage) app"
+  local appimage_name="love-$LOVE_VERSION-x86_64.AppImage"
+  local love_appimage="$CACHE/$appimage_name"
+  # Same cache-validity gap as the win64 zip above: an AppImage is just an
+  # ELF, so check the magic bytes before trusting a cached copy is complete.
+  if [ -f "$love_appimage" ] && [ "$(head -c 4 "$love_appimage" | od -An -tx1 | tr -d ' \n')" != "7f454c46" ]; then
+    warn "cached $appimage_name is not a valid ELF binary,  removing and re-downloading"
+    rm -f "$love_appimage"
+  fi
+  if [ ! -f "$love_appimage" ]; then
+    say "downloading LÖVE $LOVE_VERSION Linux AppImage"
+    curl -fL --progress-bar \
+      "https://github.com/love2d/love/releases/download/$LOVE_VERSION/$appimage_name" \
+      -o "$love_appimage" || fail "download failed,  check LOVE_VERSION or your network"
+    [ "$(head -c 4 "$love_appimage" | od -An -tx1 | tr -d ' \n')" = "7f454c46" ] \
+      || fail "downloaded $appimage_name is not a valid ELF binary (truncated download?)"
+  fi
+  chmod +x "$love_appimage"
+
+  # The Windows-style `cat love.exe game.love` fusion does NOT work here:
+  # an AppImage is a small runtime ELF with a squashfs appended, and at
+  # launch the runtime mounts the squashfs and executes bin/love from
+  # *inside* it -- bytes appended to the outer file are never read, so
+  # users would just get vanilla LÖVE's no-game screen. Instead, unpack
+  # the squashfs, drop game.love in, point AppRun's FUSE_PATH hook at it
+  # (the hook ships commented-out in LÖVE's official AppImage), and glue
+  # runtime + repacked squashfs back together.
+  command -v unsquashfs >/dev/null && command -v mksquashfs >/dev/null \
+    || fail "squashfs tools not found; install with: brew install squashfs"
+
+  # The squashfs starts right where the ELF ends:
+  # e_shoff + e_shnum * e_shentsize (all little-endian in the ELF64 header).
+  local e_shoff e_shentsize e_shnum sfs_offset
+  e_shoff=$(od -An -j40 -N8 -tu8 "$love_appimage" | tr -d ' ')
+  e_shentsize=$(od -An -j58 -N2 -tu2 "$love_appimage" | tr -d ' ')
+  e_shnum=$(od -An -j60 -N2 -tu2 "$love_appimage" | tr -d ' ')
+  sfs_offset=$((e_shoff + e_shentsize * e_shnum))
+  [ "$(dd if="$love_appimage" bs=1 skip="$sfs_offset" count=4 2>/dev/null)" = "hsqs" ] \
+    || fail "no squashfs superblock at computed offset $sfs_offset (unexpected AppImage layout)"
+
+  local appdir="$WORK/linux-appdir"
+  rm -rf "$appdir"
+  unsquashfs -q -no-xattrs -o "$sfs_offset" -d "$appdir" "$love_appimage" >/dev/null
+
+  cp "$LOVE_FILE" "$appdir/game.love"
+  sed -i '' 's|^#FUSE_PATH="$APPDIR/my_game.love"$|FUSE_PATH="$APPDIR/game.love"|' "$appdir/AppRun"
+  grep -q '^FUSE_PATH="\$APPDIR/game.love"$' "$appdir/AppRun" \
+    || fail "failed to enable FUSE_PATH in AppRun (upstream AppRun changed?)"
+
+  # Match the upstream image's compression (gzip, 128K blocks) so the
+  # bundled runtime can read it.
+  local sfs_out="$WORK/game.squashfs"
+  rm -f "$sfs_out"
+  mksquashfs "$appdir" "$sfs_out" \
+    -comp gzip -b 131072 -noappend -all-root -no-xattrs -quiet >/dev/null
+
+  local out_bin="$WORK/$APP_NAME-x86_64.AppImage"
+  rm -f "$out_bin"
+  head -c "$sfs_offset" "$love_appimage" > "$out_bin"
+  cat "$sfs_out" >> "$out_bin"
+  chmod +x "$out_bin"
+
+  local zip_out="$DIST/linux/$APP_NAME-linux.zip"
+  rm -f "$zip_out"
+  (cd "$WORK" && zip -q -9 -j "$zip_out" "$(basename "$out_bin")")
+  say "Linux build: $zip_out"
+}
+
 # --------------------------------------------------------------- Android
 build_android() {
   say "building Android (delegating to scripts/build_android.sh)"
   local args=()
-  if [ "$ANDROID_RELEASE" = true ]; then
-    args+=(--release)
+  if [ "$VERSION_EXPLICIT" = true ]; then
+    args+=(--version "$VERSION")
   fi
   "$ROOT/scripts/build_android.sh" ${args[@]+"${args[@]}"}
 }
@@ -190,9 +296,10 @@ build_ios() {
 case "$TARGET" in
   mac) build_mac ;;
   win) build_win ;;
+  linux) build_linux ;;
   android) build_android ;;
   ios) build_ios ;;
-  all) build_mac; build_win ;;
+  all) build_mac; build_win; build_linux ;;
 esac
 
 case "$TARGET" in

scripts/build_android.sh

@@ -1,11 +1,10 @@
 #!/usr/bin/env bash
 # Packages the LÖVE2D Pokémon Red port into an Android APK via love-android 11.5a.
 #
-# Usage: scripts/build_android.sh [--release] [--package-only]
+# Usage: scripts/build_android.sh [--version X.Y.Z] [--package-only]
 #
-#   (default)       assembleEmbedNoRecordDebug  (debug keystore)
-#   --release       assembleEmbedNoRecordRelease (requires out-of-band signing)
-#   --package-only  zip game.love + apply branding; skip gradle
+#   --version X.Y.Z  set app.version_name / app.version_code (else left as-is)
+#   --package-only   zip game.love + apply branding; skip gradle
 #
 # Prerequisites:
 #   - mobile/android vendored love-android tree at tag 11.5a (in-repo; see mobile/ANDROID.md)
@@ -13,9 +12,8 @@
 #   - JDK 17
 #
 # Output (after gradle):
-#   dist/android/{debug,release}/*.apk (convenience copy)
+#   dist/android/debug/*.apk (convenience copy)
 #   mobile/android/app/build/outputs/apk/embedNoRecord/debug/*.apk
-#   mobile/android/app/build/outputs/apk/embedNoRecord/release/*.apk
 
 set -euo pipefail
 
@@ -24,12 +22,12 @@ ANDROID_DIR="$ROOT/mobile/android"
 EMBED_ASSETS="$ANDROID_DIR/app/src/embed/assets"
 LOVE_FILE="$EMBED_ASSETS/game.love"
 DIST="$ROOT/dist/android"
-APP_NAME="Pokemon Red"
+APP_NAME="gen1recomp"
 APPLICATION_ID="com.theboisclub.pokemonred"
 LOVE_ANDROID_VERSION="11.5a"
 NDK_VERSION="25.2.9519653"
 
-RELEASE=false
+VERSION=""
 PACKAGE_ONLY=false
 
 say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
@@ -38,17 +36,29 @@ fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    --release) RELEASE=true ;;
+    --version) VERSION="$2"; shift ;;
     --package-only) PACKAGE_ONLY=true ;;
     -h|--help)
       sed -n '2,20p' "$0"
       exit 0
       ;;
-    *) fail "unknown argument: $1 (try --release or --package-only)" ;;
+    *) fail "unknown argument: $1 (try --version X.Y.Z or --package-only)" ;;
   esac
   shift
 done
 
+VERSION_CODE=""
+if [ -n "$VERSION" ]; then
+  if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    fail "invalid --version '$VERSION' (expected X.Y.Z)"
+  fi
+  major="${VERSION%%.*}"
+  rest="${VERSION#*.}"
+  minor="${rest%%.*}"
+  patch="${rest##*.}"
+  VERSION_CODE=$((major * 10000 + minor * 100 + patch))
+fi
+
 # --------------------------------------------------------------- preconditions
 if [ ! -f "$ANDROID_DIR/settings.gradle" ] || [ ! -f "$ANDROID_DIR/gradlew" ]; then
   fail "love-android not found at mobile/android/.
@@ -74,10 +84,10 @@ apply_android_branding() {
 
   say "applying Android branding (gradle.properties + permission trim)"
 
-  python3 - "$props" "$APPLICATION_ID" "$APP_NAME" <<'PY'
+  python3 - "$props" "$APPLICATION_ID" "$APP_NAME" "$VERSION" "$VERSION_CODE" <<'PY'
 import pathlib, re, sys
 path = pathlib.Path(sys.argv[1])
-app_id, name = sys.argv[2], sys.argv[3]
+app_id, name, version, version_code = sys.argv[2], sys.argv[3], sys.argv[4], sys.argv[5]
 text = path.read_text()
 
 def set_prop(text, key, value):
@@ -91,7 +101,10 @@ def set_prop(text, key, value):
 text = re.sub(r"(?m)^app\.name_byte_array=.*\n?", "", text)
 text = set_prop(text, "app.name", name)
 text = set_prop(text, "app.application_id", app_id)
-text = set_prop(text, "app.orientation", "portrait")
+text = set_prop(text, "app.orientation", "fullUser")
+if version:
+    text = set_prop(text, "app.version_name", version)
+    text = set_prop(text, "app.version_code", version_code)
 path.write_text(text)
 PY
 
@@ -124,7 +137,7 @@ pack_game_love() {
   mkdir -p "$EMBED_ASSETS"
   rm -f "$LOVE_FILE"
   (cd "$ROOT" && zip -q -9 -r "$LOVE_FILE" \
-    main.lua conf.lua src data assets tools/rom_manifest.json \
+    main.lua conf.lua src data assets tools/rom_manifest.json tools/rom_manifest_blue.json \
     -x '*.DS_Store' -x '*/.git/*' -x '*/.DS_Store' \
     -x 'data/generated/*' -x 'assets/generated/*')
   if unzip -Z1 "$LOVE_FILE" \
@@ -132,6 +145,32 @@ pack_game_love() {
     fail "game.love unexpectedly contains generated ROM data"
   fi
   say "game.love: $(du -h "$LOVE_FILE" | cut -f1) -> $LOVE_FILE"
+
+  # This script packs its own game.love (it does not reuse build.sh's), so it
+  # stamps the release version the same way: patch a copy of Version.lua
+  # (engine set to $VERSION) under a throwaway staging dir and replace the
+  # entry inside the archive in place -- never the source tree. VERSION is
+  # already validated as X.Y.Z above; when it is empty the packaged game keeps
+  # the "0.0.0-dev" default. The stamp is read back out and the build fails if
+  # it did not take.
+  if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    say "stamping engine version $VERSION into game.love"
+    local stamp_dir
+    stamp_dir="$(mktemp -d)"
+    mkdir -p "$stamp_dir/src/core"
+    sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+      "$ROOT/src/core/Version.lua" > "$stamp_dir/src/core/Version.lua"
+    (cd "$stamp_dir" && zip -q "$LOVE_FILE" src/core/Version.lua)
+    local version_re
+    version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+    unzip -p "$LOVE_FILE" src/core/Version.lua \
+      | grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+      || fail "version stamp failed: game.love does not report engine $VERSION"
+    rm -rf "$stamp_dir"
+    say "stamped engine version: $VERSION"
+  else
+    say "no X.Y.Z --version,  shipping default engine (no stamp)"
+  fi
 }
 
 # --------------------------------------------------------------- SDK check
@@ -178,16 +217,8 @@ require_android_sdk() {
 
 # --------------------------------------------------------------- gradle
 run_gradle() {
-  local task
-  if $RELEASE; then
-    task="assembleEmbedNoRecordRelease"
-    say "building release APK ($task)"
-    warn "release signing is out-of-band,  see mobile/ANDROID.md (Signing)."
-    warn "without a signingConfig, assembleRelease may produce an unsigned APK or fail."
-  else
-    task="assembleEmbedNoRecordDebug"
-    say "building debug APK ($task),  uses the default Android debug keystore"
-  fi
+  local task="assembleEmbedNoRecordDebug"
+  say "building APK ($task)"
 
   if ! (
     cd "$ANDROID_DIR"
@@ -199,19 +230,12 @@ run_gradle() {
   You can still iterate on the .love payload with: scripts/build_android.sh --package-only"
   fi
 
-  local out_dir
-  if $RELEASE; then
-    out_dir="$ANDROID_DIR/app/build/outputs/apk/embedNoRecord/release"
-  else
-    out_dir="$ANDROID_DIR/app/build/outputs/apk/embedNoRecord/debug"
-  fi
+  local out_dir="$ANDROID_DIR/app/build/outputs/apk/embedNoRecord/debug"
   if [ -d "$out_dir" ]; then
     say "APK output:"
     find "$out_dir" -name '*.apk' -exec ls -lh {} \;
 
-    local flavor="debug"
-    $RELEASE && flavor="release"
-    local dist_dir="$DIST/$flavor"
+    local dist_dir="$DIST/debug"
     rm -rf "$dist_dir"
     mkdir -p "$dist_dir"
     find "$out_dir" -name '*.apk' -exec cp {} "$dist_dir/" \;

scripts/build_ios.sh

@@ -15,8 +15,8 @@
 #   - mobile/ios/love-src/ (see --fetch / mobile/ios/README.md)
 #   - prebuilt iOS libraries under love-src/platform/xcode/ios/libraries/
 #
-# Output: dist/ios/<Config>-<sdk>/PokemonRed.app (convenience copy)
-#         mobile/ios/build/Build/Products/<Config>-<sdk>/PokemonRed.app
+# Output: dist/ios/<Config>-<sdk>/gen1recomp.app (convenience copy)
+#         mobile/ios/build/Build/Products/<Config>-<sdk>/gen1recomp.app
 
 set -euo pipefail
 
@@ -33,8 +33,8 @@ RESOURCES_DIR="$XCODE_DIR/ios/resources"
 LOVE_FILE="$RESOURCES_DIR/game.love"
 LIBS_DIR="$XCODE_DIR/ios/libraries"
 
-APP_NAME="PokemonRed"
-DISPLAY_NAME="Pokemon Red"
+APP_NAME="gen1recomp"
+DISPLAY_NAME="gen1recomp"
 BUNDLE_ID="com.theboisclub.pokemonred"
 LOVE_VERSION="$(tr -d '[:space:]' < "$IOS_DIR/LOVE_VERSION" 2>/dev/null || echo 11.5)"
 IOS_SOURCE_ZIP="love-${LOVE_VERSION}-ios-source.zip"
@@ -155,7 +155,7 @@ require_ios_libraries
 apply_ios_branding() {
   [ -f "$OVERLAY_PLIST" ] || fail "missing overlay plist: $OVERLAY_PLIST"
   local dest="$XCODE_DIR/ios/love-ios.plist"
-  say "applying iOS branding (portrait-only Info.plist, display name)"
+  say "applying iOS branding (portrait + landscape Info.plist, display name)"
   cp "$OVERLAY_PLIST" "$dest"
 }
 
@@ -166,7 +166,7 @@ pack_game_love() {
   rm -f "$LOVE_FILE"
   # Same payload as scripts/build.sh / build_android.sh: game sources only.
   (cd "$ROOT" && zip -q -9 -r "$LOVE_FILE" \
-    main.lua conf.lua src data assets tools/rom_manifest.json \
+    main.lua conf.lua src data assets tools/rom_manifest.json tools/rom_manifest_blue.json \
     -x '*.DS_Store' -x '*/.git/*' -x '*/.DS_Store' \
     -x 'data/generated/*' -x 'assets/generated/*')
   if unzip -Z1 "$LOVE_FILE" \

scripts/test.sh

@@ -78,23 +78,14 @@ run_tier "T4 mod-SDK" "$LUA" tests/run_modkit.lua
 # ------- content tier: only meaningful with an imported ROM
 
 
-# tests/run_tests.lua carries two pre-existing failures that are stale
-# about the chip-audio architecture rather than real defects:
-#
-#   Pikachu cry WAV exists        nothing writes .wav any more -- cries are
-#                                 synthesized at play time from
-#                                 Data.audio.cries + programs.bin
-#   low-health alarm sfx extracted  the importer deliberately does not
-#                                 extract it; Sound.startLoop falls back to
-#                                 ChipAudio.newLowHealthAlarm (Sound.lua:268)
-#
-# They are left in place (fixing them is a separate, reviewed change), so
-# the tier passes on exactly this baseline and fails the moment a third
-# failure appears or one of these two changes identity.  Ignoring the exit
-# code outright would hide every future content regression.
-KNOWN_CONTENT_FAILURES=2
-KNOWN_CONTENT_LINES="FAIL Pikachu cry WAV exists
-FAIL low-health alarm sfx extracted"
+# tests/run_tests.lua is expected to be clean.  It used to carry two stale
+# chip-audio assertions on the allowlist below (Pikachu cry WAV exists /
+# low-health alarm sfx extracted); both have since been fixed, so the
+# baseline is zero and any failure fails the tier.  Keep the allowlist
+# mechanism rather than ignoring the exit code -- that would hide every
+# future content regression.
+KNOWN_CONTENT_FAILURES=0
+KNOWN_CONTENT_LINES=""
 
 run_content_behavior() {
   local out
@@ -107,7 +98,9 @@ run_content_behavior() {
   if [ "$count" -eq "$KNOWN_CONTENT_FAILURES" ] \
      && [ "$lines" = "$(printf '%s\n' "$KNOWN_CONTENT_LINES" | sort)" ]; then
     printf '%s\n' "$out" | tail -3
-    echo "(the $KNOWN_CONTENT_FAILURES known stale audio assertions, unchanged)"
+    if [ "$KNOWN_CONTENT_FAILURES" -gt 0 ]; then
+      echo "(the $KNOWN_CONTENT_FAILURES known stale assertions, unchanged)"
+    fi
     return 0
   fi
 

src/battle/AnimPlayer.lua

@@ -144,6 +144,25 @@ function AnimPlayer.new(data)
   }, AnimPlayer)
 end
 
+-- Release the tilesheet images and quads this player built.  They live in
+-- per-instance caches (a fresh AnimPlayer is made per battle), so unlike a
+-- shared module cache they are dead the moment the battle ends -- freeing
+-- them here instead of waiting on a GC finalizer keeps grinding battles
+-- from piling orphaned VRAM up faster than the (Lua-heap-triggered) GC
+-- reclaims it.
+function AnimPlayer:release()
+  for _, img in pairs(self.images) do
+    if img and img.release then pcall(img.release, img) end
+  end
+  self.images = {}
+  for _, byTile in pairs(self.quads) do
+    for _, q in pairs(byTile) do
+      if q and q.release then pcall(q.release, q) end
+    end
+  end
+  self.quads = {}
+end
+
 function AnimPlayer:warnOnce(key, fmt, ...)
   if not self.warned[key] then
     self.warned[key] = true

src/battle/EffectRegistry.lua

@@ -8,6 +8,7 @@
 local MoveEffects = require("src.battle.MoveEffects")
 local Runtime = require("src.mods.Runtime")
 local StatusRegistry = require("src.battle.StatusRegistry")
+local Strings = require("src.core.Strings")
 
 local EffectRegistry = {}
 
@@ -89,7 +90,9 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   -- Swift ignores semi-invulnerability (MoveHitTest returns hit for
   -- SWIFT_EFFECT before the INVULNERABLE check)
   if target.invulnerable and not neverMiss then
-    battle:sayNext(("%s's\nattack missed!"):format(displayName(user)))
+    -- Explosion/Selfdestruct still animate on a miss (HandleIfPlayerMoveMissed)
+    if not (record and record.explode) then battle:cancelMoveAnim() end
+    battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
     return
   end
 
@@ -97,6 +100,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   if record and record.gate then
     local ok, failMsg = record.gate(ctx)
     if not ok then
+      battle:cancelMoveAnim()
       if failMsg then battle:sayNext(failMsg) end
       return
     end
@@ -108,7 +112,9 @@ function EffectRegistry.runDamaging(battle, ctx, record)
 
   if not neverMiss then
     if not battle:accuracyRoll(move, user, target) then
-      battle:sayNext(("%s's\nattack missed!"):format(displayName(user)))
+      -- Explosion/Selfdestruct still animate on a miss (HandleIfPlayerMoveMissed)
+      if not (record and record.explode) then battle:cancelMoveAnim() end
+      battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
       -- Jump Kick crash, Explode self-destruct
       if record and record.onMiss then record.onMiss(ctx, "accuracy") end
       user.trappingTurns = nil
@@ -134,7 +140,8 @@ function EffectRegistry.runDamaging(battle, ctx, record)
       end
     end
     if not counterable or (battle.lastDamage or 0) == 0 then
-      battle:sayNext(("%s's\nattack missed!"):format(displayName(user)))
+      battle:cancelMoveAnim()
+      battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
       return
     end
     dmg = math.min(65535, battle.lastDamage * 2)
@@ -144,6 +151,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     -- failed with that text already chosen
     local chosen, extra = record.chooseDamage(ctx)
     if not chosen then
+      battle:cancelMoveAnim()
       if extra then battle:sayNext(extra) end
       return
     end
@@ -154,37 +162,66 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   end
 
   if info.typeMult == 0 then
-    battle:sayNext(("It doesn't affect\n%s!"):format(displayName(target)))
+    -- type immunity zeros damage and sets wMoveMissed in Gen 1, so no anim
+    if not (record and record.explode) then battle:cancelMoveAnim() end
+    battle:sayNext(Strings("It doesn't affect\n%s!", displayName(target)))
     if record and record.onMiss then record.onMiss(ctx, "immune") end
     return
   end
   if info.missed then
     -- 0.25x floored the damage to zero: the original registers a miss
-    battle:sayNext(("%s's\nattack missed!"):format(displayName(user)))
+    if not (record and record.explode) then battle:cancelMoveAnim() end
+    battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
     if record and record.onMiss then record.onMiss(ctx, "floored") end
     return
   end
   battle.lastDamage = dmg -- wDamage (shared by both sides, read by Counter)
 
-  -- the hit blink + damage sound ride the queue behind the animation:
-  -- on the move's anim row when one was announced, else on a bare hit
-  -- row (thrash/rage continuations), placed BEFORE the drain rows the
-  -- hits loop inserts so the blink precedes the bar drain
-  local hitRow = battle.moveAnimRow
-  if not hitRow then
-    battle.nextInsert = (battle.nextInsert or 0) + 1
-    hitRow = { hitRow = true }
-    table.insert(battle.queue, battle.nextInsert, hitRow)
-  end
+  -- the hit blink + damage sound ride each animation row, placed BEFORE
+  -- that hit's drain so the blink precedes the bar.  Multi-hit moves
+  -- replay PlayMoveAnimation per strike (pokered: GetPlayerAnimationType
+  -- / GetEnemyAnimationType loop on wNumAttacksLeft); hit 1 reuses the
+  -- announcement-time moveAnimRow, later hits queue fresh anim rows.
+  -- Thrash/rage continuations have no announcement anim -- a bare
+  -- hitRow carries the blink instead.
+  local hitSfx = info.typeMult > 10 and "Super_Effective"
+                 or info.typeMult < 10 and "Not_Very_Effective" or "Damage"
+  local hitFx = { sfx = hitSfx,
+                  blink = battle:animationsOn() and target or nil }
 
   local totalDealt = 0
   local landed, brokeSub = 0, false
   for h = 1, hits do
     if target.mon.hp <= 0 then break end
+    local hitRow
+    if h == 1 then
+      hitRow = battle.moveAnimRow
+      if not hitRow then
+        battle.nextInsert = (battle.nextInsert or 0) + 1
+        hitRow = { hitRow = true }
+        table.insert(battle.queue, battle.nextInsert, hitRow)
+      end
+    else
+      battle.nextInsert = (battle.nextInsert or 0) + 1
+      hitRow = { anim = move.id, attackerIsPlayer = user.isPlayer }
+      table.insert(battle.queue, battle.nextInsert, hitRow)
+    end
     local hadSub = target.substituteHP ~= nil
     local dealt = battle:applyDamage(target, dmg)
     totalDealt = totalDealt + dealt
     landed = h
+    if dealt > 0 then hitRow.hit = hitFx end
+    -- PrintCriticalOHKOText + DisplayEffectiveness run inside the
+    -- multi-hit loop (core.asm .moveDidNotMiss before the jump back
+    -- to GetPlayerAnimationType), so crit/effectiveness reprint on
+    -- every strike -- damage was only rolled once
+    if info.crit then battle:sayNext(Strings("Critical hit!")) end
+    if info.ohko then battle:sayNext(Strings("One-hit KO!")) end
+    if info.typeMult > 10 then
+      battle:sayNext(Strings("It's super\neffective!"))
+    elseif info.typeMult < 10 then
+      battle:sayNext(Strings("It's not very\neffective..."))
+    end
     if Runtime.wants("battle.damage_dealt") then
       Runtime.emit("battle.damage_dealt", {
         battle = battle, user = user, target = target, move = move,
@@ -198,29 +235,12 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     end
   end
   hits = landed > 0 and landed or hits
-  if totalDealt > 0 then
-    -- the original's per-hit sound: normal / super / not-very-effective
-    local hitSfx = info.typeMult > 10 and "Super_Effective"
-                   or info.typeMult < 10 and "Not_Very_Effective" or "Damage"
-    hitRow.hit = { sfx = hitSfx,
-                   blink = battle:animationsOn() and target or nil }
-  end
-  -- PrintCriticalOHKOText prints "Critical hit!"/"One-hit KO!" right
-  -- after the damage lands, BEFORE DisplayEffectiveness (core.asm
-  -- .moveDidNotMiss); the multi-hit count follows the last hit
-  if info.crit then battle:sayNext("Critical hit!") end
-  if info.ohko then battle:sayNext("One-hit KO!") end
-  if info.typeMult > 10 then
-    battle:sayNext("It's super\neffective!")
-  elseif info.typeMult < 10 then
-    battle:sayNext("It's not very\neffective...")
-  end
   if hits > 1 then
     -- player: _MultiHitText; enemy: _HitXTimesText (always plural)
     if user.isPlayer then
-      battle:sayNext(("Hit the enemy\n%d times!"):format(hits))
+      battle:sayNext(Strings("Hit the enemy\n%d times!", hits))
     else
-      battle:sayNext(("Hit %d times!"):format(hits))
+      battle:sayNext(Strings("Hit %d times!", hits))
     end
   end
 
@@ -232,7 +252,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   elseif moveInst.struggle then
     -- struggle recoils even when its effect id resolves to no record
     local recoil = math.max(1, math.floor(dmg / 2))
-    battle:sayNext(("%s's\nhit with recoil!"):format(displayName(user)))
+    battle:sayNext(Strings("%s's\nhit with recoil!", displayName(user)))
     battle:applyDamage(user, recoil)
   end
 

src/battle/MoveEffects.lua

@@ -15,6 +15,7 @@ local Logger = require("src.core.Logger")
 local StatusRegistry = require("src.battle.StatusRegistry")
 local TurnOrder = require("src.battle.TurnOrder")
 local TypeChart = require("src.battle.TypeChart")
+local Strings = require("src.core.Strings")
 
 local MoveEffects = {}
 
@@ -36,14 +37,14 @@ local STAT_LABEL = {
 local function changeStage(battle, who, stat, delta, fromEnemy)
   if fromEnemy and (who.substituteHP or who.mist) then
     if who.mist then
-      return { displayName(who) .. " is\nprotected by MIST!" }
+      return { Strings("%s is\nprotected by MIST!", displayName(who)) }
     end
-    return { "But, it failed!" }
+    return { Strings("But, it failed!") }
   end
   local cur = who.stages[stat] or 0
   local new = math.max(-6, math.min(6, cur + delta))
   if new == cur then
-    return { ("Nothing happened!") }
+    return { Strings("Nothing happened!") }
   end
   who.stages[stat] = new
   -- effects.asm:505-506: after any stat-stage change, modified stats are
@@ -53,13 +54,13 @@ local function changeStage(battle, who, stat, delta, fromEnemy)
   -- _MonsStatsRoseText/_MonsStatsFellText: "X's / STAT rose!"; the
   -- two-stage variants scroll "greatly" onto a third line
   if delta >= 2 then
-    return { ("%s's\n%s\ngreatly rose!"):format(displayName(who), STAT_LABEL[stat]) }
+    return { Strings("%s's\n%s\ngreatly rose!", displayName(who), STAT_LABEL[stat]) }
   elseif delta == 1 then
-    return { ("%s's\n%s rose!"):format(displayName(who), STAT_LABEL[stat]) }
+    return { Strings("%s's\n%s rose!", displayName(who), STAT_LABEL[stat]) }
   elseif delta == -1 then
-    return { ("%s's\n%s fell!"):format(displayName(who), STAT_LABEL[stat]) }
+    return { Strings("%s's\n%s fell!", displayName(who), STAT_LABEL[stat]) }
   end
-  return { ("%s's\n%s\ngreatly fell!"):format(displayName(who), STAT_LABEL[stat]) }
+  return { Strings("%s's\n%s\ngreatly fell!", displayName(who), STAT_LABEL[stat]) }
 end
 MoveEffects.changeStage = changeStage
 
@@ -88,10 +89,10 @@ end
 local function statusMove(status)
   return function(battle, user, target, move)
     if target.mon.status then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     if status == "PSN" and target.substituteHP then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     local msgs = inflictStatus(battle, target, status, {
       toxic = move and move.id == "TOXIC",
@@ -99,7 +100,7 @@ local function statusMove(status)
       source = move and move.id,
     })
     if #msgs == 0 then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     return msgs
   end
@@ -111,7 +112,7 @@ local function statusSide(status, chance)
     -- target (regardless of the burn roll)
     if move and move.type == "FIRE" and target.mon.status == "FRZ" then
       target.mon.status = nil
-      return { ("Fire defrosted\n%s!"):format(displayName(target)) }
+      return { Strings("Fire defrosted\n%s!", displayName(target)) }
     end
     if battle.rng(0, 255) >= chance then return {} end
     return inflictStatus(battle, target, status, {
@@ -144,10 +145,10 @@ end
 
 local function confuse(battle, target, pierceSub)
   if target.confusedTurns or (target.substituteHP and not pierceSub) then
-    return { "But, it failed!" }
+    return { Strings("But, it failed!") }
   end
   target.confusedTurns = battle.rng(2, 5)
-  return { ("%s\nbecame confused!"):format(displayName(target)) }
+  return { Strings("%s\nbecame confused!", displayName(target)) }
 end
 
 -- ---------------------------------------------------------------------
@@ -181,53 +182,53 @@ MoveEffects.primary = {
   LEECH_SEED_EFFECT = function(battle, user, target)
     -- leech_seed.asm has no substitute check: seeding lands through one
     if target.leechSeeded then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     for _, t in ipairs(target.curTypes) do
-      if t == "GRASS" then return { "But, it failed!" } end
+      if t == "GRASS" then return { Strings("But, it failed!") } end
     end
     target.leechSeeded = true
-    return { ("%s\nwas seeded!"):format(displayName(target)) }
+    return { Strings("%s\nwas seeded!", displayName(target)) }
   end,
 
   HEAL_EFFECT = function(battle, user, target, move)
     local mon = user.mon
     if move.id == "REST" then
-      if mon.hp == mon.stats.hp then return { "But, it failed!" } end
+      if mon.hp == mon.stats.hp then return { Strings("But, it failed!") } end
       mon.hp = mon.stats.hp
       mon.status = "SLP"
       user.sleepTurns = 2
       user.toxicCounter = nil
-      return { ("%s\nstarted sleeping!"):format(displayName(user)) }
+      return { Strings("%s\nstarted sleeping!", displayName(user)) }
     end
-    if mon.hp == mon.stats.hp then return { "But, it failed!" } end
+    if mon.hp == mon.stats.hp then return { Strings("But, it failed!") } end
     mon.hp = math.min(mon.stats.hp, mon.hp + math.floor(mon.stats.hp / 2))
-    return { ("%s\nregained health!"):format(displayName(user)) }
+    return { Strings("%s\nregained health!", displayName(user)) }
   end,
 
   LIGHT_SCREEN_EFFECT = function(battle, user)
-    if user.lightScreen then return { "But, it failed!" } end
+    if user.lightScreen then return { Strings("But, it failed!") } end
     user.lightScreen = true
-    return { ("%s's\nprotected against\nspecial attacks!"):format(displayName(user)) }
+    return { Strings("%s's\nprotected against\nspecial attacks!", displayName(user)) }
   end,
 
   REFLECT_EFFECT = function(battle, user)
-    if user.reflect then return { "But, it failed!" } end
+    if user.reflect then return { Strings("But, it failed!") } end
     user.reflect = true
-    return { ("%s\ngained armor!"):format(displayName(user)) }
+    return { Strings("%s\ngained armor!", displayName(user)) }
   end,
 
   MIST_EFFECT = function(battle, user)
-    if user.mist then return { "But, it failed!" } end
+    if user.mist then return { Strings("But, it failed!") } end
     user.mist = true
     -- _ShroudedInMistText (lowercase "mist")
-    return { ("%s's\nshrouded in mist!"):format(displayName(user)) }
+    return { Strings("%s's\nshrouded in mist!", displayName(user)) }
   end,
 
   FOCUS_ENERGY_EFFECT = function(battle, user)
-    if user.focusEnergy then return { "But, it failed!" } end
+    if user.focusEnergy then return { Strings("But, it failed!") } end
     user.focusEnergy = true
-    return { ("%s's\ngetting pumped!"):format(displayName(user)) }
+    return { Strings("%s's\ngetting pumped!", displayName(user)) }
   end,
 
   HAZE_EFFECT = function(battle, user, target)
@@ -254,33 +255,33 @@ MoveEffects.primary = {
       target.skipMove = true
     end
     target.mon.status = nil
-    return { "All STATUS changes\nare eliminated!" }
+    return { Strings("All STATUS changes\nare eliminated!") }
   end,
 
   SUBSTITUTE_EFFECT = function(battle, user)
-    if user.substituteHP then return { ("%s\nhas a SUBSTITUTE!"):format(displayName(user)) } end
+    if user.substituteHP then return { Strings("%s\nhas a SUBSTITUTE!", displayName(user)) } end
     local cost = math.floor(user.mon.stats.hp / 4)
     -- substitute.asm only fails on subtraction underflow (current HP
     -- strictly below maxHP/4); at equality the substitute is built and
     -- the user is left standing on exactly 0 HP (it faints only when
     -- the engine next checks HP, not here)
     if user.mon.hp < cost then
-      return { "Too weak to make\na SUBSTITUTE!" }
+      return { Strings("Too weak to make\na SUBSTITUTE!") }
     end
     user.mon.hp = user.mon.hp - cost
     user.substituteHP = cost + 1
     -- _SubstituteText
-    return { "It created a\nSUBSTITUTE!" }
+    return { Strings("It created a\nSUBSTITUTE!") }
   end,
 
   CONVERSION_EFFECT = function(battle, user, target)
     -- conversion.asm fails against a mid-Fly/Dig target (INVULNERABLE)
     if target.invulnerable then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     user.curTypes = { target.curTypes[1], target.curTypes[2] }
     -- _ConvertedTypeText
-    return { ("Converted type to\n%s's!"):format(displayName(target)) }
+    return { Strings("Converted type to\n%s's!", displayName(target)) }
   end,
 
   -- MIMIC_EFFECT lives in BattleState:resolveMimic: MimicEffect
@@ -311,27 +312,27 @@ MoveEffects.primary = {
       table.insert(user.curMoves, { id = mv.id, pp = 5, mimic = true })
     end
     -- _TransformedText: the copied name prints bare (wNameBuffer)
-    return { ("%s\ntransformed into\n%s!"):format(displayName(user), target.name) }
+    return { Strings("%s\ntransformed into\n%s!", displayName(user), target.name) }
   end,
 
   DISABLE_EFFECT = function(battle, user, target)
-    if target.disabledSlot then return { "But, it failed!" } end
+    if target.disabledSlot then return { Strings("But, it failed!") } end
     local usable = {}
     for i, mv in ipairs(target.curMoves) do
       if mv.pp > 0 then table.insert(usable, i) end
     end
-    if #usable == 0 then return { "But, it failed!" } end
+    if #usable == 0 then return { Strings("But, it failed!") } end
     local slot = usable[battle.rng(1, #usable)]
     target.disabledSlot = slot
     target.disabledTurns = battle.rng(1, 8)
     local id = target.curMoves[slot].id
     -- _MoveWasDisabledText: "X's / MOVE was / disabled!"
-    return { ("%s's\n%s was\ndisabled!"):format(displayName(target),
+    return { Strings("%s's\n%s was\ndisabled!", displayName(target),
                                                 battle.data.moves[id].name) }
   end,
 
   SPLASH_EFFECT = function()
-    return { "No effect!" }
+    return { Strings("No effect!") }
   end,
 }
 
@@ -428,7 +429,9 @@ local function drainHalf(text)
     local mon = ctx.user.mon
     mon.hp = math.min(mon.stats.hp, mon.hp + heal)
     ctx.drain()
-    ctx.say(text:format(displayName(ctx.target)))
+    -- `text` arrives as a source string (Strings.source at the call
+    -- site keeps it in the catalog); look it up here, at use time
+    ctx.say(Strings(text, displayName(ctx.target)))
   end
 end
 
@@ -436,7 +439,7 @@ end
 -- flags the miss before the special-damage override)
 local function immuneMsg(ctx)
   if TypeChart.effectiveness(ctx.move.type, ctx.target.curTypes) == 0 then
-    return ("It doesn't affect\n%s!"):format(displayName(ctx.target))
+    return Strings("It doesn't affect\n%s!", displayName(ctx.target))
   end
   return nil
 end
@@ -498,12 +501,12 @@ MoveEffects.full = {
       -- removed): overkill and substitute hits recoil at full strength
       local recoil = math.max(1, math.floor(ctx.rawDamage
                                             / (ctx.moveInst.struggle and 2 or 4)))
-      ctx.say(("%s's\nhit with recoil!"):format(displayName(ctx.user)))
+      ctx.say(Strings("%s's\nhit with recoil!", displayName(ctx.user)))
       ctx.battle:applyDamage(ctx.user, recoil)
     end,
   },
   DRAIN_HP_EFFECT = {
-    afterDamage = drainHalf("Sucked health from\n%s!"),
+    afterDamage = drainHalf(Strings.source("Sucked health from\n%s!")),
   },
   DREAM_EATER_EFFECT = {
     -- only works on sleeping targets (checked before damage)
@@ -511,13 +514,13 @@ MoveEffects.full = {
       if ctx.target.mon.status ~= "SLP" then return false, "But, it failed!" end
       return true
     end,
-    afterDamage = drainHalf("%s's\ndream was eaten!"),
+    afterDamage = drainHalf(Strings.source("%s's\ndream was eaten!")),
   },
 
   -- charge moves: first turn just charges; Fly AND Dig go
   -- semi-invulnerable (ChargeEffect sets INVULNERABLE for both)
-  CHARGE_EFFECT = { charge = {} },
-  FLY_EFFECT = { charge = { invulnerable = true } },
+  CHARGE_EFFECT = { charge = { anim = "XSTATITEM_ANIM", enemyAnim = "XSTATITEM_DUPLICATE_ANIM" } },
+  FLY_EFFECT = { charge = { invulnerable = true, anim = "TELEPORT" } },
 
   TRAPPING_EFFECT = {
     -- TrappingEffect runs BEFORE the hit test and clears the target's
@@ -557,7 +560,7 @@ MoveEffects.full = {
           user.thrashTurns, user.thrashMove, user.thrashAnnounced = nil, nil, nil
           if not user.confusedTurns then
             user.confusedTurns = ctx.rng(2, 5)
-            ctx.say(("%s\nbecame confused!"):format(displayName(user)))
+            ctx.say(Strings("%s\nbecame confused!", displayName(user)))
           end
         end
       end
@@ -566,7 +569,7 @@ MoveEffects.full = {
   JUMP_KICK_EFFECT = {
     onMiss = function(ctx, reason)
       if reason ~= "accuracy" then return end
-      ctx.say(("%s\nkept going and\ncrashed!"):format(displayName(ctx.user)))
+      ctx.say(Strings("%s\nkept going and\ncrashed!", displayName(ctx.user)))
       ctx.damage(ctx.user, 1)
     end,
   },
@@ -581,8 +584,12 @@ MoveEffects.full = {
   },
   HYPER_BEAM_EFFECT = {
     afterDamage = function(ctx)
-      -- no recharge when the target faints OR its substitute breaks
-      if ctx.target.mon.hp > 0 and not ctx.brokeSub then
+      -- Gen 1: no recharge when the target faints OR its substitute breaks.
+      -- Ruleset hyperBeamSkipRechargeOnKO=false forces Gen 2+ always-recharge.
+      local ruleset = ctx.battle and ctx.battle.ruleset
+      local skipOnKO = not ruleset or ruleset.hyperBeamSkipRechargeOnKO ~= false
+      local targetDown = ctx.target.mon.hp <= 0 or ctx.brokeSub
+      if not skipOnKO or not targetDown then
         ctx.user.mustRecharge = true
       end
     end,
@@ -591,7 +598,7 @@ MoveEffects.full = {
     afterDamage = function(ctx)
       local battle = ctx.battle
       battle.payDay = (battle.payDay or 0) + 2 * ctx.user.mon.level
-      ctx.say("Coins scattered\neverywhere!")
+      ctx.say(Strings("Coins scattered\neverywhere!"))
     end,
   },
   SWIFT_EFFECT = { neverMiss = true },
@@ -606,7 +613,7 @@ MoveEffects.full = {
       local user = ctx.user
       user.bideTurns = ctx.rng(2, 3)
       user.bideDamage = 0
-      ctx.say(("%s\nis storing energy!"):format(displayName(user)))
+      ctx.say(Strings("%s\nis storing energy!", displayName(user)))
     end,
   },
   SWITCH_AND_TELEPORT_EFFECT = {
@@ -616,6 +623,7 @@ MoveEffects.full = {
     -- roll is below opponentLevel/4.  Teleport's failure text is "But
     -- it failed!", Roar/Whirlwind's is DidntAffectText; in trainer
     -- battles Teleport fails and Roar/Whirlwind are "unaffected".
+    -- Fail paths DelayFrames then print -- no PlayCurrentMoveAnimation.
     perform = function(ctx)
       local battle, user, target, move = ctx.battle, ctx.user, ctx.target, ctx.move
       if battle.kind == "wild" then
@@ -626,23 +634,27 @@ MoveEffects.full = {
         end
         if ok then
           if move.id == "ROAR" then
-            ctx.say(("%s\nran away scared!"):format(displayName(target)))
+            ctx.say(Strings("%s\nran away scared!", displayName(target)))
           elseif move.id == "WHIRLWIND" then
-            ctx.say(("%s\nwas blown away!"):format(displayName(target)))
+            ctx.say(Strings("%s\nwas blown away!", displayName(target)))
           else
-            ctx.say(("%s\nran from battle!"):format(displayName(user)))
+            ctx.say(Strings("%s\nran from battle!", displayName(user)))
           end
           battle.result = "run"
           battle.afterQueue = "finish"
         elseif move.id == "TELEPORT" then
-          ctx.say("But, it failed!")
+          battle:cancelMoveAnim()
+          ctx.say(Strings("But, it failed!"))
         else
-          ctx.say(("It didn't affect\n%s!"):format(displayName(target)))
+          battle:cancelMoveAnim()
+          ctx.say(Strings("It didn't affect\n%s!", displayName(target)))
         end
       elseif move.id == "TELEPORT" then
-        ctx.say("But, it failed!")
+        battle:cancelMoveAnim()
+        ctx.say(Strings("But, it failed!"))
       else
-        ctx.say(("%s\nis unaffected!"):format(displayName(target)))
+        battle:cancelMoveAnim()
+        ctx.say(Strings("%s\nis unaffected!", displayName(target)))
       end
     end,
   },
@@ -660,7 +672,7 @@ MoveEffects.full = {
     callsMove = function(ctx)
       local last = ctx.target.lastMove
       if not last then
-        ctx.say("The MIRROR MOVE\nfailed!")
+        ctx.say(Strings("The MIRROR MOVE\nfailed!"))
         return nil
       end
       return last

src/battle/Status.lua

@@ -5,6 +5,8 @@
 -- and residual sweep.  Callers without a battle (pure-module tests) fall
 -- back to the vanilla records, which is bit-identical behavior.
 
+local Strings = require("src.core.Strings")
+
 local Status = {}
 
 -- pokered's <USER>/<TARGET> text macros print "Enemy " before the enemy
@@ -28,8 +30,11 @@ local function hasType(battler, wanted)
 end
 
 -- shared PSN/BRN residual: 1/16 max HP, multiplied (and advanced) by the
--- Toxic counter (HandlePoisonBurnLeechSeed)
-local function damageOverTime(what)
+-- Toxic counter (HandlePoisonBurnLeechSeed).  The caller passes the whole
+-- sentence rather than the noun: "hurt by poison" and "hurt by the burn"
+-- decline differently once translated, so a shared fragment cannot be the
+-- translatable unit.
+local function damageOverTime(template)
   return function(battler)
     local mon = battler.mon
     local base = math.max(1, math.floor(mon.stats.hp / 16))
@@ -39,10 +44,15 @@ local function damageOverTime(what)
       battler.toxicCounter = battler.toxicCounter + 1
     end
     mon.hp = math.max(0, mon.hp - dmg)
-    return { ("%s's\nhurt by %s!"):format(name(battler), what) }
+    return { Strings(template, name(battler)) }
   end
 end
 
+-- Labels stay plain literals on purpose: this table is built at require
+-- time, before Strings.load has a catalog, so a Strings() here would
+-- freeze the English.  They are already translatable through the
+-- statuses registry (mod.content.statuses:patch(id, { label = ... })).
+--
 -- The five persistent conditions as records: the beforeMove gauntlet, the
 -- residual sweep, the inflict text/immunities (StatusRegistry.inflict),
 -- the catch/wobble bonuses (Catching.attempt), the HUD label, and the
@@ -57,13 +67,13 @@ Status.RECORDS = {
       battler.sleepTurns = (battler.sleepTurns or 1) - 1
       if battler.sleepTurns <= 0 then
         battler.mon.status = nil
-        return false, { name(battler) .. "\nwoke up!" } -- wakes but loses the turn
+        return false, { Strings("%s\nwoke up!", name(battler)) } -- wakes, loses the turn
       end
-      return false, { name(battler) .. "\nis fast asleep!" }
+      return false, { Strings("%s\nis fast asleep!", name(battler)) }
     end,
     onInflict = function(battle, target, opts, display)
       target.sleepTurns = battle.rng(1, 7)
-      return { ("%s\nfell asleep!"):format(display) }
+      return { Strings("%s\nfell asleep!", display) }
     end,
   },
   FRZ = {
@@ -71,35 +81,35 @@ Status.RECORDS = {
     catchBonus = 25, shakeBonus = 10,
     beforeMovePriority = 30,
     beforeMove = function(battler)
-      return false, { name(battler) .. "\nis frozen solid!" }
+      return false, { Strings("%s\nis frozen solid!", name(battler)) }
     end,
     canInflict = function(target) return not hasType(target, "ICE") end,
     onInflict = function(_, _, _, display)
-      return { ("%s\nwas frozen solid!"):format(display) }
+      return { Strings("%s\nwas frozen solid!", display) }
     end,
   },
   PSN = {
     id = "PSN", label = "PSN", hudLabel = "PSN",
     catchBonus = 12, shakeBonus = 5,
-    residual = damageOverTime("poison"),
+    residual = damageOverTime(Strings.source("%s's\nhurt by poison!")),
     canInflict = function(target) return not hasType(target, "POISON") end,
     onInflict = function(_, target, opts, display)
       if opts.toxic then
         target.toxicCounter = 1
         -- _BadlyPoisonedText
-        return { ("%s's\nbadly poisoned!"):format(display) }
+        return { Strings("%s's\nbadly poisoned!", display) }
       end
-      return { ("%s\nwas poisoned!"):format(display) }
+      return { Strings("%s\nwas poisoned!", display) }
     end,
   },
   BRN = {
     id = "BRN", label = "BRN", hudLabel = "BRN",
     catchBonus = 12, shakeBonus = 5,
     statPenalty = { stat = "attack", div = 2 },
-    residual = damageOverTime("the burn"),
+    residual = damageOverTime(Strings.source("%s's\nhurt by the burn!")),
     canInflict = function(target) return not hasType(target, "FIRE") end,
     onInflict = function(_, _, _, display)
-      return { ("%s\nwas burned!"):format(display) }
+      return { Strings("%s\nwas burned!", display) }
     end,
   },
   PAR = {
@@ -110,7 +120,7 @@ Status.RECORDS = {
     beforeMove = function(battler, rng)
       -- cp 25 percent / jr nc: fully paralyzed on rand < 63 (63/256)
       if rng(0, 255) < 63 then
-        return false, { name(battler) .. "'s\nfully paralyzed!" }
+        return false, { Strings("%s's\nfully paralyzed!", name(battler)) }
       end
       return true, {}
     end,
@@ -120,7 +130,7 @@ Status.RECORDS = {
     end,
     onInflict = function(_, _, _, display)
       -- _ParalyzedMayNotAttackText (primary and secondary paralysis)
-      return { ("%s's\nparalyzed! It may\nnot attack!"):format(display) }
+      return { Strings("%s's\nparalyzed! It may\nnot attack!", display) }
     end,
   },
 }
@@ -156,7 +166,7 @@ function Status.beforeMove(battler, rng, battle)
   end
   if battler.flinched then
     battler.flinched = false
-    return false, { name(battler) .. "\nflinched!" }
+    return false, { Strings("%s\nflinched!", name(battler)) }
   end
   local record = Status.recordFor(battleStatuses(battle), mon.status)
   local handler = record and record.beforeMove
@@ -174,23 +184,23 @@ function Status.beforeMove(battler, rng, battle)
   end
   if battler.boundTurns and battler.boundTurns > 0 then
     battler.boundTurns = battler.boundTurns - 1
-    msgs[#msgs + 1] = name(battler) .. "\ncan't move!"
+    msgs[#msgs + 1] = Strings("%s\ncan't move!", name(battler))
     return false, msgs
   end
   if battler.disabledTurns then
     battler.disabledTurns = battler.disabledTurns - 1
     if battler.disabledTurns <= 0 then
       battler.disabledTurns, battler.disabledSlot = nil, nil
-      table.insert(msgs, name(battler) .. "'s\ndisabled no more!")
+      table.insert(msgs, Strings("%s's\ndisabled no more!", name(battler)))
     end
   end
   if battler.confusedTurns then
     battler.confusedTurns = battler.confusedTurns - 1
     if battler.confusedTurns <= 0 then
       battler.confusedTurns = nil
-      table.insert(msgs, name(battler) .. "\nsnapped out of\nconfusion!")
+      table.insert(msgs, Strings("%s\nsnapped out of\nconfusion!", name(battler)))
     else
-      table.insert(msgs, name(battler) .. "\nis confused!")
+      table.insert(msgs, Strings("%s\nis confused!", name(battler)))
       -- cp 50 percent + 1 / jr c: hurt itself on rand >= 128 (128/256)
       if rng(0, 255) < 128 then
         return false, msgs, true -- hurt itself
@@ -231,7 +241,7 @@ function Status.residual(battler, opponent, battle)
     dmg = math.min(dmg, mon.hp)
     mon.hp = mon.hp - dmg
     opponent.mon.hp = math.min(opponent.mon.stats.hp, opponent.mon.hp + dmg)
-    table.insert(msgs, ("LEECH SEED saps\n%s!"):format(name(battler)))
+    table.insert(msgs, Strings("LEECH SEED saps\n%s!", name(battler)))
   end
   return msgs
 end

src/battle/StatusRegistry.lua

@@ -5,6 +5,7 @@
 
 local Runtime = require("src.mods.Runtime")
 local Status = require("src.battle.Status")
+local Strings = require("src.core.Strings")
 
 local StatusRegistry = {}
 
@@ -45,7 +46,7 @@ function StatusRegistry.inflict(battle, target, status, opts)
   if record and record.onInflict then
     msgs = record.onInflict(battle, target, opts, display)
   else
-    msgs = { ("%s\nwas afflicted\nby %s!"):format(display,
+    msgs = { Strings("%s\nwas afflicted\nby %s!", display,
                record and record.label or tostring(status)) }
   end
   Runtime.emit("battle.status_inflicted", {

src/battle/TrainerAI.lua

@@ -15,9 +15,11 @@
 -- (super-effective) or adds 1 (not-effective when a better move exists);
 -- the MINIMUM-scored move is chosen, ties broken uniformly among the
 -- tied minima (core.asm:2971-3002).  A non-minimal move is never
--- selectable.  Respects PP, Disable and Transform/Mimic move overrides.
+-- selectable.  Respects Disable (and PP only when the ruleset depletes
+-- enemy PP — Gen 1 AI never reads wEnemyMonPP).
 
 local TypeChart = require("src.battle.TypeChart")
+local Strings = require("src.core.Strings")
 
 local TrainerAI = {}
 
@@ -98,7 +100,7 @@ function TrainerAI.useItem(battle, item)
   local enemy = battle.enemy
   local trainerName = battle.trainer.name
   local itemName = battle.data.items[item] and battle.data.items[item].name or item
-  local msgs = { ("%s\nused %s!"):format(trainerName, itemName) }
+  local msgs = { Strings("%s\nused %s!", trainerName, itemName) }
   if item == "FULL_HEAL" then
     enemy.mon.status = nil
     enemy.toxicCounter = nil
@@ -111,10 +113,10 @@ function TrainerAI.useItem(battle, item)
   elseif X_STAT[item] then
     local stat = X_STAT[item]
     enemy.stages[stat] = math.min(6, (enemy.stages[stat] or 0) + 1)
-    table.insert(msgs, ("%s's\n%s rose!"):format(enemy.name, stat:upper()))
+    table.insert(msgs, Strings("%s's\n%s rose!", enemy.name, stat:upper()))
   elseif item == "GUARD_SPEC" then
     enemy.mist = true
-    table.insert(msgs, ("%s's\nprotected against\nstat changes!"):format(enemy.name))
+    table.insert(msgs, Strings("%s's\nprotected against\nstat changes!", enemy.name))
   end
   return msgs
 end
@@ -212,9 +214,13 @@ end
 
 function TrainerAI.chooseMove(battler, rng, battle)
   rng = rng or love.math.random
+  -- Gen 1: SelectEnemyMove never consults wEnemyMonPP; Struggle only when
+  -- every move slot is missing/disabled (core.asm:2957-2999). modern_clean
+  -- depletes enemy PP and falls back to Struggle when none remain.
+  local unlimited = battle and battle.ruleset and battle.ruleset.enemyUnlimitedPP
   local usable = {}
   for i, mv in ipairs(battler.curMoves) do
-    if mv.pp > 0 and battler.disabledSlot ~= i then
+    if battler.disabledSlot ~= i and (unlimited or mv.pp > 0) then
       table.insert(usable, mv)
     end
   end

src/battle/rulesets/gen1_faithful.lua

@@ -13,4 +13,10 @@ return {
   randMax = 255,
   -- Focus Energy famously QUARTERS the crit rate instead of x4
   focusEnergyBug = true,
+  -- Wild/trainer enemies never spend PP (DecrementPP only touches the
+  -- player side in pokered). They therefore never Struggle from empty PP.
+  enemyUnlimitedPP = true,
+  -- Gen 1 Hyper Beam: no recharge when the target faints (or its
+  -- substitute breaks).  Set false to always recharge like Gen 2+.
+  hyperBeamSkipRechargeOnKO = true,
 }

src/battle/rulesets/modern_clean.lua

@@ -9,4 +9,8 @@ return {
   randMin = 217,
   randMax = 255,
   focusEnergyBug = false,
+  -- Gen 2+ style: AI opponents deplete PP and can Struggle when empty.
+  enemyUnlimitedPP = false,
+  -- Gen 2+: Hyper Beam always forces a recharge turn, even on a KO.
+  hyperBeamSkipRechargeOnKO = false,
 }

src/core/ChipSynth.lua

@@ -0,0 +1,760 @@
+-- Pure Game Boy audio synthesis (the DMG/GBC channel-program interpreter and
+-- PCM renderer), factored out of ChipAudio so it can run on EITHER the main
+-- thread (SFX/cries, and the synchronous music fallback) or the ChipAudio
+-- worker thread (src/core/chip_worker.lua), which is where map/battle music is
+-- synthesized so a song change never stutters the render thread.
+--
+-- Deliberately depends ONLY on `bit`, love.sound and love.filesystem: no
+-- love.audio (Sources are a playback concern the caller owns) and no
+-- src.render.Assets (hot-reload registration stays in ChipAudio).  Both of
+-- those are unavailable or main-thread-only inside a love.thread worker, so
+-- keeping them out is what lets the same synth code run in the worker.
+
+local bit = require("bit")
+
+local ChipSynth = {}
+
+local SAMPLE_RATE = 22050
+local TICKS_PER_SECOND = 15360
+local FRAME_TICKS = 256
+local GB_CLOCK = 4194304
+
+-- one 4096-sample stereo SoundData is the unit both the worker hands off and
+-- the synchronous fallback queues; the source keeps MUSIC_BUFFER_COUNT of them
+-- (~6s) for stall tolerance (window resize, a long GC pause)
+local MUSIC_BUFFER_SAMPLES = 4096
+local MUSIC_BUFFER_COUNT = 32
+
+ChipSynth.SAMPLE_RATE = SAMPLE_RATE
+ChipSynth.MUSIC_BUFFER_SAMPLES = MUSIC_BUFFER_SAMPLES
+ChipSynth.MUSIC_BUFFER_COUNT = MUSIC_BUFFER_COUNT
+
+local PITCHES = {
+  0xF82C, 0xF89D, 0xF907, 0xF96B, 0xF9CA, 0xFA23,
+  0xFA77, 0xFAC7, 0xFB12, 0xFB58, 0xFB9B, 0xFBDA,
+}
+local DUTY = { [0] = 0.125, [1] = 0.25, [2] = 0.5, [3] = 0.75 }
+local WAVE_LEVEL = { [0] = 0, [1] = 1, [2] = 0.5, [3] = 0.25 }
+local NOISE_DIVISORS = {
+  [0] = 8, [1] = 16, [2] = 32, [3] = 48,
+  [4] = 64, [5] = 80, [6] = 96, [7] = 112,
+}
+
+local function snapTicks(ticks)
+  return math.floor((ticks * 735 + 256) / 512)
+end
+
+local cachedProgramFile
+local cachedBanks
+
+local function loadBanks(data)
+  local audio = data.audio
+  if cachedProgramFile == audio.programFile and cachedBanks then
+    return cachedBanks
+  end
+  local raw, readError = love.filesystem.read(audio.programFile)
+  if not raw then error("could not read sound programs: " .. tostring(readError)) end
+  local banks = {}
+  for index, bank in ipairs(audio.bankOrder) do
+    local first = (index - 1) * 0x4000 + 1
+    banks[bank] = raw:sub(first, first + 0x3FFF)
+  end
+  cachedProgramFile, cachedBanks = audio.programFile, banks
+  return banks
+end
+
+-- drop the single-slot bank cache; the worker keeps its own copy of this
+-- module's state, so ChipAudio.invalidate must reach it via a worker message
+function ChipSynth.invalidateBanks()
+  cachedProgramFile, cachedBanks = nil, nil
+end
+
+-- A def-local program (ChipAsm output) is mounted as pseudo-bank 0 next to
+-- the ROM banks, so the 0x4000-window byte reader and every call/loop
+-- target work unchanged.  The ROM's own cached bank table is never touched
+-- because bank 0 differs per def, and a blob that carries its own waves and
+-- drums renders even where programs.bin is unreadable.
+local function engineBanks(data, chip)
+  if not chip then return loadBanks(data) end
+  local banks = {}
+  local ok, romBanks = pcall(loadBanks, data)
+  if ok then
+    for bank, bytes in pairs(romBanks) do banks[bank] = bytes end
+  end
+  banks[0] = chip.blob
+  return banks
+end
+
+local function romByte(banks, bank, address)
+  local bytes = assert(banks[bank], "uncached audio bank " .. tostring(bank))
+  local value = bytes:byte(address - 0x4000 + 1)
+  if not value then
+    error(("audio read outside bank %02X:%04X"):format(bank, address))
+  end
+  return value
+end
+
+local function romWord(banks, bank, address)
+  return romByte(banks, bank, address)
+    + romByte(banks, bank, address + 1) * 0x100
+end
+
+local function headerChannels(banks, header)
+  local channels = {}
+  local address = header.address
+  local first = romByte(banks, header.bank, address)
+  local count = bit.rshift(bit.band(first, 0xF0), 6) + 1
+  for _ = 1, count do
+    local descriptor = romByte(banks, header.bank, address)
+    channels[#channels + 1] = {
+      number = bit.band(descriptor, 0x0F) + 1,
+      address = romWord(banks, header.bank, address + 1),
+    }
+    address = address + 3
+  end
+  return channels
+end
+
+local function fadeValue(nibble)
+  if bit.band(nibble, 8) ~= 0 then return -bit.band(nibble, 7) end
+  return nibble
+end
+
+local Channel = {}
+Channel.__index = Channel
+
+function Channel.new(engine, spec, options)
+  options = options or {}
+  local hardware = (spec.number - 1) % 4 + 1
+  local isSfxChannel = spec.number > 4
+  return setmetatable({
+    engine = engine,
+    bank = options.bank,
+    address = spec.address,
+    number = spec.number,
+    hardware = hardware,
+    wave = hardware == 3,
+    noise = hardware == 4,
+    sfx = isSfxChannel,
+    executeMusic = not isSfxChannel,
+    allowLoops = options.allowLoops ~= false,
+    frequencyOffset = options.frequencyOffset or 0,
+    frameTicks = options.frameTicks or FRAME_TICKS,
+    speed = 12,
+    volume = 12,
+    fade = 0,
+    duty = 0.5,
+    octave = 4,
+    waveInstrument = 0,
+    waveLevel = 1,
+    perfectPitch = false,
+    vibrato = nil,
+    pendingSlide = nil,
+    sweep = nil,
+    callStack = {},
+    loopCounts = {},
+    event = nil,
+    ended = false,
+    phase = 0,
+    noiseLfsr = 0x7FFF,
+    noiseClock = 0,
+    timeTicks = 0,
+  }, Channel)
+end
+
+function Channel:byte()
+  local value = romByte(self.engine.banks, self.bank, self.address)
+  self.address = self.address + 1
+  return value
+end
+
+function Channel:word()
+  local value = romWord(self.engine.banks, self.bank, self.address)
+  self.address = self.address + 2
+  return value
+end
+
+function Channel:frequency(note, octave)
+  local signed = PITCHES[note + 1] - 0x10000
+  local register = bit.band(
+    bit.arshift(signed, math.max(0, (octave or self.octave) - 1)), 0x7FF)
+  if self.perfectPitch then register = bit.band(register + 1, 0x7FF) end
+  return bit.band(register + self.frequencyOffset, 0x7FF)
+end
+
+function Channel:durationTicks(length)
+  local tempo = self.sfx and self.frameTicks or self.engine.tempo
+  local speed = self.sfx and (self.executeMusic and self.speed or 1)
+    or self.speed
+  return length * speed * tempo
+end
+
+function Channel:timedEvent(event, ticks)
+  local first = snapTicks(self.timeTicks)
+  self.timeTicks = self.timeTicks + ticks
+  event.duration = ticks / TICKS_PER_SECOND
+  event.samples = snapTicks(self.timeTicks) - first
+  event.sample = 0
+  event.elapsed = 0
+  return event
+end
+
+function Channel:pan()
+  local mask = bit.lshift(1, self.hardware - 1)
+  return bit.band(bit.rshift(self.engine.pan, 4), mask) ~= 0,
+    bit.band(self.engine.pan, mask) ~= 0
+end
+
+function Channel:tone(ticks, register, volume, fade)
+  if register >= 0x800 then
+    return self:timedEvent({ silence = true }, ticks)
+  end
+  local duration = ticks / TICKS_PER_SECOND
+  local panLeft, panRight = self:pan()
+  local slide
+  if self.pendingSlide then
+    slide = {
+      target = self.pendingSlide.target,
+      frames = math.max(1, duration * 60 - self.pendingSlide.length),
+    }
+    self.pendingSlide = nil
+  end
+  return self:timedEvent({
+    register = register,
+    volume = volume == nil and self.volume or volume,
+    fade = fade == nil and self.fade or fade,
+    duty = self.duty,
+    wave = self.wave,
+    waveInstrument = self.waveInstrument,
+    waveLevel = self.waveLevel,
+    vibrato = slide and nil or self.vibrato,
+    slide = slide,
+    sweep = self.sfx and self.hardware == 1 and self.sweep or nil,
+    panLeft = panLeft,
+    panRight = panRight,
+  }, ticks)
+end
+
+function Channel:noiseEvent(ticks, volume, fade, parameter)
+  local panLeft, panRight = self:pan()
+  return self:timedEvent({
+    noise = true,
+    volume = volume or self.volume,
+    fade = fade or 0,
+    noiseParameter = parameter,
+    panLeft = panLeft, panRight = panRight,
+  }, ticks)
+end
+
+function Channel:drumEvent(ticks, instrument)
+  local panLeft, panRight = self:pan()
+  return self:timedEvent({
+    noise = true,
+    drum = self.engine:noiseInstrument(instrument),
+    panLeft = panLeft,
+    panRight = panRight,
+  }, ticks)
+end
+
+function Channel:silenceEvent(ticks)
+  return self:timedEvent({ silence = true }, ticks)
+end
+
+function Channel:nextEvent()
+  if self.ended then return nil end
+  for _ = 1, 100000 do
+    local commandAddress = self.address
+    local command = self:byte()
+
+    if (self.executeMusic or not self.sfx) and command < 0xC0 then
+      local note = bit.rshift(command, 4)
+      local length = bit.band(command, 0x0F) + 1
+      if self.noise then
+        local instrument = note
+        if command >= 0xB0 then instrument = self:byte() end
+        return self:drumEvent(self:durationTicks(length), instrument)
+      end
+      return self:tone(self:durationTicks(length), self:frequency(note))
+    elseif command >= 0xC0 and command < 0xD0 then
+      local length = bit.band(command, 0x0F) + 1
+      return self:silenceEvent(self:durationTicks(length))
+    elseif command >= 0xD0 and command < 0xE0 then
+      self.speed = bit.band(command, 0x0F)
+      if not self.noise then
+        local packed = self:byte()
+        if self.wave then
+          self.waveLevel = WAVE_LEVEL[bit.band(bit.rshift(packed, 4), 3)]
+          self.waveInstrument = bit.band(packed, 0x0F)
+        else
+          self.volume = bit.rshift(packed, 4)
+          self.fade = fadeValue(bit.band(packed, 0x0F))
+        end
+      end
+    elseif command >= 0xE0 and command <= 0xE7 then
+      self.octave = 8 - bit.band(command, 7)
+    elseif command == 0xE8 then
+      self.perfectPitch = not self.perfectPitch
+    elseif command == 0xE9 then
+      -- Unused command.
+    elseif command == 0xEA then
+      local delay, packed = self:byte(), self:byte()
+      local depth = bit.rshift(packed, 4)
+      if depth == 0 then
+        self.vibrato = nil
+      else
+        self.vibrato = {
+          delay = delay,
+          above = bit.rshift(depth, 1) + bit.band(depth, 1),
+          below = bit.rshift(depth, 1),
+          rate = bit.band(packed, 0x0F),
+        }
+      end
+    elseif command == 0xEB then
+      local length, packed = self:byte(), self:byte()
+      local octave = 8 - bit.rshift(packed, 4)
+      self.pendingSlide = {
+        length = length,
+        target = self:frequency(bit.band(packed, 0x0F), octave),
+      }
+    elseif command == 0xEC then
+      self.duty = DUTY[bit.band(self:byte(), 3)] or 0.5
+    elseif command == 0xED then
+      self.engine.tempo = self:byte() * 0x100 + self:byte()
+    elseif command == 0xEE then
+      self.engine.pan = self:byte()
+    elseif command == 0xEF or command == 0xF0 then
+      self:byte()
+    elseif command == 0xF8 then
+      self.executeMusic = not self.executeMusic
+    elseif command == 0xFC then
+      local packed = self:byte()
+      self.duty = {
+        DUTY[bit.band(bit.rshift(packed, 6), 3)],
+        DUTY[bit.band(bit.rshift(packed, 4), 3)],
+        DUTY[bit.band(bit.rshift(packed, 2), 3)],
+        DUTY[bit.band(packed, 3)],
+      }
+    elseif command == 0xFD then
+      self.callStack[#self.callStack + 1] = self.address + 2
+      self.address = self:word()
+    elseif command == 0xFE then
+      local count, target = self:byte(), self:word()
+      if count == 0 then
+        if self.allowLoops then
+          self.address = target
+        else
+          self.ended = true
+          return nil
+        end
+      else
+        local remaining = self.loopCounts[commandAddress]
+        if remaining == nil then remaining = count end
+        remaining = remaining - 1
+        if remaining > 0 then
+          self.loopCounts[commandAddress] = remaining
+          self.address = target
+        else
+          self.loopCounts[commandAddress] = nil
+        end
+      end
+    elseif command == 0xFF then
+      local returnAddress = table.remove(self.callStack)
+      if returnAddress then
+        self.address = returnAddress
+      else
+        self.ended = true
+        return nil
+      end
+    elseif self.sfx and command >= 0x20 and command < 0x30 then
+      local length = bit.band(command, 0x0F) + 1
+      local packed = self:byte()
+      local volume = bit.rshift(packed, 4)
+      local fade = fadeValue(bit.band(packed, 0x0F))
+      if self.noise then
+        local parameter = self:byte()
+        return self:noiseEvent(
+          self:durationTicks(length), volume, fade, parameter)
+      end
+      local register = bit.band(self:word() + self.frequencyOffset, 0x7FF)
+      return self:tone(self:durationTicks(length), register, volume, fade)
+    elseif command == 0x10 then
+      local packed = self:byte()
+      self.sweep = {
+        pace = bit.band(bit.rshift(packed, 4), 7),
+        subtract = bit.band(packed, 8) ~= 0,
+        shift = bit.band(packed, 7),
+      }
+    else
+      self.ended = true
+      return nil
+    end
+  end
+  self.ended = true
+  return nil
+end
+
+local function envelopeVolume(volume, fade, elapsed)
+  if fade == 0 then return volume end
+  local steps = math.floor(elapsed / (math.abs(fade) / 64))
+  if fade > 0 then return math.max(0, volume - steps) end
+  return math.min(15, volume + steps)
+end
+
+function Channel:resetNoise()
+  self.noiseLfsr = 0x7FFF
+  self.noiseClock = 0
+end
+
+function Channel:clockNoise(width7)
+  local feedback = bit.bxor(
+    bit.band(self.noiseLfsr, 1),
+    bit.band(bit.rshift(self.noiseLfsr, 1), 1))
+  self.noiseLfsr = bit.bor(
+    bit.rshift(self.noiseLfsr, 1),
+    bit.lshift(feedback, 14))
+  if width7 then
+    self.noiseLfsr = bit.bor(
+      bit.band(self.noiseLfsr, bit.bnot(0x40)),
+      bit.lshift(feedback, 6))
+  end
+end
+
+function Channel:sampleNoise(parameter)
+  parameter = parameter or 0
+  local divisor = NOISE_DIVISORS[bit.band(parameter, 7)]
+  local shift = bit.rshift(parameter, 4)
+  local output = bit.band(self.noiseLfsr, 1) == 0 and 1 or -1
+  if shift >= 14 then return output end
+  local cycles = GB_CLOCK / divisor / (2 ^ shift) / SAMPLE_RATE
+  local width7 = bit.band(parameter, 8) ~= 0
+  local remaining = cycles
+  local area = 0
+
+  while remaining > 0 do
+    local untilClock = 1 - self.noiseClock
+    local span = math.min(remaining, untilClock)
+    output = bit.band(self.noiseLfsr, 1) == 0 and 1 or -1
+    area = area + output * span
+    self.noiseClock = self.noiseClock + span
+    remaining = remaining - span
+    if self.noiseClock >= 1 - 1e-12 then
+      self.noiseClock = 0
+      self:clockNoise(width7)
+    end
+  end
+
+  return area / cycles
+end
+
+local function sweepCalculation(register, sweep)
+  local delta = math.floor(register / (2 ^ sweep.shift))
+  if sweep.subtract then return register - delta end
+  return register + delta
+end
+
+local function sweptRegister(register, sweep, elapsed)
+  if not sweep or sweep.shift == 0 then return register end
+  local nextRegister = sweepCalculation(register, sweep)
+  if nextRegister > 0x7FF or nextRegister < 0 then return nil end
+  if sweep.pace == 0 then return register end
+
+  local iterations = math.floor(elapsed * 128 / sweep.pace)
+  for _ = 1, iterations do
+    register = nextRegister
+    nextRegister = sweepCalculation(register, sweep)
+    if nextRegister > 0x7FF or nextRegister < 0 then return nil end
+  end
+  return register
+end
+
+function Channel:sampleDrum(event, sampleIndex)
+  local index = event.drumSegmentIndex or 1
+  local segment = event.drum[index]
+  while segment and sampleIndex >= segment.endSample do
+    index = index + 1
+    segment = event.drum[index]
+  end
+  if not segment or sampleIndex < segment.startSample then return 0 end
+  if event.drumSegmentIndex ~= index then
+    event.drumSegmentIndex = index
+    self:resetNoise()
+  end
+  local elapsed = (sampleIndex - segment.startSample) / SAMPLE_RATE
+  local volume = envelopeVolume(segment.volume, segment.fade, elapsed)
+  return self:sampleNoise(segment.parameter) * volume / 15 * 0.35
+end
+
+function Channel:sample()
+  while not self.ended
+      and (not self.event or self.event.sample >= self.event.samples) do
+    self.event = self:nextEvent()
+    self.phase = 0
+    self:resetNoise()
+  end
+  local event = self.event
+  if not event then return 0 end
+  local sampleIndex = event.sample
+  event.elapsed = sampleIndex / SAMPLE_RATE
+  event.sample = sampleIndex + 1
+  if event.silence then return 0 end
+
+  if event.drum then return self:sampleDrum(event, sampleIndex) end
+  local volume = envelopeVolume(
+    event.volume or 0, event.fade or 0, event.elapsed)
+  if event.noise then
+    return self:sampleNoise(event.noiseParameter) * volume / 15 * 0.35
+  end
+
+  local register = event.register
+  local frame = math.floor(event.elapsed * 60)
+  if event.sweep then
+    register = sweptRegister(register, event.sweep, event.elapsed)
+    if not register then return 0 end
+  elseif event.slide then
+    local amount = math.min(1, frame / event.slide.frames)
+    register = register + (event.slide.target - register) * amount
+  elseif event.vibrato and frame >= event.vibrato.delay then
+    local vibrato = event.vibrato
+    local toggles = math.floor(
+      (frame - vibrato.delay + 1) / (vibrato.rate + 1))
+    if toggles > 0 then
+      local low = bit.band(register, 0xFF)
+      local high = bit.band(register, 0x700)
+      if bit.band(toggles, 1) ~= 0 then
+        register = high + math.min(0xFF, low + vibrato.above)
+      else
+        register = high + math.max(0, low - vibrato.below)
+      end
+    end
+  end
+  local frequency = 131072 / (2048 - math.min(register, 2047))
+  if event.wave then frequency = frequency * 0.5 end
+  local phase = self.phase
+  self.phase = (phase + frequency / SAMPLE_RATE) % 1
+  if event.wave then
+    local wave = self.engine.waves[
+      math.min(event.waveInstrument + 1, #self.engine.waves)]
+    -- a def-local program may omit its wave table entirely
+    if not wave then return 0 end
+    local index = math.min(32, math.floor(phase * 32) + 1)
+    return wave[index] * event.waveLevel * 0.55
+  end
+  local duty = event.duty
+  if type(duty) == "table" then
+    duty = duty[frame % 4 + 1]
+  end
+  return (phase < duty and 1 or -1) * volume / 15 * 0.5
+end
+
+local Engine = {}
+Engine.__index = Engine
+
+function Engine:noiseInstrument(number)
+  -- a def-local drum wins over the ROM engine's table for that id
+  local custom = self.customDrums and self.customDrums[number]
+  if custom then return custom end
+  local cached = self.noiseInstruments[number]
+  if cached then return cached end
+
+  local header = self.noiseHeaders[tostring(number)]
+  local segments = {}
+  if header then
+    local spec = headerChannels(self.banks, header)[1]
+    local address = spec and spec.address
+    local ticks = 0
+    for _ = 1, 64 do
+      local command = romByte(self.banks, header.bank, address)
+      address = address + 1
+      if command == 0xFF then break end
+      if command < 0x20 or command >= 0x30 then
+        error(("unsupported drum command %02X at %02X:%04X")
+          :format(command, header.bank, address - 1))
+      end
+      local packed = romByte(self.banks, header.bank, address)
+      local parameter = romByte(self.banks, header.bank, address + 1)
+      address = address + 2
+      local duration = (bit.band(command, 0x0F) + 1) * FRAME_TICKS
+      segments[#segments + 1] = {
+        startSample = snapTicks(ticks),
+        endSample = snapTicks(ticks + duration),
+        volume = bit.rshift(packed, 4),
+        fade = fadeValue(bit.band(packed, 0x0F)),
+        parameter = parameter,
+      }
+      ticks = ticks + duration
+    end
+  end
+
+  self.noiseInstruments[number] = segments
+  return segments
+end
+
+local function readWaves(banks, audio, engineNumber)
+  local spec = audio.waveBanks[tostring(engineNumber)]
+  local waves = {}
+  for wave = 0, 4 do
+    local values = {}
+    for byteIndex = 0, 15 do
+      local packed = romByte(
+        banks, spec.bank, spec.address + wave * 16 + byteIndex)
+      values[#values + 1] = (bit.rshift(packed, 4) - 7.5) / 7.5
+      values[#values + 1] = (bit.band(packed, 0x0F) - 7.5) / 7.5
+    end
+    waves[#waves + 1] = values
+  end
+  local values = {}
+  for byteIndex = 0, 15 do
+    local packed = romByte(
+      banks, spec.bank, spec.address + 5 * 16 + byteIndex)
+    values[#values + 1] = (bit.rshift(packed, 4) - 7.5) / 7.5
+    values[#values + 1] = (bit.band(packed, 0x0F) - 7.5) / 7.5
+  end
+  for _ = 1, 4 do waves[#waves + 1] = values end
+  return waves
+end
+
+-- def-local waves are authored either as raw 0-15 nibbles (the ROM's own
+-- units) or as the -1..1 samples readWaves produces; the synth wants the
+-- latter
+local function normalizeWaves(source)
+  local waves = {}
+  for index, values in ipairs(source) do
+    local nibbles = false
+    for _, value in ipairs(values) do
+      if value > 1 or value < -1 then nibbles = true break end
+    end
+    local wave = {}
+    for position, value in ipairs(values) do
+      wave[position] = nibbles and (value - 7.5) / 7.5 or value
+    end
+    waves[index] = wave
+  end
+  return waves
+end
+
+function Engine.new(data, header, options)
+  options = options or {}
+  local audio = data.audio or {}
+  -- shape dispatch: a def-local chip program supplies its own channels and
+  -- may supply its own waves/drums, falling back to a ROM engine's tables
+  local chip = header.chip
+  local banks = engineBanks(data, chip)
+  local engineNumber = chip and (chip.engine or 1) or header.engine
+  local waves
+  if chip and chip.waves then
+    waves = normalizeWaves(chip.waves)
+  elseif chip then
+    local ok, romWaves = pcall(readWaves, banks, audio, engineNumber)
+    waves = ok and romWaves or {}
+  else
+    waves = readWaves(banks, audio, engineNumber)
+  end
+  local engine = setmetatable({
+    banks = banks,
+    tempo = 0x100,
+    pan = 0xFF,
+    waves = waves,
+    noiseHeaders = audio.noiseHeaders
+      and audio.noiseHeaders[tostring(engineNumber)] or {},
+    customDrums = chip and chip.drums or nil,
+    noiseInstruments = {},
+    channels = {},
+  }, Engine)
+  for _, spec in ipairs(chip and chip.channels
+      or headerChannels(banks, header)) do
+    local frameTicks = options.frameTicks
+    local hardware = (spec.number - 1) % 4 + 1
+    if hardware == 4 then
+      frameTicks = FRAME_TICKS
+    elseif options.cryLength then
+      frameTicks = 0x80 + options.cryLength
+    end
+    engine.channels[#engine.channels + 1] = Channel.new(engine, spec, {
+      bank = chip and 0 or header.bank,
+      sfx = options.sfx,
+      allowLoops = options.allowLoops,
+      frequencyOffset = options.frequencyOffset,
+      frameTicks = frameTicks,
+    })
+  end
+  return engine
+end
+
+function Engine:finished()
+  for _, channel in ipairs(self.channels) do
+    if not channel.ended or channel.event then return false end
+  end
+  return true
+end
+
+function Engine:sample()
+  local value = 0
+  for _, channel in ipairs(self.channels) do value = value + channel:sample() end
+  return math.max(-1, math.min(1, value * 0.5))
+end
+
+function Engine:sampleStereo()
+  local left, right = 0, 0
+  for _, channel in ipairs(self.channels) do
+    local value = channel:sample()
+    local event = channel.event
+    if not event or event.panLeft ~= false then left = left + value end
+    if not event or event.panRight ~= false then right = right + value end
+  end
+  return math.max(-1, math.min(1, left * 0.5)),
+    math.max(-1, math.min(1, right * 0.5))
+end
+
+function Engine:sampleChannel(number)
+  local selected = 0
+  for _, channel in ipairs(self.channels) do
+    local value = channel:sample()
+    if channel.number == number then selected = value end
+  end
+  return math.max(-1, math.min(1, selected * 0.5))
+end
+
+-- render `samples` frames into a fresh SoundData (mono or stereo).  love.sound
+-- is available on worker threads, so this is the hand-off unit the worker
+-- produces and the main thread queues.
+local function soundData(engine, samples, channels)
+  local result = love.sound.newSoundData(samples, SAMPLE_RATE, 16, channels)
+  for index = 0, samples - 1 do
+    if channels == 2 then
+      local left, right = engine:sampleStereo()
+      result:setSample(index, 1, left)
+      result:setSample(index, 2, right)
+    else
+      result:setSample(index, engine:sample())
+    end
+  end
+  return result
+end
+
+-- Render a one-shot effect (SFX/cry) to a mono SoundData, or nil when it is
+-- too short to be audible.  The caller wraps it in a static love.audio.Source
+-- (a playback concern, hence not done here).
+local function renderEffectData(data, header, options)
+  if not header then return nil end
+  options = options or {}
+  options.sfx = true
+  options.allowLoops = false
+  local engine = Engine.new(data, header, options)
+  local maximum = SAMPLE_RATE * 5
+  local values = {}
+  local count = 0
+  while count < maximum and not engine:finished() do
+    count = count + 1
+    values[count] = engine:sample()
+  end
+  if count < math.floor(SAMPLE_RATE / 100) then return nil end
+  local result = love.sound.newSoundData(count, SAMPLE_RATE, 16, 1)
+  for index = 1, count do result:setSample(index - 1, values[index]) end
+  return result
+end
+
+ChipSynth.newEngine = Engine.new
+ChipSynth.soundData = soundData
+ChipSynth.renderEffectData = renderEffectData
+
+return ChipSynth

src/core/Data.lua

@@ -41,7 +41,11 @@ local CONSTANT_DEFAULTS = {
 -- field.boot is the total-conversion override point for the new game; the
 -- values match what SaveData.newGame and the Oak speech used to inline.
 local BOOT_DEFAULTS = {
-  startMap = "PALLET_TOWN", startX = 5, startY = 6, startFacing = "down",
+  -- special_warps.asm NewGameWarp: REDS_HOUSE_2F, 3, 6 -- the bedroom, not
+  -- the tile outside the house. lastHeal is deliberately absent: SaveData
+  -- derives the vanilla blackout point, and seeding it here would leak into
+  -- total conversions that patch the spawn without naming a heal point.
+  startMap = "REDS_HOUSE_2F", startX = 3, startY = 6, startFacing = "down",
   playerName = "RED", rivalName = "BLUE",
   startMoney = 3000,
   screens = { splash = "IntroMovie", title = "TitleState", newGame = "OakSpeech" },
@@ -93,6 +97,63 @@ function Data:seedDefaults()
   -- the overworld's Kanto literals, same fill-if-absent contract; required
   -- here rather than at the top so core keeps out of src/world at load time
   require("src.world.FieldDefaults").seed(self)
+  -- Cinnabar's quiz trainers are text_asm (no def_trainers), so the
+  -- extractor never writes headers for them.  Seed the EVENT_BEAT_* /
+  -- after-battle rows so Blaine's SetEventRange deactivation and talk
+  -- after-text work like the other gyms (scripts/CinnabarGym.asm).
+  self:seedCinnabarGymTrainerHeaders()
+  -- #197: the Fighting Dojo Karate Master is text_asm, so the extractor
+  -- writes no header for him -- seed one so he engages on sight and has
+  -- his defeat / re-talk lines (same idea as the Cinnabar seed above).
+  self:seedFightingDojoKarateMaster()
+  -- #189: 1F cabin door order vs rooms map (survey zoom)
+  require("src.world.SsAnneLayout").apply(self.maps)
+end
+
+-- The Karate Master (FightingDojo.asm) is a text_asm object: his object has
+-- no def_trainers row (DisplayTextID routes to his ASM script), so the
+-- extractor emits headers only for the four blackbelts ([2]..[5]).  Seed
+-- object index [1] so he behaves like the real leader:
+--   * range 4 (matches the strongest blackbelt) -> CheckFightingMapTrainers
+--     spots the player in his DOWN line and he challenges on sight (#197),
+--   * battle = his pre-battle challenge, won = "Hwa! Arrgh! Beaten!",
+--   * after = the "Stay and train at Karate with us!" re-talk line.
+-- Deliberately NO `event`: EVENT_BEAT_KARATE_MASTER is owned by
+-- victories.lua (OPP_BLACKBELT#1) exactly like the gym leaders, and
+-- engageTrainer sets header.event *before* checkVictoryRewards runs -- if
+-- this header also set it, the reward's flag guard would early-return and
+-- swallow the prize dialogue.  trainerDefeated tracks him via
+-- defeatedTrainers[npc.id] like the leaders.
+function Data:seedFightingDojoKarateMaster()
+  local headers = self.trainer_headers
+  if not headers then return end
+  headers.FightingDojo = headers.FightingDojo or {}
+  if headers.FightingDojo[1] then return end
+  headers.FightingDojo[1] = {
+    range = 4,
+    battle = "_FightingDojoKarateMasterText",
+    won = "_FightingDojoKarateMasterDefeatedText",
+    after = "_FightingDojoKarateMasterStayAndTrainWithUsText",
+  }
+end
+
+function Data:seedCinnabarGymTrainerHeaders()
+  local headers = self.trainer_headers
+  if not headers or headers.CinnabarGym then return end
+  local gym = {}
+  for i = 0, 6 do
+    local n = i + 1
+    -- object indices 2..8 are SUPER_NERD1..7; range 0 -- they only
+    -- engage via talk / wrong quiz answer, never sight lines
+    gym[i + 2] = {
+      event = "EVENT_BEAT_CINNABAR_GYM_TRAINER_" .. i,
+      range = 0,
+      battle = "_CinnabarGymSuperNerd" .. n .. "BattleText",
+      won = "_CinnabarGymSuperNerd" .. n .. "EndBattleText",
+      after = "_CinnabarGymSuperNerd" .. n .. "AfterBattleText",
+    }
+  end
+  headers.CinnabarGym = gym
 end
 
 -- POKEPORT_DATA_DIR points a test runner at another dataset root (the

src/core/DiscordPresence.lua

@@ -0,0 +1,789 @@
+-- Discord Rich Presence via the local Discord IPC pipe.  Shows the player's
+-- current map (and battle status) on their Discord profile.  Desktop only;
+-- no-ops on mobile, headless runs, or when Discord is not running.
+--
+-- Application ID is the only credential needed for presence.  The Discord
+-- Interactions public key is unused here (that is for verifying bot HTTP
+-- payloads, not Rich Presence).
+
+local Json = require("src.link.Json")
+local Logger = require("src.core.Logger")
+local Runtime = require("src.mods.Runtime")
+local Strings = require("src.core.Strings")
+
+local DiscordPresence = {
+  APP_ID = "1529183141267374262",
+}
+
+local OP_HANDSHAKE, OP_FRAME, OP_CLOSE = 0, 1, 2
+
+local MIN_UPDATE_INTERVAL = 2.0
+local RECONNECT_INTERVAL = 30.0
+
+local state = {
+  enabled = false,
+  connected = false,
+  socket = nil,       -- Windows: file handle; Unix: ffi sockfd
+  isWindows = false,
+  ffi = nil,
+  ffiReady = false,
+  startedAt = 0,
+  dirty = false,
+  lastSentKey = nil,
+  lastSendAt = -1e9,
+  nextReconnectAt = 0,
+  location = nil,     -- display name
+  mapId = nil,
+  activity = "menu",  -- menu | exploring | battle
+  battleLabel = nil,
+  unsubs = {},
+  pid = nil,
+  loggedAbsent = false, -- one quiet note when Discord isn't running
+  game = nil,          -- kept for the "friend clicked join" -> push a screen path
+  joinCode = nil,       -- the online-match/tournament code to advertise as a join secret, if any
+  joinKind = "match",   -- "match" (LinkState online) or "tournament"
+  partySize = 1,        -- current headcount for the party.size Discord shows
+  partyMax = 2,
+  subscribedJoin = false, -- SUBSCRIBE ACTIVITY_JOIN sent on this connection?
+}
+
+-- MSG_DONTWAIT differs by OS (Darwin 0x80, Linux 0x40); only used for the
+-- ongoing per-frame inbound poll, never for the one-time connect/handshake
+local MSG_DONTWAIT_BY_OS = { ["OS X"] = 0x80, Linux = 0x40 }
+
+local function disabledByEnv()
+  return os.getenv("POKEPORT_NO_DISCORD") == "1"
+      or os.getenv("POKEPORT_AUTOPILOT") ~= nil
+      or os.getenv("POKEPORT_DRIVER") ~= nil
+end
+
+local function isDesktop()
+  if not love or not love.system or not love.system.getOS then return false end
+  local osName = love.system.getOS()
+  return osName == "OS X" or osName == "Windows" or osName == "Linux"
+end
+
+local function packU32(n)
+  n = math.floor(n) % 0x100000000
+  local b1 = n % 256; n = math.floor(n / 256)
+  local b2 = n % 256; n = math.floor(n / 256)
+  local b3 = n % 256; n = math.floor(n / 256)
+  local b4 = n % 256
+  return string.char(b1, b2, b3, b4)
+end
+
+local function unpackU32(s)
+  local b1, b2, b3, b4 = s:byte(1, 4)
+  return b1 + b2 * 256 + b3 * 65536 + b4 * 16777216
+end
+
+local function nonce()
+  return string.format("%08x-%04x-4%03x-%04x-%04x%08x",
+    math.random(0, 0xffffffff),
+    math.random(0, 0xffff),
+    math.random(0, 0xfff),
+    math.random(0, 0x3fff) + 0x8000,
+    math.random(0, 0xffff),
+    math.random(0, 0xffffffff))
+end
+
+local function resolvePid()
+  if state.pid then return state.pid end
+  local ffi = state.ffi
+  if ffi then
+    if state.isWindows then
+      pcall(ffi.cdef, "unsigned long GetCurrentProcessId(void);")
+      local ok, p = pcall(function() return ffi.C.GetCurrentProcessId() end)
+      if ok and p and tonumber(p) and tonumber(p) > 0 then
+        state.pid = tonumber(p)
+        return state.pid
+      end
+    else
+      pcall(ffi.cdef, "int getpid(void);")
+      local ok, p = pcall(function() return ffi.C.getpid() end)
+      if ok and p and tonumber(p) and tonumber(p) > 0 then
+        state.pid = tonumber(p)
+        return state.pid
+      end
+    end
+  end
+  state.pid = 1000 + math.random(1, 8999)
+  return state.pid
+end
+
+local function ensureFfi()
+  if state.ffiReady then return state.ffi end
+  if state.ffi == false then return nil end
+  local ok, ffi = pcall(require, "ffi")
+  if not ok or not ffi then
+    state.ffi = false
+    return nil
+  end
+  state.ffi = ffi
+  if state.isWindows then
+    state.ffiReady = true
+    return ffi
+  end
+  -- Darwin sockaddr_un has sun_len + uint8_t family; Linux uses u16 family.
+  local osName = love.system.getOS()
+  local cdef
+  if osName == "OS X" then
+    cdef = [[
+      typedef unsigned int socklen_t;
+      typedef int ssize_t;
+      struct sockaddr_un {
+        uint8_t sun_len;
+        uint8_t sun_family;
+        char sun_path[104];
+      };
+      struct timeval { long tv_sec; int tv_usec; };
+      int socket(int domain, int type, int protocol);
+      int connect(int sockfd, const void *addr, socklen_t addrlen);
+      int setsockopt(int sockfd, int level, int optname, const void *optval, socklen_t optlen);
+      ssize_t send(int sockfd, const void *buf, size_t len, int flags);
+      ssize_t recv(int sockfd, void *buf, size_t len, int flags);
+      int close(int fd);
+    ]]
+  else
+    cdef = [[
+      typedef unsigned int socklen_t;
+      typedef int ssize_t;
+      struct sockaddr_un {
+        unsigned short sun_family;
+        char sun_path[108];
+      };
+      struct timeval { long tv_sec; long tv_usec; };
+      int socket(int domain, int type, int protocol);
+      int connect(int sockfd, const void *addr, socklen_t addrlen);
+      int setsockopt(int sockfd, int level, int optname, const void *optval, socklen_t optlen);
+      ssize_t send(int sockfd, const void *buf, size_t len, int flags);
+      ssize_t recv(int sockfd, void *buf, size_t len, int flags);
+      int close(int fd);
+    ]]
+  end
+  -- cdef may already be registered from a prior boot; either way we need
+  -- sockaddr_un usable before claiming readiness
+  pcall(ffi.cdef, cdef)
+  local ready = pcall(function() return ffi.new("struct sockaddr_un") end)
+  if not ready then
+    state.ffi = false
+    state.ffiReady = false
+    return nil
+  end
+  state.ffiReady = true
+  return ffi
+end
+
+local function closeSocket()
+  local sock = state.socket
+  state.socket = nil
+  state.connected = false
+  if not sock then return end
+  if state.isWindows then
+    pcall(function() sock:close() end)
+  elseif state.ffi then
+    pcall(state.ffi.C.close, sock)
+  end
+end
+
+local function writeRaw(bytes)
+  if not state.socket then return false end
+  if state.isWindows then
+    local ok = pcall(function()
+      state.socket:seek("end")
+      local _, writeErr = state.socket:write(bytes)
+      state.socket:flush()
+      if writeErr then error(writeErr) end
+    end)
+    return ok
+  end
+  local ffi = state.ffi
+  if not ffi then return false end
+  local ok, sent = pcall(ffi.C.send, state.socket, bytes, #bytes, 0)
+  return ok and sent == #bytes
+end
+
+local function sendFrame(opcode, payload)
+  local body = payload or ""
+  local ok, frame = pcall(function()
+    return packU32(opcode) .. packU32(#body) .. body
+  end)
+  if not ok or not frame then return false end
+  return writeRaw(frame)
+end
+
+local function readExact(n)
+  if not state.socket or n <= 0 then return nil end
+  if state.isWindows then
+    local ok, data = pcall(function() return state.socket:read(n) end)
+    if not ok or not data or #data < n then return nil end
+    return data
+  end
+  local ffi = state.ffi
+  if not ffi then return nil end
+  local ok, data = pcall(function()
+    local buf = ffi.new("char[?]", n)
+    local got = 0
+    while got < n do
+      local nread = ffi.C.recv(state.socket, buf + got, n - got, 0)
+      if not nread or nread <= 0 then return nil end
+      got = got + tonumber(nread)
+    end
+    return ffi.string(buf, n)
+  end)
+  if not ok then return nil end
+  return data
+end
+
+local function receiveFrame()
+  local header = readExact(8)
+  if not header then return nil end
+  local ok, opcode, length = pcall(function()
+    return unpackU32(header:sub(1, 4)), unpackU32(header:sub(5, 8))
+  end)
+  if not ok or not opcode or not length or length < 0 or length > 65536 then
+    return nil
+  end
+  local data = length > 0 and readExact(length) or ""
+  if data == nil then return nil end
+  return opcode, data
+end
+
+local function unixSocketPaths()
+  local paths = {}
+  local envs = { "XDG_RUNTIME_DIR", "TMPDIR", "TMP", "TEMP" }
+  local bases = {}
+  for _, key in ipairs(envs) do
+    local v = os.getenv(key)
+    if v and v ~= "" then
+      if v:sub(-1) == "/" then v = v:sub(1, -2) end
+      bases[#bases + 1] = v
+    end
+  end
+  bases[#bases + 1] = "/tmp"
+  local suffixes = {
+    "",
+    "/app/com.discordapp.Discord",
+    "/app/com.discordapp.DiscordCanary",
+    "/app/com.discordapp.DiscordPTB",
+    "/snap.discord",
+    "/snap.discord-canary",
+  }
+  local seen = {}
+  for i = 0, 9 do
+    local name = "discord-ipc-" .. i
+    for _, base in ipairs(bases) do
+      for _, suffix in ipairs(suffixes) do
+        local path = base .. suffix .. "/" .. name
+        if not seen[path] then
+          seen[path] = true
+          paths[#paths + 1] = path
+        end
+      end
+    end
+  end
+  return paths
+end
+
+local function setSocketTimeout(fd, seconds)
+  local ffi = state.ffi
+  if not ffi or not fd then return end
+  pcall(function()
+    local tv = ffi.new("struct timeval")
+    tv.tv_sec = seconds
+    tv.tv_usec = 0
+    -- SOL_SOCKET / SO_RCVTIMEO / SO_SNDTIMEO differ by OS
+    local sol, rcv, snd
+    if love.system.getOS() == "OS X" then
+      sol, rcv, snd = 0xffff, 0x1006, 0x1005
+    else
+      sol, rcv, snd = 1, 20, 21
+    end
+    ffi.C.setsockopt(fd, sol, rcv, tv, ffi.sizeof(tv))
+    ffi.C.setsockopt(fd, sol, snd, tv, ffi.sizeof(tv))
+  end)
+end
+
+local function connectUnix()
+  local ffi = ensureFfi()
+  if not ffi then return false end
+  local darwin = love.system.getOS() == "OS X"
+  local maxPath = darwin and 103 or 107
+  -- AF_UNIX=1, SOCK_STREAM=1 on Linux/macOS
+  local pathsOk, paths = pcall(unixSocketPaths)
+  if not pathsOk or not paths then return false end
+  for _, path in ipairs(paths) do
+    if #path <= maxPath then
+      local ok, connected = pcall(function()
+        local fd = ffi.C.socket(1, 1, 0)
+        if not fd or fd < 0 then return false end
+        local addr = ffi.new("struct sockaddr_un")
+        addr.sun_family = 1
+        if darwin then
+          -- SUN_LEN: sizeof(sun_len+sun_family) + path + NUL
+          addr.sun_len = 2 + #path + 1
+        end
+        ffi.copy(addr.sun_path, path)
+        local rc = ffi.C.connect(fd, ffi.cast("void*", addr), ffi.sizeof(addr))
+        if rc == 0 then
+          setSocketTimeout(fd, 1) -- handshake must not freeze the game
+          state.socket = fd
+          return true
+        end
+        ffi.C.close(fd)
+        return false
+      end)
+      if ok and connected then return true end
+    end
+  end
+  return false
+end
+
+local function connectWindows()
+  for i = 0, 9 do
+    local path = "\\\\.\\pipe\\discord-ipc-" .. i
+    local ok, file = pcall(io.open, path, "r+")
+    if ok and file then
+      state.socket = file
+      return true
+    end
+  end
+  return false
+end
+
+local function handshake()
+  local ok, payload = pcall(Json.encode, { v = 1, client_id = DiscordPresence.APP_ID })
+  if not ok or not payload then return false end
+  if not sendFrame(OP_HANDSHAKE, payload) then return false end
+  -- Discord echoes READY as a FRAME.  A timeout/missing client is a soft miss.
+  local opcode = receiveFrame()
+  if opcode == OP_FRAME then return true end
+  -- Windows named pipes have no easy read timeout: if the write succeeded
+  -- and Discord is present, proceed optimistically so boot never blocks.
+  if state.isWindows then return true end
+  return false
+end
+
+local function noteAbsent()
+  if state.loggedAbsent then return end
+  state.loggedAbsent = true
+  -- info, not warn: missing Discord is normal for many players
+  Logger.info("discord: rich presence unavailable (Discord not running)")
+end
+
+local function connect()
+  local ok, result = pcall(function()
+    closeSocket()
+    local linked
+    if state.isWindows then
+      linked = connectWindows()
+    else
+      linked = connectUnix()
+    end
+    if not linked then return false end
+    if not handshake() then
+      closeSocket()
+      return false
+    end
+    state.connected = true
+    state.dirty = true
+    state.lastSentKey = nil
+    state.loggedAbsent = false
+    state.subscribedJoin = false
+    -- ask for "friend clicked join" dispatches; a plain outbound write, so
+    -- it's harmless to send even on Windows, where the inbound poll below
+    -- isn't implemented yet (see pollJoinRequest)
+    if sendFrame(OP_FRAME, Json.encode({
+      cmd = "SUBSCRIBE", evt = "ACTIVITY_JOIN", nonce = nonce(),
+    })) then
+      state.subscribedJoin = true
+    end
+    Logger.info("discord: rich presence connected")
+    return true
+  end)
+  if not ok then
+    closeSocket()
+    return false
+  end
+  return result and true or false
+end
+
+local function locationName(game, mapId)
+  if not mapId then return nil end
+  local field = game and game.data and game.data.field
+  local townMap = field and field.townMap
+  local locations = townMap and (townMap.locations or townMap)
+  local entry = type(locations) == "table" and locations[mapId]
+  if type(entry) == "table" then
+    local name = entry.name or entry.label
+    if type(name) == "string" and name ~= "" then return name end
+  end
+  local def = game and game.data and game.data.maps and game.data.maps[mapId]
+  if def and type(def.label) == "string" and def.label ~= "" then
+    -- PalletTown -> Pallet Town
+    return def.label:gsub("(%l)(%u)", "%1 %2")
+  end
+  return tostring(mapId):gsub("_", " ")
+end
+
+local function speciesName(game, species)
+  if not species or not game or not game.data or not game.data.pokemon then
+    return nil
+  end
+  local def = game.data.pokemon[species]
+  return def and def.name or tostring(species):gsub("_", " ")
+end
+
+local function buildActivity()
+  local details, activityState
+  if state.activity == "battle" then
+    details = state.battleLabel or Strings("In battle")
+    activityState = state.location and (state.location) or "Kanto"
+  elseif state.activity == "exploring" and state.location then
+    details = state.location
+    activityState = "Exploring the overworld"
+  else
+    details = state.location or "Kanto"
+    activityState = "At the title screen"
+  end
+
+  local activity = {
+    details = details,
+    state = activityState,
+    timestamps = { start = state.startedAt },
+    assets = {
+      large_image = "logo",
+      large_text = "Pokemon Gen1Recomp",
+    },
+  }
+  -- a party/join-secret pair is what makes Discord show "Ask to Join" on
+  -- the profile card; the secret carries our own room/tournament code plus
+  -- a one-letter kind tag ("m"/"t") so the click handler on the other end
+  -- knows which screen to jump into -- Discord only echoes the string
+  -- back, so the kind has to ride inside it
+  if state.joinCode then
+    local kindTag = state.joinKind == "tournament" and "t" or "m"
+    activity.party = { id = "pokeport-" .. state.joinCode,
+                       size = { state.partySize, state.partyMax } }
+    activity.secrets = { join = "join:" .. kindTag .. ":" .. state.joinCode }
+  end
+  return activity
+end
+
+local function activityKey(activity)
+  local partyKey = activity.party
+    and (activity.party.size[1] .. "/" .. activity.party.size[2]) or ""
+  return (activity.details or "") .. "|" .. (activity.state or "") .. "|"
+    .. (activity.secrets and activity.secrets.join or "") .. "|" .. partyKey
+end
+
+local function flush(force)
+  if not state.enabled or not state.connected then return end
+  local ok = pcall(function()
+    local now = love.timer.getTime()
+    if not force and (now - state.lastSendAt) < MIN_UPDATE_INTERVAL then
+      state.dirty = true
+      return
+    end
+    local activity = buildActivity()
+    local key = activityKey(activity)
+    if not force and key == state.lastSentKey then
+      state.dirty = false
+      return
+    end
+    local payload = Json.encode({
+      cmd = "SET_ACTIVITY",
+      args = {
+        pid = resolvePid(),
+        activity = activity,
+      },
+      nonce = nonce(),
+    })
+    if not sendFrame(OP_FRAME, payload) then
+      closeSocket()
+      state.nextReconnectAt = now + RECONNECT_INTERVAL
+      return
+    end
+    state.lastSentKey = key
+    state.lastSendAt = now
+    state.dirty = false
+  end)
+  if not ok then
+    closeSocket()
+    local now = love and love.timer and love.timer.getTime and love.timer.getTime() or 0
+    state.nextReconnectAt = now + RECONNECT_INTERVAL
+  end
+end
+
+local function setPresence(fields)
+  -- event listeners must never throw into the overworld/battle path
+  pcall(function()
+    if fields.location ~= nil then state.location = fields.location end
+    if fields.mapId ~= nil then state.mapId = fields.mapId end
+    if fields.activity ~= nil then state.activity = fields.activity end
+    if fields.clearBattle then
+      state.battleLabel = nil
+    elseif fields.battleLabel ~= nil then
+      state.battleLabel = fields.battleLabel
+    end
+    state.dirty = true
+    flush(false)
+  end)
+end
+
+local function subscribe(game)
+  local events = Runtime.events
+  if not events or not events.on then return end
+
+  local function track(name, fn)
+    state.unsubs[#state.unsubs + 1] = events:on(name, fn, 0, "discord")
+  end
+
+  track("map.entered", function(ev)
+    local mapId = ev and ev.mapId
+    setPresence({
+      mapId = mapId,
+      location = locationName(game, mapId),
+      activity = "exploring",
+      clearBattle = true,
+    })
+  end)
+
+  track("battle.started", function(ev)
+    local battle = ev and ev.battle
+    local label = Strings("In battle")
+    if ev and ev.kind == "wild" then
+      local name = speciesName(game, ev.species)
+      if name then
+        label = "Battling wild " .. name
+        if ev.level then label = label .. " Lv" .. tostring(ev.level) end
+      else
+        label = Strings("Wild battle")
+      end
+    elseif ev and ev.kind == "trainer" then
+      local tname = battle and battle.trainer and battle.trainer.name
+      label = tname and ("Battling " .. tname) or Strings("Trainer battle")
+    elseif ev and ev.kind == "link" then
+      label = Strings("Link battle")
+    end
+    local mapId = state.mapId
+      or (game.save and game.save.player and game.save.player.map)
+    setPresence({
+      activity = "battle",
+      battleLabel = label,
+      location = locationName(game, mapId) or state.location,
+      mapId = mapId,
+    })
+  end)
+
+  track("battle.ended", function()
+    local mapId = state.mapId
+      or (game.save and game.save.player and game.save.player.map)
+    setPresence({
+      activity = mapId and "exploring" or "menu",
+      clearBattle = true,
+      location = locationName(game, mapId) or state.location,
+      mapId = mapId,
+    })
+  end)
+
+  track("screen.pushed", function(ev)
+    local s = ev and ev.state
+    local id = s and s.screenId
+    if not id and s and s.onNewGame then id = "TitleState" end
+    if id == "TitleState" or id == "IntroMovie" then
+      state.mapId = nil
+      setPresence({
+        activity = "menu",
+        location = id == "IntroMovie" and "Watching the intro" or Strings("Title screen"),
+        clearBattle = true,
+      })
+    end
+  end)
+end
+
+-- Advertise (or clear, with code=nil) an online-match/tournament code as a
+-- Discord join secret. LinkState/Tournament call this once they have a
+-- real code from the relay, and clear it again once paired/started or the
+-- hosting screen exits (an invite that's already full or gone is worse
+-- than no invite). kind is "match" (default) or "tournament"; size/max are
+-- the party.size Discord shows (default 1/2, a plain 1v1 room) -- a
+-- tournament passes its live roster count and a generous cap instead, and
+-- should call this again whenever the roster changes, not just once.
+function DiscordPresence.setJoinCode(code, kind, size, max)
+  pcall(function()
+    state.joinCode = code
+    state.joinKind = kind or "match"
+    state.partySize = size or 1
+    state.partyMax = max or 2
+    state.dirty = true
+    flush(false)
+  end)
+end
+
+-- A friend clicked "Ask to Join" on our profile and Discord delivered the
+-- secret back over this same connection. Only act from a safe spot (never
+-- yank the player out of a battle or an already-running link session) --
+-- "exploring"/"menu" are the coarse buckets subscribe() above already
+-- tracks; anything more specific (a shop, a dialogue box) is a rarer miss
+-- worth accepting rather than adding a second, finer-grained state tracker
+-- just for this.
+local function handleJoinRequest(secret)
+  if not secret or secret == "" then return end
+  if state.activity == "battle" then return end
+  local game = state.game
+  if not game or not game.stack then return end
+  local top = game.stack:top()
+  if top and top.stage and top.net then return end -- already in a link session
+  local kindTag, code = secret:match("^(%a):(.+)$")
+  if not kindTag then kindTag, code = "m", secret end -- older/plain secret: assume match
+  Runtime.emit("discord.join_requested", { code = code, kind = kindTag })
+  if kindTag == "t" then
+    local ok, Tournament = pcall(require, "src.link.Tournament")
+    if ok and Tournament.newJoinOnline then
+      game.stack:push(Tournament.newJoinOnline(game, code))
+    end
+  else
+    local ok, LinkState = pcall(require, "src.link.LinkState")
+    if ok and LinkState.newJoinOnline then
+      game.stack:push(LinkState.newJoinOnline(game, code))
+    end
+  end
+end
+
+-- non-blocking peek for an incoming ACTIVITY_JOIN dispatch. Unix (FFI)
+-- only for now: reading a Windows named pipe without risking a stall needs
+-- a HANDLE-level PeekNamedPipe that the plain io.open() connection below
+-- doesn't give us, so a Windows player's presence/party/join-secret still
+-- all work (they can still be seen and clicked), the click just isn't
+-- delivered back to their own game session yet.
+local function pollJoinRequest()
+  if state.isWindows or not state.ffi or not state.socket or not state.subscribedJoin then
+    return
+  end
+  pcall(function()
+    local ffi = state.ffi
+    local dontwait = MSG_DONTWAIT_BY_OS[love.system.getOS()] or 0
+    local hbuf = ffi.new("char[8]")
+    local n = ffi.C.recv(state.socket, hbuf, 8, dontwait)
+    if not n or tonumber(n) <= 0 then return end -- nothing waiting right now
+    local header = ffi.string(hbuf, 8)
+    local opcode = unpackU32(header:sub(1, 4))
+    local length = unpackU32(header:sub(5, 8))
+    if not opcode or not length or length < 0 or length > 65536 then return end
+    -- the body may lag the header by a packet; the connection's normal
+    -- (short-timeout) blocking read is fine here since it has already
+    -- announced its exact length
+    local body = length > 0 and readExact(length) or ""
+    if body == nil then return end
+    if opcode == 3 then -- PING -> PONG, keeps Discord from closing on us
+      sendFrame(4, body)
+      return
+    end
+    if opcode ~= 1 then return end
+    local decoded = Json.decode(body)
+    if decoded and decoded.evt == "ACTIVITY_JOIN" then
+      local secret = decoded.data and decoded.data.secret
+      if type(secret) == "string" and secret ~= "" then
+        if secret:sub(1, 5) == "join:" then secret = secret:sub(6) end
+        handleJoinRequest(secret)
+      end
+    end
+  end)
+end
+
+function DiscordPresence.init(game)
+  local ok, err = pcall(function()
+    DiscordPresence.shutdown()
+    if disabledByEnv() or not isDesktop() then return end
+
+    state.enabled = true
+    state.isWindows = love.system.getOS() == "Windows"
+    state.startedAt = os.time()
+    state.activity = "menu"
+    state.location = "Title screen"
+    state.mapId = nil
+    state.battleLabel = nil
+    state.joinCode = nil
+    state.game = game
+    state.dirty = true
+    state.nextReconnectAt = 0
+    state.loggedAbsent = false
+
+    if not state.isWindows and not ensureFfi() then
+      -- no FFI / broken cdef: stay disabled, never throw
+      state.enabled = false
+      return
+    end
+
+    subscribe(game)
+    if connect() then
+      flush(true)
+    else
+      noteAbsent()
+      local now = (love.timer and love.timer.getTime and love.timer.getTime()) or 0
+      state.nextReconnectAt = now + RECONNECT_INTERVAL
+    end
+  end)
+  if not ok then
+    closeSocket()
+    state.enabled = false
+    -- still soft: a broken presence stack must not abort boot
+    Logger.info("discord: rich presence disabled (%s)", tostring(err))
+  end
+end
+
+function DiscordPresence.update(_dt)
+  if not state.enabled then return end
+  pcall(function()
+    local now = love.timer.getTime()
+    if not state.connected then
+      if now >= state.nextReconnectAt then
+        state.nextReconnectAt = now + RECONNECT_INTERVAL
+        if connect() then
+          flush(true)
+        else
+          noteAbsent()
+        end
+      end
+      return
+    end
+    pollJoinRequest()
+    if state.dirty then flush(false) end
+  end)
+end
+
+function DiscordPresence.shutdown()
+  pcall(function()
+    for _, unsub in ipairs(state.unsubs) do
+      pcall(unsub)
+    end
+    state.unsubs = {}
+    if state.connected then
+      pcall(function()
+        -- omit activity to clear the presence
+        sendFrame(OP_FRAME, Json.encode({
+          cmd = "SET_ACTIVITY",
+          args = { pid = resolvePid() },
+          nonce = nonce(),
+        }))
+        sendFrame(OP_CLOSE, "{}")
+      end)
+    end
+    closeSocket()
+  end)
+  state.enabled = false
+  state.dirty = false
+  state.lastSentKey = nil
+  state.connected = false
+  state.socket = nil
+  state.subscribedJoin = false
+  state.joinCode = nil
+end
+
+-- test / debug helpers
+DiscordPresence._state = state
+DiscordPresence.locationName = locationName
+DiscordPresence.handleJoinRequest = handleJoinRequest
+
+return DiscordPresence

src/core/FixedStep.lua

@@ -12,12 +12,27 @@ function FixedStep:init(callback)
   self.callback = callback
 end
 
+-- The anti-spiral clamp doubles as a steps-per-frame ceiling (0.25s = 15
+-- steps), which silently throttled the high fast-forward levels: at 100X
+-- a 60fps frame wants ~100 steps. Game:update raises this to fit the
+-- current speed target; a stall still cannot snowball past one frame's
+-- intended budget.
+FixedStep.maxAccum = MAX_ACCUM
+
 function FixedStep:update(dt)
-  self.accum = math.min(self.accum + dt, MAX_ACCUM)
+  self.accum = math.min(self.accum + dt, self.maxAccum or MAX_ACCUM)
   while self.accum >= self.STEP do
     self.accum = self.accum - self.STEP
     self.callback(self.STEP)
   end
 end
 
+-- Drop any pending catch-up steps.  A hitch inside one logic step (map
+-- seam setMap / song start) makes the next real-time dt huge; without this
+-- the while-loop above would advance many walk frames before the next
+-- draw, which looks like a slide with no leg animation (issue #93).
+function FixedStep:discardCatchup()
+  self.accum = 0
+end
+
 return FixedStep

src/core/FrameCap.lua

@@ -0,0 +1,72 @@
+-- Render frame-rate cap.  With a driver control panel forcing
+-- vsync off, the 160x144 game is trivially cheap and love.run will present
+-- thousands of frames a second; over hours that cooks the graphics driver
+-- until a restart, and it wastes power whenever the window is left open in
+-- the background.  A hard cap bounds the present rate.  Render-only: game
+-- logic is fixed-step off dt (src/core/FixedStep.lua), so pacing present()
+-- changes nothing about timing, audio, or determinism.
+--
+-- Persisted as save.options.fpsCap; applied from OptionsMenu and on boot
+-- via Game:applyOptions.  main.lua's love.run reads FrameCap.current each
+-- frame for its sleep budget.  The module never touches love.timer itself,
+-- so it stays safe under the headless test stub.
+
+local FrameCap = {}
+
+-- Selectable steps: the normal framerate stops between the floor and the
+-- ceiling.  STEPS[1] == MIN and STEPS[#STEPS] == MAX, so the nearest-step
+-- snap in normalize doubles as the clamp.  Cycling past the last wraps.
+FrameCap.STEPS = { 30, 40, 50, 60, 75, 90, 100, 120, 144, 160 }
+FrameCap.MIN = 30
+FrameCap.MAX = 160
+FrameCap.DEFAULT = 60
+
+-- The live cap the run loop paces to.  Defaults so the launcher and the
+-- save editor are paced before any save applies its stored option.
+FrameCap.current = FrameCap.DEFAULT
+
+-- Nearest valid step for an arbitrary value (a hand-edited options.lua or
+-- an old save with no fpsCap key), so a bad number degrades to something
+-- sane; nil / non-numbers fall back to the default.  A value below MIN or
+-- above MAX snaps to that end, since MIN/MAX are the first/last steps.
+function FrameCap.normalize(value)
+  value = tonumber(value)
+  if not value then return FrameCap.DEFAULT end
+  local best, bestDiff = FrameCap.DEFAULT, math.huge
+  for _, step in ipairs(FrameCap.STEPS) do
+    local diff = math.abs(step - value)
+    if diff < bestDiff then best, bestDiff = step, diff end
+  end
+  return best
+end
+
+-- plain numeric text for the options row (e.g. "60")
+function FrameCap.label(value)
+  return tostring(FrameCap.normalize(value))
+end
+
+-- cycle to the next/previous step, wrapping (the options row idiom)
+function FrameCap.cycle(value, dir)
+  local steps = FrameCap.STEPS
+  local snapped = FrameCap.normalize(value)
+  local cur = 1
+  for i, step in ipairs(steps) do
+    if step == snapped then cur = i break end
+  end
+  local nextIdx = (cur - 1 + (dir or 1)) % #steps + 1
+  return steps[nextIdx]
+end
+
+-- Store the chosen cap as the live value the run loop paces to.  Never
+-- touches love.timer, so it is safe headless -- the loop just reads the
+-- number back.  Returns the normalized value it stored.
+function FrameCap.apply(value)
+  FrameCap.current = FrameCap.normalize(value)
+  return FrameCap.current
+end
+
+function FrameCap.applyOptions(opts)
+  FrameCap.apply(opts and opts.fpsCap)
+end
+
+return FrameCap

src/core/Game.lua

@@ -8,7 +8,7 @@ local Logger = require("src.core.Logger")
 local Renderer = require("src.render.Renderer")
 local SaveData = require("src.core.SaveData")
 local StateStack = require("src.core.StateStack")
-local TouchInput = require("src.core.TouchInput")
+local TouchControls = require("src.core.TouchControls")
 local ModLoader = require("src.mods.Loader")
 local ModRuntime = require("src.mods.Runtime")
 local Screens = require("src.ui.Screens")
@@ -17,7 +17,7 @@ local Game = {}
 
 -- dev-mode gate for the F5/backtick hotkeys; false keeps every src/dev
 -- module unloaded, so a player boot never touches a byte of dev code
-local devMode = os.getenv("POKEPORT_DEV") == "1"
+local devMode = os.getenv("POKEPORT_DEV") == "1" or _G.POKEPORT_DEV_MODE == true
 
 -- the boot screen ids (field.boot.screens); a plain function so the
 -- headless harness can borrow makeTitleState onto a stub game
@@ -37,12 +37,15 @@ function Game:load()
   self.mods = ModLoader.new()
   self.mods:load(Data)
   self.modStatus = self.mods:status()
+  -- render pipelines dispatch off the merged dataset; point them at the
+  -- one the mods just merged into before anything can draw a frame
+  require("src.render.Pipelines").install(Data)
 
   self.input = Input
   Input:init()
 
-  self.touchInput = TouchInput
-  TouchInput:init()
+  self.touchControls = TouchControls
+  TouchControls:init()
 
   self.renderer = Renderer
   Renderer:init()
@@ -50,6 +53,9 @@ function Game:load()
   require("src.render.Font").load(Data)
   -- menu cursor/border/geometry constants; field.theme restyles them
   require("src.ui.Theme").load(Data)
+  -- the engine's own text, after the merge so a translation mod's catalog
+  -- is already in Data.strings; empty on a mod-free boot and skipped
+  require("src.core.Strings").load(Data)
 
   self.stack = StateStack
   StateStack:init()
@@ -68,6 +74,10 @@ function Game:load()
   local OverworldState = require("src.world.OverworldController")
   self.overworld = OverworldState
 
+  -- Discord Rich Presence: map name / battle status on the player's profile.
+  -- Soft-fail: missing Discord / IPC errors must never block boot.
+  pcall(function() require("src.core.DiscordPresence").init(self) end)
+
   -- every service is up but nothing is on the stack yet; this payload is
   -- the sanctioned way for a mod to obtain the Game object
   ModRuntime.emit("game.ready", { game = self })
@@ -89,13 +99,32 @@ function Game:load()
   end
 
   Logger.info("game loaded")
+  -- Scaling bug reports (#87, #208) are unanswerable without these three
+  -- numbers: LOVE units, drawable pixels, and the integer physical pixels
+  -- per GB pixel the renderer settled on.  Cheap, once, and it turns "it
+  -- looks stretched" into something reproducible.
+  if love.graphics and love.graphics.getDimensions then
+    local ww, wh = love.graphics.getDimensions()
+    local pw, ph = ww, wh
+    if love.graphics.getPixelDimensions then
+      pw, ph = love.graphics.getPixelDimensions()
+    end
+    Logger.info(string.format(
+      "display: %dx%d units, %dx%d px, fit scale %d px/GB px",
+      ww, wh, pw, ph, Renderer:fitScale()))
+  end
 end
 
 -- the merged field.boot: spawn, names, money and the naming presets a
 -- total conversion overrides.  Threaded into SaveData so persistence stays
 -- free of a Data dependency.
 function Game:bootConfig()
-  return self.data and self.data.field and self.data.field.boot
+  local boot = self.data and self.data.field and self.data.field.boot
+  -- stamp the running game version onto the boot config so a New Game records
+  -- it (SaveData.newGame reads boot.version); this is what routes a Blue
+  -- playthrough to save_blue.lua and Blue's version-gated content
+  if boot then boot.version = require("src.core.GameVersion").get() end
+  return boot
 end
 
 -- the title screen with its NEW GAME / CONTINUE wiring; used at boot
@@ -103,7 +132,7 @@ end
 function Game:makeTitleState()
   local OverworldState = require("src.world.OverworldController")
   local factory = Screens.get(self, bootScreens(self).title or "TitleState")
-  return factory.new(self, {
+  local title = factory.new(self, {
     onNewGame = function()
       while self.stack:top() do self.stack:pop() end
       -- New Game keeps the standalone options.lua preferences
@@ -126,6 +155,8 @@ function Game:makeTitleState()
       end
     end,
   })
+  title.screenId = title.screenId or "TitleState"
+  return title
 end
 
 -- QUIT from the START menu: back to the title like a power-cycle,
@@ -148,17 +179,53 @@ function Game:step(dt)
   self.stack:update(dt)
   -- play time for the trainer card / save screen
   self.save.playTime = (self.save.playTime or 0) + dt
-  require("src.core.Music").update(Data)
+  -- Music.update is NOT serviced here: it decrements fade counters and
+  -- drives ChipAudio once per call, so running it inside the logic step
+  -- would pitch music and sfx up under fast-forward. Game:update advances
+  -- it on its own real-time 60Hz accumulator instead.
+end
+
+-- The logic multiplier for this frame. Read live rather than cached so the
+-- Options row takes effect immediately; speedOverride is the --speed /
+-- POKEPORT_SPEED run argument, which wins over the saved option so a bot
+-- or screenshot run does not depend on whatever the player last chose.
+function Game:logicSpeed()
+  local GameSpeed = require("src.core.GameSpeed")
+  if self.speedOverride then return GameSpeed.clamp(self.speedOverride) end
+  local opts = self.save and self.save.options
+  return GameSpeed.clamp(opts and opts.speed or GameSpeed.DEFAULT)
 end
 
 function Game:update(dt)
-  -- Touch timers / prior-frame auto-releases before the fixed step so
-  -- deferred A and edge pulses land in Input's press queue for this step.
-  TouchInput:update(dt)
-  FixedStep:update(dt)
+  -- Fast-forward scales only the logic clock (see src/core/GameSpeed.lua).
+  -- Give the accumulator room for one full frame at the current speed,
+  -- or the anti-spiral clamp quietly caps every level above ~15X.
+  local speed = self:logicSpeed()
+  FixedStep.maxAccum = math.max(0.25, speed * FixedStep.STEP * 1.5)
+  FixedStep:update(dt * speed)
+  -- Audio runs off real time at a fixed 60Hz regardless of game speed or
+  -- display refresh, so fades and chip synthesis keep their intended tempo
+  -- whether we are at 1X, 10X, or running with vsync disabled.
+  local step = FixedStep.STEP
+  self.audioAccum = math.min((self.audioAccum or 0) + dt, 0.25)
+  while self.audioAccum >= step do
+    self.audioAccum = self.audioAccum - step
+    require("src.core.Music").update(Data)
+  end
   -- Overworld tilt toggle tween: presentational, so it runs on the real
   -- frame dt (not the fixed logic step) for a smooth ~0.25s glide.
   require("src.render.Tilt").update(dt)
+  -- mod render pipelines tween on the same real-frame clock, for the same
+  -- reason: they are presentational, so fast-forward must not speed them up
+  require("src.render.Pipelines").update(dt)
+  pcall(function() require("src.core.DiscordPresence").update(dt) end)
+  -- Steady-state memory backstop: advance the incremental collector one
+  -- small step every rendered frame.  The heavy GPU objects are now freed
+  -- explicitly (map eviction, battle exit, canvas/renderer swaps), so this
+  -- only has to keep ordinary Lua-heap garbage (per-frame tables/closures)
+  -- from drifting upward over a long session, and to spread collection out
+  -- so the default lazy schedule never batches it into a visible pause.
+  if collectgarbage then collectgarbage("step", 1) end
 end
 
 -- render.zones' identity default: unhooked, the zone list reaches the blit
@@ -193,13 +260,19 @@ function Game:draw()
     worldZones = self.overworld:sgbWorldZones()
   end
   Renderer:endFrame(zones, worldZones)
+  -- on-screen mobile controls: pure screen-space, over the finished frame
+  TouchControls:draw()
 end
 
 -- overworld survey zoom: wheel up / '=' zooms in, wheel down / '-' out
 function Game:zoomStep(delta)
   local Zoom = require("src.render.Zoom")
   if not Zoom.gateOK(self.stack:top(), self.overworld) then return end
-  Zoom.step(delta, Renderer:fitScale())
+  local offset = Zoom.step(delta, Renderer:fitScale())
+  if self.save and self.save.options then
+    self.save.options.zoom = offset
+    self:writeOptions()
+  end
 end
 
 function Game:wheelmoved(_, dy)
@@ -248,10 +321,22 @@ function Game:keypressed(key)
     self:zoomStep(1)
     return
   elseif key == "2" then
-    -- cycle COLORS (GBC / OG / OG INV / GBC INV / CLASSIC); always on
-    local PaletteFX = require("src.render.PaletteFX")
-    self.save.options.colors = PaletteFX.cycleMode()
-    self:writeOptions()
+    -- cycle COLORS (GBC / OG / OG INV / GBC INV / CLASSIC); the pack change
+    -- forces Game.overworld:reloadMap, which rebuilds the live NPC array, so
+    -- hold it while a warp/transition or an on-screen scripted cutscene is
+    -- driving the overworld rather than tear the escort's NPCs out mid-move
+    local ow = self.overworld
+    local top = self.stack:top()
+    local busy = ow and (ow.transitioning
+      or (top == ow and (
+           (ow.runner and ow.runner.isRunning and ow.runner:isRunning())
+        or (ow.scriptMoves and #ow.scriptMoves > 0)
+        or ow.engaging or ow.emote)))
+    if not busy then
+      local PaletteFX = require("src.render.PaletteFX")
+      self.save.options.colors = PaletteFX.cycleMode()
+      self:writeOptions()
+    end
     return
   elseif key == "3" then
     -- cycle TILT OFF → 15 → 35 → 50 → OFF (mnemonic: 3D), free-roam only
@@ -261,13 +346,34 @@ function Game:keypressed(key)
       self:writeOptions()
     end
     return
+  elseif key == "4" then
+    -- cycle ZOOM through every integer level (survey → FIT → close-up → wrap)
+    local Zoom = require("src.render.Zoom")
+    if Zoom.gateOK(self.stack:top(), self.overworld) then
+      self.save.options.zoom = Zoom.cycle(Renderer:fitScale())
+      self:writeOptions()
+    end
+    return
   elseif key == "5" then
     -- cycle GBC FX OFF → 1 → 2 → 3 → 4 (unlit-GBC ladder); always on
+    -- desktop.  Mobile refuses the present shader (issue #136).
     local GBCFX = require("src.render.GBCFX")
+    if not GBCFX.isSupported() then return end
     self.save.options.gbcfx = GBCFX.cycle()
     self:writeOptions()
     return
   end
+  -- Mod render pipelines claim their hotkeys last, so one can never shadow
+  -- an engine display key however a mod declares it (12 §rendering
+  -- pipelines).  syncOptions writes the whole ladder back, including the
+  -- tilt exclusion a world pipeline forces.
+  local Pipelines = require("src.render.Pipelines")
+  if Pipelines.hotkey(key, self.stack:top(), self.overworld) then
+    Pipelines.syncOptions(self.save.options)
+    require("src.render.Tilt").setLevel(self.save.options.tilt or 0)
+    self:writeOptions()
+    return
+  end
   Input:keypressed(key)
 end
 
@@ -285,6 +391,9 @@ function Game:keyreleased(key)
 end
 
 function Game:gamepadpressed(joystick, button)
+  -- a controller is being used: the touch overlay steps aside until the
+  -- next screen touch (mobile only; a no-op elsewhere)
+  TouchControls:noteGamepad()
   -- BindingsMenu's pad capture rides the same top-state routing as keys
   local top = self.stack and self.stack:top()
   if top and top.onGamepadPressed then
@@ -299,19 +408,43 @@ function Game:gamepadreleased(joystick, button)
 end
 
 function Game:gamepadaxis(joystick, axis, value)
+  -- past-deadzone only, so resting-stick drift can't hide the overlay
+  if math.abs(value) > 0.5 then TouchControls:noteGamepad() end
   Input:gamepadaxis(joystick, axis, value)
 end
 
+-- Window focus/visibility flips: a release due while unfocused/hidden can
+-- be swallowed by the OS. Reset on both edges -- gaining focus with a
+-- physically held key won't re-fire keypressed, so trusting leftover
+-- state is worse than asking the player to re-press.
+function Game:focus(f)
+  Input:reset()
+  TouchControls:reset()
+end
+
+function Game:visible(v)
+  Input:reset()
+  TouchControls:reset()
+end
+
+-- A disconnected/dropped controller can't send the button-up for whatever
+-- it was holding, so drop all input state rather than try to guess which
+-- flags it owned.
+function Game:joystickremoved(joystick)
+  Input:reset()
+  TouchControls:joystickremoved()
+end
+
 function Game:touchpressed(id, x, y)
-  TouchInput:touchpressed(id, x, y)
+  TouchControls:touchpressed(id, x, y)
 end
 
 function Game:touchmoved(id, x, y)
-  TouchInput:touchmoved(id, x, y)
+  TouchControls:touchmoved(id, x, y)
 end
 
 function Game:touchreleased(id, x, y)
-  TouchInput:touchreleased(id, x, y)
+  TouchControls:touchreleased(id, x, y)
 end
 
 -- Point the loader's mod.save backing at this save's modData so per-mod
@@ -362,7 +495,20 @@ function Game:applyOptions(opts)
   if Sound.applyOptions then Sound.applyOptions(opts) end
   require("src.render.PaletteFX").applyOptions(opts)
   require("src.render.Tilt").applyOptions(opts)
-  require("src.render.GBCFX").applyOptions(opts)
+  -- after Tilt, so a persisted world pipeline can switch the tilt level it
+  -- just restored back off (the two are mutually exclusive)
+  require("src.render.Pipelines").applyOptions(opts)
+  require("src.render.Zoom").applyOptions(opts)
+  require("src.render.TileRenderer").applyOptions(opts)
+  -- returns true when a persisted GBC FX level was cleared on mobile
+  local gbcCleared = require("src.render.GBCFX").applyOptions(opts)
+  require("src.core.VideoMode").applyOptions(opts)
+  -- normalizes a nil/garbage cap to the 60 default, so old saves with no
+  -- fpsCap key pace at the standard rate (issue #88)
+  require("src.core.FrameCap").applyOptions(opts)
+  Input:applyBindings(opts.bindings)
+  -- heal soft-bricked APK installs that already saved gbcfx > 0 (#136)
+  if gbcCleared then self:writeOptions() end
 end
 
 function Game:restoreSave(loaded, recovered)
@@ -374,6 +520,13 @@ function Game:restoreSave(loaded, recovered)
   -- SaveData.load and skip on the format guard
   local activeMods = self.modStatus and self.modStatus.loaded
   SaveData.runMigrations(loaded, self.mods and self.mods.migrations, activeMods)
+  -- Issue #103: 0.1.11 softlocks left CONTINUE in HALL_OF_FAME with
+  -- lastOutdoor on Indigo.  One-shot relocate + heal before validate.
+  if SaveData.needsPostGameRescue(loaded) then
+    SaveData.applyPostGameHome(loaded, self:bootConfig())
+    local Pokemon = require("src.pokemon.Pokemon")
+    for _, mon in ipairs(loaded.party or {}) do Pokemon.heal(mon) end
+  end
   local modsDiff = SaveData.modsDiff(loaded, activeMods)
   local report = SaveData.validate(loaded, self.data)
   report.recovered = recovered

src/core/GameSpeed.lua

@@ -0,0 +1,54 @@
+-- Fast-forward multiplier for game logic.
+--
+-- Speeding up means running the 1/60 fixed step N times per real frame
+-- (Game:update), so everything driven by the step -- movement, text,
+-- battle timing, scripts -- advances N times faster while staying
+-- deterministic. Audio deliberately does NOT scale: Music.update drives
+-- fade counters and ChipAudio synthesis off its own real-time 60Hz
+-- accumulator in Game:update, so music and sfx play at normal pitch and
+-- tempo at every speed.
+--
+-- Vsync still caps how much work a real frame can do, so 10X is a target
+-- rather than a promise on a slow machine -- the logic simply runs as many
+-- steps as the frame budget allows.
+
+local GameSpeed = {}
+
+-- 20X exists for the bot runs (tests/drivers/route.lua): a full-route
+-- attempt is long enough that the iteration loop, not the engine, is the
+-- bottleneck. Vsync caps how much a real frame can do, so past 10X the
+-- multiplier is increasingly a ceiling rather than a rate.
+GameSpeed.LEVELS = { 1, 2, 4, 10, 20, 30, 50, 75, 100,200 }
+GameSpeed.DEFAULT = 1
+
+function GameSpeed.levelLabel(v)
+  v = tonumber(v) or GameSpeed.DEFAULT
+  if v == 1 then return "NORMAL" end
+  return tostring(v) .. "X"
+end
+
+-- nearest valid level for an arbitrary value (a hand-edited options.lua or
+-- a --speed argument), so a bad number degrades to something sane
+function GameSpeed.clamp(v)
+  v = tonumber(v)
+  if not v then return GameSpeed.DEFAULT end
+  local best, bestDiff = GameSpeed.DEFAULT, math.huge
+  for _, level in ipairs(GameSpeed.LEVELS) do
+    local diff = math.abs(level - v)
+    if diff < bestDiff then best, bestDiff = level, diff end
+  end
+  return best
+end
+
+-- cycle to the next/previous level, wrapping (the options row idiom)
+function GameSpeed.cycle(v, dir)
+  local levels = GameSpeed.LEVELS
+  local cur = 1
+  for i, level in ipairs(levels) do
+    if level == GameSpeed.clamp(v) then cur = i break end
+  end
+  local nextIdx = (cur - 1 + (dir or 1)) % #levels + 1
+  return levels[nextIdx]
+end
+
+return GameSpeed

src/core/GameVersion.lua

@@ -0,0 +1,77 @@
+-- Which Gen-1 game this process is running: Red (the historical default) or
+-- Blue.  One source of truth for everything that differs by version -- the
+-- accepted ROM hash, the import manifest, where the extracted cache lives,
+-- and the save-file suffix -- so the importer, cache mount, SaveData, title
+-- screen and palette all agree.
+--
+-- Red keeps every un-suffixed path it always used (save.lua, the root cache),
+-- so existing installs are untouched; Blue is namespaced under blue/ and
+-- _blue so both can be imported and played side by side.
+--
+-- Zero requires, so it loads during love.conf and under plain Lua for tools
+-- and tests.  The active version is a process-global set once at boot from
+-- the launcher's column choice (main.lua); it defaults to Red.
+
+local GameVersion = {}
+
+GameVersion.VERSIONS = {
+  red = {
+    id = "red",
+    label = "Red",
+    displayName = "Pokemon Red",
+    sha1 = "ea9bcae617fdf159b045185467ae58b2e4a48b9a",
+    manifest = "tools/rom_manifest.json",
+    cachePrefix = "",       -- Red owns the cache root (backwards compatible)
+    saveSuffix = "",        -- save.lua / save.lua.bak / save.lua.tmp
+  },
+  blue = {
+    id = "blue",
+    label = "Blue",
+    displayName = "Pokemon Blue",
+    sha1 = "d7037c83e1ae5b39bde3c30787637ba1d4c48ce2",
+    manifest = "tools/rom_manifest_blue.json",
+    cachePrefix = "blue/",  -- blue/data/generated, blue/assets/generated
+    saveSuffix = "_blue",   -- save_blue.lua / .bak / .tmp
+  },
+}
+
+-- Launcher column order (Yellow is still a placeholder, handled by the UI).
+GameVersion.ORDER = { "red", "blue" }
+
+GameVersion.current = "red"
+
+function GameVersion.set(id)
+  GameVersion.current = GameVersion.VERSIONS[id] and id or "red"
+  return GameVersion.current
+end
+
+function GameVersion.get()
+  return GameVersion.current
+end
+
+function GameVersion.isBlue()
+  return GameVersion.current == "blue"
+end
+
+-- Metadata for a version id, defaulting to the active one.
+function GameVersion.info(id)
+  return GameVersion.VERSIONS[id or GameVersion.current]
+end
+
+function GameVersion.saveSuffix(id)
+  return GameVersion.info(id).saveSuffix
+end
+
+function GameVersion.cachePrefix(id)
+  return GameVersion.info(id).cachePrefix
+end
+
+-- The version a ROM belongs to, by its SHA-1, or nil for an unknown ROM.
+function GameVersion.forSha1(sha1)
+  for id, info in pairs(GameVersion.VERSIONS) do
+    if info.sha1 == sha1 then return id end
+  end
+  return nil
+end
+
+return GameVersion

src/core/Input.lua

@@ -3,7 +3,7 @@
 
 local Input = {}
 
-local BINDINGS = {
+local DEFAULT_BINDINGS = {
   up = "up", w = "up",
   down = "down", s = "down",
   left = "left", a = "left",
@@ -11,15 +11,23 @@ local BINDINGS = {
   z = "a", ["return"] = "a", space = "a",
   x = "b", backspace = "b",
   ["kpenter"] = "start", escape = "start",
+  -- Select: fight-menu move reorder + bag item reorder. Tab is the
+  -- discoverable default (shown in CONTROLS); both shifts stay as
+  -- aliases so Right-Shift muscle memory from older builds still works.
+  tab = "select",
   rshift = "select",
+  lshift = "select",
 }
 
 -- keys that map to "start" but also to "a" would conflict; keep Enter = a,
 -- Escape = start for desktop friendliness.
 
 -- LÖVE's standard gamepad mapping (SDL game controller DB), consistent
--- across Xbox/PlayStation/generic controllers on desktop and mobile.
-local GAMEPAD_BINDINGS = {
+-- across Xbox/PlayStation/generic controllers on desktop and mobile. Some
+-- third-party pads report their own SDL mapping for a given physical
+-- button (e.g. Select/Back/View on off-brand XInput pads), which is what
+-- src/ui/BindingsMenu.lua's rebinding is for -- see applyBindings below.
+local DEFAULT_GAMEPAD_BINDINGS = {
   dpup = "up", dpdown = "down", dpleft = "left", dpright = "right",
   a = "a", b = "b",
   start = "start", back = "select",
@@ -32,48 +40,142 @@ local STICK_ON = 0.5
 local STICK_OFF = 0.3
 
 function Input:init()
+  self:applyBindings(nil)
+  self:reset()
+end
+
+-- Layers a player's rebind choices (save.options.bindings, written by
+-- src/ui/BindingsMenu.lua) on top of the defaults above. A rebind adds an
+-- extra way to trigger that action instead of replacing the default key,
+-- so e.g. Z/Enter/Space all still press A even after binding a 4th key to
+-- it. Call whenever options load or change (see Game:applyOptions and
+-- BindingsMenu:storeBinding) -- without this the menu records a choice
+-- that never actually reaches gameplay.
+function Input:applyBindings(overlay)
+  local keys, pads = {}, {}
+  for key, action in pairs(DEFAULT_BINDINGS) do keys[key] = action end
+  for button, action in pairs(DEFAULT_GAMEPAD_BINDINGS) do pads[button] = action end
+  for actionId, binding in pairs(overlay or {}) do
+    if type(binding) == "table" then
+      if binding.key then keys[binding.key] = actionId end
+      if binding.pad then pads[binding.pad] = actionId end
+    elseif type(binding) == "string" then
+      keys[binding] = actionId
+    end
+  end
+  self.keyBindings = keys
+  self.padBindings = pads
+end
+
+-- Purely event-driven state (press sets true, release sets false) has no
+-- fallback if a release event never arrives -- focus loss, a minimized
+-- window, or a disconnected gamepad can all swallow the key-up/button-up
+-- that would have cleared a held direction. Called from Game on those
+-- transitions so a stuck flag can't outlive them.
+function Input:reset()
   self.state = {}
   self.pressQueue = {}
   self.pressed = {}
+  self.sources = {}
   self.stickAxis = { x = 0, y = 0 }
   self.stickDir = nil
 end
 
-function Input:keypressed(key)
-  local btn = BINDINGS[key]
-  if btn then
+-- Multiple physical sources (W + Up, d-pad + stick, etc.) can claim the
+-- same GB button. Track them individually so releasing one doesn't clear
+-- a hold another source still owns, and so a press+release that both land
+-- before the next FixedStep can't be revived when step() drains the queue.
+local function press(self, btn, source)
+  local sources = self.sources[btn]
+  if not sources then
+    sources = {}
+    self.sources[btn] = sources
+  end
+  if not sources[source] then
+    sources[source] = true
     table.insert(self.pressQueue, btn)
   end
+  self.state[btn] = true
+end
+
+local function release(self, btn, source)
+  local sources = self.sources[btn]
+  if sources then
+    sources[source] = nil
+    if next(sources) == nil then
+      -- Leave an empty table (not nil) so step() can tell a real
+      -- source was released before the queue drained, versus a
+      -- synthetic pressQueue inject that never had sources at all.
+      self.state[btn] = false
+    end
+  else
+    self.state[btn] = false
+  end
+end
+
+function Input:keypressed(key)
+  local btn = self.keyBindings[key]
+  if btn then
+    press(self, btn, "key:" .. key)
+  end
 end
 
 function Input:keyreleased(key)
-  local btn = BINDINGS[key]
+  local btn = self.keyBindings[key]
   if btn then
-    self.state[btn] = false
+    release(self, btn, "key:" .. key)
   end
 end
 
 -- Called once per fixed step: promote queued presses to this step's edges.
+-- Hold state is owned by live sources (updated in press/release), not
+-- re-asserted here -- otherwise a same-frame press→release leaves the
+-- button stuck on after the queue drains.
+-- Synthetic injects (tests/drivers writing pressQueue directly, with no
+-- source entry) still set state so scripted holds keep working.
 function Input:step()
   self.pressed = {}
   for _, btn in ipairs(self.pressQueue) do
     self.pressed[btn] = true
-    self.state[btn] = true
+    local sources = self.sources[btn]
+    if sources == nil then
+      -- synthetic pressQueue inject (tests/drivers): no live source map
+      self.state[btn] = true
+    elseif next(sources) ~= nil then
+      self.state[btn] = true
+    end
+    -- sources == {}: real press fully released before this step — keep up
+  end
+  for btn, sources in pairs(self.sources) do
+    if next(sources) == nil then
+      self.sources[btn] = nil
+    end
   end
   self.pressQueue = {}
 end
 
+-- The on-screen touch overlay (src/core/TouchControls.lua) presses GB
+-- buttons directly by name -- not through a keyboard alias -- so a player
+-- rebind can never detach or shadow the overlay.
+function Input:overlayPressed(btn)
+  press(self, btn, "touch:" .. btn)
+end
+
+function Input:overlayReleased(btn)
+  release(self, btn, "touch:" .. btn)
+end
+
 function Input:gamepadpressed(joystick, button)
-  local btn = GAMEPAD_BINDINGS[button]
+  local btn = self.padBindings[button]
   if btn then
-    table.insert(self.pressQueue, btn)
+    press(self, btn, "pad:" .. button)
   end
 end
 
 function Input:gamepadreleased(joystick, button)
-  local btn = GAMEPAD_BINDINGS[button]
+  local btn = self.padBindings[button]
   if btn then
-    self.state[btn] = false
+    release(self, btn, "pad:" .. button)
   end
 end
 
@@ -103,10 +205,10 @@ function Input:gamepadaxis(joystick, axis, value)
 
   if newDir ~= self.stickDir then
     if self.stickDir then
-      self.state[self.stickDir] = false
+      release(self, self.stickDir, "stick")
     end
     if newDir then
-      table.insert(self.pressQueue, newDir)
+      press(self, newDir, "stick")
     end
     self.stickDir = newDir
   end

src/core/Music.lua

@@ -24,7 +24,31 @@ local FILTER_HIGHGAIN = { 0.4, 0.16, 0.064 }
 local filterLevel = 0
 
 local function applyVolume(src)
-  if src then pcall(src.setVolume, src, VOLUME * volumeScale) end
+  if not src then return end
+  local vol = VOLUME * volumeScale
+  if Runtime.wantsHook("music.volume") then
+    local ctx = {
+      song = state.current,
+      mapSong = state.mapSong,
+      onBike = state.onBike,
+      surfing = state.surfing,
+      fading = state.fade ~= nil,
+      optionScale = volumeScale,
+    }
+    local ok, Game = pcall(require, "src.core.Game")
+    if ok and Game then
+      local ow = Game.overworld
+      if ow and ow.player then
+        ctx.x, ctx.y = ow.player.cellX, ow.player.cellY
+        ctx.mapId = ow.map and ow.map.id
+        ctx.tod = ow.tod
+      end
+    end
+    vol = Runtime.call("music.volume", function(v) return v end, vol, ctx)
+    vol = tonumber(vol) or (VOLUME * volumeScale)
+    if vol < 0 then vol = 0 end
+  end
+  pcall(src.setVolume, src, vol)
 end
 
 -- Source:setFilter needs OpenAL EFX; the pcall degrades to unfiltered
@@ -114,6 +138,7 @@ local SPECIAL = {
   oakRoute = "Music_Routes2",
   bike = "Music_BikeRiding",
   surf = "Music_Surfing",
+  evolution = "Music_SafariZone",
 }
 
 -- the label a scene role resolves to; call sites keep their own presence
@@ -253,6 +278,7 @@ function Music.stop()
   require("src.core.ChipAudio").stopMusic()
   state.current, state.source, state.loopSource, state.fade = nil, nil, nil, nil
   state.chip = false
+  state.pendingRestore = nil
   if previous and Runtime.wants("music.stopped") then
     Runtime.emit("music.stopped", { song = previous })
   end
@@ -346,18 +372,25 @@ end
 function Music.playOnce(data, song)
   if not songDef(data, song) then return false end
   Music.play(data, song, false, { reason = "once" })
+  -- play() can no-op (hook silence, failed def); only arm restore when
+  -- the jingle actually became current
+  if state.current ~= song then return false end
   state.pendingRestore = true
   return true
 end
 
--- is a playOnce jingle still sounding?  (AnimateHealingMachine's
--- .waitLoop2 holds the healing machine until MUSIC_PKMN_HEALED ends)
+local function chipAwaitingFirstBuffer()
+  return state.chip
+     and require("src.core.ChipAudio").awaitingFirstBuffer()
+end
+
+-- is a playOnce jingle still in flight?  (AnimateHealingMachine's
+-- .waitLoop2 / Mom heal / captain rub hold until MUSIC_PKMN_HEALED ends.)
+-- pendingRestore stays set from playOnce until Music.update restores the
+-- map theme, covering the threaded chip "empty QueueableSource" window
+-- where Source:isPlaying is briefly false before the first buffer lands.
 function Music.oneShotPlaying()
-  if not state.pendingRestore then return false end
-  local src = state.source
-  if not src then return false end
-  local ok, playing = pcall(src.isPlaying, src)
-  return ok and playing or false
+  return state.pendingRestore == true
 end
 
 function Music.restoreMap(data)
@@ -399,6 +432,12 @@ end
 -- restores the map theme after a one-shot jingle
 function Music.update(data)
   if state.chip then require("src.core.ChipAudio").update() end
+  -- distance / indoor muffling mods re-apply volume every frame while
+  -- subscribed; otherwise applyVolume only runs on song/option changes
+  if Runtime.wantsHook("music.volume") and not state.fade then
+    applyVolume(state.source)
+    applyVolume(state.loopSource)
+  end
   -- volume ramp (Music.fadeOut): hold the current level for `control`
   -- frames, then drop one level (FadeOutAudio decrements both rAUDVOL
   -- nibbles when its counter reaches 0); at level 0 the music stops.
@@ -440,8 +479,10 @@ function Music.update(data)
     state.source = loopSrc
     pcall(loopSrc.play, loopSrc)
   end
+  -- do not treat "threaded source still waiting on its first buffer" as
+  -- ended, or playOnce jingles get restored over before they can sound
   if state.pendingRestore and sourceStopped(state.source)
-     and not state.loopSource then
+     and not state.loopSource and not chipAwaitingFirstBuffer() then
     Music.restoreMap(data)
   end
 end