Merge pull request #1234 from bryanthaboi/dev

bugs and slugs

.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:
@@ -355,6 +356,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 +444,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 +464,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 +580,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 +602,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 +624,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"

CONTRIBUTING-mods.md

@@ -242,48 +242,7 @@ 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. 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`
+### 5. `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,
@@ -304,7 +263,7 @@ Two fields deserve their own note:
   distributed mod never carries ROM-derived bytes, not even in its preview
   images.
 
-### 7. Tags
+### 6. 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/oaks_lab.lua

@@ -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

@@ -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" },
     },
   },
 }
@@ -1058,6 +1061,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 +1071,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 +1237,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

@@ -413,6 +413,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

data/scripts/story4.lua

@@ -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,
   },
@@ -512,24 +512,29 @@ 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()
+          require("src.core.Sound").play(game.data, "Get_Item1")
+          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)
+          game.stringBuffer = game.data.items.NUGGET.name
+          push(game, t._Route24CooltrainerM1ReceivedNuggetText, function()
+            require("src.core.Sound").play(game.data, "Get_Item1")
+            push(game, t._Route24CooltrainerM1JoinTeamRocketText,
+              battleOrDone)
+          end)
         end)
         return
       end

data/scripts/story5.lua

@@ -508,12 +508,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 +567,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 +596,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 +621,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 +734,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 +780,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 +799,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 +874,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 +910,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")

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

docs/modding.md

@@ -340,6 +340,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
@@ -442,9 +454,12 @@ 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.
+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 +510,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,41 +544,3 @@ 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,7 +19,6 @@ 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**
@@ -28,8 +27,7 @@ Features intentionally added beyond the original Pokémon Red, Blue, and Yellow
 
 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:
 
-* **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**
@@ -40,5 +38,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

@@ -260,18 +260,13 @@ selected game reads `Needs <id> (not for Gold)` rather than `Ready`.
 
 ### 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

@@ -1,49 +0,0 @@
-# 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

@@ -1,68 +0,0 @@
-# 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,38 @@
 {
-  "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.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

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

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

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

@@ -357,6 +357,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"

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"

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()
@@ -613,6 +613,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 +930,11 @@ 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
+
 -- sayNext for a page that ends in `text_end` (see sayAuto) (#765)
 function BattleState:sayNextAuto(text, delay)
   self.nextInsert = (self.nextInsert or 0) + 1
@@ -1255,13 +1261,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 +1367,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
@@ -1746,6 +1757,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
@@ -1962,6 +1974,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 +2056,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 +2082,7 @@ function BattleState:update(dt)
         self.phase = "messages"
         self.afterQueue = "menu"
       else
+        self.playerMoveListIndex = self.moveIndex
         self:resolveTurn(mv)
       end
     end
@@ -2412,11 +2438,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 +2448,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)
@@ -2934,7 +2960,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
@@ -3828,9 +3854,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 +3883,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))
@@ -4118,15 +4147,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
 
@@ -5780,6 +5811,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/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/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

@@ -109,6 +109,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 +689,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
@@ -1441,8 +1463,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 +1476,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 +1529,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 +1929,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/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/LauncherView.lua

@@ -100,6 +100,7 @@ end
 -- other half of that guarantee.
 function LauncherView.update(imp, dt)
   if not imp._flex then return end
+  if imp._launchFade then return end
 
   local down = false
   if love.mouse and love.mouse.isDown then
@@ -312,6 +313,236 @@ local function cartColor(version)
   return CART_COLOR[version] or PAL.green
 end
 
