Merge pull request #1288 from bryanthaboi/dev

CLOSES #1283

.github/workflows/ci.yml

@@ -94,8 +94,8 @@ jobs:
         if: github.repository == 'bryanthaboi/gen1recomp'
         uses: actions/upload-artifact@v7
         with:
-          name: gen1recomp-ios-ipa
-          path: dist/ios/gen1recomp.ipa
+          name: gen1recomp++-ios-ipa
+          path: dist/ios/gen1recomp++.ipa
           if-no-files-found: error
           retention-days: 7
       - name: clean up signing keychain

.github/workflows/ios-artifact-comment.yml

@@ -22,7 +22,7 @@ jobs:
           HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
           HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name }}
         run: |
-          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp-ios-ipa") | .id')"
+          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp++-ios-ipa") | .id')"
           [ -n "$artifact_id" ] || exit 0
           head_owner="${HEAD_REPOSITORY%%/*}"
           pr_number="$(gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$head_owner:$HEAD_BRANCH" --jq '.[0].number // empty')"
@@ -44,7 +44,7 @@ jobs:
         uses: thollander/actions-comment-pull-request@v3
         with:
           message: |
-            [gen1recomp.ipa](${{ steps.artifact.outputs.artifact_url }})
+            [gen1recomp++.ipa](${{ steps.artifact.outputs.artifact_url }})
 
             **Commit**: [#${{ steps.build-info.outputs.hash }}](https://github.com/${{ github.event.workflow_run.head_repository.full_name }}/commit/${{ github.event.workflow_run.head_sha }})
             **Build Time**: `${{ steps.build-info.outputs.time }}`

.github/workflows/release.yml

@@ -1,8 +1,9 @@
 name: Release
 
 # Builds the macOS, Windows, and Linux desktop apps, an Android APK, an iOS
-# IPA, a Nintendo Switch SD-ready zip (experimental), Xbox UWP, and the Anbernic
-# RG34XXSP (Stock OS 64-bit MOD / PortMaster) port, then publishes them as a
+# IPA, a Nintendo Switch SD-ready zip (experimental), Xbox UWP, the Anbernic
+# RG34XXSP (Stock OS 64-bit MOD / PortMaster) and Linux ARM SBC PortMaster
+# handheld ports on the self-hosted Mac runner, and publishes them as a
 # GitHub Release.
 #
 # Versioning:
@@ -251,8 +252,40 @@ jobs:
               Remove-Item $env:UWP_PFX -Force -ErrorAction SilentlyContinue
           }
 
+  # Windows Native AOT TLS dialer. The Mac release runner fuses the win64 zip
+  # from LÖVE's prebuilt binaries and cannot cross-compile this DLL, so build
+  # it here and inject it in the release job before scripts/build.sh win.
+  native-tls-win:
+    name: build Windows gen1tls.dll
+    needs: version
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Setup .NET 8
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "8.0.x"
+      - name: Publish gen1tls (win-x64 Native AOT)
+        shell: pwsh
+        run: |
+          $out = "dist/native/win-x64"
+          New-Item -ItemType Directory -Force -Path $out | Out-Null
+          dotnet publish native/tls_dial/Gen1Tls.csproj `
+            -c Release -r win-x64 -o $out
+          if (-not (Test-Path "$out/gen1tls.dll")) {
+            throw "gen1tls.dll missing after publish"
+          }
+          Get-Item "$out/gen1tls.dll" | Format-List Name, Length, LastWriteTime
+      - name: Upload gen1tls.dll
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1tls-win-x64
+          path: dist/native/win-x64/gen1tls.dll
+          if-no-files-found: error
+          retention-days: 1
+
   release:
-    needs: [version, xbox-uwp, linux-arm64]
+    needs: [version, xbox-uwp, linux-arm64, native-tls-win]
     runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
 
     steps:
@@ -268,6 +301,12 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
 
+      - name: Download Windows gen1tls dialer
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1tls-win-x64
+          path: dist/native/win-x64
+
       - name: Import signing certificate into a temporary keychain
         if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
@@ -306,13 +345,21 @@ jobs:
           security find-identity -v -p codesigning "$KEYCHAIN_PATH"
 
       - name: Build macOS + Windows + Linux
+        env:
+          GEN1TLS_DLL: ${{ github.workspace }}/dist/native/win-x64/gen1tls.dll
         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. "all" also builds the Linux AppImage,
           # which needs no signing/notarization.
+          if [ ! -f "$GEN1TLS_DLL" ]; then
+            echo "::error::gen1tls.dll missing at $GEN1TLS_DLL (native-tls-win job)"
+            exit 1
+          fi
           scripts/build.sh all --version "${{ needs.version.outputs.version }}" --no-notarize
+          unzip -l dist/win/gen1recomp-win64.zip | grep -F gen1tls.dll \
+            || { echo "::error::Windows zip is missing gen1tls.dll"; exit 1; }
 
       - name: Build Android
         run: |
@@ -355,6 +402,20 @@ jobs:
           # runtime from PortMaster-GUI, so it needs no signing/notarization.
           ./build-rg34xxsp.sh --version "${{ needs.version.outputs.version }}"
 
+      - name: Build Linux ARM SBC PortMaster port
+        env:
+          # The release workflow must package the commit being released. The
+          # script defaults to the latest published release for standalone
+          # builds, while this explicit local override keeps CI source-aligned.
+          GEN1RECOMP_SOURCE_DIR: ${{ github.workspace }}
+          GEN1RECOMP_RELEASE_TAG: v${{ needs.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          # Same aarch64 PortMaster-style pack for Linux ARM SBC PortMaster. The build
+          # keeps its own cache because the two scripts use different staging
+          # layouts and runtime package paths.
+          ./build-linux-arm-sbc.sh --version "${{ needs.version.outputs.version }}"
+
       - name: Notarize & staple macOS app
         if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
@@ -429,9 +490,9 @@ jobs:
           [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
           cp "$apk" "$outdir/gen1recomp-${v}-android.apk"
 
-          ipa="dist/ios/gen1recomp.ipa"
+          ipa="dist/ios/gen1recomp++.ipa"
           [ -f "$ipa" ] || { echo "::error::$ipa not found (expected from scripts/build_ios.sh --device)"; exit 1; }
-          cp "$ipa" "$outdir/gen1recomp-${v}-ios.ipa"
+          cp "$ipa" "$outdir/gen1recomp++-${v}-ios.ipa"
 
           swzip="dist/switch/gen1recomp-${v}-switch.zip"
           [ -f "$swzip" ] || { echo "::error::$swzip not found (expected from scripts/build_switch.sh --fused → pack_sd_zip.sh)"; exit 1; }
@@ -449,6 +510,11 @@ jobs:
           [ -f "$rg34" ] || { echo "::error::$rg34 not found (expected from ./build-rg34xxsp.sh)"; exit 1; }
           cp "$rg34" "$outdir/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip"
 
+          # Linux ARM SBC PortMaster handheld port.
+          sbc="dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip"
+          [ -f "$sbc" ] || { echo "::error::$sbc not found (expected from ./build-linux-arm-sbc.sh)"; exit 1; }
+          cp "$sbc" "$outdir/gen1recomp-${v}-sbc-portmaster.zip"
+
           # 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"
@@ -560,10 +626,11 @@ jobs:
             "dist/release/gen1recomp-${v}-linux.zip"
             "dist/release/gen1recomp-${v}-linux-arm64.AppImage"
             "dist/release/gen1recomp-${v}-android.apk"
-            "dist/release/gen1recomp-${v}-ios.ipa"
+            "dist/release/gen1recomp++-${v}-ios.ipa"
             "dist/release/gen1recomp-${v}-switch.zip"
             "dist/release/gen1recomp-${v}-xbox-uwp.zip"
             "dist/release/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip"
+            "dist/release/gen1recomp-${v}-sbc-portmaster.zip"
             "dist/release/gen1recomp-${v}.love"
             "dist/release/sha256sums.txt"
           )
@@ -581,14 +648,15 @@ jobs:
         run: |
           set -euo pipefail
           v="${{ needs.version.outputs.version }}"
-          ipa="dist/release/gen1recomp-${v}-ios.ipa"
+          ipa="dist/release/gen1recomp++-${v}-ios.ipa"
           app_repo="mobile/ios/app-repo.json"
           [ -f "$ipa" ] || { echo "::error::$ipa not found"; exit 1; }
           [ -f "$app_repo" ] || { echo "::error::$app_repo not found"; exit 1; }
 
           date="$(date -u +"%Y-%m-%d")"
           size="$(wc -c < "$ipa" | tr -d '[:space:]')"
-          download_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/v${v}/gen1recomp-${v}-ios.ipa"
+          download_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/v${v}/gen1recomp++-${v}-ios.ipa"
+          bundle_id="com.theboisclub.gen1recompplusplus"
           localized_description="Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke"
           release_notes="$(GH_TOKEN="${{ github.token }}" gh release view "v${v}" --json body --jq '.body // ""' 2>/dev/null || true)"
           if [ -n "$release_notes" ]; then
@@ -602,15 +670,15 @@ jobs:
             --argjson size "$size" \
             '{version: $version, date: $date, size: $size, downloadURL: $download_url, localizedDescription: $localized_description}')"
 
-          if jq -e --arg version "$v" \
-            'any(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions[]?; .version == $version)' \
+          if jq -e --arg bundle_id "$bundle_id" --arg version "$v" \
+            'any(.apps[] | select(.bundleIdentifier == $bundle_id).versions[]?; .version == $version)' \
             "$app_repo" >/dev/null; then
-            jq --arg version "$v" --argjson entry "$entry" \
-              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= map(if .version == $version then $entry else . end)' \
+            jq --arg bundle_id "$bundle_id" --arg version "$v" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == $bundle_id).versions) |= map(if .version == $version then $entry else . end)' \
               "$app_repo" > "$app_repo.tmp"
           else
-            jq --argjson entry "$entry" \
-              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= [$entry] + .' \
+            jq --arg bundle_id "$bundle_id" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == $bundle_id).versions) |= [$entry] + .' \
               "$app_repo" > "$app_repo.tmp"
           fi
           mv "$app_repo.tmp" "$app_repo"

.gitignore

@@ -3,8 +3,9 @@
 data/generated/
 assets/generated/
 
-# LÖVE packages
+# LÖVE packages & archives
 *.love
+*.zip
 
 # Local saves (LÖVE writes to its save dir, but keep the repo clean anyway)
 save/
@@ -75,3 +76,6 @@ mobile/ios/bundle_id.local
 /dist/native/
 /dist/win/
 /.bazinga/
+
+# Local options / preferences
+/options.lua*

CONTRIBUTING-mods.md

@@ -242,10 +242,52 @@ with a `MK4xx` finding per site and an `unresolved:` note, with a file and a
 line, for every reach a static scan could not follow. Neither substitutes for a
 real Gold boot.
 
-### 5. `mod.card`
+### 5. What a mod's code can reach
+
+Your code runs in a sandbox (`src/mods/Sandbox.lua`), not against the
+engine's globals. Every chunk you author gets it: `main.lua`, your
+`options_schema`, and anything you `load()` yourself. What is absent:
+
+| Absent | Use instead |
+| --- | --- |
+| `io`, and `require("io")` | `mod:read` for your own files, `mod.storage` to persist |
+| `os.getenv`, `os.execute`, `os.remove`, `os.rename`, `os.exit` | nothing; `os.time`/`os.date`/`os.clock` still work |
+| `package`, `dofile`, `loadfile`, `debug`, `getfenv`, `setfenv` | `require` for the supported engine modules |
+| `require("ffi")`, `require("love.*")` | the `love` table you are given |
+| `love.filesystem` | `mod.storage` (per-mod, per-playthrough) and `mod:read` |
+| `love.thread`, `love.event` | `mod.events`, `mod.hooks` |
+| `love.system` | `mod.device:powerInfo()` for battery information; `mod.steps` (with the `steps` permission) for the step bridge |
+
+The rest of `love` passes through unchanged, so graphics, audio, timers and
+input work as they always have.
+
+Three consequences worth knowing before you write against it:
+
+- **Your globals are yours.** `_G` inside a mod is that mod's own table. Two
+  mods no longer share a namespace, and neither can reach the engine's. To
+  publish something to another mod, put it on `mod.exports` and let them
+  `mod.find("your_id").exports` — the channel that was always the intended
+  one. The same goes for the standard library: `string`, `table` and `math`
+  are per-mod copies, so patching one is a local decision.
+- **Paths cannot climb.** `mod:read`, `mod.assets:path` and `mod.assets:image`
+  join to your own directory, and `..`, absolute paths and drive letters are
+  refused. So are `entry` and `options_schema` in your manifest.
+- **Ship source, not bytecode.** A precompiled entry file is refused.
+
+`permissions` in the manifest is still a disclosure the manager shows the
+player, and `network` now gates `require("socket")` and friends. There is no
+permission that grants raw filesystem access, because no mod needs one:
+everything a mod legitimately writes is already scoped by
+`mod.storage` or the asset-transform derived root.
+
+If your mod used one of the absent globals, the fix is almost always
+`mod.storage`. Open an issue if you have a case it does not cover.
+
+### 6. `mod.card`
 
 The manifest is the *engine's* contract: identity, load order, dependencies,
-permissions, profile. The card is the *human-facing* one: who made this,
+permissions, profile (see [Manifest specification](docs/modding.md#manifest-specification-manifestjson)).
+The card is the *human-facing* one: who made this,
 what it changes, what it does not do yet. It is never read by the loader's
 merge — only by tooling and the manager's detail pane — so an absent or
 malformed card can never break a load.
@@ -263,7 +305,7 @@ Two fields deserve their own note:
   distributed mod never carries ROM-derived bytes, not even in its preview
   images.
 
-### 6. Tags
+### 7. Tags
 
 Lowercase kebab strings, open vocabulary. The showcase generator
 lowercases and de-dupes. A recommended starting set: `beginner`,

KANTO-CONTINUE.md

@@ -1,457 +0,0 @@
-# KANTO-CONTINUE: executing the never-run half of Gold (sections 19-32)
-
-Deferred from the 2026-08-09 fix campaign by request. This doc is self-contained: the
-audit documents it was distilled from are being retired, so everything a future session
-needs is here.
-
-## What this is
-
-The Johto main line (walkthrough sections 00-18) is proven: the route bot beats Champion
-Lance with every row passing. Kanto (sections 19-32) is extracted and wired but has
-NEVER been executed by any bot row, driver, or human. Every entry below reads clean in
-static review (cache + code + cart source were cross-checked adversarially); the risk is
-purely runtime. The job: make each beat actually run, fix what breaks, and leave
-executable evidence (bot rows or assertion drivers) behind.
-
-## State after the 2026-08-09 campaign (what changed under you)
-
-- ~80 defects fixed across the port; 91/91 gen2 suites, engine 128/128, T3 all green.
-- The post-game handoff WORKS now: post-E4 credits end at the title screen, and
-  CONTINUE consumes the post-game spawn (HallOfFame.consumePostGameSpawn): after Lance
-  you continue in NEW_BARK_TOWN, after Red at SILVER_CAVE_OUTSIDE (23,20). Section 19
-  is reachable by normal play for the first time.
-- The Snorlax wake chain is fully functional (engine-flag bridge unlocks the Pokegear
-  and EXPN card; the tuned radio song persists after closing the gear; SnorlaxAwake
-  fires; proven live by tests/drivers/gold_radio_persist.lua).
-- Landed systems Kanto beats depend on: phone random/outgoing calls, field item use
-  (Escape Rope/Dig via save.backupWarp), Repel, swarms, Rock Smash encounters,
-  waterfall current tiles, roamer scatter on CONTINUE, trap volatiles + FORCESHINY
-  battle types (beast catching in section 32 is now mechanically possible), badge
-  boosts, held items, specialty balls (Lure Ball needs battleType 'fish', already
-  stamped by updateFishing).
-- NPC HOUR WINDOWS are now enforced (they were not when the Johto route was authored).
-  Any Kanto row that talks to a time-gated NPC must pin the clock (POKEPORT_GOLD_HOUR /
-  POKEPORT_GOLD_DAY) or handle absence. Only 11 hour-gated objects exist on the whole
-  cart: CELADON_GAME_CORNER 6/7, GOLDENROD_GAME_CORNER 4/5, MOUNT_MOON_GIFT_SHOP 1-4,
-  and the three Moms in PLAYERS_HOUSE_1F; Celadon and Mt Moon are the Kanto exposures.
-- The game clock now anchors on every new game (cart InitClock semantics), so time of
-  day no longer follows the host wall clock in driver runs; POKEPORT_GOLD_HOUR pins
-  the anchored base too. Runs are reproducible across day/night; a pre-existing flake
-  class (night runs catching HOOTHOOT where day runs catch PIDGEY, shifting grind
-  levels) died with it.
-- Battles hit harder both ways since the cart MIN_DAMAGE floor landed; grind budgets
-  tuned for the old numbers may need a nudge.
-
-## Known bot weaknesses to expect (verified pre-existing, not campaign regressions)
-
-- Pathfinding pocket: travel into ILEX_FOREST / SLOWPOKE_WELL bounces (probe
-  CHERRYGROVE_CITY>ILEX_FOREST reports no route), and route row 16.54 gives up the
-  walk to VICTORY_ROAD_GATE with the identical TELEPORT signature in every logged run.
-  Kanto routing should waypoint doors explicitly per the ops recipes above.
-- Optional buy rows 04.5d and 18.g4/18.g5 fail whenever the wallet is empty at that
-  point in the run; they are budgeting gaps in the route, not engine bugs.
-- Grind row 08.g (Route 41 water) has almost no margin; with the clock now anchored
-  its inputs are stable, but a low-level POLIWAG catch can still stretch it.
-
-## How to run things
-
-Identity/cache: gold-dev (~/Library/Application Support/LOVE/gold-dev/gold), rebuilt
-2026-08-09 with swarm/rock/roam tables. Checkpoints gold-ckpt-NN.lua exist per section;
-gold-ckpt-18-pristine.lua is the post-E4 seed. ROM: ../decprep/Pokemon - Gold
-Version.gbc. Cart source: ../pokegold (cite it in any hand-ported code).
-
-Headless love needs a pty on macOS; wrap every run:
-  perl -e 'alarm 900; exec @ARGV' python3 -c "import pty; pty.spawn(['love','.'])"
-
-Full bot run:  POKEPORT_IDENTITY=<id> POKEPORT_GAME=gold POKEPORT_SPEED=200 \
-  POKEPORT_GOLD_CKPT=1 POKEPORT_GOLD_STALL=20000 POKEPORT_GOLD_LOG=/tmp/b.log \
-  POKEPORT_DRIVER=tests/drivers/gold_bot.lua love .
-Resume a section: POKEPORT_GOLD_RESUME=NN (same identity, prior CKPT=1 run).
-Travel probe: POKEPORT_GOLD_PROBE="MAP_A>MAP_B" with tests/drivers/gold_travel_probe.lua.
-Map graph: luajit tools/goldwalk/mapgraph.lua path|map|reach|audit; regenerate
-tests/drivers/gold/map_regions.lua with `mapgraph.lua graph >` after ANY extractor map
-change, then re-check route region indices.
-Route validation (before any run): luajit tests/gold_route_validate_test.lua and
-luajit tests/gold_flag_names_test.lua.
-Suites: GOLD_CACHE="$HOME/Library/Application Support/LOVE/gold-dev/gold" luajit
-tests/gen2_<name>_test.lua; tiers run_engine/run_modkit/run_tests.
-Reimport after extractor/manifest changes: python3 tools/make_gold_manifest.py, then
-POKEPORT_IMPORT_TRACE=1 POKEPORT_IDENTITY=gold-dev POKEPORT_IMPORT_ROM="../decprep/\
-Pokemon - Gold Version.gbc" POKEPORT_IMPORT_ONLY=1 POKEPORT_FORCE_IMPORT=1 \
-POKEPORT_GAME=gold love .
-
-## Recommended shape of the work
-
-1. Extend tests/drivers/gold/route.lua with sections 19-32 (the row format, ops and
-   evidence rules are documented in the file head and bot.lua). Seed runs from
-   gold-ckpt-18-pristine plus the now-working post-credits CONTINUE. `expect` flags are
-   the only oracles; never make a row load-bearing on a soft-failing map.
-2. Highest-risk multi-map scripted chains first: S.S. Aqua voyage, Machine Part chain,
-   PASS/Magnet Train chain. Each deserves an assertion driver even if bot rows also
-   cover it.
-3. Time-gated beats (S.S. Aqua sailing days, Indigo rival Mon/Wed, Dragon's Den
-   Tue/Thu, Clefairy Monday night, TM03 night gate) need POKEPORT_GOLD_DAY/HOUR pins.
-4. Johto stragglers are folded in below (lighthouse descent, TM08 flake, and the
-   optional gift beats); they ride the same route-extension pass.
-5. Section 32 (beasts) last: it needs long roaming play; trap volatiles and FORCESHINY
-   landed this campaign, so Mean Look + Heavy/Fast Ball plans are now viable.
-
-## Also deferred (deliberate stubs, do not re-flag)
-
-Time Capsule trading, Trainer House CAL2/Mystery Gift visitor, Silver-version import,
-Cable Club link rooms, and Game Boy Printer output are deliberate product-level stubs,
-not campaign work.
-
-## The beats, in walkthrough order
-
-### Runtime coverage ends at the Hall of Fame: no bot row, driver, or human has run any Kanto beat (sections 19-32) or the section 14 Tin Tower/Whirl Islands content
-
-walkthrough section(s) 19,20,21,22,23,24,27,28,29,30,31,14 | missing
-
-One root cause: tests/drivers/gold/route.lua (1264 lines) ends at row 18.20 (settle HALL_OF_FAME, expect EVENT_BEAT_ELITE_FOUR); the campaign covers asm-walk sections 00-18 only and none of the 24/36 gold_* drivers reaches any Kanto map, so sections 19-32 have zero execution proof. Extend route.lua into sections 19-32 and/or add targeted drivers. Per section pair: (s19/20) next rows are the Elm ticket (needs the post-credits spawn fix or a fly detour from Indigo), the ship crossing as far as the docking events, the Surge fight, and a Saffron Gym pad-chain assertion. (s21/22) All 24 route/gym trainers resolve in cache with correct parties: Route 9 six (Edna, Sid, Dean, Sidney, Tim, Heidi); Route 25 seven plus Kevin, whose Nugget-then-battle script 50:488d is hand-shaped (a full bag aborts before the battle, cart behavior); Cerulean's three swimmers; Route 10 South's Jim and Robert (Robert's Quagsire holds a BERRY via TRAINERTYPE_ITEM); Route 8's five; Celadon Gym's five including the twins' shared beat flag. Sight-line engagement is Trainers.sees (proven by the Johto bot); prize money base x level x 4 is Prize.lua; Erika's class item extracts as HYPER_POTION (the walkthrough's 'three Full Restores' is a FAQ error, not a port gap); Gold-only wilds (Mankey line Route 9, Growlithe Routes 7/8) come from the ROM version branch; Route 8's PRZCureBerry fruit tree is a fruittree op (Vm.lua:1218) into Apricorns.lua daily reset. One Kanto smoke-run converts the whole block. (s23/24) Nothing touches Routes 11-19, Fuchsia City/gym, Vermilion Snorlax, Diglett's Cave, Route 2, Pewter; the report's three blocker findings (START menu row, Pokegear card flags, radio persistence) are exactly the UI-plumbing breaks data audits miss: a gold_snorlax_wake.lua that grants the gear and EXPN card the way the game does (setflag 4, setflag 0, setflag 3 through the VM, not by poking save fields), tunes the radio, closes the gear, and talks to the Snorlax would currently fail at three separate steps; gold_cycling_road.lua and gold_fuchsia_gym.lua are the other two cheap proofs (gold_menu_shots.lua:72-73 only ever hand-seeded save fields). (s27/28) Drive first: (1) Cinnabar Blue talk -> disappear -> clearevent 1910 -> Viridian Gym populated -> Blue beaten -> ENGINE_EARTHBADGE set -> VAR_BADGES answers 16 (a break anywhere makes the 16th badge unobtainable and the Mt. Silver gate unpassable); cache chain exists: CINNABAR_ISLAND obj 1 SPRITE_BLUE at (9,6) scriptKey 4e:4985 eventFlag 1909; VIRIDIAN_GYM objs 1-2 gated on 1910; (2) the ROUTE_20 MAPCALLBACK_NEWMAP 4e:4cfa setevent 215 / ROUTE_19 MAPCALLBACK_TILES 4e:4f09 changeblock unseal pair (regression walls off Route 19). Driver: surf Pallet -> Route 21 -> Cinnabar -> talk to Blue -> Route 20 -> beat Blaine -> fly to Viridian -> beat Blue. (s29/30) No rows for Kanto OAKS_LAB, ROUTE_22, ROUTE_28, SILVER_CAVE_OUTSIDE, or the Union Cave B2F Lapras revisit (route.lua's only Union Cave rows are 03.29/04.g); risk concentrates on composites never run together: the 16-badge Oak visit with ProfOaksPCBoot text chain, the double Cut approach to the Route 28 west strip, surf-to-talk on the drifting SWIM_WANDER Lapras (Lake of Rage Gyarados proves the shape via gold_lake_probe.lua), and the daily-flag consume-and-respawn cycle across a save reload; a targeted gold_lapras_probe driver (clockDay=5, walk in, assert object present, catch, walk out, re-enter, assert gone) plus route extension converts inspected to proven. (s31) All six Silver Cave maps decode (warps, item balls flags 1689-1693, hidden items, SILVER_CAVE_OUTSIDE flypoint callback, PALETTE_DARK on Room 1, grass/water tables including Room 2 water); Flash lifts PALETTE_DARK via Palettes.isDarkness + World flashUsed; Surf/Waterfall live in FieldMoves with the badge table; gen2 ledges landed via Permissions.ledgeFacings / World:tryLedgeJump (the asm-walk's 'ledge hop missing' row is stale, GOLD-NEXT-RUN records the fix); the flypoint is FieldMoves.lua:386 flag 75; but no driver has entered Silver Cave, used Waterfall on Room 2's two bands, hopped Room 1's Escape Rope ledge, or talked to Red (closest: gold_halloffame_shots, gold_hm07_probe which proved Waterfall only at Tohjo Falls). (s14) The bot covers sections 10,11,12,13,16,17,18 and never section 14 (Ho-Oh is optional); untested: the 4F-9F ladder/hop mazes (depend on the recently added ledge-hop and one-way-wall support), the Ecruteak entrance sage scene retarget from Morty's setmapscene, the 1F sage unmasking off EVENT_TEAM_ROCKET_DISBANDED (set on the Gold arm of the Radio Tower boss script), the roof save/reset loop, and the entire Gold-side Whirl Islands dive; needs one probe driver carrying a RAINBOW_WING save up the tower and one diving to the Lugia chamber.
-
-*How to prove it:* Extend tests/drivers/gold/route.lua past row 18.20 into sections 19-32, and/or write the named targeted drivers: gold_snorlax_wake.lua, gold_cycling_road.lua, gold_fuchsia_gym.lua, a gold_lapras_probe (clockDay=5 present/absent cycle), a Cinnabar-to-Viridian 16th-badge driver, a Route 20/19 unseal driver, a Silver Cave/Red driver, a Tin Tower RAINBOW_WING probe, and a Whirl Islands Lugia dive probe.
-
-*Notes:* Merged from the parent heading plus six 'Also filed as' sub-findings (all one cause). Doc's own ratings: parent missing/minor (s19,20, already in ledger); s21,22 unverified/minor; s23,24 unverified/minor; s27,28 missing/major; s29,30 unverified/minor; s31 unverified/minor; s14 unverified/minor. The adversarial re-check ran on the s27/28 sub-claim, tried to refute and could not; its one correction: tests/drivers/gold/flag_names.lua and map_regions.lua DO name the Kanto maps (map_regions even carries CINNABAR/SEAFOAM/VIRIDIAN region graphs, so bot travel there is data-ready) but they are lookup tables, not executed coverage. 'Implemented statically, executed by nobody' matches the project's Roamers/Events:restore failure mode. GOLD-WALK-HANDOFF sections 1 and 4 already document the Johto-only scope.
-
-
-### Olivine Port pier and Fast Ship boarding gate: the only road into Kanto, fully extracted, never executed
-
-walkthrough section(s) 19 | unverified
-
-Coord event at (7,15) (cache 5b:407d) does the full cart sequence: temporary-event bails, first-time bypass on event 48, readvar VAR_WEEKDAY branch, yesorno, checkitem S_S_TICKET (item 68), setevent 1, 7-step applymovement, sjump into gangway script 5b:401e which plays SFX, disappears/appears the sailor, runs special 46 = FadeOutToWhite (specialOrder[46+1], implemented Specials.lua:998), clears the eight eastbound EVENT_BEAT_* rematch flags on repeat trips, sets FAST_SHIP_1F scene 1, and warps to (25,1). Port sprite toggles for the post-Hall-of-Fame sailor (events 1847/1848) are armed by the HOF script. All data extracted, every op has a proven Johto call site; matched op-for-op against pokegold maps/OlivinePort.asm. Needs one live run or driver.
-
-*How to prove it:* A driver or bot section that reaches OLIVINE_PORT post-HOF with the S_S_TICKET, boards, and asserts the warp to FAST_SHIP_1F (25,1) with scene 1 set. No gold_* driver currently reaches OLIVINE_PORT post-HOF.
-
-*Notes:* Doc rating: unverified/blocker, new. If this chain fails, the walkthrough stops here (Kanto unreachable).
-
-
-### S.S. Aqua maiden voyage: trainer gauntlet, lazy sailor, granddaughter, Metal Coat, docking; extracted end to end, never run
-
-walkthrough section(s) 19 | unverified
-
-Verified in cache, never executed: FastShip1F enter scene 5b:48a8 sdefer 5b:48ad (SFX_BOAT, earthquake 30, blackoutmod to cabin map, clearevent 49, scene 2 on first trip); grandpa bump coord events at (24,6)/(25,6); maiden-trip trainer objects behind flag 1849 with parties matching data/trainers/parties.asm exactly (NOLAND Sandslash31/Golem33, LYLE Koffing28/Flareon31/Koffing28, COLIN Delibird32 holding BERRY, MEG&PEG, FRITZ Mr.Mime/Magmar/Machoke, JEFF 2x Raticate32, DEBRA Seaking33, STANLY Machop31/Machoke33/Psyduck26, all in trainers.lua); B1F blocking-sailor coord scripts 5b:5e0c/5b:5e21 plus shared talk script 5b:5e37 clearing event 1837 to spawn the lazy sailor; FastShipLazySailorScript 5b:4d68 (playmusic, loadtrainer SAILOR 9, reloadmap, special 27 = HealParty, setmapscene B1F NOOP, readvar VAR_FACING walk-out); bed script 5b:521b (HealParty, fades, ReloadSpritesNoPalettes, RestartMapMusic, dock check on events 49/50/48 so sleeping cannot dock the maiden voyage); granddaughter payoff 5b:55c6 (fade, disappear/moveobject/appear teleport, showemote, sjump 5b:5633 = Metal Coat verbosegiveitem plus EVENT_FAST_SHIP_HAS_ARRIVED/FOUND_GIRL); door guard 5b:48d2 with arrived arm 5b:48ec (scall facing arm, setmapscene VERMILION_PORT scene 1, warp to VERMILION_PORT 7,17). Specials 27/46/47/49/50/60 resolve to HealParty/FadeOutToWhite/FadeOutToBlack/FadeInFromBlack/ReloadSpritesNoPalettes/RestartMapMusic, all implemented. Nothing in the chain touches a stubbed special, callasm, or VAR. Matched against pokegold maps/FastShip*.asm.
-
-*How to prove it:* A bot section or driver for the full crossing (board, fight or dodge the gauntlet, sleep check, granddaughter Metal Coat, dock at VERMILION_PORT 7,17).
-
-*Notes:* Doc rating: unverified/blocker, new. If any link breaks, arrival in Kanto is impossible.
-
-
-### Machine Part quest chain (Power Plant manager, Cerulean Gym grunt scene, Route 24 grunt, part return, TM07) never executed
-
-walkthrough section(s) 21,22 | unverified
-
-The spine of sections 21-22: manager talk sets EVENT_MET_MANAGER_AT_POWER_PLANT 202, clears EVENT_CERULEAN_GYM_ROCKET 1901 and EVENT_FOUND_MACHINE_PART_IN_CERULEAN_GYM 251, arms CERULEAN_GYM scene 1 and the POWER_PLANT guard phone-call scene; grunt runs out of the gym (sets 203, clears 1900/1902, arms ROUTE_25 scene 1); beat the Route 24 grunt (GRUNTM 31, L30 Golbat); return the part for TM07 Zap Cannon plus EVENT_RESTORED_POWER_TO_KANTO 205 and the Saffron station population flip (clears 1906). Statically verified: cache holds full bytecode for PowerPlantManager 54:4dbd with both branches (54:4deb takeitem MACHINE_PART / 54:4e04 TM give guarded by event 223), gym scene script 54:4332 sdefer 54:4336 with all 34 rows, Route 24 grunt script 50:4407; initial_events.lua seeds flags 251/1900/1901/1902/1903/1906/1907 at new game exactly as InitializeEventsScript does (pokegold engine/events/std_scripts.asm:546-550); World.lua:607 applies the seed while EVENT_INITIALIZED_EVENTS is clear. Engine deps all have call sites: World:trySceneScript (World.lua:5369, called at :6893), setmapscene/setscene (Vm.lua:274-284), specials RestartMapMusic/FadeOutToBlack/FadeInFromBlack/ReloadSpritesNoPalettes/FadeOutMusic (Specials.lua:999-1072). Missing only run-time proof: route bot covers sections 00-18, no Kanto driver exists.
-
-*How to prove it:* Route extension or a driver walking manager -> gym grunt scene -> Route 24 grunt battle -> part return, asserting events 202/203/205 set and 1900/1901/1902/251/1906 cleared and TM07 in bag.
-
-*Notes:* Doc rating: unverified/blocker, new.
-
-
-### Route 25 Misty date scene, Cerulean gym population, and Misty fight never executed (and Misty gives no TM, contrary to walkthrough)
-
-walkthrough section(s) 21 | unverified
-
-The date cutscene at Route 25 cells (42,6)/(42,7) is what clears EVENT_TRAINERS_IN_CERULEAN_GYM 1903 and populates the gym with Misty, three swimmers, and the guide; without it Misty never appears and the Cascade Badge is unreachable. Cache has both coord events with sceneId=1 (scripts 18305/18369) and full scripts 50:4781/50:47c1 (34-row cutscene: heart emote, boyfriend flees, Misty approach movement, clearevent 1903, setscene 0, special 60=RestartMapMusic), armed by gym grunt script 54:4336 row 27 (setmapscene group=7 map=16 scene=1). Engine deps: World:tryCoordScript (World.lua:5006) filters on the map scene id; mapScenes persist on the save (GOLD-INDEX tier note on World:loadPlayerData). CeruleanGymMistyScript 54:438a is in the cache; MISTY trainer 1 party (L42 Golduck, L42 Quagsire, L44 Lapras, L47 Starmie with full movesets) extracts correctly; baseMoney 25 so the 4700G payout follows from Prize.reward.
-
-*How to prove it:* Driver: arm the scene via the gym grunt, trigger the date coord event at (42,6)/(42,7), assert 1903 cleared and the gym populated, then fight Misty and assert the Cascade Badge and 4700G.
-
-*Notes:* Doc rating: unverified/blocker, new. Correction embedded in the doc: Misty gives NO TM on the Gold cart, only the badge plus retroactive swimmer beat flags; the walkthrough and the lead's 'TM from Misty' are wrong about the cart, nothing is missing in the port there.
-
-
-### PASS quest: Copycat lost item and Fan Club doll chain fully extracted, never run
-
-walkthrough section(s) 22 | unverified
-
-Copycat (COPYCATS_HOUSE_2F object 1, variable sprite slot 251) talk after the machine part return sets EVENT_MET_COPYCAT_FOUND_OUT_ABOUT_LOST_ITEM 206; Fan Club Clefairy guy (POKEMON_FAN_CLUB object 3, script 59:437b) then gives LOST_ITEM 130 and disappears the doll (flag 1908, correctly NOT in the initial seed; doc evidence line also cites POKEMON_FAN_CLUB object 5 flag 1908); returning it (Copycat branch 61:528b: takeitem 130, setevent 208, clearevent 1907 to re-show her shelf doll, then PASS 134 via 61:529d) yields the PASS. All bytecode in cache (61:5235/61:5270/61:528b); the mimicry gag's variablesprite slot 11 plus special 93 resolves to LoadUsedSpritesGFX (specialOrder[94], Specials.lua:1033); the Copycat's variable sprite slot is seeded through World.initialSprites/findInitialSprites (World.lua:1530, the fix GOLD-INDEX credits for the Copycat existing at all). Flag 1907 is in the initial seed so the shelf doll is hidden until the return; 1906 is seeded so the Saffron station stays empty until power is restored.
-
-*How to prove it:* Driver: after machine-part return, talk to Copycat (assert 206), get LOST_ITEM at the Fan Club (assert doll flag 1908 set), return it (assert 208 set, 1907 cleared, PASS 134 in bag).
-
-*Notes:* Doc rating: unverified/major, new. Correction embedded: the walkthrough's 'Rail Pass then Magnet Train Pass' is one item (PASS) on the cart, not a port gap. Merge-with hint: the s20 entry 'Copycat lost doll quest chain toward the rail PASS' (copycat-doll-pass-s20) describes the same quest from the section-20 audit with slightly different event ids cited (210/201 gate checks there vs 206/208 here).
-
-
-### Magnet Train ride wired end to end; arrival behavior needs a human eye, never ridden since
-
-walkthrough section(s) 22 | unverified
-
-SaffronMagnetTrainStationOfficerScript (cache 61:4bc2/61:4bd0, rows 11-14) checks EVENT_RESTORED_POWER_TO_KANTO 205 then checkitem PASS 134, does setval 1, special id=35 which resolves to MagnetTrain (specialOrder[36]), then warpcheck and newloadmap 249 (MAPSETUP_TRAIN). All implemented: H.MagnetTrain (Specials.lua:2119) reads scriptVar for direction and blocks on World:magnetTrain (World.lua:2393) which pushes Gen2MagnetTrainRide; Vm handles warpcheck (:1135) and newloadmap (:1177); MAPSETUP_TRAIN defined at World.lua:175. Gating events (205 set by the Power Plant manager, PASS from the Copycat) are this section's other findings.
-
-*How to prove it:* WHATS-NEXT item 8: a human rides both ways and presses a direction on arrival; the conversation must start on the first step because south is the only legal step out of the doorway cell. Nothing has run this since.
-
-*Notes:* Doc rating: unverified/major, already named in the ledger.
-
-
-### Silver Wing in Gold: Pewter City gramps script extracted, but Kanto (and the Whirl Islands dive) never run
-
-walkthrough section(s) 14 | unverified
-
-For a Gold cart, Lugia needs the SILVER_WING carried in the bag (WhirlIslandLugiaChamberLugiaCallback does checkevent EVENT_FOUGHT_LUGIA then checkitem SILVER_WING), and in Gold the wing comes from the Pewter City gramps (pokegold maps/PewterCity.asm PewterCityGrampsScript: checkver, Silver arm branches away, Gold falls through to verbosegiveitem SILVER_WING + setevent). Verified in cache: PEWTER_CITY object 3 (SPRITE_GRAMPS at 29,17) scriptKey 4d:583e = faceplayer / opentext / checkver / iftrue 4d:585c / checkevent 121 / verbosegiveitem item 71 / setevent 121 / closetext / end, all generic opcodes. The Lugia chamber map, its SPRITE_LUGIA object (scriptKey 47:41a0, eventFlag 1853), and its MAPCALLBACK_OBJECTS callback (47:418c) are in the cache using only implemented machinery. Route bot has no section 14/25 rows (grep 'id = "1[0-9]' shows 10,11,12,13,16,17,18). One mechanical gap on the dive path: the waterfall forced-down item, reported separately in the doc.
-
-*How to prove it:* Driver or bot rows: reach Pewter in Gold, talk to the gramps (assert SILVER_WING item 71 given, event 121 set), then the full Whirl Islands dive to the Lugia chamber.
-
-*Notes:* Doc rating: unverified/major, new. The waterfall forced-down item on the dive path is a separate finding elsewhere in the doc, not part of this entry.
-
-
-### Vermilion Port arrival bookkeeping, Vermilion flypoint, and Kanto music never executed
-
-walkthrough section(s) 19 | unverified
-
-Arrival scene (VERMILION_PORT scene 1, sdefer 5b:450e) extracted intact: one step up, appear the gangway sailor, setscene 0, end-of-voyage flags (1841/1840 hide grandpa and granddaughter for good, 1849 retires the maiden-trip trainers, clear 1843 to reveal the Olivine passage Pokefan, set 48 EVENT_FAST_SHIP_FIRST_TIME), and blackoutmod VERMILION_CITY. ENGINE_FLYPOINT_VERMILION comes from MAPCALLBACK_NEWMAP on both VERMILION_PORT and VERMILION_CITY (setflag 57); the port's fly table carries the matching row (FieldMoves.lua:392) and World:runMapCallback has a live call site (World.lua:5659 plus the MAPCALLBACK_OBJECTS call in setMap). Fly deliberately stays region-locked exactly like the cart (FieldMoves.flyPoints, FieldMoves.lua:442: Kanto page only after SPAWN_INDIGO, no cross-region fly, verified against pokegold engine/pokegear/pokegear.asm .KantoFlyMap). Kanto music extracted: audio.lua songs has 92 entries, musicOrder includes Music_VermilionCity and Music_ViridianCity (musicOrder[63]=Music_VermilionCity), mapSongs carries all 362 map rows.
-
-*How to prove it:* Driver: dock at Vermilion, assert flags 1841/1840/1849/48 set and 1843 cleared, flypoint flag 57 set on map entry, and Vermilion/Viridian city music playing.
-
-*Notes:* Doc rating: unverified/major, new.
-
-
-### Pokemon Fan Club chairman Rare Candy give never run
-
-walkthrough section(s) 19 | unverified
-
-Chairman script 59:4340: checkevent 212 (already heard), checkevent 211 (bag-full retry), yesorno where answering No gives nothing (cart behavior), two promptbutton speech pages, verbosegiveitem item 32 = RARE_CANDY, setevent 212. The cart quirk that nothing ever sets the bag-full retry event 211 is faithfully carried in the extracted bytecode. Same map also holds the Clefairy doll object (flag 1908) and Clefairy Guy script 59:437b that the later Copycat quest reads. yesorno, verbosegiveitem, and multi-page writetext all have proven Johto call sites. Matched against pokegold maps/PokemonFanClub.asm; RARE_CANDY present in items.lua.
-
-*How to prove it:* Covered by any Kanto smoke-run that talks to the chairman and asserts RARE_CANDY given and event 212 set.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Lt. Surge gym: trainers, Thunder Badge, AI item use fully extracted, never fought
-
-walkthrough section(s) 19 | unverified
-
-Surge script 59:4bfc: checkflag 36 re-fight guard, loadtrainer class 19 member 1, winlosstext, reloadmapafterbattle (whose loss-abort semantics were fixed during the Johto campaign), retroactive setevent of the three gym trainers, setflag 36 = ENGINE_THUNDERBADGE which routes to save.player.kantoBadges.THUNDER. Parties in trainers.lua match data/trainers/parties.asm exactly: Surge is RAICHU44/ELECTRODE40/MAGNETON40/ELECTRODE40/ELECTABUZZ46 with full TRAINERTYPE_MOVES movesets; Vincent, Horton, Gregory all match (GUITARIST 2/JUGGLER 3/GENTLEMAN 3). Trainer AI item use implemented: Ai.ITEM_ORDER/Ai.chooseItem (Ai.lua:1368-1400) dispatched from Battle.lua:1790 (AI_SwitchOrTryItem) off the extracted class attributes. The gym has no puzzle in Gen 2, matching the walkthrough's power-outage line.
-
-*How to prove it:* Driver or route rows: fight the gym trainers and Surge, assert ENGINE_THUNDERBADGE (flag 36) set into save.player.kantoBadges.THUNDER and the AI HYPER_POTION use path exercised.
-
-*Notes:* Doc rating: unverified/major, new. Correction embedded: the walkthrough's claim that Surge holds a Full Restore is a FAQ error; pokegold data/trainers/attributes.asm line 114 (block 113-117) gives the Lt Surge class HYPER_POTION and the cache carries exactly that (LT_SURGE items=HYPER_POTION, baseMoney 25).
-
-
-### Route 6 Underground Path blocker and Saffron gate guard extracted, never walked
-
-walkthrough section(s) 20 | unverified
-
-The walkthrough's 'large man who blocks the entire entrance' is the ROUTE6_POKEFAN_M object at (17,4) whose event flag EVENT_ROUTE_5_6_POKEFAN_M_BLOCKS_UNDERGROUND_PATH hides him only when SET (set by the Power Plant script in a later section); the port's object-visibility rule 'flag set hides object' is implemented and documented at Events.lua:1-2, and his script is a bare jumptextfaceplayer about the Power Plant. The Route 6 Saffron gate guard at (0,4) stands off the walking lane and is dialogue only (branches on EVENT_RETURNED_MACHINE_PART). ROUTE_6 grass and water encounter tables (Abra/Magnemite slots) are present in encounters.lua. Nothing gated on engine work; it has just never been walked.
-
-*How to prove it:* Covered by any Kanto walk through Route 6 before and after the Power Plant script sets the blocker flag.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Mr. Psychic's TM29 Psychic give extracted verbatim, Kanto walk to the door unproven
-
-walkthrough section(s) 20 | unverified
-
-Cache 61:4b15: checkevent 227, writetext, promptbutton, verbosegiveitem item 221 = TM_PSYCHIC_M, iffalse full-bag fall-through WITHOUT setting the flag (cart behavior, re-talk after making room), setevent 227. TM_PSYCHIC_M is in items.lua with pocket TM_HM and price 2000; the four-pocket bag and TM teaching were exercised in the Johto run (TM08 ROCK SMASH teach passed on merit per GOLD-WALK-HANDOFF). Matched against pokegold maps/MrPsychicsHouse.asm.
-
-*How to prove it:* Any Kanto run that walks to the house, talks, and asserts TM29 given and event 227 set (plus the full-bag retry arm).
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Silph Co. 1F Up-Grade give extracted, never run
-
-walkthrough section(s) 20 | unverified
-
-Cache 61:4f81: same shape as Mr. Psychic, verbosegiveitem item 172 = UP_GRADE guarded by event 222 with the full-bag fall-through. The officer at (13,1) has event flag -1 so he never moves, and SILPH_CO_1F has only the two street-door warps: there is no upstairs in Gen 2, so the 'man blocking the stairway' never opens, matching the cart (verified against pokegold maps/SilphCo1F.asm). Generic mechanisms only. UP_GRADE present in items.lua.
-
-*How to prove it:* Any Kanto run that enters Silph Co. 1F and asserts UP_GRADE given behind event 222.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Saffron Gym teleporter maze (30 same-map warp pads) never exercised; same-map warp chains untested anywhere
-
-walkthrough section(s) 20 | unverified
-
-The gym's whole puzzle is 30 warp pads (cache SAFFRON_GYM warps 3-32) that all target SAFFRON_GYM itself; the only route to Sabrina is entrance pad (11,15) -> ... -> (1,5) -> (11,9). The engine mechanism exists and reads correct: pads are COLL_WARP_PANEL 0x7c, an immediate warp (Permissions.lua:311); World:takeWarp (World.lua:6022-6040) handles a destination equal to the current map through setMap; warpCooldown keyed on the landing cell (World.lua:6135 set, 6217-6222, 6240 suppression check) stops the landing pad from re-firing until the player steps off, exactly what a pad-to-pad maze needs. But the asm-walk's own port-coverage table flags that no driver has ever exercised a same-map warp chain, and no Kanto run exists. If this breaks, Sabrina is unreachable and the 10th badge (and eventually Red's gate) is lost.
-
-*How to prove it:* Targeted driver: enter the gym, ride pad (11,15), assert arrival at (19,17), then the full 5-hop chain to (11,9).
-
-*Notes:* Doc rating: unverified/major, new.
-
-
-### Sabrina battle and Marsh Badge fully extracted, never fought
-
-walkthrough section(s) 20 | unverified
-
-Sabrina script (cache 61:40cf): checkflag 39 guard, loadtrainer class 35 member 1, reloadmapafterbattle, force-sets the four gym trainer flags (so the trainers are skippable, as the walkthrough implies), setflag 39 = ENGINE_MARSHBADGE routed to save.player.kantoBadges.MARSH. Party matches the cart exactly (trainers.lua SABRINA 1: ESPEON46 Sand-Attack/Quick Attack/Swift/Psychic, MR__MIME46 Barrier/Reflect/Baton Pass/Psychic, ALAKAZAM48 Recover/Future Sight/Psychic/Reflect; class item HYPER_POTION, base reward 25, AI attribute words extracted; attributes.asm:209-213). The four trainers (Rebecca, Franklin, Doris, Jared; MEDIUM 6,7 / PSYCHIC_T 2,11; parties verified including the cart's L35 third Exeggcute that the FAQ gets wrong) are OBJECTTYPE_TRAINER with SPINRANDOM movement, which Npc.lua supports, and sight/battle handoff is the proven Trainers.lua path. Prize money base x last-level x4 is implemented in Prize.lua (matches the walkthrough's 4800G).
-
-*How to prove it:* Driver through the warp maze to Sabrina; assert ENGINE_MARSHBADGE (flag 39) into save.player.kantoBadges.MARSH, the four trainer flags force-set, and the 4800G payout.
-
-*Notes:* Doc rating: unverified/major, new. Corrections embedded: the L35 third Exeggcute is cart-correct (the FAQ is wrong); Sabrina's class item is HYPER_POTION.
-
-
-### Copycat lost doll quest chain toward the rail PASS (section-20 filing): all pieces present and generic, never run
-
-walkthrough section(s) 20 | unverified
-
-Spans this section's maps (Copycat's house is Saffron warp 8, the doll source is the Vermilion Fan Club) though the walkthrough text defers it to after the Power Plant (EVENT_RETURNED_MACHINE_PART gates the dialogue arms). Copycat's 2F object uses variable sprite 251 (SPRITE_COPYCAT), and the new-game variablesprite seeding that used to leave Copycat despawned was fixed during the Johto campaign (tests/gen2_variable_sprites_test.lua, GOLD-WALK-HANDOFF section 5); her script (cache 61:5235) is extracted bytecode whose only special, LoadUsedSpritesGFX, is implemented (Specials.lua:1033); the Fan Club Clefairy Guy (59:437b) checks events 210/201 and gives LOST_ITEM; the doll object (flag 1907) and the PASS handover (verbosegiveitem PASS, setevent EVENT_GOT_PASS_FROM_COPYCAT per pokegold maps/CopycatsHouse2F.asm:61-73) are ordinary ops; PASS is a KEY_ITEM in items.lua. Nothing engine-shaped is missing.
-
-*How to prove it:* Same driver as the s22 PASS quest entry: full Copycat/Fan Club round trip asserting LOST_ITEM, doll flags, and PASS.
-
-*Notes:* Doc rating: unverified/minor, new, named in the leads. Merge-with hint: same quest chain as pass-quest-copycat-fanclub (s22); kept separate because the doc filed them as distinct headings from two section audits. This filing cites Clefairy Guy gate events 210/201 and doll flag 1907; the s22 filing cites 206/208 and doll-disappear flag 1908.
-
-
-### Celadon side items: TM03 Curse night gate, Leftovers trash can, hidden PP Up (plus Berserk Gene, Route 9 Ether, Route 25 Potion) never run
-
-walkthrough section(s) 22 | unverified
-
-TM03 Curse: roof house pharmacist script 5e:5083 in cache with checktime mask 4 (NITE) at row 7; the Vm checktime opcode (Vm.lua:788) maps NITE to bit 4 off World:timeOfDayId, so the night-only gate should behave; the give branch 5e:509a is guarded by EVENT_GOT_TM03_CURSE 218. Leftovers: CeladonCafeTrashcan bg event at (7,1) key 5e:648c present, plain giveitem bytecode with the flag only set on success so a full pack retries, exactly the cart. Hidden PP Up at Celadon (37,21): BGEVENT_ITEM row present, handled by HiddenItems (fixed PP_UP; the walkthrough's 'random PP Up' is wrong on the cart too). Berserk Gene at Cerulean (2,12), hidden Ether Route 9 (10,5), and hidden Potion Route 25 (4,5) likewise extract. All generic and statically sound, none ever run.
-
-*How to prove it:* Kanto run collecting each: night visit for TM03 (checktime NITE), cafe trash can Leftovers with full-pack retry, hidden-item picks via HiddenItems.
-
-*Notes:* Doc rating: unverified/minor, new. Correction embedded: the PP Up is fixed, not random, on the cart.
-
-
-### Mt. Moon Square Clefairy dance (Monday night) + hidden Moon Stone + Rock Smash rock: all dependencies present, sequence never executed
-
-walkthrough section(s) 26 | unverified
-
-Coord event at (7,11) scene 0 runs 5b:676a, whose 45 rows extract completely: checkflag 87 (ENGINE_MT_MOON_SQUARE_CLEFAIRY), readvar var 11 (VAR_WEEKDAY, real in the port) ifnotequal 1 (MONDAY), checktime NITE, then the appear/follow/applymovement/cry/showemote dance, clearevent 236 (the hidden Moon Stone flag) and setflag 87. Both callbacks extracted (type 5 NEWMAP 5b:6763 re-hides the stone on entry; type 2 OBJECTS 5b:6767 hides the rock). The rock object (SPRITE_ROCK at 7,7, scriptKey 5b:67ee = jumpstd SmashRockScript) resolves to the real SmashRock/AskRockSmash bodies GOLD-INDEX.md:377-382 documents; follow/stopfollow are implemented (Vm.lua:1009,1026). Flag semantics match the cart: ENGINE_MT_MOON_SQUARE_CLEFAIRY lives in wDailyFlags2 (pokegold constants/engine_flags.asm:105-106) and the port clears id 87 in Apricorns.DAILY_ENGINE_FLAGS, so the dance is once per day, i.e. once per Monday night. Unproven in-game: (a) whether the appeared rock correctly blocks/receives the A press on the Moon Stone tile at (7,7) and Rock Smash then exposes the hidden item in the same visit, and (b) the full follow-chain animation. The stubbed RockMonEncounter (CallAsm STUB_ROWS) does NOT affect this rock: MOUNT_MOON_SQUARE is not in the cart's RockMonMaps (pokegold data/wild/treemon_maps.asm:43-48), so no encounter roll is owed here.
-
-*How to prove it:* Driver: force clockDay=MONDAY clockHour=NITE, walk to (7,11), watch the dance, smash the rock, take the Moon Stone.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Rival re-encounters after Mt Moon (Indigo Plateau Mon/Wed rematch, Dragon's Den Tue/Thu cameo) never run
-
-walkthrough section(s) 26 | unverified
-
-Both beats are pure extracted content keyed on EVENT_BEAT_RIVAL_IN_MT_MOON (set by the implemented Mt Moon script) and VAR_WEEKDAY (real in the port; World:readVar VAR_WEEKDAY at World.lua:1289): the cache carries INDIGO_PLATEAU_POKECENTER_1F's NEWMAP callback 5a:48b6 (23 rows of setmapscene/clearevent resets) plus its two coord events, and DRAGONS_DEN_B1F's callback 47:44e1 (checkevent 793 -> disappear object 4). The daily rematch flag ENGINE_INDIGO_PLATEAU_RIVAL_FIGHT (id 92) is in Apricorns.DAILY_ENGINE_FLAGS so it clears on the daily rollover. The rematch parties RIVAL2 members 4-6 (L45-50 with CROBAT) are in trainers.lua. Nothing looks missing, but the coord-event choreography in the Pokecenter (rival walks in as you leave) is the kind of scene worth a driver before trusting; filed unverified rather than implemented for that reason.
-
-*How to prove it:* Driver: set EVENT_BEAT_RIVAL_IN_MT_MOON via the Mt Moon fight, force weekday Monday/Wednesday, enter the Indigo lobby and assert the rematch triggers; force Tuesday/Thursday and assert the Dragon's Den object 4 state.
-
-*Notes:* Doc rating: unverified/minor, new. Merge-with hint: overlaps indigo-lobby-rival-rematch (s18), the same Indigo Plateau rematch filed from the section-18 audit; that filing cites World:weekday at World.lua:1247 and scriptKeys 5a:48ff/5a:4940.
-
-
-### Indigo lobby rival rematch (Monday/Wednesday, RIVAL2, post Mt. Moon) armed on tiles the walkthrough crosses, never run
-
-walkthrough section(s) 18 | unverified
-
-Not in the walkthrough text but armed on the lobby tiles it crosses: coord events at (16,4)/(17,4) run PlateauRivalBattle1/2 (cache scriptKeys 5a:48ff/5a:4940), which fight the RIVAL2 second-tier party when EVENT_BEAT_RIVAL_IN_MT_MOON is set, ENGINE_INDIGO_PLATEAU_RIVAL_FIGHT is clear, and VAR_WEEKDAY is Monday or Wednesday (pokegold maps/IndigoPlateauPokecenter1F.asm). Every dependency exists: coord events and scripts extracted, VAR_WEEKDAY answers the real weekday (World:weekday, World.lua:1247), the daily engine flag is registered for midnight reset (Apricorns.lua:88, id 92 ENGINE_INDIGO_PLATEAU_RIVAL_FIGHT), and RIVAL2 parties 4-6 (SNEASEL/45, CROBAT/48, MAGNETON/45, GENGAR/46, ALAKAZAM/46, starter/50) are in the trainers cache. But the gate flag EVENT_BEAT_RIVAL_IN_MT_MOON is Kanto content no run has ever set.
-
-*How to prove it:* Should be picked up when section 26 is audited/run: same driver as rival-rematch-mtmoon, entering the lobby on Monday/Wednesday with the Mt Moon flag set and asserting the coord-event battle fires.
-
-*Notes:* Doc rating: unverified/minor, new. Merge-with hint: same beat as rival-rematch-mtmoon (s26); kept separate because the doc filed both headings. Line-cite difference between filings: World.lua:1247 (weekday) here vs World.lua:1289 (readVar VAR_WEEKDAY) there.
-
-
-### Lighthouse descent and swim to Cianwood (route rows 08.50/08.51) never walked; collision data matches the cart, blame points at the bot's region graph
-
-walkthrough section(s) 08 | unverified
-
-The route bot has never completed the descent from Jasmine to Route 40, so the Surf crossing, all fourteen Route 40/41 swimmers, and Cianwood arrival are engine-unwalked (runs reach section 08+ by teleport; run 28 still failed rows 08.50/08.51). The handoff narrows it to the 3F seven-cell pocket: warps 8/9 at (8,3)/(9,3) 'do not take' when stood on. Verified in the current cache: OLIVINE_LIGHTHOUSE_3F (8,3)/(9,3) decode to COLL_FLOOR 0x00, and pokegold data/tilesets/lighthouse_collision.asm block $27 is FLOOR,FLOOR,FLOOR,FLOOR, so those two warp rows are one-way landing anchors for the 4F pits at (8,3)/(9,3) (which decode to COLL_PIT 0x60) and never fire on the cart either. The pocket's real exit is warp 3, the staircase at (9,5), which decodes to 0x72 and does fire ((13,3) also 0x72). Fix shape: correct the bot's region graph, which treats landing-anchor warp coordinates as exits (the exact trap GOLD-WALK-HANDOFF.md:593 documents), not the engine; a human following the walkthrough (drop beside Connie, fight Terrell, take the Ether, head up the stairs) uses the (9,5) staircase and should be fine.
-
-*How to prove it:* Something must walk 6F down to CIANWOOD_CITY in the engine (bot rows 08.50/08.51 passing, or a driver doing the descent and the Route 40/41 Surf crossing); until then the second half of section 08 stays a beat-completeness check rather than a proven path.
-
-*Notes:* Doc rating: unverified/major, already named in the ledger. The doc's own re-check corrected the suspicion of an engine defect: the cache collision matches the cart exactly, so the failing rows indict the bot's region graph, not the engine or the warp data.
-
-
-### TM08 Rock Smash give (route row 06.21) flaky across runs; ledger contradicts itself and the failure is unresolved
-
-walkthrough section(s) 06 | unverified
-
-The Route 36 fisher gives TM08 after EVENT_FOUGHT_SUDOWOODO (Route36RockSmashGuyScript, generic extracted bytecode with verbosegiveitem guarded by iffalse .NoRoomForTM). The ledger contradicts itself across runs: GOLD-WALK-HANDOFF section 8 says 'Everything before it now passes on merit: Sudowoodo, TM08, the ROCK SMASH teach', but run 28's failure table lists '06.21 ROUTE_36 EVENT_GOT_TM08_ROCK_SMASH not set' while the Sudowoodo row itself passed. Plausible causes: full TM pocket taking the iffalse arm, or the bot failing to stand adjacent. The script path is generic and the same give shape works everywhere else, so this is most likely route flake, but it is unresolved in the latest continuous run and TM08 gates all Rock Smash content downstream (Burned Tower rocks, Route 40/Cianwood rock items).
-
-*How to prove it:* Re-run route row 06.21 in a continuous run and assert EVENT_GOT_TM08_ROCK_SMASH gets set; instrument for TM-pocket fullness and adjacency to distinguish the two suspected causes.
-
-*Notes:* Doc rating: unverified/minor, already named in the ledger. Not given severity unverified-risk because the problem is a reproduced-once run failure (a live flake), not purely never-executed content.
-
-
-### New Bark rival push scene (talk to rival by the lab) unproven; low risk, zero coverage
-
-walkthrough section(s) 00 | unverified
-
-Walkthrough: 'If you talk to him, he'll push you out of the way.' NewBarkTownRivalScript is optional, repeatable (sets no flag) and uses follow PLAYER, applymovement with turn_head/step/fix_facing/jump_step, and SFX_TACKLE. Every opcode involved is implemented (follow/stopfollow in the VM, jump_step in Movement.lua which the ledge fixes exercised), and the sibling teacher-drag scene has a dedicated driver (tests/drivers/gold_teacher_scene.lua), but no driver or test touches this specific scene and the route bot never talks to optional NPCs. Cache maps.lua NEW_BARK_TOWN objects include the rival with a scriptKey and eventFlag.
-
-*How to prove it:* A short driver that talks to the rival by the lab and observes the push movement chain, mirroring gold_teacher_scene.lua.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Kiyo battle and Tyrogue gift (Mount Mortar B1F): fully wired, never exercised by any driver or bot run
-
-walkthrough section(s) 15 | unverified
-
-The game's only Tyrogue. Cache scripts['46:5eec'] holds all 29 rows of MountMortarB1FKiyoScript (checkevent 97 / 1193, winlosstext, loadtrainer class BLACKBELT_T member 6, startbattle, reloadmapafterbattle, setevent 1193, readvar var=1 VAR_PARTYCOUNT, ifequal 6, givepoke species 236 level 10, setevent 97); trainers cache has BLACKBELT_T[6] KIYO = L34 HITMONLEE + L34 HITMONCHAN (KIYO object at 13,4 with scriptKey 46:5eec); readvar VAR_PARTYCOUNT is a real read (World.lua:1271); givepoke is implemented at Vm.lua:443. The full dependency chain has never run: Surf across the 1F Outside lake, the in-cave Waterfall climb to warp 4 at (17,5), the 2F/1F-inside/B1F warp descent, the battle, and the gift. The waterfall climb mechanic itself is bot-verified only at Tohjo Falls; route.lua contains no MORTAR/KIYO/DARK_CAVE rows.
-
-*How to prove it:* A Mount Mortar driver: Surf the outside lake, Waterfall to warp 4 (17,5), descend to B1F, beat Kiyo, assert Tyrogue (species 236, L10) given with a party of <6 and events 97/1193 set.
-
-*Notes:* Doc rating: unverified/major, new. Correction embedded: GOLD-INDEX's claim that only VAR_WEEKDAY and VAR_FACING answer readvar is STALE; World.lua:1265-1330 now answers essentially every VAR_*.
-
-
-### Blackglasses pharmacist in Dark Cave Blackthorn entrance extracted exactly, never run (same for TM13 Snore and Revive balls)
-
-walkthrough section(s) 15 | unverified
-
-The script is fully extracted (cache scripts['47:436c'], 13 rows matching pokegold maps/DarkCaveBlackthornEntrance.asm exactly: checkevent / verbosegiveitem / iffalse pack-full arm / setevent), the spinning NPC object (SPRITE_PHARMACIST) is in the cache at (7,3) with that scriptKey, and verbosegiveitem is implemented in the VM. Reaching him also needs Flash plus Surf inside the cave, both implemented. The same unverified state covers the TM13 Snore and Revive item balls beside him (item ball arm is implemented and tested). No driver enters Dark Cave and the bot route bypasses it (grep DARK_CAVE in route.lua is empty).
-
-*How to prove it:* A Dark Cave driver: Flash + Surf to the Blackthorn entrance, talk to the pharmacist (assert Blackglasses given), pick up TM13 Snore and the Revives.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Master Ball from Elm after eighth badge: route rows exist but optional, no run log confirms the event ever set
-
-walkthrough section(s) 16 | unverified
-
-ProfElmScript's ElmCheckMasterBall gate is checkflag ENGINE_RISINGBADGE then verbosegiveitem MASTER_BALL then setevent EVENT_GOT_MASTER_BALL_FROM_ELM (pokegold maps/ElmsLab.asm:57-61). All generic extracted bytecode; checkflag over ENGINE_* badges works since the badge-store fix (GOLD-WALK-HANDOFF.md:502, badges routed into save.player.badges). The route bot has rows 16.24/16.24b for this beat but both are marked optional = true, and no run log or handoff note confirms EVENT_GOT_MASTER_BALL_FROM_ELM was ever actually set in a live run (no MASTER hits in GOLD-NEXT-RUN.md run logs). A full bag silently skips the setevent (verbosegiveitem iffalse), same as the cart.
-
-*How to prove it:* Make route rows 16.24/16.24b non-optional (or run them) and assert EVENT_GOT_MASTER_BALL_FROM_ELM set with bag space available.
-
-*Notes:* Doc rating: unverified/major, new.
-
-
-### Everstone from Elm by showing a self-hatched Togepi: pieces individually proven, full chain never exercised end to end
-
-walkthrough section(s) 16 | unverified
-
-The gating special FindPartyMonThatSpeciesYourTrainerID is a real handler with the own-OT check (Specials.lua:1134), and the phone-call prerequisite is NOT required: pokegold maps/ElmsLab.asm ElmCheckTogepiEgg -> EVENT_TOGEPI_HATCHED -> ElmEggHatchedScript re-runs the same species scan, so a hatched Togepi in the party is sufficient (maps/ElmsLab.asm:62-95, engine/phone/scripts/elm.asm:46). Egg hatching has a driver (tests/drivers/gold_egg_hatch.lua) and PC withdraw exists (BoxMenu.lua / PcMenu.lua). The full chain (hatch with your OT, withdraw, talk, EVENT_SHOWED_TOGEPI_TO_ELM, verbosegiveitem EVERSTONE) has never run end to end. The .egghatched arm of ElmPhoneCalleeScript (sets EVENT_TOLD_ELM_ABOUT_TOGEPI_OVER_THE_PHONE) lives in the bank $41 callee scripts and only matters for the alternate entry path. No route row exists for the Everstone.
-
-*How to prove it:* A driver chaining gold_egg_hatch-style hatching (own OT), PC withdraw, and the Elm talk, asserting EVENT_SHOWED_TOGEPI_TO_ELM and EVERSTONE in bag.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### TM37 Sandstorm happiness gate at the Route 27 house never exercised; gate is first-slot happiness >= 150
-
-walkthrough section(s) 16 | unverified
-
-The granny's script is extracted (cache scripts['60:6352'], 9 rows: checkevent, special id 88, ifgreater, sjump into the loyal/disloyal arms) and special id 88 resolves through constants.specialOrder with the VM's order[id+1] rule (Vm.lua:1773) to specialOrder[89] = GetFirstPokemonHappiness, a real handler at Specials.lua:1506 reading the first non-egg party member. The cart gate is happiness >= 150 on the FIRST party slot (ifgreater 150-1), not 'one of your Pokemon'. Happiness accrues via Happiness.lua stepped from StepEvents. No driver or bot row enters ROUTE_27_SANDSTORM_HOUSE.
-
-*How to prove it:* Driver: enter ROUTE_27_SANDSTORM_HOUSE with a first-slot mon at happiness >= 150 and assert TM37 given; also assert the disloyal arm below 150.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Route 27 whirlpool island (Bird Keeper Jose, TM22 Solarbeam, Rare Candy) and Tohjo Falls Moon Stone never run; whirlpool mechanic only proven on Route 41
-
-walkthrough section(s) 16 | unverified
-
-The whirlpool mechanic is implemented and driver-verified, but on Route 41, not here: tests/drivers/gold_water_moves.lua:105-124 clears a real whirlpool block with GLACIERBADGE gating and asserts the block replacement. The Route 27 island content is all in the cache (TM_SOLARBEAM ball at (60,12) item id 213 with event flag, Rare Candy ball at (53,12), BIRD_KEEPER[14] JOSE = L35 FARFETCH_D with phone contact rows; maps.ROUTE_27 objects rows 6-8) and the item ball arm is implemented, but the bot route crosses Route 27 only via Tohjo Falls and never surfs south past Gilbert (route rows 16.42-16.43 skip the south water), so this specific whirlpool, the Jose fight, and the TM22 pickup have never run. Same for the Tohjo Falls MOON_STONE ball at (2,6) (maps.TOHJO_FALLS object 1), which the walkthrough itself never mentions.
-
-*How to prove it:* Driver or route rows: surf south past Gilbert, clear the Route 27 whirlpool, fight Jose, collect TM22 and the Rare Candy; separately pick up the Tohjo Falls Moon Stone.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Route 26 heal house free heal extracted with all specials real, never entered
-
-walkthrough section(s) 16 | unverified
-
-The teacher's script is extracted (cache scripts['60:60e6'], 17 rows) and every special id in it resolves via order[id+1] to a real handler: 47 FadeOutToBlack, 50 ReloadSpritesNoPalettes, 27 HealParty, 49 FadeInFromBlack, 60 RestartMapMusic (Specials.lua:450, :999, :1025, and the fade-in/restart pair at :1059). Unconditional and repeatable like the cart. No driver or bot row ever enters ROUTE_26_HEAL_HOUSE; the bot route's Route 26 leg is a single travel row straight to the gate.
-
-*How to prove it:* Driver: enter ROUTE_26_HEAL_HOUSE with a damaged party, talk, assert full heal and that the scene is repeatable.
-
-*Notes:* Doc rating: unverified/minor, new.
-
-
-### Victory Road item pickups (TM26 Earthquake pit, Full Restore shelf, Max Revive, Full Heal, X Special, two hidden items) never exercised
-
-walkthrough section(s) 17 | unverified
-
-The walkthrough collects five Poke Ball items (TM26 Earthquake via the one-way pit at (0,11), Full Restore on the ledge shelf via the (17,19) ladder, Max Revive and Full Heal in the entrance region, X Special on the HOP_LEFT column) plus two hidden items (Max Potion at (3,29), Full Heal at (3,65)). All pieces exist: cache maps.VICTORY_ROAD carries 6 objects (5 with itemball item/qty payloads), 2 bgEvents with hiddenItem tables, 10 warps, 2 coord events; World:interact consumes obj.itemball (World.lua:5483-5490, an earlier bot-found fix); HiddenItems handles BGEVENT_ITEM; Permissions models the COLL_PIT one-way warp, the six ladders, ledge hops (isLedge/ledgeFacings, Gold's own direction order where $a0 is HOP_RIGHT), and COLL_UP_WALL side walls (Permissions.lua:170-260 LEDGE_FACINGS/SIDE_BLOCKS/NEIGHBOR_ARM), with a test section at tests/gen2_world_test.lua:2936. But nothing has walked these routes: the bot's section 17 is only travel/walk rows 17.2, 17.11, 17.15 (no pickup rows), so the pit drop, the two HOP exits from the TM pocket, the HOP_DOWN off the shelf, and the X Special ball sitting ON a HOP_LEFT tile (the one placement the asm-walk flags as needing hardware confirmation) are all unproven end to end.
-
-*How to prove it:* Driver or route rows through Victory Road collecting all five balls and both hidden items, specifically exercising the (0,11) pit drop, the (17,19) ladder shelf with HOP_DOWN exit, the two HOP exits from the TM pocket, and interaction with the X Special ball on its HOP_LEFT tile.
-
-*Notes:* Doc rating: unverified/minor, new.
-

README.md

@@ -242,7 +242,7 @@ in [docs/linux-arm64-build.md](docs/linux-arm64-build.md).
 
 ## iOS
 
-Every release ships `gen1recomp-*-ios.ipa`. Sideload it with AltStore
+Every release ships `gen1recomp++-*-ios.ipa`. Sideload it with AltStore
 (Windows or Mac) — see [docs/ios-sideload.md](docs/ios-sideload.md). To
 build and install from source on a Mac instead, see
 [docs/ios-install.md](docs/ios-install.md).

build-linux-arm-sbc.sh

@@ -0,0 +1,366 @@
+#!/usr/bin/env bash
+# Build a PortMaster aarch64 port of gen1recomp for Linux ARM SBC handhelds.
+# The package uses PortMaster control hooks and a self-contained LÖVE runtime,
+# while keeping paths relative to the launcher for broad CFW compatibility.
+#
+# The launcher uses SHDIR-relative paths and bundles the LÖVE 11.5 aarch64
+# runtime so the device does not need a separate runtime download on first launch.
+#
+# Usage:
+#   ./build-linux-arm-sbc.sh [--version X.Y.Z]
+#   GEN1RECOMP_SOURCE_DIR="$PWD" ./build-linux-arm-sbc.sh --version X.Y.Z
+#   ./build-linux-arm-sbc.sh --source /path/to/gen1recomp --version X.Y.Z
+#
+# Output:
+#   dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip
+#
+# Install on device:
+#   1. Install PortMaster for the handheld firmware.
+#   2. Unzip into the device's PortMaster ports folder so you have:
+#        Roms/Ports (PORTS)/gen1recomp-sbc.sh
+#        Roms/Ports (PORTS)/gen1recomp-sbc/...
+#   3. Copy a legal US Red or Blue .gb into Roms/Ports (PORTS)/gen1recomp-sbc/lovegame/
+#   4. Launch "gen1recomp-sbc" from the Ports list; press Choose ROM (scans that
+#      folder when zenity is missing).
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+HERE="$ROOT/.bazinga"
+CACHE="$HERE/cache/linux-arm-sbc"
+WORK="$HERE/work/linux-arm-sbc"
+DIST="$ROOT/dist/linux-arm-sbc"
+
+APP_NAME="gen1recomp-sbc"
+# Artifact suffix identifies this as the generic PortMaster SBC package.
+# Release uploads stage it as gen1recomp-<ver>-sbc-portmaster.zip.
+ARTIFACT_SUFFIX="portmaster"
+PORT_DIR_NAME="gen1recomp-sbc"
+LAUNCHER_NAME="gen1recomp-sbc.sh"
+LOVE_VERSION="11.5"
+# By default the pack is reproducible from the latest published GitHub release,
+# not whatever happens to be in the caller's checkout.  Development builds can
+# point this at a local checkout with GEN1RECOMP_SOURCE_DIR=/path/to/repo.
+SOURCE_DIR_OVERRIDE="${GEN1RECOMP_SOURCE_DIR:-}"
+SOURCE_TAG_OVERRIDE="${GEN1RECOMP_RELEASE_TAG:-}"
+VERSION="${GEN1RECOMP_VERSION:-}"
+
+# Official PortMaster LÖVE 11.5 aarch64 runtime (small love stub + liblove).
+PM_RUNTIME_BASE="https://raw.githubusercontent.com/PortsMaster/PortMaster-GUI/main/PortMaster/runtimes/love_${LOVE_VERSION}"
+RELEASES_LATEST_URL="https://github.com/bryanthaboi/gen1recomp/releases/latest"
+RELEASE_TARBALL_BASE="https://github.com/bryanthaboi/gen1recomp/archive/refs/tags"
+
+say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33mwarn:\033[0m %s\n' "$*" >&2; }
+fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --version) [ $# -ge 2 ] || fail "--version needs X.Y.Z"; VERSION="$2"; shift ;;
+    --source) [ $# -ge 2 ] || fail "--source needs a directory"; SOURCE_DIR_OVERRIDE="$2"; shift ;;
+    --release-tag) [ $# -ge 2 ] || fail "--release-tag needs a tag"; SOURCE_TAG_OVERRIDE="$2"; shift ;;
+    -h|--help)
+      sed -n '2,24p' "$0"
+      exit 0
+      ;;
+    *) fail "unknown argument: $1" ;;
+  esac
+  shift
+done
+
+command -v curl >/dev/null || fail "curl is required"
+command -v zip  >/dev/null || fail "zip is required"
+command -v unzip >/dev/null || fail "unzip is required"
+command -v tar  >/dev/null || fail "tar is required"
+
+mkdir -p "$CACHE" "$WORK" "$DIST"
+
+download() {
+  local url="$1" dest="$2"
+  if [ -f "$dest" ] && [ -s "$dest" ]; then
+    return 0
+  fi
+  say "downloading $(basename "$dest")"
+  curl -fL --progress-bar "$url" -o "$dest.tmp" \
+    || fail "download failed: $url"
+  mv "$dest.tmp" "$dest"
+}
+
+# --------------------------------------------------------------- source + game tree
+# Release builds use the latest published source archive. A local checkout is
+# an explicit override for development and for CI's just-built release source.
+if [ -n "$SOURCE_DIR_OVERRIDE" ]; then
+  SOURCE_DIR_OVERRIDE="$(cd "$SOURCE_DIR_OVERRIDE" 2>/dev/null && pwd)" \
+    || fail "source directory does not exist: $SOURCE_DIR_OVERRIDE"
+  SOURCE_DIR="$SOURCE_DIR_OVERRIDE"
+  SOURCE_TAG="${SOURCE_TAG_OVERRIDE:-local}"
+  if [ "$SOURCE_TAG" != "local" ]; then
+    printf '%s' "$SOURCE_TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+      || fail "release tag must look like vX.Y.Z: $SOURCE_TAG"
+  fi
+  if [ -z "$VERSION" ]; then
+    VERSION="$(git -C "$SOURCE_DIR" rev-parse --short HEAD 2>/dev/null || echo dev)"
+  fi
+else
+  if [ -z "$SOURCE_TAG_OVERRIDE" ]; then
+    latest_location="$(curl -fsSI "$RELEASES_LATEST_URL" \
+      | awk 'tolower($1) == "location:" { print $2 }' | tail -1 | tr -d '\r')" \
+      || fail "could not resolve latest published release"
+    SOURCE_TAG_OVERRIDE="${latest_location##*/}"
+  fi
+  printf '%s' "$SOURCE_TAG_OVERRIDE" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+    || fail "release tag must look like vX.Y.Z: $SOURCE_TAG_OVERRIDE"
+  SOURCE_TAG="$SOURCE_TAG_OVERRIDE"
+  SOURCE_ARCHIVE="$CACHE/gen1recomp-${SOURCE_TAG}.tar.gz"
+  download "$RELEASE_TARBALL_BASE/$SOURCE_TAG.tar.gz" "$SOURCE_ARCHIVE"
+  SOURCE_EXTRACT="$WORK/source-$SOURCE_TAG"
+  rm -rf "$SOURCE_EXTRACT"
+  mkdir -p "$SOURCE_EXTRACT"
+  tar -xzf "$SOURCE_ARCHIVE" -C "$SOURCE_EXTRACT"
+  SOURCE_DIR="$(find "$SOURCE_EXTRACT" -mindepth 1 -maxdepth 1 -type d -print -quit)"
+  [ -n "$SOURCE_DIR" ] || fail "release archive had no source directory"
+  if [ -z "$VERSION" ]; then VERSION="${SOURCE_TAG#v}"; fi
+fi
+
+say "staging lovegame/ from $SOURCE_TAG"
+GAME_SRC="$WORK/lovegame"
+rm -rf "$GAME_SRC"
+mkdir -p "$GAME_SRC"
+
+# Same payload as scripts/build.sh's game.love — never ship ROM-derived cache.
+# tools/save-editor is part of that payload: the launcher's Edit button on a
+# save row opens it in-process (main.lua).
+(cd "$SOURCE_DIR" && zip -q -9 -r "$WORK/game-payload.zip" \
+  main.lua conf.lua src libs data assets tools/save-editor \
+  tools/rom_manifest.json tools/rom_manifest_blue.json \
+  -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
+if unzip -Z1 "$WORK/game-payload.zip" \
+    | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/'; then
+  fail "payload unexpectedly contains generated ROM data"
+fi
+unzip -q "$WORK/game-payload.zip" -d "$GAME_SRC"
+rm -f "$WORK/game-payload.zip"
+
+# Stamp release version into the staged tree only (never the working tree).
+if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  say "stamping engine version $VERSION"
+  sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+    "$SOURCE_DIR/src/core/Version.lua" > "$GAME_SRC/src/core/Version.lua"
+  version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+  grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+    "$GAME_SRC/src/core/Version.lua" \
+    || fail "version stamp failed"
+else
+  say "version '$VERSION' is not X.Y.Z — shipping default engine (no stamp)"
+fi
+
+# Portable marker: saves + ROM cache live next to the game on the SD card.
+: > "$GAME_SRC/portable.txt"
+
+# --------------------------------------------------------------- love runtime
+say "fetching LÖVE $LOVE_VERSION aarch64 runtime"
+LOVE_BIN="$CACHE/love.aarch64"
+LOVE_LIB="$CACHE/liblove-11.5.so"
+LUAJIT_LIB="$CACHE/libluajit-5.1.so.2"
+MODPLUG_LIB="$CACHE/libmodplug.so.1"
+OGG_LIB="$CACHE/libogg.so.0"
+
+download "$PM_RUNTIME_BASE/love.aarch64" "$LOVE_BIN"
+download "$PM_RUNTIME_BASE/libs.aarch64/liblove-11.5.so" "$LOVE_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libluajit-5.1.so.2" "$LUAJIT_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libmodplug.so.1" "$MODPLUG_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libogg.so.0" "$OGG_LIB"
+
+# Sanity: love stub must be an aarch64 ELF.
+file "$LOVE_BIN" | grep -qi 'aarch64\|ARM aarch64' \
+  || fail "love.aarch64 does not look like an aarch64 ELF (got: $(file "$LOVE_BIN"))"
+
+# --------------------------------------------------------------- port tree
+say "assembling port package"
+PORT_ROOT="$WORK/port"
+rm -rf "$PORT_ROOT"
+mkdir -p "$PORT_ROOT/$PORT_DIR_NAME/bin" \
+         "$PORT_ROOT/$PORT_DIR_NAME/libs.aarch64" \
+         "$PORT_ROOT/$PORT_DIR_NAME/licenses" \
+         "$PORT_ROOT/$PORT_DIR_NAME/conf"
+
+cp -R "$GAME_SRC" "$PORT_ROOT/$PORT_DIR_NAME/lovegame"
+cp "$LOVE_BIN" "$PORT_ROOT/$PORT_DIR_NAME/bin/love.aarch64"
+chmod +x "$PORT_ROOT/$PORT_DIR_NAME/bin/love.aarch64"
+cp "$LOVE_LIB" "$LUAJIT_LIB" "$MODPLUG_LIB" "$OGG_LIB" \
+  "$PORT_ROOT/$PORT_DIR_NAME/libs.aarch64/"
+
+# Drop a short license pointer for the bundled LÖVE bits.
+cat > "$PORT_ROOT/$PORT_DIR_NAME/licenses/LICENSE.love2d.txt" <<'EOF'
+This port bundles the LÖVE 11.5 aarch64 runtime from PortMaster
+(https://github.com/PortsMaster/PortMaster-GUI). LÖVE is zlib-licensed;
+see https://love2d.org/ for full terms.
+EOF
+
+# --------------------------------------------------------------- launcher
+# Resolve the game directory from the launcher so this works with both
+# PortMaster-managed ports directories.
+cat > "$PORT_ROOT/$LAUNCHER_NAME" <<'EOF'
+#!/bin/bash
+# gen1recomp-sbc — Linux ARM SBC / PortMaster launcher
+# Uses SHDIR-relative paths so firmware-specific mount points do not matter.
+
+export HOME="${HOME:-/root}"
+XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+SHDIR="$(cd "$(dirname "$0")" && pwd)"
+
+if [ -d "/mnt/SDCARD/Apps/PortMaster/PortMaster/" ]; then
+  controlfolder="/mnt/SDCARD/Apps/PortMaster/PortMaster"
+elif [ -d "/mnt/SDCARD/Roms/ports/PortMaster" ]; then
+  controlfolder="/mnt/SDCARD/Roms/ports/PortMaster"
+elif [ -d "/mnt/SDCARD/Data/PortMaster/" ]; then
+  controlfolder="/mnt/SDCARD/Data/PortMaster"
+elif [ -d "$SHDIR/PortMaster" ]; then
+  controlfolder="$SHDIR/PortMaster"
+elif [ -d "/opt/system/Tools/PortMaster/" ]; then
+  controlfolder="/opt/system/Tools/PortMaster"
+elif [ -d "/opt/tools/PortMaster/" ]; then
+  controlfolder="/opt/tools/PortMaster"
+elif [ -d "$XDG_DATA_HOME/PortMaster/" ]; then
+  controlfolder="$XDG_DATA_HOME/PortMaster"
+elif [ -d "/roms/ports/PortMaster" ]; then
+  controlfolder="/roms/ports/PortMaster"
+else
+  controlfolder="/mnt/SDCARD/Roms/PORTS/PortMaster"
+fi
+
+if [ ! -f "$controlfolder/control.txt" ]; then
+  echo "PortMaster control.txt not found under $controlfolder" >&2
+  exit 1
+fi
+# shellcheck disable=SC1090
+source "$controlfolder/control.txt"
+get_controls
+if [ -n "${CFW_NAME:-}" ] && [ -f "${controlfolder}/mod_${CFW_NAME}.txt" ]; then
+  # shellcheck disable=SC1090
+  source "${controlfolder}/mod_${CFW_NAME}.txt"
+fi
+
+GAMEDIR="$SHDIR/gen1recomp-sbc"
+CONFDIR="$GAMEDIR/conf"
+mkdir -p "$CONFDIR"
+
+cd "$GAMEDIR" || exit 1
+> "$GAMEDIR/log.txt" && exec > >(tee "$GAMEDIR/log.txt") 2>&1
+
+export XDG_DATA_HOME="$CONFDIR"
+export XDG_CONFIG_HOME="$CONFDIR"
+export LD_LIBRARY_PATH="$GAMEDIR/libs.aarch64:${LD_LIBRARY_PATH:-}"
+export SDL_GAMECONTROLLERCONFIG="${sdl_controllerconfig:-}"
+# GLES is the common path on ARM SBC handhelds; firmware may override it.
+export LOVE_GRAPHICS_USE_OPENGLES="${LOVE_GRAPHICS_USE_OPENGLES:-1}"
+
+$ESUDO chmod a+x ./bin/love.aarch64 2>/dev/null || chmod a+x ./bin/love.aarch64
+$ESUDO chmod 666 /dev/uinput 2>/dev/null || true
+
+if [ -n "${GPTOKEYB:-}" ]; then
+  $GPTOKEYB "love.aarch64" &
+fi
+if type pm_platform_helper >/dev/null 2>&1; then
+  pm_platform_helper "$GAMEDIR/bin/love.aarch64"
+fi
+
+./bin/love.aarch64 "$GAMEDIR/lovegame"
+
+if type pm_finish >/dev/null 2>&1; then
+  pm_finish
+else
+  if [ -n "${ESUDO:-}" ]; then
+    $ESUDO kill -9 $(pidof gptokeyb) 2>/dev/null || true
+  else
+    kill -9 $(pidof gptokeyb) 2>/dev/null || true
+  fi
+fi
+EOF
+chmod +x "$PORT_ROOT/$LAUNCHER_NAME"
+
+# --------------------------------------------------------------- metadata
+cat > "$PORT_ROOT/port.json" <<EOF
+{
+  "version": 2,
+  "name": "gen1recomp-sbc.zip",
+  "items": [
+    "$LAUNCHER_NAME",
+    "$PORT_DIR_NAME"
+  ],
+  "items_opt": null,
+  "attr": {
+    "title": "gen1recomp-sbc",
+    "desc": "Native LÖVE2D recreation of Pokemon Red and Blue. Supply your own legal US Red or Blue ROM.",
+    "source": "https://github.com/bryanthaboi/gen1recomp/releases/tag/$SOURCE_TAG",
+    "inst": "Requires a 64-bit Linux ARM handheld with PortMaster. Copy a canonical US Red or Blue .gb into gen1recomp-sbc/lovegame/, then launch and press Choose ROM.",
+    "genres": ["adventure", "rpg"],
+    "porter": ["gen1recomp-sbc"],
+    "image": {},
+    "rtr": true,
+    "runtime": null,
+    "reqs": [],
+    "arch": ["aarch64"]
+  }
+}
+EOF
+
+cat > "$PORT_ROOT/gameinfo.xml" <<EOF
+<?xml version="1.0" encoding="utf-8"?>
+<gameList>
+  <game>
+    <path>./$LAUNCHER_NAME</path>
+    <name>gen1recomp-sbc</name>
+    <desc>Native LÖVE2D recreation of Pokemon Red and Blue. Requires your own legal US Red or Blue ROM.</desc>
+    <releasedate>20250101T000000</releasedate>
+    <developer>the bois club</developer>
+    <publisher>the bois club</publisher>
+    <genre>RPG</genre>
+  </game>
+</gameList>
+EOF
+
+cat > "$PORT_ROOT/README.md" <<'EOF'
+## gen1recomp-sbc (Linux ARM SBC / PortMaster)
+
+Native LÖVE 11.5 aarch64 PortMaster port of gen1recomp for compatible Linux ARM SBC handhelds, including H700-class devices. This pack was built from source release **__SOURCE_TAG__**.
+
+### Install
+
+1. Install PortMaster for your handheld firmware.
+2. Unzip so `gen1recomp-sbc.sh` and the `gen1recomp-sbc/` folder are siblings in the device's PortMaster ports directory.
+3. Copy a legal US Pokémon Red or Blue `.gb` into `gen1recomp-sbc/lovegame/`.
+4. Refresh the launcher and launch **gen1recomp-sbc** from Ports.
+
+### Controls
+
+| Input | Action |
+|--|--|
+| D-pad | Move cursor |
+| A | Click |
+| L1 / R1 | Switch tabs |
+| Start / Select | Play or choose ROM |
+
+Controls use the normal PortMaster / SDL pad map. Device-specific power/suspend behavior is supplied by the firmware and PortMaster runtime.
+
+### First run
+
+Put the `.gb` in `lovegame/`, then press **Choose ROM**. After import, the ROM-derived cache and saves stay beside the game (`portable.txt`).
+
+### Thanks
+
+LÖVE runtime binaries from [PortMaster](https://portmaster.games/). PortMaster device support and runtime integration are maintained by the PortMaster team.
+EOF
+sed -i.bak "s/__SOURCE_TAG__/$SOURCE_TAG/g" "$PORT_ROOT/README.md"
+rm -f "$PORT_ROOT/README.md.bak"
+
+# --------------------------------------------------------------- zip
+ZIP_OUT="$DIST/$APP_NAME-$ARTIFACT_SUFFIX.zip"
+rm -f "$ZIP_OUT"
+say "packing $ZIP_OUT"
+(cd "$PORT_ROOT" && zip -q -9 -r "$ZIP_OUT" \
+  "$LAUNCHER_NAME" "$PORT_DIR_NAME" port.json gameinfo.xml README.md)
+
+say "done."
+say "artifact: $ZIP_OUT ($(du -h "$ZIP_OUT" | cut -f1))"
+say "copy into the device PortMaster ports folder, then drop your .gb into gen1recomp-sbc/lovegame/"

build-rg34xxsp.sh

@@ -91,11 +91,14 @@ mkdir -p "$GAME_SRC"
 (cd "$ROOT" && zip -q -9 -r "$WORK/game-payload.zip" \
   main.lua conf.lua src libs data assets tools/save-editor \
   tools/rom_manifest.json tools/rom_manifest_blue.json \
+  tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
   -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
-if unzip -Z1 "$WORK/game-payload.zip" \
-    | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/'; then
-  fail "payload unexpectedly contains generated ROM data"
-fi
+payload_list="$(unzip -Z1 "$WORK/game-payload.zip")"
+printf '%s\n' "$payload_list" \
+  | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/' \
+  && fail "payload unexpectedly contains generated ROM data"
+printf '%s\n' "$payload_list" | grep -qxF "tools/rom_manifest_gold.json" \
+  || fail "payload is missing tools/rom_manifest_gold.json"
 unzip -q "$WORK/game-payload.zip" -d "$GAME_SRC"
 rm -f "$WORK/game-payload.zip"
 

data/scripts/celadon_eevee.lua

@@ -92,7 +92,7 @@ return {
       { "set_flag", "EVENT_GOT_EEVEE" },                       -- 7
       { "hide_object", "CELADON_MANSION_ROOF_HOUSE",
         "CELADONMANSION_ROOF_HOUSE_EEVEE_POKEBALL" },          -- 8
-      { "play_sound", "Get_Item1" },                           -- 9 (GotMonText jingle)
+      { "text_sound", "Get_Item1" },                           -- 9 (GotMonText jingle)
       { "show_text", "_GotMonText", { RAM = "EEVEE" } },       -- 10
       { "jump", 13 },                                          -- 11
       { "show_text", "_BoxIsFullText" },                       -- 12

data/scripts/flavor/game_corner.lua

@@ -10,10 +10,10 @@
 local function coinGiver(opts)
   return function(game, ow, npc, done)
     local TextBox = require("src.render.TextBox")
-    local Sound = require("src.core.Sound")
     local t = game.data.text
-    local function push(label, fallback, onDone)
-      game.stack:push(TextBox.new(game, t[label] or fallback, onDone or done))
+    local function push(label, fallback, onDone, popts)
+      game.stack:push(TextBox.new(game, t[label] or fallback, onDone or done,
+                                  popts))
     end
     if game.save.flags[opts.event] then
       push(opts.alreadyGotLabel, opts.alreadyGotFallback)
@@ -30,9 +30,10 @@ local function coinGiver(opts)
       end
       game.save.coins = math.min(9999, (game.save.coins or 0) + opts.amount)
       game.save.flags[opts.event] = true
-      Sound.play(game.data, "Get_Item1")
+      -- the ReceivedNCoinsText strings carry sound_get_item_1
       push(opts.receivedLabel,
-        ("{PLAYER} received\n%d coins!"):format(opts.amount))
+        ("{PLAYER} received\n%d coins!"):format(opts.amount), nil,
+        TextBox.soundOpts(game, "Get_Item1"))
     end)
   end
 end

data/scripts/flavor/museum_1f.lua

@@ -22,8 +22,8 @@ return {
         local TextBox = require("src.render.TextBox")
         local Commands = require("src.script.Commands")
         local t = game.data.text
-        local function say(label, cb)
-          game.stack:push(TextBox.new(game, t[label] or label, cb))
+        local function say(label, cb, sopts)
+          game.stack:push(TextBox.new(game, t[label] or label, cb, sopts))
         end
 
         if game.save.flags.EVENT_GOT_OLD_AMBER then
@@ -39,8 +39,9 @@ return {
           game.save.flags.EVENT_GOT_OLD_AMBER = true
           Commands.hide_object({ save = game.save, overworld = ow, game = game },
                                 "MUSEUM_1F", "MUSEUM1F_OLD_AMBER")
-          require("src.core.Sound").play(game.data, "Get_Item1")
-          say("_Museum1FScientist2ReceivedOldAmberText", done)
+          -- .ReceivedOldAmberText carries sound_get_item_1
+          say("_Museum1FScientist2ReceivedOldAmberText", done,
+              TextBox.soundOpts(game, "Get_Item1"))
         end)
       end,
 

data/scripts/oaks_lab.lua

@@ -38,9 +38,9 @@ local function starterBall(askText, species, choseFlag, ownBall,
     -- inside give_pokemon).  Show the received text first so the
     -- nickname prompt follows "you got X", matching Gen1.
     -- The received text carries sound_get_key_item (OaksLab.asm
-    -- OaksLabReceivedMonText); the jingle plays as the box opens
-    -- (same beat as the Yellow port's starter, #668).
-    { "play_sound", "Get_Key_Item" },                              -- 8
+    -- OaksLabReceivedMonText), so the jingle fires once the box has
+    -- typed out and holds it (same beat as the Yellow port's starter, #668).
+    { "text_sound", "Get_Key_Item" },                              -- 8
     { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 9
     { "give_pokemon", species, 5 },               -- 10
     { "set_flag", "EVENT_GOT_STARTER" },          -- 11
@@ -54,7 +54,7 @@ local function starterBall(askText, species, choseFlag, ownBall,
     { "face_object", 1, "up" },                   -- 15
     { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 16
     { "hide_object", "OAKS_LAB", rivalBall },     -- 17
-    { "play_sound", "Get_Key_Item" },             -- 18 (sound_get_key_item)
+    { "text_sound", "Get_Key_Item" },             -- 18 (sound_get_key_item)
     { "show_text", "_OaksLabRivalReceivedMonText",
       { RAM = rivalBall == "OAKSLAB_CHARMANDER_POKE_BALL" and "CHARMANDER"
               or rivalBall == "OAKSLAB_SQUIRTLE_POKE_BALL" and "SQUIRTLE"
@@ -106,8 +106,8 @@ return {
       { "check_item", "OAKS_PARCEL" },
       { "jump_if_false", "raise_young" },
       -- OaksLabOak1Text.got_parcel → RivalArrives + OakGivesPokedex
+      { "text_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOak1DeliverParcelText" },
-      { "play_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOak1ParcelThanksText" },
       { "take_item", "OAKS_PARCEL", 1 },
       { "stop_music" },
@@ -128,8 +128,8 @@ return {
       { "face_object", 1, "up" },
       { "face_object", 5, "down" },
       { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "text_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOakGotPokedexText" },
-      { "play_sound", "Get_Key_Item" },
       { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
       { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
       { "face_object", 1, "up" },
@@ -246,9 +246,17 @@ return {
   -- 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
+    local flags = game.save.flags or {}
+    if flags.EVENT_GOT_STARTER and not flags.EVENT_BATTLED_RIVAL_IN_OAKS_LAB then
+      local rival = ow:npcByIndex(1)
+      if rival then
+        rival.cellX = flags.EVENT_CHOSE_CHARMANDER and 7
+          or flags.EVENT_CHOSE_SQUIRTLE and 8 or 6
+        rival.cellY = 4
+        rival.px, rival.py = rival.cellX * 16, rival.cellY * 16
+      end
     end
+    if not 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")
@@ -286,6 +294,7 @@ return {
       -- fanfare for the taunt/challenge exchange, same as the Yellow port
       -- (oaks_lab_yellow.lua); it was silently dropped here (#596).
       local rows = {
+        { "face_player_dir", "up" },
         { "stop_music" },
         { "play_music", "Music_MeetRival" },
         { "show_text", "_OaksLabRivalIllTakeYouOnText" },         -- 1
@@ -309,28 +318,19 @@ return {
       local base = #rows
       local party = flags.EVENT_CHOSE_BULBASAUR and 3
                     or flags.EVENT_CHOSE_SQUIRTLE and 2 or 1
+      table.insert(rows, { "save_end_battle_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
       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" })
-      -- 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" })
       -- OaksLabRivalStartsExitScript: parting shot, rival exit fanfare, then
       -- walk out past the player.  The fanfare was dropped here (#683) -- the
       -- parcel scene above already plays Music_MeetRival on both arrival and
       -- departure (lines 144-146), and this exit should match (#596).
       table.insert(rows, { "stop_music" })
-      table.insert(rows, { "play_music", "Music_MeetRival" })
+      table.insert(rows, { "play_music", "Music_MeetRival", { start = "rival" } })
       table.insert(rows, { "move_npc_to", 1, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
       table.insert(rows, { "play_music", "Music_OaksLab" })

data/scripts/oaks_lab_yellow.lua

@@ -38,8 +38,8 @@ return {
       { "jump_if_false", "raise_young" },
       -- .DeliverParcelText: parcel handover, then the Pokédex scene
       -- (OaksLabRivalArrivesAtOaksRequestScript -> OakGivesPokedexScript)
+      { "text_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOak1DeliverParcelText" },
-      { "play_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOak1ParcelThanksText" },
       { "take_item", "OAKS_PARCEL", 1 },
       { "stop_music" },
@@ -62,8 +62,8 @@ return {
       { "face_object", RIVAL, "up" },
       { "face_object", OAK1, "down" },
       { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "text_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOakGotPokedexText" },
-      { "play_sound", "Get_Key_Item" },
       { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
       { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
       { "face_object", RIVAL, "up" },
@@ -113,8 +113,8 @@ return {
       { "jump_if_true", "come_see" },
       { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
       { "give_item", "POKE_BALL", 5, false },
+      { "text_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOak1ReceivedPokeballsText" },
-      { "play_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabGivePokeballsExplanationText" },
       { "jump", "end" },
 
@@ -176,7 +176,7 @@ return {
       -- rival starter baseline (RIVAL_STARTER_JOLTEON) at snatch time
       rows[#rows + 1] = { "set_field", "rivalStarter", 1 }
       rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText1" }
-      rows[#rows + 1] = { "play_sound", "Get_Key_Item" }
+      rows[#rows + 1] = { "text_sound", "Get_Key_Item" }
       rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText2" }
       rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText3" }
       rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText4" }
@@ -196,7 +196,7 @@ return {
       rows[#rows + 1] = { "face_object", OAK1, "down" }
       -- OaksLabPlayerReceivedMonText clears wMonDataLocation, so AskName runs (#1013)
       rows[#rows + 1] = { "show_text", "_OaksLabOakGivesText" }
-      rows[#rows + 1] = { "play_sound", "Get_Key_Item" }
+      rows[#rows + 1] = { "text_sound", "Get_Key_Item" }
       rows[#rows + 1] = { "show_text", "_OaksLabReceivedText", { RAM = "PIKACHU" } }
       rows[#rows + 1] = { "give_pokemon", "PIKACHU", 5 }
       -- DisablePikachuOverworldSpriteDrawing keeps it in the ball (#1009)
@@ -226,9 +226,15 @@ return {
   },
 
   onEnter = function(game, ow)
-    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
-      return
+    local flags = game.save.flags or {}
+    if flags.EVENT_GOT_STARTER and not flags.EVENT_BATTLED_RIVAL_IN_OAKS_LAB then
+      local rival = ow:npcByIndex(RIVAL)
+      if rival then
+        rival.cellX, rival.cellY = 7, 4
+        rival.px, rival.py = 7 * 16, 4 * 16
+      end
     end
+    if not 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")
@@ -296,13 +302,14 @@ return {
       table.insert(rows, { "wait", 20 })
       table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
       table.insert(rows, { "stop_music" })
-      table.insert(rows, { "play_music", "Music_MeetRival" })
+      table.insert(rows, { "play_music", "Music_MeetRival", { start = "rival" } })
       table.insert(rows, { "move_npc_to", RIVAL, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
       table.insert(rows, { "play_music", "Music_OaksLab" })
       -- OaksLabPikachuEscapesPokeballScript: the follower reaches the map (#1009)
       table.insert(rows, { "face_player_dir", "up" })
       table.insert(rows, { "set_field", "pikachuInBall", false })
+      table.insert(rows, { "spawn_pikachu_follower" })
       table.insert(rows, { "play_cry", "PIKACHU" })
       table.insert(rows, { "show_text", "_OaksLabPikachuDislikesPokeballsText1" })
       table.insert(rows, { "show_text", "_OaksLabPikachuDislikesPokeballsText2" })

data/scripts/story.lua

@@ -142,20 +142,23 @@ M.VIRIDIAN_CITY = {
 M.BLUES_HOUSE = {
   talk = {
     TEXT_BLUESHOUSE_DAISY_SITTING = {
-      { "face_player" },                                     -- 1
-      { "check_flag", "EVENT_GOT_TOWN_MAP" },                -- 2
-      { "jump_if_true", 10 },                                -- 3
-      { "check_flag", "EVENT_GOT_STARTER" },                 -- 4
-      { "jump_if_false", 12 },                               -- 5
-      { "show_text", "_BluesHouseDaisyOfferMapText" },       -- 6
+      { "face_player" },
+      { "check_flag", "EVENT_GOT_TOWN_MAP" },
+      { "jump_if_true", "got_map" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_false", "too_early" },
+      { "show_text", "_BluesHouseDaisyOfferMapText" },
       -- _GotMapText: "{PLAYER} got a\n{RAM:wStringBuffer}!" -- the
       -- buffer supplies "TOWN MAP" (scripts/BluesHouse.asm GotMapText)
-      { "give_item", "TOWN_MAP", 1, "_GotMapText" },         -- 7
-      { "set_flag", "EVENT_GOT_TOWN_MAP" },                  -- 8
-      { "jump", 13 },                                        -- 9
-      { "show_text", "_BluesHouseDaisyUseMapText" },         -- 10
-      { "jump", 13 },                                        -- 11
-      { "show_text", "_BluesHouseDaisyRivalAtLabText" },     -- 12
+      { "give_item", "TOWN_MAP", 1, "_GotMapText" },
+      { "hide_object", "BLUES_HOUSE", "BLUESHOUSE_TOWN_MAP" },
+      { "set_flag", "EVENT_GOT_TOWN_MAP" },
+      { "jump", "end" },
+      { "label", "got_map" },
+      { "show_text", "_BluesHouseDaisyUseMapText" },
+      { "jump", "end" },
+      { "label", "too_early" },
+      { "show_text", "_BluesHouseDaisyRivalAtLabText" },
     },
   },
 }
@@ -294,6 +297,7 @@ M.BILLS_HOUSE = {
 
 M.ROUTE_25 = {
   onEnter = function(game, ow)
+    game.save.pikachuMapScriptActive = nil
     local flags = game.save.flags
     if flags.EVENT_LEFT_BILLS_HOUSE_AFTER_HELPING then return end
     local Commands = require("src.script.Commands")
@@ -326,6 +330,7 @@ M.VERMILION_CITY = {
   -- only read while EVENT_1ST_LOCK_OPENED is unset (the gym is only
   -- reachable through this map, so a fresh visit always re-rolls).
   onEnter = function(game, ow)
+    game.save.pikachuMapScriptActive = nil
     local puz = game.save.trashPuzzle or {}
     game.save.trashPuzzle = puz
     puz.first = love.math.random(0, 7) * 2
@@ -1058,6 +1063,7 @@ local championsRoomRivalScript = {
   -- OakCongratulatesPlayerScript: rival faces left, Oak faces down
   { "face_object", 1, "left" },                             -- 17
   { "face_object", 2, "down" },                             -- 18
+  { "load_player_starter_name" },
   { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 19
   -- OakDisappointedWithRivalScript: Oak turns to the rival (right)
   { "face_object", 2, "right" },                            -- 20
@@ -1067,13 +1073,8 @@ local championsRoomRivalScript = {
   { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 23
   { "move_npc", 2, "up", 2 },                               -- 24 OakExitChampionsRoomMovement
   { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 25
-  -- ChampionsRoomPlayerFollowsOakScript / WalkToHallOfFame_RLEMovement.
-  -- The player walks out after Oak instead of the screen just fading on the
-  -- spot (#704).  Route one tile right before walking north so the player
-  -- reaches the north-wall HALL_OF_FAME warp without sharing the rival's
-  -- (4,2) cell.  The original simulated movement bypasses entity collision,
-  -- but this scene should not visibly walk through the defeated rival.
-  { "move_player", "right", 1 },                            -- 26
+  -- scripts/ChampionsRoom.asm WalkToHallOfFame_RLEMovement
+  { "move_player", "left", 1 },
   { "move_player", "up", 3 },                               -- 27
   -- 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)
@@ -1238,6 +1239,7 @@ local function pokemonTower2FRivalScript(playerX)
     { "jump_if_false", "end" },                                   -- 6 loss: stay
     { "set_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },             -- 7
     { "show_text", "_PokemonTower2FRivalDefeatedText" },          -- 8
+    { "play_music", "Music_MeetRival", { start = "rival" } },
     { "walk_npc", 1, exitDirs },                                  -- 9
     { "hide_object", "POKEMON_TOWER_2F", "POKEMONTOWER2F_RIVAL" }, -- 10
     { "jump", "end" },                                            -- 11

data/scripts/story2.lua

@@ -178,7 +178,8 @@ M.PALLET_TOWN = {
       end
     end
 
-    local function enterLab()
+    local function enterLab(oak)
+      if oak then oak.stepFrames = nil end
       Commands.hide_object(ctx, "PALLET_TOWN", "PALLETTOWN_OAK")
       Commands.show_object(ctx, "OAKS_LAB", "OAKSLAB_OAK2")
       ow.doorWarp = true
@@ -187,12 +188,17 @@ M.PALLET_TOWN = {
     end
 
     local function walkToLab(oak)
+      -- lockstep half runs Oak on the player's own frames per cell
+      -- engine/overworld/movement.asm:737 (DoScriptedNPCMovement)
       local i = 0
+      if oak then
+        oak.stepFrames = ow.player.stepFramesCur or ow.player.stepFrames
+      end
       local function tick()
         i = i + 1
         local playerStep = escort.playerSteps[i]
         if not playerStep then
-          enterLab()
+          enterLab(oak)
           return
         end
         if oak and escort.oakSteps[i] then
@@ -413,6 +419,9 @@ M.ROUTE_8_GATE = saffronGate("TEXT_ROUTE8GATE_GUARD", { { 2, 3 }, { 2, 4 } }, tr
 -- -------------------------------------------------------------------
 
 M.POKEMON_FAN_CLUB = {
+  onEnter = function(game, ow)
+    require("src.world.PikachuFollower").onFanClubEntered(game, ow)
+  end,
   talk = {
     TEXT_POKEMONFANCLUB_CHAIRMAN = {
       { "face_player" },                                          -- 1
@@ -645,8 +654,10 @@ local function mtMoonFossil(itemId, otherName, gotFlag)
       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)
+      -- MtMoonB2FReceivedFossilText: text_far, sound_get_key_item,
+      -- text_waitbutton -- the jingle plays after the box has typed and
+      -- the button wait comes after it
       game.stack:push(TextBox.new(game,
         t._MtMoonB2FReceivedFossilText
           or ("{PLAYER} got the\n" .. game.stringBuffer .. "!"),
@@ -659,11 +670,11 @@ local function mtMoonFossil(itemId, otherName, gotFlag)
           ow.runner:run({
             { "walk_npc", 1, dirs },
             { "text_opts", { auto = true } },
+            { "text_sound", "Get_Key_Item" },
             { "show_text", "_MtMoonB2FSuperNerdThenThisIsMineText" },
-            { "play_sound", "Get_Key_Item" },
             { "hide_object", "MT_MOON_B2F", otherName },
           }, { onDone = done })
-        end))
+        end, TextBox.soundOpts(game, "Get_Key_Item")))
     end }))
   end
 end

data/scripts/story4.lua

@@ -8,9 +8,9 @@ local M = {}
 
 local function text(game) return game.data.text end
 
-local function push(game, s, done)
+local function push(game, s, done, opts)
   local TextBox = require("src.render.TextBox")
-  game.stack:push(TextBox.new(game, s, done))
+  game.stack:push(TextBox.new(game, s, done, opts))
 end
 
 -- The question stays on screen under the YES/NO menu.  The dojo prize
@@ -142,7 +142,7 @@ M.MT_MOON_POKECENTER = {
         local Commands = require("src.script.Commands")
         Commands.give_pokemon({ save = game.save, game = game, overworld = ow },
                               "MAGIKARP", 5)
-        push(game, ("%s got a\nMAGIKARP!"):format(game.save.player.name), done)
+        push(game, t._GotMonText or "{PLAYER} got\n{RAM:wNameBuffer}!", done)
       end)
     end,
   },
@@ -263,7 +263,7 @@ M.SILPH_CO_7F = {
       { "jump_if_false", "box_full" },
       -- flag ahead of the jingle, like the Celadon EEVEE (#426)
       { "set_flag", "EVENT_GOT_LAPRAS" },
-      { "play_sound", "Get_Item1" },
+      { "text_sound", "Get_Item1" },
       { "show_text", "_GotMonText", { RAM = "LAPRAS" } },
       { "show_text", "_SilphCo7FSilphWorkerM1LaprasDescriptionText" },
       { "jump", "end" },
@@ -307,12 +307,11 @@ M.COPYCATS_HOUSE_2F = {
             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, t._CopycatsHouse2FCopycatReceivedTM31Text, function()
             push(game, t._CopycatsHouse2FCopycatTM31Explanation1Text, done)
-          end)
+          end, require("src.render.TextBox").soundOpts(game, "Get_Item1"))
         end)
       end)
     end,
@@ -478,7 +477,6 @@ M.CELADON_MART_ROOF = {
                     return
                   end
                   game.save.flags[g.flag] = true
-                  require("src.core.Sound").play(game.data, "Get_Item1")
                   local subs = { player = game.save.player.name,
                                  ram = game.data.items[g.tm].name }
                   local explain = fill(t[g.explain] or "", subs)
@@ -490,7 +488,7 @@ M.CELADON_MART_ROOF = {
                     else
                       done()
                     end
-                  end)
+                  end, require("src.render.TextBox").soundOpts(game, "Get_Item1"))
                 end)
               end,
               onCancel = done,
@@ -512,25 +510,28 @@ M.ROUTE_24 = {
       local flags = game.save.flags
       local function battleOrDone()
         if ow:trainerDefeated(npc) then
-          push(game, "I hate this!\nMy dreams of\nTEAM ROCKET...", done)
+          push(game, text(game)._Route24CooltrainerM1YouCouldBecomeATopLeaderText,
+            done)
         else
           ow:engageTrainer(npc, done)
         end
       end
       if not flags.EVENT_GOT_NUGGET then
-        push(game, "Congratulations!\nYou beat our 5\ncontest trainers!\f"
-          .. "You just earned a\nfabulous prize!", function()
+        local t = text(game)
+        push(game, t._Route24CooltrainerM1YouBeatOurContestText .. "\f"
+          .. t._Route24CooltrainerM1YouJustEarnedAPrizeText, function()
+          if not require("src.inventory.Bag").add(game.save, "NUGGET", 1,
+              game.data) then
+            push(game, t._Route24CooltrainerM1NoRoomText, done)
+            return
+          end
           flags.EVENT_GOT_NUGGET = true
-          require("src.inventory.Bag").add(game.save, "NUGGET", 1)
-          push(game, ("%s received\na NUGGET!"):format(game.save.player.name),
-            function()
-              ask(game, "By the way, would\nyou like to join\nTEAM ROCKET?",
-                function()
-                  push(game, "Arrgh! You are\nnot convinced?\fThen I'll show\n"
-                    .. "you my power!", battleOrDone)
-                end)
-            end)
-        end)
+          game.stringBuffer = game.data.items.NUGGET.name
+          push(game, t._Route24CooltrainerM1ReceivedNuggetText, function()
+            push(game, t._Route24CooltrainerM1JoinTeamRocketText,
+              battleOrDone)
+          end, require("src.render.TextBox").soundOpts(game, "Get_Item1"))
+        end, require("src.render.TextBox").soundOpts(game, "Get_Item1"))
         return
       end
       battleOrDone()

data/scripts/story5.lua

@@ -4,9 +4,9 @@ local M = {}
 
 local function text(game) return game.data.text end
 
-local function push(game, s, done)
+local function push(game, s, done, opts)
   local TextBox = require("src.render.TextBox")
-  game.stack:push(TextBox.new(game, s, done))
+  game.stack:push(TextBox.new(game, s, done, opts))
 end
 
 -- fill the extracted text placeholders ({RAM:...}, {PLAYER})
@@ -25,8 +25,8 @@ local function gift(opts)
     local t = text(game)
     local itemName = game.data.items[opts.item].name
     local subs = { ram = itemName, player = game.save.player.name }
-    local function say(label, fallback, cb)
-      push(game, fill(t[label] or fallback, subs), cb)
+    local function say(label, fallback, cb, sopts)
+      push(game, fill(t[label] or fallback, subs), cb, sopts)
     end
     if game.save.flags[opts.flag] then
       say(opts.already or opts.explain, "It's a useful\nitem, isn't it?", done)
@@ -39,15 +39,16 @@ local function gift(opts)
       end
       game.save.flags[opts.flag] = true
       local idef = game.data.items[opts.item]
-      require("src.core.Sound").play(game.data,
-        (idef and idef.keyItem) and "Get_Key_Item" or "Get_Item1")
+      -- the received texts carry sound_get_item_1 / sound_get_key_item, so
+      -- the jingle only fires once that box has typed out
       say(opts.received, "{PLAYER} received\n{RAM:}!", function()
         if opts.explain then
           say(opts.explain, "", done)
         else
           done()
         end
-      end)
+      end, require("src.render.TextBox").soundOpts(game,
+        (idef and idef.keyItem) and "Get_Key_Item" or "Get_Item1"))
     end
     if opts.pre then say(opts.pre, opts.preFallback or "", give) else give() end
   end
@@ -445,7 +446,7 @@ local function pewterGymEscort(game, ow)
   end
 
   local function afterWalk()
-    if guy then guy.facing = "left" end
+    if guy then guy.stepFrames, guy.facing = nil, "left" end
     Music.playMap(game.data, "PEWTER_CITY")
     push(game, t._PewterCityYoungsterGoTakeOnBrockText
       or "Go take on BROCK\nat the GYM first!", walkHome)
@@ -468,6 +469,11 @@ local function pewterGymEscort(game, ow)
   end
 
   local function beginWalk()
+    -- the escort runs the youngster on the player's own frames per cell
+    -- engine/overworld/movement.asm:737 (DoScriptedNPCMovement)
+    if guy then
+      guy.stepFrames = ow.player.stepFramesCur or ow.player.stepFrames
+    end
     Music.play(game.data, "Music_MuseumGuy")
     if guy and head > 0 then
       local h = 0
@@ -508,12 +514,12 @@ M.PEWTER_CITY = {
 -- Rival ambush: show the hidden rival, walk him up to the player, run
 -- the battle rows, march him back and hide him.  On a loss the walk is
 -- skipped (the blackout rebuilds the map mid-script).
-local function runAmbush(game, ow, rows, playerFacing)
+local function runAmbush(game, ow, rows, playerFacing, musicOpts)
   if ow.runner:isRunning() then return false end
   ow.player.facing = playerFacing
   -- the rival encounter sting (MUSIC_MEET_RIVAL); the battle music
   -- takes over and the map theme returns after the victory jingle
-  require("src.core.Music").play(game.data, "Music_MeetRival")
+  require("src.core.Music").play(game.data, "Music_MeetRival", nil, musicOpts)
   ow.runner:run(rows)
   return true
 end
@@ -567,10 +573,12 @@ local function route22Scene(n, objIndex, objName, oppClass, baseParty, beatFlag,
     { "face_object", objIndex, rivalFacing },                  -- 3
     { "show_text", "_Route22RivalBeforeBattleText" .. n },     -- 4
     { "rival_battle", oppClass, baseParty },                   -- 5
-    { "jump_if_false", 11 },                                   -- 6
+    { "jump_if_false", 12 },                                   -- 6
     { "set_flag", beatFlag },                                  -- 7
     { "show_text", "_Route22Rival" .. n .. "DefeatedText" },   -- 8
     { "show_text", "_Route22RivalAfterBattleText" .. n },      -- 9
+    { "play_music", "Music_MeetRival", { start = "rival",
+      tempo = n == 2 and 100 or nil } },
     { "walk_npc", objIndex, route22ExitDirs(n, py) },          -- 10
     { "hide_object", "ROUTE_22", objName },                    -- 11
   }
@@ -594,7 +602,8 @@ M.ROUTE_22 = {
     if f.EVENT_BEAT_GIOVANNI and not f.EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE then
       return runAmbush(game, ow,
         route22Scene(2, 2, "ROUTE22_RIVAL2", "OPP_RIVAL2", 10,
-                     "EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE", y), playerFacing)
+                     "EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE", y), playerFacing,
+        { tempo = 100 })
     end
     return false
   end,
@@ -618,10 +627,11 @@ local function ceruleanRivalScene(px, py)
     { "face_object", 1, "down" },                              -- 3
     { "show_text", "_CeruleanCityRivalPreBattleText" },        -- 4
     { "rival_battle", "OPP_RIVAL1", 7 },                       -- 5
-    { "jump_if_false", 11 },                                   -- 6
+    { "jump_if_false", 12 },                                   -- 6
     { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },               -- 7
     { "show_text", "_CeruleanCityRivalDefeatedText" },         -- 8
     { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 9
+    { "play_music", "Music_MeetRival", { start = "rival" } },
     { "walk_npc", 1, ceruleanRivalExitDirs(px) },              -- 10
     { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 11
   }
@@ -730,7 +740,7 @@ local JIGGLYPUFF_SILENCE, JIGGLYPUFF_STEP, JIGGLYPUFF_TAIL = 32, 24, 48
 -- Built as a TextBox `auto` table: auto.sound fires the frame the last
 -- page has typed out (PrintText returning), and auto.tick then runs once
 -- per frame while the gate it returns still reads as playing.
-local function jigglypuffDance(game, npc)
+local function jigglypuffDance(game, npc, ow)
   local Music = require("src.core.Music")
   -- .findMatchingFacingDirectionLoop: the rotation picks up at the entry
   -- matching the sprite's current facing (showMapText has just turned it
@@ -776,7 +786,13 @@ local function jigglypuffDance(game, npc)
         if npc then npc.facing = JIGGLYPUFF_SPIN[step] end
         return
       end
-      if frames >= JIGGLYPUFF_TAIL then phase = "done" end
+      if frames >= JIGGLYPUFF_TAIL then
+        phase = "done"
+        if require("src.core.GameVersion").isYellow()
+            and require("src.world.PikachuFollower").starterInParty(game.save) then
+          ow.pikachuPewterSleepScene = true
+        end
+      end
     end,
   }
 end
@@ -789,7 +805,7 @@ M.PEWTER_POKECENTER = {
       local TextBox = require("src.render.TextBox")
       game.stack:push(TextBox.new(game,
         text(game)._PewterPokecenterJigglypuffText or "JIGGLYPUFF: Puu\npupuu!",
-        done, { auto = jigglypuffDance(game, npc) }))
+        done, { auto = jigglypuffDance(game, npc, ow) }))
     end,
   },
 }
@@ -864,10 +880,11 @@ M.SILPH_CO_7F = {
       { "face_object", 9, "up" },                              -- 4
       { "show_text", "_SilphCo7FRivalWaitedHereText" },        -- 5
       { "rival_battle", "OPP_RIVAL2", 7 },                     -- 6
-      { "jump_if_false", 12 },                                 -- 7
+      { "jump_if_false", 13 },                                 -- 7
       { "set_flag", "EVENT_BEAT_SILPH_CO_RIVAL" },             -- 8
       { "show_text", "_SilphCo7FRivalDefeatedText" },          -- 9
       { "show_text", "_SilphCo7FRivalGoodLuckToYouText" },     -- 10
+      { "play_music", "Music_MeetRival", { start = "rival" } },
       { "move_npc_to", 9, 5, y + 1 },                          -- 11
       { "hide_object", "SILPH_CO_7F", "SILPHCO7F_RIVAL" },     -- 12
     }, "down")
@@ -899,10 +916,11 @@ M.SS_ANNE_2F = {
       { "face_object", 2, onLeft and "down" or "right" },      -- 3
       { "show_text", "_SSAnne2FRivalText" },                   -- 4
       { "rival_battle", "OPP_RIVAL2", 1 },                     -- 5
-      { "jump_if_false", 11 },                                 -- 6
+      { "jump_if_false", 12 },                                 -- 6
       { "set_flag", "EVENT_BEAT_SS_ANNE_RIVAL" },              -- 7
       { "show_text", "_SSAnne2FRivalDefeatedText" },           -- 8
       { "show_text", "_SSAnne2FRivalCutMasterText" },          -- 9
+      { "play_music", "Music_MeetRival", { start = "rival" } },
       { "walk_npc", 2, ssAnne2FRivalExitDirs(onLeft) },        -- 10
       { "hide_object", "SS_ANNE_2F", "SSANNE2F_RIVAL" },       -- 11
     }, onLeft and "up" or "left")

data/scripts/victories.lua

@@ -28,6 +28,14 @@
 -- is full; `gotFlag` (pokered's EVENT_GOT_TM*) is set only on a
 -- successful give, which is what makes the leader's talk script retry
 -- later (gyms.lua).
+--
+-- `badgeSound` / `tmSound` are the text sound command each gym's reward
+-- text carries right after its FIRST label -- home/text.asm TextCommand_SOUND
+-- plays it once that page has typed out and then blocks on
+-- WaitForSoundToFinish, so the jingle sits between the pages rather than
+-- under them.  macros/scripts/text.asm defines sound_level_up as
+-- sound_get_item_1, so Pewter's and Viridian's badge lines are Get_Item1
+-- too.  Vermilion, Celadon and Fuchsia carry no sound on the badge text.
 
 local function range(prefix, first, last)
   local t = {}
@@ -50,6 +58,8 @@ return {
                         { "PEWTER_CITY", "PEWTERCITY_YOUNGSTER" },
                         { "ROUTE_22", "ROUTE22_RIVAL1" },
                       },
+                      badgeSound = "Get_Item1", -- sound_level_up
+                      tmSound = "Get_Item1",
                       dialogue = {
                         "_PewterGymBrockReceivedBoulderBadgeText",
                         "_PewterGymBrockBoulderBadgeInfoText",
@@ -64,6 +74,8 @@ return {
                       gotFlag = "EVENT_GOT_TM11",
                       noRoom = "_CeruleanGymMistyTM11NoRoomText",
                       deactivate = range("EVENT_BEAT_CERULEAN_GYM_TRAINER_", 0, 1),
+                      badgeSound = "Get_Key_Item",
+                      tmSound = "Get_Item1",
                       dialogue = {
                         "_CeruleanGymMistyReceivedCascadeBadgeText",
                       },
@@ -76,6 +88,7 @@ return {
                          gotFlag = "EVENT_GOT_TM24",
                          noRoom = "_VermilionGymLTSurgeTM24NoRoomText",
                          deactivate = range("EVENT_BEAT_VERMILION_GYM_TRAINER_", 0, 2),
+                         tmSound = "Get_Key_Item",
                          dialogue = {
                            "_VermilionGymLTSurgeReceivedThunderBadgeText",
                          },
@@ -89,6 +102,7 @@ return {
                       gotFlag = "EVENT_GOT_TM21",
                       noRoom = "_CeladonGymTM21NoRoomText",
                       deactivate = range("EVENT_BEAT_CELADON_GYM_TRAINER_", 0, 6),
+                      tmSound = "Get_Item1",
                       dialogue = {
                         "_CeladonGymErikaReceivedRainbowBadgeText",
                       },
@@ -102,6 +116,7 @@ return {
                      gotFlag = "EVENT_GOT_TM06",
                      noRoom = "_FuchsiaGymKogaTM06NoRoomText",
                      deactivate = range("EVENT_BEAT_FUCHSIA_GYM_TRAINER_", 0, 5),
+                     tmSound = "Get_Key_Item",
                      dialogue = {
                        "_FuchsiaGymKogaReceivedSoulBadgeText",
                      },
@@ -115,6 +130,8 @@ return {
                         gotFlag = "EVENT_GOT_TM46",
                         noRoom = "_SaffronGymSabrinaTM46NoRoomText",
                         deactivate = range("EVENT_BEAT_SAFFRON_GYM_TRAINER_", 0, 6),
+                        badgeSound = "Get_Key_Item",
+                        tmSound = "Get_Item1",
                         dialogue = {
                           "_SaffronGymSabrinaReceivedMarshBadgeText",
                         },
@@ -128,6 +145,8 @@ return {
                        gotFlag = "EVENT_GOT_TM38",
                        noRoom = "_CinnabarGymBlaineTM38NoRoomText",
                        deactivate = range("EVENT_BEAT_CINNABAR_GYM_TRAINER_", 0, 6),
+                       badgeSound = "Get_Key_Item",
+                       tmSound = "Get_Item1",
                        dialogue = {
                          "_CinnabarGymBlaineReceivedVolcanoBadgeText",
                        },
@@ -141,6 +160,8 @@ return {
                          gotFlag = "EVENT_GOT_TM27",
                          noRoom = "_ViridianGymGiovanniTM27NoRoomText",
                          deactivate = range("EVENT_BEAT_VIRIDIAN_GYM_TRAINER_", 0, 7),
+                         badgeSound = "Get_Item1", -- sound_level_up
+                         tmSound = "Get_Item1",
                          dialogue = {
                            "_ViridianGymGiovanniReceivedEarthBadgeText",
                          },

docs/ios-sideload.md

@@ -1,6 +1,6 @@
 # Sideload the iOS build with AltStore
 
-Every GitHub Release ships an IPA (`gen1recomp-*-ios.ipa`). Install it on
+Every GitHub Release ships an IPA (`gen1recomp++-*-ios.ipa`). Install it on
 your iPhone or iPad with [AltStore Classic](https://altstore.io/) — AltStore
 re-signs the app with **your** free Apple ID so you do not need a Mac or
 Xcode.
@@ -23,7 +23,7 @@ Stuck? Start here:
 
 ## 2. Install the game
 
-1. Download `gen1recomp-*-ios.ipa` from
+1. Download `gen1recomp++-*-ios.ipa` from
    [Releases](https://github.com/bryanthaboi/gen1recomp/releases).
 2. Open **AltStore** on the phone (AltServer must be running on the same
    Wi‑Fi, or keep the phone plugged into the computer).

docs/launcher.md

@@ -130,18 +130,20 @@ before `Game:load`, so **it never loads a mod's entry chunk**; only
   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).
+  `"MOD"`, uppercased. `enabledByVersion` contains an answer for each game;
+  missing entries default to enabled (except experimental mods), matching the
+  loader. On the first run with per-game controls, legacy shared choices are
+  copied to every installed game's answer.
 - `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
+- `LauncherMods.setEnabled(id, bool, version)` persists the selected game's
+  answer, so the running game and the in-game `ManagerState` see the change on
+  next boot. The MODS panel renders a coloured checkbox for Red, Blue, Yellow,
+  and Gold on every row 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

docs/linux-arm-sbc.md

@@ -0,0 +1,54 @@
+# Linux ARM SBC Handhelds (PortMaster)
+
+Download `gen1recomp-*-sbc-portmaster.zip` from the [Gen1Recomp releases](https://github.com/bryanthaboi/gen1recomp/releases). This build targets 64-bit Linux ARM handhelds with PortMaster, including compatible H700 devices.
+
+## Install
+
+1. Unzip the release. It contains `gen1recomp-sbc.sh` and a `gen1recomp-sbc/` folder.
+2. Copy both as siblings into your device's PortMaster ports directory, commonly `Roms/Ports (PORTS)/` or `Roms/PORTS/`.
+3. Install PortMaster for your firmware and refresh the Ports list.
+4. Copy your legally owned canonical US Red or Blue `.gb` file into `gen1recomp-sbc/lovegame/`.
+5. Launch **gen1recomp-sbc** from Ports and choose the ROM.
+
+The pack includes `portable.txt`, so saves and ROM-derived cache remain beside the game on the SD card. The build never ships ROM-derived bytes.
+
+Canonical US cart SHA-1 values:
+
+- Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
+- Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
+
+## Controls
+
+| Input | Action |
+| --- | --- |
+| D-pad | Move cursor |
+| A | Click / confirm |
+| L1 / R1 | Switch tabs |
+| Start / Select | Play or choose ROM |
+
+In-game controls use the normal PortMaster/SDL mapping and can be rebound in **OPTIONS → CONTROLS**.
+
+## Runtime and suspend
+
+The package bundles PortMaster's LÖVE 11.5 aarch64 runtime. The launcher sources `control.txt`, calls `get_controls`, applies an optional CFW override, invokes `pm_platform_helper`, and calls `pm_finish` on exit. Paths are relative to the launcher, allowing different firmware mount points.
+
+Suspend/resume uses the existing LÖVE focus/visibility lifecycle: input is reset on focus loss and the game resumes when the window becomes visible again. Exact power-button behavior remains firmware-dependent; hardware validation has been performed on the TrimUI Brick, not every SBC or H700 device.
+
+## Building
+
+Release workflows build this automatically. Standalone builds resolve the latest published Gen1Recomp release by default:
+
+```sh
+./build-linux-arm-sbc.sh --version 0.1.75
+```
+
+For development, package a local checkout explicitly:
+
+```sh
+GEN1RECOMP_SOURCE_DIR="$PWD" ./build-linux-arm-sbc.sh --version 0.1.0
+# or: ./build-linux-arm-sbc.sh --source "$PWD" --version 0.1.0
+```
+
+The generated `port.json` records the source release tag. `install-linux-arm-sbc.sh` is a macOS helper for copying a built pack to a mounted SD card.
+
+PortMaster device support and runtime integration are maintained in the [PortMaster](https://github.com/PortsMaster/PortMaster-New) ecosystem.

docs/mod-api-gen2-compat.md

@@ -96,14 +96,14 @@ The launcher asks the same question of a mod's dependencies: one whose hard
 dependency does not run on the selected game reads `Needs <id> (not for Gold)`,
 matching the loader's contagious skip.
 
-A separate overlay, `options.modsByVersion[version][id]`, is where a per-game
-enable flag will live. It is a preview: `SaveData.PER_VERSION_MODS` is `false`,
-so `SaveData.modScope` answers nil for every caller and the launcher panel, the
-in-game manager and the loader all read *and* write the one shared
-`options.mods` flag. Nothing consults the overlay for enablement until that
-flips, which is deliberate: the overlay is plantable from an imported
-`.g1rmodlist`, and a reader scoped differently from the writers would show a
-mod set no boot would honour.
+A separate overlay, `options.modsByVersion[version][id]`, holds each game's
+enable flag. The launcher shows a coloured Red / Blue / Yellow / Gold checkbox
+for every installed mod, and the loader and in-game manager read the same
+game-specific answer on the next boot. On the first launch after this feature,
+the existing shared state is copied to every game, so a mod that was enabled
+remains enabled everywhere; after that, changing one checkbox affects only
+that game. New mods still default to enabled on every game (experimental mods
+retain their explicit opt-in default).
 
 That is deliberate. Gold reimplements the battle engine, the overworld, the
 script VM and the save format, so a Gen 1 mod dropped into a Gold boot would
@@ -118,10 +118,11 @@ Gen 2 games no longer loads on Red, Blue or Yellow. Say `["all"]` or list both
 generations if you want both.
 
 Two riders. **A hard dependency that does not run here takes the dependent down
-with it**, as a skip rather than a failure and carrying the dependency's own
-wording (`depends on X, which does not run here (For Blue, not Red)`), so the
-whole chain has to cover the same games. And **the claim is yours, not the last
-word**: it is the manager's `TRY HERE ANYWAY` row that lets a player run a mod
+with it** (unless scoped to specific games, e.g.
+`dependencies: [{ id = "x", games = ["gen2"] }]`), as a skip rather than a
+failure and carrying the dependency's own wording (`depends on X, which does not
+run here (For Blue, not Red)`), so the whole chain has to cover the same games.
+And **the claim is yours, not the last word**: it is the manager's `TRY HERE ANYWAY` row that lets a player run a mod
 whose author never opted in, which is the only route for a mod written before
 the field existed. The override is per game -- `options.modsGen2[id]` is a
 `{ [version] = true }` table, so forcing a mod onto Red does not force it onto
@@ -474,6 +475,8 @@ Generation-agnostic; nothing to adapt.
 (`src/world/gen2/WorldAPI.lua`). Two differences show through and are
 documented on the module: Gold's world is not a stack state, and Gen 2 event
 flags are numeric ids into `wEventFlags` rather than string keys.
+`mapOverview` returns the same read-only terrain, tile-shading, and marker
+shape, using Gold's live object masks and event flags to omit collected items.
 `spawnNpc` / `removeNpc` append onto the map def's own object list, the way the
 Gen 1 arm does, so a spawned actor is pooled, drawn, walked and talked to like
 an extracted one and survives a map reload; it is not serialized, so a mod
@@ -531,8 +534,9 @@ gains a field instead of the name gaining a prefix.
   `pokemon.level_up`, `pokemon.move_learned`; hooks `battle.damage`,
   `battle.crit`, `battle.accuracy`, `battle.turn_order`,
   `battle.enemy_action`, `battle.run`, `battle.exp_award`, `exp.gain`,
-  `catch.rate`, `trainer.party`, `battle.overlay`, `battle.low_health_alarm`
-  and `battle.catch_exp`. One payload difference: Gen 1's vanilla
+  `catch.rate`, `trainer.party`, `battle.overlay`, `battle.low_health_alarm`,
+  `battle.catch_exp`, `battle.bottom_ui_visible` and
+  `battle.status_hud_visible`. One payload difference: Gen 1's vanilla
   `battle.low_health_alarm` link reads `ctx.battle.data`, and Gold's battle
   screen has no `.data` field, so the Gen 2 site **adds** `ctx.data` beside the
   Gen 1 keys. A mod that calls `nextFn` is unaffected; one that reaches through
@@ -544,11 +548,13 @@ gains a field instead of the name gaining a prefix.
   each row's decision in `evolution.check`. The hook passes `data` where Gen 1
   passes `game`; positions 2-4 (mon, row, trigger) match.
 - *The frame (`src/core/Game2.lua`):* hooks `input.step`, `input.pointer`,
-  `render.zones`, `render.compose`, `render.letterbox`, `render.hud`. Each sits
+  `render.zones`, `render.compose`, `render.output_enabled`, `render.output`,
+  `render.letterbox`, `render.hud`. Each sits
   at the same moment `src/core/Game.lua` and `src/render/Renderer.lua` raise it
   -- the logic tick before the pad is read, a pointer the touch overlay gets
   first refusal on, the palette zone list handed to the present pass, the
-  letterbox, and the finished playfield rect -- and carries the same payload.
+  composed frame before GBCFX, the letterbox, and the finished playfield rect
+  -- and carries the same payload.
   `render.hud`'s `gameX` / `gameY` really is where Gold's dialogue boxes and
   menus land, because `Chrome.fitScale` / `fitOrigin` and `World:fitScale`
   compute the same number. `render.zones` is handed `nil` in GBC mode (Gold

docs/modding.md

@@ -21,6 +21,76 @@ luajit tools/gen_registry_docs.lua
 luajit tools/gen_registry_docs.lua ../gen1recomp.wiki
 ```
 
+## Manifest specification (`manifest.json`)
+
+Every mod contains a root `manifest.json` defining its metadata, supported games, and dependencies for the engine loader.
+
+```json
+{
+  "id": "my_mod",
+  "name": "My Cool Mod",
+  "version": "1.0.0",
+  "api": 2,
+  "entry": "main.lua",
+  "profile": "content",
+  "category": "GAMEPLAY",
+  "games": ["gen1", "gen2"],
+  "game_version": ">=0.0.0-dev <2.0.0",
+  "priority": 100,
+  "dependencies": [
+    "helper_lib@^1.0.0",
+    { "id": "pokegear_cards", "games": ["gen2"], "range": "^1.0.0", "github": "1jamie/pokegear_cards" }
+  ],
+  "optional_dependencies": [
+    "gen1_modern_ui"
+  ],
+  "conflicts": [],
+  "permissions": ["engine_internals"],
+  "description": "A brief description of the mod.",
+  "github": "author/my_mod"
+}
+```
+
+### Manifest Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique identifier (lowercase alphanumeric, underscores, hyphens). |
+| `name` | `string` | Human-readable title shown in launcher and manager. |
+| `version` | `string` | Semantic version string (e.g. `"1.0.0"`). |
+| `api` | `integer` | Mod API level (`2` for current standard, `1` for legacy). |
+| `entry` | `string` | Entry Lua file path relative to mod root (usually `"main.lua"`). |
+| `profile` | `string` | Mod profile: `"content"`, `"overhaul"`, or `"total_conversion"`. |
+| `category` | `string` | Categorization chip (e.g. `"GAMEPLAY"`, `"CONTENT"`, `"UI"`, `"AUDIO"`). |
+| `games` | `array` | Supported game versions: `["gen1"]`, `["gen2"]`, `["red"]`, `["blue"]`, `["yellow"]`, `["gold"]`, or `["all"]`. |
+| `game_version`| `string` | Semver range of required engine version (e.g. `">=0.0.0-dev <2.0.0"`). |
+| `priority` | `integer` | Load priority order (lower numbers load earlier; dependencies always precede dependents regardless of priority). |
+| `dependencies` | `array` | Hard required dependencies. A mod will not load if a required dependency is missing or disabled for the active game. |
+| `optional_dependencies` | `array` | Soft dependencies. Guarantees that if the target mod is present and active, it loads *before* this mod without blocking load if absent. |
+| `conflicts` / `incompatible` | `array` | List of mod IDs that cannot run concurrently with this mod. |
+| `permissions` | `array` | Requested privileges (e.g. `["engine_internals"]`, `["network"]`, `["filesystem"]`). |
+| `github` | `string` | GitHub repository (`"owner/repo"`) used for update checks and dependency download links. |
+
+### Declaring Dependencies & Scoping
+
+Dependencies in `dependencies` and `optional_dependencies` can be declared in several formats:
+
+1. **Simple string**: `"mod_id"`
+2. **Version-pinned string**: `"mod_id@^1.2.0"`
+3. **Repository-hinted string**: `"mod_id#owner/repo"` or `"mod_id@^1.2.0#owner/repo"`
+4. **Structured object**:
+   ```json
+   {
+     "id": "mod_id",
+     "range": "^1.2.0",
+     "games": ["gen2"],
+     "github": "owner/repo"
+   }
+   ```
+
+#### Version-Scoped Dependencies
+When a mod supports multiple games (`"games": ["gen1", "gen2"]`), a dependency can specify `"games": ["gen2"]` to indicate it is only required when booting Gen 2. When booting Gen 1, the engine will ignore the dependency, preventing unnecessary boot blocks on games that do not need it.
+
 ## Mods and Gold (Gen 2)
 
 The mod API is one API across both generations, but Gold runs its own battle
@@ -66,7 +136,8 @@ optional visual `tileRows` at 2x resolution, and optional `tileDetailRows` at
 `"3"` (darkest); their matching width and height fields describe the grid.
 `markers` contains active `{ kind, x, y }` points in map-cell coordinates for
 `warp`, visible `item`, and untaken `hidden` locations. All fields are
-read-only snapshots; mods choose which layers to render.
+read-only snapshots; mods choose which layers to render. Red and Gold expose
+the same contract while applying their own object and event visibility rules.
 
 ## Party ordering
 
@@ -340,6 +411,18 @@ failure as a failed first checkpoint rather than claiming restart safety.
 See RFC 0003, RFC 0004, RFC 0005, and RFC 0006 for exact contracts and error
 codes.
 
+At that same settled supported wild/trainer decision boundary, a tool may claim
+START through `battle.menu_auxiliary`. It receives `(next, game, context)`, where
+`context` is the data-only `{ kind = "wild" }` or `{ kind = "trainer" }`; it
+never receives the live battle controller. Return `true` to consume START after
+opening source-owned UI, or call `next(game, context)` to allow lower-priority
+handlers. With no handler, START remains inert. Ordinary encounters and the
+validated built-in scripted battle origins described by RFC 0005 are eligible;
+opaque scripts, link/Safari/ghost/demo battles, action queues,
+animation/messages, forced choices, and every phase that cannot safely be
+checkpointed remain excluded. Exceptions are contained by normal hook isolation
+and fall through without advancing a turn.
+
 ## Developer console
 
 Boot with developer mode on to unlock the in-game console and hot-reload
@@ -427,6 +510,20 @@ oldest queued event as `"action,x,y"` in submitted-frame coordinates, or `nil`.
 This is what lets a mod lay the two passes out as two stacked Game Boy screens,
 or push one onto a second screen, without the engine knowing the layout.
 
+`render.output_enabled` and `render.output` are the later, whole-window seam
+for mods that need the engine's normal composite rather than its separate
+layers. It runs after registered present pipelines and before GBCFX,
+`render.hud`, and touch controls. A mod wraps both hooks: the first returns
+`true` only while output ownership is needed, and the second receives
+`(next, ctx)` with `canvas`, `width`, `height`, `gameX`, `gameY`, `gameWidth`,
+`gameHeight`, `scale`, `dpiX`,
+`dpiY`, and `generation`. Returning `true` from `render.output` takes over the
+window; calling `next(ctx)` keeps the normal presentation. Both hooks default
+to `false`. Enabling the seam requires a full-window canvas for that frame.
+With no `render.output` subscriber, or while `render.output_enabled` is false,
+the existing presentation path is unchanged. `render.compose` takes precedence
+when it owns the frame.
+
 `screen.render_visible` receives `(next, state)` while the main screen is being
 composed. Return `false` to omit that state from drawing, opacity selection and
 palette-zone ownership. The state remains on the stack and keeps its normal
@@ -442,9 +539,13 @@ identifiers: `pc_box_withdraw`, `pc_box_deposit`, `pc_box_release`,
 `battle.bottom_ui_visible` and `battle.status_hud_visible` independently
 control the battle text/menu layer and the HP/status panels. Both receive
 `(next, state)` and default to `true`, so vanilla rendering is unchanged.
-Pushed text boxes also pass through `battle.bottom_ui_visible`; a wrapper that
-only owns battle presentation should return `false` only for its active battle
-or text-box state.
+Both hooks apply to Gen 1 and Gen 2 battles.
+Text boxes and YES/NO prompts pushed above a battle inherit a `false` result
+for that battle, so hiding the bottom layer cannot leave their white backing
+behind under another overlay. Text boxes also pass through the hook as their
+own state, preserving selective control outside a battle; a wrapper that only
+owns battle presentation should return `false` only for its active battle or
+text-box state.
 
 `core.logic_speed` receives `(next, game)` once per `Game:logicSpeed()` call
 (once per frame). Vanilla behavior resolves the per-category GAME SPEED
@@ -495,6 +596,21 @@ Neither hook needs a `Runtime.wantsHook` guard before calling it: `Hooks:call`
 already falls straight through to the vanilla function when no mod has
 wrapped the name, at negligible cost.
 
+## Detached Pokémon icon presentation
+
+`mod.ui.PokemonIcon.draw(game, summary, x, y, opts)` draws the same party icon
+the native Party menu would resolve without exposing a live Pokémon record or
+the private Party menu. `summary` is the detached data-only shape
+`{ species = string, hp = integer, maxHp = integer }`; `opts.selected` and
+`opts.counter` optionally request the native selected-icon animation phase.
+
+The engine retains icon ownership. Content registered through
+`mod.content.icons`, species `icon` definitions, asset overrides, and the
+public `pokemon.icon` hook therefore continue to compose. Invalid summaries
+return `false, code, message` and draw nothing. The helper is presentation
+only: it does not expose moves, status, checkpoint payloads, or mutable party
+state.
+
 ## Shared date and time presentation
 
 The global Options menu owns `DATE FORMAT` (`DEVICE`, `DD-MM-YYYY`,
@@ -514,3 +630,41 @@ local both = mod.datetime:dateTime(game, createdAt)
 The live `game` supplies only the current option context. Formatting never
 mutates the save, options, or timestamp, and invalid timestamps return
 `"----"`.
+
+## Device power information
+
+Sandboxed mods can read the host's battery state without receiving the rest
+of `love.system`:
+
+```lua
+local state, percent = mod.device:powerInfo()
+```
+
+`state` follows LÖVE's values: `"unknown"`, `"battery"`, `"nobattery"`,
+`"charging"`, or `"charged"`. `percent` is `0` through `100`, or `nil` when
+the platform cannot report it. The facade is read-only and does not expose
+URL launching, clipboard access, or other system operations.
+
+## Real-world steps
+
+On iOS and Android the game counts the player's real-world steps natively
+(HealthKit / the hardware step counter). A mod reaches that bridge through
+the `steps` permission in `manifest.json`, which the player sees in the
+mod manager like every other permission:
+
+```lua
+if mod.steps:available() then
+  mod.steps:sync()                -- async; OS consent sheet on first use
+end
+-- later, at a quiet moment:
+local walk = mod.steps:poll()     -- { steps = n, from = ?, to = ? } or nil
+```
+
+`available()` is `false` on builds without the bridge (desktop) and for
+mods without the permission, so a probe is always safe. `sync()` asks the
+platform to refresh its count and returns whether there was a bridge to
+ask. `poll()` returns the next delivery for this mod — the engine consumes
+the native side's pending file itself, each permissioned mod receives its
+own copy of a delivery, and steps are anchored natively so the same walk
+is never delivered twice. Without the permission, `sync` and `poll` raise
+an error naming it.

docs/new-features.md

@@ -19,16 +19,16 @@ Features intentionally added beyond the original Pokémon Red, Blue, and Yellow
 * **Soft reset button combination**
 * **Keyboard and controller rebinding**
 * **Mod profiles** with separate mod settings and save slots
+* **Sandboxed mods**: an installed mod can read only its own folder and write only its own storage, so it cannot reach the rest of your device
 * **Improved launcher and save editor UI**, including background downloads and update checks
 * **Direct-launch options** for shortcuts, Steam entries, and handheld frontends
 * **Custom boot branding**
 
 ## Pokémon Gold (Gen 2)
 
-A fourth game the launcher can import and play, built from pret/pokegold the same way Red/Blue/Yellow are built from pokered. Port extras beyond the cartridge:
+A fourth game the launcher can import and play, built from pret/pokegold the same way Red/Blue/Yellow are built from pokered (and pokeyellow). Port extras beyond the cartridge:
 
-* **Separate Gold save file** beside the Gen 1 ones
-* **COLOR, zoom, tilt, GBC FX, and quick save/load** on the same keys as Gen 1
+* **COLOR, zoom, tilt, GBC FX, and quick save/load** 
 * **UI that stays fixed while the overworld zooms**
 * **Border-block surrounds** for maps smaller than the screen
 * **Gold-specific launcher options**
@@ -39,5 +39,4 @@ A fourth game the launcher can import and play, built from pret/pokegold the sam
 * **Followers** for mods, plus Gen 2-only registries and hooks
 * **On-screen touch pad** and controller SELECT for registered items
 
-Actual approximations, and missing original behavior are documented separately in `docs/known-differences.md`.
 

docs/preparing-your-mod-for-gen2.md

@@ -258,20 +258,34 @@ row on the detail screen. The launcher's dependency verdict asks the same
 question of your dependencies: a mod whose hard dependency does not run on the
 selected game reads `Needs <id> (not for Gold)` rather than `Ready`.
 
+### Scoping dependencies per game / generation
+
+For mods targeting multiple generations (`"games": ["gen1", "gen2"]`), a hard
+dependency can be scoped to specific games so that it is only enforced when
+booting those games:
+
+```json
+"dependencies": [
+  { "id": "pokegear_cards", "games": ["gen2"], "range": "^1.0.0", "github": "1jamie/pokegear_cards" }
+]
+```
+
+When booting a Gen 1 game (Red, Blue, Yellow), the engine loader sees that
+`pokegear_cards` is scoped to `"gen2"` and will not skip or block the parent mod
+on Gen 1. When booting Gen 2 (Gold), `pokegear_cards` is strictly required.
+
+For conditional integrations where the dependency is optional across the board,
+`optional_dependencies` remains the standard pattern.
+
 ### One limit worth knowing
 
-**Per-game enable flags are still a preview.** The overlay
-`options.modsByVersion[version][id]` exists and every surface goes through
-`SaveData.modEnabled` / `SaveData.setModEnabled`, but
-`SaveData.PER_VERSION_MODS` is `false`
-(`src/core/SaveData.lua:489`). While it is false, `SaveData.modScope` answers
-nil for every caller, so the launcher panel, the in-game manager *and* the
-loader all read and write the one shared `options.mods` flag and the overlay is
-not consulted for enablement anywhere. That matters because the overlay is
-plantable from an imported `.g1rmodlist`: keeping every reader on the same
-scope as every writer is what stops a stored per-game flag from showing a mod
-set no boot would honour. Nothing about this affects a mod author; it affects
-what a player can currently express.
+**Enablement is per game.** The overlay
+`options.modsByVersion[version][id]` is read and written through
+`SaveData.modEnabled` / `SaveData.setModEnabled` by the launcher, in-game
+manager, and loader. Existing shared settings are copied to every game the
+first time this version sees the installed mods; from then on, each coloured
+game checkbox changes only that game's next boot. Nothing about this affects a
+mod author; it affects what a player can express.
 
 Targeting is a different question from enablement and *is* enforced per game,
 as above. The two do not share a switch.

docs/rfcs/0007-battle-menu-auxiliary-actions.md

@@ -0,0 +1,46 @@
+# RFC 0007: Battle menu auxiliary actions
+
+## Status
+
+Proposed.
+
+## Problem
+
+Tool mods can inspect/capture a persistent checkpoint only at a settled
+ordinary wild/trainer player-decision boundary. Before this proposal, that
+boundary had no public semantic input/action seam: `BattleState` consumed the
+command loop directly. A mod could reach it only through private battle/input
+internals, which would be unsafe and incompatible with controller/touch input.
+
+## Contract
+
+`mod.hooks:wrap("battle.menu_auxiliary", callback)` is called only when START
+is pressed at the existing checkpoint-safe player-decision boundary. The
+callback signature is:
+
+```lua
+function callback(next, game, context)
+  -- context is { kind = "wild" } or { kind = "trainer" }
+  -- return true after claiming START, otherwise return next(game, context)
+end
+```
+
+The context is data-only. No live battle controller, input object, serializer,
+or restoration primitive is exposed. A `true` result consumes START for that
+fixed step without selecting a battle command. With no installed handler,
+START is inert exactly as before. Hook priorities and error isolation are the
+existing generic wrapper semantics: a throwing handler is skipped and cannot
+advance battle state.
+
+The engine reuses the same internal safety predicate as battle checkpoint
+capture. Link, Safari, ghost/demo, unsupported origins, scripts, queues,
+animations, messages, forced replacement/locked actions, and unsettled HP or
+status presentation never invoke the hook.
+
+## Compatibility and verification
+
+The call is additive and no-op with no handler. ROM-free engine tests prove
+wild/trainer delivery, cursor/turn preservation, and unsafe-phase refusal;
+the mod-SDK fixture proves a loaded mod can consume the semantic action using
+only its public hook facade. `gate_hooks` automatically includes the new call
+site in no-mod parity coverage.

docs/rfcs/0008-device-power-info.md

@@ -0,0 +1,49 @@
+# RFC 0008 — Read-only device power information for sandboxed mods
+
+## Status
+
+Proposed. Engine: `Loader.lua`, `Sandbox.lua`. Test:
+`tests/modkit/cases/device_power_info.lua`.
+
+## Motivation
+
+A handheld UI mod can show the player's battery state and warn before power
+loss. The sandbox correctly removes `love.system` because that module also
+launches URLs and exposes other host operations, but it leaves no scoped way
+to read the harmless power values that LÖVE already provides.
+
+## The decision it extends
+
+Extends the mod sandbox in `src/mods/Sandbox.lua`: blocked host modules stay
+blocked while legitimate operations receive narrow engine-owned facades.
+
+## The exact API delta
+
+Add `mod.device:powerInfo() -> state, percent`.
+
+The engine calls `love.system.getPowerInfo()` outside the mod sandbox and
+returns only its first two values. `state` is one of LÖVE's standard power
+states. `percent` is `0` through `100` or `nil`. When the platform has no
+power-information backend, the result is `"unknown", nil`.
+
+No permission grants access to `love.system`; URL launching, clipboard access,
+OS identification, and the module table itself remain unavailable.
+
+## Migration note for existing mods
+
+Mods that used `love.system.getPowerInfo()` replace that call with
+`mod.device:powerInfo()`. No other mod changes.
+
+## Parity tests
+
+- **No mod:** loading no mods does not call the platform power backend.
+- **Mod API:** a fixture mod loaded through the public loader receives state
+  and percentage through `mod.device`, while the existing sandbox suite keeps
+  proving that direct `love.system` access is refused.
+- **Unavailable backend:** the public facade returns `"unknown", nil` rather
+  than inventing battery data or failing mod load.
+
+## Deprecation etiquette
+
+Nothing deprecated. The facade is additive; the sandbox's `love.system` block
+remains in force.

docs/rfcs/0009-step-bridge-permission.md

@@ -0,0 +1,68 @@
+# RFC 0009 — Permission-gated step bridge for sandboxed mods
+
+## Status
+
+Proposed. Engine: `Steps.lua` (new), `Loader.lua`, `Manifest.lua`,
+`Sandbox.lua`. Test: `tests/modkit/cases/steps_bridge.lua`. Issue: #1186.
+
+## Motivation
+
+The iOS and Android builds count the player's real-world steps natively
+(#452, #489), exposed to Lua as `love.system.syncHealthSteps()` and
+delivered as `steps_pending.json` in the save-directory root. The sandbox
+correctly blocks both — `love.system` also launches URLs, and the file API
+names paths — but that leaves the bridge with no consumer: the mod that
+step counting was built for (Pokéwalker, steps→EXP) can no longer be
+written.
+
+## The decision it extends
+
+Extends the mod sandbox in `src/mods/Sandbox.lua` (blocked host modules
+stay blocked; legitimate operations receive narrow engine-owned facades)
+and the permission model `network` established: a `manifest.json`
+permission the player sees in the mod manager that genuinely gates a
+capability.
+
+## The exact API delta
+
+A new manifest permission token, `steps`, and a `mod.steps` facade:
+
+- `mod.steps:available() -> boolean` — whether this build carries the
+  native bridge. Answers `false` without the permission, so a probe stays
+  quiet.
+- `mod.steps:sync() -> boolean` — asks the platform to refresh its count
+  (async; the OS consent sheet still appears on first use, exactly as
+  before the sandbox). `false` when there is no bridge.
+- `mod.steps:poll() -> { steps = n, from = iso?, to = iso? } | nil` — the
+  next delivery for this mod, engine-consumed from the pending file. Each
+  permissioned mod receives its own copy of a delivery.
+
+Without the permission, `sync` and `poll` raise an error naming the
+missing permission, the way the network gate does. The engine owns the
+pending file: mods never learn its name or location, and only the three
+contract fields travel. No new event, hook, or registry names.
+
+## Migration note for existing mods
+
+Mods that called `love.system.syncHealthSteps()` and read
+`steps_pending.json` themselves add `"steps"` to `permissions` and switch
+to `mod.steps:sync()` / `mod.steps:poll()`. No other mod changes.
+
+## Parity tests
+
+- **No mod:** with nothing installed the bridge is never called and a
+  pending file on disk is left untouched.
+- **Mod API:** a fixture mod with the permission syncs and receives a
+  delivery through the public loader; two permissioned mods both receive
+  the same walk; a second poll returns nil.
+- **No permission:** `available()` is false and the acting calls name the
+  missing permission; the sandbox suite keeps proving direct
+  `love.system` access is refused.
+- **Malformed delivery:** a bad or empty pending file is dropped whole
+  rather than crashing a poll (the native anchor only advances on a
+  successful sync, so nothing is lost).
+
+## Deprecation etiquette
+
+Nothing deprecated. The facade is additive; the sandbox's `love.system`
+and `love.filesystem` blocks remain in force.

docs/updater.md

@@ -26,7 +26,7 @@ JSON parsing, and sha256 verification run on a background `love.thread`
 
 ## Version.lua fields
 
-`src/core/Version.lua` carries three fields the updater reads directly (the
+`src/core/Version.lua` carries four fields the updater reads directly (the
 existing `modApi`, `linkProtocol`, `saveFormat`, and `cache` fields are
 untouched):
 
@@ -37,6 +37,11 @@ untouched):
   as a valid payload to chainload).
 - `shell` - the native-shell contract this build's fused executable
   implements.
+- `payloadHost` - the native host family an in-place payload targets. Ordinary
+  LÖVE packages use `"love"`. A specialized native package uses a distinct,
+  stable identifier and accepts only payloads carrying that same identifier.
+  A missing field defaults to `"love"`, preserving compatibility with payloads
+  released before this field existed.
 - `minShell` - the lowest shell contract required to *run* this payload.
 
 Bump `minShell` only when a payload needs something the currently-shipped
@@ -49,6 +54,12 @@ rather than deleting it, in case a future shell upgrade can run it, and
 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.
 
+Change `payloadHost` only when the packaged Lua depends on a different native
+host family. This is separate from `minShell`: the host name answers *which*
+native integration the payload targets, while the shell number answers *which
+revision* of that integration it requires. A mismatched-host payload is never
+mounted or deleted as stale; the launcher directs the player to a full package.
+
 ## Release assets
 
 Each tagged release `vX.Y.Z` carries the existing per-platform archives

install-linux-arm-sbc.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# After first boot of a compatible Linux ARM handheld (or when PortMaster is installed), reinsert the
+# SD card and run this to install gen1recomp-sbc + Red/Blue ROMs into Roms/PORTS.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+STAGE="$ROOT/.bazinga/work/linux-arm-sbc-install"
+DECPREP="${DECPREP:-$ROOT/../decprep}"
+ZIP="$ROOT/dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip"
+
+say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
+fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
+
+# Find a mounted handheld userdata volume with a ROMs or Apps directory.
+find_roms_root() {
+  local v candidate
+  for v in /Volumes/*; do
+    [ -d "$v" ] || continue
+    # Prefer a volume that already has Roms/ or Apps/
+    if [ -d "$v/Roms" ] || [ -d "$v/roms" ] || [ -d "$v/PORTS" ] || [ -d "$v/ports" ] || [ -d "$v/Apps" ]; then
+      echo "$v"
+      return 0
+    fi
+  done
+  # Fallback: common removable-volume labels
+  for v in /Volumes/SDCARD /Volumes/sdcard /Volumes/NO\ NAME /Volumes/ROMS; do
+    if [ -d "$v" ]; then
+      echo "$v"
+      return 0
+    fi
+  done
+  return 1
+}
+
+say "looking for handheld SD volume"
+ROMS_ROOT="$(find_roms_root)" || fail "no SD volume mounted. boot the handheld once, power it off, reinsert the SD, then rerun."
+
+say "using: $ROMS_ROOT"
+# Resolve the device PortMaster ports directory
+if [ -d "$ROMS_ROOT/Roms/PORTS" ]; then
+  PORTS="$ROMS_ROOT/Roms/PORTS"
+elif [ -d "$ROMS_ROOT/roms/PORTS" ]; then
+  PORTS="$ROMS_ROOT/roms/PORTS"
+elif [ -d "$ROMS_ROOT/Roms/ports" ]; then
+  PORTS="$ROMS_ROOT/Roms/ports"
+elif [ -d "$ROMS_ROOT/PORTS" ]; then
+  PORTS="$ROMS_ROOT/PORTS"
+else
+  mkdir -p "$ROMS_ROOT/Roms/PORTS"
+  PORTS="$ROMS_ROOT/Roms/PORTS"
+fi
+say "PORTS: $PORTS"
+
+# Refresh staged payload
+mkdir -p "$STAGE/PORTS"
+if [ -f "$ZIP" ]; then
+  rm -rf "$STAGE/PORTS/gen1recomp-sbc.sh" "$STAGE/PORTS/gen1recomp-sbc" "$STAGE/PORTS/port.json" \
+    "$STAGE/PORTS/gameinfo.xml" "$STAGE/PORTS/README.md"
+  unzip -q -o "$ZIP" -d "$STAGE/PORTS"
+else
+  fail "missing $ZIP — run ./build-linux-arm-sbc.sh first"
+fi
+
+# Ensure ROMs are in lovegame (Choose ROM scans this folder on minimal images)
+[ -f "$DECPREP/Pokemon - Red Version.gb" ] || fail "missing Red ROM in $DECPREP"
+[ -f "$DECPREP/Pokemon - Blue Version.gb" ] || fail "missing Blue ROM in $DECPREP"
+cp -f "$DECPREP/Pokemon - Red Version.gb" "$STAGE/PORTS/gen1recomp-sbc/lovegame/"
+cp -f "$DECPREP/Pokemon - Blue Version.gb" "$STAGE/PORTS/gen1recomp-sbc/lovegame/"
+
+say "copying gen1recomp port"
+rm -rf "$PORTS/gen1recomp-sbc" "$PORTS/gen1recomp-sbc.sh"
+cp -R "$STAGE/PORTS/gen1recomp-sbc" "$PORTS/"
+cp -f "$STAGE/PORTS/gen1recomp-sbc.sh" "$PORTS/"
+cp -f "$STAGE/PORTS/port.json" "$PORTS/"
+cp -f "$STAGE/PORTS/README.md" "$PORTS/"
+chmod +x "$PORTS/gen1recomp-sbc.sh" "$PORTS/gen1recomp-sbc/bin/love.aarch64"
+
+# Also drop carts in the stock GB folder for the emulator library
+GB_DIR=""
+for candidate in "$ROMS_ROOT/Roms/GB" "$ROMS_ROOT/roms/GB" "$ROMS_ROOT/Roms/gb"; do
+  if [ -d "$candidate" ]; then GB_DIR="$candidate"; break; fi
+done
+if [ -n "$GB_DIR" ]; then
+  say "copying .gb into $GB_DIR"
+  cp -f "$DECPREP/Pokemon - Red Version.gb" "$GB_DIR/"
+  cp -f "$DECPREP/Pokemon - Blue Version.gb" "$GB_DIR/"
+fi
+
+sync
+say "installed:"
+ls -lh "$PORTS/gen1recomp-sbc.sh"
+ls -lh "$PORTS/gen1recomp-sbc/lovegame/"*.gb
+say "eject the SD, insert it in the handheld, open Ports → gen1recomp-sbc, Choose ROM."

main.lua

@@ -14,6 +14,7 @@ local SwitchDiagnostics = require("src.debug.SwitchDiagnostics")
 local LaunchOptions = require("src.core.LaunchOptions")
 local NxDisplay = require("src.core.NxDisplay")
 local PlatformHooks = require("src.core.PlatformHooks")
+local HostDisplay = require("src.core.HostDisplay")
 
 -- Lua errors: persist a redacted trace in the save dir and surface a hint.
 do
@@ -197,14 +198,19 @@ end
 local touchEditorHost
 local closeTouchControlsEditor  -- forward declaration
 
-local function openTouchControlsEditor()
+-- `version` is the launcher tab the gear was opened on, and it decides which
+-- option block the layout lands in (src/ui/TouchControlsEditor.lua persist).
+local function openTouchControlsEditor(version)
   touchEditorHost = Importer
   if Importer and Importer.prepareOverlayHandoff then
     Importer:prepareOverlayHandoff()
   end
   Importer = nil
   TouchEditor = require("src.ui.TouchControlsEditor")
-  TouchEditor.load({ onClose = function() closeTouchControlsEditor() end })
+  TouchEditor.load({
+    version = version,
+    onClose = function() closeTouchControlsEditor() end,
+  })
 end
 
 function closeTouchControlsEditor()
@@ -425,6 +431,7 @@ function love.load(args)
 end
 
 function love.update(dt)
+  HostDisplay.update(dt)
   SwitchDiagnostics.maybeFlush(false)
   -- NX only (no-op elsewhere): follow dock/undock without waiting for SDL.
   NxDisplay.sync()
@@ -472,11 +479,27 @@ function love.update(dt)
 end
 
 function love.draw()
-  if editorMode then return EditorApp.draw() end
-  if TouchEditor then return TouchEditor.draw() end
-  if Importer then return Importer:draw() end
+  if editorMode then
+    HostDisplay.beginFrame("editor", EditorApp)
+    local result = EditorApp.draw()
+    HostDisplay.endFrame("editor", EditorApp)
+    return result
+  end
+  if TouchEditor then
+    HostDisplay.beginFrame("touch_editor", TouchEditor)
+    local result = TouchEditor.draw()
+    HostDisplay.endFrame("touch_editor", TouchEditor)
+    return result
+  end
+  if Importer then
+    HostDisplay.beginFrame("launcher", Importer)
+    local result = Importer:draw()
+    HostDisplay.endFrame("launcher", Importer)
+    return result
+  end
   if not Game then return end
 
+  HostDisplay.beginFrame("game", Game)
   Game:draw()
   -- frame capture requested by a driver
   if Game.capturePath then
@@ -491,6 +514,7 @@ function love.draw()
       end
     end)
   end
+  HostDisplay.endFrame("game", Game)
 end
 
 function love.keypressed(key, scancode, isrepeat)

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

@@ -143,16 +143,36 @@ public class GameActivity extends SDLActivity {
 
     private static native void nativeSetDefaultStreamValues(int sampleRate, int framesPerBurst);
 
+    /**
+     * Native libraries required by an optional Android host extension.
+     *
+     * Subclasses supplied by another product flavor may override this method.
+     * The libraries are loaded after LÖVE's dependencies and before liblove;
+     * liblove must remain last because SDL treats the final entry as the main
+     * shared object.
+     */
+    protected String[] getHostLibraries() {
+        return new String[0];
+    }
+
     @Override
     protected String[] getLibraries() {
-        return new String[] {
-            "c++_shared",
-            "mpg123",
-            "openal",
-            "love",
-        };
+        String[] hostLibraries = getHostLibraries();
+        String[] libraries = new String[hostLibraries.length + 4];
+        libraries[0] = "c++_shared";
+        libraries[1] = "mpg123";
+        libraries[2] = "openal";
+        System.arraycopy(hostLibraries, 0, libraries, 3, hostLibraries.length);
+        libraries[libraries.length - 1] = "love";
+        return libraries;
     }
 
+    protected void onHostCreateBeforeSDL(Bundle savedInstanceState) {}
+    protected void onHostCreateAfterSDL(Bundle savedInstanceState) {}
+    protected void onHostResume() {}
+    protected void onHostPause() {}
+    protected void onHostDestroy() {}
+
     @Override
     protected String getMainSharedObject() {
         String[] libs = getLibraries();
@@ -192,7 +212,9 @@ public class GameActivity extends SDLActivity {
             intent.setData(null);
         }
 
+        onHostCreateBeforeSDL(savedInstanceState);
         super.onCreate(savedInstanceState);
+        onHostCreateAfterSDL(savedInstanceState);
         if (savedInstanceState != null) {
             // Restore the in-flight SAF destinations, so a pick that returns to
             // a recreated activity still lands under the basename it asked for.
@@ -341,6 +363,7 @@ public class GameActivity extends SDLActivity {
             Log.d("GameActivity", "Cancelling vibration");
             vibrator.cancel();
         }
+        onHostDestroy();
         super.onDestroy();
     }
 
@@ -351,12 +374,14 @@ public class GameActivity extends SDLActivity {
             vibrator.cancel();
         }
         teardownSecondaryDisplay();
+        onHostPause();
         super.onPause();
     }
 
     @Override
     public void onResume() {
         super.onResume();
+        onHostResume();
         setupSecondaryDisplay();
     }
 

mobile/ios/README.md

@@ -7,7 +7,7 @@ an iOS app with LÖVE 12.0.
 
 The app uses the public iOS Documents directory as its LÖVE save directory.
 There is no `pokemon-love2d` subdirectory and the app does not create a
-README file there. When browsing `On My iPhone > gen1recomp` in Files, the
+README file there. When browsing `On My iPhone > gen1recomp++` in Files, the
 directory contains the app's runtime data directly, including:
 
 - installed mods and downloaded ROMs
@@ -46,7 +46,7 @@ scripts/build_ios.sh --device --release --install
 Device builds require a paired, unlocked device and a valid Apple signing
 identity. Set `DEVELOPMENT_TEAM` or `CODE_SIGN_IDENTITY` when automatic
 signing cannot select the intended account. Add `--ipa` to create
-`dist/ios/gen1recomp.ipa`.
+`dist/ios/gen1recomp++.ipa`.
 
 The script verifies the final app before packaging it:
 
@@ -76,10 +76,10 @@ option.
 Simulator and device app bundles are copied to:
 
 ```text
-dist/ios/Debug-iphonesimulator/gen1recomp.app
-dist/ios/Release-iphonesimulator/gen1recomp.app
-dist/ios/Debug-iphoneos/gen1recomp.app
-dist/ios/Release-iphoneos/gen1recomp.app
+dist/ios/Debug-iphonesimulator/gen1recomp++.app
+dist/ios/Release-iphonesimulator/gen1recomp++.app
+dist/ios/Debug-iphoneos/gen1recomp++.app
+dist/ios/Release-iphoneos/gen1recomp++.app
 ```
 
 The intermediate Xcode products are under `mobile/ios/build/`. Both locations
@@ -94,9 +94,9 @@ saves; those are created at runtime in Documents.
 
 | Field | Default |
 | --- | --- |
-| Display name | `gen1recomp` |
-| Product name | `gen1recomp` |
-| Bundle identifier | `com.theboisclub.gen1recomp` |
+| Display name | `gen1recomp++` |
+| Product name | `gen1recomp++` |
+| Bundle identifier | `com.theboisclub.gen1recompplusplus` |
 | Save directory | Public `Documents` root |
 | Orientation | Portrait |
 

mobile/ios/app-repo.json

@@ -1,17 +1,66 @@
 {
-  "name": "gen1recomp App Repo",
-  "identifier": "com.theboisclub.gen1recomp.repo",
+  "name": "gen1recomp++ App Repo",
+  "identifier": "com.theboisclub.gen1recompplusplus.repo",
   "iconURL": "https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/assets/logo/gen1recomp_cover.png",
   "apps": [
     {
-      "name": "gen1recomp",
-      "bundleIdentifier": "com.theboisclub.gen1recomp",
+      "name": "gen1recomp++",
+      "bundleIdentifier": "com.theboisclub.gen1recompplusplus",
       "developerName": "bryanthaboi",
       "iconURL": "https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/assets/logo/gen1recomp_cover.png",
       "localizedDescription": "Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke",
       "tintColor": "3b5ca8",
       "category": "games",
       "versions": [
+        {
+          "version": "0.1.85",
+          "date": "2026-08-14",
+          "size": 11306462,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.85/gen1recomp++-0.1.85-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.84",
+          "date": "2026-08-14",
+          "size": 11306462,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.84/gen1recomp++-0.1.84-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #919 Bills House game save moves strangely after reload\n- #982 Trading QOL aspect missing from OG.\n- #1003 Land Pokemon Encounters while Surfing in Cerulean Cave\n- #1012 Multiple issues with text speed, animations, and audio\n- #1022 Cannot interact with small trees\n- #1028 Trainers not resetting on route change.\n- #1033 Some issues with Link battles.\n- #1243 Can't sell TMs at Poké Marts\n\n## Contributors\n\n- @1Jamie\n- @AverageConsumer\n- @bryanthaboi\n- @TheRealSolidusSnake\n- Myles Resnick\n- ShaneMcGovernIE"
+        },
+        {
+          "version": "0.1.83",
+          "date": "2026-08-13",
+          "size": 11282300,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.83/gen1recomp++-0.1.83-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.82",
+          "date": "2026-08-13",
+          "size": 11281277,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.82/gen1recomp++-0.1.82-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #914 Immunity steps and no encounter tiles\n- #936 Fly and teleporting allow should block interactions\n- #944 When starting a new game, the character sprite is facing down instead of up\n- #949 Save game import, save game export, \"normal\" save game\n- #964 Menu closing when trying to view Pokemon before picking starter\n- #978 Following up of #847\n- #983 Pikachu incorrectly able to be released\n- #984 EXP calculation after trading a PKMN back isnt right.\n- #987 Celadon Game Corner Display Error (L22680)\n- #988 (Yellow) Missing Pikachu Interaction - Pewter City Pokemon Centre\n- #989 (Yellow) Missing Pikachu Interaction - Vermilion City Pokemon Fan Club\n- #990 (Yellow) Pikachu Missing Hat\n- #999 Pallet Town music while player follows Prof. Oak\n- #1007 Transition into battle state for the 'Catching Pikachu' scene missing\n- #1010 Rival's position resets\n- #1011 Rival dialogue issue\n- #1029 1px black line sits under the title logo at the SGB zone boundary\n- #1035 Alt Music not playing\n- #1041 Mimic text not swoing up\n- #1047 Using a TM or HM closes the menu afterwards.\n- #1048 Cannot select items from the sell menu.\n- #1056 Cursor not jumping when switching moves\n- #1065 Player walks through statue after final battle while walking into Hall Of Fame\n- #1066 Anomalies when opponent switches out Pokemon\n- #1069 missing {RAM:wNameBuffer}\n- #1073 _GotMonText not used\n- #1089 Scripted movement missing for player and rival\n- #1101 Recoil damage calculation bug\n- #1115 Hitting attack does no damage\n- #1119 Wrongs textlines and events\n- #1120 Health is black when viewing stats\n- #1129 Errors in bowing animations of the nurse\n- #1146 [Recomp] Map music glitch\n- #1149 issue that affects tranlations\n- #1175 Pikachu visible too late\n- #1189 Town Map Item\n- #1193 Status moves have (wrong) sound effects when battle animations are turned off\n- #1206 Gen1: Cinnebar island has unfishable tiles north and east\n- #1207 Poison Flicker Visual issue\n- #1214 Title Screen with OG Red is the wrong color\n- #1219 [GOLD] UNABLE TO USE SUN STONE\n- #1220 No screen shaking for hitting moves when battle animations are off\n- #1221 [Gold] Flaafy evolution to at Lvl 30 Ampharos skipped learn thunder punch\n- #1225 Jingles for learning moves missing\n\n## Contributors\n\n- @1Jamie\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.81",
+          "date": "2026-08-13",
+          "size": 9886854,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.81/gen1recomp++-0.1.81-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1091 Encounter Rate is tied to Game Speed\n- #1097 Phase through walls exiting a cave\n- #1100 Allow for control edit and vibration toggle on gold\n- #1104 wrong warp\n- #1135 update for iphone - haptic vibrations\n- #1155 Magnitude always rolls a 4\n- #1157 Sonic Boom doesn't deal set damage\n- #1158 Unable to view opponent's next Pokemon\n- #1159 Dig animation is bugged\n- #1160 64x64 battle sprite followup for mods\n- #1167 [Gold] items in ilex forest missing\n- #1208 Gold Save game not showing properly in LAUNCHER after having multiple saves\n\n## Contributors\n\n- @bryanthaboi\n- @castdrian\n- @MaxTomahawk\n- @Yukitty\n- Codex Agent"
+        },
+        {
+          "version": "0.1.80",
+          "date": "2026-08-12",
+          "size": 10964568,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.80/gen1recomp-0.1.80-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1100 Allow for control edit and vibration toggle on gold\n- #1107 [Gold] When playing without a save slot in the launcher, no save will be created at all when saving ingame\n- #1112 [Gold] In the shop when buying items and pressing \"down\", it should not default to x99\n- #1121 [Gold] NPC trading (probably player too?) animation broken / missing things\n- #1126 [Gold] Jumping off ledge animation missing\n- #1130 A separate program for Gen2 (Gen2 Recomp)\n- #1145 Gen1recomp internal update - Mod didn't filter for Gen1 and Gen2 when click on individual tab\n- #1150 Control in Gold freeze when change\n- #1151 [Gold] Following up of #1127\n- #1152 [Gold] You cannot try to run away from wild battle after one of your Pokemon gets fainted.\n- #1161 window/borderless & resolution selection for gen2\n- #1162 [gold] learning TM/HM doesn't show if possible or not\n- #1164 Goldenrod Tower Softlock\n- #1165 [Gold] NPC trading behavior and ledge jumping missing still there despite fix\n- #1166 [Gold] nickname screen grey\n- #1167 [Gold] items in ilex forest missing\n- #1168 [Gold] multi-hit attacks only hits twice\n- #1169 [Gold] the sales lady in goldenrod underground\n- #1172 [Gold] {last item u found/got} used ROCK SMASH\n- #1173 [Gold] ROCK SMASH rocks keep slide left\n- #1177 [Gold] Touch controls position\n- #1178 No Vibration Setting for Gold\n- #1180 [Gold] something feels off with the DV calculation\n- #1184 [Gold] Kurt is in the wrong spot, blocking you from progressing\n- #1185 [Gold] Text messages is in the wrong order when a Pokemon learns a new skill after a trainer fight\n- #1188 GoldenRod tower softlock\n- #1190 POKEMON GOLD GEN1RECOMP++\n- #1192 cant import gold on RGXX build\n\n## Contributors\n\n- @anxiousintrovert\n- @AverageConsumer\n- @bryanthaboi\n- @MaxTomahawk\n- @ShaneMcGovernIE\n- @thibautbus"
+        },
+        {
+          "version": "0.1.79",
+          "date": "2026-08-12",
+          "size": 10956333,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.79/gen1recomp-0.1.79-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1090 With TILT Option enabled, screen does not correctly render beyond what would be visible with TILT Disabled.\n- #1093 Gen 2 Gold Beta: jingle doesn't play when receiving Elm's phone number\n- #1094 Gen 2 Gold Beta: no battle SFX when animations are Off\n- #1095 Gen 2 Gold Beta: player sprite has white box outline that cuts off Pokémon sprites\n- #1098 [Gold] Can't change controls (no menu for it and it doesn't use the one set in RBY)\n- #1102 [Gold] Shop ui off because of a border\n- #1105 [Gold] Game speed doesn't apply to the intro\n- #1106 [Gold] Games slots don't respect portable.txt\n- #1108 [Gold] Launcher doesn't show any information about the save slot(s)\n- #1109 [Options] text speed doesn't work at all.\n- #1110 [Gold] When catching a Pokemon, the ball disappears  and the text doesn't wait for you to progress\n- #1111 [Gold] nurse joy doesn't look left for healing\n- #1113 [Gold] Poke center -> Bills PC -> Deposit Pokemon, screen off\n- #1114 [Gold] Can't release Pokemon, menu doesn't appear\n- #1117 [Gold/Options] sound doesn't change\n- #1118 [Gold] Berrys animation missing and speedup.\n- #1121 [Gold] NPC trading (probably player too?) animation broken / missing things\n- #1122 [Gold] Level up UI.\n- #1123 [Gold] Character stops \"inside door\" when leaving buildings instead of moving one tile down\n- #1124 [Gold] When \"turning\", no animation is played\n- #1126 [Gold] Jumping off ledge animation missing\n- #1127 [Gold] Very minor Pokegear issues.\n- #1128 [Gold] When calling mom, the yes/no dialogue background color doesn't fit\n- #1131 [Gold] Pokegear map bug(s)\n- #1132 [gold] pokedex bugs\n- #1134 Unable to Validate/Pack mod calling Gold's overworld sprite\n- #1137 64x64 sprite support broken for mods on Gen 2\n- #1141 Teleport doesn't end wild battle\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi\n- @dburton95\n- @dlloa\n- @MaxTomahawk\n- @swuff-star\n- @TheRealSolidusSnake\n- @thibautbus"
+        },
         {
           "version": "0.1.78",
           "date": "2026-08-11",

mobile/ios/overlays/love-ios.plist

@@ -5,7 +5,7 @@
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleDisplayName</key>
-	<string>gen1recomp</string>
+	<string>gen1recomp++</string>
 	<key>CFBundleDocumentTypes</key>
 	<array>
 		<dict>
@@ -32,7 +32,7 @@
 	<key>CFBundleInfoDictionaryVersion</key>
 	<string>6.0</string>
 	<key>CFBundleName</key>
-	<string>gen1recomp</string>
+	<string>gen1recomp++</string>
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>

mobile/ios/patch_love_src.py

@@ -29,6 +29,9 @@ WRAP_SYSTEM = LOVE_SRC / "src" / "modules" / "system" / "wrap_System.cpp"
 PBXPROJ = LOVE_SRC / "platform" / "xcode" / "love.xcodeproj" / "project.pbxproj"
 APPLE_MM = LOVE_SRC / "src" / "common" / "apple.mm"
 FILESYSTEM_CPP = LOVE_SRC / "src" / "modules" / "filesystem" / "physfs" / "Filesystem.cpp"
+IOS_MM = LOVE_SRC / "src" / "common" / "ios.mm"
+IOS_H = LOVE_SRC / "src" / "common" / "ios.h"
+SYSTEM_CPP = LOVE_SRC / "src" / "modules" / "system" / "System.cpp"
 ENTITLEMENTS_SRC = IOS_DIR / "overlays" / "love-ios.entitlements"
 
 NATIVE_FILES = ("GRPickerBridge.swift", "GRHealthBridge.swift", "GRBootstrap.m")
@@ -120,7 +123,7 @@ int w_pickFileKinds(lua_State *L)
 	typedef const char *(*GRUTF8)(id, SEL);
 	const char *bytes = ((GRUTF8)objc_msgSend)(kinds,
 	                                           sel_registerName("UTF8String"));
-	if (bytes == nullptr || bytes[0] == '\0')
+	if (bytes == nullptr || bytes[0] == '\\0')
 	{
 		lua_pushnil(L);
 		return 1;
@@ -358,6 +361,50 @@ def patch_public_documents():
     print("patch_love_src: iOS save directory routed to Documents root")
 
 
+def patch_ios_haptics():
+    text = pristine(IOS_MM, ("UIImpactFeedbackGenerator",))
+    original = """void vibrate()
+{
+	@autoreleasepool
+	{
+		AudioServicesPlaySystemSound(kSystemSoundID_Vibrate);
+	}
+}
+"""
+    replacement = """void vibrate(double seconds)
+{
+	@autoreleasepool
+	{
+		UIImpactFeedbackStyle style = UIImpactFeedbackStyleLight;
+		if (seconds >= 0.035)
+			style = UIImpactFeedbackStyleHeavy;
+		else if (seconds >= 0.02)
+			style = UIImpactFeedbackStyleMedium;
+		UIImpactFeedbackGenerator *generator = [[UIImpactFeedbackGenerator alloc]
+			initWithStyle:style];
+		[generator prepare];
+		[generator impactOccurred];
+	}
+}
+"""
+    if original not in text:
+        fail(f"iOS haptic anchor not found in {IOS_MM}")
+    IOS_MM.write_text(text.replace(original, replacement, 1))
+
+    header = pristine(IOS_H, ("void vibrate(double seconds);",))
+    header_original = "void vibrate();"
+    if header_original not in header:
+        fail(f"iOS haptic declaration not found in {IOS_H}")
+    IOS_H.write_text(header.replace(header_original, "void vibrate(double seconds);", 1))
+
+    system = pristine(SYSTEM_CPP, ("love::ios::vibrate(seconds)",))
+    system_original = "love::ios::vibrate();"
+    if system_original not in system:
+        fail(f"iOS haptic call site not found in {SYSTEM_CPP}")
+    SYSTEM_CPP.write_text(system.replace(system_original, "love::ios::vibrate(seconds);", 1))
+    print("patch_love_src: iOS haptics use Taptic Engine impact presets")
+
+
 def patch_pbxproj():
     text = pristine(PBXPROJ)
 
@@ -408,7 +455,9 @@ def patch_pbxproj():
             fail(f"build configuration {config_id} not found")
         settings = (
             "\t\t\t\tSWIFT_VERSION = 5.0;\n"
-            "\t\t\t\tIPHONEOS_DEPLOYMENT_TARGET = 14.0;\n"
+            "\t\t\t\tIPHONEOS_DEPLOYMENT_TARGET = 15.0;\n"
+            "\t\t\t\tPRODUCT_NAME = \"gen1recomp++\";\n"
+            "\t\t\t\tEXECUTABLE_NAME = \"gen1recomp++\";\n"
             '\t\t\t\tCODE_SIGN_ENTITLEMENTS = "ios/native/love-ios.entitlements";\n'
         )
         text = text[: m.end()] + settings + text[m.end():]
@@ -422,6 +471,7 @@ def main():
         fail("love-src/ missing; run scripts/build_ios.sh --fetch first")
     copy_native_files()
     patch_public_documents()
+    patch_ios_haptics()
     patch_wrap_system()
     patch_pbxproj()
 

mods/timekeepers_hut

@@ -0,0 +1 @@
+/Users/bryanbassett/Documents/development/pokemon-gen1-recomp-project/.bazinga/mods/timekeepers_hut

native/tls_dial/README.md

@@ -23,6 +23,10 @@ Ship `gen1tls.dll` (or `libgen1tls.so` / `libgen1tls.dylib`) **next to** the
 fused executable. Mods load it through LuaJIT FFI; no .NET runtime is
 required on the player's machine.
 
+Official Windows release zips get `gen1tls.dll` from CI: a `windows-2022`
+job publishes this project and `scripts/build.sh`'s Windows packaging copies
+it beside `gen1recomp.exe` (see `GEN1TLS_DLL` / `dist/native/win-x64`).
+
 ## Android
 
 On Android, the matching API is exposed as `love.system.tlsOpen` /

scripts/build.sh

@@ -13,7 +13,7 @@
 #         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>/gen1recomp.app (full xcodebuild output stays
+#         dist/ios/<Config>-<sdk>/gen1recomp++.app (full xcodebuild output stays
 #           under mobile/ios/build/Build/Products/)
 
 set -euo pipefail
@@ -261,6 +261,21 @@ build_win() {
   cp "$love_dir"/*.dll "$out_dir"/
   cp "$love_dir"/license.txt "$out_dir"/ 2>/dev/null || true
 
+  # Native AOT TLS dialer for outbound wss:// (e.g. Archipelago hosted rooms).
+  # Release CI builds this on windows-2022 (Native AOT can't cross-compile
+  # win-x64 from the Mac runner) and either exports GEN1TLS_DLL or drops the
+  # file at dist/native/win-x64/gen1tls.dll before calling build.sh.
+  local tls_dll="${GEN1TLS_DLL:-}"
+  if [ -z "$tls_dll" ] && [ -f "$DIST/native/win-x64/gen1tls.dll" ]; then
+    tls_dll="$DIST/native/win-x64/gen1tls.dll"
+  fi
+  if [ -n "$tls_dll" ] && [ -f "$tls_dll" ]; then
+    cp "$tls_dll" "$out_dir/gen1tls.dll"
+    say "bundled gen1tls.dll for Windows TLS (wss://)"
+  else
+    warn "gen1tls.dll not found — Windows zip will not support wss:// (set GEN1TLS_DLL or build native/tls_dial)"
+  fi
+
   # The exe's icon lives in love.exe's PE resources, so it must be patched
   # BEFORE the .love is appended: peresed rewrites the whole file and would
   # drop the fused bytes. peresed (pipx install pe_tools) has no .ico input,
@@ -400,6 +415,9 @@ EOF
   grep -q '^FUSE_PATH="\$APPDIR/game.love"$' "$appdir/AppRun" \
     || fail "failed to enable FUSE_PATH in AppRun (upstream AppRun changed?)"
 
+  sed -i '' 's|^exec "\$APPDIR/bin/love"|if [ -n "$WAYLAND_DISPLAY" ] \&\& [ -z "$SDL_VIDEODRIVER" ]; then export SDL_VIDEODRIVER=x11; fi\
+exec "$APPDIR/bin/love"|' "$appdir/AppRun"
+
   # Match the upstream image's compression (gzip, 128K blocks) so the
   # bundled runtime can read it.
   local sfs_out="$WORK/game.squashfs"

scripts/build_android.sh

@@ -27,10 +27,9 @@ APPLICATION_ID="com.theboisclub.pokemonred"
 LOVE_ANDROID_VERSION="11.5a"
 NDK_VERSION="25.2.9519653"
 YELLOW_MANIFEST_RELATIVE="tools/rom_manifest_yellow.json"
-# A fresh source checkout normally supplies this through Git.  This URL is
-# deliberately only a last resort for incomplete source exports: the manifest
-# contains extraction metadata, never a ROM or extracted game data.
 YELLOW_MANIFEST_URL="${YELLOW_MANIFEST_URL:-https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/tools/rom_manifest_yellow.json}"
+GOLD_MANIFEST_RELATIVE="tools/rom_manifest_gold.json"
+GOLD_MANIFEST_URL="${GOLD_MANIFEST_URL:-https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/tools/rom_manifest_gold.json}"
 
 VERSION=""
 PACKAGE_ONLY=false
@@ -130,6 +129,54 @@ ensure_yellow_manifest() {
   fail "Yellow import manifest is unavailable. Git recovery failed and could not download $YELLOW_MANIFEST_URL"
 }
 
+gold_manifest_is_valid() {
+  local path="$1"
+  python3 - "$path" <<'PY'
+import json, pathlib, sys
+
+try:
+    manifest = json.loads(pathlib.Path(sys.argv[1]).read_text())
+except (OSError, ValueError):
+    raise SystemExit(1)
+
+raise SystemExit(0 if manifest.get("romSha1") ==
+                 "d8b8a3600a465308c9953dfa04f0081c05bdcb94" else 1)
+PY
+}
+
+ensure_gold_manifest() {
+  local manifest="$ROOT/$GOLD_MANIFEST_RELATIVE"
+  local staged
+  staged="$(mktemp)"
+
+  if gold_manifest_is_valid "$manifest"; then
+    rm -f "$staged"
+    return
+  fi
+
+  warn "Gold import manifest is missing or invalid; recovering it before packaging"
+  if git -C "$ROOT" show "HEAD:$GOLD_MANIFEST_RELATIVE" > "$staged" 2>/dev/null \
+      && gold_manifest_is_valid "$staged"; then
+    mkdir -p "$(dirname "$manifest")"
+    mv "$staged" "$manifest"
+    say "restored Gold import manifest from this checkout's Git data"
+    return
+  fi
+
+  if command -v curl >/dev/null 2>&1 \
+      && curl --fail --location --retry 2 --connect-timeout 15 \
+          --output "$staged" "$GOLD_MANIFEST_URL" \
+      && gold_manifest_is_valid "$staged"; then
+    mkdir -p "$(dirname "$manifest")"
+    mv "$staged" "$manifest"
+    say "downloaded Gold import manifest from the project repository"
+    return
+  fi
+
+  rm -f "$staged"
+  fail "Gold import manifest is unavailable. Git recovery failed and could not download $GOLD_MANIFEST_URL"
+}
+
 # --------------------------------------------------------------- branding
 # love-android 11.5+ reads app id / name / orientation from gradle.properties.
 # Manifest still gets permission trims. Re-applied every build so refreshing
@@ -194,6 +241,7 @@ PY
 pack_game_love() {
   say "packing game.love for love-android embed flavor"
   ensure_yellow_manifest
+  ensure_gold_manifest
   mkdir -p "$EMBED_ASSETS"
   rm -f "$LOVE_FILE"
   # tools/save-editor ships with the app: the launcher's Edit button on a save

scripts/build_ios.sh

@@ -20,9 +20,9 @@
 #   - macOS + Xcode (xcodebuild)
 #   - mobile/ios/love-src/ (see --fetch / mobile/ios/README.md)
 #
-# Output: dist/ios/<Config>-<sdk>/gen1recomp.app (convenience copy)
-#         dist/ios/gen1recomp.ipa                 (device builds only)
-#         mobile/ios/build/Build/Products/<Config>-<sdk>/gen1recomp.app
+# Output: dist/ios/<Config>-<sdk>/gen1recomp++.app (convenience copy)
+#         dist/ios/gen1recomp++.ipa                 (device builds only)
+#         mobile/ios/build/Build/Products/<Config>-<sdk>/gen1recomp++.app
 
 set -euo pipefail
 
@@ -39,8 +39,9 @@ RESOURCES_DIR="$XCODE_DIR/ios/resources"
 LOVE_FILE="$RESOURCES_DIR/game.love"
 LIBS_DIR="$XCODE_DIR/ios/libraries"
 
-APP_NAME="gen1recomp"
-DISPLAY_NAME="gen1recomp"
+APP_NAME="gen1recomp++"
+DISPLAY_NAME="gen1recomp++"
+PRODUCT_NAME="gen1recomp++"
 # Bundle ID resolution, most specific wins:
 #   1. GEN1_BUNDLE_ID env var
 #   2. mobile/ios/bundle_id.local (one line, gitignored — pins YOUR install
@@ -50,7 +51,7 @@ DISPLAY_NAME="gen1recomp"
 #      capabilities like HealthKit are involved), so a per-team default
 #      lets anyone build without colliding with someone else's app
 #   4. simulator: the project default (no App ID registration involved)
-BUNDLE_ID="${GEN1_BUNDLE_ID:-com.theboisclub.gen1recomp}"
+BUNDLE_ID="${GEN1_BUNDLE_ID:-}"
 if [ -z "$BUNDLE_ID" ] && [ -f "$IOS_DIR/bundle_id.local" ]; then
   BUNDLE_ID="$(tr -d '[:space:]' < "$IOS_DIR/bundle_id.local")"
 fi
@@ -138,11 +139,7 @@ if $DEVICE && [ -z "${DEVELOPMENT_TEAM:-}" ]; then
   fi
 fi
 if [ -z "$BUNDLE_ID" ]; then
-  if $DEVICE; then
-    BUNDLE_ID="com.gen1recomp.t$(printf '%s' "$DEVELOPMENT_TEAM" | tr '[:upper:]' '[:lower:]')"
-  else
-    BUNDLE_ID="com.theboisclub.pokemonred"
-  fi
+  BUNDLE_ID="com.theboisclub.gen1recompplusplus"
 fi
 
 # --------------------------------------------------------------- host checks
@@ -226,13 +223,26 @@ verify_documents_overlay() {
 }
 
 apply_ios_icon() {
-  local source="$ROOT/assets/logo/gen1recomp_cover.png"
+  local source="$ROOT/assets/logo/logo.png"
   local target="$XCODE_DIR/Images.xcassets/iOS AppIcon.appiconset"
   [ -f "$source" ] || fail "missing iOS icon source: $source"
   [ -d "$target" ] || fail "missing iOS app icon set: $target"
+  local icon="$BUILD_DIR/gen1recomp-ios-icon.png"
+  mkdir -p "$BUILD_DIR"
+  if command -v magick >/dev/null 2>&1; then
+    magick -size 1024x1024 xc:black \
+      \( "$source" -resize 900x900 \) -gravity center -composite \
+      -alpha off "$icon" || fail "could not create iOS app icon: $source"
+  else
+    local scaled="$BUILD_DIR/gen1recomp-logo.png"
+    sips -Z 900 "$source" --out "$scaled" >/dev/null \
+      || fail "could not resize iOS app icon source: $source"
+    sips -p 1024 1024 --padColor 000000 "$scaled" --out "$icon" >/dev/null \
+      || fail "could not center iOS app icon source: $source"
+  fi
   local entry name size
   while IFS=: read -r name size; do
-    sips -z "$size" "$size" "$source" --out "$target/$name" >/dev/null
+    sips -z "$size" "$size" "$icon" --out "$target/$name" >/dev/null
   done <<'EOF'
 icon-1024pt@1x.png:1024
 icon-29pt@1x.png:29
@@ -647,6 +657,7 @@ run_xcodebuild() {
     CURRENT_PROJECT_VERSION="$project_version"
     INFOPLIST_KEY_UIFileSharingEnabled=YES
     INFOPLIST_KEY_LSSupportsOpeningDocumentsInPlace=YES
+    IPHONEOS_DEPLOYMENT_TARGET=15.0
     ONLY_ACTIVE_ARCH=NO
     DISABLE_MANUAL_TARGET_ORDER_BUILD_WARNING=YES
   )
@@ -666,6 +677,9 @@ run_xcodebuild() {
     if [ -n "${CODE_SIGN_IDENTITY:-}" ]; then
       args+=(CODE_SIGN_IDENTITY="$CODE_SIGN_IDENTITY")
     fi
+    if [ "${GEN1_DISABLE_HEALTHKIT:-0}" = "1" ]; then
+      args+=(CODE_SIGN_ENTITLEMENTS=)
+    fi
   fi
 
   if ! xcodebuild -showsdks 2>/dev/null | grep -q "$sdk"; then
@@ -708,18 +722,22 @@ run_xcodebuild() {
   fi
 
   local products="$BUILD_DIR/Build/Products/${config}-${sdk}"
-  local app="$products/$APP_NAME.app"
-  if [ ! -d "$app" ]; then
-    # PRODUCT_NAME override can still leave love.app on older projects
-    if [ -d "$products/love.app" ]; then
-      app="$products/$APP_NAME.app"
-      mv "$products/love.app" "$app"
-      warn "renamed love.app to $APP_NAME.app"
-    else
-      warn "xcodebuild finished but no .app under $products"
-      find "$BUILD_DIR/Build/Products" -name '*.app' 2>/dev/null | head -20 || true
-      return 0
+  local app=""
+  local candidate
+  for candidate in "$products/$PRODUCT_NAME.app" "$products/$APP_NAME.app" "$products/love.app"; do
+    if [ -d "$candidate" ]; then
+      app="$candidate"
+      break
     fi
+  done
+  if [ -z "$app" ]; then
+    warn "xcodebuild finished but no .app under $products"
+    find "$BUILD_DIR/Build/Products" -name '*.app' 2>/dev/null | head -20 || true
+    return 0
+  fi
+  if [ "$app" != "$products/$APP_NAME.app" ]; then
+    mv "$app" "$products/$APP_NAME.app"
+    app="$products/$APP_NAME.app"
   fi
 
   verify_documents_configuration "$app"
@@ -760,7 +778,7 @@ run_xcodebuild() {
   fi
 }
 
-# Pack Payload/<app>.app into dist/ios/gen1recomp.ipa for release / sideload tools.
+# Pack Payload/<app>.app into dist/ios/gen1recomp++.ipa for release / sideload tools.
 package_ipa() {
   local app="$1"
   local ipa="$DIST/$APP_NAME.ipa"

scripts/linux-arm64/build_appimage.sh

@@ -93,7 +93,8 @@ build_autotools mpg123 "$MPG123_VERSION" "$MPG123_TARBALL" libmpg123.so.0 \
 # The symbol that was missing when this was bullseye's copy. Assert it, so a
 # version bump that quietly regresses below the host's expectations fails the
 # build instead of silently killing audio again.
-objdump -T "$PREFIX/lib/libmpg123.so.0" | grep -q 'mpg123_info2' \
+mpg123_syms="$(objdump -T "$PREFIX/lib/libmpg123.so.0")"
+grep -q 'mpg123_info2' <<<"$mpg123_syms" \
   || fail "bundled libmpg123 lacks mpg123_info2; the host's libsndfile will fail to relocate"
 
 # ------------------------------------------------------------ compile SDL2
@@ -128,8 +129,9 @@ fi
 # the host having that exact stack -- which is the bug this replaced.
 sdl_lib="$PREFIX/lib/libSDL2-2.0.so.0"
 [ -f "$sdl_lib" ] || fail "SDL2 build produced no libSDL2-2.0.so.0"
+sdl_needed="$(objdump -p "$sdl_lib")"
 for forbidden in libpulse libasound libX11 libwayland libdrm libgbm libsndio; do
-  if objdump -p "$sdl_lib" | grep -q "NEEDED.*$forbidden"; then
+  if grep -q "NEEDED.*$forbidden" <<<"$sdl_needed"; then
     fail "SDL2 hard-links $forbidden; it must dlopen its backends (--enable-*-shared)"
   fi
 done
@@ -164,8 +166,9 @@ fi
 
 openal_lib="$PREFIX/lib/libopenal.so.1"
 [ -f "$openal_lib" ] || fail "openal-soft build produced no libopenal.so.1"
+openal_needed="$(objdump -p "$openal_lib")"
 for forbidden in libsndio libasound libpulse libjack; do
-  if objdump -p "$openal_lib" | grep -q "NEEDED.*$forbidden"; then
+  if grep -q "NEEDED.*$forbidden" <<<"$openal_needed"; then
     fail "openal hard-links $forbidden; backends must stay behind dlopen"
   fi
 done
@@ -196,7 +199,8 @@ fi
 
 theora_lib="$PREFIX/lib/libtheoradec.so.1"
 [ -f "$theora_lib" ] || fail "libtheora build produced no libtheoradec.so.1"
-if objdump -p "$theora_lib" | grep -q "NEEDED.*libcairo"; then
+theora_needed="$(objdump -p "$theora_lib")"
+if grep -q "NEEDED.*libcairo" <<<"$theora_needed"; then
   fail "libtheoradec still links libcairo (--disable-examples stopped working)"
 fi
 
@@ -231,16 +235,18 @@ love_bin="$PREFIX/bin/love"
 love_lib="$PREFIX/lib/liblove-$LOVE_VERSION.so"
 [ -x "$love_bin" ] || fail "LÖVE build produced no bin/love"
 [ -f "$love_lib" ] || fail "LÖVE build produced no lib/liblove-$LOVE_VERSION.so"
-file "$love_bin" | grep -q 'ARM aarch64' \
+love_file="$(file "$love_bin")"
+grep -q 'ARM aarch64' <<<"$love_file" \
   || fail "built love is not an aarch64 ELF (got: $(file -b "$love_bin"))"
 
 # A configure run that lost an optional dependency still exits 0 and still
 # builds -- the loss only shows up as a missing love module at runtime, i.e.
 # in a shipped artifact. Assert the decoder/font/video libs really linked.
+love_needed="$(objdump -p "$love_lib")"
 for soname in libSDL2-2.0.so.0 libopenal.so.1 libfreetype.so.6 \
               libmodplug.so.1 libmpg123.so.0 libvorbisfile.so.3 \
               libtheoradec.so.1 libluajit-5.1.so.2; do
-  objdump -p "$love_lib" | grep -q "NEEDED.*$soname" \
+  grep -q "NEEDED.*$soname" <<<"$love_needed" \
     || fail "liblove is not linked against $soname (a -dev package went missing)"
 done
 
@@ -357,6 +363,9 @@ cp -R "$jit_share/jit" "$APPDIR/share/$LUAJIT_SHARE_DIR/"
 
 # --------------------------------------------------------------- branding
 cp "$IN/game.love" "$APPDIR/game.love"
+unzip -Z1 "$APPDIR/game.love" > "$WORK/love-listing.txt"
+grep -qxF "tools/rom_manifest_gold.json" "$WORK/love-listing.txt" \
+  || fail "game.love is missing tools/rom_manifest_gold.json"
 # The .desktop's Icon= resolves against the AppDir root by basename, and
 # .DirIcon is what appimaged and file-manager thumbnailers read.
 cp "$IN/icon.png" "$APPDIR/$APP_NAME.png"
@@ -402,6 +411,12 @@ if [ -z "\$LUA_CPATH" ]; then
 fi
 export LUA_CPATH="\$APPDIR/lib/lua/5.1/?.so;\$LUA_CPATH"
 
+# SDL2 on Wayland crashes during desktop drag-and-drop in certain compositors;
+# default to X11/XWayland when available to ensure rock-solid drag-drop stability.
+if [ -n "\$WAYLAND_DISPLAY" ] && [ -z "\$SDL_VIDEODRIVER" ]; then
+    export SDL_VIDEODRIVER=x11
+fi
+
 exec "\$APPDIR/bin/love" --fused "\$APPDIR/game.love" "\$@"
 EOF
 chmod +x "$APPDIR/AppRun"

scripts/linux-arm64/selftest_build_linux_arm64.sh

@@ -167,5 +167,7 @@ trap 'rm -rf "$temp_dir"' EXIT
 unzip -p "$temp_dir/game.love" src/core/Version.lua \
   | grep -Eq 'engine[[:space:]]*=[[:space:]]*"1\.2\.3"' \
   || fail "shared payload version was not stamped"
+grep -qxF "tools/rom_manifest_gold.json" "$temp_dir/love-listing.txt" \
+  || fail "shared payload is missing tools/rom_manifest_gold.json"
 
 say "Linux arm64 self-test passed"

scripts/run.sh

@@ -35,4 +35,10 @@ find_love() {
 LOVE_BIN="$(find_love)" \
   || fail "LÖVE not found,  run scripts/setup.sh (or install from https://love2d.org)"
 
+# SDL2 on Wayland crashes during desktop drag-and-drop in certain compositors;
+# default to X11/XWayland when available to ensure rock-solid drag-drop stability.
+if [ -n "${WAYLAND_DISPLAY:-}" ] && [ -z "${SDL_VIDEODRIVER:-}" ]; then
+  export SDL_VIDEODRIVER=x11
+fi
+
 exec "$LOVE_BIN" "$ROOT" "$@"

src/battle/BattleSafety.lua

@@ -0,0 +1,98 @@
+-- Shared settled supported player-decision predicate. Checkpoint capture and
+-- the public auxiliary action deliberately use this one engine-owned rule so
+-- a tool cannot open at a phase that it could not subsequently checkpoint.
+-- It exposes no controller; callers receive only the result/reason.
+
+local BattleSafety = {}
+
+local BATTLE_BUSY_FIELDS = {
+  "current", "afterQueue", "nextInsert", "pendingHit", "waitingUI",
+  "waitingSound", "waitFrames", "draining", "animPlaying", "growIn",
+  "introSlide", "ghostReveal", "mimicCtx", "mimicMoves", "result",
+}
+
+local function nonempty(value)
+  return type(value) == "table" and next(value) ~= nil
+end
+
+local function running(runner)
+  return runner and runner.isRunning and runner:isRunning()
+end
+
+local function scriptsBusy(overworld)
+  return running(overworld and overworld.runner)
+    or nonempty(overworld and overworld.parallelRunners)
+    or nonempty(overworld and overworld.pendingScripts)
+    or nonempty(overworld and overworld.parallelQueue)
+    or nonempty(overworld and overworld.scriptMoves)
+end
+
+function BattleSafety.inspect(game, battle)
+  if type(game) ~= "table" or type(game.save) ~= "table"
+      or type(game.save.version) ~= "string" then
+    return nil, "not_in_playthrough", "A checkpoint requires an identified active playthrough."
+  end
+  if type(battle) ~= "table" then
+    return nil, "not_battle", "No battle is active."
+  end
+  if battle.kind == "link" then
+    return nil, "link_battle_unsupported", "Network battles cannot be checkpointed."
+  end
+  if battle.safari or battle.ghost or battle.scopeReveal or battle.demo or battle.noCatch then
+    return nil, "battle_variant_unsupported",
+      "This battle variant does not have a checkpoint contract."
+  end
+  if battle.kind ~= "wild" and battle.kind ~= "trainer" then
+    return nil, "battle_variant_unsupported",
+      "This battle kind does not have a checkpoint contract."
+  end
+  local origin = battle.checkpointOrigin
+  local ordinaryOrigin = battle.kind == "wild" and "wild_encounter"
+    or "trainer_encounter"
+  local scriptedOrigin = type(origin) == "table"
+    and origin.kind == "script_battle"
+  if type(origin) ~= "table"
+      or (origin.kind ~= ordinaryOrigin and not scriptedOrigin) then
+    return nil, "battle_origin_unsupported",
+      "The battle completion path cannot be reconstructed safely."
+  end
+  local overworld = game.overworld or {}
+  local scriptedRunner = scriptedOrigin and (battle.checkpointScriptContinuation
+    or (overworld.runner
+    and overworld.runner.isCheckpointBattle
+    and overworld.runner:isCheckpointBattle(battle)))
+  local otherScriptWork = nonempty(overworld.parallelRunners)
+    or nonempty(overworld.pendingScripts) or nonempty(overworld.parallelQueue)
+    or nonempty(overworld.scriptMoves)
+  if (scriptedOrigin and (not scriptedRunner or otherScriptWork))
+      or (not scriptedOrigin and scriptsBusy(overworld)) then
+    return nil, "script_busy", "A suspended or queued script cannot be checkpointed."
+  end
+  if battle.phase ~= "menu" or nonempty(battle.queue) then
+    return nil, "battle_phase_busy",
+      "Wait for the player command menu before creating a checkpoint."
+  end
+  for _, field in ipairs(BATTLE_BUSY_FIELDS) do
+    if battle[field] ~= nil and battle[field] ~= false then
+      return nil, "battle_phase_busy", "Wait for the current battle action to finish."
+    end
+  end
+  if not battle.player or not battle.enemy or not battle.player.mon
+      or battle.player.mon.hp <= 0
+      or (battle.menuLockedAction and battle:menuLockedAction(battle.player)) then
+    return nil, "battle_phase_busy",
+      "Wait for a supported player decision before creating a checkpoint."
+  end
+  for _, battler in ipairs({ battle.player, battle.enemy }) do
+    if not battler.mon or battler.shownHP ~= battler.mon.hp
+        or battler.shownStatus ~= battler.mon.status
+        or battler.drainFloor ~= nil or battler.drainHold ~= nil
+        or battler.faintQueued then
+      return nil, "battle_phase_busy",
+        "Wait for battle status and HP presentation to settle."
+    end
+  end
+  return true
+end
+
+return BattleSafety

src/battle/BattleState.lua

@@ -21,12 +21,14 @@ local MoveEffects = require("src.battle.MoveEffects")
 local Party = require("src.pokemon.Party")
 local Pokemon = require("src.pokemon.Pokemon")
 local Runtime = require("src.mods.Runtime")
+local BattleSafety = require("src.battle.BattleSafety")
 local Screens = require("src.ui.Screens")
 local Status = require("src.battle.Status")
 local Timing = require("src.core.Timing")
 local TrainerAI = require("src.battle.TrainerAI")
 local TurnOrder = require("src.battle.TurnOrder")
 local TypeChart = require("src.battle.TypeChart")
+local UIVisibility = require("src.battle.UIVisibility")
 local RomText = require("src.core.RomText")
 local Strings = require("src.core.Strings")
 local WideBattle = require("src.battle.WideBattle")
@@ -134,9 +136,7 @@ function BattleState:sgbPalettes()
 end
 
 function BattleState:bottomUIVisible()
-  if not Runtime.wantsHook("battle.bottom_ui_visible") then return true end
-  return Runtime.call("battle.bottom_ui_visible", function() return true end,
-                      self) ~= false
+  return UIVisibility.bottomVisible(self, true)
 end
 
 function BattleState:statusHUDVisible()
@@ -501,6 +501,9 @@ local function makeBattler(data, mon, isPlayer, save)
     badgeBoosts = badgeBoosts,
     statuses = data.statuses,
     shownHP = mon.hp, -- the HP the bar displays (UpdateHPBar drain)
+    -- the bar's own length in GetHPBarLength pixels; it trails shownHP
+    -- because UpdateHPBar_AnimateHPBar slides it one pixel at a time
+    shownPx = Timing.hpBarPixels(mon.hp, math.max(1, mon.stats.hp)),
     -- HUD status label (DrawHUDsAndHPBars); mon.status can land mid-move
     -- while the tilemap still shows the prior condition until the next
     -- post-action HUD refresh (core.asm after Execute*Move)
@@ -563,10 +566,6 @@ local function markOwned(game, species)
   local dex = game.save.pokedex
   if dex then
     dex.seen[species] = true
-    if not dex.owned[species] then
-      -- new dex page registered (SFX_DEX_PAGE_ADDED)
-      require("src.core.Sound").play(game.data, "Dex_Page_Added")
-    end
     dex.owned[species] = true
   end
 end
@@ -613,6 +612,7 @@ local function newBattle(game)
   self.phase = "intro"
   self.menuIndex = 1
   self.moveIndex = 1
+  self.playerMoveListIndex = 1
   self.frame = 0
   return self
 end
@@ -929,6 +929,22 @@ function BattleState:sayNext(text)
   table.insert(self.queue, self.nextInsert, { text = text })
 end
 
+function BattleState:sayNextWaitSfx(text, sfx)
+  self.nextInsert = (self.nextInsert or 0) + 1
+  table.insert(self.queue, self.nextInsert, { text = text, waitForLearningSfx = sfx })
+end
+
+-- WaitForSoundToFinish for a sound an act() has already started: PlayCry
+-- ends in `jp WaitForSoundToFinish` (home/pokemon.asm), so every cry in
+-- Gen 1 holds whatever the ROM does next.  `src` is the audio source, or a
+-- getter the row calls at execution time when the source is only known then.
+function BattleState:waitSfxNext(src)
+  self.nextInsert = (self.nextInsert or 0) + 1
+  table.insert(self.queue, self.nextInsert,
+               { waitSound = type(src) == "function" and src
+                             or function() return src end })
+end
+
 -- sayNext for a page that ends in `text_end` (see sayAuto) (#765)
 function BattleState:sayNextAuto(text, delay)
   self.nextInsert = (self.nextInsert or 0) + 1
@@ -1016,22 +1032,39 @@ function BattleState:stepHPDrain()
          and b.shownHP >= b.drainFloor then
         goal = b.drainFloor
       end
+      local maxHP = math.max(1, b.mon.stats.hp)
+      local playerSide = (b == self.player)
+      local targetPx = Timing.hpBarPixels(b.shownHP, maxHP)
+      if not b.shownPx then b.shownPx = targetPx end
       if (b.drainHold or 0) > 0 then
         b.drainHold = b.drainHold - 1
         busy = true
+      elseif b.shownPx ~= targetPx then
+        -- .barAnimationLoop redraws the bar one pixel at a time, `ld c, 2 /
+        -- call DelayFrames` apiece (:141-148), so a single HP point that
+        -- spans several pixels still slides instead of jumping
+        b.shownPx = b.shownPx + ((b.shownPx > targetPx) and -1 or 1)
+        b.drainHold = Timing.HP_BAR_PIXEL_STEP - 1
+        busy = true
       elseif b.shownHP ~= goal then
-        local maxHP = math.max(1, b.mon.stats.hp)
-        local playerSide = (b == self.player)
-        local cost = 0
+        local spent = 0
         -- consume whole HP steps until this frame's budget is spent; on the
         -- enemy HUD several free steps can land in the same frame
-        while b.shownHP ~= goal and cost < 1 do
-          local nextHP = b.shownHP + ((b.shownHP > goal) and -1 or 1)
-          cost = cost + Timing.hpDrainStepFrames(b.shownHP, nextHP,
-                                                 maxHP, playerSide)
-          b.shownHP = nextHP
+        repeat
+          b.shownHP = b.shownHP + ((b.shownHP > goal) and -1 or 1)
+          spent = spent + (playerSide and Timing.HP_BAR_HP_STEP or 0)
+          targetPx = Timing.hpBarPixels(b.shownHP, maxHP)
+        until b.shownHP == goal or targetPx ~= b.shownPx or spent >= 1
+        if spent > 0 then
+          b.drainHold = spent - 1
+        elseif targetPx ~= b.shownPx then
+          -- the enemy HUD printed no number, so this frame is already the
+          -- first of the pixel step the crossing just asked for
+          b.shownPx = b.shownPx + ((b.shownPx > targetPx) and -1 or 1)
+          b.drainHold = Timing.HP_BAR_PIXEL_STEP - 1
+        else
+          b.drainHold = 0
         end
-        b.drainHold = math.max(0, cost - 1)
         b.draining = true
         busy = true
       elseif b.draining then
@@ -1255,13 +1288,13 @@ function BattleState:updateQueue()
         -- no subanimation player: keep the single-sound fallback (with
         -- the move's pitch/tempo modifiers; GROWL/ROAR play the
         -- attacker's cry -- GetMoveSound/IsCryMove)
-        if item.anim == "GROWL" or item.anim == "ROAR" then
+        if self:animationsOn() and (item.anim == "GROWL" or item.anim == "ROAR") then
           local attacker = item.attackerIsPlayer and self.player or self.enemy
           if attacker then
             require("src.core.Sound").playMoveCry(self.data, attacker.mon.species,
                                                    anim and anim.tempo)
           end
-        elseif anim and anim.sound then
+        elseif self:animationsOn() and anim and anim.sound then
           local Sound = require("src.core.Sound")
           if Sound.playMove then
             Sound.playMove(self.data, anim)
@@ -1361,6 +1394,11 @@ function BattleState:updateQueue()
         self.current = nil
       end
     elseif not (item and item.choice) then
+      if item and item.waitForLearningSfx and not item.soundStarted then
+        item.soundStarted = true
+        self.waitingSound = item.waitForLearningSfx()
+        return true
+      end
       -- The page is typed out and waiting on the player: PromptText
       -- (home/text.asm:209-217) writes '▼' at (18,16) and ManualTextScroll
       -- blinks it until A/B, so the arrow belongs on a finished page and not
@@ -1420,7 +1458,7 @@ end
 function BattleState:playEntranceCry(battler)
   local mon = battler and battler.mon
   if not mon then return end
-  require("src.core.Sound").playCry(self.data, mon.species,
+  return require("src.core.Sound").playCry(self.data, mon.species,
     mon.status == "SLP" and 37 or 11)
 end
 
@@ -1544,7 +1582,23 @@ function BattleState:enter()
   -- default stays opaque for every other battle and for older saves.
   self.isOpaque = self:bgMode() ~= "world"
   self.introSlide = Timing.BATTLE_SLIDE_IN_FRAMES
-  self.showEnemyTrainer = self.kind == "trainer" and self.trainerPic ~= nil
+  -- GetTrainerInformation .linkBattle (home/trainers2.asm:26-31): the link
+  -- foe's pic is RedPicFront whatever either save looks like, and
+  -- InitBattleCommon loads and tilemaps it at hlcoord 12,0 for every
+  -- wIsInBattle == 2 battle (core.asm:6681-6688), the link one included.
+  -- wEnemyMonSpecies2 is zeroed under it, so the pic palette is PAL_MEWMON
+  -- exactly as it is for a trainer.
+  if self.kind == "link" and not self.trainerPic then
+    local frontPath, frontTrueColor =
+      require("src.pokemon.Sprites").playerPath(self.data, "front",
+        { kind = "battle", battle = self })
+    if frontPath and require("src.render.Assets").exists(frontPath) then
+      self.trainerPic = getImage(frontPath, namedPalette(self.data, "MEWMON"),
+                                 frontTrueColor)
+    end
+  end
+  self.showEnemyTrainer = (self.kind == "trainer" or self.kind == "link")
+                          and self.trainerPic ~= nil
   -- DrawAllPokeballs (common_text.asm:27) puts the party ball rows AND the
   -- HUD corner/underline tiles under them (PlacePlayerHUDTiles /
   -- PlaceEnemyHUDTiles, draw_hud_pokeball_gfx.asm:119-165) on screen with
@@ -1576,13 +1630,13 @@ function BattleState:enter()
   -- a different point in each battle kind, so queue it per branch
   local function queueEnemyCry()
     self:act(function()
-      self:playEntranceCry(self.enemy)
+      self:waitSfxNext(self:playEntranceCry(self.enemy))
     end)
   end
   -- PrintBeginningBattleText (engine/battle/common_text.asm:10-19): a wild
-  -- battle calls PlayCry BEFORE PrintText WildMonAppearedText, so the cry
-  -- sounds with the "Wild X appeared!" box instead of waiting on the A
-  -- press that clears its `prompt` (#303).  The Silph-Scope-less tower
+  -- battle calls PlayCry BEFORE PrintText WildMonAppearedText, and PlayCry
+  -- ends in WaitForSoundToFinish, so the cry runs to its end and only then
+  -- does the "Wild X appeared!" box open (#303).  The Silph-Scope-less tower
   -- ghost gets no cry at all (common_text.asm:43-48), and neither does the
   -- unveiled MAROWAK: .isMarowak never reaches PlayCry (#492).
   if self.kind ~= "trainer" and self.kind ~= "link"
@@ -1600,7 +1654,10 @@ function BattleState:enter()
   -- The sfx is extracted as "Trainer_Appeared" (tools/rom_manifest.json
   -- sfxHeaders, bank 8 / $42bb -- the same header pokered names
   -- SFX_Silph_Scope); nothing had ever played it.
-  if self.kind == "trainer" then
+  --
+  -- A link battle is wIsInBattle == 2, so PrintBeginningBattleText takes the
+  -- same .trainerBattle arm and owes the sfx too (common_text.asm:20-23).
+  if self.kind == "trainer" or self.kind == "link" then
     self:act(function()
       self.introSfx = require("src.core.Sound").play(self.data,
                                                      "Trainer_Appeared")
@@ -1618,13 +1675,17 @@ function BattleState:enter()
   -- battle -- not on a switch, and not when the beaten trainer's pic
   -- scrolls back in (#317, #282)
   self:act(function() self.introBalls = nil end)
-  if self.kind == "trainer" then
-    -- EnemySendOutFirstMon (core.asm:1308-1310): SlideTrainerPicOffScreen
-    -- walks the foe's pic off the RIGHT edge (hlcoord 18,0, a = 8 tiles,
-    -- one tile every 2 frames) BEFORE TrainerSentOutText -- the pic does
-    -- not blink out under the text (#317)
-    self:act(function() self:slidePic("foe", 0, 64, 4) end)
-    table.insert(self.queue, { wait = 16 })
+  if self.kind == "trainer" or self.kind == "link" then
+    local foeName = self.trainer and self.trainer.name
+                    or self.opponentName or Strings("FOE")
+    if self.showEnemyTrainer then
+      -- EnemySendOutFirstMon (core.asm:1308-1310): SlideTrainerPicOffScreen
+      -- walks the foe's pic off the RIGHT edge (hlcoord 18,0, a = 8 tiles,
+      -- one tile every 2 frames) BEFORE TrainerSentOutText -- the pic does
+      -- not blink out under the text (#317)
+      self:act(function() self:slidePic("foe", 0, 64, 4) end)
+      table.insert(self.queue, { wait = 16 })
+    end
     self:act(function()
       self.showEnemyTrainer = false
       -- the slot is EMPTY from here until AnimateSendingOutMon runs below:
@@ -1637,7 +1698,7 @@ function BattleState:enter()
       self.enemySendingOut = true
       self:slidePic("foe")
     end)
-    self:say(Strings("%s sent\nout %s!", self.trainer.name, self.enemy.name))
+    self:say(Strings("%s sent\nout %s!", foeName, self.enemy.name))
     self:act(function()
       -- EnemySendOutFirstMon (core.asm:1421-1434): after the text the
       -- pic grows out of the ball (AnimateSendingOutMon), then the cry
@@ -1645,18 +1706,6 @@ function BattleState:enter()
       self:startGrowIn(self.enemy)
     end)
     queueEnemyCry()
-  elseif self.kind == "link" then
-    -- Colosseum has no foe trainer pic, but the enemy mon still grows
-    -- out of the ball after "X sent out Y!" (not the wild "already there"
-    -- intro that LinkBattle previously inherited from newWild).
-    self.enemySendingOut = true
-    self:say(Strings("%s sent\nout %s!", self.opponentName or Strings("FOE"),
-                                          self.enemy.name))
-    self:act(function()
-      self.enemySendingOut = false
-      self:startGrowIn(self.enemy)
-    end)
-    queueEnemyCry()
   end
   -- StartBattle .foundFirstAliveEnemyMon (core.asm:152-156): the `call nz`
   -- gates only EnemySendOutFirstMon -- the `ld c, 40 / call DelayFrames`
@@ -1687,7 +1736,7 @@ function BattleState:enter()
       -- SendOutMon (core.asm:1757-1762): after the poof the mon grows
       -- out of the ball (AnimateSendingOutMon at hlcoord 4,11)
       self:startGrowIn(self.player)
-      self:playEntranceCry(self.player)
+      self:waitSfxNext(self:playEntranceCry(self.player))
     end)
     self:markParticipant()
   end
@@ -1746,6 +1795,7 @@ end
 local function sendOutMonCursors(self)
   self.menuIndex = 1
   self.moveIndex = 1
+  self.playerMoveListIndex = 1
 end
 
 -- core.asm:297-300: both sides' FLINCHED bits are cleared as a turn's move
@@ -1864,7 +1914,10 @@ function BattleState:update(dt)
   if self.phase == "menu" then
     for _, b in ipairs({ self.player, self.enemy }) do
       if b then
-        if b.shownHP then b.shownHP = b.mon.hp end
+        if b.shownHP then
+          b.shownHP = b.mon.hp
+          b.shownPx = Timing.hpBarPixels(b.mon.hp, math.max(1, b.mon.stats.hp))
+        end
         b.drainFloor = nil
         b.shownStatus = b.mon.status
       end
@@ -1962,6 +2015,17 @@ function BattleState:update(dt)
       self:resolveTurn(locked)
       return
     end
+    -- START has no vanilla action at a settled supported player-decision
+    -- boundary.  A tool mod may claim this semantic auxiliary action through
+    -- the public hook, receiving only game plus a data-only kind.  The shared
+    -- safety predicate keeps every unsupported/forced/animated phase inert.
+    if input:wasPressed("start") and Runtime.wantsHook("battle.menu_auxiliary") then
+      local safe = BattleSafety.inspect(self.game, self)
+      if safe and Runtime.call("battle.menu_auxiliary", function() return false end,
+          self.game, { kind = self.kind }) == true then
+        return
+      end
+    end
     local col = (self.menuIndex - 1) % 2
     local row = math.floor((self.menuIndex - 1) / 2)
     if input:wasPressed("left") then
@@ -2033,8 +2097,10 @@ function BattleState:update(dt)
       if self.moveSwapIndex then
         self:swapMoves(self.moveSwapIndex, self.moveIndex)
         self.moveSwapIndex = nil
+        self.moveIndex = math.min(self.playerMoveListIndex or 1, #moves)
       else
         self.moveSwapIndex = self.moveIndex
+        self.moveIndex = math.min(self.playerMoveListIndex or 1, #moves)
       end
     elseif input:wasPressed("b") then
       require("src.core.Sound").play(self.data, "Press_AB")
@@ -2057,6 +2123,7 @@ function BattleState:update(dt)
         self.phase = "messages"
         self.afterQueue = "menu"
       else
+        self.playerMoveListIndex = self.moveIndex
         self:resolveTurn(mv)
       end
     end
@@ -2268,10 +2335,10 @@ function BattleState:oldManThrow()
       return
     end
     self:ballChain("TOSS_ANIM", true, 3, "POKE_BALL")
-    self:actNext(function()
-      require("src.core.Sound").play(self.data, "Caught_Mon")
-    end)
-    self:sayNext(Strings("All right!\n%s was\ncaught!", self.enemy.name))
+    -- ItemUseBallText05: text_far, sound_caught_mon, text_promptbutton --
+    -- the fanfare follows the caught text and holds the prompt
+    self:sayNextWaitSfx(Strings("All right!\n%s was\ncaught!", self.enemy.name),
+      function() return require("src.core.Sound").play(self.data, "Caught_Mon") end)
   end)
 end
 
@@ -2412,11 +2479,9 @@ function BattleState:resolveTurn(playerAction)
   end
   local order
   if pFirst then
-    order = { { self.player, self.enemy, playerAction },
-              { self.enemy, self.player, enemyAction } }
+    order = { { true, playerAction }, { false, enemyAction } }
   else
-    order = { { self.enemy, self.player, enemyAction },
-              { self.player, self.enemy, playerAction } }
+    order = { { false, enemyAction }, { true, playerAction } }
   end
 
   self.phase = "messages"
@@ -2424,7 +2489,9 @@ function BattleState:resolveTurn(playerAction)
 
   for _, entry in ipairs(order) do
     self:act(function()
-      self:executeAction(entry[1], entry[2], entry[3])
+      local user = entry[1] and self.player or self.enemy
+      local target = entry[1] and self.enemy or self.player
+      self:executeAction(user, target, entry[2])
     end)
   end
   self:act(function() self:endOfTurn() end)
@@ -2455,7 +2522,7 @@ function BattleState:resolveSwitch(newMon)
       self.sendingOut = false
       -- SendOutMon (core.asm:1757-1762): poof, then the grow-in
       self:startGrowIn(self.player)
-      self:playEntranceCry(self.player)
+      self:waitSfxNext(self:playEntranceCry(self.player))
     end)
   end)
   self:act(function()
@@ -2934,7 +3001,7 @@ function BattleState:applyHitFx(hit)
       Sound.play(self.data, hit.sfx)
     end
   end
-  if not t or not self:animationsOn() then return end
+  if not t then return end
   if t == 1 then
     -- PredefShakeScreenVertically b=8: the window drops by b for 3 frames
     -- then home for 3, b counting down
@@ -3767,7 +3834,7 @@ function BattleState:onFaint(battler)
     if battler.isPlayer then
       -- RemoveFaintedPlayerMon (core.asm:1040-1042): the player mon's
       -- faint plays its ordinary species cry -- no Faint_Fall
-      Sound.playCry(self.data, battler.mon.species)
+      self.faintCry = Sound.playCry(self.data, battler.mon.species)
     elseif self.kind ~= "wild" then
       -- FaintEnemyPokemon (core.asm:732-771): the enemy faint plays no
       -- species cry; trainer battles get SFX_FAINT_FALL, then SFX_FAINT_THUD
@@ -3782,6 +3849,11 @@ function BattleState:onFaint(battler)
   end)
   self.nextInsert = (self.nextInsert or 0) + 1
   table.insert(self.queue, self.nextInsert, { wait = Timing.FAINT_SLIDE })
+  if battler.isPlayer then
+    -- RemoveFaintedPlayerMon ends `call PlayCry / jp PrintText`, and PlayCry
+    -- is `jp WaitForSoundToFinish`, so "X fainted!" waits out the cry
+    self:waitSfxNext(function() return self.faintCry end)
+  end
   if not battler.isPlayer and self.kind ~= "wild" then
     -- FaintEnemyPokemon's SFX_FAINT_THUD lands as the slide does (after
     -- Faint_Fall, before EnemyMonFaintedText)
@@ -3828,9 +3900,12 @@ function BattleState:awardExp()
     participants, alive = 1, { self.player.mon }
   end
   local function applyShare(mon, split, announce)
+    local playerId = self.game.save.player and self.game.save.player.id
+    local traded = mon.otId ~= nil and playerId ~= nil
+      and mon.otId ~= playerId or mon.traded == true and mon.otId == nil
     local levels, gained = Experience.apply(self.data, mon, self.enemy.def,
                                             self.enemy.mon.level, self.kind == "trainer",
-                                            split, mon.traded)
+                                            split, traded)
     -- Track level-ups for EvolveAfterBattle (OverworldState:afterBattle ->
     -- Evolution.checkParty).  B-cancel leaves the mon at/above threshold;
     -- without this gate it re-triggers after every later fight (#213).
@@ -3854,7 +3929,7 @@ function BattleState:awardExp()
       local text = Strings.source("%s gained\n%d EXP. Points!")
       if announce == "expAll" then
         text = Strings.source("%s gained\nwith EXP.ALL,\v%d EXP. Points!")
-      elseif mon.traded then
+      elseif traded then
         text = Strings.source("%s gained\na boosted\v%d EXP. Points!")
       end
       self:sayNext(Strings(text, name, gained))
@@ -3866,9 +3941,11 @@ function BattleState:awardExp()
       -- experience.asm:248 fires per grew-level text
       require("src.world.PikachuFollower")
         .modifyHappiness(game.save, "LEVELUP", mon)
-      self:sayNext(Strings("%s grew\nto level %d!", name, lv))
+      -- GrewLevelText: text_far, sound_level_up, text_end (experience.asm:
+      -- 369-372); PrintStatsBox only runs once PrintText has returned
+      self:sayNextWaitSfx(Strings("%s grew\nto level %d!", name, lv),
+        function() return require("src.core.Sound").play(game.data, "Level_Up") end)
       self:uiNext(function()
-        require("src.core.Sound").play(game.data, "Level_Up")
         return StatBox.new(game, mon)
       end)
       -- After PrintStatsBox, experience.asm reloads the active battler's
@@ -4013,7 +4090,7 @@ function BattleState:enemyMonFainted()
           self.enemySendingOut = false
           self:startGrowIn(self.enemy)
           self:actNext(function()
-            self:playEntranceCry(self.enemy)
+            self:waitSfxNext(self:playEntranceCry(self.enemy))
           end)
         end)
       end)
@@ -4052,7 +4129,7 @@ function BattleState:enemyMonFainted()
         self:actNext(function()
           self.sendingOut = false
           self:startGrowIn(self.player)
-          self:playEntranceCry(self.player)
+          self:waitSfxNext(self:playEntranceCry(self.player))
         end)
       end)
       return
@@ -4118,15 +4195,17 @@ function BattleState:learnMove(mon, moveId)
   if #mon.moves < 4 then
     table.insert(mon.moves, { id = moveId, pp = mdef.pp })
     Runtime.emit("pokemon.move_learned", { mon = mon, moveId = moveId })
-    self:sayNext(self:romText("_MimicLearnedMoveText", "%s learned\n%s!", mon.nickname or self.data.pokemon[mon.species].name,
-                                            mdef.name))
+    self:sayNextWaitSfx(self:romText("_MimicLearnedMoveText", "%s learned\n%s!", mon.nickname or self.data.pokemon[mon.species].name,
+                                            mdef.name), function()
+      return require("src.core.Sound").play(self.data, "Level_Up")
+    end)
     return
   end
   -- the "trying to learn" preamble lives inside MoveLearnMenu:enter;
   -- ordered insert so multi-level gains keep each level's checks
   -- between its own stat box and the next "grew to level" text
   self:uiNext(function()
-    return self:buildScreen("MoveLearnMenu", mon, moveId)
+    return self:buildScreen("MoveLearnMenu", mon, moveId, nil, "Level_Up")
   end)
 end
 
@@ -4246,7 +4325,7 @@ function BattleState:openReplacementMenu()
           self.sendingOut = false
           -- SendOutMon (core.asm:1757-1762): poof, then the grow-in
           self:startGrowIn(self.player)
-          self:playEntranceCry(self.player)
+          self:waitSfxNext(self:playEntranceCry(self.player))
         end)
       end,
     })
@@ -4290,11 +4369,10 @@ function BattleState:safariAction(choice)
       -- above DoBallTossSpecialEffects's <= ULTRA_BALL check)
       self:ballChain(self:tossAnimFor("SAFARI_BALL"), caught, shakes, "SAFARI_BALL")
       if caught then
-        -- ItemUseBallText05's sound_caught_mon: fanfare with the text
-        self:actNext(function()
-          require("src.core.Sound").play(self.data, "Caught_Mon")
-        end)
-        self:sayNext(Strings("All right!\n%s was\ncaught!", self.enemy.name))
+        -- ItemUseBallText05: text_far, sound_caught_mon, text_promptbutton --
+        -- the fanfare follows the caught text and holds the prompt
+        self:sayNextWaitSfx(Strings("All right!\n%s was\ncaught!", self.enemy.name),
+          function() return require("src.core.Sound").play(self.data, "Caught_Mon") end)
         -- same ItemUseBall .captured flow as a regular ball
         self:act(function() self:storeCaughtMon() end)
       else
@@ -4522,8 +4600,12 @@ function BattleState:storeCaughtMon()
   markOwned(game, species)
   stampOT(game.save, self.enemy.mon)
   if isNew then
-    -- _ItemUseBallText06 + ShowPokedexData
-    self:sayNext(Strings("New POKéDEX data\nwill be added for\n%s!", self.enemy.name))
+    -- _ItemUseBallText06 + ShowPokedexData: text_far, sound_dex_page_added,
+    -- text_promptbutton (item_effects.asm:624-629), so the fanfare follows
+    -- the box rather than firing when the dex bit is set
+    self:sayNextWaitSfx(
+      Strings("New POKéDEX data\nwill be added for\n%s!", self.enemy.name),
+      function() return require("src.core.Sound").play(self.data, "Dex_Page_Added") end)
     self:uiNext(function()
       return self:buildScreen("DexEntryMenu", species)
     end)
@@ -4673,12 +4755,10 @@ function BattleState:throwBall(ball)
     self:ballChain(self:tossAnimFor(ball), caught, shakes, ball)
     if caught then
       -- ItemUseBallText05 carries sound_caught_mon (item_effects.asm:
-      -- 608-614): the fanfare sounds with the caught message, before
-      -- the prompt, not after the text is dismissed
-      self:actNext(function()
-        require("src.core.Sound").play(self.data, "Caught_Mon")
-      end)
-      self:sayNext(Strings("All right!\n%s was\ncaught!", self.enemy.name))
+      -- 608-614): text_far, sound_caught_mon, text_promptbutton -- the
+      -- fanfare follows the caught message and holds the prompt
+      self:sayNextWaitSfx(Strings("All right!\n%s was\ncaught!", self.enemy.name),
+        function() return require("src.core.Sound").play(self.data, "Caught_Mon") end)
       self:act(function() self:storeCaughtMon() end)
     else
       self:sayNext(self:ballMissMessage(shakes))
@@ -5165,7 +5245,8 @@ function BattleState:sgbBattlePals()
   local function bar(b)
     if not b then return pals.GREENBAR end
     local hp = b.shownHP or b.mon.hp
-    return pals[PaletteFX.barPalName(hp, b.mon.stats.hp)] or pals.GREENBAR
+    return pals[PaletteFX.barPalName(hp, b.mon.stats.hp, b.shownPx)]
+           or pals.GREENBAR
   end
   local function mon(b, placeholder)
     if placeholder or not b then return pals.MEWMON or pals.GREENBAR end
@@ -5563,7 +5644,7 @@ function BattleState:drawHUDs(slide)
     hudTile(0x73, 8, 16)
     drawHPBar(barData, 2, 2,
               { hp = shownHP(self.enemy), stats = self.enemy.mon.stats },
-              nil, grayFill)
+              nil, grayFill, nil, self.enemy.shownPx)
     hudTile(0x74, 8, 24)
     for i = 2, 9 do hudTile(0x76, i * 8, 24) end
     hudTile(0x78, 80, 24)
@@ -5644,7 +5725,7 @@ function BattleState:drawHUDs(slide)
     end
     drawHPBar(barData, 10, 9,
               { hp = shownHP(self.player), stats = self.player.mon.stats },
-              1, grayFill) -- wHPBarType 1: the $6D cap
+              1, grayFill, nil, self.player.shownPx) -- wHPBarType 1: the $6D cap
     Font.draw(("%3d/%3d"):format(shownHP(self.player), self.player.mon.stats.hp), 88, 80)
     hudTile(0x73, 144, 80)
     hudTile(0x77, 144, 88)
@@ -5780,6 +5861,7 @@ function BattleState:drawTextArea()
       Font.draw(self.data.moves[m.id].name, 16, (7 + i) * 8)
     end
     Font.drawCode(0xED, 8, (7 + self.mimicIndex) * 8)
+    Font.draw(Strings("WHICH TECHNIQUE?"), 8, 112)
   end
 end
 

src/battle/EffectRegistry.lua

@@ -310,8 +310,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   if record and record.afterDamage then
     record.afterDamage(ctx, totalDealt)
   elseif moveInst.struggle then
-    -- struggle recoils even when its effect id resolves to no record
-    local recoil = math.max(1, math.floor(dmg / 2))
+    local recoil = math.max(1, math.floor(totalDealt / 2))
     battle:sayNext(romText(battle.data, "_HitWithRecoilText", "%s's\nhit with recoil!", displayName(user)))
     battle:applyDamage(user, recoil)
   end

src/battle/MoveEffects.lua

@@ -348,8 +348,9 @@ MoveEffects.primary = {
     target.disabledTurns = battle.rng(1, 8)
     local id = target.curMoves[slot].id
     -- _MoveWasDisabledText: "X's / MOVE was / disabled!"
-    return { romText(battle.data, "_MoveWasDisabledText", "%s's\n%s was\ndisabled!", displayName(target),
-                                                battle.data.moves[id].name) }
+    return { romText(battle.data, "_MoveWasDisabledText", "%s's\n%s was\ndisabled!",
+      { TARGET = displayName(target),
+        ["RAM:wNameBuffer"] = battle.data.moves[id].name }) }
   end,
 
   SPLASH_EFFECT = function(battle)
@@ -441,11 +442,10 @@ local function hitsFrom(dist, ctx)
   return dist[r + 1]
 end
 
--- drain_hp.asm halves the RAW wDamage IN PLACE (minimum 1) and heals
--- that amount, so Counter would see the halved value
+-- engine/battle/core.asm ApplyDamageToEnemyPokemon
 local function drainHalf(label, text)
   return function(ctx)
-    local heal = math.max(1, math.floor(ctx.rawDamage / 2))
+    local heal = math.max(1, math.floor(ctx.totalDealt / 2))
     ctx.battle.lastDamage = heal
     local mon = ctx.user.mon
     mon.hp = math.min(mon.stats.hp, mon.hp + heal)
@@ -529,9 +529,8 @@ MoveEffects.full = {
 
   RECOIL_EFFECT = {
     afterDamage = function(ctx)
-      -- recoil.asm reads the RAW computed wDamage (not the HP actually
-      -- removed): overkill and substitute hits recoil at full strength
-      local recoil = math.max(1, math.floor(ctx.rawDamage
+      -- engine/battle/move_effects/recoil.asm
+      local recoil = math.max(1, math.floor(ctx.totalDealt
                                             / (ctx.moveInst.struggle and 2 or 4)))
       ctx.say(romText(ctx.battle.data, "_HitWithRecoilText", "%s's\nhit with recoil!", displayName(ctx.user)))
       ctx.battle:applyDamage(ctx.user, recoil)

src/battle/Status.lua

@@ -243,7 +243,9 @@ function Status.beforeMove(battler, rng, battle, selectedMoveId)
       local shown = moves and moves[selectedMoveId] and moves[selectedMoveId].name
                     or tostring(selectedMoveId)
       table.insert(msgs, romText(battle and battle.data, "_MoveIsDisabledText",
-        "%s's\n%s is\ndisabled!", name(battler), shown))
+        "%s's\n%s is\ndisabled!", {
+          USER = name(battler), ["RAM:wNameBuffer"] = shown,
+        }))
       return false, msgs
     end
   end

src/battle/UIVisibility.lua

@@ -0,0 +1,39 @@
+-- Shared visibility rules for battle-owned UI states.  Text and choice
+-- overlays live above BattleState on the state stack, but they are still part
+-- of its bottom UI layer and must inherit that layer's visibility.
+
+local Runtime = require("src.mods.Runtime")
+
+local UIVisibility = {}
+
+local function enclosingBattle(state)
+  local stack = state and state.game and state.game.stack
+  local states = stack and stack.states
+  local found = false
+  for i = #(states or {}), 1, -1 do
+    local candidate = states[i]
+    if candidate == state then found = true end
+    if found and candidate and candidate.isBattle then return candidate end
+  end
+  return nil
+end
+
+-- queryState keeps the existing TextBox contract: a mod may still decide
+-- visibility for that individual box.  ChoiceBox only inherits the enclosing
+-- battle decision, so field YES/NO prompts never become battle-hook states.
+function UIVisibility.bottomVisible(state, queryState)
+  if not Runtime.wantsHook("battle.bottom_ui_visible") then return true end
+  local battle = enclosingBattle(state)
+  if battle and battle ~= state
+      and Runtime.call("battle.bottom_ui_visible",
+                       function() return true end, battle) == false then
+    return false
+  end
+  if queryState or battle == state then
+    return Runtime.call("battle.bottom_ui_visible",
+                        function() return true end, state) ~= false
+  end
+  return true
+end
+
+return UIVisibility

src/battle/WideBattle.lua

@@ -108,7 +108,7 @@ local function drawStatusPanel(battle, battler, x, y, player)
   HudTiles.drawHPBar(battle.data, tx + 1, ty + 2, {
     hp = shownHP(battler),
     stats = battler.mon.stats,
-  }, nil, monoMode(), tw - 5)
+  }, nil, monoMode(), tw - 5, battler.shownPx)
 
   if player then
     Font.draw(("%3d/%3d"):format(shownHP(battler), battler.mon.stats.hp),

src/battle/gen2/Battle.lua

@@ -37,8 +37,10 @@ local Prize = require("src.battle.gen2.Prize")
 --   * Gen 1's `user` / `target` / `battler` are battler wrappers around a mon
 --     ({ mon = , name = , isPlayer = }); Gen 2's engine works on the party mon
 --     table directly, so that is what these payloads carry.
---   * Gen 1's `rng` is love.math.random (1..n); Gen 2's injected `random` is
---     the cart's BattleRandom convention (0..n-1).  Both keys are present.
+--   * Gen 1's `rng` is love.math.random (rng(n) → 1..n, rng(lo,hi) → lo..hi).
+--     Gen 2's cart BattleRandom is random(n) → 0..n-1.  Both live on the
+--     battle: `random` / `roller()` are BattleRandom for damage, accuracy,
+--     Magnitude, etc.; `rng` is the Gen 1 / love-style view of the same stream.
 local Runtime = require("src.mods.Runtime")
 -- The two battle lines that carry the cart's own `line` break: a marker-bearing
 -- literal has to stay reachable from a translation mod (#186, #245), which is
@@ -88,6 +90,19 @@ local function rand(random, n)
   return math.random(n) - 1
 end
 
+-- Gen 1 / love.math view of BattleRandom: rng(n) → 1..n, rng(lo,hi) → lo..hi.
+local function loveStyleRng(random)
+  return function(lo, hi)
+    if hi == nil then
+      local n = lo or 1
+      if n < 1 then n = 1 end
+      return (rand(random, n) or 0) + 1
+    end
+    if hi < lo then lo, hi = hi, lo end
+    return lo + (rand(random, hi - lo + 1) or 0)
+  end
+end
+
 -- data/trainers/leaders.asm.  The two lists are ONE array in the ROM: only
 -- KantoGymLeaders carries the -1 terminator, and GymLeaders falls through into
 -- it, so IsGymLeader matches all twenty-two classes while IsKantoGymLeader
@@ -212,12 +227,15 @@ Battle.KANTO_BADGE_ORDER = {
 --             this wild battle is BATTLETYPE_ROAMING; the caller built `wild`
 --             through Roamers.beginBattle and reads Battle.roaming back to
 --             bank the beast's HP afterwards
---   random(n) 0..n-1, injected so a test is deterministic
+--   random(n) 0..n-1, injected so a test is deterministic (BattleRandom)
+--   rng(lo,hi) / rng(n) Gen 1 / love.math contract; defaults over `random`
 function Battle.new(opts)
   opts = opts or {}
   local self = setmetatable({}, Battle)
   self.data = opts.data or {}
-  self.random = opts.random
+  self.random = opts.random or function(n) return rand(nil, n) end
+  -- Same stream as `random`, Gen 1 / love.math calling convention.
+  self.rng = opts.rng or loveStyleRng(self.random)
   self.party = opts.party or {}
   self.trainer = opts.trainer
   self.save = opts.save
@@ -271,6 +289,13 @@ function Battle.new(opts)
     self.enemy = self.enemyParty[self.enemyIndex]
   end
 
+  for _, mon in ipairs(self.party) do
+    Mon.refreshStats(mon, self.data)
+  end
+  for _, mon in ipairs(self.enemyParty or {}) do
+    Mon.refreshStats(mon, self.data)
+  end
+
   -- Battle RAM opens empty on both sides: NewBattleMonStatus and
   -- NewEnemyMonStatus run at the first send-out of every battle.
   self:clearAllVolatiles()
@@ -396,11 +421,8 @@ function Battle:endBattle(outcome)
   Runtime.emit("battle.ended", { battle = self, result = outcome })
 end
 
--- A never-nil 0..n-1 roller for the hook contexts.  `random` is optional on the
--- constructor (a headless test injects one, the game leaves it to love.math),
--- and a mod reaching for ctx.rng must not have to know that.  Note the
--- convention: this is the cart's BattleRandom byte (0..n-1), NOT Gen 1's
--- love.math.random (1..n).
+-- Never-nil BattleRandom (0..n-1) for call sites that want the cart byte.
+-- `battle.rng` is the Gen 1 / love.math view of the same stream.
 function Battle:roller()
   if not self.rollerFn then
     self.rollerFn = function(n) return rand(self.random, n) end
@@ -1597,9 +1619,25 @@ function Battle:useMove(attacker, defender, moveId)
     return
   end
 
-  -- Damage that skips the formula entirely.
-  local fixed = Effects.fixedDamage(def.effect, attacker, defender, self.random)
+  -- Damage that skips the formula entirely.  The move's own power goes with
+  -- it: EFFECT_STATIC_DAMAGE's arm of BattleCommand_ConstantDamage reads
+  -- BATTLE_VARS_MOVE_POWER as the damage (effect_commands.asm:3157-3161).
+  local fixed = Effects.fixedDamage(def.effect, attacker, defender, self.random,
+    def.power)
   if fixed then
+    -- The constant-damage effect list carries `resettypematchup` instead of
+    -- `stab`, and that command misses the move outright when the matchup byte
+    -- is 0 (effect_commands.asm:1480-1493) -- an immune target is the one
+    -- thing that stops SONIC BOOM, NIGHT SHADE or SUPER FANG.
+    local defenderTypes = (self:speciesDef(defender) or {}).types
+      or defender.types
+    local matchups = self.data.type_chart and self.data.type_chart.matchups
+    if Damage.typeMultiplier(def.type, defenderTypes, matchups) == 0 then
+      self:markMissed()
+      self:emit({ kind = "message",
+        text = "It doesn't affect " .. self:monName(defender) .. "..." })
+      return
+    end
     self:dealDamage(attacker, defender, fixed, { move = def, moveId = moveId })
     return
   end
@@ -1655,7 +1693,7 @@ function Battle:useMove(attacker, defender, moveId)
       state.rolloutLock = nil
     end
 
-    local hits = Effects.hitCount(def.effect, self.random)
+    local hits = Effects.hitCount(def.effect, self:roller())
     local landed = 0
     for hit = 1, hits do
       if (defender.hp or 0) <= 0 then break end
@@ -3178,7 +3216,8 @@ function Battle:giveExperiencePass(loser, def, recipients, count, halved)
         -- ChangeHappiness is outside the level loop.
         Happiness.change(mon, "GAINLEVEL")
         self:emit({ kind = "level", index = index, level = mon.level,
-          text = self:monName(mon) .. " grew to level " .. mon.level .. "!" })
+          text = self:monName(mon) .. " grew to level " .. mon.level .. "!",
+          sfx = "Sfx_DexFanfare5079", waitSfx = true })
         for _, moveId in ipairs(result.learned) do
           local ok, reason, entry = Mon.learnMove(mon, moveId, self.data)
           local moveDef = self:moveDef(moveId)
@@ -3644,7 +3683,7 @@ end
 -- Running: Gen 2's odds (engine/battle/core.asm TryToRunAwayFromBattle) are
 -- based on the speed ratio and how many times you have tried this battle.
 -- Trainers never let you run.
-function Battle:tryRun()
+function Battle:tryRun(pSpd)
   -- .cant_escape and .cant_run_from_trainer leave wBattlePlayerAction alone,
   -- which is what BattleMenu_Run reads to decide whether the turn was spent
   -- (engine/battle/core.asm:5035); only .cant_escape_2, the failed roll at the
@@ -3676,7 +3715,8 @@ function Battle:tryRun()
     return false
   end
   self.runAttempts = (self.runAttempts or 0) + 1
-  if self:runRoll(self:effectiveSpeed(self.player),
+  -- engine/battle/core.asm:2614
+  if self:runRoll(pSpd or self:effectiveSpeed(self.player),
       self:effectiveSpeed(self.enemy)) then
     self:emit({ kind = "run", text = "Got away safely!" })
     self:endBattle("run")

src/battle/gen2/Effects.lua

@@ -100,21 +100,28 @@ end
 -- are 1/8 each, which is what the `and 3` on a 0-3 roll plus the two-step
 -- fallthrough in .DetermineNumberOfHits produces.
 function Effects.multiHitCount(random)
-  local roll = random and random(4) or 0
-  if roll < 2 then return roll + 2 end
-  -- Hits 4 and 5 take a second roll, so each ends up half as likely.
-  local second = random and random(2) or 0
-  return second + 4
+  local function roll(n)
+    if random then return random(n) end
+    if love and love.math and love.math.random then
+      return love.math.random(n) - 1
+    end
+    return math.random(n) - 1
+  end
+  -- engine/battle/effect_commands.asm:5228
+  local first = roll(4)
+  if first < 2 then return first + 2 end
+  return roll(4) + 2
 end
 
 Effects.HIT_COUNTS = {
   EFFECT_DOUBLE_HIT = 2,
+  EFFECT_POISON_MULTI_HIT = 2,
   -- Triple Kick stops early if a hit misses; Battle rolls that per hit.
   EFFECT_TRIPLE_KICK = 3,
 }
 
 function Effects.hitCount(effect, random)
-  if effect == "EFFECT_MULTI_HIT" or effect == "EFFECT_POISON_MULTI_HIT" then
+  if effect == "EFFECT_MULTI_HIT" then
     return Effects.multiHitCount(random)
   end
   return Effects.HIT_COUNTS[effect] or 1
@@ -172,9 +179,9 @@ end
 
 -- --------------------------------------------------------------- fixed damage
 
--- BattleCommand_LevelDamage / SuperFang / Psywave, all of which skip the
--- damage formula entirely.
-function Effects.fixedDamage(effect, attacker, defender, random)
+-- BattleCommand_ConstantDamage (engine/battle/effect_commands.asm:3131-3205),
+-- one command for the whole SuperFang / Psywave / StaticDamage list.
+function Effects.fixedDamage(effect, attacker, defender, random, power)
   if effect == "EFFECT_LEVEL_DAMAGE" then
     return math.max(1, attacker.level or 1)
   end
@@ -182,9 +189,17 @@ function Effects.fixedDamage(effect, attacker, defender, random)
     return math.max(1, math.floor((defender.hp or 1) / 2))
   end
   if effect == "EFFECT_PSYWAVE" then
-    -- 1..(level * 1.5), rerolled until it is in range; one roll is enough here.
-    local ceiling = math.max(1, math.floor((attacker.level or 1) * 3 / 2))
-    return math.max(1, (random and random(ceiling) or 0) + 1)
+    -- .psywave rerolls until the byte is nonzero AND below level * 1.5, so the
+    -- top of the range is that ceiling minus one (effect_commands.asm:3163).
+    local ceiling = math.max(2, math.floor((attacker.level or 1) * 3 / 2))
+    return math.max(1, (random and random(ceiling - 1) or 0) + 1)
+  end
+  -- SONIC BOOM and DRAGON RAGE share EFFECT_STATIC_DAMAGE, whose arm reads
+  -- BATTLE_VARS_MOVE_POWER straight into the damage word: their stored power
+  -- (20 and 40) IS the damage, never a formula input
+  -- (effect_commands.asm:3157-3161).
+  if effect == "EFFECT_STATIC_DAMAGE" then
+    return math.max(1, math.floor(power or 0))
   end
   return nil
 end
@@ -250,8 +265,18 @@ Effects.MAGNITUDE_POWER = {
 -- is what damagecalc reads as the move's power -- data/moves/moves.asm stores
 -- MAGNITUDE at power 1 precisely because this overwrites it.  Returns the
 -- power and the magnitude number the text prints.
+--
+-- `random` is BattleRandom (0..n-1).  If none is supplied, roll via love.math
+-- / math.random — never hard-code 0 (that always yields Magnitude 4).
 function Effects.magnitudePower(random)
-  local roll = random and random(256) or 0
+  local roll
+  if type(random) == "function" then
+    roll = random(256) or 0
+  elseif love and love.math and love.math.random then
+    roll = love.math.random(256) - 1
+  else
+    roll = math.random(256) - 1
+  end
   for _, row in ipairs(Effects.MAGNITUDE_POWER) do
     if row[1] >= roll then return row[2], row[3] end
   end

src/battle/gen2/Mon.lua

@@ -68,7 +68,16 @@ function Mon.stats(baseStats, dvs, level, statExp)
   baseStats = baseStats or {}
   dvs = dvs or {}
   statExp = statExp or {}
-  local hpDv = dvs.hp or Mon.hpDV(dvs)
+  -- engine/pokemon/move_mon.asm:1540
+  local specialDv = dvs.special
+  if specialDv == nil then
+    specialDv = dvs.specialAttack or dvs.specialDefense
+  end
+  -- engine/pokemon/move_mon.asm:1496
+  local hpDv = Mon.hpDV({
+    attack = dvs.attack, defense = dvs.defense,
+    speed = dvs.speed, special = specialDv,
+  })
   local hp = math.floor((((baseStats.hp or 1) * 2 + hpDv * 2
     + math.floor(math.sqrt(statExp.hp or 0) / 4)) * level) / 100)
     + level + 10
@@ -82,13 +91,27 @@ function Mon.stats(baseStats, dvs, level, statExp)
     -- box_struct ends them at SpcExp), so SpA and SpD grow together.  The
     -- per-stat keys are still read as a fallback for a record written before
     -- the shared word existed.
-    specialAttack = statValue(baseStats.specialAttack, dvs.special, level,
+    specialAttack = statValue(baseStats.specialAttack, specialDv, level,
       statExp.special or statExp.specialAttack),
-    specialDefense = statValue(baseStats.specialDefense, dvs.special, level,
+    specialDefense = statValue(baseStats.specialDefense, specialDv, level,
       statExp.special or statExp.specialDefense),
   }
 end
 
+function Mon.refreshStats(mon, data)
+  if type(mon) ~= "table" then return mon end
+  local def = data and data.pokemon and data.pokemon[mon.species]
+  if not (def and def.baseStats) then return mon end
+  -- engine/pokemon/move_mon.asm:1402
+  local stats = Mon.stats(def.baseStats, mon.dvs, mon.level or 1, mon.statExp)
+  mon.stats = stats
+  mon.maxHp = stats.hp
+  if mon.hp == nil or mon.hp > stats.hp then
+    mon.hp = stats.hp
+  end
+  return mon
+end
+
 -- The five stat exp words, in struct order.  There is no sixth: see Mon.stats.
 Mon.STAT_EXP_ORDER = { "hp", "attack", "defense", "speed", "special" }
 

src/core/BattleCheckpoint.lua

@@ -334,6 +334,12 @@ function BattleCheckpoint.restore(game, checkpoint, copy)
     battle.player.mon.hp, battle.player.mon.status
   battle.enemy.shownHP, battle.enemy.shownStatus =
     battle.enemy.mon.hp, battle.enemy.mon.status
+  -- the bar's own pixel length is derived HUD state, not captured: it
+  -- settles with shownHP above (UpdateHPBar_AnimateHPBar's end position)
+  local Timing = require("src.core.Timing")
+  for _, b in ipairs({ battle.player, battle.enemy }) do
+    b.shownPx = Timing.hpBarPixels(b.mon.hp, math.max(1, b.mon.stats.hp))
+  end
 
   local ow = game.overworld
   if not ow or type(ow.restoreBattleContinuation) ~= "function"

src/core/Checkpoint.lua

@@ -7,6 +7,7 @@ local Version = require("src.core.Version")
 local BattleState = require("src.battle.BattleState")
 local BattleCheckpoint = require("src.core.BattleCheckpoint")
 local ModRuntime = require("src.mods.Runtime")
+local BattleSafety = require("src.battle.BattleSafety")
 
 local Checkpoint = {}
 
@@ -36,72 +37,9 @@ local function scriptsBusy(ow)
     or nonempty(ow.scriptMoves)
 end
 
-local BATTLE_BUSY_FIELDS = {
-  "current", "afterQueue", "nextInsert", "pendingHit", "waitingUI",
-  "waitingSound", "waitFrames", "draining", "animPlaying", "growIn",
-  "introSlide", "ghostReveal", "mimicCtx", "mimicMoves", "result",
-}
-
-local function inspectBattle(ow, battle)
-  if battle.kind == "link" then
-    return refusal("battle", "link_battle_unsupported",
-      "Network battles cannot be checkpointed.")
-  end
-  if battle.safari or battle.ghost or battle.scopeReveal or battle.demo
-      or battle.noCatch then
-    return refusal("battle", "battle_variant_unsupported",
-      "This battle variant does not have a checkpoint contract.")
-  end
-  if battle.kind ~= "wild" and battle.kind ~= "trainer" then
-    return refusal("battle", "battle_variant_unsupported",
-      "This battle kind does not have a checkpoint contract.")
-  end
-  local origin = battle.checkpointOrigin
-  local ordinaryOrigin = battle.kind == "wild" and "wild_encounter"
-    or "trainer_encounter"
-  local scriptedOrigin = type(origin) == "table"
-    and origin.kind == "script_battle"
-  if type(origin) ~= "table"
-      or (origin.kind ~= ordinaryOrigin and not scriptedOrigin) then
-    return refusal("battle", "battle_origin_unsupported",
-      "The battle completion path cannot be reconstructed safely.")
-  end
-  local scriptedRunner = scriptedOrigin and (battle.checkpointScriptContinuation
-    or (ow.runner
-    and ow.runner.isCheckpointBattle
-    and ow.runner:isCheckpointBattle(battle)))
-  local otherScriptWork = nonempty(ow.parallelRunners)
-    or nonempty(ow.pendingScripts) or nonempty(ow.parallelQueue)
-    or nonempty(ow.scriptMoves)
-  if (scriptedOrigin and (not scriptedRunner or otherScriptWork))
-      or (not scriptedOrigin and scriptsBusy(ow)) then
-    return refusal("battle", "script_busy",
-      "A suspended or queued script cannot be checkpointed.")
-  end
-  if battle.phase ~= "menu" or nonempty(battle.queue) then
-    return refusal("battle", "battle_phase_busy",
-      "Wait for the player command menu before creating a checkpoint.")
-  end
-  for _, field in ipairs(BATTLE_BUSY_FIELDS) do
-    if battle[field] ~= nil and battle[field] ~= false then
-      return refusal("battle", "battle_phase_busy",
-        "Wait for the current battle action to finish.")
-    end
-  end
-  if not battle.player or not battle.enemy or battle.player.mon.hp <= 0
-      or (battle.menuLockedAction and battle:menuLockedAction(battle.player)) then
-    return refusal("battle", "battle_phase_busy",
-      "Wait for an ordinary player decision before creating a checkpoint.")
-  end
-  for _, battler in ipairs({ battle.player, battle.enemy }) do
-    if battler.shownHP ~= battler.mon.hp
-        or battler.shownStatus ~= battler.mon.status
-        or battler.drainFloor ~= nil or battler.drainHold ~= nil
-        or battler.faintQueued then
-      return refusal("battle", "battle_phase_busy",
-        "Wait for battle status and HP presentation to settle.")
-    end
-  end
+local function inspectBattle(game, battle)
+  local allowed, reason, message = BattleSafety.inspect(game, battle)
+  if not allowed then return refusal("battle", reason, message) end
   return { canCapture = true, canRestore = true, kind = "battle" }
 end
 
@@ -120,7 +58,7 @@ function Checkpoint.inspect(game)
   end
   local top = game.stack and game.stack.top and game.stack:top()
   if getmetatable(top) == BattleState then
-    return inspectBattle(ow, top)
+    return inspectBattle(game, top)
   end
   if top ~= ow then
     return refusal("overworld", "screen_busy",
@@ -375,6 +313,16 @@ local function equalData(a, b)
   return okA and okB and encodedA == encodedB
 end
 
+local function normalizeVerificationMetadata(actual, expected)
+  if type(actual) == "table" and type(actual.identity) == "table"
+      and type(expected) == "table" and type(expected.identity) == "table" then
+    -- RFC 0004 treats engineVersion as compatibility metadata, not runtime
+    -- state. A fresh recapture stamps the running engine, so normalize only
+    -- that metadata before differential verification.
+    actual.identity.engineVersion = expected.identity.engineVersion
+  end
+end
+
 local function firstDifference(a, b, path)
   path = path or "$"
   if type(a) ~= type(b) then return path .. " (type)" end
@@ -456,6 +404,7 @@ function Checkpoint.restore(game, checkpoint)
   if ok then
     local restored, verifyCode = Checkpoint.capture(game)
     if restored and validated.rng == nil then restored.rng = nil end
+    normalizeVerificationMetadata(restored, validated)
     if restored and equalData(restored, validated) then
       emitRestored(game, validated)
       return true
@@ -536,6 +485,7 @@ function Checkpoint.resume(game, checkpoint)
   if ok then
     local restored, verifyCode = Checkpoint.capture(game)
     if restored and validated.rng == nil then restored.rng = nil end
+    normalizeVerificationMetadata(restored, validated)
     if restored and equalData(restored, validated) then
       emitRestored(game, validated)
       return true

src/core/ChipSynth.lua

@@ -1230,8 +1230,17 @@ function Engine.new(data, header, options)
     engine.tempo = header.tempo
     engine.tempoLocked = true
   end
-  for _, spec in ipairs(chip and chip.channels
-      or headerChannels(banks, header)) do
+  local channels = chip and chip.channels or headerChannels(banks, header)
+  if header.startChannels then
+    local byNumber = {}
+    for _, start in ipairs(header.startChannels) do
+      byNumber[start.number] = start.address
+    end
+    for _, spec in ipairs(channels) do
+      spec.address = byNumber[spec.number] or spec.address
+    end
+  end
+  for _, spec in ipairs(channels) do
     local frameTicks = options.frameTicks
     local hardware = (spec.number - 1) % 4 + 1
     if hardware == 4 then

src/core/Game.lua

@@ -159,14 +159,15 @@ function Game:makeTitleState()
       self:applyOptions(self.save.options)
       self.stack:push(OverworldState, self.save.player.map,
                       self.save.player.x, self.save.player.y,
-                      self.save.player.facing)
+                      self.save.player.facing,
+                      { via = "boot", freshBoot = true })
       Screens.push(self, bootScreens(self).newGame or "OakSpeech",
                    function() end)
     end,
     onContinue = function()
       local loaded, recovered = SaveData.load()
       if loaded then
-        self:restoreSave(loaded, recovered)
+        self:restoreSave(loaded, recovered, { freshBoot = true })
       end
     end,
   })
@@ -639,7 +640,12 @@ function Game:keypressed(key)
     return
   elseif key == "f2" then
     local loaded, recovered = SaveData.load()
-    if loaded then self:restoreSave(loaded, recovered) end
+    if loaded then
+      -- F2 jumps straight to the loaded save's map/position, with no
+      -- walking transition -- a hard state teleport like Continue, not a
+      -- smooth warp -- whether pressed at the title screen or mid-session.
+      self:restoreSave(loaded, recovered, { freshBoot = true })
+    end
     return
   elseif key == "-" then
     self:zoomStep(-1)
@@ -1124,7 +1130,7 @@ function Game:applyOptions(opts)
   if gbcCleared then self:writeOptions() end
 end
 
-function Game:restoreSave(loaded, recovered)
+function Game:restoreSave(loaded, recovered, opts)
   if ModRuntime.wants("save.loading") then
     ModRuntime.emit("save.loading", { raw = loaded })
   end
@@ -1157,8 +1163,12 @@ function Game:restoreSave(loaded, recovered)
   end
   -- rebuild the state stack from the save
   while self.stack:top() do self.stack:pop() end
+  -- freshBoot threads through from the caller (onContinue and F2 both set
+  -- it); a future caller that doesn't ask for it keeps the ordinary
+  -- crossfade by default.
   self.stack:push(self.overworld, loaded.player.map,
-                  loaded.player.x, loaded.player.y, loaded.player.facing)
+                  loaded.player.x, loaded.player.y, loaded.player.facing,
+                  { via = "boot", freshBoot = opts and opts.freshBoot })
   self.saveReport = report
   if not SaveData.emptyReport(report) then
     -- the report screen is a Screens id so mods (or the ui milestone) own
@@ -1187,9 +1197,12 @@ function Game:restoreCheckpointSave(loaded)
   self.save = loaded
   self:adoptSave(loaded)
   while self.stack:top() do self.stack:pop() end
+  -- freshBoot unconditionally: Checkpoint.resume (src/core/Checkpoint.lua)
+  -- is this method's only caller, and it is itself gated to the title
+  -- session (isTitleSession).
   self.stack:push(self.overworld, loaded.player.map,
                   loaded.player.x, loaded.player.y, loaded.player.facing,
-                  { via = "checkpoint", checkpoint = true })
+                  { via = "checkpoint", checkpoint = true, freshBoot = true })
 end
 
 -- Install a reconstructed battle without calling BattleState:enter(), whose

src/core/Game2.lua

@@ -73,7 +73,7 @@ end
 --
 -- Gold composites its own frame (Game2:draw / drawScene) and pumps its own pad
 -- (the FixedStep callback in Game2:load), so none of it goes through
--- src/render/Renderer.lua or src/core/Game.lua.  That explains why the six
+-- src/render/Renderer.lua or src/core/Game.lua.  That explains why the eight
 -- hooks below never used to fire here; it is not a reason they should not.  A
 -- hook is a contract about a MOMENT in the frame, and Gold has every one of
 -- these moments -- so each is raised under the Gen 1 NAME with the Gen 1
@@ -83,6 +83,7 @@ end
 --   input.pointer    uncaptured pointer events       (src/core/Game.lua:887)
 --   render.zones     the palette pass, pre-blit      (src/core/Game.lua:505)
 --   render.compose   the whole-window composite      (Renderer.lua:759)
+--   render.output*   the normal composed frame       (Renderer.lua:1063)
 --   render.letterbox the void around the 160x144 blit (Renderer.lua:840)
 --   render.hud       screen-space UI over the frame  (src/core/Game.lua:521)
 --
@@ -109,6 +110,12 @@ local function makeStack()
   return StateStack
 end
 
+local function visibleBaseState(stack)
+  if not stack then return nil end
+  local state = stack.states[stack:visibleBase()]
+  return stack:renderVisible(state) and state or nil
+end
+
 local function loadGenerated(path)
   local chunk = love.filesystem.load(path)
   if not chunk then return nil end
@@ -683,10 +690,26 @@ function Game2:usePartyItem(itemId)
       self:say(result.text)
       return
     end
-    self:consumeItem(itemId)
-    if action == "candy" then
+    if action == "stone" then
+      local party = (self.save and self.save.party) or {}
+      local index
+      for i, member in ipairs(party) do
+        if member == mon then index = i break end
+      end
+      Screens.push(self, "Gen2EvolutionAnim", {
+        mon = mon, entry = result.evolution, index = index,
+        party = party, save = self.save,
+        force = true,
+        onDone = function(evolution)
+          if evolution and evolution.evolved then self:consumeItem(itemId) end
+          self.stack:pop()
+        end,
+      })
+    elseif action == "candy" then
+      self:consumeItem(itemId)
       self:say(result.text, function() self:afterRareCandy(mon, result) end)
     else
+      self:consumeItem(itemId)
       self:say(result.text)
     end
   end
@@ -1360,12 +1383,14 @@ function Game2:draw()
   local zoned = type(zones) == "table" and zones[1] ~= nil
 
   -- A present canvas is paid for only when something reads it: the zone pass,
-  -- GBC FX, a mod post-process, or a render.compose subscriber about to be
-  -- handed the finished frame.  With none of them the frame draws straight to
-  -- the screen exactly as it always did.
+  -- GBC FX, a mod post-process, render.compose, or an enabled render.output
+  -- subscriber. With none of them the frame draws straight to the screen
+  -- exactly as it always did.
   local composing = ModRuntime.wantsHook("render.compose")
+  local hasOutputHook = ModRuntime.wantsHook("render.output")
+    and ModRuntime.call("render.output_enabled", function() return false end) == true
   local scene = nil
-  if zoned or fx or composing or Pipelines.wantsPresent() then
+  if zoned or fx or composing or Pipelines.wantsPresent() or hasOutputHook then
     scene = self:presentCanvas(1, w, h)
   end
   if not scene then
@@ -1397,7 +1422,7 @@ function Game2:draw()
   -- untinted one.  On its own the tint rides the final blit and no second
   -- canvas is paid for.
   local source = scene
-  local reread = fx or Pipelines.wantsPresent()
+  local reread = fx or Pipelines.wantsPresent() or hasOutputHook
   if zoned and reread then
     local tinted = self:presentCanvas(2, w, h)
     if tinted then
@@ -1417,15 +1442,25 @@ function Game2:draw()
     -- Post-process pipelines run over the finished composite and before GBC
     -- FX.  Each hands back a canvas; with none registered this returns `source`
     -- unchanged and the frame is byte-identical (Renderer.lua:1058).
-    local scale, _, _, dpi = self:frameFit(w, h)
+    local scale, ox, oy, dpi = self:frameFit(w, h)
     source = Pipelines.present(source, { width = w, height = h, scale = scale,
       dpi = dpi, dpiX = dpi, dpiY = dpi }) or source
-    if fx then
-      GBCFX.present(source, self:pixelScale(w, h))
-    else
-      G.setColor(1, 1, 1, 1)
-      G.draw(source, 0, 0)
-      G.setShader()
+    local outputHandled = hasOutputHook
+      and ModRuntime.call("render.output", function() return false end, {
+        canvas = source, width = w, height = h,
+        gameX = ox, gameY = oy,
+        gameWidth = 160 * scale, gameHeight = 144 * scale,
+        scale = scale, dpiX = dpi, dpiY = dpi,
+        generation = 2,
+      }) == true
+    if not outputHandled then
+      if fx then
+        GBCFX.present(source, self:pixelScale(w, h))
+      else
+        G.setColor(1, 1, 1, 1)
+        G.draw(source, 0, 0)
+        G.setShader()
+      end
     end
   end
   G.pop()
@@ -1441,8 +1476,7 @@ end
 -- them but the Pokegear, whose paper is RGB 28,31,20.  Nil means white, which
 -- is what Font.drawBox does by default.
 function Game2:textboxPaper()
-  local base = self.stack and self.stack.states
-    and self.stack.states[self.stack:visibleBase()]
+  local base = visibleBaseState(self.stack)
   if base and base.paperColor then return base:paperColor() end
   return nil
 end
@@ -1455,10 +1489,11 @@ function Game2:drawScene(w, h)
 
   if self:inFillBoot() then
     local top = self.stack:top()
-    local base = self.stack.states[self.stack:visibleBase()]
+    local base = visibleBaseState(self.stack)
     -- Title (and friends) paint sky/clouds edge-to-edge; Oak speech and
     -- name pick paint a paper-white surround via drawWidescreen.
-    local wide = (top and top.drawsWidescreen and top:drawsWidescreen()
+    local wide = (self.stack:renderVisible(top)
+      and top.drawsWidescreen and top:drawsWidescreen()
       and top.drawWidescreen) and top
       or (base and base.drawsWidescreen and base:drawsWidescreen()
         and base.drawWidescreen and base)
@@ -1507,8 +1542,9 @@ function Game2:drawScene(w, h)
     -- PARTY, PACK, #DEX, PC, DAY-CARE, MAILBOX and TRADE screens whenever a
     -- TextBox goes up over them.
     local top = self.stack:top()
-    local base = self.stack.states[self.stack:visibleBase()]
-    local wide = (top and top.drawsWidescreen and top:drawsWidescreen()
+    local base = visibleBaseState(self.stack)
+    local wide = (self.stack:renderVisible(top)
+      and top.drawsWidescreen and top:drawsWidescreen()
       and top.drawWidescreen) and top
       or (base and base.drawsWidescreen and base:drawsWidescreen()
         and base.drawWidescreen and base)
@@ -1906,11 +1942,10 @@ function Game2:applyOptions()
   require("src.render.Pipelines").applyOptions(options)
   -- src/core/Game.lua:1121 mirrors this call for Gen 1
   Input:applyBindings(options.bindings)
-  -- options.touchControls (the launcher editor's per-orientation layouts) and
-  -- options.haptics, the same two keys Gen 1 hands over here
-  -- (src/core/Game.lua:1073).  One options.lua serves both games, so the pad a
-  -- player laid out for Red is already the pad Gold draws.
-  TouchControls:applyOptions(options)
+  TouchControls:applyOptions({
+    touchControls = options.touchControls,
+    haptics = options.haptics,
+  })
   local GBCFX = require("src.render.GBCFX")
   if GBCFX.applyOptions(options) and self.save then
     -- applyOptions returns true when it had to clear an unsupported level.

src/core/HostDisplay.lua

@@ -0,0 +1,41 @@
+-- Optional native-host display lifecycle.
+--
+-- The engine always owns simulation and drawing. A packaged host may install
+-- one backend to observe per-frame updates and prepare/finalize a render target
+-- around an otherwise unchanged draw. With no backend installed every method
+-- is a no-op, which is the normal desktop and mobile path.
+--
+-- Backend methods are optional:
+--   backend:update(dt)
+--   backend:beginFrame(kind, subject)
+--   backend:endFrame(kind, subject)
+--
+-- `kind` is "editor", "touch_editor", "launcher", or "game". `subject` is
+-- the object whose existing draw method runs between beginFrame and endFrame.
+local HostDisplay = {}
+
+local backend
+
+function HostDisplay.setBackend(value)
+  if value ~= nil and type(value) ~= "table" then
+    error("host display backend must be a table or nil", 2)
+  end
+  backend = value
+end
+
+function HostDisplay.update(dt)
+  local fn = backend and backend.update
+  if fn then return fn(backend, dt) end
+end
+
+function HostDisplay.beginFrame(kind, subject)
+  local fn = backend and backend.beginFrame
+  if fn then return fn(backend, kind, subject) end
+end
+
+function HostDisplay.endFrame(kind, subject)
+  local fn = backend and backend.endFrame
+  if fn then return fn(backend, kind, subject) end
+end
+
+return HostDisplay

src/core/Input.lua

@@ -119,6 +119,34 @@ function Input:reset()
   self.stickAxis = { x = 0, y = 0 }
   self.stickDir = nil
   self.hatDirs = {}
+  self.captureArmed = false
+  self.captureEvents = nil
+end
+
+function Input:armCapture()
+  self.captureArmed = true
+  self.captureEvents = {}
+end
+
+function Input:disarmCapture()
+  self.captureArmed = false
+  self.captureEvents = nil
+end
+
+function Input:takeCaptureEvents()
+  local ev = self.captureEvents
+  self.captureEvents = self.captureArmed and {} or nil
+  return ev
+end
+
+local function noteCapture(self, kind, phase, value)
+  if not self.captureArmed then return end
+  local ev = self.captureEvents
+  if not ev then
+    ev = {}
+    self.captureEvents = ev
+  end
+  ev[#ev + 1] = { kind = kind, phase = phase, value = value }
 end
 
 -- Multiple physical sources (W + Up, d-pad + stick, etc.) can claim the
@@ -154,6 +182,7 @@ local function release(self, btn, source)
 end
 
 function Input:keypressed(key)
+  noteCapture(self, "key", "pressed", key)
   local btn = self.keyBindings[key]
   if btn then
     press(self, btn, "key:" .. key)
@@ -161,6 +190,7 @@ function Input:keypressed(key)
 end
 
 function Input:keyreleased(key)
+  noteCapture(self, "key", "released", key)
   local btn = self.keyBindings[key]
   if btn then
     release(self, btn, "key:" .. key)
@@ -221,6 +251,7 @@ function Input:sourceRelease(btn, source)
 end
 
 function Input:gamepadpressed(joystick, button)
+  noteCapture(self, "pad", "pressed", button)
   local btn = self.padBindings[button]
   if btn then
     press(self, btn, "pad:" .. button)
@@ -228,6 +259,7 @@ function Input:gamepadpressed(joystick, button)
 end
 
 function Input:gamepadreleased(joystick, button)
+  noteCapture(self, "pad", "released", button)
   local btn = self.padBindings[button]
   if btn then
     release(self, btn, "pad:" .. button)
@@ -249,12 +281,14 @@ end
 
 function Input:joystickpressed(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  noteCapture(self, "joy", "pressed", button)
   local btn = self.joyBindings[button]
   if btn then press(self, btn, "joy:" .. button) end
 end
 
 function Input:joystickreleased(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  noteCapture(self, "joy", "released", button)
   local btn = self.joyBindings[button]
   if btn then release(self, btn, "joy:" .. button) end
 end

src/core/Music.lua

@@ -64,6 +64,7 @@ state = {
   fanfareResume = false, -- start/resume state.source when the fanfare ends
   fade = nil,         -- active volume-ramp fade-out (see Music.fadeOut)
   tempo = nil,        -- alternate-tempo override in force for `current`
+  start = nil,
   failed = {},        -- labels whose def could not be started; logged once
 }
 
@@ -215,9 +216,11 @@ function Music.play(data, song, loop, ctx)
   song = selectSong(song, ctx)
 
   local tempo = ctx and ctx.tempo or nil
+  local start = ctx and ctx.start or nil
   -- a hook may silence the cue outright, or swap in a label the dedupe
   -- below has to compare against
-  if not song or (song == state.current and tempo == state.tempo) then return end
+  if not song or (song == state.current and tempo == state.tempo
+      and start == state.start) then return end
   local def = songDef(data, song)
   if not def or state.failed[song] then return end
 
@@ -240,6 +243,17 @@ function Music.play(data, song, loop, ctx)
     slowed.tempo = tempo
     def = slowed
   end
+  if start == "rival" and song == "Music_MeetRival"
+     and def.bank == 2 and def.address == 17050 then
+    local started = {}
+    for key, value in pairs(def) do started[key] = value end
+    started.startChannels = {
+      { number = 1, address = 0x71a2 },
+      { number = 2, address = 0x721d },
+      { number = 3, address = 0x72b5 },
+    }
+    def = started
+  end
   local wantLoop = loop ~= false
   local src, loopSrc, isChip, err = startSong(data, def, wantLoop)
   if not src then
@@ -276,6 +290,7 @@ function Music.play(data, song, loop, ctx)
   state.source, state.loopSource, state.chip = src, loopSrc, isChip
   state.current = song
   state.tempo = tempo
+  state.start = start
   if Runtime.wants("music.started") then
     Runtime.emit("music.started", {
       song = song, previous = previous, chip = isChip,
@@ -290,7 +305,7 @@ function Music.stop()
   stopSource(state.loopSource)
   require("src.core.ChipAudio").stopMusic()
   state.current, state.source, state.loopSource, state.fade = nil, nil, nil, nil
-  state.tempo = nil
+  state.tempo, state.start = nil, nil
   state.chip = false
   state.pendingRestore = nil
   if previous and Runtime.wants("music.stopped") then

src/core/RomText.lua

@@ -33,6 +33,14 @@ return function(data, label, fallback, ...)
   local args = { ... }
   if #args == 0 then return text end
 
+  if #args == 1 and type(args[1]) == "table" then
+    local values = args[1]
+    return (text:gsub("%b{}", function(token)
+      local value = values[token] or values[token:sub(2, -2)]
+      return value == nil and token or tostring(value)
+    end))
+  end
+
   local slots, named = 0, 0
   for token in text:gmatch("%b{}") do
     slots = slots + 1

src/core/SaveData.lua

@@ -304,6 +304,10 @@ function SaveData.defaultOptions()
     -- options.lua written before this key keeps its exact meaning.  Read and
     -- written through SaveData.modEnabled / SaveData.setModEnabled.
     modsByVersion = {},
+    -- Set after the first per-game enablement migration.  Older options files
+    -- have only `mods`, so the migration copies each installed mod's current
+    -- answer to every game before game-specific toggles begin changing it.
+    modsByVersionMigrated = false,
     -- Named setups the player can switch between (#593; src/mods/ModProfile.lua
     -- owns the shape, src/mods/ManagerState.lua the UI): each row is
     -- { name, enabled = {id=bool}, options = {id={k=v}}, slots = {version=slotId} }.
@@ -335,11 +339,11 @@ function SaveData.defaultOptions()
     -- TouchControls.normalizeConfig folds it into both orientations on load.
     touchControls = { enabled = true },
     -- Haptic feedback level for on-screen pad presses (#806):
-    -- off | light | medium | heavy, mapped to a love.system.vibrate
-    -- duration in src/core/TouchControls.lua.  LIGHT by default, like the
-    -- overlay itself defaulting on, so an options.lua predating this key
-    -- gets the tick without going looking for the row.  Inert wherever the
-    -- overlay never appears (desktop) or LOVE has no vibrator.
+    -- off | light | normal | strong, mapped to a love.system.vibrate duration
+    -- in src/core/TouchControls.lua.  LIGHT by default, so an options.lua
+    -- predating this key gets the tick without going looking for the row.
+    -- Inert wherever the overlay never appears (desktop) or LOVE has no
+    -- vibrator.
     haptics = "light",
     -- Shared UI/mod timestamp presentation. DEVICE follows the process time
     -- locale where the platform exposes one; otherwise DateTime falls back to
@@ -563,19 +567,68 @@ end
 -- only holds the games the player actually chose for, so a mod set can differ
 -- between Red and Gold without either one owning the other's flags.
 
--- Whether a per-game answer is honoured at boot.  The loader reads the enable
--- flags once, before any entry chunk (src/mods/Loader.lua _loadState), so this
--- flips on with that read and not before: until then every writer keeps to the
--- shared flag and no surface promises what the boot does not do.
-SaveData.PER_VERSION_MODS = false
+-- Per-game answers are live.  Every reader and writer goes through modScope,
+-- so a choice made in the launcher is the choice the next boot loads.
+SaveData.PER_VERSION_MODS = true
 
--- The version a write should be scoped to: the game asked for once per-game
--- flags are live, nil (the shared flag) while they are only a preview.
+-- The version a write is scoped to: per-game controls name one game; a nil
+-- caller still addresses the legacy shared fallback.
 function SaveData.modScope(version)
   if SaveData.PER_VERSION_MODS then return version end
   return nil
 end
 
+-- Promote an installation that predates per-game flags.  `mods` may contain
+-- manifest rows ({ id, experimental }) or bare ids.  A mod with no old entry
+-- had the loader default: on, except for experimental mods.  Copy that answer
+-- to every game once, preserving any per-game overlay somebody imported before
+-- this feature shipped.  New installs need no rows here: an absent answer
+-- still defaults to enabled for every game.
+function SaveData.migrateModEnablement(options, mods)
+  if type(options) ~= "table" or options.modsByVersionMigrated then return false end
+  options.mods = type(options.mods) == "table" and options.mods or {}
+  options.modsByVersion = type(options.modsByVersion) == "table"
+    and options.modsByVersion or {}
+
+  local known = {}
+  for id in pairs(options.mods) do
+    if type(id) == "string" and id ~= "" then known[id] = { id = id } end
+  end
+  for version, bucket in pairs(options.modsByVersion) do
+    if GameVersion.VERSIONS[version] and type(bucket) == "table" then
+      for id in pairs(bucket) do
+        if type(id) == "string" and id ~= "" then known[id] = known[id] or { id = id } end
+      end
+    end
+  end
+  for _, mod in ipairs(mods or {}) do
+    local id = type(mod) == "table" and mod.id or mod
+    if type(id) == "string" and id ~= "" then
+      known[id] = type(mod) == "table" and mod or (known[id] or { id = id })
+    end
+  end
+
+  -- Do not create options.lua just to record an empty migration on a fresh
+  -- no-mod boot.  Keep it pending until there is a real installed or saved
+  -- mod answer to preserve.
+  if next(known) == nil then return false end
+
+  for id, mod in pairs(known) do
+    local shared = options.mods[id]
+    if type(shared) ~= "boolean" then shared = not (mod.experimental == true) end
+    for _, version in ipairs(GameVersion.ORDER) do
+      local bucket = options.modsByVersion[version]
+      if type(bucket) ~= "table" then
+        bucket = {}
+        options.modsByVersion[version] = bucket
+      end
+      if type(bucket[id]) ~= "boolean" then bucket[id] = shared end
+    end
+  end
+  options.modsByVersionMigrated = true
+  return true
+end
+
 -- true/false as chosen for `version`, else the shared flag, else nil -- the
 -- caller owns the default (the loader enables, the launcher keeps
 -- experimental mods off until asked).
@@ -818,9 +871,19 @@ end
 function SaveData.slotSummary(save)
   if type(save) ~= "table" then return nil, nil end
   local name = save.player and save.player.name or nil
+  -- A Gen 2 slot carries no badge items and fills pokedex.caught, so both
+  -- counts come off wJohtoBadges/wPokedexCaught (engine/menus/intro_menu.asm:461).
+  local vinfo = type(save.version) == "string" and GameVersion.info(save.version)
+  local gen2 = save.generation == 2 or (vinfo and vinfo.generation == 2) or false
   local dexCount = 0
-  for _ in pairs((save.pokedex and save.pokedex.owned) or {}) do
-    dexCount = dexCount + 1
+  if gen2 then
+    for _, has in pairs((save.pokedex and save.pokedex.caught) or {}) do
+      if has then dexCount = dexCount + 1 end
+    end
+  else
+    for _ in pairs((save.pokedex and save.pokedex.owned) or {}) do
+      dexCount = dexCount + 1
+    end
   end
   -- playTime is a plain seconds count in a Gen 1 save but a
   -- { hours, minutes, seconds, frames } table in a Gen 2 (Gold) save, matching
@@ -838,8 +901,21 @@ function SaveData.slotSummary(save)
   end
   local timeText = ("%d:%02d"):format(math.floor(t / 3600),
                                       math.floor(t / 60) % 60)
+  local badges
+  if gen2 then
+    -- Continue_DisplayBadgeCount walks TWO bytes, Johto then Kanto
+    -- (engine/menus/intro_menu.asm:461-469).
+    badges = 0
+    local p = save.player or {}
+    for _, has in pairs(p.badges or {}) do if has then badges = badges + 1 end end
+    for _, has in pairs(p.kantoBadges or {}) do
+      if has then badges = badges + 1 end
+    end
+  else
+    badges = Badges.count(nil, save)
+  end
   return name, {
-    badges = Badges.count(nil, save),
+    badges = badges,
     timeText = timeText,
     dexCount = dexCount,
   }
@@ -1811,6 +1887,8 @@ function SaveData.newGame(boot)
   boot = type(boot) == "table" and boot or {}
   local map = boot.startMap or "REDS_HOUSE_2F"
   local x, y = boot.startX or 3, boot.startY or 6
+  local facing = boot.startFacing or "down"
+  if map == "REDS_HOUSE_2F" and boot.version ~= "yellow" then facing = "up" end
   local heal = SaveData.defaultHeal(boot)
   local save = {
     meta = { format = Version.saveFormat, mods = {} },
@@ -1821,7 +1899,7 @@ function SaveData.newGame(boot)
       map = map,
       x = x,
       y = y,
-      facing = boot.startFacing or "down",
+      facing = facing,
       name = boot.playerName or "RED",
       rival = boot.rivalName or "BLUE",
       -- 16-bit trainer ID rolled at new game (wPlayerID, filled from

src/core/TouchControls.lua

@@ -105,17 +105,21 @@ end
 -- would be dropped on every editor save.
 -- love.system.vibrate takes a duration and nothing else, so "intensity" is a
 -- duration preset: Android runs the platform vibrator for exactly that long,
--- while iOS ignores the duration and fires the fixed system vibration, so
--- there the three levels all read as simply on.
-TouchControls.HAPTICS = { "off", "light", "medium", "heavy" }
+-- while iOS maps each duration to a matching Taptic Engine impact.
+TouchControls.HAPTICS = { "off", "light", "normal", "strong" }
 TouchControls.HAPTIC_DEFAULT = "light"
 
-local HAPTIC_SECONDS = { off = 0, light = 0.012, medium = 0.025, heavy = 0.045 }
+local HAPTIC_SECONDS = {
+  off = 0, light = 0.012, normal = 0.025, strong = 0.045,
+}
 local HAPTIC_LABELS = {
-  off = "OFF", light = "LIGHT", medium = "MEDIUM", heavy = "HEAVY",
+  off = "OFF", light = "LIGHT", normal = "NORMAL", strong = "STRONG",
 }
 
 function TouchControls.normalizeHaptics(level)
+  if level == "physical" then return "light" end
+  if level == "medium" then return "normal" end
+  if level == "heavy" then return "strong" end
   if HAPTIC_SECONDS[level] then return level end
   return TouchControls.HAPTIC_DEFAULT
 end
@@ -211,6 +215,10 @@ function TouchControls.defaultLayout(ww, wh, ox, oy, scale)
   local abW = dpadW * 0.46
   local ssW = dpadW * 0.30
   local margin = dpadW * 0.12
+  local ok, GameVersion = pcall(require, "src.core.GameVersion")
+  if ok and GameVersion.isGold and GameVersion.isGold() then
+    margin = math.max(margin, math.min(ww * 0.10, 72))
+  end
   return {
     dpad = { cx = ox + margin + dpadW / 2, cy = oy + wh - margin - dpadW / 2, w = dpadW },
     a = { cx = ox + ww - margin - abW * 0.55, cy = oy + wh - margin - abW * 1.75, w = abW },

src/core/Version.lua

@@ -8,6 +8,9 @@ local Version = {
                           -- "-dev" placeholder; CI stamps the real X.Y.Z into
                           -- the packed game.love only, never the working tree.
   shell = 1,              -- native-shell contract this build implements
+  payloadHost = "love",   -- native host family for in-place Lua payloads.
+                          -- A payload must name the same family; this prevents
+                          -- mounting code packaged for a different native host.
   minShell = 1,           -- lowest shell contract that can RUN this payload.
                           -- Bump only when a payload needs a newer native
                           -- binary (e.g. a LOVE version bump); an older shell

src/core/gen2/ItemEffects.lua

@@ -450,6 +450,20 @@ record("RARE_CANDY", "candy", function(ctx)
   return rareCandy(ctx.mon, ctx.data)
 end)
 
+for _, itemId in ipairs({ "SUN_STONE", "MOON_STONE", "FIRE_STONE",
+                          "THUNDERSTONE", "WATER_STONE", "LEAF_STONE" }) do
+  record(itemId, "stone", function(ctx)
+    if ctx.mon.item == "EVERSTONE" then
+      return { used = false, text = ItemEffects.TEXT_NO_EFFECT }
+    end
+    local Evolution = require("src.core.gen2.Evolution")
+    local entry = Evolution.checkMon(ctx.data, ctx.mon,
+      { force = true, item = ctx.item })
+    if not entry then return { used = false, text = ItemEffects.TEXT_NO_EFFECT } end
+    return { used = true, evolution = entry }
+  end)
+end
+
 for itemId in pairs(ItemEffects.REVIVE) do
   record(itemId, "revive", function(ctx) return revive(ctx.item, ctx.mon) end)
 end

src/core/gen2/Save.lua

@@ -275,6 +275,8 @@ Save.DEFAULT_OPTIONS = {
   musicVol = 7,             -- 0-7, like the GB's NR50 master volume
   sfxVol = 7,               -- 0-7
   musicFilter = 0,          -- low-pass steps, 0 = off
+  haptics = "light",
+  touchControls = { enabled = true },
 }
 
 function Save.defaultOptions()
@@ -719,6 +721,13 @@ end
 -- copy is the witness that survives a crash mid-replace.
 function Save.save(save)
   if type(save) ~= "table" then return false, "no save" end
+  if (save.version or "gold") == "gold" then
+    local ok, SaveData = pcall(require, "src.core.SaveData")
+    if ok and SaveData.activeSlot and not SaveData.activeSlot("gold") then
+      local id = SaveData.createSlot and SaveData.createSlot("gold")
+      if id and SaveData.setActiveSlot then SaveData.setActiveSlot("gold", id) end
+    end
+  end
   local main, backup, tmp = saveNames(save.version)
   local f = fs()
   if not f then return false, "no filesystem" end
@@ -755,9 +764,14 @@ end
 function Save.summary(save)
   if type(save) ~= "table" then return nil end
   local badges = 0
+  -- Continue_DisplayBadgeCount counts TWO bytes, wJohtoBadges then wKantoBadges
+  -- (engine/menus/intro_menu.asm:461-469).
   for _, has in pairs(save.player and save.player.badges or {}) do
     if has then badges = badges + 1 end
   end
+  for _, has in pairs(save.player and save.player.kantoBadges or {}) do
+    if has then badges = badges + 1 end
+  end
   local caught = 0
   for _, has in pairs(save.pokedex and save.pokedex.caught or {}) do
     if has then caught = caught + 1 end

src/import/CacheFs.lua

@@ -116,6 +116,8 @@ local physfsMountFn = nil
 local function resolveMount()
   if physfsMountFn ~= nil then return physfsMountFn end
   physfsMountFn = false
+  if Platform.isUWP() then return physfsMountFn end
+  if love and love.filesystem and love.filesystem._mounts then return physfsMountFn end
   local ok, ffi = pcall(require, "ffi")
   if not ok then return physfsMountFn end
   pcall(ffi.cdef,
@@ -159,6 +161,8 @@ local physfsUnmountFn = nil
 local function resolveUnmount()
   if physfsUnmountFn ~= nil then return physfsUnmountFn end
   physfsUnmountFn = false
+  if Platform.isUWP() then return physfsUnmountFn end
+  if love and love.filesystem and love.filesystem._mounts then return physfsUnmountFn end
   local ok, ffi = pcall(require, "ffi")
   if not ok then return physfsUnmountFn end
   pcall(ffi.cdef, "int PHYSFS_unmount(const char *oldDir);")

src/import/LauncherSettings.lua

@@ -62,6 +62,68 @@ local FILTERS = { "OFF", "1X", "2X", "3X" }
 -- The core rows.  Helper modules are required lazily under pcall: they are
 -- pure label/cycle tables, but the launcher must never die because a render
 -- module grew a dependency on live game data.
+-- TOUCH PAD, VIBRATION and the layout editor, shared by both row sets.
+--
+-- Gold reads these out of its own `gold` block (src/core/gen2/Save.lua:297),
+-- so `opts` is whichever table the gear is editing and the rows never have to
+-- know which game they belong to.  #1100 / #1135: the Gold gear carried none
+-- of them, so a phone player could turn the pad and the buzz off in Red and
+-- had no way to reach either in Gold.
+local function addTouchRows(rows, add, opts, hooks)
+  -- TOUCH PAD only where the overlay can appear, mirroring OptionsMenu's
+  -- gate (mobile, or desktop forced by POKEPORT_TOUCH=1).
+  local env = os.getenv("POKEPORT_TOUCH")
+  local osName = love.system and love.system.getOS and love.system.getOS()
+  local show = env == "1"
+    or (env ~= "0" and (osName == "Android" or osName == "iOS"))
+  if show then
+    add(Strings("TOUCH PAD"),
+      function()
+        local tc = opts.touchControls
+        local on = not (type(tc) == "table" and tc.enabled == false)
+        return on and Strings("ON") or Strings("OFF")
+      end,
+      function()
+        local tc = type(opts.touchControls) == "table" and opts.touchControls or {}
+        tc.enabled = tc.enabled == false
+        opts.touchControls = tc
+        return true
+      end)
+    -- VIBRATION sits with it (#806): same gate, same subsystem.  Stepping
+    -- the row buzzes once at the level being selected.
+    local okTC, TC = pcall(require, "src.core.TouchControls")
+    if okTC then
+      add(Strings("VIBRATION"),
+        function() return Strings(TC.hapticLabel(opts.haptics)) end,
+        function(dir)
+          opts.haptics = TC.cycleHaptics(opts.haptics, dir)
+          TC.buzz(opts.haptics)
+          return true
+        end)
+    end
+  end
+
+  -- TOUCH CONTROLS, the on-screen pad's layout editor.  It used to be a
+  -- button on the game panel, once per game -- but the overlay layout is
+  -- global (options.touchControls.layouts), so three tabs offered three
+  -- buttons that edited the same thing while crowding the column that has to
+  -- hold Play.  It belongs with the other control rows, behind the gear.
+  -- The host owns the editor screen, so the row only fires when a hook was
+  -- supplied (the standalone save editor opens this model with none).
+  if hooks and hooks.editTouchControls then
+    rows[#rows + 1] = {
+      label = Strings("TOUCH CONTROLS"),
+      actionLabel = Strings("Edit"),
+      action = function()
+        hooks.editTouchControls()
+        -- The editor replaces the whole screen: nothing left to persist here
+        -- beyond what the caller already saved on the way out.
+        return false
+      end,
+    }
+  end
+end
+
 local function coreRows(opts, hooks)
   local rows = {}
   local function add(label, value, step)
@@ -236,60 +298,7 @@ local function coreRows(opts, hooks)
       end)
   end
 
-  -- TOUCH PAD only where the overlay can appear, mirroring OptionsMenu's
-  -- gate (mobile, or desktop forced by POKEPORT_TOUCH=1).
-  do
-    local env = os.getenv("POKEPORT_TOUCH")
-    local osName = love.system and love.system.getOS and love.system.getOS()
-    local show = env == "1"
-      or (env ~= "0" and (osName == "Android" or osName == "iOS"))
-    if show then
-      add(Strings("TOUCH PAD"),
-        function()
-          local tc = opts.touchControls
-          local on = not (type(tc) == "table" and tc.enabled == false)
-          return on and Strings("ON") or Strings("OFF")
-        end,
-        function()
-          local tc = type(opts.touchControls) == "table" and opts.touchControls or {}
-          tc.enabled = tc.enabled == false
-          opts.touchControls = tc
-          return true
-        end)
-      -- VIBRATION sits with it (#806): same gate, same subsystem.  Stepping
-      -- the row buzzes once at the level being selected.
-      local okTC, TC = pcall(require, "src.core.TouchControls")
-      if okTC then
-        add(Strings("VIBRATION"),
-          function() return Strings(TC.hapticLabel(opts.haptics)) end,
-          function(dir)
-            opts.haptics = TC.cycleHaptics(opts.haptics, dir)
-            TC.buzz(opts.haptics)
-            return true
-          end)
-      end
-    end
-  end
-
-  -- TOUCH CONTROLS, the on-screen pad's layout editor.  It used to be a
-  -- button on the game panel, once per game -- but the overlay layout is
-  -- global (options.touchControls.layouts), so three tabs offered three
-  -- buttons that edited the same thing while crowding the column that has to
-  -- hold Play.  It belongs with the other control rows, behind the gear.
-  -- The host owns the editor screen, so the row only fires when a hook was
-  -- supplied (the standalone save editor opens this model with none).
-  if hooks and hooks.editTouchControls then
-    rows[#rows + 1] = {
-      label = Strings("TOUCH CONTROLS"),
-      actionLabel = Strings("Edit"),
-      action = function()
-        hooks.editTouchControls()
-        -- The editor replaces the whole screen: nothing left to persist here
-        -- beyond what the caller already saved on the way out.
-        return false
-      end,
-    }
-  end
+  addTouchRows(rows, add, opts, hooks)
 
   -- RESET REBINDS, directly under the touch-pad row.  Rebinds are additive
   -- (src/core/Input.lua:applyBindings layers options.bindings over the
@@ -462,7 +471,7 @@ end
 -- src/ui/gen2/OptionsMenu.lua's ROWS; when editing one, keep the two in sync.
 local GEN2_KEY = "gold"
 
-local function gen2Rows(opts)
+local function gen2Rows(opts, hooks)
   local rows = {}
   local function add(label, value, step)
     rows[#rows + 1] = { label = label, value = value, step = step }
@@ -551,6 +560,8 @@ local function gen2Rows(opts)
       end)
   end
 
+  addTouchRows(rows, add, opts, hooks)
+
   return rows
 end
 
@@ -574,7 +585,7 @@ function LauncherSettings.open(hooks, version)
       opts[GEN2_KEY] = block
     end
     sections = {
-      { title = Strings("OPTIONS"), rows = gen2Rows(block) },
+      { title = Strings("OPTIONS"), rows = gen2Rows(block, hooks) },
     }
   else
     sections = {

src/import/RomImporter.lua

@@ -1228,8 +1228,8 @@ function RomImporter.new(onComplete, opts)
     saveNotice = {},
     -- MODS panel state (pass 3): mods is the cached LauncherMods.list() array
     -- (refreshed lazily on first draw and after any toggle/install/delete);
-    -- modScroll is the list scroll offset (px, clamped in draw); modNotice is
-    -- the last install/delete result { ok, text } shown as a line above the list.
+    -- modScroll is the current paged list's inner scroll offset (px, clamped
+    -- in draw); modNotice is the last install/delete result { ok, text }.
     mods = nil, modScroll = 0, modNotice = nil,
     -- Which game the MODS panel is answering for (a GameVersion id, nil =
     -- every game).  Rows resolve their enable-state and their "runs here"
@@ -1370,6 +1370,10 @@ function RomImporter.new(onComplete, opts)
     end
   end
 
+  if GameVersion.VERSIONS[self.tab] then
+    self.modScope = self.tab
+  end
+
   return self
 end
 
@@ -1645,7 +1649,7 @@ end
 function RomImporter:_installMod(source)
   if self.workState == "working" then return end
   self.tab = "mods"
-  local ok, installed, res = pcall(function()
+  local ok, installed, res, manifest = pcall(function()
     local LauncherMods = require("src.mods.LauncherMods")
     return LauncherMods.installZip(source)
   end)
@@ -1657,6 +1661,17 @@ function RomImporter:_installMod(source)
   if installed then
     pcall(self._refreshMods, self)
     self.modNotice = { ok = true, text = "Installed " .. tostring(res) }
+    local LauncherMods = require("src.mods.LauncherMods")
+    local checkTarget = manifest
+    if not checkTarget and type(res) == "string" then
+      checkTarget = { id = res }
+    end
+    if checkTarget and LauncherMods.checkDependencies then
+      local depCheck = LauncherMods.checkDependencies(checkTarget)
+      if depCheck and depCheck.hasIssues then
+        self._modDepResolver = depCheck
+      end
+    end
   else
     self.modNotice = { ok = false, text = tostring(res) }
   end
@@ -2044,6 +2059,15 @@ end
 
 function RomImporter:update(dt)
   self.pulse = self.pulse + dt
+  if self._launchFade then
+    self._launchFade.elapsed = self._launchFade.elapsed + dt
+    if self._launchFade.elapsed >= self._launchFade.duration then
+      local version = self._launchFade.version
+      self._launchFade = nil
+      self:play(version)
+      return
+    end
+  end
   self:_updatePadCursor(dt)
   self:_stepBaseRomScan()
   -- Pump the FlexLove view (input polling + the queued click actions).  The
@@ -2432,9 +2456,15 @@ function RomImporter:joystickhat(joystick, hat, direction)
 end
 
 -- Player pressed Play on a game whose ROM is imported: hand off to boot.
-function RomImporter:play(version)
+function RomImporter:play(version, fade)
   if self.workState == "working" then return end
   if not self.ready[version] then return end
+  if fade then
+    if not self._launchFade then
+      self._launchFade = { version = version, elapsed = 0, duration = 0.24 }
+    end
+    return
+  end
   self._handedOff = true
   -- #835: remember the game being launched so the next launcher start opens on
   -- its column (_applyLastVersionTab).  It rides options.lua rather than a file
@@ -2627,6 +2657,9 @@ function RomImporter:_switchTab(id)
   self.tab = id
   self._findSearchFocus = false
   self:_disarmTextInput()
+  if GameVersion.VERSIONS[id] then
+    self:_setModScope(id)
+  end
 end
 
 function RomImporter:_toggleFindSearchFocus()
@@ -2645,11 +2678,14 @@ function RomImporter:_openSettings()
   -- hook rather than reaching for main.lua's handler itself.  Closing the
   -- settings panel FIRST persists the pending edits (_closeSettings saves)
   -- and leaves no modal behind the editor to return to.
+  -- The tab rides along: the editor persists the layout into that game's own
+  -- option block, and Gold's is not the flat Gen 1 one (#1100).
   local hooks = {}
   if self.onEditTouchControls then
+    local version = self.tab
     hooks.editTouchControls = function()
       self:_closeSettings()
-      self.onEditTouchControls()
+      self.onEditTouchControls(version)
     end
   end
   -- The tab the gear was opened on decides the row set: Gold reads a
@@ -2691,6 +2727,43 @@ function RomImporter:fileUrl(path)
 end
 
 function RomImporter:keypressed(key)
+  if self._profileSavePrompt then
+    if key == "backspace" then
+      self._profileSavePrompt.text = utf8Back(self._profileSavePrompt.text or "")
+    elseif key == "return" or key == "kpenter" then
+      local txt = self._profileSavePrompt and self._profileSavePrompt.text
+      if txt and txt ~= "" then
+        local LauncherMods = require("src.mods.LauncherMods")
+        LauncherMods.saveProfile(txt)
+        self._profileSavePrompt = nil
+        self:_disarmTextInput()
+        if self._refreshMods then self:_refreshMods() end
+      end
+    elseif key == "escape" then
+      self._profileSavePrompt = nil
+      self:_disarmTextInput()
+    end
+    return
+  end
+  if self._profileRenamePrompt then
+    if key == "backspace" then
+      self._profileRenamePrompt.text = utf8Back(self._profileRenamePrompt.text or "")
+    elseif key == "return" or key == "kpenter" then
+      local txt = self._profileRenamePrompt and self._profileRenamePrompt.text
+      local old = self._profileRenamePrompt and self._profileRenamePrompt.oldName
+      if txt and txt ~= "" and old then
+        local LauncherMods = require("src.mods.LauncherMods")
+        LauncherMods.renameProfile(old, txt)
+        self._profileRenamePrompt = nil
+        self:_disarmTextInput()
+        if self._refreshMods then self:_refreshMods() end
+      end
+    elseif key == "escape" then
+      self._profileRenamePrompt = nil
+      self:_disarmTextInput()
+    end
+    return
+  end
   if self._settingsText then
     if key == "backspace" then
       self._settingsText.text = utf8Back(self._settingsText.text)
@@ -2734,6 +2807,13 @@ function RomImporter:keypressed(key)
   end
   if self._modConfirm or self._modVersions or self._modReleaseNotes
       or self._findDetails then
+    -- Focus navigation belongs to the visible modal as well as the launcher
+    -- beneath it. Route arrows and an already-armed confirm before this guard
+    -- returns; unarmed Enter still falls through to the modal guard. Keep this
+    -- inside the modal branch so text fields retain exclusive keyboard input.
+    if self._flex and require("src.import.LauncherView").keypressed(self, key) then
+      return
+    end
     if key == "escape" then
       if self._findDetails then
         self._findDetails = nil
@@ -2853,6 +2933,14 @@ function RomImporter:_commitRename()
 end
 
 function RomImporter:textinput(text)
+  if self._profileSavePrompt then
+    self._profileSavePrompt.text = utf8Cap((self._profileSavePrompt.text or "") .. text, MAX_SLOT_LABEL)
+    return
+  end
+  if self._profileRenamePrompt then
+    self._profileRenamePrompt.text = utf8Cap((self._profileRenamePrompt.text or "") .. text, MAX_SLOT_LABEL)
+    return
+  end
   if self._settingsText then
     local st = self._settingsText
     st.text = utf8Cap(st.text .. text, st.maxLen or MAX_SLOT_LABEL)
@@ -2937,6 +3025,13 @@ function RomImporter:_refreshMods()
     end
   end
   self.mods = LauncherMods.list(self.modScope) or {}
+  if self.modScope then
+    local kept = {}
+    for _, m in ipairs(self.mods) do
+      if m.targetsHere ~= false then kept[#kept + 1] = m end
+    end
+    self.mods = kept
+  end
   self:_syncModUpdateInfo(false)
 end
 
@@ -3040,15 +3135,19 @@ function RomImporter:_modUpdateInfo(id)
   return self.modUpdateInfo and self.modUpdateInfo[id] or nil
 end
 
--- Flip a mod's enabled flag (persisted via LauncherMods.setEnabled) and relist
--- so the toggle, count, and every status chip reflect the new resolution.
--- Enabling an experimental mod arms a confirm first.
-function RomImporter:_toggleMod(id, confirmed)
+-- Flip one game's mod flag (persisted via LauncherMods.setEnabled) and relist
+-- so that game's checkbox and status chips reflect the new resolution.
+-- Enabling an experimental mod arms a confirmation for that same game.
+function RomImporter:_toggleMod(id, confirmed, version)
   local LauncherMods = require("src.mods.LauncherMods")
   local cur, experimental = false, false
   for _, m in ipairs(self.mods or {}) do
     if m.id == id then
-      cur = m.enabled
+      if version and m.enabledByVersion then
+        cur = m.enabledByVersion[version] == true
+      else
+        cur = m.enabled
+      end
       experimental = m.experimental == true
       break
     end
@@ -3056,7 +3155,7 @@ function RomImporter:_toggleMod(id, confirmed)
   local want = not cur
   if want and experimental and not confirmed then
     self._modConfirm = {
-      kind = "experimental", id = id,
+      kind = "experimental", id = id, version = version,
       title = "Experimental mod",
       yesLabel = "Enable",
       lines = {
@@ -3068,7 +3167,7 @@ function RomImporter:_toggleMod(id, confirmed)
     return
   end
   self._modConfirm = nil
-  LauncherMods.setEnabled(id, want, self.modScope)
+  LauncherMods.setEnabled(id, want, version or self.modScope)
   self:_refreshMods()
 end
 
@@ -3328,6 +3427,76 @@ function RomImporter:_pumpModInstall()
   else
     self.modNotice = { ok = true, text = text }
   end
+  local LauncherMods = require("src.mods.LauncherMods")
+  local depCheck = LauncherMods.checkDependencies({ id = spec.modId })
+  if depCheck and depCheck.hasIssues then
+    self._modDepResolver = depCheck
+  end
+end
+
+-- Start an async pull for a single dependency
+function RomImporter:_startDepPull(dep)
+  if not dep or not dep.github then return end
+  self._depPullState = self._depPullState or {}
+  local hFetch = require("src.mods.ModUpdate").beginFetchReleases(dep.github, dep.id, { force = true })
+  self._depPullState[dep.id] = {
+    dep = dep,
+    stage = "fetching",
+    fetchHandle = hFetch,
+  }
+end
+
+-- Pump all in-flight dependency pulls
+function RomImporter:_pumpDepPulls()
+  if not self._depPullState then return end
+  local ModUpdate = require("src.mods.ModUpdate")
+  local LauncherMods = require("src.mods.LauncherMods")
+
+  for depId, state in pairs(self._depPullState) do
+    if state.stage == "fetching" then
+      local done, releases, err = ModUpdate.pumpFetchReleases(state.fetchHandle)
+      if done then
+        if err or not releases or #releases == 0 then
+          state.stage = "error"
+          state.err = err or "No downloadable releases found on GitHub"
+        else
+          local rel = releases[1]
+          if not rel or not rel.zip or not rel.zip.url then
+            state.stage = "error"
+            state.err = "Latest release has no downloadable .zip asset"
+          else
+            local tmpName = ("dep_%s_%s.zip"):format(depId, tostring(rel.version or os.time()))
+            state.dlHandle = ModUpdate.beginDownloadZip(rel.zip.url, tmpName, rel.zip.size)
+            state.stage = "downloading"
+            state.targetVersion = rel.version
+          end
+        end
+      end
+    elseif state.stage == "downloading" then
+      local done, localPath, err, progress = ModUpdate.pumpDownloadZip(state.dlHandle)
+      state.progress = progress
+      if done then
+        if err or not localPath then
+          state.stage = "error"
+          state.err = err or "Download failed"
+        else
+          state.stage = "installing"
+          local okInst, versionRes = LauncherMods.installDownloadedZip(depId, localPath, state.targetVersion)
+          if okInst then
+            state.stage = "done"
+            pcall(self._refreshMods, self)
+            if self._modDepResolver and self._modDepResolver.targetMod then
+              local updated = LauncherMods.checkDependencies(self._modDepResolver.targetMod)
+              self._modDepResolver = updated
+            end
+          else
+            state.stage = "error"
+            state.err = tostring(versionRes or "Installation failed")
+          end
+        end
+      end
+    end
+  end
 end
 
 function RomImporter:_confirmModUpdate(modId, release)
@@ -3586,7 +3755,7 @@ function RomImporter:_findRows()
   -- index, query, or category actually changed.
   local c = self._findRowsCache
   if c and c.src == all and c.query == self.findQuery
-      and c.category == self.findCategory then
+      and c.category == self.findCategory and c.scope == self.modScope then
     return c.rows
   end
   local ModIndex = require("src.mods.ModIndex")
@@ -3594,8 +3763,33 @@ function RomImporter:_findRows()
     query = self.findQuery,
     category = self.findCategory,
   })
+  if self.modScope then
+    local gen = GameVersion.generation(self.modScope)
+    local kept = {}
+    for _, entry in ipairs(rows) do
+      local has1, has2 = false, false
+      local function note(s)
+        s = tostring(s or ""):lower()
+        if s == "gen1" or s == "gen 1" or s == "red" or s == "blue"
+            or s == "yellow" then
+          has1 = true
+        end
+        if s == "gen2" or s == "gen 2" or s == "gold" then
+          has2 = true
+        end
+      end
+      for _, cat in ipairs(entry.categories or {}) do note(cat) end
+      for _, tag in ipairs(entry.tags or {}) do note(tag) end
+      if (not has1 and not has2)
+          or (gen == 2 and has2)
+          or (gen ~= 2 and has1) then
+        kept[#kept + 1] = entry
+      end
+    end
+    rows = kept
+  end
   self._findRowsCache = { src = all, query = self.findQuery,
-    category = self.findCategory, rows = rows }
+    category = self.findCategory, scope = self.modScope, rows = rows }
   return rows
 end
 

src/inventory/ItemEffects.lua

@@ -210,6 +210,17 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
   -- (ItemUsePokeFlute, engine/items/item_effects.asm); never consumed.
   if itemId == "POKE_FLUTE" then
     if not battle then
+      if ow and ow.map and ow.map.id == "PEWTER_POKECENTER"
+          and ow.pikachuPewterSleepScene then
+        local Follower = require("src.world.PikachuFollower")
+        local pika = Follower.current(ow)
+        local player = ow.player
+        if pika and player
+            and math.abs(pika.cellX - player.cellX) + math.abs(pika.cellY - player.cellY) == 1 then
+          return "flute_wake_pikachu", { romText(data, "_PlayedFluteHadEffectText",
+            "{PLAYER} played the\nPOKé FLUTE.") }
+        end
+      end
       -- standing next to a not-yet-beaten Snorlax: this is the ONLY way
       -- Snorlax wakes -- using the flute from the item-use menu, never
       -- just talking to it with the flute in the bag (see

src/link/LinkBattle.lua

@@ -9,15 +9,16 @@
 -- cable pull.
 --
 -- Cable rules: no experience, no money, no items; either side may RUN
--- (a draw); a fainted mon is auto-replaced by the next healthy party
--- member (the original prompts; documented divergence).  Badge stat
--- boosts don't apply on either side (divergence: Gen 1 famously kept
--- them in link battles).
+-- (a draw); a fainted mon is replaced from the party menu and the chosen
+-- slot rides the wire, the way ChooseNextMon hands it to
+-- LinkBattleExchangeData.  Badge stat boosts don't apply on either side
+-- (divergence: Gen 1 famously kept them in link battles).
 
 local Fingerprint = require("src.link.Fingerprint")
 local Font = require("src.render.Font")
 local Handshake = require("src.link.Handshake")
 local Logger = require("src.core.Logger")
+local Party = require("src.pokemon.Party")
 local Protocol = require("src.link.Protocol")
 local Runtime = require("src.mods.Runtime")
 local TurnOrder = require("src.battle.TurnOrder")
@@ -257,7 +258,9 @@ function LinkBattle.new(game, net, opts)
   self.enemyParty = theirParty
   self.playerParty = myParty -- intro ball row uses the clamped copies
   self.opponentName = theirName
-  self.introText = Strings("%s wants\nto battle!", theirName)
+  -- _TrainerWantsToFightText (data/text/text_2.asm:1257): wIsInBattle == 2
+  -- takes PrintBeginningBattleText's .trainerBattle arm, link included
+  self.introText = Strings("%s wants\nto fight!", theirName)
   self.remoteHashes = {}
   self.localHashes = {}
   self.remoteParts = {}
@@ -327,6 +330,68 @@ function LinkBattle.new(game, net, opts)
     end)
   end
 
+  -- ChooseNextMon (engine/battle/core.asm:1086-1103): the replacement after
+  -- a faint is a free party-menu pick in a link battle too -- DisplayPartyMenu
+  -- runs first, a fainted pick or a cancel goes back to it
+  -- (.goBackToPartyMenu), and only the chosen slot rides
+  -- LinkBattleExchangeData.
+  local function chooseReplacement(s)
+    s.linkReplacement = nil
+    s:uiNext(function()
+      return s:buildScreen("PartyMenu", {
+        battle = s,
+        party = myParty,
+        forceSwitch = true,
+        onSwitch = function(mon)
+          if mon.hp > 0 then s.linkReplacement = mon end
+        end,
+      })
+    end)
+    s:actNext(function()
+      local mon = s.linkReplacement
+      s.linkReplacement = nil
+      if s.result then return end
+      if not mon then
+        chooseReplacement(s)
+        return
+      end
+      for i, m in ipairs(myParty) do
+        if m == mon then send({ type = "replace", index = i }) break end
+      end
+      sendOutPlayer(s, mon)
+    end)
+  end
+
+  -- ReplaceFaintedEnemyMon (core.asm:892-905) reads the peer's slot back out
+  -- of the exchange, and EnemySendOutFirstMon (core.asm:1315-1320) decodes it
+  -- as wSerialExchangeNybbleReceiveData - 4.  HandlePlayerMonFainted
+  -- (core.asm:989-996) always runs ChooseNextMon BEFORE that read, so on a
+  -- double faint both machines commit their own slot before they block on the
+  -- peer's; our queue can reach the enemy's handler first, so the wait
+  -- pre-empts itself with the local pick rather than deadlocking on a message
+  -- neither side is going to send.
+  local function awaitReplacement(s)
+    s:actNext(function()
+      if s.result then return end
+      if s.player.mon.hp <= 0 and not s.linkChoiceQueued
+         and Party.firstHealthy(myParty) then
+        s.linkChoiceQueued = true
+        chooseReplacement(s)
+        awaitReplacement(s)
+        return
+      end
+      local idx = s.remoteReplace
+      if not idx then
+        awaitReplacement(s)
+        return
+      end
+      s.remoteReplace = nil
+      local mon = theirParty[idx]
+      if not mon or mon.hp <= 0 then mon = Party.firstHealthy(theirParty) end
+      sendOutEnemy(s, mon)
+    end)
+  end
+
   -- decode a remote action message against the enemy battler
   local function decodeTheirAction(s, msg)
     return decodeWireAction(s, msg, s.enemy)
@@ -540,12 +605,17 @@ function LinkBattle.new(game, net, opts)
     submit(s, { type = "action", kind = "run" }, nil)
   end
 
-  -- fainted mons auto-replace with the next healthy teammate, in party
-  -- order, identically on both machines
+  -- linkChoiceQueued: awaitReplacement already pre-empted itself with this
+  -- side's ChooseNextMon and put the slot on the wire, so the handler the
+  -- faint queued has nothing left to do but drop the flag
   self.playerMonFainted = function(s)
+    if s.linkChoiceQueued then
+      s.linkChoiceQueued = nil
+      return
+    end
     for _, mon in ipairs(myParty) do
       if mon.hp > 0 then
-        s:act(function() sendOutPlayer(s, mon) end)
+        if not s.result then chooseReplacement(s) end
         return
       end
     end
@@ -558,7 +628,7 @@ function LinkBattle.new(game, net, opts)
   self.enemyMonFainted = function(s)
     for _, mon in ipairs(theirParty) do
       if mon.hp > 0 then
-        s:act(function() sendOutEnemy(s, mon) end)
+        if not s.result then awaitReplacement(s) end
         return
       end
     end
@@ -579,6 +649,9 @@ function LinkBattle.new(game, net, opts)
         s.remoteHashes[msg.turn or 0] = msg.value
         s.remoteParts[msg.turn or 0] = msg.parts
         checkHashes(s)
+      elseif msg.type == "replace" then
+        local idx = math.floor(tonumber(msg.index) or 1)
+        s.remoteReplace = math.max(1, math.min(#theirParty, idx))
       elseif msg.type == "bye" then
         -- only a draw if our own simulation hasn't already decided
         -- (the winner's bye can arrive while we're still animating)
@@ -770,6 +843,34 @@ function LinkBattle.newSpectator(game, net, opts)
     end)
   end
 
+  local function awaitHostReplacement(s)
+    s:actNext(function()
+      if s.result then return end
+      local idx = table.remove(s.hostReplace, 1)
+      if not idx then
+        awaitHostReplacement(s)
+        return
+      end
+      local mon = hostParty[idx]
+      if not mon or mon.hp <= 0 then mon = Party.firstHealthy(hostParty) end
+      sendOutHost(s, mon)
+    end)
+  end
+
+  local function awaitGuestReplacement(s)
+    s:actNext(function()
+      if s.result then return end
+      local idx = table.remove(s.guestReplace, 1)
+      if not idx then
+        awaitGuestReplacement(s)
+        return
+      end
+      local mon = guestParty[idx]
+      if not mon or mon.hp <= 0 then mon = Party.firstHealthy(guestParty) end
+      sendOutGuest(s, mon)
+    end)
+  end
+
   local function resolveSpecTurn(s, hostMsg, guestMsg)
     if hostMsg.kind == "run" or guestMsg.kind == "run" then
       endSpectate(s, "The match ended.")
@@ -840,7 +941,7 @@ function LinkBattle.newSpectator(game, net, opts)
   self.playerMonFainted = function(s)
     for _, mon in ipairs(hostParty) do
       if mon.hp > 0 then
-        s:act(function() sendOutHost(s, mon) end)
+        if not s.result then awaitHostReplacement(s) end
         return
       end
     end
@@ -852,7 +953,7 @@ function LinkBattle.newSpectator(game, net, opts)
   self.enemyMonFainted = function(s)
     for _, mon in ipairs(guestParty) do
       if mon.hp > 0 then
-        s:act(function() sendOutGuest(s, mon) end)
+        if not s.result then awaitGuestReplacement(s) end
         return
       end
     end
@@ -862,6 +963,7 @@ function LinkBattle.newSpectator(game, net, opts)
   end
 
   self.hostMsg, self.guestMsg = nil, nil
+  self.hostReplace, self.guestReplace = {}, {}
   local baseUpdate = self.update
   self.update = function(s, dt)
     net:update()
@@ -875,6 +977,13 @@ function LinkBattle.newSpectator(game, net, opts)
             s.hostMsg, s.guestMsg = nil, nil
             resolveSpecTurn(s, h, g)
           end
+        elseif inner.type == "replace" then
+          local idx = math.floor(tonumber(inner.index) or 1)
+          if msg.side == "host" then
+            table.insert(s.hostReplace, math.max(1, math.min(#hostParty, idx)))
+          else
+            table.insert(s.guestReplace, math.max(1, math.min(#guestParty, idx)))
+          end
         elseif inner.type == "bye" or inner.type == "forfeit" then
           if not s.result then endSpectate(s, "The match ended.") end
         end

src/link/LinkState.lua

@@ -19,6 +19,7 @@ LinkState.__index = LinkState
 LinkState.isOpaque = true
 
 local CURSOR = 0xED
+local CURSOR_HOLLOW = 0xEC
 local ANY = "ANY" -- sentinel: a leading nil array entry breaks ipairs under
                   -- LuaJIT even though # still reports the full size, so
                   -- the level picker cycles this string instead of nil,
@@ -114,6 +115,7 @@ end
 function LinkState:exitWith(message, reason)
   DiscordPresence.setJoinCode(nil)
   self.game.linkSession = nil -- back to the player's own GAME SPEED
+  if self.game.linkNet == self.net then self.game.linkNet = nil end
   Runtime.emit("link.ended", { reason = reason or (message and "error" or "bye") })
   if self.net then self.net:close() end
   self.game.stack:pop()
@@ -519,6 +521,9 @@ function LinkState:startMode(mode, isHost)
     })
     self.net:send(self.trade:opening())
     self.index = 1
+    self.theirIndex = 1
+    self.side = "mine"
+    self.pickChoice = nil
   else
     self.stage = "battleWait"
     -- the host deals the shared RNG seed for the lockstep simulation
@@ -536,7 +541,14 @@ end
 -- trade flow
 -- -------------------------------------------------------------------
 
+function LinkState:openStats(mon)
+  if not mon then return end
+  self.game.linkNet = self.net
+  Screens.push(self.game, "SummaryMenu", mon)
+end
+
 function LinkState:updateTrade(input)
+  if self.game.linkNet == self.net then self.game.linkNet = nil end
   for _, msg in ipairs(self.net:poll()) do
     local reply = self.trade:handle(msg)
     if reply then self.net:send(reply) end
@@ -591,10 +603,51 @@ function LinkState:updateTrade(input)
     return
   end
 
-  if t.stage == "picking" and input:wasPressed("up") then
-    self.index = math.max(1, self.index - 1)
+  -- pokered engine/link/cable_club.asm TradeCenter_SelectMon: A on one of
+  -- your own mons opens the "STATS     TRADE" row (.displayStatsTradeMenu)
+  -- and only TRADE commits the pick, while the enemy list carries its own
+  -- cursor whose A shows that mon's status pages (.displayEnemyMonStats).
+  -- The cart's enemy path sets hl but never wMonDataLocation, the way the
+  -- battle menu's STATS (engine/battle/core.asm) does, so LoadMonData_ reads
+  -- the player's party and it draws YOUR mon at that slot -- an omission,
+  -- not behaviour, so we show the peer's mon.
+  if t.stage == "picking" and self.pickChoice then
+    if input:wasPressed("left") then
+      self.pickChoice = 1
+    elseif input:wasPressed("right") then
+      self.pickChoice = 2
+    elseif input:wasPressed("b") then
+      self.pickChoice = nil -- .cancelPlayerMonChoice: back to the list, not
+                            -- out of the trade
+    elseif input:wasPressed("a") then
+      if self.pickChoice == 1 then
+        self.pickChoice = nil
+        self:openStats(self.game.save.party[self.index])
+      elseif t:canPick(self.index) then
+        self.pickChoice = nil
+        self.side = "mine"
+        self.net:send(t:pick(self.index))
+      end
+    end
+  elseif t.stage == "picking" and input:wasPressed("up") then
+    if self.side == "theirs" then
+      self.theirIndex = math.max(1, self.theirIndex - 1)
+    else
+      self.index = math.max(1, self.index - 1)
+    end
   elseif t.stage == "picking" and input:wasPressed("down") then
-    self.index = math.min(#self.game.save.party, self.index + 1)
+    if self.side == "theirs" then
+      self.theirIndex = math.min(#(t.theirParty or {}), self.theirIndex + 1)
+    else
+      self.index = math.min(#self.game.save.party, self.index + 1)
+    end
+  elseif t.stage == "picking" and input:wasPressed("right") then
+    if t.theirParty and #t.theirParty > 0 then
+      self.side = "theirs"
+      self.theirIndex = math.min(self.theirIndex, #t.theirParty)
+    end
+  elseif t.stage == "picking" and input:wasPressed("left") then
+    self.side = "mine"
   elseif self.confirmed == nil and input:wasPressed("b") then
     -- once confirm=true has been sent to the peer, backing out here
     -- would desync the two sides (the peer may already be committing
@@ -603,8 +656,10 @@ function LinkState:updateTrade(input)
     self.net:send({ type = "bye" })
     self:exitWith(Strings("The trade was\ncancelled."))
   elseif t.stage == "picking" and input:wasPressed("a") then
-    if t:canPick(self.index) then
-      self.net:send(t:pick(self.index))
+    if self.side == "theirs" then
+      self:openStats((t.theirParty or {})[self.theirIndex])
+    else
+      self.pickChoice = 1
     end
   elseif t.stage == "confirming" and self.confirmed == nil then
     if input:wasPressed("a") then
@@ -738,25 +793,40 @@ function LinkState:draw()
       local label = (mon.nickname or def.name):sub(1, 8)
       if not t:canPick(i) then label = label .. "X" end
       Font.draw(label, 16, 20 + i * 12)
-      if i == self.index then Font.drawCode(CURSOR, 8, 20 + i * 12) end
+      if i == self.index and self.side ~= "theirs" then
+        Font.drawCode(CURSOR, 8, 20 + i * 12)
+      end
     end
     Font.draw(Strings("THEIRS"), 84, 20)
     for i, mon in ipairs(t.theirParty or {}) do
       local def = self.game.data.pokemon[mon.species]
       Font.draw((mon.nickname or def.name):sub(1, 8), 92, 20 + i * 12)
-      if t.theirPick == i then Font.drawCode(CURSOR, 84, 20 + i * 12) end
+      if self.side == "theirs" and i == self.theirIndex then
+        Font.drawCode(CURSOR, 84, 20 + i * 12)
+      elseif t.theirPick == i then
+        Font.drawCode(CURSOR_HOLLOW, 84, 20 + i * 12)
+      end
     end
-    local hint
-    if t.stage == "waitRecords" then hint = "Comparing games..."
-    elseif t.stage == "waitParty" then hint = "Exchanging data..."
-    elseif t.stage == "picking" then
-      hint = t:canPick(self.index) and "Pick one to trade"
-             or Strings("X: not on theirs")
-    elseif t.stage == "waitPick" then hint = "Waiting for them..."
-    elseif t.stage == "confirming" then
-      hint = self.confirmed and "Waiting..." or Strings("A: trade  B: cancel")
+    if self.pickChoice then
+      Font.draw(Strings("STATS"), 16, 128)
+      Font.draw(Strings("TRADE"), 96, 128)
+      Font.drawCode(CURSOR, self.pickChoice == 1 and 8 or 88, 128)
+    else
+      local hint
+      if t.stage == "waitRecords" then hint = "Comparing games..."
+      elseif t.stage == "waitParty" then hint = "Exchanging data..."
+      elseif t.stage == "picking" then
+        if self.side == "theirs" then hint = Strings("A: stats")
+        else
+          hint = t:canPick(self.index) and "Pick one to trade"
+                 or Strings("X: not on theirs")
+        end
+      elseif t.stage == "waitPick" then hint = "Waiting for them..."
+      elseif t.stage == "confirming" then
+        hint = self.confirmed and "Waiting..." or Strings("A: trade  B: cancel")
+      end
+      Font.draw(hint or "", 8, 132)
     end
-    Font.draw(hint or "", 8, 132)
 
   elseif self.stage == "battleWait" or self.stage == "battleRunning" then
     drawTitle("LINK BATTLE")

src/mods/AssetTransform.lua

@@ -16,6 +16,7 @@
 
 local Logger = require("src.core.Logger")
 local Runtime = require("src.mods.Runtime")
+local SafePath = require("src.mods.SafePath")
 
 local unpack = table.unpack or unpack
 local loadstring = loadstring or load
@@ -31,25 +32,8 @@ AssetTransform.SOURCE_ROOT = SOURCE_ROOT
 AssetTransform.DERIVED_ROOT = DERIVED_ROOT
 
 -- ------- path sandbox
-
--- a relative path that cannot climb out of the root it is joined to
-local function safeRelative(rel)
-  if type(rel) ~= "string" or rel == "" then return nil end
-  if rel:sub(1, 1) == "/" then return nil end
-  if rel:find("\\", 1, true) then return nil end
-  for segment in rel:gmatch("[^/]+") do
-    if segment == ".." or segment == "." then return nil end
-  end
-  return rel
-end
-
-local function requireRelative(rel, what)
-  local safe = safeRelative(rel)
-  if not safe then
-    error(("%s must stay inside its root, got %q"):format(what, tostring(rel)), 0)
-  end
-  return safe
-end
+-- shared with mod:read and the manifest's own paths (src/mods/SafePath.lua)
+local requireRelative = SafePath.require
 
 -- ------- the restricted context
 

src/mods/Gen2Compat.lua

@@ -736,7 +736,7 @@ COVERAGE["src.pokemon.Boxes"] = {
 
 COVERAGE["src.world.WorldAPI"] = {
   kind = "alias", target = "src.world.gen2.WorldAPI",
-  backed = "new __index overworld current warpTo toggleObject replaceBlock "
+  backed = "new __index overworld current mapOverview warpTo toggleObject replaceBlock "
     .. "spawnNpc removeNpc npc queueScript invalidateMap",
   warned = "setFlag getFlag",
   absent = "",

src/mods/LauncherMods.lua

@@ -36,10 +36,13 @@ local ModTargets = require("src.mods.ModTargets")
 local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
 local SaveData = require("src.core.SaveData")
+local GameVersion = require("src.core.GameVersion")
 local CacheFs = require("src.import.CacheFs")
 
 local LauncherMods = {}
 
+local discover  -- forward declaration for helper functions above line 343
+
 -- ------- pure status derivation
 
 -- A hard-dependency / conflict / version verdict for one manifest.  mods is
@@ -84,31 +87,196 @@ local function statusFor(mods, id, enabledSet, enabled, version, forcedFor)
   -- resolveToggle would cascade-enable a merely-disabled dep rather than flag
   -- it, so the disabled case is judged straight off the manifest here.
   for _, spec in ipairs(m.dependencySpecs or {}) do
-    local dep = mods[spec.id]
-    if not dep then
-      return "warn", "Needs " .. spec.id .. " (not installed)"
-    elseif not enabledSet[spec.id] then
-      return "warn", "Needs " .. spec.id .. " (disabled)"
-    -- installed and on, but not for THIS game: the loader skips the
-    -- dependency and the skip is contagious (Loader:_enforceDependencies),
-    -- so a mod that runs everywhere still does not run here
-    elseif version
-        and not ModTargets.runsHere(dep, version, nil, forcedFor(spec.id)) then
-      return "warn", "Needs " .. spec.id .. " (not for "
-        .. ModTargets.gameLabel(version) .. ")"
-    elseif spec.range
-        and not Semver.satisfies(dep.version, spec.range) then
-      return "warn", "Needs " .. spec.id .. " " .. spec.range
+    if ModTargets.specApplies(spec, version) then
+      local dep = mods[spec.id]
+      if not dep then
+        return "warn", "Needs " .. spec.id .. " (not installed)"
+      elseif not enabledSet[spec.id] then
+        return "warn", "Needs " .. spec.id .. " (disabled)"
+      -- installed and on, but not for THIS game: the loader skips the
+      -- dependency and the skip is contagious (Loader:_enforceDependencies),
+      -- so a mod that runs everywhere still does not run here
+      elseif version
+          and not ModTargets.runsHere(dep, version, nil, forcedFor(spec.id)) then
+        return "warn", "Needs " .. spec.id .. " (not for "
+          .. ModTargets.gameLabel(version) .. ")"
+      elseif spec.range
+          and not Semver.satisfies(dep.version, spec.range) then
+        return "warn", "Needs " .. spec.id .. " " .. spec.range
+      end
     end
   end
   return "ok", "Ready"
 end
 
+-- Resolves the best-known GitHub owner/repo string for a dependency spec, if any.
+function LauncherMods.resolveDependencyRepo(depId, parentManifest, installedDep)
+  if not depId or depId == "" then return nil end
+  -- 1. Check spec hint if parentManifest dependencySpecs carries it
+  if parentManifest and parentManifest.dependencySpecs then
+    for _, spec in ipairs(parentManifest.dependencySpecs) do
+      if spec.id == depId and spec.github then
+        return spec.github
+      end
+    end
+  end
+  -- 2. Check parentManifest raw dependency_sources
+  if parentManifest and parentManifest.raw and type(parentManifest.raw.dependency_sources) == "table" then
+    local src = parentManifest.raw.dependency_sources[depId]
+    if src then
+      local ok, clean = pcall(Manifest.parseGithub, src)
+      if ok and clean then return clean end
+    end
+  end
+  -- 3. Check installed dependency manifest
+  if installedDep and installedDep.github then
+    return installedDep.github
+  end
+  -- 4. Check ModIndex entries if available
+  local okModIndex, ModIndex = pcall(require, "src.mods.ModIndex")
+  if okModIndex and ModIndex and type(ModIndex.sources) == "function" then
+    for _, src in ipairs(ModIndex.sources() or {}) do
+      local cached = ModIndex.readCache and ModIndex.readCache(src.feed)
+      if cached and type(cached.index) == "table" then
+        for _, entry in ipairs(cached.index) do
+          if type(entry) == "table" and entry.id == depId and entry.github then
+            local ok, clean = pcall(Manifest.parseGithub, entry.github)
+            if ok and clean then return clean end
+          end
+        end
+      end
+    end
+  end
+  return nil
+end
+
+-- Inspect manifest dependencies and conflicts against installed mods.
+-- Returns: { hasIssues = bool, targetMod = {...}, deps = [ { id, name, range, status, kind, installedVersion, github, safeUrl }, ... ] }
+function LauncherMods.checkDependencies(manifest, options, version, installedManifests)
+  if not manifest then
+    return { hasIssues = false, targetMod = { name = "Unknown" }, deps = {} }
+  end
+
+  local SaveData = require("src.core.SaveData")
+  local manifests = installedManifests or discover()
+  local installedMap = {}
+  for _, m in ipairs(manifests) do
+    installedMap[m.id] = m
+  end
+
+  local depsResult = {}
+  local hasIssues = false
+
+  -- 1. Hard Dependencies (dependencySpecs)
+  if type(manifest.dependencySpecs) == "table" then
+    for _, spec in ipairs(manifest.dependencySpecs) do
+      if not version or ModTargets.specApplies(spec, version) then
+        local depId = spec.id
+        local range = spec.range
+        local installedDep = installedMap[depId]
+        local status = "satisfied"
+        local installedVersion = installedDep and installedDep.version or nil
+
+        if not installedDep then
+          status = "missing"
+          hasIssues = true
+        elseif range and not Semver.satisfies(installedDep.version, range) then
+          status = "incompatible"
+          hasIssues = true
+        end
+
+        local ghRepo = LauncherMods.resolveDependencyRepo(depId, manifest, installedDep)
+        local safeUrl = ghRepo and ("https://github.com/" .. ghRepo) or nil
+
+        depsResult[#depsResult + 1] = {
+          id = depId,
+          name = (installedDep and installedDep.name) or depId,
+          range = range,
+          status = status,
+          kind = "dependency",
+          installedVersion = installedVersion,
+          github = ghRepo,
+          safeUrl = safeUrl,
+        }
+      end
+    end
+  end
+
+  -- 2. Conflicts / Incompatible Mods (conflictSpecs)
+  local conflictIdsSeen = {}
+  local scope = SaveData.modScope and SaveData.modScope(version) or version
+
+  local isEnabled = function(modId)
+    if not options then return true end
+    local dec = SaveData.modEnabled(options, modId, scope)
+    if dec ~= nil then return dec == true end
+    local m = installedMap[modId]
+    return m and not m.experimental
+  end
+
+  -- (a) Conflicts declared by target manifest
+  if type(manifest.conflictSpecs) == "table" then
+    for _, spec in ipairs(manifest.conflictSpecs) do
+      local conflictId = spec.id
+      local installedOther = installedMap[conflictId]
+      if installedOther and isEnabled(conflictId) and not conflictIdsSeen[conflictId] then
+        conflictIdsSeen[conflictId] = true
+        hasIssues = true
+        depsResult[#depsResult + 1] = {
+          id = conflictId,
+          name = installedOther.name or conflictId,
+          status = "conflict",
+          kind = "conflict",
+          installedVersion = installedOther.version or "?",
+          github = nil,
+          safeUrl = nil,
+        }
+      end
+    end
+  end
+
+  -- (b) Reverse conflicts declared by installed mods against target manifest
+  if manifest.id then
+    for _, other in ipairs(manifests) do
+      if other.id ~= manifest.id and isEnabled(other.id) and not conflictIdsSeen[other.id] then
+        local conflicts = other.conflictSpecs or {}
+        for _, spec in ipairs(conflicts) do
+          if spec.id == manifest.id then
+            conflictIdsSeen[other.id] = true
+            hasIssues = true
+            depsResult[#depsResult + 1] = {
+              id = other.id,
+              name = other.name or other.id,
+              status = "conflict",
+              kind = "conflict",
+              installedVersion = other.version or "?",
+              github = nil,
+              safeUrl = nil,
+            }
+            break
+          end
+        end
+      end
+    end
+  end
+
+  return {
+    hasIssues = hasIssues,
+    targetMod = {
+      id = manifest.id,
+      name = manifest.name or manifest.id,
+      version = manifest.version or "?",
+    },
+    deps = depsResult,
+  }
+end
+
 -- deriveList(manifests, options [, version]) -> the panel row list, pure.
 -- manifests is an array of validated manifests (Manifest.validate output);
 -- options is the options table (options.mods, options.modsByVersion and
--- options.modsGen2 are read).  `version` is the game the panel is showing:
--- nil keeps the pre-per-game view, where the shared flag is the whole answer.
+-- options.modsGen2 are read).  `version` is the game the panel is showing;
+-- each row also carries its answer for every game so the launcher can render
+-- the coloured game checkboxes together.
 -- Rows come back sorted by id so the panel order is stable.
 function LauncherMods.deriveList(manifests, options, version)
   local ordered = {}
@@ -126,8 +294,7 @@ function LauncherMods.deriveList(manifests, options, version)
     -- this game's choice, then the shared flag, then the default: enabled,
     -- matching the loader -- except experimental mods, which stay off until
     -- the player opts in.  Scoped through modScope, so this reads exactly what
-    -- setEnabled writes and the loader loads: while per-game flags are a
-    -- preview the shared flag is the whole answer on every surface.
+    -- setEnabled writes and the loader loads for the selected game.
     local decided = SaveData.modEnabled(options, m.id, SaveData.modScope(version))
     if decided == nil then decided = not m.experimental end
     if decided then enabledSet[m.id] = true end
@@ -152,10 +319,20 @@ function LauncherMods.deriveList(manifests, options, version)
       badge = badge,
       description = m.description or "",
       enabled = enabled,
+      enabledByVersion = (function()
+        local answers = {}
+        for _, game in ipairs(GameVersion.ORDER) do
+          local answer = SaveData.modEnabled(options, m.id, game)
+          answers[game] = answer == true or (answer == nil and not m.experimental)
+        end
+        return answers
+      end)(),
       status = status,
       statusDetail = detail,
       github = m.github,
       experimental = m.experimental == true,
+      dependencySpecs = m.dependencySpecs,
+      manifest = m,
       -- what game this mod is for, and whether it will run on the one the
       -- panel is showing (src/mods/ModTargets.lua)
       targets = ModTargets.chip(m),
@@ -243,7 +420,7 @@ end
 -- Scan "mods/" one level deep for valid manifests (mirrors Loader:_discover,
 -- but validates only -- no entry chunk is ever loaded).  First id wins on a
 -- duplicate.  Returns an array of validated manifests.
-local function discover()
+discover = function()
   local fs = love and love.filesystem
   local out = {}
   if not (fs and fs.getInfo and fs.getDirectoryItems) then return out end
@@ -281,7 +458,14 @@ end
 function LauncherMods.list(version)
   local ok, result = pcall(function()
     local options = SaveData.loadOptions()
-    return LauncherMods.deriveList(discover(), options, version)
+    local manifests = discover()
+    -- The first build containing game-specific switches turns the old shared
+    -- state into one explicit answer per installed mod and game.  Saving here
+    -- means users who only visit the launcher still receive the migration.
+    if SaveData.migrateModEnablement(options, manifests) then
+      SaveData.saveOptions(options)
+    end
+    return LauncherMods.deriveList(manifests, options, version)
   end)
   if not ok then
     -- a single bad options/mod file must not blank the launcher
@@ -364,14 +548,13 @@ function LauncherMods.translationStrings()
   return merged
 end
 
--- setEnabled(id, enabled [, version]): persist options.mods[id] in the exact
--- shape Loader:_saveState writes (a plain boolean), so the running game and
--- the in-game ManagerState pick it up unchanged.  With `version` the choice
--- lands in that game's overlay instead and no other game moves.
+-- setEnabled(id, enabled [, version]): with a game, persist just that game's
+-- answer.  The loader and the in-game manager use the same scope on next boot.
 function LauncherMods.setEnabled(id, enabled, version)
   local options = SaveData.loadOptions()
   SaveData.setModEnabled(options, id, enabled, SaveData.modScope(version))
   SaveData.saveOptions(options)
+  LauncherMods.syncActiveProfile(options)
   return true
 end
 
@@ -384,9 +567,18 @@ function LauncherMods.setAllEnabled(ids, enabled, version)
   local options = SaveData.loadOptions()
   local scope = SaveData.modScope(version)
   for _, id in ipairs(ids or {}) do
-    SaveData.setModEnabled(options, id, enabled, scope)
+    if scope then
+      SaveData.setModEnabled(options, id, enabled, scope)
+    elseif SaveData.PER_VERSION_MODS then
+      for _, game in ipairs(GameVersion.ORDER) do
+        SaveData.setModEnabled(options, id, enabled, game)
+      end
+    else
+      SaveData.setModEnabled(options, id, enabled)
+    end
   end
   SaveData.saveOptions(options)
+  LauncherMods.syncActiveProfile(options)
   return true
 end
 
@@ -652,9 +844,9 @@ function LauncherMods.adoptStrays() return scanStrays(true) end
 -- opts.replace = true uninstalls an existing same-id mod first (updates /
 -- rollbacks).  opts.expectId, when set, refuses a zip whose manifest id differs.
 function LauncherMods.installZip(source, opts)
-  local ok, result, err = pcall(LauncherMods._installZipInner, source, opts)
+  local ok, result, res2, res3 = pcall(LauncherMods._installZipInner, source, opts)
   if not ok then return nil, "import failed: " .. tostring(result) end
-  return result, err
+  return result, res2, res3
 end
 
 function LauncherMods._installZipInner(source, opts)
@@ -764,7 +956,7 @@ function LauncherMods._installZipInner(source, opts)
     return nil, copyErr or "could not copy the mod files"
   end
   cleanup()
-  return true, manifest.id
+  return true, manifest.id, manifest
 end
 
 -- Install (or replace) a mod from a GitHub release zip URL.
@@ -843,7 +1035,7 @@ end
 
 -- uninstall(id) -> true  |  nil, errString
 -- Removes mods/<id>/ from wherever it was installed (the portable game folder
--- or the save directory, CacheFs decides -- #330) and clears options.mods[id]
+-- or the save directory, CacheFs decides -- #330) and clears every enable flag
 -- so the loader and in-game manager no longer see it.  Rejects missing ids.
 -- Does not touch other mods' enable state.
 function LauncherMods.uninstall(id)
@@ -872,8 +1064,164 @@ function LauncherMods.uninstall(id)
   -- Drop the enable flag so a reinstall of the same id starts from the
   -- loader's default (enabled) rather than a stale false.
   local options = SaveData.loadOptions()
+  local changed = false
   if options.mods and options.mods[id] ~= nil then
     options.mods[id] = nil
+    changed = true
+  end
+  for _, version in ipairs(GameVersion.ORDER) do
+    local bucket = options.modsByVersion and options.modsByVersion[version]
+    if type(bucket) == "table" and bucket[id] ~= nil then
+      bucket[id] = nil
+      changed = true
+    end
+  end
+  if changed then
+    SaveData.saveOptions(options)
+  end
+  return true
+end
+
+-- ----------------------------------------------------------- Mod Profiles (#593)
+local ModProfile = require("src.mods.ModProfile")
+
+function LauncherMods.getProfiles(options)
+  options = options or SaveData.loadOptions()
+  local manifests = discover()
+  ModProfile.ensureFirst(options, manifests, options.modOptions)
+  return options.modProfiles or {}, options.activeProfile or "PROFILE 1"
+end
+
+function LauncherMods.applyProfile(profileName, options)
+  options = options or SaveData.loadOptions()
+  local profiles = options.modProfiles or {}
+  local targetProfile
+  for _, p in ipairs(profiles) do
+    if p.name == profileName then targetProfile = p; break end
+  end
+  if not targetProfile then return false end
+  ModProfile.restoreVersions(targetProfile, options)
+  options.activeProfile = profileName
+  SaveData.saveOptions(options)
+  return true
+end
+
+function LauncherMods.saveProfile(profileName, options)
+  options = options or SaveData.loadOptions()
+  local manifests = discover()
+  options.modProfiles = options.modProfiles or {}
+  local snap = ModProfile.capture(manifests, options.modOptions, options.modsByVersion)
+  snap.name = profileName
+  local existingIdx
+  for i, p in ipairs(options.modProfiles) do
+    if p.name == profileName then existingIdx = i; break end
+  end
+  if existingIdx then
+    options.modProfiles[existingIdx] = snap
+  else
+    options.modProfiles[#options.modProfiles + 1] = snap
+  end
+  options.activeProfile = profileName
+  SaveData.saveOptions(options)
+  return snap
+end
+
+local function copyTable(tbl)
+  if type(tbl) ~= "table" then return tbl end
+  local copy = {}
+  for k, v in pairs(tbl) do
+    copy[k] = type(v) == "table" and copyTable(v) or v
+  end
+  return copy
+end
+
+function LauncherMods.syncActiveProfile(options)
+  options = options or SaveData.loadOptions()
+  local activeName = options.activeProfile or "PROFILE 1"
+  local profiles = options.modProfiles or {}
+  local manifests = discover()
+  local snap = ModProfile.capture(manifests, options.modOptions, options.modsByVersion)
+  snap.name = activeName
+
+  local found = false
+  for i, p in ipairs(profiles) do
+    if p.name == activeName then
+      profiles[i] = snap
+      found = true
+      break
+    end
+  end
+  if not found then
+    profiles[#profiles + 1] = snap
+  end
+  options.modProfiles = profiles
+  options.activeProfile = activeName
+  SaveData.saveOptions(options)
+  return snap
+end
+
+function LauncherMods.duplicateProfile(sourceName, options)
+  options = options or SaveData.loadOptions()
+  local profiles = options.modProfiles or {}
+  local sourceProfile
+  for _, p in ipairs(profiles) do
+    if p.name == sourceName then sourceProfile = p; break end
+  end
+  if not sourceProfile then return nil end
+
+  local baseName = sourceName .. " (Copy)"
+  local newName = baseName
+  local n = 1
+  local taken = {}
+  for _, p in ipairs(profiles) do taken[p.name] = true end
+  while taken[newName] do
+    n = n + 1
+    newName = sourceName .. " (" .. n .. ")"
+  end
+
+  local snap = {
+    name = newName,
+    enabled = copyTable(sourceProfile.enabled),
+    options = copyTable(sourceProfile.options),
+    slots = copyTable(sourceProfile.slots),
+    enabledByVersion = copyTable(sourceProfile.enabledByVersion),
+  }
+  profiles[#profiles + 1] = snap
+  options.modProfiles = profiles
+  options.activeProfile = newName
+  SaveData.saveOptions(options)
+  return snap
+end
+
+function LauncherMods.renameProfile(oldName, newName, options)
+  options = options or SaveData.loadOptions()
+  if not newName or newName == "" then return false end
+  local profiles = options.modProfiles or {}
+  for i, p in ipairs(profiles) do
+    if p.name == oldName then
+      p.name = newName
+      if options.activeProfile == oldName then
+        options.activeProfile = newName
+      end
+      SaveData.saveOptions(options)
+      return true
+    end
+  end
+  return false
+end
+
+function LauncherMods.deleteProfile(profileName, options)
+  options = options or SaveData.loadOptions()
+  options.modProfiles = options.modProfiles or {}
+  local newProfiles = {}
+  for _, p in ipairs(options.modProfiles) do
+    if p.name ~= profileName then newProfiles[#newProfiles + 1] = p end
+  end
+  options.modProfiles = newProfiles
+  if options.activeProfile == profileName then
+    local fallback = newProfiles[1] and newProfiles[1].name or "PROFILE 1"
+    LauncherMods.applyProfile(fallback, options)
+  else
     SaveData.saveOptions(options)
   end
   return true

src/mods/Loader.lua

@@ -12,12 +12,15 @@ local Manifest = require("src.mods.Manifest")
 local Merge = require("src.mods.Merge")
 local ModTargets = require("src.mods.ModTargets")
 local Registry = require("src.mods.Registry")
+local SafePath = require("src.mods.SafePath")
+local Sandbox = require("src.mods.Sandbox")
 local Schemas = require("src.mods.Schemas")
 local Semver = require("src.mods.Semver")
 local Events = require("src.mods.Events")
 local Gen2Compat = require("src.mods.Gen2Compat")
 local Hooks = require("src.mods.Hooks")
 local Runtime = require("src.mods.Runtime")
+local Steps = require("src.mods.Steps")
 
 local Loader = {}
 Loader.__index = Loader
@@ -72,10 +75,12 @@ local function orderedIds(mods, filter)
   return ids
 end
 
--- ------- dev-mode permissions tripwire
--- Attribution only: the shim delegates unconditionally and blocks nothing.
--- Installed once per process and only when the loader runs in dev mode, so a
--- player build has zero interposition.
+-- ------- the require gate
+-- Two jobs in one interposition.  The engine_internals/network scan is
+-- attribution only and stays dev-mode: it warns and delegates.  The
+-- Sandbox.moduleDenial check is not -- require("io") would hand back
+-- package.loaded.io and undo the whole mod environment -- so it is installed
+-- in player builds too, for any boot that has mods on it.
 
 local devShim = { installed = false, permissions = {}, warned = {}, depth = 0 }
 
@@ -135,7 +140,8 @@ end
 
 local function scanRequire(name)
   local modId = Runtime.currentMod
-  if not modId or type(name) ~= "string" then return end
+  if type(modId) ~= "string" then modId = Runtime.modRequire end
+  if type(modId) ~= "string" or type(name) ~= "string" then return end
   local granted = devShim.permissions[modId] or {}
   local function warnOnce(permission)
     local key = modId .. "|" .. permission .. "|" .. name
@@ -188,6 +194,7 @@ function Loader:_installDevShim()
   for id, mod in pairs(self.mods) do
     devShim.permissions[id] = mod.manifest.permissionSet
   end
+  devShim.dev = self.dev
   if devShim.installed then return end
   devShim.installed = true
   local delegate = require
@@ -195,12 +202,22 @@ function Loader:_installDevShim()
     -- only the mod's own call is the mod's doing; whatever that module
     -- requires in turn is the engine wiring itself up
     if devShim.depth == 0 then
-      scanRequire(name)
+      -- Backstop for the deny list Sandbox.envFor's require already applies:
+      -- an engine module requiring io is the engine wiring itself up, a mod
+      -- doing it is the hole this closes, and any future path that runs mod
+      -- code without a sandbox env still lands here.
+      local owner = Runtime.currentMod or Runtime.modRequire
+      if owner or callerIsMod(3) then
+        local id = type(owner) == "string" and owner or nil
+        local denial = Sandbox.moduleDenial(name, devShim.permissions[id])
+        if denial then error(("[%s] %s"):format(id or "mod", denial), 0) end
+      end
+      if devShim.dev or devShim.generation ~= 1 then scanRequire(name) end
       -- The Gen 1 name a mod asked for, answered by the Gen 2 arm behind it.
       -- Engine code keeps the real module: src/render/PaletteFX.lua:776
       -- requires src.core.Game on both generations and means it.
       if devShim.generation ~= 1 and Gen2Compat.serves(name)
-          and callerIsMod(3) then
+          and (owner or callerIsMod(3)) then
         local adapter = Gen2Compat.resolve(name, Runtime.currentMod)
         if adapter then
           local key = "adapter|" .. name
@@ -235,7 +252,7 @@ function Loader.new(opts)
     events = Events.new(), hooks = Hooks.new(), content = {}, assets = {},
     exports = {}, migrations = {}, order = {},
     modSave = {}, modOptions = {}, optionSchemas = {}, imageCache = {},
-    modInput = {},
+    modInput = {}, modEnv = {}, stepsQueues = {},
     fs = (opts and opts.fs) or (love and love.filesystem),
     dev = dev,
     -- Which generation this boot is (1 or 2).  Fixed at construction: the
@@ -270,8 +287,7 @@ function Loader:_targetVersion()
   return version
 end
 
--- The version an enable flag is read and written under: this game once
--- per-game flags are live, nil (the shared flag) while they are a preview.
+-- The version an enable flag is read and written under: this running game.
 -- Reads and writes go through the same answer so the two can never drift.
 function Loader:_enableScope()
   return SaveData.modScope(self:_targetVersion())
@@ -358,11 +374,13 @@ function Loader:_writeOptionSchemas()
       -- demand; using it here means older mods do not need to migrate to
       -- mod.options:define just to appear in a launcher settings screen.
       if schema == nil and mod.manifest.options_schema and self.fs.load then
-        local chunk = self.fs.load(mod.path .. "/" .. mod.manifest.options_schema)
-        if chunk then
-          local ok, rows = pcall(chunk)
-          if ok and type(rows) == "table" then schema = rows end
-        end
+        local ok, rows = pcall(function()
+          local path = SafePath.join(mod.path, mod.manifest.options_schema,
+            "options_schema")
+          local chunk = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
+          return chunk and chunk()
+        end)
+        if ok and type(rows) == "table" then schema = rows end
       end
       if schema ~= nil then
         mods[id] = schema
@@ -562,42 +580,46 @@ end
 -- hard dependencies must exist, be enabled, have survived, and satisfy their
 -- range; run to a fixpoint so failures propagate to dependents transitively
 function Loader:_enforceDependencies()
+  local targetVersion = self:_targetVersion()
+  local generation = self.generation
   local changed = true
   while changed do
     changed = false
     for _, id in ipairs(orderedIds(self.mods, isActive)) do
       local mod = self.mods[id]
       for _, spec in ipairs(mod.manifest.dependencySpecs) do
-        local dep = self.mods[spec.id]
-        local reason, skip
-        if not dep then
-          reason = "missing dependency: " .. spec.id
-        elseif not dep.enabled then
-          reason = ("dependency %s is disabled"):format(spec.id)
-        elseif dep.state == "wrong_generation" then
-          -- the gate's skip is contagious as a SKIP, not as a failure: the
-          -- dependency has no bug to report and neither does this mod, so
-          -- nothing here lands on the boot error list
-          skip = true
-          -- carry the dependency's own reason: it names the game or the
-          -- missing gen2compat, and a guess here would name the wrong one
-          reason = ("depends on %s, which does not run here (%s)")
-            :format(spec.id, dep.skipReason or "not made for this game")
-        elseif dep.failed then
-          reason = ("dependency %s failed to load"):format(spec.id)
-        elseif spec.range
-            and not Semver.satisfies(dep.manifest.version, spec.range) then
-          reason = ("needs %s@%s, found %s")
-            :format(spec.id, spec.range, dep.manifest.version)
-        end
-        if reason then
-          if skip then
-            self:_skip(mod, "wrong_generation", reason)
-          else
-            self:_fail(mod, "blocked_dependency", reason)
+        if ModTargets.specApplies(spec, targetVersion, generation) then
+          local dep = self.mods[spec.id]
+          local reason, skip
+          if not dep then
+            reason = "missing dependency: " .. spec.id
+          elseif not dep.enabled then
+            reason = ("dependency %s is disabled"):format(spec.id)
+          elseif dep.state == "wrong_generation" then
+            -- the gate's skip is contagious as a SKIP, not as a failure: the
+            -- dependency has no bug to report and neither does this mod, so
+            -- nothing here lands on the boot error list
+            skip = true
+            -- carry the dependency's own reason: it names the game or the
+            -- missing gen2compat, and a guess here would name the wrong one
+            reason = ("depends on %s, which does not run here (%s)")
+              :format(spec.id, dep.skipReason or "not made for this game")
+          elseif dep.failed then
+            reason = ("dependency %s failed to load"):format(spec.id)
+          elseif spec.range
+              and not Semver.satisfies(dep.manifest.version, spec.range) then
+            reason = ("needs %s@%s, found %s")
+              :format(spec.id, spec.range, dep.manifest.version)
+          end
+          if reason then
+            if skip then
+              self:_skip(mod, "wrong_generation", reason)
+            else
+              self:_fail(mod, "blocked_dependency", reason)
+            end
+            changed = true
+            break
           end
-          changed = true
-          break
         end
       end
     end
@@ -607,6 +629,8 @@ end
 -- Tarjan SCC over the hard-dependency graph: only a cycle's own members
 -- fail, so an unrelated mod beside a cycle still loads
 function Loader:_failCycles()
+  local targetVersion = self:_targetVersion()
+  local generation = self.generation
   local mods = self.mods
   local counter, stack, onStack, index, low = 0, {}, {}, {}, {}
   local cycles = {}
@@ -617,14 +641,16 @@ function Loader:_failCycles()
     onStack[id] = true
     local selfEdge = false
     for _, spec in ipairs(mods[id].manifest.dependencySpecs) do
-      local dep = mods[spec.id]
-      if spec.id == id then selfEdge = true end
-      if dep and isActive(dep) and spec.id ~= id then
-        if not index[spec.id] then
-          connect(spec.id)
-          if low[spec.id] < low[id] then low[id] = low[spec.id] end
-        elseif onStack[spec.id] and index[spec.id] < low[id] then
-          low[id] = index[spec.id]
+      if ModTargets.specApplies(spec, targetVersion, generation) then
+        local dep = mods[spec.id]
+        if spec.id == id then selfEdge = true end
+        if dep and isActive(dep) and spec.id ~= id then
+          if not index[spec.id] then
+            connect(spec.id)
+            if low[spec.id] < low[id] then low[id] = low[spec.id] end
+          elseif onStack[spec.id] and index[spec.id] < low[id] then
+            low[id] = index[spec.id]
+          end
         end
       end
     end
@@ -675,6 +701,8 @@ end
 -- Kahn over the surviving graph with the ready set kept in (priority, id)
 -- order, so dependencies come first and the rest matches the v1 contract
 function Loader:_order()
+  local targetVersion = self:_targetVersion()
+  local generation = self.generation
   local pending, indegree, dependents = {}, {}, {}
   for _, id in ipairs(orderedIds(self.mods, isActive)) do
     pending[id], indegree[id] = true, 0
@@ -687,9 +715,17 @@ function Loader:_order()
       dependents[depId][#dependents[depId] + 1] = id
       indegree[id] = indegree[id] + 1
     end
-    for _, spec in ipairs(manifest.dependencySpecs) do edge(spec.id) end
+    for _, spec in ipairs(manifest.dependencySpecs) do
+      if ModTargets.specApplies(spec, targetVersion, generation) then
+        edge(spec.id)
+      end
+    end
     -- optional dependencies order without requiring anything
-    for _, spec in ipairs(manifest.optionalSpecs) do edge(spec.id) end
+    for _, spec in ipairs(manifest.optionalSpecs) do
+      if ModTargets.specApplies(spec, targetVersion, generation) then
+        edge(spec.id)
+      end
+    end
   end
   local ordered = {}
   local function nextId()
@@ -981,6 +1017,40 @@ function Loader:_api(mod)
         return DateTime.dateTime(game, timestamp)
       end,
     },
+    -- The read-only part of love.system that device UIs legitimately need.
+    -- Do not expose the module: openURL and clipboard access stay sandboxed.
+    device = {
+      powerInfo = function()
+        local getPowerInfo = love and love.system and love.system.getPowerInfo
+        if not getPowerInfo then return "unknown", nil end
+        local state, percent = getPowerInfo()
+        return state, percent
+      end,
+    },
+    -- The native step bridge (#1186), behind the "steps" permission the
+    -- player sees in the mod manager: sync asks the platform to refresh
+    -- its count, poll hands this mod its copy of what the bridge
+    -- delivered.  The engine owns the pending file -- a mod never names a
+    -- path, it only receives { steps, from, to }.  available() answers
+    -- false without the permission (a probe stays quiet); the calls that
+    -- would do something name the missing permission instead, the way the
+    -- network gate does.
+    steps = (function()
+      if mod.manifest.permissionSet.steps then
+        loader.stepsQueues[modId] = loader.stepsQueues[modId] or {}
+        return {
+          available = function() return Steps.available() end,
+          sync = function() return Steps.sync() end,
+          poll = function() return Steps.poll(loader, modId) end,
+        }
+      end
+      local function refuse()
+        error(('[%s] mod.steps needs the "steps" permission in '
+          .. "manifest.json"):format(modId), 2)
+      end
+      return { available = function() return false end,
+               sync = refuse, poll = refuse }
+    end)(),
     -- namespaced per mod; M11 backs these with save.modData /
     -- options.modOptions, the shape mods compile against is already final
     save = {
@@ -1091,9 +1161,11 @@ function Loader:_api(mod)
   -- assets keeps the v1 alias to the content accessors and adds the file
   -- helpers on top, so mod.assets.pokemon and mod.assets:image both resolve
   api.assets = setmetatable({
-    path = function(_, relative) return mod.path .. "/" .. relative end,
+    path = function(_, relative)
+      return SafePath.join(mod.path, relative, "mod.assets:path")
+    end,
     image = function(_, relative)
-      local full = mod.path .. "/" .. relative
+      local full = SafePath.join(mod.path, relative, "mod.assets:image")
       local cached = loader.imageCache[full]
       if cached then return cached end
       assert(love and love.graphics,
@@ -1103,9 +1175,10 @@ function Loader:_api(mod)
       return image
     end,
   }, { __index = api.content })
+  -- the mod's own directory and nothing above it: PhysFS already refuses a
+  -- climb, but loader.fs is injectable and has no such floor
   function api:read(relative)
-    local path = self.path .. "/" .. relative
-    return loader.fs.read(path)
+    return loader.fs.read(SafePath.join(self.path, relative, "mod:read"))
   end
   -- mod.world materializes on first touch, like the image helper above: a
   -- headless load must not drag the world stack in, and the Game the facade
@@ -1149,9 +1222,21 @@ function Loader:_game()
   return engineRequire("src.core.Game")
 end
 
+-- The environment every chunk this mod authors runs in, built once per mod so
+-- its entry file and its options_schema share one globals table.
+function Loader:_modEnv(mod)
+  local id = mod.manifest.id
+  local env = self.modEnv[id]
+  if not env then
+    env = Sandbox.envFor({ modId = id, permissions = mod.manifest.permissionSet })
+    self.modEnv[id] = env
+  end
+  return env
+end
+
 function Loader:_loadMod(mod)
-  local path = mod.path .. "/" .. mod.manifest.entry
-  local chunk, err = self.fs.load(path)
+  local path = SafePath.join(mod.path, mod.manifest.entry, "manifest entry")
+  local chunk, err = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
   if not chunk then error(err or ("unable to load " .. path)) end
   local api = self:_api(mod)
   local result = chunk(api)
@@ -1183,6 +1268,7 @@ function Loader:_rollback(modId)
   self.optionSchemas[modId] = nil
   self.migrations[modId] = nil
   self.modSave[modId] = nil
+  self.stepsQueues[modId] = nil
 end
 
 -- a mod that explicitly swears it stays link-compatible while writing into a
@@ -1306,13 +1392,30 @@ function Loader:load(data)
   require("src.mods.Builtins").install(self.content, data, self.generation)
   self:_loadState()
   self:_discover()
+  -- Existing installs stored one shared answer.  Once their manifests are
+  -- known, split that answer across every game before the next launcher/game
+  -- toggle can change one independently.  _loadState already used the same
+  -- fallback, so this write cannot change the current boot's result.
+  do
+    local options = SaveData.loadOptions(self.fs)
+    local installed = {}
+    for id, mod in pairs(self.mods) do
+      installed[#installed + 1] = {
+        id = id,
+        experimental = mod.manifest and mod.manifest.experimental == true,
+      }
+    end
+    if SaveData.migrateModEnablement(options, installed) and self.fs.write then
+      SaveData.saveOptions(options, self.fs)
+    end
+  end
   -- Experimental mods stay off until the player opts in: a missing
   -- options.mods entry normally means enabled, but experimental flips that.
   do
     local options = SaveData.loadOptions(self.fs)
-    local modsOpt = options.mods or {}
+    local scope = self:_enableScope()
     for id, mod in pairs(self.mods) do
-      if not self.disabled[id] and modsOpt[id] == nil
+      if not self.disabled[id] and SaveData.modEnabled(options, id, scope) == nil
           and mod.manifest.experimental then
         self.disabled[id] = true
       end
@@ -1349,10 +1452,12 @@ function Loader:load(data)
   -- every touch: a mod captures the facade at file scope, before Game2 has a
   -- save or a world (src/mods/Gen2Compat.lua).
   Gen2Compat.bind(function() return self:_game() end)
-  -- Dev mode wants the permissions tripwire; a Gold boot with mods on it wants
-  -- the Gen 1-only require report, which is the difference between "the mod
-  -- does nothing" and knowing why.  A Gold boot with no mods pays nothing.
-  if self.dev or (self.generation ~= 1 and next(self.mods) ~= nil) then
+  -- Any boot with mods on it needs the gate, because require("io") is how a
+  -- mod would walk out of Sandbox.envFor.  Dev mode adds the permissions
+  -- tripwire on top, and a Gold boot the Gen 1-only require report -- the
+  -- difference between "the mod does nothing" and knowing why.  A boot with no
+  -- mods pays nothing.
+  if self.dev or next(self.mods) ~= nil then
     self:_installDevShim()
   end
   for _, mod in ipairs(ordered) do

src/mods/ManagerState.lua

@@ -8,6 +8,8 @@ local Font = require("src.render.Font")
 local GameVersion = require("src.core.GameVersion")
 local ModTargets = require("src.mods.ModTargets")
 local Runtime = require("src.mods.Runtime")
+local SafePath = require("src.mods.SafePath")
+local Sandbox = require("src.mods.Sandbox")
 local SaveData = require("src.core.SaveData")
 local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
@@ -735,8 +737,7 @@ function ManagerState:toggleGen2Force(m)
   }, apply)
 end
 
--- Where the loader persisted an enable flag: this game's slot once it keeps
--- them per game, the shared flag until then (SaveData.modScope).
+-- Where the loader persists an enable flag: this running game's slot.
 function ManagerState:enableScope()
   return SaveData.modScope((self:targetGame()))
 end
@@ -936,13 +937,18 @@ function ManagerState:schemaFor(m)
   local schema = loader.optionSchemas and loader.optionSchemas[m.id]
   if schema == nil and m.options_schema and m.path
       and loader.fs and loader.fs.load then
-    local chunk = loader.fs.load(m.path .. "/" .. m.options_schema)
-    if chunk then
-      local ok, rows = pcall(chunk)
-      if ok and type(rows) == "table" then
-        schema = rows
-        if loader.optionSchemas then loader.optionSchemas[m.id] = schema end
-      end
+    -- mod-authored code, so it runs in the same sandbox the entry chunk does
+    local ok, rows = pcall(function()
+      local path = SafePath.join(m.path, m.options_schema, "options_schema")
+      local mod = loader.mods and loader.mods[m.id]
+      local env = mod and loader._modEnv and loader:_modEnv(mod)
+        or Sandbox.envFor()
+      local chunk = Sandbox.loadFile(loader.fs, path, env)
+      return chunk and chunk()
+    end)
+    if ok and type(rows) == "table" then
+      schema = rows
+      if loader.optionSchemas then loader.optionSchemas[m.id] = schema end
     end
   end
   return schema

src/mods/Manifest.lua

@@ -3,13 +3,15 @@
 -- that need to stat a file, this owns shape, vocabulary and range grammar.
 local Logger = require("src.core.Logger")
 local ModTargets = require("src.mods.ModTargets")
+local SafePath = require("src.mods.SafePath")
 local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
 
 local Manifest = {}
 
 Manifest.PROFILES = { content = true, overhaul = true, total_conversion = true }
-Manifest.PERMISSIONS = { network = true, filesystem = true, engine_internals = true }
+Manifest.PERMISSIONS = { network = true, filesystem = true,
+                         engine_internals = true, steps = true }
 
 -- link-relevant registries; a mod that writes into one of these while
 -- declaring affects_link = false gets an attributed warning from the loader
@@ -31,26 +33,6 @@ local function violation(strict, id, message)
   Logger.warn("[%s] %s", tostring(id), message)
 end
 
--- "id" or "id@<range>"; a malformed id or range fails for every api level
--- because there is no sane fallback reading for it
-local function parseSpecs(list, field)
-  local specs = {}
-  for _, entry in ipairs(list) do
-    assert(type(entry) == "string" and entry ~= "",
-      field .. " entries must be non-empty strings")
-    local id, range = entry:match("^([%w_%-]+)@(.+)$")
-    if not id then
-      id = entry:match("^([%w_%-]+)$")
-      assert(id, ("malformed %s entry %q"):format(field, entry))
-      range = nil
-    end
-    local ok, err = Semver.validRange(range)
-    assert(ok, ("malformed %s range in %q: %s"):format(field, entry, tostring(err)))
-    specs[#specs + 1] = { id = id, range = range }
-  end
-  return specs
-end
-
 -- Optional GitHub repo for launcher auto-update / other-versions.
 -- Accepts "owner/repo" or a github.com URL; empty/absent means no updates.
 function Manifest.parseGithub(value)
@@ -73,6 +55,69 @@ function Manifest.parseGithub(value)
   return owner .. "/" .. repo
 end
 
+-- "id", "id@<range>", "id@<range>#<github>", "id#<github>", or table entry
+local function parseSpecs(list, field, sources)
+  local specs = {}
+  sources = type(sources) == "table" and sources or {}
+  for _, entry in ipairs(list) do
+    local id, range, ghHint, gamesRaw, gameVersion
+    if type(entry) == "table" then
+      id = entry.id
+      range = entry.range or entry.version
+      ghHint = entry.github or entry.repo
+      gamesRaw = entry.games or entry.game
+      gameVersion = entry.game_version
+    elseif type(entry) == "string" and entry ~= "" then
+      local main, hashRepo = entry:match("^([^#]+)#(.*)$")
+      if main then
+        entry = main
+        ghHint = hashRepo
+      end
+      id, range = entry:match("^([%w_%-]+)@(.+)$")
+      if not id then
+        id = entry:match("^([%w_%-]+)$")
+        assert(id, ("malformed %s entry %q"):format(field, entry))
+        range = nil
+      end
+    else
+      error(field .. " entries must be non-empty strings or tables")
+    end
+    assert(id, ("malformed %s entry"):format(field))
+    local ok, err = Semver.validRange(range)
+    assert(ok, ("malformed %s range in %q: %s"):format(field, tostring(entry), tostring(err)))
+
+    if gameVersion then
+      local okV, errV = Semver.validRange(gameVersion)
+      assert(okV, ("malformed %s game_version range in %q: %s"):format(field, tostring(entry), tostring(errV)))
+    end
+
+    local parsedGames = nil
+    if gamesRaw ~= nil then
+      if type(gamesRaw) == "string" then gamesRaw = { gamesRaw } end
+      assert(type(gamesRaw) == "table", "dependency games must be a string or table")
+      local normalized, unknown = ModTargets.normalize(gamesRaw)
+      assert(#unknown == 0, ("unknown game in %s: %s"):format(field, table.concat(unknown, ", ")))
+      parsedGames = normalized
+    end
+
+    local parsedGh = nil
+    local rawGh = ghHint or sources[id]
+    if rawGh then
+      local okGh, cleanGh = pcall(Manifest.parseGithub, rawGh)
+      if okGh and cleanGh then parsedGh = cleanGh end
+    end
+
+    specs[#specs + 1] = {
+      id = id,
+      range = range,
+      github = parsedGh,
+      games = parsedGames,
+      game_version = gameVersion,
+    }
+  end
+  return specs
+end
+
 -- conflicts + incompatible (alias) merged, first-wins on duplicate ids
 local function mergeConflictLists(conflicts, incompatible)
   local seen, out = {}, {}
@@ -144,6 +189,9 @@ function Manifest.validate(raw, path)
   assert(type(raw.name) == "string" and raw.name ~= "", "manifest name is required")
   assert(type(raw.version) == "string" and raw.version ~= "", "manifest version is required")
   assert(type(raw.entry) == "string" and raw.entry ~= "", "manifest entry is required")
+  -- every manifest path is joined to the mod's own directory, so none of them
+  -- may climb out of it (src/mods/SafePath.lua)
+  local entry = SafePath.require(raw.entry, "manifest entry")
 
   -- absent means 1: full v1 compat, schema violations downgrade to warnings
   assert(raw.api == nil or tonumber(raw.api) ~= nil, "manifest api must be a number")
@@ -229,27 +277,32 @@ function Manifest.validate(raw, path)
   local affectsLink = profile ~= "content" and not language
   if type(raw.affects_link) == "boolean" then affectsLink = raw.affects_link end
 
-  local function optionalFile(value, field)
+  local function optionalString(value, field)
     if value == nil then return nil end
     assert(type(value) == "string" and value ~= "", field .. " must be a file path")
     return value
   end
 
+  local function optionalFile(value, field)
+    local text = optionalString(value, field)
+    return text and SafePath.require(text, field)
+  end
+
   local conflicts = mergeConflictLists(raw.conflicts, raw.incompatible)
 
   return {
     id = raw.id,
     name = raw.name,
     version = raw.version,
-    entry = raw.entry,
+    entry = entry,
     api = api,
     priority = tonumber(raw.priority) or 0,
     dependencies = array(raw.dependencies),
     optional_dependencies = array(raw.optional_dependencies),
     conflicts = conflicts,
     incompatible = array(raw.incompatible),
-    dependencySpecs = parseSpecs(array(raw.dependencies), "dependencies"),
-    optionalSpecs = parseSpecs(array(raw.optional_dependencies), "optional_dependencies"),
+    dependencySpecs = parseSpecs(array(raw.dependencies), "dependencies", raw.dependency_sources),
+    optionalSpecs = parseSpecs(array(raw.optional_dependencies), "optional_dependencies", raw.dependency_sources),
     conflictSpecs = parseSpecs(conflicts, "conflicts"),
     category = raw.category or "OTHER",
     game_version = raw.game_version,
@@ -265,7 +318,8 @@ function Manifest.validate(raw, path)
     permissionSet = permissionSet,
     options_schema = optionalFile(raw.options_schema, "options_schema"),
     assets_transforms = optionalFile(raw.assets_transforms, "assets_transforms"),
-    force_enable_env = optionalFile(raw.force_enable_env, "force_enable_env"),
+    -- an env var name, not a path, so it keeps the plain string check
+    force_enable_env = optionalString(raw.force_enable_env, "force_enable_env"),
     path = path,
     raw = raw,
   }

src/mods/ModIndex.lua

@@ -334,9 +334,15 @@ function ModIndex.compatIssues(entry, ctx)
   local function eachSpec(spec, fn)
     if type(spec) ~= "table" then return end
     for k, v in pairs(spec) do
-      if type(k) == "number" and type(v) == "string" then
-        local id, range = v:match("^([^@]+)@(.+)$")
-        fn(id or v, range)
+      if type(k) == "number" then
+        if type(v) == "table" and type(v.id) == "string" then
+          fn(v.id, v.range or v.version, v.github or v.repo)
+        elseif type(v) == "string" then
+          local main, hashRepo = v:match("^([^#]+)#(.*)$")
+          if main then v = main end
+          local id, range = v:match("^([^@]+)@(.+)$")
+          fn(id or v, range, hashRepo)
+        end
       elseif type(k) == "string" then
         fn(k, type(v) == "string" and v or nil)
       end

src/mods/ModTargets.lua

@@ -168,4 +168,39 @@ function ModTargets.detail(manifest, version)
     ModTargets.gameLabel(version))
 end
 
+-- Does a dependency spec apply to this game / version?
+-- If spec.games is provided, it must match version / generation.
+-- If spec.game_version is provided, the engine version must satisfy it.
+function ModTargets.specApplies(spec, version, generation)
+  if not spec then return false end
+  if type(spec.games) == "table" and #spec.games > 0 then
+    if version or generation then
+      local match = false
+      for _, id in ipairs(spec.games) do
+        if version and id == version then
+          match = true
+          break
+        end
+        if generation and GameVersion.generation(id) == generation then
+          match = true
+          break
+        end
+      end
+      if not match then return false end
+    end
+  end
+  if spec.game_version then
+    local ok = pcall(function()
+      local Semver = require("src.mods.Semver")
+      local Version = require("src.core.Version")
+      if Version and Version.engine and Version.engine:match("^0%.0%.0%-") == nil then
+        return Semver.satisfies(Version.engine, spec.game_version)
+      end
+      return true
+    end)
+    if not ok then return false end
+  end
+  return true
+end
+
 return ModTargets

src/mods/Runtime.lua

@@ -28,6 +28,11 @@ Runtime.errors = nil
 -- permissions tripwire knows there is nobody to attribute to
 Runtime.currentMod = nil
 
+-- set by the sandbox's require for the duration of one mod-initiated require,
+-- so the loader's gate can still attribute a lazy one made long after
+-- currentMod went back to nil (src/mods/Sandbox.lua)
+Runtime.modRequire = nil
+
 function Runtime.install(events, hooks, errors)
   Runtime.events, Runtime.hooks = events, hooks
   Runtime.errors = errors

src/mods/SafePath.lua

@@ -0,0 +1,38 @@
+-- One relative-path grammar for every path a mod supplies: a mod names files
+-- inside its own directory and nowhere else.  love.filesystem (PhysFS) already
+-- refuses "..", absolute paths and backslashes, but Loader.new takes an
+-- injected fs that has no such floor, so the rule lives here and not in
+-- whichever filesystem happens to be underneath.
+local SafePath = {}
+
+-- The normalized path, or nil when it could climb out of the root it is about
+-- to be joined to.  "." segments are dropped rather than rejected so a
+-- manifest that says "./main.lua" still loads.
+function SafePath.safe(rel)
+  if type(rel) ~= "string" or rel == "" then return nil end
+  if rel:sub(1, 1) == "/" then return nil end
+  if rel:find("\\", 1, true) then return nil end
+  if rel:match("^%a:") then return nil end -- windows drive-relative
+  local parts = {}
+  for segment in rel:gmatch("[^/]+") do
+    if segment == ".." then return nil end
+    if segment ~= "." then parts[#parts + 1] = segment end
+  end
+  if #parts == 0 then return nil end
+  return table.concat(parts, "/")
+end
+
+function SafePath.require(rel, what)
+  local safe = SafePath.safe(rel)
+  if not safe then
+    error(("%s must stay inside its root, got %q"):format(what, tostring(rel)), 0)
+  end
+  return safe
+end
+
+-- root .. "/" .. rel, with the traversal check in between
+function SafePath.join(root, rel, what)
+  return root .. "/" .. SafePath.require(rel, what or "path")
+end
+
+return SafePath

src/mods/Sandbox.lua

@@ -0,0 +1,228 @@
+-- The environment a mod's own code runs in.  Every chunk a mod authors -- the
+-- entry file, an options_schema, anything it hands to load() -- runs against
+-- this table instead of _G, so the only paths it can name are the ones the
+-- engine hands it (mod:read, mod.storage, mod.assets).
+--
+-- What this is and is not: raw io/os/ffi are the only way to name a file
+-- outside the game tree at all, and they are absent here, so the reported
+-- "any mod can rewrite anything in your home directory" hole closes by
+-- construction.  Inside the LÖVE tree this is defense in depth, not a security
+-- boundary: an engine module reached through require, or ImageData:encode,
+-- still writes in the save directory.
+--
+-- Lua 5.1/LuaJIT is the target, so setfenv is the mechanism; the 5.2+ arm
+-- exists because AssetTransform's sandbox needed it and getting this wrong
+-- silently hands the chunk the real globals.
+
+local Runtime = require("src.mods.Runtime")
+local SafePath = require("src.mods.SafePath")
+
+local Sandbox = {}
+
+-- Modules that hand a mod the disk, a raw socket or a fresh Lua state no
+-- matter what this file removes from the environment.  package.loaded.io is
+-- the one call that would undo every other rule here.
+local DENIED = {
+  io = "the filesystem", os = "the filesystem", debug = "the debug library",
+  package = "the module loader", ffi = "arbitrary C calls",
+}
+
+-- Same idea one level up: love.filesystem is reachable by name, and
+-- love.thread starts a Lua state this sandbox has no say over.
+local DENIED_PREFIX = { ["love"] = true, ["ffi"] = true }
+
+-- The wire, which is what the network permission governs.
+local NETWORK = { socket = true, enet = true, http = true, https = true,
+                  ssl = true, mime = true, ltn12 = true }
+
+local function head(name)
+  return (name:match("^([^%.]+)")) or name
+end
+
+-- nil when the require is allowed, else the message to fail it with.
+function Sandbox.moduleDenial(name, permissionSet)
+  if type(name) ~= "string" then return nil end
+  local root = head(name)
+  local reason = DENIED[root]
+  if reason then
+    return ("%s is not available to mods (it grants %s); use mod.storage, "
+      .. "mod:read and the engine API instead"):format(name, reason)
+  end
+  if DENIED_PREFIX[root] and name ~= root then
+    return ("%s is not available to mods; use mod.storage, mod:read and the "
+      .. "engine API instead"):format(name)
+  end
+  if NETWORK[root] and not (permissionSet or {}).network then
+    return ("%s needs the \"network\" permission in manifest.json"):format(name)
+  end
+  return nil
+end
+
+-- ------- the love facade
+
+-- Dropped, not narrowed: filesystem writes anywhere in the save directory
+-- (including another mod's storage), thread opens a Lua state with a full
+-- standard library, system.openURL launches whatever it is handed, and event
+-- lets a mod quit the game out from under the player.  Everything else LÖVE
+-- exposes passes through, so a new module in a future LÖVE is available
+-- without an edit here.
+-- value is the replacement to name in the error, or true when there is none
+local BLOCKED_LOVE = {
+  filesystem = "mod.storage and mod:read", thread = true,
+  system = "mod.device:powerInfo() for battery information, mod.steps for "
+    .. "the step bridge", event = true,
+}
+
+local loveProxy
+local function loveFacade()
+  if loveProxy or not _G.love then return loveProxy end
+  loveProxy = setmetatable({}, {
+    __index = function(_, key)
+      local hint = BLOCKED_LOVE[key]
+      if hint then
+        error(("love.%s is not available to mods%s"):format(key,
+          type(hint) == "string" and (", use " .. hint) or ""), 2)
+      end
+      return _G.love[key]
+    end,
+    __newindex = function(_, key)
+      error(("mods cannot assign love.%s"):format(tostring(key)), 2)
+    end,
+  })
+  return loveProxy
+end
+
+-- ------- the environment
+
+-- Absent on purpose: io, package, dofile, loadfile, getfenv, setfenv, debug,
+-- newproxy, module.  os keeps only the clock -- getenv is how the reported
+-- exploit found the user's home directory.
+local SAFE_OS = { time = true, date = true, clock = true, difftime = true }
+
+-- Per-mod copies, not the shared tables: a mod that assigns string.trim or
+-- replaces table.insert changes its own view and nobody else's.  The functions
+-- are the same objects, so state behind them (math.randomseed's RNG) is
+-- unaffected -- only the namespace is private.
+local function copy(source)
+  if type(source) ~= "table" then return source end
+  local out = {}
+  for key, value in pairs(source) do out[key] = value end
+  return out
+end
+
+local function baseGlobals()
+  local safeOs = {}
+  for key in pairs(SAFE_OS) do safeOs[key] = os[key] end
+  return {
+    assert = assert, error = error, ipairs = ipairs, next = next,
+    pairs = pairs, pcall = pcall, xpcall = xpcall, select = select,
+    tonumber = tonumber, tostring = tostring, type = type, unpack = unpack,
+    rawequal = rawequal, rawget = rawget, rawset = rawset, rawlen = rawlen,
+    setmetatable = setmetatable, getmetatable = getmetatable, print = print,
+    collectgarbage = collectgarbage, _VERSION = _VERSION,
+    coroutine = copy(coroutine), math = copy(math), string = copy(string),
+    table = copy(table), bit = copy(bit), jit = jit, os = safeOs,
+  }
+end
+
+-- setfenv on 5.1/LuaJIT; on 5.2+ the env has to be handed to load itself, so
+-- a caller there compiles through Sandbox.compile instead.
+function Sandbox.bind(chunk, env)
+  if setfenv then setfenv(chunk, env) end
+  return chunk
+end
+
+-- Bytecode is unreviewable and, on LuaJIT, a way out of any sandbox built out
+-- of environments.  Mods ship source.
+local function rejectBytecode(source, what)
+  if type(source) == "string" and source:sub(1, 1) == "\27" then
+    return nil, (what or "chunk") .. ": mods must ship Lua source, not bytecode"
+  end
+  return true
+end
+
+function Sandbox.compile(source, chunkname, env)
+  local ok, err = rejectBytecode(source, chunkname)
+  if not ok then return nil, err end
+  if setfenv then
+    local chunk, compileErr = loadstring(source, chunkname)
+    if not chunk then return nil, compileErr end
+    return setfenv(chunk, env)
+  end
+  return load(source, chunkname, "t", env)
+end
+
+-- The load() a mod sees.  Lua 5.1 gives a loaded chunk the GLOBAL environment
+-- rather than the caller's, so without this every sandboxed mod is one
+-- load(mod:read(...)) away from the real _G -- which is exactly how the
+-- multi-file mods in mods/ are written.
+local function sandboxedLoad(env)
+  return function(chunk, chunkname)
+    if type(chunk) == "function" then
+      local parts = {}
+      while true do
+        local piece = chunk()
+        if piece == nil or piece == "" then break end
+        parts[#parts + 1] = piece
+      end
+      chunk = table.concat(parts)
+    end
+    if type(chunk) ~= "string" then return nil, "load expects a string or reader" end
+    return Sandbox.compile(chunk, chunkname or "=(load)", env)
+  end
+end
+
+-- The require a mod sees: the deny list lives here rather than on a stack
+-- walk, because pcall(require, "io") puts a C frame where the walk would look.
+-- Runtime.modRequire is how the loader's gate identifies the caller for the
+-- Gen 2 facade once Runtime.currentMod has gone back to nil (a mod requiring
+-- lazily from an event handler).
+local function sandboxedRequire(modId, permissionSet)
+  return function(name, ...)
+    local denial = Sandbox.moduleDenial(name, permissionSet)
+    if denial then error(("[%s] %s"):format(modId or "mod", denial), 2) end
+    local previous = Runtime.modRequire
+    Runtime.modRequire = modId or true
+    local ok, result = pcall(_G.require, name, ...)
+    Runtime.modRequire = previous
+    if not ok then error(result, 0) end
+    return result
+  end
+end
+
+function Sandbox.envFor(opts)
+  opts = opts or {}
+  local env = baseGlobals()
+  env.love = loveFacade()
+  env.require = sandboxedRequire(opts.modId, opts.permissions)
+  local loader = sandboxedLoad(env)
+  env.load = loader
+  env.loadstring = loader
+  -- a mod's globals are its own: two mods no longer share a namespace, and
+  -- neither can reach the engine's
+  env._G = env
+  return env
+end
+
+-- fs.load keeps the real filesystem's handling of the file; the environment is
+-- swapped after the fact.  The 5.2+ arm has to go back to source, which is the
+-- only reason fs.read is touched here.
+function Sandbox.loadFile(fs, path, env)
+  if fs.read then
+    local ok, err = rejectBytecode(fs.read(path), path)
+    if not ok then return nil, err end
+  end
+  if setfenv then
+    local chunk, err = fs.load(path)
+    if not chunk then return nil, err end
+    return setfenv(chunk, env)
+  end
+  local source = fs.read and fs.read(path)
+  if not source then return nil, "unable to read " .. path end
+  return Sandbox.compile(source, "@" .. path, env)
+end
+
+Sandbox.safePath = SafePath.safe
+Sandbox.requirePath = SafePath.require
+
+return Sandbox

src/mods/Steps.lua

@@ -0,0 +1,84 @@
+-- The scoped seam for the native step bridge (#1186).
+--
+-- The iOS/Android builds count the player's real-world steps natively
+-- (#452, #489) and deliver them by writing steps_pending.json into the
+-- save-directory root.  Before the sandbox, the Pokéwalker mod called
+-- love.system.syncHealthSteps() and consumed that file itself; the sandbox
+-- blocks both, which is correct -- love.system launches URLs and the file
+-- API names paths -- but it left the bridge with no consumer at all.
+--
+-- This module is the narrow replacement, gated by the "steps" permission
+-- in manifest.json (the network model: a permission the player sees that
+-- genuinely gates a capability).  The engine owns the file: mods never
+-- learn its name or location, they receive only the three contract fields
+-- ({ steps, from, to }), each permissioned mod gets its own copy, and the
+-- merge-don't-overwrite anchor semantics stay on the native side where
+-- they always lived.
+--
+-- No frame pump: the file is looked for lazily when a mod polls, so a
+-- build with no permissioned mod installed never touches the bridge or
+-- the disk.
+
+local Json = require("src.link.Json")
+
+local Steps = {}
+
+-- The native contract's drop point, in the save-directory root (see
+-- mobile/ios and mobile/android step bridges).
+Steps.PENDING = "steps_pending.json"
+
+local function bridge()
+  return _G.love and _G.love.system and _G.love.system.syncHealthSteps
+end
+
+-- Whether this build carries the native bridge.  Desktop builds do not;
+-- a mod uses this to stay dormant without probing love.system.
+function Steps.available()
+  return bridge() ~= nil
+end
+
+-- Ask the native side to refresh its count.  Async: the result lands in
+-- the pending file and comes back through a later poll.  The platform's
+-- own consent sheet (HealthKit / ACTIVITY_RECOGNITION) still appears on
+-- first use, exactly as it did pre-sandbox.  false when there is no
+-- bridge to ask.
+function Steps.sync()
+  local fn = bridge()
+  if not fn then return false end
+  fn()
+  return true
+end
+
+-- Consume the pending file, if one has appeared, and fan its payload out
+-- to every permissioned mod's queue.  Only the contract fields travel;
+-- anything else in the file stays in the file's grave.  A malformed or
+-- empty delivery is dropped whole -- the native anchor only advances on a
+-- successful sync, so nothing is lost to a bad write.
+function Steps.pump(loader)
+  local fs = _G.love and _G.love.filesystem
+  if not (fs and fs.getInfo(Steps.PENDING, "file")) then return end
+  local raw = fs.read(Steps.PENDING)
+  fs.remove(Steps.PENDING)
+  if not raw then return end
+  local ok, decoded = pcall(Json.decode, raw)
+  if not ok or type(decoded) ~= "table" then return end
+  local steps = tonumber(decoded.steps)
+  if not steps or steps <= 0 then return end
+  local payload = { steps = steps, from = decoded.from, to = decoded.to }
+  for _, queue in pairs(loader.stepsQueues) do
+    queue[#queue + 1] = { steps = payload.steps, from = payload.from,
+                          to = payload.to }
+  end
+end
+
+-- The next delivery for this mod, or nil.  Each permissioned mod consumes
+-- its own queue, so two mods both see the same walk (pre-sandbox, whoever
+-- read the file first won).
+function Steps.poll(loader, modId)
+  Steps.pump(loader)
+  local queue = loader.stepsQueues[modId]
+  if not queue then return nil end
+  return table.remove(queue, 1)
+end
+
+return Steps

src/pokemon/Evolution.lua

@@ -140,9 +140,12 @@ function Evolution.learnEvolutionMoves(game, mon, onDone)
     if #mon.moves < 4 then
       table.insert(mon.moves, { id = moveId, pp = mdef.pp })
       Runtime.emit("pokemon.move_learned", { mon = mon, moveId = moveId })
+      -- LearnedMove1Text: text_far, sound_get_item_1, text_promptbutton
+      -- (learn_move.asm), so the jingle rides the box
       game.stack:push(TextBox.new(game,
         romText(game.data, "_LearnedMove1Text",
-          "%s learned\n%s!", name, mdef.name), nextStep))
+          "%s learned\n%s!", name, mdef.name), nextStep,
+        TextBox.soundOpts(game, "Get_Item1")))
     else
       -- LearnMoveFromLevelUp with a full moveset: the forget UI
       Screens.push(game, "MoveLearnMenu", mon, moveId, nextStep)

src/render/HudTiles.lua

@@ -141,13 +141,20 @@ end
 -- Tinting first would double-apply the color: GREENBAR's fill {0,189,0} has
 -- red channel 0, so the tint zeroes the whole bar's red and the zone's
 -- red-channel-keyed shade shader then maps every pixel to color 3 = black.
-function HudTiles.drawHPBar(data, tx, ty, mon, barType, grayFill, segments)
+--
+-- pixels: an explicit 0..48 bar length on GetHPBarLength's scale, for a
+-- caller that is animating the bar between two HP values
+-- (UpdateHPBar_AnimateHPBar); it scales with `segments` like the color
+-- thresholds do.  Without it the length comes from mon.hp as before.
+function HudTiles.drawHPBar(data, tx, ty, mon, barType, grayFill, segments, pixels)
   local x, y = tx * 8, ty * 8
   segments = math.max(1, math.floor(segments or 6))
   HudTiles.tile(0x71, x, y)
   HudTiles.tile(0x62, x + 8, y)
   local px = 0
-  if mon.stats.hp > 0 and mon.hp > 0 then
+  if pixels then
+    px = math.max(0, math.floor(pixels * segments / 6))
+  elseif mon.stats.hp > 0 and mon.hp > 0 then
     px = math.max(1, math.floor(mon.hp * segments * 8 / mon.stats.hp))
   end
   local tint

src/render/PaletteFX.lua

@@ -691,10 +691,12 @@ function PaletteFX.spriteObp(spriteDef, seed)
   return PaletteFX.darkObp(w.spritePalettes[group], group)
 end
 
--- GetHealthBarColor (home/palettes.asm) on the standard 48px bar
-function PaletteFX.barPalName(hp, maxHp)
-  local px = maxHp > 0 and math.floor(hp * 48 / maxHp) or 0
-  if hp > 0 and px < 1 then px = 1 end
+-- GetHealthBarColor (home/palettes.asm) on the standard 48px bar.  It reads
+-- the bar's own length, so a caller mid-drain passes the animated `pixels`
+-- rather than let it be re-derived from hp.
+function PaletteFX.barPalName(hp, maxHp, pixels)
+  local px = pixels or (maxHp > 0 and math.floor(hp * 48 / maxHp) or 0)
+  if not pixels and hp > 0 and px < 1 then px = 1 end
   return px >= 27 and "GREENBAR" or px >= 10 and "YELLOWBAR" or "REDBAR"
 end
 

src/render/Renderer.lua

@@ -768,11 +768,12 @@ function Renderer:endFrame(zones, worldZones)
     end
   end
 
-  -- A post-process pipeline needs the whole composite in a canvas for the
-  -- same reason GBC FX does, so either one alone is enough to take the
-  -- present path; with neither, the frame draws straight to the screen
-  -- exactly as it always did.
-  local needPresent = GBCFX.active() or Pipelines.wantsPresent()
+  -- Post-process pipelines, GBC FX and an enabled final-output owner need the
+  -- whole composite in a canvas. With none of them, the frame draws straight
+  -- to the screen exactly as it always did.
+  local hasOutputHook = Runtime.wantsHook("render.output")
+    and Runtime.call("render.output_enabled", function() return false end) == true
+  local needPresent = GBCFX.active() or Pipelines.wantsPresent() or hasOutputHook
   local present = nil
   if needPresent then
     if not self.presentCanvas or self.presentCanvas:getWidth() ~= ww
@@ -1057,14 +1058,25 @@ function Renderer:endFrame(zones, worldZones)
     -- this returns `present` unchanged and the frame is byte-identical.
     local composed = Pipelines.present(present,
       { width = ww, height = wh, scale = Sp, dpi = dpiY, dpiX = dpiX, dpiY = dpiY }) or present
-    if GBCFX.active() then
-      -- shader grid/shadow math is in framebuffer pixels
-      GBCFX.present(composed, Sp)
-    else
-      -- the present canvas only existed for the post-process, so put the
-      -- result on the screen at the same 1:1 unit mapping it was built at
-      love.graphics.setColor(1, 1, 1, 1)
-      love.graphics.draw(composed, 0, 0)
+    local outputHandled = hasOutputHook
+      and Runtime.call("render.output", function() return false end, {
+        canvas = composed,
+        width = ww, height = wh,
+        gameX = ox, gameY = oy,
+        gameWidth = vpw, gameHeight = vph,
+        scale = Sp, dpiX = dpiX, dpiY = dpiY,
+        generation = 1,
+      }) == true
+    if not outputHandled then
+      if GBCFX.active() then
+        -- shader grid/shadow math is in framebuffer pixels
+        GBCFX.present(composed, Sp)
+      else
+        -- the present canvas only existed for the post-process, so put the
+        -- result on the screen at the same 1:1 unit mapping it was built at
+        love.graphics.setColor(1, 1, 1, 1)
+        love.graphics.draw(composed, 0, 0)
+      end
     end
   end
   self.worldActive = false

src/render/SpriteRenderer.lua

@@ -62,6 +62,8 @@ local function getObpImage(path, colors, group)
   return obpCache[key]
 end
 
+SpriteRenderer.obpImage = getObpImage
+
 -- hot reload drops the sheets; live instances hold their own image, so
 -- the world rebuilds them (MapLoader.invalidateAll) rather than this
 function SpriteRenderer.invalidate()
@@ -281,7 +283,7 @@ end
 -- swapped and OAM_XFLIP on each (data/sprites/facings.asm:192-197).  Optional
 -- and trailing, so every existing call site is unchanged.
 function SpriteRenderer:draw(px, py, camX, camY, facing, walkPhase, stepFlip,
-    topHalf, forceFlip)
+    topHalf, forceFlip, frameOverride)
   local x, y = self:getScreenOrigin(px, py, camX, camY)
   local image = self.image
   local redraw = false
@@ -329,6 +331,9 @@ function SpriteRenderer:draw(px, py, camX, camY, facing, walkPhase, stepFlip,
   -- still 3-frame sprites turn to face (the nurse at her machine,
   -- facePlayer on STAY NPCs) but never show walk frames.
   local frame, flip = pose(self, facing, walkPhase, stepFlip)
+  if frameOverride and self.frames[frameOverride] then
+    frame, flip = frameOverride, false
+  end
   if forceFlip then flip = true end
   local quad = self.frames[frame]
   local drawHeight = self.frameHeight

src/render/TextBox.lua

@@ -7,7 +7,7 @@
 -- the text is exhausted and A is pressed, then calls onDone.
 
 local Font = require("src.render.Font")
-local Runtime = require("src.mods.Runtime")
+local UIVisibility = require("src.battle.UIVisibility")
 local Theme = require("src.ui.Theme")
 local Timing = require("src.core.Timing")
 
@@ -100,6 +100,26 @@ function TextBox.new(game, text, onDone, opts)
   return self
 end
 
+-- soundOpts: a jingle carried at the end of the string as a trailing text
+-- command (sound_get_item_1 and friends -> home/text.asm TextCommand_SOUND),
+-- which runs PlaySound then WaitForSoundToFinish once the last page has
+-- typed, so the box holds until the fanfare is over.  Merges into a caller's
+-- opts table; auto.wait keeps the trailing button press the plain A/B path
+-- gives every other box.
+function TextBox.soundOpts(game, sound, opts)
+  opts = opts or {}
+  local auto = opts.auto
+  -- auto = true is the no-button-wait arming (text_opts); keep that choice
+  if auto == true then auto = { wait = false } end
+  auto = auto or {}
+  if auto.wait == nil then auto.wait = true end
+  auto.delay = auto.delay or 0
+  auto.sound = type(sound) == "function" and sound
+    or function() return require("src.core.Sound").play(game.data, sound) end
+  opts.auto = auto
+  return opts
+end
+
 -- The runtime tokens substitute() knows, as handlers the tokens registry
 -- serves.  Each is fn(game, arg) -> replacement, or nil to drop the token.
 -- RAM keeps pokered's stale-buffer semantics: give_item copies the item
@@ -130,6 +150,7 @@ TextBox.TOKENS = {
   STRBUF = function(game) return game.stringBuffer end,
   RAM = function(game, arg)
     if arg == "wStringBuffer" then return game.stringBuffer end
+    if arg == "wNameBuffer" then return game.stringBuffer end
     if arg == "wBoxNumString" then return game.boxNumString end
     -- SendNewMonToBox / _SentToBoxText reads the deposited nick here
     if arg == "wBoxMonNicks" then return game.boxMonNicks end
@@ -393,11 +414,7 @@ function TextBox:update(dt)
 end
 
 function TextBox:draw()
-  if Runtime.wantsHook("battle.bottom_ui_visible")
-      and Runtime.call("battle.bottom_ui_visible", function() return true end,
-                       self) == false then
-    return
-  end
+  if not UIVisibility.bottomVisible(self, true) then return end
   -- The dialogue box belongs against the bottom of the screen, not floating
   -- in the middle of a zoomed-out letterbox.  Declared per frame; the
   -- renderer blits this region to the screen edge and the rest of the UI