+local CART_DRAG_SLOP = 8
+local TAU = math.pi * 2
+
+local function cartridgeState(imp, version)
+  imp._cartridge = imp._cartridge or {}
+  local state = imp._cartridge[version]
+  if not state then
+    state = { spin = 0, lastTime = Kit.time }
+    imp._cartridge[version] = state
+  end
+  return state
+end
+
+local function cartridgeLabel(imp, version)
+  imp._cartridgeLabels = imp._cartridgeLabels or {}
+  local label = imp._cartridgeLabels[version]
+  if label ~= nil then return label or nil end
+  local ok, image = pcall(love.graphics.newImage,
+    "assets/labels/" .. tostring(version) .. ".png")
+  if not ok then
+    imp._cartridgeLabels[version] = false
+    return nil
+  end
+  local iw, ih = image:getDimensions()
+  label = { image = image, width = iw, height = ih }
+  imp._cartridgeLabels[version] = label
+  return label
+end
+
+local function cartProject(cx, cy, yaw, pitch, x, y, z)
+  local cyaw, syaw = math.cos(yaw), math.sin(yaw)
+  local cpitch, spitch = math.cos(pitch), math.sin(pitch)
+  local rx = x * cyaw + z * syaw
+  local rz = -x * syaw + z * cyaw
+  local ry = y * cpitch - rz * spitch
+  rz = y * spitch + rz * cpitch
+  local perspective = 620 / (620 - rz)
+  return cx + rx * perspective, cy + ry * perspective
+end
+
+local function cartPolygon(points, color, alpha)
+  local flat = {}
+  for i = 1, #points do
+    flat[#flat + 1], flat[#flat + 2] = points[i][1], points[i][2]
+  end
+  Theme.col(color, alpha or 1)
+  love.graphics.polygon("fill", flat)
+end
+
+local function cartQuad(project, x, y, w, h, z)
+  return {
+    { project(x, y, z) }, { project(x + w, y, z) },
+    { project(x + w, y + h, z) }, { project(x, y + h, z) },
+  }
+end
+
+local function cartPill(project, x, y, w, h, z, color, alpha)
+  local points, radius = {}, h / 2
+  for i = 0, 10 do
+    local a = math.pi + math.pi * i / 10
+    points[#points + 1] = { project(x + radius + math.cos(a) * radius,
+      y + radius + math.sin(a) * radius, z) }
+  end
+  for i = 0, 10 do
+    local a = math.pi * i / 10
+    points[#points + 1] = { project(x + w - radius + math.cos(a) * radius,
+      y + radius + math.sin(a) * radius, z) }
+  end
+  cartPolygon(points, color, alpha)
+end
+
+local function cartLabelMesh(imp, version, label, points)
+  if not love.graphics.newMesh then return nil end
+  imp._cartridgeLabelMeshes = imp._cartridgeLabelMeshes or {}
+  local mesh = imp._cartridgeLabelMeshes[version]
+  if not mesh then
+    mesh = love.graphics.newMesh({
+      { 0, 0, 0, 0, 255, 255, 255, 255 },
+      { 0, 0, 1, 0, 255, 255, 255, 255 },
+      { 0, 0, 1, 1, 255, 255, 255, 255 },
+      { 0, 0, 0, 1, 255, 255, 255, 255 },
+    }, "fan", "dynamic")
+    mesh:setTexture(label.image)
+    imp._cartridgeLabelMeshes[version] = mesh
+  end
+  mesh:setVertices({
+    { points[1][1], points[1][2], 0, 0, 255, 255, 255, 255 },
+    { points[2][1], points[2][2], 1, 0, 255, 255, 255, 255 },
+    { points[3][1], points[3][2], 1, 1, 255, 255, 255, 255 },
+    { points[4][1], points[4][2], 0, 1, 255, 255, 255, 255 },
+  })
+  return mesh
+end
+
+local function cartridgeButton(imp, x, y, w, h, key, version, gameName, action)
+  local state = cartridgeState(imp, version)
+  local focused = Kit.focusable(key, x, y, w, h)
+  local hot = Kit.hover(x, y, w, h)
+  local active = state.active
+  local cx, cy = x + w / 2, y + h / 2
+
+  if Kit.mouseClicked and Kit.hit(x, y, w, h) and not Kit.blockClicks then
+    if Kit.mouseDown then
+      state.active = true
+      state.startX, state.startY = Kit.mouseX, Kit.mouseY
+      state.lastDragX, state.lastDragY = Kit.mouseX, Kit.mouseY
+      state.dragged = false
+      active = true
+    else
+      queueAction(imp, key, action)
+    end
+  end
+
+  if state.active then
+    active = true
+    if Kit.mouseDown then
+      local movedX, movedY = Kit.mouseX - state.startX, Kit.mouseY - state.startY
+      if movedX * movedX + movedY * movedY > CART_DRAG_SLOP * CART_DRAG_SLOP then
+        state.dragged = true
+      end
+      if state.dragged then
+        local dragX = Kit.mouseX - (state.lastDragX or Kit.mouseX)
+        local dragY = Kit.mouseY - (state.lastDragY or Kit.mouseY)
+        state.spin = state.spin + dragX * 0.018
+        state.pitchDrag = clamp((state.pitchDrag or 0) + dragY * 0.010,
+          -1.20, 1.20)
+      end
+      state.lastDragX, state.lastDragY = Kit.mouseX, Kit.mouseY
+    else
+      if not state.dragged then queueAction(imp, key, action) end
+      state.active, active = nil, false
+      state.dragged = nil
+    end
+  end
+
+  local dt = math.min(0.08, math.max(0, Kit.time - (state.lastTime or Kit.time)))
+  state.lastTime = Kit.time
+  if not state.active then
+    local upright = math.floor(state.spin / TAU + 0.5) * TAU
+    state.spin = state.spin + (upright - state.spin) * math.min(1, dt * 4)
+    state.pitchDrag = (state.pitchDrag or 0)
+      * (1 - math.min(1, dt * 4))
+  end
+  local pointerX = clamp((Kit.mouseX - cx) / math.max(1, w / 2), -1, 1)
+  local pointerY = clamp((Kit.mouseY - cy) / math.max(1, h / 2), -1, 1)
+  local hoverTilt = hot and pointerX * 0.12 or math.sin(Kit.time * 0.75) * 0.035
+  local pressX = active and pointerX * w * 0.025 or 0
+  local pressY = active and pointerY * h * 0.018 or 0
+  local yaw = -0.42 + state.spin + hoverTilt
+  local pitch = 0.14 + (state.pitchDrag or 0)
+    + (hot and pointerY * 0.08 or math.sin(Kit.time * 0.6) * 0.018)
+  local pressedScale = active and 0.965 or 1
+
+  Kit._audit("control", x, y, w, h, key)
+  if focused then
+    Theme.strokeRounded(x - 3, y - 3, w + 6, h + 6, PAL.lineStrong,
+      Theme.A.focus, 2, Theme.cardRadius() + 2)
+  end
+
+  local halfW, halfH = w / 2, h / 2
+  local depth = math.max(8, w * 0.14)
+  local project = function(px, py, pz)
+    return cartProject(cx + pressX, cy + pressY, yaw, pitch,
+      px * pressedScale, py * pressedScale, pz * pressedScale)
+  end
+
+  local capH = h * 3 / 65
+  local mainTop = -halfH + capH
+  local capRight = halfW - w * 5 / 57
+  local mainFront = cartQuad(project, -halfW, mainTop, w, h - capH, depth)
+  local mainBack = cartQuad(project, -halfW, mainTop, w, h - capH, -depth)
+  local capFront = cartQuad(project, -halfW, -halfH,
+    capRight + halfW, capH, depth)
+  local capBack = cartQuad(project, -halfW, -halfH,
+    capRight + halfW, capH, -depth)
+  local shell = cartColor(version)
+  local side = { math.floor(shell[1] * 0.54), math.floor(shell[2] * 0.54),
+    math.floor(shell[3] * 0.54) }
+
+  cartPolygon(mainBack, side, 1)
+  cartPolygon(capBack, side, 1)
+  cartPolygon({ mainFront[2], mainFront[3], mainBack[3], mainBack[2] }, side, 1)
+  cartPolygon({ mainFront[3], mainFront[4], mainBack[4], mainBack[3] }, side, 1)
+  cartPolygon({ mainFront[1], mainFront[2], mainBack[2], mainBack[1] }, side, 1)
+  cartPolygon({ capFront[2], capFront[3], capBack[3], capBack[2] }, side, 1)
+  cartPolygon({ capFront[1], capFront[2], capBack[2], capBack[1] }, side, 1)
+  cartPolygon({ capFront[4], capFront[1], capBack[1], capBack[4] }, side, 1)
+  cartPolygon(mainFront, shell, 1)
+  cartPolygon(capFront, shell, 1)
+
+  local faceZ = depth + 0.8
+  for i = 0, 4 do
+    local ry = mainTop + 7 + i * h * 0.025
+    cartPolygon(cartQuad(project, -halfW + 2, ry, w * 0.13, 2, faceZ), side, 0.7)
+    cartPolygon(cartQuad(project, halfW - w * 0.13 - 2, ry, w * 0.13, 2, faceZ), side, 0.7)
+  end
+  local recessX, recessY = -w * 0.32, mainTop + h * 0.023
+  local recessW, recessH = w * 0.64, h * 0.24
+  cartPolygon(cartQuad(project, recessX, recessY, recessW, recessH, faceZ), shell, 0.88)
+  cartPill(project, recessX + w * 0.025, recessY + h * 0.025,
+    recessW - w * 0.05, h * 0.12, faceZ + 0.5, shell, 0.7)
+  cartPill(project, recessX + w * 0.045, recessY + h * 0.043,
+    recessW - w * 0.09, h * 0.083, faceZ + 0.8, side, 0.42)
+
+  local labelX, labelY = -w * 0.33, -h * 0.20
+  local labelW, labelH = w * 0.66, h * 0.55
+  local plate = cartQuad(project, labelX - 2, labelY - 2, labelW + 4, labelH + 4, faceZ + 0.8)
+  cartPolygon(plate, side, 0.95)
+  local labelPoints = cartQuad(project, labelX, labelY, labelW, labelH, faceZ + 1.2)
+  local label = cartridgeLabel(imp, version)
+  local mesh = label and cartLabelMesh(imp, version, label, labelPoints)
+  if mesh then
+    love.graphics.setColor(1, 1, 1, 1)
+    love.graphics.draw(mesh)
+  elseif label then
+    local artScale = math.min(labelW / label.width, labelH / label.height)
+    love.graphics.draw(label.image, labelPoints[1][1], labelPoints[1][2],
+      0, artScale, artScale)
+  end
+  cartPolygon({
+    { project(-w * 0.07, h * 0.37, faceZ + 1) },
+    { project(w * 0.07, h * 0.37, faceZ + 1) },
+    { project(0, h * 0.43, faceZ + 1) },
+  }, side, 0.70)
+
+  if not state.active and (Kit._activateId == key) then
+    queueAction(imp, key, action)
+  end
+end
+
 local function modStatusColor(status)
   if status == "ok" then return Strings("Ready"), PAL.green end
   if status == "conflict" then return Strings("Conflict"), PAL.red end
@@ -1011,8 +1242,16 @@ local function buildGamePanel(imp, x, y, w, availH, m, version)
   else tagText, tagCol = Strings("ROM REQUIRED"), PAL.yellow end
   local tagW = Kit.textWidth("micro", tagText) + math.floor(18 * m.s)
   local tagH = Kit.textHeight("micro") + math.floor(10 * m.s)
-  Kit.tag(x + Kit.textWidth("title", Kit.ellipsize("title", gameName, w * 0.6))
-    + math.floor(12 * m.s), y + (titleH - tagH) / 2, tagW, tagH, tagText, tagCol)
+  local tagX = x + Kit.textWidth("title", Kit.ellipsize("title", gameName, w * 0.6))
+    + math.floor(12 * m.s)
+  Kit.tag(tagX, y + (titleH - tagH) / 2, tagW, tagH, tagText, tagCol)
+  if ready then
+    local hint = Strings("(PRESS THE CART TO PLAY)")
+    local hintX = tagX + tagW + math.floor(10 * m.s)
+    local hintW = math.max(0, x + w - hintX)
+    Kit.text("micro", Kit.ellipsize("micro", hint, hintW), hintX,
+      y + (titleH - Kit.textHeight("micro")) / 2, PAL.heading)
+  end
   local cy = y + titleH + math.floor(12 * m.s)
   local remaining = availH - (titleH + math.floor(12 * m.s))
 
@@ -1038,25 +1277,20 @@ local function buildGamePanel(imp, x, y, w, availH, m, version)
   local ly = cy
 
   if ready then
-    -- Play IS the panel: it takes the space the ROM buttons used to hold, at
-    -- the top of the column where the eye lands, wearing this game's own
-    -- cartridge colour rather than a generic green.
-    -- Play grows into the room the column has: it is the one thing on this
-    -- screen the player came for, and the space freed by moving ROM and
-    -- control management out belongs to it rather than to a gap.  Clamped at
-    -- both ends so a short window still gets a real button and a tall one
-    -- does not get a billboard.
-    local playH = math.floor(clamp(remaining * 0.30, 64 * m.s, 132 * m.s))
-    local mgW = playH
+    -- The cartridge takes the Play button's former place.  Its portrait
+    -- ratio comes from a real Game Boy cart rather than stretching the old
+    -- horizontal control, and its body colour comes from the active game.
+    local playH = math.floor(clamp(remaining * 0.52, 112 * m.s, 260 * m.s))
+    local mgW = math.max(Kit.tapMin(), math.floor(34 * m.s))
     local bgap = math.floor(8 * m.s)
-    btn(imp, lx, ly, lw - mgW - bgap, playH, "play-" .. version,
-      Strings("Play ") .. gameName, {
-        fill = cartColor(version), ink = PAL.inverse, font = "stat",
-        action = function() imp:play(version) end,
-      })
+    local cartAreaW = lw - mgW - bgap
+    local cartW = math.min(cartAreaW, math.floor(playH * 0.88))
+    local cartX = lx + math.floor((cartAreaW - cartW) / 2)
+    cartridgeButton(imp, cartX, ly, cartW, playH, "play-" .. version,
+      version, gameName, function() imp:play(version, true) end)
     imp._gearIcon = imp._gearIcon
       or love.graphics.newImage("assets/launcher/gear.png")
-    iconButton(imp, "manage-" .. version, lx + lw - mgW, ly, playH,
+    iconButton(imp, "manage-" .. version, lx + lw - mgW, ly, mgW,
       imp._gearIcon, function() imp._gameManage = version end)
     ly = ly + playH + gap
   end
@@ -1139,6 +1373,28 @@ local function drawCheck(x, y, size, color)
   love.graphics.pop()
 end
 
+-- One compact coloured checkbox for each game.  The cartridge colour carries
+-- the game identity even when the row is narrow; the letter keeps an unchecked
+-- box legible without relying on colour alone.
+local function modGameCheckbox(x, y, size, checked, game, id)
+  local color = cartColor(game)
+  local focused = Kit.focusable(id, x, y, size, size)
+  local hot = focused or Kit.hover(x, y, size, size)
+  if love.graphics then
+    if checked then
+      Theme.fillRounded(x, y, size, size, color, 1)
+      drawCheck(x, y, size, PAL.inverse)
+    else
+      Theme.fillRounded(x, y, size, size, PAL.bg, 1)
+      Kit.textCenterBold("micro", game:sub(1, 1):upper(), x,
+        y + (size - Kit.textHeight("micro")) / 2, size, color)
+    end
+    Theme.strokeRounded(x, y, size, size, color,
+      hot and Theme.A.focus or Theme.A.hover, 1)
+  end
+  return Kit.press(x, y, size, size) or Kit._activateId == id
+end
+
 local function buildModsPanel(imp, x, y, w, availH, m)
   imp:_ensureMods()
   local ModUpdate = require("src.mods.ModUpdate")
@@ -1225,15 +1481,14 @@ local function buildModsPanel(imp, x, y, w, availH, m)
     mods = sorted
   end
 
-  -- A mod row is a fixed height: name line, version + status line, one line
-  -- of description, and an action row.  Fixed because a page of uniform rows
-  -- is what lets perPage come from the viewport.
-  local chipH = math.max(Kit.tapMin(), math.floor(30 * m.s))
-  -- Text block on the left, chips right-aligned beside it: one row, not a
-  -- text block with a button strip stacked under it.
+  -- A mod row is a fixed height: its details first, then a dedicated second
+  -- line of per-game checkboxes.  Fixed because a page of uniform rows is
+  -- what lets perPage come from the viewport.
+  local togH = math.floor(26 * m.s)
+  local gamesLabel = Strings("Enable for:")
   local textH = Kit.textHeight("button") + math.floor(4 * m.s)
     + Kit.textHeight("small") + math.floor(2 * m.s) + Kit.textHeight("small")
-  local rowH = math.floor(8 * m.s) + math.max(textH, chipH)
+  local rowH = math.floor(8 * m.s) + textH + math.floor(8 * m.s) + togH
     + math.floor(8 * m.s)
   local pagerH = math.max(Kit.tapMin(), math.floor(30 * m.s))
   local listH = availH - (cy - y) - pagerH - gap
@@ -1258,28 +1513,36 @@ local function buildModsPanel(imp, x, y, w, availH, m)
     local px, inner = x + pad, w - 2 * pad
     local ly = ry + math.floor(10 * m.s)
 
-    local togW = math.floor(56 * m.s)
-    local togH = math.floor(26 * m.s)
+    local togGap = math.floor(4 * m.s)
     local info = mod.github and mod.github ~= "" and imp:_modUpdateInfo(mod.id)
 
-    local togKey = "mod-toggle-" .. mod.id
-    -- The toggle reports its own new value, but the importer owns the state:
-    -- queue the flip and let _toggleMod (which may raise an experimental-mod
-    -- confirm) decide what actually happens.
-    local _, flipped = Kit.toggle(px + inner - togW,
-      ry + (rowH - togH) / 2, togW, togH, mod.enabled, togKey)
-    if flipped then
-      queueAction(imp, togKey, function() imp:_toggleMod(mod.id) end)
+    -- These answer separate games, not a single shared install flag.  The
+    -- importer receives the game id so an experimental confirmation also
+    -- applies only to the checkbox the player pressed.
+    local flipped = false
+    local gamesY = ry + math.floor(8 * m.s) + textH + math.floor(8 * m.s)
+    Kit.text("micro", gamesLabel, px,
+      gamesY + (togH - Kit.textHeight("micro")) / 2, PAL.muted)
+    local tx = px + Kit.textWidth("micro", gamesLabel) + math.floor(10 * m.s)
+    for _, game in ipairs(GameVersion.ORDER) do
+      local togKey = "mod-toggle-" .. mod.id .. "-" .. game
+      if modGameCheckbox(tx, gamesY, togH,
+          mod.enabledByVersion and mod.enabledByVersion[game] == true,
+          game, togKey) then
+        local version = game
+        queueAction(imp, togKey, function() imp:_toggleMod(mod.id, nil, version) end)
+        flipped = true
+      end
+      tx = tx + togH + togGap
     end
-    -- The toggle sits inside the row's rect, so its press also passes the
-    -- row's hit test; `flipped` gates the row action to everywhere else.
+    -- The checkboxes sit inside the row's rect, so their press also passes the
+    -- row hit test; `flipped` gates the row action to everywhere else.
     if not flipped
         and (Kit.press(x, ry, w, rowH) or Kit._activateId == rowKey) then
       local id = mod.id
       queueAction(imp, rowKey, function() imp._modActions = id end)
     end
-    local chipsW = togW + math.floor(6 * m.s)
-    local textW = inner - chipsW - math.floor(12 * m.s)
+    local textW = inner
 
     local badgeW = Kit.textWidth("micro", mod.badge) + math.floor(12 * m.s)
     -- the games the mod is for, beside its category: the same chip the
@@ -1741,7 +2004,7 @@ local function buildConfirmModal(imp, m)
         elseif c.kind == "importOversize" then
           imp:_importSave(c.version, c.source, true)
         else
-          imp:_toggleMod(c.id, true)
+          imp:_toggleMod(c.id, true, c.version)
         end
       end,
     })
@@ -2608,6 +2871,11 @@ function LauncherView.draw(imp)
     end
   end
 
+  if imp._launchFade then
+    Theme.fill(0, 0, m.W, m.H, PAL.bg,
+      math.min(1, imp._launchFade.elapsed / imp._launchFade.duration))
+  end
+
   Kit.endFrame()
   drawPadCursor(imp)
 end

src/import/RomImporter.lua

@@ -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
 
@@ -2044,6 +2048,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 +2445,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 +2646,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 +2667,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
@@ -2734,6 +2759,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
@@ -2937,6 +2969,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 +3079,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 +3099,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 +3111,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
 
@@ -3586,7 +3629,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 +3637,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/mods/AssetTransform.lua

@@ -16,7 +16,6 @@
 
 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
@@ -32,8 +31,25 @@ AssetTransform.SOURCE_ROOT = SOURCE_ROOT
 AssetTransform.DERIVED_ROOT = DERIVED_ROOT
 
 -- ------- path sandbox
--- shared with mod:read and the manifest's own paths (src/mods/SafePath.lua)
-local requireRelative = SafePath.require
+
+-- 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
 
 -- ------- the restricted context
 

src/mods/LauncherMods.lua

@@ -36,6 +36,7 @@ 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 = {}
@@ -107,8 +108,9 @@ 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 +128,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,6 +153,14 @@ 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,
@@ -281,7 +290,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,10 +380,8 @@ 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))
@@ -384,7 +398,15 @@ 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)
   return true
@@ -843,7 +865,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 +894,19 @@ 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

src/mods/Loader.lua

@@ -12,15 +12,12 @@ 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
@@ -75,12 +72,10 @@ local function orderedIds(mods, filter)
   return ids
 end
 
--- ------- 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.
+-- ------- 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.
 
 local devShim = { installed = false, permissions = {}, warned = {}, depth = 0 }
 
@@ -140,8 +135,7 @@ end
 
 local function scanRequire(name)
   local modId = Runtime.currentMod
-  if type(modId) ~= "string" then modId = Runtime.modRequire end
-  if type(modId) ~= "string" or type(name) ~= "string" then return end
+  if not modId or type(name) ~= "string" then return end
   local granted = devShim.permissions[modId] or {}
   local function warnOnce(permission)
     local key = modId .. "|" .. permission .. "|" .. name
@@ -194,7 +188,6 @@ 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
@@ -202,22 +195,12 @@ 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
-      -- 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
+      scanRequire(name)
       -- 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 (owner or callerIsMod(3)) then
+          and callerIsMod(3) then
         local adapter = Gen2Compat.resolve(name, Runtime.currentMod)
         if adapter then
           local key = "adapter|" .. name
@@ -252,7 +235,7 @@ function Loader.new(opts)
     events = Events.new(), hooks = Hooks.new(), content = {}, assets = {},
     exports = {}, migrations = {}, order = {},
     modSave = {}, modOptions = {}, optionSchemas = {}, imageCache = {},
-    modInput = {}, modEnv = {}, stepsQueues = {},
+    modInput = {},
     fs = (opts and opts.fs) or (love and love.filesystem),
     dev = dev,
     -- Which generation this boot is (1 or 2).  Fixed at construction: the
@@ -287,8 +270,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())
@@ -375,13 +357,11 @@ 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 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
+        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
       end
       if schema ~= nil then
         mods[id] = schema
@@ -1000,40 +980,6 @@ 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 = {
@@ -1144,11 +1090,9 @@ 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 SafePath.join(mod.path, relative, "mod.assets:path")
-    end,
+    path = function(_, relative) return mod.path .. "/" .. relative end,
     image = function(_, relative)
-      local full = SafePath.join(mod.path, relative, "mod.assets:image")
+      local full = mod.path .. "/" .. relative
       local cached = loader.imageCache[full]
       if cached then return cached end
       assert(love and love.graphics,
@@ -1158,10 +1102,9 @@ 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)
-    return loader.fs.read(SafePath.join(self.path, relative, "mod:read"))
+    local path = self.path .. "/" .. relative
+    return loader.fs.read(path)
   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
@@ -1205,21 +1148,9 @@ 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 = SafePath.join(mod.path, mod.manifest.entry, "manifest entry")
-  local chunk, err = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
+  local path = mod.path .. "/" .. mod.manifest.entry
+  local chunk, err = self.fs.load(path)
   if not chunk then error(err or ("unable to load " .. path)) end
   local api = self:_api(mod)
   local result = chunk(api)
@@ -1251,7 +1182,6 @@ 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
@@ -1375,13 +1305,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
@@ -1418,12 +1365,10 @@ 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)
-  -- 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
+  -- 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
     self:_installDevShim()
   end
   for _, mod in ipairs(ordered) do

src/mods/ManagerState.lua

@@ -8,8 +8,6 @@ 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")
@@ -737,8 +735,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
@@ -938,18 +935,13 @@ 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
-    -- 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
+    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
     end
   end
   return schema

src/mods/Manifest.lua

@@ -3,15 +3,13 @@
 -- 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, steps = true }
+Manifest.PERMISSIONS = { network = true, filesystem = true, engine_internals = true }
 
 -- link-relevant registries; a mod that writes into one of these while
 -- declaring affects_link = false gets an attributed warning from the loader
@@ -146,9 +144,6 @@ 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")
@@ -234,24 +229,19 @@ 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 optionalString(value, field)
+  local function optionalFile(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 = entry,
+    entry = raw.entry,
     api = api,
     priority = tonumber(raw.priority) or 0,
     dependencies = array(raw.dependencies),
@@ -275,8 +265,7 @@ function Manifest.validate(raw, path)
     permissionSet = permissionSet,
     options_schema = optionalFile(raw.options_schema, "options_schema"),
     assets_transforms = optionalFile(raw.assets_transforms, "assets_transforms"),
-    -- 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"),
+    force_enable_env = optionalFile(raw.force_enable_env, "force_enable_env"),
     path = path,
     raw = raw,
   }

src/mods/Runtime.lua

@@ -28,11 +28,6 @@ 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

@@ -1,38 +0,0 @@
--- 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

@@ -1,228 +0,0 @@
--- 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

@@ -1,84 +0,0 @@
--- 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,6 +140,7 @@ 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 })
+      require("src.core.Sound").play(game.data, "Get_Item1")
       game.stack:push(TextBox.new(game,
         romText(game.data, "_LearnedMove1Text",
           "%s learned\n%s!", name, mdef.name), nextStep))

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")
 
@@ -130,6 +130,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 +394,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

src/save_convert/GenSave.lua

@@ -100,6 +100,7 @@ O.tradeFlags = O.townVisited + 44                         -- 2B (flag_array NUM_
 -- Sits 2 bytes (wPlayerCoins) past O.coins per the walk above; absolute
 -- 0x2852 (#763, #857).
 O.toggleObjectFlags = O.coins + 2                         -- 32B
+O.hiddenItemFlags = O.townVisited - 27
 -- Play time (wPlayTimeHours/Maxed/Minutes/Seconds/Frames) lives INSIDE the
 -- sMainData window (wMainDataStart..wMainDataEnd is copied verbatim into
 -- SRAM), 1866 bytes past wMainDataStart -- reached from the checksum-verified
@@ -770,6 +771,15 @@ function GenSave.decode(bytes, data, opts)
     end
   end
 
+  if data.hiddenItems then
+    save.hiddenTaken = {}
+    for i, row in ipairs(data.hiddenItems) do
+      if bitGet(bytes, O.hiddenItemFlags, i - 1) then
+        save.hiddenTaken[row[1] .. "_" .. row[2] .. "_" .. row[3]] = true
+      end
+    end
+  end
+
   -- FLY destinations.  wTownVisitedFlag's bit index IS the town's map index:
   -- engine/items/town_map.asm BuildFlyLocationsList loads the 16-bit value
   -- into de and rotates it right one bit per iteration with b counting up
@@ -953,6 +963,14 @@ function GenSave.encode(save, data, template)
     end
   end
 
+  if data.hiddenItems then
+    local taken = save.hiddenTaken or {}
+    for i, row in ipairs(data.hiddenItems) do
+      local key = row[1] .. "_" .. row[2] .. "_" .. row[3]
+      bitSet(buf, O.hiddenItemFlags, i - 1, taken[key] and true or false)
+    end
+  end
+
   -- FLY destinations back into wTownVisitedFlag (see the decode note), so a
   -- save exported from this port is flyable on hardware (#263).  A save
   -- table with no `visited` key at all says nothing about the set, so leave

src/save_convert/SaveConvert.lua

@@ -49,6 +49,7 @@ local DATA_MODULES = {
   charmap    = { "src.save_convert.data.charmap",   "src/save_convert/data/charmap.lua" },
   eventFlags = { "src.save_convert.data.event_flags", "src/save_convert/data/event_flags.lua" },
   toggleObjects = { "src.save_convert.data.toggle_objects", "src/save_convert/data/toggle_objects.lua" },
+  hiddenItems = { "src.save_convert.data.hidden_items", "src/save_convert/data/hidden_items.lua" },
 }
 
 local OPTIONAL_MODULES = { tilesets = true, audio = true }
@@ -64,6 +65,10 @@ local YELLOW_EVENT_FLAGS = {
   "src.save_convert.data.event_flags_yellow",
   "src/save_convert/data/event_flags_yellow.lua",
 }
+local YELLOW_HIDDEN_ITEMS = {
+  "src.save_convert.data.hidden_items_yellow",
+  "src/save_convert/data/hidden_items_yellow.lua",
+}
 
 local function loadTable(requirePath, filePath)
   local ok, mod = pcall(require, requirePath)
@@ -133,6 +138,8 @@ local function ensureData(gameVersion)
       if name ~= "charmap" then
         if name == "eventFlags" and gameVersion == "yellow" then
           spec = YELLOW_EVENT_FLAGS -- Yellow's bit numbering differs (#838)
+        elseif name == "hiddenItems" and gameVersion == "yellow" then
+          spec = YELLOW_HIDDEN_ITEMS
         end
         local mod = loadCacheTable(gameVersion, spec[2])
         if not mod then

src/save_convert/data/hidden_items.lua

@@ -0,0 +1,30 @@
+return {
+  { "VIRIDIAN_FOREST", 1, 18 }, { "VIRIDIAN_FOREST", 16, 42 },
+  { "MT_MOON_B2F", 18, 12 }, { "ROUTE_25", 38, 3 },
+  { "ROUTE_9", 14, 7 }, { "SS_ANNE_KITCHEN", 13, 9 },
+  { "SS_ANNE_B1F_ROOMS", 3, 1 }, { "ROUTE_10", 9, 17 },
+  { "ROUTE_10", 16, 53 }, { "ROCKET_HIDEOUT_B1F", 21, 15 },
+  { "ROCKET_HIDEOUT_B3F", 27, 17 }, { "ROCKET_HIDEOUT_B4F", 25, 1 },
+  { "POKEMON_TOWER_5F", 4, 12 }, { "ROUTE_13", 1, 14 },
+  { "ROUTE_13", 16, 13 }, { "POKEMON_MANSION_B1F", 1, 9 },
+  { "SAFARI_ZONE_GATE", 10, 1 }, { "SAFARI_ZONE_WEST", 6, 5 },
+  { "SILPH_CO_5F", 12, 3 }, { "SILPH_CO_9F", 2, 15 },
+  { "COPYCATS_HOUSE_2F", 1, 1 }, { "CERULEAN_CAVE_1F", 14, 11 },
+  { "CERULEAN_CAVE_B1F", 27, 3 }, { "POWER_PLANT", 17, 16 },
+  { "POWER_PLANT", 12, 1 }, { "SEAFOAM_ISLANDS_B2F", 15, 15 },
+  { "SEAFOAM_ISLANDS_B4F", 25, 17 }, { "POKEMON_MANSION_1F", 8, 16 },
+  { "POKEMON_MANSION_3F", 1, 9 }, { "ROUTE_23", 9, 44 },
+  { "ROUTE_23", 19, 70 }, { "ROUTE_23", 8, 90 },
+  { "VICTORY_ROAD_2F", 5, 2 }, { "VICTORY_ROAD_2F", 26, 7 },
+  { "UNUSED_MAP_6F", 14, 11 }, { "VIRIDIAN_CITY", 14, 4 },
+  { "ROUTE_11", 48, 5 }, { "ROUTE_12", 2, 63 },
+  { "ROUTE_17", 15, 14 }, { "ROUTE_17", 8, 45 },
+  { "ROUTE_17", 17, 72 }, { "ROUTE_17", 4, 91 },
+  { "ROUTE_17", 8, 121 }, { "UNDERGROUND_PATH_NORTH_SOUTH", 3, 4 },
+  { "UNDERGROUND_PATH_NORTH_SOUTH", 4, 34 },
+  { "UNDERGROUND_PATH_WEST_EAST", 12, 2 },
+  { "UNDERGROUND_PATH_WEST_EAST", 21, 5 }, { "CELADON_CITY", 48, 15 },
+  { "ROUTE_25", 10, 1 }, { "MT_MOON_B2F", 33, 9 },
+  { "SEAFOAM_ISLANDS_B3F", 9, 16 }, { "VERMILION_CITY", 14, 11 },
+  { "CERULEAN_CITY", 15, 8 }, { "ROUTE_4", 40, 3 },
+}

src/save_convert/data/hidden_items_yellow.lua

@@ -0,0 +1,31 @@
+return {
+  { "SILPH_CO_5F", 12, 3 }, { "SILPH_CO_9F", 2, 15 },
+  { "POKEMON_MANSION_3F", 1, 9 }, { "POKEMON_MANSION_B1F", 1, 9 },
+  { "SAFARI_ZONE_WEST", 6, 5 }, { "CERULEAN_CAVE_2F", 16, 13 },
+  { "CERULEAN_CAVE_B1F", 8, 14 }, { "UNUSED_MAP_6F", 14, 11 },
+  { "SEAFOAM_ISLANDS_B2F", 15, 15 }, { "SEAFOAM_ISLANDS_B3F", 9, 16 },
+  { "SEAFOAM_ISLANDS_B4F", 25, 17 }, { "VIRIDIAN_FOREST", 1, 18 },
+  { "VIRIDIAN_FOREST", 16, 42 }, { "MT_MOON_B2F", 18, 12 },
+  { "MT_MOON_B2F", 33, 9 }, { "SS_ANNE_B1F_ROOMS", 3, 1 },
+  { "SS_ANNE_KITCHEN", 13, 9 }, { "UNDERGROUND_PATH_NORTH_SOUTH", 3, 4 },
+  { "UNDERGROUND_PATH_NORTH_SOUTH", 4, 34 },
+  { "UNDERGROUND_PATH_WEST_EAST", 12, 2 },
+  { "UNDERGROUND_PATH_WEST_EAST", 21, 5 }, { "ROCKET_HIDEOUT_B1F", 21, 15 },
+  { "ROCKET_HIDEOUT_B3F", 27, 17 }, { "ROCKET_HIDEOUT_B4F", 25, 1 },
+  { "ROUTE_10", 9, 17 }, { "ROUTE_10", 16, 53 },
+  { "POWER_PLANT", 17, 16 }, { "POWER_PLANT", 12, 1 },
+  { "ROUTE_11", 48, 5 }, { "ROUTE_12", 2, 63 },
+  { "ROUTE_13", 1, 14 }, { "ROUTE_13", 16, 13 },
+  { "ROUTE_17", 15, 14 }, { "ROUTE_17", 8, 45 },
+  { "ROUTE_17", 17, 72 }, { "ROUTE_17", 4, 91 },
+  { "ROUTE_17", 8, 121 }, { "ROUTE_23", 9, 44 },
+  { "ROUTE_23", 19, 70 }, { "ROUTE_23", 8, 90 },
+  { "VICTORY_ROAD_2F", 5, 2 }, { "VICTORY_ROAD_2F", 26, 7 },
+  { "ROUTE_25", 38, 3 }, { "ROUTE_25", 10, 1 },
+  { "ROUTE_4", 40, 3 }, { "ROUTE_9", 14, 7 },
+  { "COPYCATS_HOUSE_2F", 1, 1 }, { "VIRIDIAN_CITY", 14, 4 },
+  { "CERULEAN_CITY", 15, 8 }, { "CERULEAN_CAVE_1F", 18, 7 },
+  { "POKEMON_TOWER_5F", 4, 12 }, { "VERMILION_CITY", 14, 11 },
+  { "CELADON_CITY", 48, 15 }, { "SAFARI_ZONE_GATE", 10, 1 },
+  { "POKEMON_MANSION_1F", 8, 16 },
+}

src/script/Commands.lua

@@ -526,6 +526,22 @@ function Commands.set_field(ctx, key, value)
   ctx.save[key] = value
 end
 
+function Commands.load_player_starter_name(ctx)
+  local flags = ctx.save.flags or {}
+  local species = flags.EVENT_CHOSE_PIKACHU and "PIKACHU"
+    or flags.EVENT_CHOSE_CHARMANDER and "CHARMANDER"
+    or flags.EVENT_CHOSE_SQUIRTLE and "SQUIRTLE"
+    or flags.EVENT_CHOSE_BULBASAUR and "BULBASAUR"
+    or (ctx.save.party and ctx.save.party[1] and ctx.save.party[1].species)
+  local def = species and ctx.game.data.pokemon[species]
+  ctx.game.stringBuffer = def and def.name or species or ""
+end
+
+function Commands.spawn_pikachu_follower(ctx)
+  require("src.world.PikachuFollower").onMapEntered(
+    ctx.game, ctx.overworld, nil, false)
+end
+
 local function toggleObject(ctx, mapId, objName, visible)
   local save = ctx.save
   save.objectToggles = save.objectToggles or {}
@@ -1131,9 +1147,7 @@ end
 -- opts.tempo is the Music_*AlternateTempo override (audio/alternate_tempo.asm
 -- re-points channel 1 at a stub that only changes the song's `tempo`) (#847).
 function Commands.play_music(ctx, songId, opts)
-  local tempo = opts and opts.tempo
-  require("src.core.Music").play(ctx.game.data, songId, nil,
-                                 tempo and { tempo = tempo } or nil)
+  require("src.core.Music").play(ctx.game.data, songId, nil, opts)
   if opts and opts.keep and ctx.overworld then
     ctx.overworld.keepMusicOnce = true
   end

src/script/gen2/CallAsm.lua

@@ -456,7 +456,13 @@ end
 -- AskRockSmashScript reads it with `ifequal 1, .no`.  Transcribing it the
 -- obvious way round refuses the move for every party that has it.
 function H.HasRockSmash(ctx)
-  return call(ctx, "partyMoveUser", "ROCK_SMASH") and 0 or 1
+  local mon = call(ctx, "partyMoveUser", "ROCK_SMASH")
+  if mon then
+    -- engine/events/overworld.asm:1339
+    ctx.curPartyMon = mon
+    return 0
+  end
+  return 1
 end
 
 -- PutTheRodAway: ClearBox over the text window, then wPlayerAction back to

src/ui/BagMenu.lua

@@ -60,6 +60,14 @@ local function useOn(game, battle, id, target, list, moveIndex, picker)
     return
   end
 
+  if result == "flute_wake_pikachu" then
+    require("src.core.Sound").play(game.data, "Pokeflute")
+    showMessages(game, payload, function()
+      game.overworld.pikachuPewterSleepScene = nil
+    end)
+    return
+  end
+
   -- field POKé FLUTE next to a not-yet-beaten Snorlax: "had effect" text,
   -- then the woke-up/battle sequence (data/scripts/story.lua snorlaxWake)
   if result == "flute_wake" then
@@ -142,12 +150,9 @@ local function useOn(game, battle, id, target, list, moveIndex, picker)
     list:close()
     local ow = game.overworld
     local p = ow and ow.player
-    if ow and p then
-      local fx, fy = p:facingCell()
-      if ow.map:inBounds(fx, fy) and ow.map:isWaterCell(fx, fy) then
-        ow:goFishing(id)
-        return
-      end
+    if ow and p and ow:facingIsShoreOrWater() then
+      ow:goFishing(id)
+      return
     end
     showMessages(game, { Strings("No good! It's not\neven near water.") })
     return
@@ -176,19 +181,25 @@ local function useOn(game, battle, id, target, list, moveIndex, picker)
       end
       if #target.moves < 4 then
         table.insert(target.moves, { id = moveId, pp = mdef.pp })
+        require("src.core.Sound").play(game.data, "Get_Item1")
         showMessages(game, { Strings("%s learned\n%s!", target.nickname or
           game.data.pokemon[target.species].name, mdef.name) })
         if result == "learn" then consume(game, id) end
+        list.items = buildItems(game)
+        list.index = math.min(list.index, math.max(1, #list.items))
         taught()
       else
         require("src.ui.Screens").push(game, "MoveLearnMenu", target, moveId,
           function(learned)
             if learned and result == "learn" then consume(game, id) end
+            if learned then
+              list.items = buildItems(game)
+              list.index = math.min(list.index, math.max(1, #list.items))
+            end
             if learned then taught() end
           end)
       end
     end
-    list:close()
     teach()
     return
   end
@@ -322,6 +333,7 @@ local function useOn(game, battle, id, target, list, moveIndex, picker)
             local mdef = game.data.moves[moveId]
             if #target.moves < 4 then
               table.insert(target.moves, { id = moveId, pp = mdef.pp })
+              require("src.core.Sound").play(game.data, "Get_Item1")
               local name = target.nickname or def.name
               showMessages(game, { Strings("%s learned\n%s!", name, mdef.name) },
                            nextStep)

src/ui/BindingsMenu.lua

@@ -127,6 +127,7 @@ function BindingsMenu:beginCapture(item)
   self.onKeyReleased = BindingsMenu.captureKeyRelease
   self.onGamepadReleased = BindingsMenu.capturePadRelease
   self.onJoystickReleased = BindingsMenu.captureJoyRelease
+  if Input.armCapture then Input:armCapture() end
 end
 
 function BindingsMenu:endCapture()
@@ -138,6 +139,7 @@ function BindingsMenu:endCapture()
   self.onKeyReleased = nil
   self.onGamepadReleased = nil
   self.onJoystickReleased = nil
+  if Input.disarmCapture then Input:disarmCapture() end
 end
 
 -- Escape is the capture's way out, so it is never captured: every other
@@ -232,7 +234,11 @@ function BindingsMenu:storeBinding(slot, value)
   b[slot] = value
   opts.bindings[item.button.id] = b
   item.right = boundRight(opts.bindings, item.button)
-  if game.writeOptions then game:writeOptions() end
+  if game.writeOptions then
+    game:writeOptions()
+  elseif game.persistOptions then
+    game:persistOptions()
+  end
 end
 
 -- SELECT: forget one row's rebind and fall back to the defaults.  #510's
@@ -246,7 +252,11 @@ function BindingsMenu:clearBinding(item)
   end
   opts.bindings[item.button.id] = nil
   item.right = boundRight(opts.bindings, item.button)
-  if game.writeOptions then game:writeOptions() end
+  if game.writeOptions then
+    game:writeOptions()
+  elseif game.persistOptions then
+    game:persistOptions()
+  end
 end
 
 -- START: confirm, then drop the whole overlay (#589).  The footer doubles
@@ -264,12 +274,39 @@ function BindingsMenu:confirmReset()
     for _, it in ipairs(self.items) do
       it.right = boundRight(nil, it.button)
     end
-    if game.writeOptions then game:writeOptions() end
+    if game.writeOptions then
+      game:writeOptions()
+    elseif game.persistOptions then
+      game:persistOptions()
+    end
   end, { defaultNo = true }))
 end
 
+function BindingsMenu:drainCapture()
+  local events = Input.takeCaptureEvents and Input:takeCaptureEvents()
+  if not events then return end
+  for i = 1, #events do
+    local ev = events[i]
+    if ev.phase == "pressed" then
+      if ev.kind == "key" then self:captureKey(ev.value)
+      elseif ev.kind == "pad" then self:capturePad(ev.value)
+      elseif ev.kind == "joy" then self:captureJoy(ev.value)
+      end
+    else
+      if ev.kind == "key" then self:captureKeyRelease(ev.value)
+      elseif ev.kind == "pad" then self:capturePadRelease(ev.value)
+      elseif ev.kind == "joy" then self:captureJoyRelease(ev.value)
+      end
+    end
+    if not self.capture then return end
+  end
+end
+
 function BindingsMenu:update(dt)
-  if self.capture then return end -- the raw capture owns the input
+  if self.capture then
+    self:drainCapture()
+    return
+  end
   if self.game.input:wasPressed("start") then
     return self:confirmReset()
   end

src/ui/BoxMenu.lua

@@ -119,6 +119,13 @@ local function deposit(game)
     onChoose = function(item, list)
       local mon = game.save.party[item.value]
       if not mon then return end
+      local Follower = require("src.world.PikachuFollower")
+      if Follower.isFollowingDisabled(game.overworld)
+          and Follower.isStarterPikachu(game.save, mon) then
+        game.stack:push(TextBox.new(game, t._SleepingPikachuText2
+          or Strings("There isn't any\nresponse...")))
+        return
+      end
       monSubmenu(game, "DEPOSIT", mon, function()
         if #game.save.party <= 1 then
           list.footer = Strings("You need at least\none POKéMON!")
@@ -167,6 +174,16 @@ local function release(game)
       local mon = box[list.index]
       if not mon then return end
       local name = monName(game, mon)
+      if require("src.core.GameVersion").isYellow()
+         and mon.species == "PIKACHU"
+         and mon.otId == game.save.player.id
+         and mon.ot == game.save.player.name then
+        require("src.core.Sound").playCry(game.data, mon.species)
+        game.stack:push(TextBox.new(game,
+          (t._PikachuUnhappyText or Strings("%s looks\nunhappy about it!", name))
+            :gsub("{RAM:wNameBuffer}", name)))
+        return
+      end
       game.stack:push(TextBox.new(game,
         Strings("Once released,\n%s is\ngone forever. OK?", name), nil, {
         defaultNo = true, noSound = true,

src/ui/ChoiceBox.lua

@@ -1,6 +1,7 @@
 -- YES/NO choice box (InitYesNoTextBoxParameters: above the text box, right).
 
 local Font = require("src.render.Font")
+local UIVisibility = require("src.battle.UIVisibility")
 local Theme = require("src.ui.Theme")
 local Strings = require("src.core.Strings")
 local Timing = require("src.core.Timing")
@@ -67,6 +68,7 @@ function ChoiceBox:update(dt)
 end
 
 function ChoiceBox:draw()
+  if not UIVisibility.bottomVisible(self, false) then return end
   local tx, ty, tw, th = self.tx, self.ty, self.tw, self.th
   -- rides the same bottom anchor as the dialogue box it sits above, so the
   -- pair travels together (the anchor keeps each element's gap from the edge)

src/ui/ModUI.lua

@@ -12,6 +12,7 @@ local MODULES = {
   QuantityBox = "src.ui.QuantityBox",
   NamingScreen = "src.ui.NamingScreen",
   PicBox = "src.ui.PicBox",
+  PokemonIcon = "src.ui.PokemonIcon",
   TextBox = "src.render.TextBox",
   Font = "src.render.Font",
   Theme = "src.ui.Theme",

src/ui/MoveLearnMenu.lua

@@ -17,12 +17,13 @@ local HM_MOVES = {
   CUT = true, FLY = true, SURF = true, STRENGTH = true, FLASH = true,
 }
 
-function MoveLearnMenu.new(game, mon, newMoveId, onDone)
+function MoveLearnMenu.new(game, mon, newMoveId, onDone, learnedSound)
   local self = setmetatable({}, MoveLearnMenu)
   self.game = game
   self.mon = mon
   self.newMoveId = newMoveId
   self.onDone = onDone
+  self.learnedSound = learnedSound or "Get_Item1"
   self.index = 1
   -- forget-list UI only after TryingToLearn YES (learn_move.asm .loop)
   self.selecting = false
@@ -118,6 +119,7 @@ function MoveLearnMenu:finish(learned)
   self.selecting = false
   game.stack:pop()
   local msg
+  local opts
   if learned then
     -- pokered pages this as four texts in a row; _ForgotAndText carries
     -- the "And..." tail
@@ -127,13 +129,16 @@ function MoveLearnMenu:finish(learned)
            "\f%s forgot\n%s!\fAnd...", name, self.forgot)
       .. "\f" .. romText(game.data, "_LearnedMove1Text",
            "%s learned\n%s!", name, mdef.name)
+    opts = { auto = { sound = function()
+      return require("src.core.Sound").play(game.data, self.learnedSound)
+    end, wait = true } }
   else
     msg = romText(game.data, "_DidNotLearnText",
       "%s\ndid not learn\v%s!", name, mdef.name)
   end
   game.stack:push(TextBox.new(game, msg, function()
     if self.onDone then self.onDone(learned) end
-  end))
+  end, opts))
 end
 
 function MoveLearnMenu:draw()

src/ui/OakSpeech.lua

@@ -266,7 +266,10 @@ function OakSpeech.new(game, onDone)
   -- RedSprite: the walking sprite the pic shrinks into (frame 0 =
   -- standing, facing down)
   local playerSprites = (game.data.field and game.data.field.playerSprites) or {}
-  local red = game.data.sprites and game.data.sprites[playerSprites.walk or "SPRITE_RED"] or game.data.sprites.SPRITE_RED
+  -- The fallback has to read the same guarded table: reaching for
+  -- game.data.sprites.SPRITE_RED after the `and` already found it nil threw.
+  local sprites = game.data.sprites or {}
+  local red = sprites[playerSprites.walk or "SPRITE_RED"] or sprites.SPRITE_RED
   self.walkSheet = tryImage(red and red.image)
   return self
 end

src/ui/OptionsMenu.lua

@@ -501,7 +501,7 @@ local function buildRows(game)
         return true
       end },
     -- Haptic feedback for on-screen pad presses (#806): OFF / LIGHT /
-    -- MEDIUM / HEAVY, where the intensity is a vibration duration --
+    -- NORMAL / STRONG, where the intensity is a vibration duration --
     -- love.system.vibrate takes nothing else.  Hidden with TOUCH PAD below,
     -- since the only thing that buzzes is a virtual button press.
     { id = "haptics", label = Strings("VIBRATION"),
@@ -515,7 +515,7 @@ local function buildRows(game)
         o.haptics = TC.cycleHaptics(o.haptics, dir)
         TC:applyOptions(o)
         -- sample the level being selected: stepping the row is the only way
-        -- to compare LIGHT against HEAVY without leaving the menu
+        -- to compare LIGHT against STRONG without leaving the menu
         TC.buzz(o.haptics)
         return true
       end },

src/ui/PartyMenu.lua

@@ -72,6 +72,21 @@ end
 
 local function sameItems(_, items) return items end
 
+local function followerUnavailable(game, mon)
+  local ow = game.overworld
+  local Follower = require("src.world.PikachuFollower")
+  return Follower.isFollowingDisabled(ow)
+    and Follower.isStarterPikachu(game.save, mon)
+end
+
+local function refuseUnavailable(self)
+  self.swapFrom = nil
+  local TextBox = require("src.render.TextBox")
+  local t = self.game.data and self.game.data.text or {}
+  self.game.stack:push(TextBox.new(self.game,
+    t._SleepingPikachuText1 or Strings("There isn't any\nresponse...")))
+end
+
 -- where DIG escapes work: escape_rope_tilesets.asm (Agatha's room is
 -- excluded by map id in ItemUseEscapeRope)
 local DIG_TILESETS = { FOREST = true, CEMETERY = true, CAVERN = true,
@@ -367,6 +382,10 @@ function PartyMenu:update(dt)
       self.submenu = nil
     elseif input:wasPressed("a") then
       local mon = party[self.index]
+      if followerUnavailable(self.game, mon) then
+        refuseUnavailable(self)
+        return
+      end
       local entry = self.subItems[self.subIndex]
       local action = entry.action
       if not action and entry.onSelect then
@@ -577,6 +596,10 @@ function PartyMenu:update(dt)
     if self.onCancel then self.onCancel() end
   elseif input:wasPressed("a") and #party > 0 then
     local mon = party[self.index]
+    if followerUnavailable(self.game, mon) then
+      refuseUnavailable(self)
+      return
+    end
     if self.softboiledFrom then
       local user = party[self.softboiledFrom]
       local heal = math.floor(user.stats.hp / 5)

src/ui/PokemonIcon.lua

@@ -0,0 +1,41 @@
+-- Public read-only Pokemon icon presentation for detached summaries.
+-- Resolution and rendering deliberately stay engine-owned: PartyMenu already
+-- composes content icon registrations, per-species definitions, asset
+-- overrides, and the pokemon.icon hook in one canonical path.
+
+local PartyMenu = require("src.ui.PartyMenu")
+
+local PokemonIcon = {}
+
+local function finite(value)
+  return type(value) == "number" and value == value
+    and value ~= math.huge and value ~= -math.huge
+end
+
+local function integer(value, minimum)
+  return finite(value) and value % 1 == 0 and value >= minimum
+end
+
+function PokemonIcon.draw(game, summary, x, y, opts)
+  opts = type(opts) == "table" and opts or {}
+  if type(game) ~= "table" or type(summary) ~= "table"
+      or type(summary.species) ~= "string" or summary.species == ""
+      or not integer(summary.hp, 0) or not integer(summary.maxHp, 1)
+      or summary.hp > summary.maxHp or not finite(x) or not finite(y)
+      or (opts.selected ~= nil and type(opts.selected) ~= "boolean")
+      or (opts.counter ~= nil and not finite(opts.counter)) then
+    return false, "invalid_pokemon_preview",
+      "Pokemon icon presentation needs species and valid captured HP values."
+  end
+  local ok, message = pcall(PartyMenu.drawIcon, game, {
+    species = summary.species,
+    hp = summary.hp,
+    stats = { hp = summary.maxHp },
+  }, x, y, opts.selected == true, opts.counter or 0)
+  if not ok then
+    return false, "pokemon_icon_failed", tostring(message)
+  end
+  return true
+end
+
+return PokemonIcon

src/ui/ShopMenu.lua

@@ -104,6 +104,27 @@ local function sell(game)
     dialogue = true,
     money = function() return game.save.money end,
     footer = greet,
+    onSelectKey = function(item, l)
+      if not item then return end
+      if not l.swapIndex then
+        l.swapIndex = l.index
+        return
+      end
+      local order = Bag.order(game.save)
+      order[l.swapIndex], order[l.index] = order[l.index], order[l.swapIndex]
+      l.swapIndex = nil
+      require("src.core.Sound").play(game.data, "Swap")
+      local rebuilt = {}
+      for _, id in ipairs(order) do
+        local def = game.data.items[id]
+        rebuilt[#rebuilt + 1] = {
+          value = id,
+          label = def and def.name or id,
+          right = "x" .. game.save.inventory[id],
+        }
+      end
+      l.items = rebuilt
+    end,
     onChoose = function(item)
       local def = game.data.items[item.value]
       -- only key items and HMs are unsellable (pokemart.asm IsKeyItem /

src/ui/StartMenu.lua

@@ -34,7 +34,8 @@ function StartMenu.new(game)
 
   -- POKéMON is always listed (draw_start_menu.asm prints it even with
   -- an empty party; selecting it then just no-ops)
-  table.insert(items, { label = Strings("POKéMON"), onSelect = function()
+  table.insert(items, { label = Strings("POKéMON"),
+    keepOpen = #game.save.party == 0, onSelect = function()
     if #game.save.party == 0 then return end
     Screens.push(game, "PartyMenu", { onCancel = reopen })
   end })