Merge pull request #1383 from bryanthaboi/dev

two absolut hogs doing hog level sh

.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

@@ -252,8 +252,40 @@ jobs:
               Remove-Item $env:UWP_PFX -Force -ErrorAction SilentlyContinue
           }
 
+  # Windows Native AOT TLS dialer. The Mac release runner fuses the win64 zip
+  # from LÖVE's prebuilt binaries and cannot cross-compile this DLL, so build
+  # it here and inject it in the release job before scripts/build.sh win.
+  native-tls-win:
+    name: build Windows gen1tls.dll
+    needs: version
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Setup .NET 8
+        uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: "8.0.x"
+      - name: Publish gen1tls (win-x64 Native AOT)
+        shell: pwsh
+        run: |
+          $out = "dist/native/win-x64"
+          New-Item -ItemType Directory -Force -Path $out | Out-Null
+          dotnet publish native/tls_dial/Gen1Tls.csproj `
+            -c Release -r win-x64 -o $out
+          if (-not (Test-Path "$out/gen1tls.dll")) {
+            throw "gen1tls.dll missing after publish"
+          }
+          Get-Item "$out/gen1tls.dll" | Format-List Name, Length, LastWriteTime
+      - name: Upload gen1tls.dll
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1tls-win-x64
+          path: dist/native/win-x64/gen1tls.dll
+          if-no-files-found: error
+          retention-days: 1
+
   release:
-    needs: [version, xbox-uwp, linux-arm64]
+    needs: [version, xbox-uwp, linux-arm64, native-tls-win]
     runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
 
     steps:
@@ -269,6 +301,12 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
 
+      - name: Download Windows gen1tls dialer
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1tls-win-x64
+          path: dist/native/win-x64
+
       - name: Import signing certificate into a temporary keychain
         if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
@@ -307,13 +345,21 @@ jobs:
           security find-identity -v -p codesigning "$KEYCHAIN_PATH"
 
       - name: Build macOS + Windows + Linux
+        env:
+          GEN1TLS_DLL: ${{ github.workspace }}/dist/native/win-x64/gen1tls.dll
         run: |
           set -euo pipefail
           # Sign in-build (identity auto-detected from the temp keychain);
           # notarize separately below so it uses secret credentials, not a
           # login-keychain profile. "all" also builds the Linux AppImage,
           # which needs no signing/notarization.
+          if [ ! -f "$GEN1TLS_DLL" ]; then
+            echo "::error::gen1tls.dll missing at $GEN1TLS_DLL (native-tls-win job)"
+            exit 1
+          fi
           scripts/build.sh all --version "${{ needs.version.outputs.version }}" --no-notarize
+          unzip -l dist/win/gen1recomp-win64.zip | grep -F gen1tls.dll \
+            || { echo "::error::Windows zip is missing gen1tls.dll"; exit 1; }
 
       - name: Build Android
         run: |
@@ -444,9 +490,9 @@ jobs:
           [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
           cp "$apk" "$outdir/gen1recomp-${v}-android.apk"
 
-          ipa="dist/ios/gen1recomp.ipa"
+          ipa="dist/ios/gen1recomp++.ipa"
           [ -f "$ipa" ] || { echo "::error::$ipa not found (expected from scripts/build_ios.sh --device)"; exit 1; }
-          cp "$ipa" "$outdir/gen1recomp-${v}-ios.ipa"
+          cp "$ipa" "$outdir/gen1recomp++-${v}-ios.ipa"
 
           swzip="dist/switch/gen1recomp-${v}-switch.zip"
           [ -f "$swzip" ] || { echo "::error::$swzip not found (expected from scripts/build_switch.sh --fused → pack_sd_zip.sh)"; exit 1; }
@@ -580,7 +626,7 @@ 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"
@@ -602,14 +648,15 @@ jobs:
         run: |
           set -euo pipefail
           v="${{ needs.version.outputs.version }}"
-          ipa="dist/release/gen1recomp-${v}-ios.ipa"
+          ipa="dist/release/gen1recomp++-${v}-ios.ipa"
           app_repo="mobile/ios/app-repo.json"
           [ -f "$ipa" ] || { echo "::error::$ipa not found"; exit 1; }
           [ -f "$app_repo" ] || { echo "::error::$app_repo not found"; exit 1; }
 
           date="$(date -u +"%Y-%m-%d")"
           size="$(wc -c < "$ipa" | tr -d '[:space:]')"
-          download_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/v${v}/gen1recomp-${v}-ios.ipa"
+          download_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/v${v}/gen1recomp++-${v}-ios.ipa"
+          bundle_id="com.theboisclub.gen1recompplusplus"
           localized_description="Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke"
           release_notes="$(GH_TOKEN="${{ github.token }}" gh release view "v${v}" --json body --jq '.body // ""' 2>/dev/null || true)"
           if [ -n "$release_notes" ]; then
@@ -623,15 +670,15 @@ jobs:
             --argjson size "$size" \
             '{version: $version, date: $date, size: $size, downloadURL: $download_url, localizedDescription: $localized_description}')"
 
-          if jq -e --arg version "$v" \
-            'any(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions[]?; .version == $version)' \
+          if jq -e --arg bundle_id "$bundle_id" --arg version "$v" \
+            'any(.apps[] | select(.bundleIdentifier == $bundle_id).versions[]?; .version == $version)' \
             "$app_repo" >/dev/null; then
-            jq --arg version "$v" --argjson entry "$entry" \
-              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= map(if .version == $version then $entry else . end)' \
+            jq --arg bundle_id "$bundle_id" --arg version "$v" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == $bundle_id).versions) |= map(if .version == $version then $entry else . end)' \
               "$app_repo" > "$app_repo.tmp"
           else
-            jq --argjson entry "$entry" \
-              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= [$entry] + .' \
+            jq --arg bundle_id "$bundle_id" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == $bundle_id).versions) |= [$entry] + .' \
               "$app_repo" > "$app_repo.tmp"
           fi
           mv "$app_repo.tmp" "$app_repo"

.gitignore

@@ -3,8 +3,9 @@
 data/generated/
 assets/generated/
 
-# LÖVE packages
+# LÖVE packages & archives
 *.love
+*.zip
 
 # Local saves (LÖVE writes to its save dir, but keep the repo clean anyway)
 save/
@@ -75,3 +76,12 @@ mobile/ios/bundle_id.local
 /dist/native/
 /dist/win/
 /.bazinga/
+
+# Local options / preferences
+/options.lua*
+
+# User-owned ROMs imported for individual mods. Manifests declare the
+# destinations, but source checkouts and packaged mods never ship the files.
+/mods/*/baseroms/
+/imports/baseroms/
+/imports/baseroms-recovery/

CONTRIBUTING-mods.md

@@ -242,10 +242,82 @@ with a `MK4xx` finding per site and an `unresolved:` note, with a file and a
 line, for every reach a static scan could not follow. Neither substitutes for a
 real Gold boot.
 
-### 5. `mod.card`
+### 5. What a mod's code can reach
+
+Your code runs in a sandbox (`src/mods/Sandbox.lua`), not against the
+engine's globals. Every chunk you author gets it: `main.lua`, your
+`options_schema`, and anything you `load()` yourself.
+
+The globals the sandbox took away are still *reachable*, as compat
+stand-ins (`src/mods/LegacyCompat.lua`) that answer with the new API
+underneath. A mod written before the sandbox keeps working; it logs one
+warning per call it should migrate, and the mod manager lists them. What
+each stand-in actually does:
+
+| Pre-sandbox call | What it does now | Migrate to |
+| --- | --- | --- |
+| `io.open`, `io.lines`, `love.filesystem.read`/`lines`/`newFile` | reads your own shipped files, then your overlay, then `mod.storage` | `mod:read`, `mod.storage` |
+| `love.filesystem.write`/`append`, `io.open(…, "w")`, `os.remove`, `os.rename` | writes to a private per-mod overlay under `mod_compat/<your id>/` | `mod.storage` |
+| `love.filesystem.getDirectoryItems`/`getInfo` | your own directory plus your overlay | `mod:list`, `mod:info` |
+| `love.filesystem.getSaveDirectory` and friends | a virtual root; anything joined to it lands in your overlay | `mod.storage` |
+| `os.getenv` | `nil`, except home-like names, which answer with that same virtual root | nothing |
+| `love.filesystem.load`, `dofile`, `loadfile` | compiles the chunk into your sandbox | `require`, `mod:read` plus `load` |
+| `love.system` | `getOS`/`getPowerInfo`/`getProcessorCount` read through; clipboard and `openURL` do nothing | `mod.device:powerInfo()`, `mod.steps` |
+| `love.event` | passes through, except `quit`, which does nothing | `mod.events`, `mod.hooks` |
+| `love.mousemoved = fn` and the other callbacks | installs on the real `love` table, the way it always did | `mod.hooks`, `mod.events` |
+| `package` | an inert stub, so `package.path = …` does not crash | `require` |
+
+What has no stand-in, because there is nothing honest to reroute it to:
+
+| Still refused | Why |
+| --- | --- |
+| `love.thread` | a LÖVE thread is a fresh Lua state with the full standard library, which no environment-based sandbox in this state can reach. Use `mod.fetch` for background HTTP (`network`) or `mod.job` for background compute (`background`) — both run your code inside the sandbox instead of outside it |
+| `require("ffi")` | arbitrary C |
+| `debug`, `getfenv`, `setfenv` | each one undoes the sandbox from inside |
+| `io.popen`, `os.execute` | spawning a process |
+| `love.run`, `love.errorhandler` | the engine's own loop and its crash path |
+| replacing a `love` module table (`love.filesystem = {}`) | the engine reads those tables too |
+
+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:list`, `mod:info`, `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. `mod:list("assets")` is the sandboxed `getDirectoryItems` for a
+  folder you shipped; `mod:info` tells file from directory so a walk can
+  recurse.
+- **Ship source, not bytecode.** A precompiled entry file is refused.
+
+`permissions` in the manifest is still a disclosure the manager shows the
+player. `network` gates `require("socket")` and friends plus `mod.fetch`
+(non-blocking HTTP), and `background` gates `mod.job` (compute on a worker
+thread). Those two are the sanctioned ways to work off the main thread now
+that `love.thread` is refused. 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 rerouted globals, the fix is almost always
+`mod.storage`. The overlay is a compatibility floor, not a second storage
+system: it is not scoped per playthrough, it does not migrate, and it is
+the first thing that will be dropped once the mods on the index have
+moved off it. Open an issue if you have a case `mod.storage` does not
+cover.
+
+### 6. `mod.card`
 
 The manifest is the *engine's* contract: identity, load order, dependencies,
-permissions, profile. The card is the *human-facing* one: who made this,
+permissions, profile (see [Manifest specification](docs/modding.md#manifest-specification-manifestjson)).
+The card is the *human-facing* one: who made this,
 what it changes, what it does not do yet. It is never read by the loader's
 merge — only by tooling and the manager's detail pane — so an absent or
 malformed card can never break a load.
@@ -263,7 +335,7 @@ Two fields deserve their own note:
   distributed mod never carries ROM-derived bytes, not even in its preview
   images.
 
-### 6. Tags
+### 7. Tags
 
 Lowercase kebab strings, open vocabulary. The showcase generator
 lowercases and de-dupes. A recommended starting set: `beginner`,

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).

data/scripts/celadon_eevee.lua

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

data/scripts/flavor/game_corner.lua

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

data/scripts/flavor/museum_1f.lua

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

data/scripts/oaks_lab.lua

@@ -38,9 +38,9 @@ local function starterBall(askText, species, choseFlag, ownBall,
     -- inside give_pokemon).  Show the received text first so the
     -- nickname prompt follows "you got X", matching Gen1.
     -- The received text carries sound_get_key_item (OaksLab.asm
-    -- OaksLabReceivedMonText); the jingle plays as the box opens
-    -- (same beat as the Yellow port's starter, #668).
-    { "play_sound", "Get_Key_Item" },                              -- 8
+    -- OaksLabReceivedMonText), so the jingle fires once the box has
+    -- typed out and holds it (same beat as the Yellow port's starter, #668).
+    { "text_sound", "Get_Key_Item" },                              -- 8
     { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 9
     { "give_pokemon", species, 5 },               -- 10
     { "set_flag", "EVENT_GOT_STARTER" },          -- 11
@@ -54,7 +54,7 @@ local function starterBall(askText, species, choseFlag, ownBall,
     { "face_object", 1, "up" },                   -- 15
     { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 16
     { "hide_object", "OAKS_LAB", rivalBall },     -- 17
-    { "play_sound", "Get_Key_Item" },             -- 18 (sound_get_key_item)
+    { "text_sound", "Get_Key_Item" },             -- 18 (sound_get_key_item)
     { "show_text", "_OaksLabRivalReceivedMonText",
       { RAM = rivalBall == "OAKSLAB_CHARMANDER_POKE_BALL" and "CHARMANDER"
               or rivalBall == "OAKSLAB_SQUIRTLE_POKE_BALL" and "SQUIRTLE"
@@ -106,8 +106,8 @@ return {
       { "check_item", "OAKS_PARCEL" },
       { "jump_if_false", "raise_young" },
       -- OaksLabOak1Text.got_parcel → RivalArrives + OakGivesPokedex
+      { "text_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOak1DeliverParcelText" },
-      { "play_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOak1ParcelThanksText" },
       { "take_item", "OAKS_PARCEL", 1 },
       { "stop_music" },
@@ -128,8 +128,8 @@ return {
       { "face_object", 1, "up" },
       { "face_object", 5, "down" },
       { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "text_sound", "Get_Key_Item" },
       { "show_text", "_OaksLabOakGotPokedexText" },
-      { "play_sound", "Get_Key_Item" },
       { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
       { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
       { "face_object", 1, "up" },
@@ -246,9 +246,17 @@ return {
   -- the table sprites; re-entering the lab applies the same HideObject
   -- the gift script now does (OaksLab.asm OakGivesPokedex).
   onEnter = function(game, ow)
-    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
-      return
+    local flags = game.save.flags or {}
+    if flags.EVENT_GOT_STARTER and not flags.EVENT_BATTLED_RIVAL_IN_OAKS_LAB then
+      local rival = ow:npcByIndex(1)
+      if rival then
+        rival.cellX = flags.EVENT_CHOSE_CHARMANDER and 7
+          or flags.EVENT_CHOSE_SQUIRTLE and 8 or 6
+        rival.cellY = 4
+        rival.px, rival.py = rival.cellX * 16, rival.cellY * 16
+      end
     end
+    if not flags.EVENT_GOT_POKEDEX then return end
     local Commands = require("src.script.Commands")
     local ctx = { save = game.save, game = game, overworld = ow }
     Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX1")
@@ -286,6 +294,7 @@ return {
       -- fanfare for the taunt/challenge exchange, same as the Yellow port
       -- (oaks_lab_yellow.lua); it was silently dropped here (#596).
       local rows = {
+        { "face_player_dir", "up" },
         { "stop_music" },
         { "play_music", "Music_MeetRival" },
         { "show_text", "_OaksLabRivalIllTakeYouOnText" },         -- 1
@@ -309,28 +318,19 @@ return {
       local base = #rows
       local party = flags.EVENT_CHOSE_BULBASAUR and 3
                     or flags.EVENT_CHOSE_SQUIRTLE and 2 or 1
+      table.insert(rows, { "save_end_battle_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
       table.insert(rows, { "start_battle", "trainer", "OPP_RIVAL1", party })
       -- OaksLabRivalEndBattleScript: heal + flag on win or loss; no blackout
       table.insert(rows, { "heal_party" })
       table.insert(rows, { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" })
-      -- OaksLabRivalEndBattleScript: on WIN, print the "picked the wrong
-      -- POKéMON!" gloat, then BOTH win and loss print the shared exit line
-      -- _OaksLabRivalSmellYouLaterText ("OK! I'll make my POKéMON fight to
-      -- toughen it up!\012<PLAYER>! Gramps! Smell you later!") before Blue
-      -- marches out.  A loss skips only the gloat (that taunt was already
-      -- shown in-battle via Rival1WinText), never the exit line (#231).  The
-      -- jump_if_false convergence point is the exit line: base+6 indexes the
-      -- SmellYouLater row below, so WIN falls IPicked -> SmellYouLater and
-      -- LOSS jumps straight to SmellYouLater (both then walk-out + hide).
       table.insert(rows, { "jump_if_false", base + 6 })
-      table.insert(rows, { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
       table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
       -- OaksLabRivalStartsExitScript: parting shot, rival exit fanfare, then
       -- walk out past the player.  The fanfare was dropped here (#683) -- the
       -- parcel scene above already plays Music_MeetRival on both arrival and
       -- departure (lines 144-146), and this exit should match (#596).
       table.insert(rows, { "stop_music" })
-      table.insert(rows, { "play_music", "Music_MeetRival" })
+      table.insert(rows, { "play_music", "Music_MeetRival", { start = "rival" } })
       table.insert(rows, { "move_npc_to", 1, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
       table.insert(rows, { "play_music", "Music_OaksLab" })

data/scripts/oaks_lab_yellow.lua

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

data/scripts/story.lua

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

data/scripts/story2.lua

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

data/scripts/story4.lua

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

data/scripts/story5.lua

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

data/scripts/victories.lua

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

docs/ios-sideload.md

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

docs/launcher.md

@@ -16,6 +16,7 @@ save directory as:
 | nil / `"rom"` | `picked_rom.gb` (open) |
 | `"mod"` | `picked_mod.zip` (open) |
 | `"sav"` / `"save"` | `picked_save.sav` (open) |
+| `"required_import"` | `picked_required_import.bin` (open) |
 
 Export uses a separate API: `love.system.createFile(suggestedName)` →
 `GameActivity.showCreateDocument` (`ACTION_CREATE_DOCUMENT`), which copies
@@ -130,18 +131,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/mod-api-gen2-compat.md

@@ -96,14 +96,14 @@ The launcher asks the same question of a mod's dependencies: one whose hard
 dependency does not run on the selected game reads `Needs <id> (not for Gold)`,
 matching the loader's contagious skip.
 
-A separate overlay, `options.modsByVersion[version][id]`, is where a per-game
-enable flag will live. It is a preview: `SaveData.PER_VERSION_MODS` is `false`,
-so `SaveData.modScope` answers nil for every caller and the launcher panel, the
-in-game manager and the loader all read *and* write the one shared
-`options.mods` flag. Nothing consults the overlay for enablement until that
-flips, which is deliberate: the overlay is plantable from an imported
-`.g1rmodlist`, and a reader scoped differently from the writers would show a
-mod set no boot would honour.
+A separate overlay, `options.modsByVersion[version][id]`, holds each game's
+enable flag. The launcher shows a coloured Red / Blue / Yellow / Gold checkbox
+for every installed mod, and the loader and in-game manager read the same
+game-specific answer on the next boot. On the first launch after this feature,
+the existing shared state is copied to every game, so a mod that was enabled
+remains enabled everywhere; after that, changing one checkbox affects only
+that game. New mods still default to enabled on every game (experimental mods
+retain their explicit opt-in default).
 
 That is deliberate. Gold reimplements the battle engine, the overworld, the
 script VM and the save format, so a Gen 1 mod dropped into a Gold boot would
@@ -118,10 +118,11 @@ Gen 2 games no longer loads on Red, Blue or Yellow. Say `["all"]` or list both
 generations if you want both.
 
 Two riders. **A hard dependency that does not run here takes the dependent down
-with it**, as a skip rather than a failure and carrying the dependency's own
-wording (`depends on X, which does not run here (For Blue, not Red)`), so the
-whole chain has to cover the same games. And **the claim is yours, not the last
-word**: it is the manager's `TRY HERE ANYWAY` row that lets a player run a mod
+with it** (unless scoped to specific games, e.g.
+`dependencies: [{ id = "x", games = ["gen2"] }]`), as a skip rather than a
+failure and carrying the dependency's own wording (`depends on X, which does not
+run here (For Blue, not Red)`), so the whole chain has to cover the same games.
+And **the claim is yours, not the last word**: it is the manager's `TRY HERE ANYWAY` row that lets a player run a mod
 whose author never opted in, which is the only route for a mod written before
 the field existed. The override is per game -- `options.modsGen2[id]` is a
 `{ [version] = true }` table, so forcing a mod onto Red does not force it onto
@@ -239,7 +240,7 @@ resolves to the weaker claim:
 | `warned` | present, answers nil or degrades, and names itself once with the mod attributed |
 | `absent` | deliberately not served; a nil read is the honest failure |
 
-Today that is 288 backed, 32 warned and 161 absent across the fifteen modules.
+Today that is 291 backed, 32 warned and 161 absent across the fifteen modules.
 `notes` keys are documentation topics rather than a member list -- dotted paths
 (`save.money`), field names (`warpAt`), hook names (`hook ui.pc.items`) and
 bare topics (`identity`, `iteration`, `rawset`) all appear there. `members` is
@@ -474,6 +475,8 @@ Generation-agnostic; nothing to adapt.
 (`src/world/gen2/WorldAPI.lua`). Two differences show through and are
 documented on the module: Gold's world is not a stack state, and Gen 2 event
 flags are numeric ids into `wEventFlags` rather than string keys.
+`mapOverview` returns the same read-only terrain, tile-shading, and marker
+shape, using Gold's live object masks and event flags to omit collected items.
 `spawnNpc` / `removeNpc` append onto the map def's own object list, the way the
 Gen 1 arm does, so a spawned actor is pooled, drawn, walked and talked to like
 an extracted one and survives a map reload; it is not serialized, so a mod
@@ -483,6 +486,11 @@ has its own entry points for (`start_battle "wild" species level`, `warp`,
 **by name, before the first row runs**, so a mod never gets a half-run queue.
 `marchInPlace` still has no Gen 2 equivalent (the Gen 2 movement stream has no
 byte for it) and returns `nil, reason` rather than approximating one.
+`availableFieldActions` and `useFieldAction` expose the same contextual field
+item and move records in both games. Gold extends the shared ids with its own
+`headbutt`, `whirlpool`, `waterfall`, `sweet_scent`, and `squirtbottle`
+actions. Each engine keeps ownership of its inventory, badges, terrain,
+surfing, bike, fishing, and field-move rules.
 
 **Hooks and events that fire on Gold.** Every name below is the Gen 1 name
 carrying the Gen 1 payload keys, because Gold's call sites reuse them rather
@@ -531,8 +539,9 @@ gains a field instead of the name gaining a prefix.
   `pokemon.level_up`, `pokemon.move_learned`; hooks `battle.damage`,
   `battle.crit`, `battle.accuracy`, `battle.turn_order`,
   `battle.enemy_action`, `battle.run`, `battle.exp_award`, `exp.gain`,
-  `catch.rate`, `trainer.party`, `battle.overlay`, `battle.low_health_alarm`
-  and `battle.catch_exp`. One payload difference: Gen 1's vanilla
+  `catch.rate`, `trainer.party`, `battle.overlay`, `battle.low_health_alarm`,
+  `battle.catch_exp`, `battle.bottom_ui_visible` and
+  `battle.status_hud_visible`. One payload difference: Gen 1's vanilla
   `battle.low_health_alarm` link reads `ctx.battle.data`, and Gold's battle
   screen has no `.data` field, so the Gen 2 site **adds** `ctx.data` beside the
   Gen 1 keys. A mod that calls `nextFn` is unaffected; one that reaches through
@@ -544,11 +553,13 @@ gains a field instead of the name gaining a prefix.
   each row's decision in `evolution.check`. The hook passes `data` where Gen 1
   passes `game`; positions 2-4 (mon, row, trigger) match.
 - *The frame (`src/core/Game2.lua`):* hooks `input.step`, `input.pointer`,
-  `render.zones`, `render.compose`, `render.letterbox`, `render.hud`. Each sits
+  `render.zones`, `render.compose`, `render.output_enabled`, `render.output`,
+  `render.letterbox`, `render.hud`. Each sits
   at the same moment `src/core/Game.lua` and `src/render/Renderer.lua` raise it
   -- the logic tick before the pad is read, a pointer the touch overlay gets
   first refusal on, the palette zone list handed to the present pass, the
-  letterbox, and the finished playfield rect -- and carries the same payload.
+  composed frame before GBCFX, the letterbox, and the finished playfield rect
+  -- and carries the same payload.
   `render.hud`'s `gameX` / `gameY` really is where Gold's dialogue boxes and
   menus land, because `Chrome.fitScale` / `fitOrigin` and `World:fitScale`
   compute the same number. `render.zones` is handed `nil` in GBC mode (Gold
@@ -757,6 +768,11 @@ name and the existing payload, plus fields where Gen 2 genuinely carries more
 
 The list is much shorter than it was. What is outstanding, in descending value:
 
+- `trainer.before_battle`: Gold constructs and pushes its trainer battle in
+  `src/world/gen2/World.lua:startBattle`, which does not yet expose a deferred
+  preparation boundary or a battle-local player-party view. Gen 1 mods can use
+  the hook documented in `docs/modding.md`; do not claim Gold compatibility
+  when that selection is required.
 - `pokemon.before_give` / `pokemon.received`: Gold has no give-mon seam of its
   own yet.
 - `link.*` and `trade.completed`: a Gold boot offers no link menu at all. The

docs/mod-option-schema.md

@@ -46,7 +46,11 @@ when the runtime schema is absent. The supported row types are `toggle`,
 `choice`, `number`, and `text`. Their optional fields retain the meanings
 established by the existing in-game option UI: choices are `[label, value]`
 pairs, numeric rows may provide `min`, `max`, and `step`, and text rows may
-provide `maxLen`.
+provide `maxLen`. A row may also use
+`visible_if = {key = "mode", equals = "compact"}` or replace `equals` with
+`not_equals`. This only hides the in-game menu row; the schema and stored value
+remain available, and consumers that do not implement conditions may ignore
+the field.
 
 Only mods that are enabled and successfully loaded in the current boot are
 included. A disabled or failed mod must not contribute rows. If an older
@@ -69,9 +73,10 @@ it may ignore an unknown row type or optional field.
 For compatibility with files produced by the original unversioned prototype,
 a missing `schema_version` means version 1. Consumers must ignore documents
 with a newer version rather than guessing at their shape. Producers must bump
-the version whenever they change the document shape or the meaning of an
-existing field. Version 1 is therefore the legacy unversioned format as well
-as the explicitly versioned format shown above.
+the version whenever they change the document envelope or the meaning of an
+existing field. New optional row fields that older consumers can safely ignore
+do not require a bump. Version 1 is therefore the legacy unversioned format as
+well as the explicitly versioned format shown above.
 
 ## Migration note
 

docs/modding.md

@@ -21,6 +21,146 @@ luajit tools/gen_registry_docs.lua
 luajit tools/gen_registry_docs.lua ../gen1recomp.wiki
 ```
 
+## Manifest specification (`manifest.json`)
+
+Every mod contains a root `manifest.json` defining its metadata, supported games, and dependencies for the engine loader.
+
+```json
+{
+  "id": "my_mod",
+  "name": "My Cool Mod",
+  "version": "1.0.0",
+  "api": 2,
+  "entry": "main.lua",
+  "profile": "content",
+  "category": "GAMEPLAY",
+  "games": ["gen1", "gen2"],
+  "game_version": ">=0.0.0-dev <2.0.0",
+  "priority": 100,
+  "dependencies": [
+    "helper_lib@^1.0.0",
+    { "id": "pokegear_cards", "games": ["gen2"], "range": "^1.0.0", "github": "1jamie/pokegear_cards" }
+  ],
+  "optional_dependencies": [
+    "gen1_modern_ui"
+  ],
+  "required_imports": [
+    {
+      "id": "stadium2",
+      "name": "Pokemon Stadium 2 ROM",
+      "description": "Pokemon Stadium 2 (USA), any supported N64 byte order",
+      "file": "stadium2.z64",
+      "format": "n64",
+      "size": 67108864,
+      "md5": ["00000000000000000000000000000000"]
+    }
+  ],
+  "optional_imports": [
+    {
+      "id": "bonus_source",
+      "name": "Optional bonus source",
+      "file": "bonus.bin",
+      "md5": "00000000000000000000000000000000"
+    }
+  ],
+  "conflicts": [],
+  "permissions": ["engine_internals"],
+  "description": "A brief description of the mod.",
+  "github": "author/my_mod"
+}
+```
+
+### Manifest Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique identifier (lowercase alphanumeric, underscores, hyphens). |
+| `name` | `string` | Human-readable title shown in launcher and manager. |
+| `version` | `string` | Semantic version string (e.g. `"1.0.0"`). |
+| `api` | `integer` | Mod API level (`2` for current standard, `1` for legacy). |
+| `entry` | `string` | Entry Lua file path relative to mod root (usually `"main.lua"`). |
+| `profile` | `string` | Mod profile: `"content"`, `"overhaul"`, or `"total_conversion"`. |
+| `category` | `string` | Categorization chip (e.g. `"GAMEPLAY"`, `"CONTENT"`, `"UI"`, `"AUDIO"`). |
+| `games` | `array` | Supported game versions: `["gen1"]`, `["gen2"]`, `["red"]`, `["blue"]`, `["yellow"]`, `["gold"]`, or `["all"]`. |
+| `game_version`| `string` | Semver range of required engine version (e.g. `">=0.0.0-dev <2.0.0"`). |
+| `priority` | `integer` | Load priority order (lower numbers load earlier; dependencies always precede dependents regardless of priority). |
+| `dependencies` | `array` | Hard required dependencies. A mod will not load if a required dependency is missing or disabled for the active game. |
+| `optional_dependencies` | `array` | Soft dependencies. Guarantees that if the target mod is present and active, it loads *before* this mod without blocking load if absent. |
+| `required_imports` | `array` | User-supplied files required by this mod. The launcher validates and copies each file into this mod's `baseroms/` directory; the mod does not load while one is missing. |
+| `optional_imports` | `array` | User-supplied files that unlock optional mod functionality. They use the same validation and private-copy flow but never block the mod from loading. |
+| `conflicts` / `incompatible` | `array` | List of mod IDs that cannot run concurrently with this mod. |
+| `permissions` | `array` | Requested privileges (e.g. `["engine_internals"]`, `["network"]`, `["filesystem"]`). |
+| `log_url` | `string` | Optional https URL for `mod.postLog` log reporting (api 2; requires the `network` permission). |
+| `github` | `string` | GitHub repository (`"owner/repo"`) used for update checks and dependency download links. |
+
+### Declaring Dependencies & Scoping
+
+Dependencies in `dependencies` and `optional_dependencies` can be declared in several formats:
+
+1. **Simple string**: `"mod_id"`
+2. **Version-pinned string**: `"mod_id@^1.2.0"`
+3. **Repository-hinted string**: `"mod_id#owner/repo"` or `"mod_id@^1.2.0#owner/repo"`
+4. **Structured object**:
+   ```json
+   {
+     "id": "mod_id",
+     "range": "^1.2.0",
+     "games": ["gen2"],
+     "github": "owner/repo"
+   }
+   ```
+
+#### Version-Scoped Dependencies
+When a mod supports multiple games (`"games": ["gen1", "gen2"]`), a dependency can specify `"games": ["gen2"]` to indicate it is only required when booting Gen 2. When booting Gen 1, the engine will ignore the dependency, preventing unnecessary boot blocks on games that do not need it.
+
+### Required user-supplied files
+
+`required_imports` and `optional_imports` keep copyrighted or otherwise user-owned source material
+out of mod archives while giving every platform the same installation flow.
+Each object requires a stable `id`, a display `name`, a destination `file`
+(a filename, never a path), and one MD5 digest or an array of accepted MD5
+digests. `format` is either `"raw"` (the default) or `"n64"`. An optional
+`description` gives players dump or region guidance in the import panel.
+`size` declares the exact canonical byte length; `max_size` declares a smaller
+per-import ceiling when an exact size is not appropriate. Every import also
+has an engine-enforced 128 MiB ceiling and is rejected before hashing when its
+filesystem reports an invalid size.
+
+For `"n64"`, the launcher recognizes `.z64`, `.v64`, and `.n64` byte orders,
+strips a recognized 512-byte copier header, converts the bytes to canonical
+big-endian `.z64` order, and then checks MD5. The canonical bytes are written
+to `mods/<mod-id>/baseroms/<file>`. Each selection is a private grant to that
+mod: the launcher never scans or copies another mod's imported files merely
+because its manifest names the same digest. Mods read the result with their existing scoped `mod:read` API, for
+example `mod:read("baseroms/stadium2.z64")`; no host path or new filesystem
+permission is exposed. Missing `required_imports` block the mod before its
+entry chunk runs; missing `optional_imports` remain visible in the same
+launcher panel but do not block loading.
+
+MD5 here identifies a known dump because ROM databases commonly publish it;
+it is not a security or authenticity guarantee. Do not paste the SHA-1 used by
+Gen1Recomp's own game-ROM importer into an import's `md5` field. Mod archives
+must not include anything beneath `baseroms/`. The engine records a validation
+receipt keyed by file size and modification time so launcher refreshes and
+later boots do not repeatedly hash an unchanged imported ROM.
+
+New mobile code should call `love.system.pickFile("required_import")`. The
+older iOS-only `"stadium"` picker kind remains temporarily for compatibility.
+Android now returns `false` for unknown picker kinds instead of treating them
+as game-ROM picks.
+
+### Platform import flow
+
+The same per-mod validation and private `mods/<mod-id>/baseroms/` destination
+applies on every supported platform. Windows, macOS, and Linux use the
+launcher file chooser. Android uses the Storage Access Framework, and iOS uses
+the Files document picker; both stage the choice as `picked_required_import.bin`
+before validation. Xbox/UWP uses its native picker and hands the launcher a
+temporary path. Switch/NX has no host picker, so the player copies a file to
+`imports/baseroms/` over MTP and chooses the import again. No platform grants
+the mod a host filesystem path or bypasses the manifest's size, format, and MD5
+checks.
+
 ## Mods and Gold (Gen 2)
 
 The mod API is one API across both generations, but Gold runs its own battle
@@ -66,7 +206,8 @@ optional visual `tileRows` at 2x resolution, and optional `tileDetailRows` at
 `"3"` (darkest); their matching width and height fields describe the grid.
 `markers` contains active `{ kind, x, y }` points in map-cell coordinates for
 `warp`, visible `item`, and untaken `hidden` locations. All fields are
-read-only snapshots; mods choose which layers to render.
+read-only snapshots; mods choose which layers to render. Red and Gold expose
+the same contract while applying their own object and event visibility rules.
 
 ## Party ordering
 
@@ -76,6 +217,72 @@ Companion UIs and alternate party screens can call
 operation is accepted only during idle overworld play; menus, movement,
 scripts, battles, and transitions leave the party untouched.
 
+## Contextual field actions
+
+`mod.world:availableFieldActions()` returns the field items and moves that can
+start at the player's current position. Both games expose `bicycle`, `fish`,
+`cut`, `surf`, `strength`, `flash`, `dig`, and `teleport`; Gold additionally
+exposes `headbutt`, `whirlpool`, `waterfall`, `sweet_scent`, and the
+contextual `squirtbottle` key item. Fishing rows include the owned rods that
+are valid choices. The list is empty while the world is busy, and omits an
+action whenever its item, move, badge, terrain, or engine state forbids it.
+The optional second return is `"world is busy"` during transient input locks
+or `"no overworld"` before a playable world exists.
+
+Call `mod.world:useFieldAction(id, opts)` to perform a listed action through
+the active game's own field-item path. Fishing accepts `{ rod = "OLD_ROD" }`
+and chooses automatically when only one rod is available. Invalid, stale, and
+busy requests return `nil` plus a reason without changing game state. Mods do
+not need generation-specific badge, terrain, bike, fishing, or field-move
+logic. Action lists are extensible; callers should render the records they
+understand and ignore unknown ids rather than assuming a fixed list length.
+
+## Read-only battle snapshots
+
+`mod.battle:snapshot()` returns `nil` outside a battle and a copied battle
+record while one is active. Gen 1 (Red, Blue, and Yellow) and Gold expose the
+same core fields:
+`revision`, `kind`, `catchable`, `prompt`, `message`, `turn`, `player`,
+`enemy`, `party`, `moves`, and `items`. Pokémon, moves, messages, and items in
+the result are detached records; changing them cannot change the battle.
+`revision` stays stable while the visible battle context is unchanged and
+advances when it changes, so a UI can skip rebuilding an identical view.
+
+Pokémon records contain `species`, `name`, `level`, `hp`, `maxHp`, `status`,
+and `active` (plus `slot` in `party`). Move records contain `slot`, `id`,
+`name`, `pp`, `maxPp`, `type`, `power`, `accuracy`, and `disabled`. Gen 1 also
+reports the actual ruleset-aware `displayPower`, `hitChance` percentage, and
+`effectiveness` multiplier (`10` neutral, `20` super-effective, `5`
+resisted). Item rows contain `id`, `name`, `count`, `ball`, `needsTarget`, and
+an optional stock `catchChance` percentage.
+
+`prompt` describes the currently visible choice (`menu`, `moves`, `party`,
+`advance`, `safari`, or `mimic`) and is `locked` when another screen or battle
+phase owns input. Generation-specific features remain optional: Gen 1 includes
+battle medicine, balls, catch previews, Safari balls, and Mimic choices;
+Gold currently returns an empty `items` list rather than guessing at its
+pocketed PACK flow. Callers should ignore unknown fields and tolerate absent
+optional ones.
+
+## Battle menu intents
+
+`mod.battle:submit(intent)` applies a validated choice to the snapshot the mod
+just read. Every intent needs a mod-owned, strictly increasing positive
+integer `id` and the latest snapshot `revision`. Stale, replayed, covered, or
+invalid choices return `nil` plus a reason without changing the battle.
+
+The shared Red, Blue, Yellow, and Gold intents are:
+
+- `{ kind = "menu", choice = "fight" }` (`party`, `item`, and `run` are the
+  other accepted choices)
+- `{ kind = "move", slot = 1..4 }`
+- `{ kind = "back" }` while the move menu is active
+
+Menu choices and moves use the same engine methods as the native controls;
+`party` and `item` open the native screens rather than exposing or duplicating
+their mutable logic. Tutorial, link, Safari, forced, stale, and covered battle
+states refuse these core intents. Use `mod.input` for ordinary text advance.
+
 ## Rendering pipelines
 
 Most registries hand the engine *content*. `render_pipelines` hands it
@@ -237,6 +444,25 @@ local keys, code, message = mod.storage:list(game, "history/quick")
 local deleted, code, message = mod.storage:delete(game, "history/quick/q0001")
 ```
 
+For independently generated binary data, use the opaque byte methods. They
+accept and return the exact Lua string of bytes, including NUL bytes and bytes
+that are not valid text:
+
+```lua
+local ok, code, message = mod.storage:writeBytes(
+  game, "cache/maps/pallet/terrain", encodedMesh)
+local encodedMesh, code, message = mod.storage:readBytes(
+  game, "cache/maps/pallet/terrain")
+```
+
+Opaque values are limited to 512 MiB per key. The engine stores them without
+decoding, compression, or an engine-defined file format, and never executes
+them. A consuming mod owns validation of its format, fingerprint, checksum,
+and compression metadata. Byte writes are staged and compared byte-for-byte
+before replacement, and reads can recover a valid backup after an interrupted
+write. Existing table values and opaque byte values use one shared logical key
+space; delete a key before changing its value from one type to the other.
+
 `context` returns `{ engineVersion, gameVersion, playthroughId }`. The engine
 version is compatibility metadata; physical launcher-slot and path identity stays
 private. A title-selected context may additionally contain `normalSavedAt`, the
@@ -245,19 +471,22 @@ progress or a slot/path handle.
 
 At the title screen only, `mod.storage:selected(game)` returns a bound storage
 facade for the launcher-selected existing playthrough, or `nil, code, message`.
-Resolving this facade is read-only: it never allocates an identity, adopts a
+Resolving this facade is non-allocating: it never allocates an identity, adopts a
 fresh New Game, or exposes a slot id/path. Its `context()`, `read(key)`,
-`write(key, value)`, `list(prefix)`, and `delete(key)` methods have the same
-data-only and transaction contract as `mod.storage`, but remain restricted to
-the calling mod's selected existing namespace. It is intended for title tools
-that need to browse or manage durable history before the first normal SAVE.
+`write(key, value)`, `readBytes(key)`, `writeBytes(key, bytes)`,
+`list(prefix)`, and `delete(key)` methods have the same scoped and
+transactional contract as `mod.storage`, but remain restricted to the calling
+mod's selected existing namespace. It is intended for title tools that need to
+browse or manage durable history before the first normal SAVE.
 
-Values must be tables containing serializable data only. Keys are conservative
-slash-separated segments (letters, digits, `_`, `-`); paths and filesystem
-handles are never exposed. Writes are staged and decode-verified, reads recover
-from a valid staged/backup generation, and methods return structured errors for
-normal data or I/O failures. The playthrough identity is allocated lazily on the
-first storage/checkpoint call, so an unused API changes no save bytes.
+Table values must contain serializable data only. Opaque values must be Lua
+strings. Keys are conservative slash-separated segments (letters, digits, `_`,
+`-`); paths and filesystem handles are never exposed. Table writes are staged
+and decode-verified; opaque writes are staged and byte-verified; reads recover
+from a valid staged/backup generation. Methods return structured errors for
+normal data, byte validation, and I/O failures. The playthrough identity is
+allocated lazily on the first storage/checkpoint call, so an unused API changes
+no save bytes.
 
 `mod.checkpoints` captures and reconstructs engine-owned semantic runtime state:
 
@@ -352,6 +581,43 @@ 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.
 
+Gen 1 trainer encounters also expose `trainer.before_battle` after the
+challenge text and immediately before battle construction. This lets a mod
+defer the encounter while it collects a player choice through a registered
+screen, then resume with a battle-local view of the save party:
+
+```lua
+mod.hooks:wrap("trainer.before_battle", function(next, game, context, continue)
+  -- context = { trainerClass, partyIndex, mapId, npcId }
+  mod.ui.push(game, "party_registration", {
+    onConfirm = function(indices)
+      continue({ playerPartyIndices = indices })
+    end,
+    onCancel = function()
+      continue({ cancel = true })
+    end,
+  })
+  return true
+end)
+```
+
+Return `true` only when retaining `continue` for a later callback. Calling
+`continue({ cancel = true })` ends the encounter without constructing a battle;
+the normal encounter completion callback returns control to the overworld and
+no trainer-defeated state is written. A cancelled sight encounter is suppressed
+at the current player cell so it cannot immediately reopen; moving one cell or
+talking to the trainer permits a new challenge. Calling `continue()` uses the
+full save party; passing
+`{ playerPartyIndices = { 2, 4, 5 } }` uses those ordered, one-based party
+members for initial send, switching and forced replacement, exhaustion,
+experience traversal, and battle party displays. The continuation is one-shot.
+An empty, duplicate, out-of-range, or otherwise malformed list safely falls
+back to the full party. The view references the original Pokemon records and
+never reorders or replaces `game.save.party`; trainer battle checkpoints retain
+the selected indices. Mods remain responsible for selection policy and should
+use only public `mod.ui`, hook, and save APIs. See RFC 0010 for the exact
+contract and compatibility guarantees.
+
 ## Developer console
 
 Boot with developer mode on to unlock the in-game console and hot-reload
@@ -439,6 +705,20 @@ oldest queued event as `"action,x,y"` in submitted-frame coordinates, or `nil`.
 This is what lets a mod lay the two passes out as two stacked Game Boy screens,
 or push one onto a second screen, without the engine knowing the layout.
 
+`render.output_enabled` and `render.output` are the later, whole-window seam
+for mods that need the engine's normal composite rather than its separate
+layers. It runs after registered present pipelines and before GBCFX,
+`render.hud`, and touch controls. A mod wraps both hooks: the first returns
+`true` only while output ownership is needed, and the second receives
+`(next, ctx)` with `canvas`, `width`, `height`, `gameX`, `gameY`, `gameWidth`,
+`gameHeight`, `scale`, `dpiX`,
+`dpiY`, and `generation`. Returning `true` from `render.output` takes over the
+window; calling `next(ctx)` keeps the normal presentation. Both hooks default
+to `false`. Enabling the seam requires a full-window canvas for that frame.
+With no `render.output` subscriber, or while `render.output_enabled` is false,
+the existing presentation path is unchanged. `render.compose` takes precedence
+when it owns the frame.
+
 `screen.render_visible` receives `(next, state)` while the main screen is being
 composed. Return `false` to omit that state from drawing, opacity selection and
 palette-zone ownership. The state remains on the stack and keeps its normal
@@ -454,6 +734,7 @@ 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.
+Both hooks apply to Gen 1 and Gen 2 battles.
 Text boxes and YES/NO prompts pushed above a battle inherit a `false` result
 for that battle, so hiding the bottom layer cannot leave their white backing
 behind under another overlay. Text boxes also pass through the hook as their
@@ -544,3 +825,228 @@ 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.
+
+## Background HTTP
+
+`mod.fetch` is how a mod does work off the main thread. It is behind the
+`network` permission in `manifest.json`, the same one that gates
+`require("socket")`, and the player sees it in the mod manager.
+
+```lua
+-- somewhere once
+local job = mod.fetch:get("https://example.com/data.json")
+
+-- in a hook or update, every frame -- poll never blocks
+if job then
+  local r = mod.fetch:poll(job)
+  if r.status ~= "pending" then
+    if r.status == "ok" then use(r.body) else warn(r.err) end
+    mod.fetch:release(job)
+    job = nil
+  end
+end
+```
+
+`get(url, opts)` returns an opaque handle, or `nil` plus a reason. `opts`
+takes `accept` (a request Accept header) and `maxSeconds` (clamped to 30).
+`poll(handle)` returns `{ status, body, err, progress }` where `status` is
+`"pending"`, `"ok"`, `"error"` or `"cancelled"`; it is a copy, and it never
+blocks, so calling it every frame is the intended use. `release(handle)`
+frees a finished job — do it, or you will hit the ceiling. `cancel(handle)`
+drops a result you no longer want. `available()` is `false` when the build
+has no transport and for mods without the permission, so a probe is safe.
+
+The rules worth knowing before you design around it:
+
+- **http and https only.** The underlying transport also speaks `file://`,
+  `ftp://` and `scp://`; those are refused, on the initial URL and on any
+  redirect. `mod.fetch` is not a way to read a local file.
+- **Four requests in flight per mod.** The worker pool is shared with the
+  launcher's own downloads, so one mod cannot fill it. Over the ceiling,
+  `get` returns `nil` and a reason until you release something.
+- **Handles are yours alone.** A handle from another mod, a fabricated
+  table, or a guessed number all poll as `"error"`.
+- **Your mod id is in the User-Agent**, so a server operator can see who is
+  calling and a mod cannot pose as the launcher.
+- Jobs are released when your mod unloads.
+
+This is deliberately not `love.thread`. A LÖVE thread is a fresh Lua state
+with a full standard library that the sandbox cannot reach, so handing one
+to a mod would undo every other rule; `mod.fetch`'s workers run engine
+code, so a mod gets asynchrony without gaining any new reach.
+
+## Log reporting
+
+`mod.postLog(body, opts)` is the one-way exception to the rule that a mod
+decides where it talks. It reports a debug/crash log to the https URL the
+manifest declares in `log_url`, and it is the only API that may not be
+pointed at a caller-chosen address:
+
+```json
+{
+  "permissions": ["network"],
+  "log_url": "https://logs.example.com/receive"
+}
+```
+
+The URL is validated at load: it must be `https://`, and declaring it
+without the `network` permission is a load violation for api 2 mods. The
+destination is reviewed when the mod ships, not chosen per call, so a mod
+cannot aim this at arbitrary hosts or read back anything a server replies.
+
+```lua
+-- fire and forget; poll() never blocks, same shape as mod.fetch
+local job = mod:postLog("session crashed at 0x1f3a\n" .. logText)
+```
+
+`postLog(body, opts)` returns the same opaque handle as `mod.fetch:get`,
+polled and released through `mod.fetch:poll` / `mod.fetch:release`. `opts`
+is a closed list with one switch: `format`, either `"text"` (the default)
+or `"json"`. `json` wraps the body in an envelope of `{ ts, mod, format,
+body }` so a server can attribute and sort reports; any other key or value
+is refused before a job is submitted. The body is capped at 64 KB, the
+transfer is bounded by the same worker ceilings as `mod.fetch`, and the
+response body is never returned to the mod.
+
+## Background jobs
+
+`mod.fetch` covers work waiting on a server. `mod.job` covers work waiting on
+the CPU — generating a map, crunching a table, anything that would otherwise
+stall a frame. It is behind the `background` permission in `manifest.json`.
+
+Ship the job as its own file inside your mod:
+
+```lua
+-- mods/your_mod/jobs/crunch.lua
+local arg = ...
+local total = 0
+for i = 1, arg.n do total = total + i end
+return { total = total }
+```
+
+```lua
+-- in your entry file
+local job = mod.job:run("jobs/crunch.lua", { n = 1e6 })
+
+-- later, in a hook -- poll never blocks
+local r = mod.job:poll(job)
+if r.status == "ok" then
+  use(r.result.total)
+  mod.job:release(job)
+end
+```
+
+`run(script, arg, opts)` returns an opaque handle, or `nil` plus a reason.
+`opts.maxSeconds` sets the job's time budget (default 5, clamped to 30).
+`poll(handle)` returns `{ status, result, err }` with `status` one of
+`"pending"`, `"ok"`, `"error"` or `"cancelled"`. `release(handle)` frees it.
+`available()` is `false` on a host without threads and for mods without the
+permission, so a probe is always safe.
+
+**A job is pure compute.** This is the part to design around, not a detail:
+
+- **Plain data in, plain data out.** Numbers, strings, booleans and tables of
+  them. A function, userdata, a cycle or a table key that is not a string or
+  number is refused at your `run` call with a reason. Nothing is shared —
+  your argument is snapshotted, and mutating the original afterwards does not
+  reach the job.
+- **No engine API, no game state, no storage.** `require` is refused inside a
+  job, and there is no `mod` object. A job cannot read the party, write
+  `mod.storage`, or touch a registry. Get what it needs into the argument and
+  act on the result back on the main thread.
+- **Your script is a file in your mod folder.** The path goes through the same
+  rules as `mod:read`; `..`, absolute paths and drive letters are refused.
+- **Two jobs per mod, four on the machine.** Over the limit, `run` returns
+  `nil` and a reason until you release one.
+- **The budget bounds how long YOU wait, not how long the work runs.** Past
+  `maxSeconds`, `poll` reports an error and the result is dropped if it ever
+  arrives — but the thread runs to its own end. There is no way to stop a
+  LÖVE thread from outside, and every attempt to stop one from inside was
+  worse than the disease (a debug hook does not reliably interrupt LuaJIT,
+  and raising from one wedged the whole process). `cancel(handle)` is the
+  same deal: it drops the result, it does not stop the work.
+
+  So **write jobs that terminate.** A job with an infinite loop will keep one
+  core busy until the game closes. It will not freeze the game — the main
+  thread stays responsive and quitting still works — but nothing will reclaim
+  that core in the meantime.
+
+Your job script runs in the same sandbox your entry file does, so `io`, `os`,
+`debug`, `ffi`, `package` and `love.filesystem` are absent there too. That is
+the whole reason this exists rather than `love.thread`: a raw LÖVE thread is a
+fresh Lua state with a full standard library that the sandbox cannot reach, so
+handing one to a mod would undo every other rule. Here the worker builds your
+sandbox first and loads your chunk into it.
+
+## Pre-sandbox globals (compat)
+
+A mod written before the sandbox landed does not have to be updated to
+load. `io`, `package`, `dofile`, `loadfile`, `os.getenv`, `love.filesystem`,
+`love.system` and `love.event` are all present again as compat stand-ins
+(`src/mods/LegacyCompat.lua`), and assigning a LÖVE callback
+(`love.mousemoved = fn`) installs on the real table the way it always did.
+Every stand-in call logs one warning naming its replacement, and
+`loader:legacyReport(modId)` returns the same list with call counts, which
+is what a "needs updating" badge should read.
+
+The stand-ins are not the old globals. Paths are classified rather than
+passed through:
+
+- A path inside your own mod directory reads the file you shipped.
+- Anything else, including an absolute path, resolves into a private
+  per-mod overlay at `mod_compat/<your id>/` under the save directory.
+  Two mods naming the same path never see each other's bytes, and nothing
+  is written outside the game tree.
+- A read misses through the overlay to your shipped file, then to
+  `mod.storage`, so a half-migrated mod sees both.
+- A write over a path you shipped shadows it; the packaged file is never
+  modified, and `mod:read` still returns the packaged bytes.
+- `love.filesystem.getSaveDirectory()` and `os.getenv("HOME")` answer with
+  a virtual root, so a legacy mod that joins its own paths lands back in
+  the same overlay.
+
+`love.thread` stays refused. A LÖVE thread runs in a separate Lua state
+with the full standard library, which the sandbox in this state cannot
+reach, so a stand-in would be a hole rather than a reroute. The same goes
+for `ffi`, `debug`, `setfenv`, `os.execute`, `io.popen`, `love.run` and
+`love.errorhandler`. A mod that needs real background work needs an
+engine-owned facility, not a compat shim -- for HTTP that facility is
+[`mod.fetch`](#modfetch), which runs on the engine's own worker pool.

docs/modding/reference/registries.md

@@ -929,6 +929,10 @@ mod.content.sfx:register("SFX_MOD_CHIME", { file = "chime.ogg" })
 
 | field | type | required |
 |---|---|---|
+| `anchorX` | number | no |
+| `anchorY` | number | no |
+| `frameHeight` | integer >= 1 | no |
+| `frameWidth` | integer >= 1 | no |
 | `frames` | integer >= 1 | yes |
 | `id` | string | no |
 | `image` | file path | yes |
@@ -1100,6 +1104,7 @@ mod.content.tokens:register("CLOCK", function(game) return "12" end)
 | `paletteSource` | string | no |
 | `parties` | list of list of {level, species} | yes |
 | `pic` | file path | no |
+| `trueColor` | boolean | no |
 
 ```lua
 mod.content.trainers:patch("OPP_BROCK", { baseMoney = 99 })
@@ -1122,7 +1127,9 @@ do not.
 | `index` | integer 0..255 | no |
 | `items` | list of items id | no |
 | `name` | string | yes |
+| `pic` | file path | no |
 | `trainers` | list of {id?, index?, name, party, trainerType?} | yes |
+| `trueColor` | boolean | no |
 
 ```lua
 mod.content.trainers:patch("BEAUTY", { baseMoney = 99 })

docs/new-features.md

@@ -19,13 +19,14 @@ 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, and mods that need the internet or heavy background work do it through permissions the mod manager shows you, without freezing the game
 * **Improved launcher and save editor UI**, including background downloads and update checks
 * **Direct-launch options** for shortcuts, Steam entries, and handheld frontends
 * **Custom boot branding**
 
 ## Pokémon Gold (Gen 2)
 
-A fourth game the launcher can import and play, built from pret/pokegold the same way Red/Blue/Yellow are built from pokered. Port extras beyond the cartridge:
+A fourth game the launcher can import and play, built from pret/pokegold the same way Red/Blue/Yellow are built from pokered (and pokeyellow). Port extras beyond the cartridge:
 
 * **COLOR, zoom, tilt, GBC FX, and quick save/load** 
 * **UI that stays fixed while the overworld zooms**
@@ -39,3 +40,4 @@ A fourth game the launcher can import and play, built from pret/pokegold the sam
 * **On-screen touch pad** and controller SELECT for registered items
 
 
+* **Older mods keep loading** after the sandbox change, through per-mod compat stand-ins for the pre-sandbox globals

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

@@ -258,20 +258,34 @@ row on the detail screen. The launcher's dependency verdict asks the same
 question of your dependencies: a mod whose hard dependency does not run on the
 selected game reads `Needs <id> (not for Gold)` rather than `Ready`.
 
+### Scoping dependencies per game / generation
+
+For mods targeting multiple generations (`"games": ["gen1", "gen2"]`), a hard
+dependency can be scoped to specific games so that it is only enforced when
+booting those games:
+
+```json
+"dependencies": [
+  { "id": "pokegear_cards", "games": ["gen2"], "range": "^1.0.0", "github": "1jamie/pokegear_cards" }
+]
+```
+
+When booting a Gen 1 game (Red, Blue, Yellow), the engine loader sees that
+`pokegear_cards` is scoped to `"gen2"` and will not skip or block the parent mod
+on Gen 1. When booting Gen 2 (Gold), `pokegear_cards` is strictly required.
+
+For conditional integrations where the dependency is optional across the board,
+`optional_dependencies` remains the standard pattern.
+
 ### One limit worth knowing
 
-**Per-game enable flags are still a preview.** The overlay
-`options.modsByVersion[version][id]` exists and every surface goes through
-`SaveData.modEnabled` / `SaveData.setModEnabled`, but
-`SaveData.PER_VERSION_MODS` is `false`
-(`src/core/SaveData.lua:489`). While it is false, `SaveData.modScope` answers
-nil for every caller, so the launcher panel, the in-game manager *and* the
-loader all read and write the one shared `options.mods` flag and the overlay is
-not consulted for enablement anywhere. That matters because the overlay is
-plantable from an imported `.g1rmodlist`: keeping every reader on the same
-scope as every writer is what stops a stored per-game flag from showing a mod
-set no boot would honour. Nothing about this affects a mod author; it affects
-what a player can currently express.
+**Enablement is per game.** The overlay
+`options.modsByVersion[version][id]` is read and written through
+`SaveData.modEnabled` / `SaveData.setModEnabled` by the launcher, in-game
+manager, and loader. Existing shared settings are copied to every game the
+first time this version sees the installed mods; from then on, each coloured
+game checkbox changes only that game's next boot. Nothing about this affects a
+mod author; it affects what a player can express.
 
 Targeting is a different question from enablement and *is* enforced per game,
 as above. The two do not share a switch.
@@ -311,7 +325,7 @@ This is not a dev-mode feature; it installs on any Gold boot that has mods.
 | `src.pokemon.Boxes` | facade | over `src/core/gen2/Boxes.lua` | 22 / 0 / 0 |
 | `src.battle.BattleState` | facade | over `src/ui/gen2/BattleState.lua` | 16 / 2 / 39 |
 | `src.ui.PartyMenu` | facade | over `src/ui/gen2/PartyMenu.lua` | 15 / 2 / 16 |
-| `src.world.WorldAPI` | alias | `src/world/gen2/WorldAPI.lua` | 12 / 2 / 0 |
+| `src.world.WorldAPI` | alias | `src/world/gen2/WorldAPI.lua` | 15 / 2 / 0 |
 | `src.world.PikachuFollower` | alias | `src/world/gen2/Follower.lua` | 10 / 0 / 11 |
 | `src.script.ScriptRunner` | facade | over `src/script/gen2/Vm.lua` | 10 / 7 / 1 |
 | `src.ui.OptionsMenu` | facade | over `src/ui/gen2/OptionsMenu.lua` | 8 / 0 / 1 |
@@ -760,7 +774,7 @@ profile to test in, and `POKEPORT_DEV=1` adds the console and `F5` hot reload.
 
 - **Coverage is partial and will stay partial.** 15 Gen 1 modules are served
   out of a much larger engine, and within those 15 the coverage table records
-  288 backed members against 32 warned and 161 absent. The absent ones are not
+  291 backed members against 32 warned and 161 absent. The absent ones are not
   a backlog; most are absent because there is no honest Gen 2 answer, and each
   one carries its reason. The counts move as the adapter learns something: a
   member that turns out to answer nil is demoted from backed to warned or

docs/rfcs/0003-playthrough-storage.md

@@ -26,8 +26,8 @@ wiki's Save Model. `mod.save` and `mod.options` keep their existing behavior.
 ## The exact API delta
 
 Backward-compatible, additive-only. `Loader:_api` binds a new `mod.storage`
-facade to the calling mod id. Mods receive logical keys and decoded values, never
-filesystem handles or physical paths.
+facade to the calling mod id. Mods receive logical keys and either decoded table
+values or exact opaque byte strings, never filesystem handles or physical paths.
 
 ### Lazy opaque playthrough identity
 
@@ -75,6 +75,25 @@ Returns a freshly decoded table, or `nil, code, message`. It tries main, staged,
 then backup data. A valid staged/backup value is returned and promoted
 best-effort; corrupt bytes are never executed.
 
+### `mod.storage:writeBytes(game, key, bytes)`
+
+Accepts a Lua string containing opaque bytes and returns `true`, or
+`false, code, message`. Empty strings are valid. Payloads are limited to 512
+MiB per key. The engine writes the supplied bytes exactly as received, without
+decoding, compression, checksums, or an engine-defined envelope. The consuming
+mod owns semantic validation of its format.
+
+Byte records use private `.bin`, `.bin.tmp`, and `.bin.bak` witnesses. A staged
+and replacement write is read back and compared byte-for-byte before it is
+committed. A failed write leaves the previous verified generation readable.
+Byte storage never passes its payload to the Lua serializer, loader, or module
+resolver.
+
+Table and byte records share one logical key namespace and a key has one type.
+Writing one type over the other returns `type_conflict`; callers must delete the
+key before changing its type. `mod.storage:selected(game)` exposes the same
+`readBytes` and `writeBytes` operations for the selected playthrough facade.
+
 ### `mod.storage:list(game[, prefix])`
 
 Returns sorted logical keys beneath a valid prefix, an exact key when the prefix
@@ -92,9 +111,9 @@ Physical records are scoped as:
 `persistence root / mod_storage / game version / playthrough id / mod id`
 
 Stable error codes are `not_in_playthrough`, `storage_unavailable`,
-`invalid_key`, `encode_failed`, `write_failed`, `verify_failed`, and
-`not_found`. Ordinary data and I/O failures are return values, not callback-
-terminating errors.
+`invalid_key`, `encode_failed`, `invalid_bytes`, `size_limit`, `type_conflict`,
+`type_mismatch`, `write_failed`, `verify_failed`, and `not_found`. Ordinary
+data and I/O failures are return values, not callback-terminating errors.
 
 The restricted serializer's recursive writer runs outside LuaJIT traces. A
 1,000-process GC stress regression found compiled recursion could intermittently
@@ -107,6 +126,8 @@ boundary.
 **Nothing.** No API is removed, no manifest field changes, and no storage path or
 playthrough id is created unless a mod invokes `mod.storage` or
 `mod.checkpoints`. Existing save bytes remain unchanged on the no-caller path.
+Existing files outside the scoped storage contract are not imported; a caller
+must rebuild them through `writeBytes`.
 
 ## Parity tests
 
@@ -115,8 +136,10 @@ playthrough id is created unless a mod invokes `mod.storage` or
 - **Engine identity:** lazy allocation, save/load preservation, stable legacy
   mapping, fresh-playthrough replacement, and version/slot isolation.
 - **Public Mod API:** two real API-2 entry chunks prove data-only roundtrip,
+  opaque byte roundtrip including NUL bytes, no execution, size/type rejection,
   deterministic listing, key rejection, mod/game/playthrough isolation,
-  corrupt-main recovery, failure retention, exact delete, and no-mod no-write.
+  corrupt-main recovery, failure retention, selected-playthrough access, exact
+  delete, and no-mod no-write.
 
 ## Deprecation etiquette
 

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

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

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

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

docs/rfcs/0010-trainer-battle-party-scope.md

@@ -0,0 +1,92 @@
+# RFC 0010: Deferred trainer preparation and battle-local party scope
+
+## Status
+
+Proposed.
+
+## Motivation
+
+Challenge and tournament mods sometimes need a player to choose an eligible
+subset of the save party before a trainer battle. The current public surface
+can replace the opponent through `trainer.party` and observe
+`world.trainer_engaged`, but it cannot pause the engagement before battle
+construction or keep unselected save-party members out of initial send,
+switch, replacement, exhaustion, experience, and party-menu traversal.
+
+Temporarily rewriting `game.save.party` is not a safe substitute: it changes
+authoritative save state, composes poorly with checkpoints and other mods, and
+can strand excluded Pokémon if a callback or process fails.
+
+## Decision and plan extended
+
+This implements **D-AT-001: battle-local Gym registration without save-party
+mutation**, the consuming design decision tracked as capability `AT-SP-001` in
+the Adaptive Trainers implementation plan. The plan file is
+[`docs/superpowers/plans/2026-08-14-adaptive-trainers.md`](https://github.com/MaxTomahawk/gen1recomp-adaptive-trainers/blob/main/docs/superpowers/plans/2026-08-14-adaptive-trainers.md),
+Task 5. The engine delta also extends the additive, guarded public-hook
+decision used by RFC 0007 and the screen facade documented in
+`docs/modding.md`; it deliberately contains none of the consuming mod's Gym
+or party-size policy.
+
+## Exact API delta
+
+Add the guarded hook:
+
+```lua
+mod.hooks:wrap("trainer.before_battle", function(next, game, context, continue)
+  -- context = { trainerClass, partyIndex, mapId, npcId }
+  -- Return true only when the battle has been deferred.
+  -- continue({ cancel = true }) returns without constructing a battle.
+  -- Call continue() for the full save party, or:
+  -- continue({ playerPartyIndices = { 2, 4, 5 } })
+end)
+```
+
+The hook runs after the trainer's challenge text and immediately before the
+trainer battle is constructed. A mod may push a registered screen with
+`mod.ui.push`, return `true`, and retain `continue` for its confirm/cancel
+callback. `continue` is one-shot and returns `false` after the first call.
+Returning anything other than `true` without calling it continues immediately
+with vanilla scope. With no subscriber, no context or continuation is built.
+
+`playerPartyIndices` is an ordered, one-based list into `game.save.party`.
+Valid unique indices create `battle.playerParty` as a battle-local view of the
+same Pokémon records; the save party itself is never reordered or replaced.
+Malformed or empty scopes degrade to the full party. The view governs initial
+send, all battle party menus and targets, voluntary and forced replacement,
+exhaustion/blackout checks, participant and EXP.ALL traversal, party counts,
+and party-ball presentation. Checkpoints preserve the index list and rebuild
+the same view before restoring battlers.
+
+`{ cancel = true }` ends a deferred encounter through its normal completion
+callback without constructing a battle or writing trainer-defeated state. A
+cancelled sight encounter is suppressed while the player remains on the same
+cell, preventing immediate reacquisition; moving or directly talking permits a
+new challenge. Cancellation is also one-shot; if supplied alongside a party
+index list, cancellation wins.
+
+The API sets no maximum, chooses no members, identifies no boss, and contains
+no scaling or challenge policy.
+
+## Migration and compatibility
+
+Existing mods change nothing. `BattleState.newTrainer(game, class, index)`
+keeps its current behavior; the optional fourth argument is additive. Existing
+battle checkpoints without a party scope restore against the full save party.
+Wild, Safari, link, and no-mod battles are unchanged.
+
+## Verification
+
+- The catalog-driven hook gate proves empty-chain parity and the guarded hot
+  path proves no-mod engagement starts exactly once without allocation.
+- A sandboxed fixture mod defers through its public hook facade, inspects the
+  data-only context, and resumes once with ordered indices.
+- Engine tests cover initial send, party menus, replacement/exhaustion,
+  EXP traversal, invalid-scope fallback, and save-party identity.
+- Battle-checkpoint tests prove scoped capture/restore and old-checkpoint
+  compatibility.
+
+## Deprecation etiquette
+
+Nothing is deprecated. The hook and optional constructor argument are
+additive.

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
@@ -115,11 +126,19 @@ bundled game, in that case.
   already driving the frame. A payload that must change `love.run` itself
   needs a `minShell` bump so an older shell refuses to chainload it rather
   than running with half its intended behavior.
-- **Android has no in-app download transport yet.** `check_worker.lua`
-  shells out to curl for both the release check and the download; curl is
-  absent on Android, so `Check` degrades to `status = "error"` there (the
-  launcher UI hides on that status) and the player is directed to the
-  releases page via `Check.releaseUrl()` instead.
+- **Android and iOS use the native download bridge, not curl.** Neither
+  platform ships curl, so the old `check_worker.lua` path (shell out to curl)
+  always landed on `error` and the launcher chip's "Check for updates" tap
+  was a no-op. The worker now talks through `HostShell`, the same transport
+  as the mod catalog: curl on desktop, `love.system.httpDownload` on mobile.
+  On Android that is the GameActivity JNI/`HttpsURLConnection` bridge; on
+  iOS it is `GRPickerBridge.httpDownload` (`URLSession`). A fused sideloaded
+  APK or IPA can therefore check GitHub and fetch the `.love` payload
+  in-app. If neither transport exists, the worker reports `needs_full` and
+  the launcher chip opens `Check.releaseUrl()`. Native package-only changes
+  still need a full reinstall (`minShell` / `payloadHost` gate →
+  `needs_full`). Applying a downloaded payload on Android relaunches via
+  `love.system.restartApp`; iOS still uses in-process `quit("restart")`.
 - **Dev/source runs never self-update.** `Boot.run` returns immediately when
   `love.filesystem.isFused()` is false, and a working tree's `engine` is the
   `"0.0.0-dev"` placeholder that always reports up to date, so a source

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
@@ -75,15 +76,6 @@ end
 local editorHost, editorVersion, editorWindow
 local closeEditor  -- forward declaration: openEditor hands it to the editor
 
--- tools/save-editor/ models the Gen 1 save and nothing else: a Gen 2 party row
--- carries fields its MonOps and panels have no idea about (dvs, statExp,
--- happiness, pokerus, caughtLevel), and SaveIO.save writes the WHOLE table
--- back, so a Gold slot opened here comes out in a shape src/core/gen2/Save.lua
--- then has to quarantine on the next boot.  Refuse by name, the same way the
--- .sav paths do (src/save_convert/SaveConvert.lua GEN2_SAV_UNSUPPORTED), so
--- Red/Blue/Yellow slots are untouched.
-local GEN2_NO_EDITOR = { gold = "Pokemon Gold" }
-
 -- The editor's modules use flat names (require("Kit"), require("Party")), so
 -- their directories have to be on the require path.  It must be
 -- love.filesystem's path, not package.path: in a packaged build these files
@@ -136,11 +128,6 @@ local function openEditor(version, slotId)
     Importer.saveNotice = Importer.saveNotice or {}
     Importer.saveNotice[version] = { ok = false, text = text }
   end
-  local gen2Name = GEN2_NO_EDITOR[version]
-  if gen2Name then
-    refuse(gen2Name .. " uses a Gen 2 save; the save editor does not read one yet.")
-    return
-  end
   local SaveData = require("src.core.SaveData")
   local path = SaveData.slotDiskPath(version, slotId)
   if not path then
@@ -161,9 +148,44 @@ local function openEditor(version, slotId)
   editorMode = true
   resizeForEditor()
   addEditorRequirePath()
-  EditorApp = require("App")
-  EditorApp.load(path, { version = version, slotId = slotId, embedded = true,
-                         onClose = function() closeEditor() end })
+  local okReq, appOrErr = pcall(require, "App")
+  if not okReq then
+    editorMode = false
+    if version then
+      require("src.import.CacheFs").unmountVersion(version)
+    end
+    restoreWindow()
+    Importer = editorHost
+    editorHost = nil
+    editorVersion = nil
+    if Importer and Importer.resumeAfterOverlay then
+      Importer:resumeAfterOverlay()
+    end
+    refuse("Could not open the save editor (" .. tostring(appOrErr) .. ").")
+    return
+  end
+  EditorApp = appOrErr
+  local okLoad, loadErr = pcall(EditorApp.load, path, {
+    version = version, slotId = slotId, embedded = true,
+    onClose = function() closeEditor() end,
+  })
+  if not okLoad then
+    editorMode = false
+    if EditorApp.unload then pcall(EditorApp.unload) end
+    EditorApp = nil
+    if version then
+      require("src.import.CacheFs").unmountVersion(version)
+      require("src.core.Data"):unloadGenerated()
+    end
+    restoreWindow()
+    Importer = editorHost
+    editorHost = nil
+    editorVersion = nil
+    if Importer and Importer.resumeAfterOverlay then
+      Importer:resumeAfterOverlay()
+    end
+    refuse("Could not open the save editor (" .. tostring(loadErr) .. ").")
+  end
 end
 
 -- Back to the launcher.  Everything the editor mounted or cached has to come
@@ -179,6 +201,11 @@ function closeEditor()
     require("src.import.CacheFs").unmountVersion(version)
     require("src.core.Data"):unloadGenerated()
   end
+  for k in pairs(package.loaded) do
+    if type(k) == "string" and (k:find("save%-editor") or k == "App" or k == "Kit" or k == "State" or k == "Catalog" or k == "SaveIO" or k == "Ops" or k == "MonOps" or k == "ItemOps" or k == "PadInput" or k == "Gen" or k == "Theme") then
+      package.loaded[k] = nil
+    end
+  end
   editorVersion = nil
   restoreWindow()
   Importer = editorHost
@@ -197,14 +224,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()
@@ -271,6 +303,11 @@ function love.load(args)
   -- of each flashing their own cmd.exe window (#606).  No-op elsewhere.
   require("src.core.HostShell").hideHostConsole()
 
+  -- Hang gen1tls on love.system before mods boot.  Android already has tls*
+  -- from JNI; this is the desktop half.  No DLL / no FFI is fine -- ws://
+  -- rooms still work, wss:// just won't.
+  pcall(function() require("src.net.Gen1Tls").install() end)
+
   -- NX fused mounts are unreliable for the blue|yellow cache overlay: wrap
   -- the love loaders once so every generated-asset read falls back to the
   -- versioned save-dir copy.  Never installed on desktop/Android/iOS.
@@ -314,14 +351,6 @@ function love.load(args)
   -- cache has to be mounted before the editor's Data:load.
   if editorMode then
     local version = os.getenv("POKEPORT_VERSION") or "red"
-    local gen2Name = GEN2_NO_EDITOR[version]
-    if gen2Name then
-      -- No launcher behind this run to carry a notice, so say it and stop
-      -- rather than open a Gen 2 slot on Gen 1 panels.
-      print(gen2Name .. " uses a Gen 2 save; the save editor does not read one yet.")
-      love.event.quit(1)
-      return
-    end
     require("src.core.GameVersion").set(version)
     require("src.import.CacheFs").mountVersion(version)
     addEditorRequirePath()
@@ -425,6 +454,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 +502,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 +537,7 @@ function love.draw()
       end
     end)
   end
+  HostDisplay.endFrame("game", Game)
 end
 
 function love.keypressed(key, scancode, isrepeat)

mobile/android/love/src/jni/love/src/modules/graphics/Canvas.cpp

@@ -154,6 +154,16 @@ love::image::ImageData *Canvas::newImageData(love::image::Image *module, int sli
 	return module->newImageData(r.w, r.h, dataformat);
 }
 
+bool Canvas::requestImageData()
+{
+	return false;
+}
+
+love::image::ImageData *Canvas::pollImageData(love::image::Image *)
+{
+	return nullptr;
+}
+
 void Canvas::draw(Graphics *gfx, Quad *q, const Matrix4 &t)
 {
 	if (gfx->isCanvasActive(this))
@@ -232,4 +242,3 @@ StringMap<Canvas::SettingType, Canvas::SETTING_MAX_ENUM> Canvas::settingTypes(Ca
 
 } // graphics
 } // love
-

mobile/android/love/src/jni/love/src/modules/graphics/Canvas.h

@@ -81,6 +81,8 @@ public:
 	int getRequestedMSAA() const;
 
 	virtual love::image::ImageData *newImageData(love::image::Image *module, int slice, int mipmap, const Rect &rect);
+	virtual bool requestImageData();
+	virtual love::image::ImageData *pollImageData(love::image::Image *module);
 	virtual void generateMipmaps() = 0;
 
 	virtual int getMSAA() const = 0;

mobile/android/love/src/jni/love/src/modules/graphics/opengl/Canvas.cpp

@@ -23,6 +23,7 @@
 #include "Graphics.h"
 
 #include <algorithm> // For min/max
+#include <cstring>
 
 namespace love
 {
@@ -197,6 +198,9 @@ Canvas::Canvas(const Settings &settings)
 	, texture(0)
     , renderbuffer(0)
 	, actualSamples(0)
+	, readbackBuffer(0)
+	, readbackFence(nullptr)
+	, readbackSize(0)
 {
 	format = getSizedFormat(format);
 
@@ -314,6 +318,14 @@ bool Canvas::loadVolatile()
 
 void Canvas::unloadVolatile()
 {
+	if (readbackFence != nullptr)
+		glDeleteSync(readbackFence);
+	if (readbackBuffer != 0)
+		glDeleteBuffers(1, &readbackBuffer);
+	readbackFence = nullptr;
+	readbackBuffer = 0;
+	readbackSize = 0;
+
 	if (fbo != 0 || renderbuffer != 0 || texture != 0)
 	{
 		// This is a bit ugly, but we need some way to destroy the cached FBO
@@ -480,6 +492,68 @@ love::image::ImageData *Canvas::newImageData(love::image::Image *module, int sli
 	return data;
 }
 
+bool Canvas::requestImageData()
+{
+	if (readbackFence != nullptr || !isReadable()
+		|| !(GLAD_ES_VERSION_3_0 || GLAD_VERSION_3_2)
+		|| texType != TEXTURE_2D
+		|| (format != PIXELFORMAT_RGBA8 && format != PIXELFORMAT_sRGBA8)
+		|| actualSamples > 0)
+		return false;
+
+	auto gfx = Module::getInstance<Graphics>(Module::M_GRAPHICS);
+	if (gfx != nullptr && gfx->isCanvasActive(this))
+		throw love::Exception("Canvas:requestImageData cannot be called while that Canvas is active.");
+
+	const size_t size = (size_t) pixelWidth * (size_t) pixelHeight * 4;
+	if (readbackBuffer == 0)
+		glGenBuffers(1, &readbackBuffer);
+
+	glBindBuffer(GL_PIXEL_PACK_BUFFER, readbackBuffer);
+	if (readbackSize != size)
+	{
+		glBufferData(GL_PIXEL_PACK_BUFFER, size, nullptr, GL_STREAM_READ);
+		readbackSize = size;
+	}
+
+	GLuint currentfbo = gl.getFramebuffer(OpenGL::FRAMEBUFFER_ALL);
+	gl.bindFramebuffer(OpenGL::FRAMEBUFFER_ALL, getFBO());
+	glReadPixels(0, 0, pixelWidth, pixelHeight, GL_RGBA, GL_UNSIGNED_BYTE, nullptr);
+	readbackFence = glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0);
+	gl.bindFramebuffer(OpenGL::FRAMEBUFFER_ALL, currentfbo);
+	glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+	return readbackFence != nullptr;
+}
+
+love::image::ImageData *Canvas::pollImageData(love::image::Image *module)
+{
+	if (readbackFence == nullptr)
+		return nullptr;
+
+	GLenum status = glClientWaitSync(readbackFence, 0, 0);
+	if (status == GL_TIMEOUT_EXPIRED)
+		return nullptr;
+
+	glDeleteSync(readbackFence);
+	readbackFence = nullptr;
+	if (status == GL_WAIT_FAILED)
+		return nullptr;
+
+	love::image::ImageData *data = module->newImageData(pixelWidth, pixelHeight, PIXELFORMAT_RGBA8);
+	glBindBuffer(GL_PIXEL_PACK_BUFFER, readbackBuffer);
+	void *pixels = glMapBufferRange(GL_PIXEL_PACK_BUFFER, 0, readbackSize, GL_MAP_READ_BIT);
+	if (pixels == nullptr)
+	{
+		glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+		data->release();
+		throw love::Exception("Could not map asynchronous Canvas readback.");
+	}
+	memcpy(data->getData(), pixels, readbackSize);
+	glUnmapBuffer(GL_PIXEL_PACK_BUFFER);
+	glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+	return data;
+}
+
 void Canvas::generateMipmaps()
 {
 	if (getMipmapCount() == 1 || getMipmapMode() == MIPMAPS_NONE)

mobile/android/love/src/jni/love/src/modules/graphics/opengl/Canvas.h

@@ -54,6 +54,8 @@ public:
 	ptrdiff_t getHandle() const override;
 
 	love::image::ImageData *newImageData(love::image::Image *module, int slice, int mipmap, const Rect &rect) override;
+	bool requestImageData() override;
+	love::image::ImageData *pollImageData(love::image::Image *module) override;
 	void generateMipmaps() override;
 
 	int getMSAA() const override
@@ -107,6 +109,9 @@ private:
 	GLenum status;
 
 	int actualSamples;
+	GLuint readbackBuffer;
+	GLsync readbackFence;
+	size_t readbackSize;
 
 	static SupportedFormat supportedFormats[PIXELFORMAT_MAX_ENUM];
 	static SupportedFormat checkedFormats[PIXELFORMAT_MAX_ENUM];

mobile/android/love/src/jni/love/src/modules/graphics/wrap_Canvas.cpp

@@ -116,6 +116,31 @@ int w_Canvas_newImageData(lua_State *L)
 	return 1;
 }
 
+int w_Canvas_requestImageData(lua_State *L)
+{
+	Canvas *canvas = luax_checkcanvas(L, 1);
+	bool requested = false;
+	luax_catchexcept(L, [&](){ requested = canvas->requestImageData(); });
+	luax_pushboolean(L, requested);
+	return 1;
+}
+
+int w_Canvas_pollImageData(lua_State *L)
+{
+	Canvas *canvas = luax_checkcanvas(L, 1);
+	love::image::Image *image = luax_getmodule<love::image::Image>(L, love::image::Image::type);
+	love::image::ImageData *data = nullptr;
+	luax_catchexcept(L, [&](){ data = canvas->pollImageData(image); });
+	if (data == nullptr)
+	{
+		lua_pushnil(L);
+		return 1;
+	}
+	luax_pushtype(L, data);
+	data->release();
+	return 1;
+}
+
 int w_Canvas_generateMipmaps(lua_State *L)
 {
 	Canvas *c = luax_checkcanvas(L, 1);
@@ -139,6 +164,8 @@ static const luaL_Reg w_Canvas_functions[] =
 	{ "getMSAA", w_Canvas_getMSAA },
 	{ "renderTo", w_Canvas_renderTo },
 	{ "newImageData", w_Canvas_newImageData },
+	{ "requestImageData", w_Canvas_requestImageData },
+	{ "pollImageData", w_Canvas_pollImageData },
 	{ "generateMipmaps", w_Canvas_generateMipmaps },
 	{ "getMipmapMode", w_Canvas_getMipmapMode },
 	{ 0, 0 }

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

@@ -192,8 +192,14 @@ bool System::pickFile(const char *kind) const
 			dest = "picked_mod.zip";
 		else if (strcmp(kind, "sav") == 0 || strcmp(kind, "save") == 0)
 			dest = "picked_save.sav";
+		else if (strcmp(kind, "required_import") == 0)
+			dest = "picked_required_import.bin";
 		else if (strcmp(kind, "rom") == 0)
 			dest = "picked_rom.gb";
+		// Unknown kinds used to fall through to the ROM destination. Refuse them
+		// so a newer Lua caller cannot silently route an unrelated file as a ROM.
+		else
+			return false;
 	}
 	return love::android::showFilePicker(dest);
 #else
@@ -202,6 +208,15 @@ bool System::pickFile(const char *kind) const
 #endif
 }
 
+const char *System::pickFileKinds() const
+{
+#ifdef LOVE_ANDROID
+	return "rom,mod,sav,required_import";
+#else
+	return "";
+#endif
+}
+
 bool System::createFile(const char *suggestedName) const
 {
 #ifdef LOVE_ANDROID

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

@@ -112,10 +112,12 @@ public:
 	 * love::android::showFilePicker and src/import/RomImporter.lua.
 	 *
 	 * @param kind Optional pick kind: nullptr/"rom" -> picked_rom.gb,
-	 *             "mod" -> picked_mod.zip, "sav"/"save" -> picked_save.sav.
+	 *             "mod" -> picked_mod.zip, "sav"/"save" -> picked_save.sav,
+	 *             "required_import" -> picked_required_import.bin.
 	 * @return Whether the picker was shown.
 	 **/
 	virtual bool pickFile(const char *kind = nullptr) const;
+	virtual const char *pickFileKinds() const;
 
 	/**
 	 * Shows the platform's native "create / save a file" UI (Android SAF

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

@@ -102,6 +102,12 @@ int w_pickFile(lua_State *L)
 	return 1;
 }
 
+int w_pickFileKinds(lua_State *L)
+{
+	luax_pushstring(L, instance()->pickFileKinds());
+	return 1;
+}
+
 int w_createFile(lua_State *L)
 {
 	const char *suggested = luaL_optstring(L, 1, nullptr);
@@ -222,6 +228,7 @@ static const luaL_Reg functions[] =
 	{ "openURL", w_openURL },
 	{ "vibrate", w_vibrate },
 	{ "pickFile", w_pickFile },
+	{ "pickFileKinds", w_pickFileKinds },
 	{ "createFile", w_createFile },
 	{ "syncHealthSteps", w_syncHealthSteps },
 	{ "restartApp", w_restartApp },

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

@@ -90,6 +90,9 @@ public class GameActivity extends SDLActivity {
     private static final String PICKED_ROM_FILENAME = "picked_rom.gb";
     private static final String PICKED_MOD_FILENAME = "picked_mod.zip";
     private static final String PICKED_SAVE_FILENAME = "picked_save.sav";
+    // Kept separate from the game-ROM destination so a dependency pick can
+    // never be mistaken for a game import when the picker returns on Android.
+    private static final String PICKED_REQUIRED_IMPORT_FILENAME = "picked_required_import.bin";
     private static final String PENDING_EXPORT_FILENAME = "pending_export.sav";
     private static final String EXPORT_DONE_FILENAME = "export_done.flag";
     // Written when a SAF pick cannot be read at all, with the destination
@@ -143,16 +146,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 +215,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 +366,8 @@ public class GameActivity extends SDLActivity {
             Log.d("GameActivity", "Cancelling vibration");
             vibrator.cancel();
         }
+        unregisterSecondaryDisplayListener();
+        onHostDestroy();
         super.onDestroy();
     }
 
@@ -350,13 +377,17 @@ public class GameActivity extends SDLActivity {
             Log.d("GameActivity", "Cancelling vibration");
             vibrator.cancel();
         }
+        unregisterSecondaryDisplayListener();
         teardownSecondaryDisplay();
+        onHostPause();
         super.onPause();
     }
 
     @Override
     public void onResume() {
         super.onResume();
+        onHostResume();
+        if (secondaryEnabled) registerSecondaryDisplayListener();
         setupSecondaryDisplay();
     }
 
@@ -479,7 +510,8 @@ public class GameActivity extends SDLActivity {
      * picker-agnostic and unchanged.
      *
      * @param destFilename basename under the app save identity (e.g.
-     *                     picked_rom.gb, picked_mod.zip, picked_save.sav)
+     *                     picked_rom.gb, picked_mod.zip, picked_save.sav, or
+     *                     picked_required_import.bin)
      */
     /** Legacy single-argument entry; resolves the save dir itself. */
     @Keep
@@ -510,6 +542,11 @@ public class GameActivity extends SDLActivity {
             Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
             intent.addCategory(Intent.CATEGORY_OPENABLE);
             intent.setType("*/*");
+            // The Storage Access Framework grants the returned content URI
+            // directly to this activity. Request the read grant explicitly as
+            // well: Android 13's scoped storage deliberately does not expose
+            // arbitrary paths or require broad media/storage permissions.
+            intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
             try {
                 self.startActivityForResult(intent, FILE_PICKER_REQUEST_CODE);
                 return true;
@@ -522,6 +559,7 @@ public class GameActivity extends SDLActivity {
         Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
         intent.addCategory(Intent.CATEGORY_OPENABLE);
         intent.setType("*/*");
+        intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
         try {
             self.startActivityForResult(
                 Intent.createChooser(intent, "Choose a file"),
@@ -551,6 +589,12 @@ public class GameActivity extends SDLActivity {
         return showFilePicker(PICKED_SAVE_FILENAME);
     }
 
+    /** Required-mod-file wrapper used by love.system.pickFile("required_import"). */
+    @Keep
+    public static boolean showRequiredImportFilePicker() {
+        return showFilePicker(PICKED_REQUIRED_IMPORT_FILENAME);
+    }
+
     /**
      * Relaunches the whole app for love.system.restartApp, used by
      * src/core/HostShell.lua when a mod toggle needs a cold boot (#575).
@@ -1364,6 +1408,7 @@ public class GameActivity extends SDLActivity {
     // in src/jni/love/src/common/android.cpp.
     private static volatile SecondaryPresentation secondaryPresentation;
     private static volatile boolean secondaryEnabled = false;
+    private SecondaryDisplayMonitor secondaryDisplayMonitor;
     private static final int MAX_SECONDARY_TOUCHES = 32;
     private static final java.util.ArrayDeque<String> secondaryTouches =
         new java.util.ArrayDeque<>();
@@ -1375,11 +1420,44 @@ public class GameActivity extends SDLActivity {
         if (self == null) return;
         self.runOnUiThread(new Runnable() {
             @Override public void run() {
-                if (on) setupSecondaryDisplay(); else teardownSecondaryDisplay();
+                if (on) {
+                    self.registerSecondaryDisplayListener();
+                    setupSecondaryDisplay();
+                } else {
+                    self.unregisterSecondaryDisplayListener();
+                    teardownSecondaryDisplay();
+                }
             }
         });
     }
 
+    private void registerSecondaryDisplayListener() {
+        if (secondaryDisplayMonitor != null || android.os.Build.VERSION.SDK_INT < 17) return;
+        SecondaryDisplayMonitor monitor = new SecondaryDisplayMonitor(this);
+        if (monitor.register()) secondaryDisplayMonitor = monitor;
+    }
+
+    private void unregisterSecondaryDisplayListener() {
+        SecondaryDisplayMonitor monitor = secondaryDisplayMonitor;
+        secondaryDisplayMonitor = null;
+        if (monitor != null) monitor.unregister();
+    }
+
+    private static void refreshSecondaryDisplay() {
+        GameActivity self = (GameActivity) mSingleton;
+        if (self == null || !secondaryEnabled) return;
+        SecondaryPresentation current = secondaryPresentation;
+        Display display = current == null ? null : current.getDisplay();
+        SecondaryDisplayMonitor monitor = self.secondaryDisplayMonitor;
+        if (current == null) {
+            setupSecondaryDisplay();
+        } else if (display == null || monitor == null
+            || !monitor.hasDisplay(display.getDisplayId())) {
+            teardownSecondaryDisplay();
+            setupSecondaryDisplay();
+        }
+    }
+
     private static void setupSecondaryDisplay() {
         GameActivity self = (GameActivity) mSingleton;
         if (self == null || !secondaryEnabled || secondaryPresentation != null) return;
@@ -1425,6 +1503,35 @@ public class GameActivity extends SDLActivity {
         }
     }
 
+    @android.annotation.TargetApi(17)
+    private static class SecondaryDisplayMonitor
+        implements android.hardware.display.DisplayManager.DisplayListener {
+        private final android.hardware.display.DisplayManager manager;
+
+        SecondaryDisplayMonitor(GameActivity activity) {
+            manager = (android.hardware.display.DisplayManager)
+                activity.getSystemService(Context.DISPLAY_SERVICE);
+        }
+
+        boolean register() {
+            if (manager == null) return false;
+            manager.registerDisplayListener(this, new Handler(Looper.getMainLooper()));
+            return true;
+        }
+
+        void unregister() {
+            manager.unregisterDisplayListener(this);
+        }
+
+        boolean hasDisplay(int displayId) {
+            return manager.getDisplay(displayId) != null;
+        }
+
+        @Override public void onDisplayAdded(int displayId) { refreshSecondaryDisplay(); }
+        @Override public void onDisplayRemoved(int displayId) { refreshSecondaryDisplay(); }
+        @Override public void onDisplayChanged(int displayId) { refreshSecondaryDisplay(); }
+    }
+
     @Keep
     public static boolean hasSecondaryDisplay() {
         return secondaryPresentation != null;

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,129 @@
 {
-  "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.95",
+          "date": "2026-08-16",
+          "size": 11373796,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.95/gen1recomp++-0.1.95-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi\n- @ShaneMcGovernIE"
+        },
+        {
+          "version": "0.1.94",
+          "date": "2026-08-15",
+          "size": 11369457,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.94/gen1recomp++-0.1.94-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #694 Missing sound effect when falling from boulder holes\n\n## Contributors\n\n- @anxiousintrovert\n- @bryanthaboi\n- @ShaneMcGovernIE"
+        },
+        {
+          "version": "0.1.93",
+          "date": "2026-08-15",
+          "size": 11366991,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.93/gen1recomp++-0.1.93-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1314 Launcher is a bit buggy\n\n## Contributors\n\n- @1Jamie\n- @anxiousintrovert\n- @bryanthaboi\n- @TheRealSolidusSnake"
+        },
+        {
+          "version": "0.1.92",
+          "date": "2026-08-15",
+          "size": 11364274,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.92/gen1recomp++-0.1.92-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.91",
+          "date": "2026-08-15",
+          "size": 11351477,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.91/gen1recomp++-0.1.91-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.90",
+          "date": "2026-08-15",
+          "size": 11344338,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.90/gen1recomp++-0.1.90-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @1Jamie\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.89",
+          "date": "2026-08-15",
+          "size": 11343841,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.89/gen1recomp++-0.1.89-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @1Jamie\n- @anxiousintrovert\n- @AverageConsumer\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.88",
+          "date": "2026-08-14",
+          "size": 11311237,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.88/gen1recomp++-0.1.88-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.87",
+          "date": "2026-08-14",
+          "size": 11310910,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.87/gen1recomp++-0.1.87-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi\n- @mleo2003\n- @ShaneMcGovernIE\n- MaxTomahawk"
+        },
+        {
+          "version": "0.1.86",
+          "date": "2026-08-14",
+          "size": 11306689,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.86/gen1recomp++-0.1.86-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1283 Intro broken and leading to softlock (R,B,Y currently unplayable without save file)\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.85",
+          "date": "2026-08-14",
+          "size": 11306462,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.85/gen1recomp++-0.1.85-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.84",
+          "date": "2026-08-14",
+          "size": 11306462,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.84/gen1recomp++-0.1.84-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #919 Bills House game save moves strangely after reload\n- #982 Trading QOL aspect missing from OG.\n- #1003 Land Pokemon Encounters while Surfing in Cerulean Cave\n- #1012 Multiple issues with text speed, animations, and audio\n- #1022 Cannot interact with small trees\n- #1028 Trainers not resetting on route change.\n- #1033 Some issues with Link battles.\n- #1243 Can't sell TMs at Poké Marts\n\n## Contributors\n\n- @1Jamie\n- @AverageConsumer\n- @bryanthaboi\n- @TheRealSolidusSnake\n- Myles Resnick\n- ShaneMcGovernIE"
+        },
+        {
+          "version": "0.1.83",
+          "date": "2026-08-13",
+          "size": 11282300,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.83/gen1recomp++-0.1.83-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.82",
+          "date": "2026-08-13",
+          "size": 11281277,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.82/gen1recomp++-0.1.82-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #914 Immunity steps and no encounter tiles\n- #936 Fly and teleporting allow should block interactions\n- #944 When starting a new game, the character sprite is facing down instead of up\n- #949 Save game import, save game export, \"normal\" save game\n- #964 Menu closing when trying to view Pokemon before picking starter\n- #978 Following up of #847\n- #983 Pikachu incorrectly able to be released\n- #984 EXP calculation after trading a PKMN back isnt right.\n- #987 Celadon Game Corner Display Error (L22680)\n- #988 (Yellow) Missing Pikachu Interaction - Pewter City Pokemon Centre\n- #989 (Yellow) Missing Pikachu Interaction - Vermilion City Pokemon Fan Club\n- #990 (Yellow) Pikachu Missing Hat\n- #999 Pallet Town music while player follows Prof. Oak\n- #1007 Transition into battle state for the 'Catching Pikachu' scene missing\n- #1010 Rival's position resets\n- #1011 Rival dialogue issue\n- #1029 1px black line sits under the title logo at the SGB zone boundary\n- #1035 Alt Music not playing\n- #1041 Mimic text not swoing up\n- #1047 Using a TM or HM closes the menu afterwards.\n- #1048 Cannot select items from the sell menu.\n- #1056 Cursor not jumping when switching moves\n- #1065 Player walks through statue after final battle while walking into Hall Of Fame\n- #1066 Anomalies when opponent switches out Pokemon\n- #1069 missing {RAM:wNameBuffer}\n- #1073 _GotMonText not used\n- #1089 Scripted movement missing for player and rival\n- #1101 Recoil damage calculation bug\n- #1115 Hitting attack does no damage\n- #1119 Wrongs textlines and events\n- #1120 Health is black when viewing stats\n- #1129 Errors in bowing animations of the nurse\n- #1146 [Recomp] Map music glitch\n- #1149 issue that affects tranlations\n- #1175 Pikachu visible too late\n- #1189 Town Map Item\n- #1193 Status moves have (wrong) sound effects when battle animations are turned off\n- #1206 Gen1: Cinnebar island has unfishable tiles north and east\n- #1207 Poison Flicker Visual issue\n- #1214 Title Screen with OG Red is the wrong color\n- #1219 [GOLD] UNABLE TO USE SUN STONE\n- #1220 No screen shaking for hitting moves when battle animations are off\n- #1221 [Gold] Flaafy evolution to at Lvl 30 Ampharos skipped learn thunder punch\n- #1225 Jingles for learning moves missing\n\n## Contributors\n\n- @1Jamie\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.81",
+          "date": "2026-08-13",
+          "size": 9886854,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.81/gen1recomp++-0.1.81-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1091 Encounter Rate is tied to Game Speed\n- #1097 Phase through walls exiting a cave\n- #1100 Allow for control edit and vibration toggle on gold\n- #1104 wrong warp\n- #1135 update for iphone - haptic vibrations\n- #1155 Magnitude always rolls a 4\n- #1157 Sonic Boom doesn't deal set damage\n- #1158 Unable to view opponent's next Pokemon\n- #1159 Dig animation is bugged\n- #1160 64x64 battle sprite followup for mods\n- #1167 [Gold] items in ilex forest missing\n- #1208 Gold Save game not showing properly in LAUNCHER after having multiple saves\n\n## Contributors\n\n- @bryanthaboi\n- @castdrian\n- @MaxTomahawk\n- @Yukitty\n- Codex Agent"
+        },
+        {
+          "version": "0.1.80",
+          "date": "2026-08-12",
+          "size": 10964568,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.80/gen1recomp-0.1.80-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1100 Allow for control edit and vibration toggle on gold\n- #1107 [Gold] When playing without a save slot in the launcher, no save will be created at all when saving ingame\n- #1112 [Gold] In the shop when buying items and pressing \"down\", it should not default to x99\n- #1121 [Gold] NPC trading (probably player too?) animation broken / missing things\n- #1126 [Gold] Jumping off ledge animation missing\n- #1130 A separate program for Gen2 (Gen2 Recomp)\n- #1145 Gen1recomp internal update - Mod didn't filter for Gen1 and Gen2 when click on individual tab\n- #1150 Control in Gold freeze when change\n- #1151 [Gold] Following up of #1127\n- #1152 [Gold] You cannot try to run away from wild battle after one of your Pokemon gets fainted.\n- #1161 window/borderless & resolution selection for gen2\n- #1162 [gold] learning TM/HM doesn't show if possible or not\n- #1164 Goldenrod Tower Softlock\n- #1165 [Gold] NPC trading behavior and ledge jumping missing still there despite fix\n- #1166 [Gold] nickname screen grey\n- #1167 [Gold] items in ilex forest missing\n- #1168 [Gold] multi-hit attacks only hits twice\n- #1169 [Gold] the sales lady in goldenrod underground\n- #1172 [Gold] {last item u found/got} used ROCK SMASH\n- #1173 [Gold] ROCK SMASH rocks keep slide left\n- #1177 [Gold] Touch controls position\n- #1178 No Vibration Setting for Gold\n- #1180 [Gold] something feels off with the DV calculation\n- #1184 [Gold] Kurt is in the wrong spot, blocking you from progressing\n- #1185 [Gold] Text messages is in the wrong order when a Pokemon learns a new skill after a trainer fight\n- #1188 GoldenRod tower softlock\n- #1190 POKEMON GOLD GEN1RECOMP++\n- #1192 cant import gold on RGXX build\n\n## Contributors\n\n- @anxiousintrovert\n- @AverageConsumer\n- @bryanthaboi\n- @MaxTomahawk\n- @ShaneMcGovernIE\n- @thibautbus"
+        },
         {
           "version": "0.1.79",
           "date": "2026-08-12",

mobile/ios/native/GRPickerBridge.swift

@@ -5,7 +5,7 @@
 // without updating that patch (see mobile/ios/patch_love_src.py).
 //
 // Contract (mirrors love-android's GameActivity.showFilePicker):
-//   love.system.pickFile("rom"|"mod"|"sav") -> copies the user's pick into
+//   love.system.pickFile("rom"|"mod"|"sav"|"required_import") -> copies the user's pick into
 //   the LÖVE save directory as picked_rom.gb / picked_mod.zip /
 //   picked_save.sav; RomImporter's pending-file scan consumes it.
 //   love.system.createFile(name) -> exports save dir's pending_export.sav
@@ -83,6 +83,8 @@ public final class GRPickerBridge: NSObject {
             types = [.zip]
         case "sav":
             destName = "picked_save.sav"
+        case "required_import":
+            destName = "picked_required_import.bin"
         // A Nintendo 64 cartridge, for mods that build assets out of one --
         // the voxel mod's Pokemon Stadium battle models are the caller this
         // was added for. Its own filename on purpose: an N64 ROM landing on
@@ -135,7 +137,7 @@ public final class GRPickerBridge: NSObject {
     // Kept beside the switch it describes, because the two drifting apart is
     // the only way this can lie.
     @objc public static func supportedPickerKinds() -> NSString {
-        return "rom,mod,sav,stadium" as NSString
+        return "rom,mod,sav,stadium,required_import" as NSString
     }
 
     @objc(presentExportWithName:saveDir:)

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")
@@ -86,7 +89,8 @@ int w_pickFile(lua_State *L)
 	return gr_callBridge(L, "GRPickerBridge", "presentPickerWithKind:saveDir:", kind);
 }
 
-// love.system.pickFileKinds() -> "rom,mod,sav,stadium", or nil off iOS.
+// love.system.pickFileKinds() -> the comma-separated kinds supported by the
+// Swift bridge (including required_import), or nil off iOS.
 //
 // So a caller can ask what this build's picker understands BEFORE opening it.
 // An unknown kind is refused (GRPickerBridge), and a refusal looks exactly
@@ -120,7 +124,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 +362,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 +456,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 +472,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()
 

native/tls_dial/README.md

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

scripts/build.sh

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

scripts/build_ios.sh

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

scripts/linux-arm64/build_appimage.sh

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

scripts/pack_love.sh

@@ -51,6 +51,12 @@ rm -f "$OUTPUT"
   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 [ -f "$ROOT/PATCH_NOTES.md" ]; then
+  (cd "$ROOT" && zip -q "$OUTPUT" PATCH_NOTES.md)
+fi
+if [ -f "$ROOT/mobile/ios/app-repo.json" ]; then
+  (cd "$ROOT" && zip -q "$OUTPUT" mobile/ios/app-repo.json)
+fi
 
 if [ -n "$BUILD_INFO" ]; then
   [ -f "$BUILD_INFO" ] || fail "missing build-info: $BUILD_INFO"

scripts/run.sh

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

scripts/test.sh

@@ -135,6 +135,7 @@ if [ -f data/generated/maps.lua ]; then
     run_tier "T3 save editor: events + dex" "$LUA" tests/save_editor_task7_tests.lua
     run_tier "T3 save editor: map browser" "$LUA" tests/save_editor_task8_tests.lua
     run_tier "T3 save editor: mod awareness" "$LUA" tests/save_editor_mod_tests.lua
+    run_tier "T3 save editor: gold / gen2" "$LUA" tests/save_editor_gen2_tests.lua
     run_tier "T3 save editor: wheel scrolling" "$LUA" tests/save_editor_wheel_bug595_test.lua
     run_tier "T3 save editor: pad / NX input" "$LUA" tests/save_editor_pad_input_test.lua
     run_tier "T5 link (loopback lockstep)" "$LUA" tests/run_link_tests.lua

src/battle/BattleAPI.lua

@@ -0,0 +1,257 @@
+-- Read-only Gen 1 battle state for companion UIs and accessibility mods.
+
+local Damage = require("src.battle.Damage")
+local ItemEffects = require("src.inventory.ItemEffects")
+local TypeChart = require("src.battle.TypeChart")
+
+local BattleAPI = {}
+BattleAPI.__index = BattleAPI
+
+function BattleAPI.new(game)
+  return setmetatable({ game = game, revision = 0, signature = nil }, BattleAPI)
+end
+
+local function activeBattle(game)
+  local states = game and game.stack and game.stack.states or {}
+  for i = #states, 1, -1 do
+    if states[i].isBattleState then return states[i], states[#states] end
+  end
+end
+
+local function monCopy(data, mon, active)
+  if not mon then return nil end
+  local def = data.pokemon[mon.species]
+  return {
+    species = mon.species,
+    name = mon.nickname or (def and def.name) or mon.species,
+    level = mon.level, hp = mon.hp,
+    maxHp = mon.stats and mon.stats.hp or mon.hp,
+    status = mon.status, active = active and true or false,
+  }
+end
+
+local function visibleMessage(battle, top)
+  local source = top and top.isTextBox and top or top == battle and battle
+  local lines = source and source.visibleText and source:visibleText()
+  if not lines then return nil end
+  local copy = {}
+  for i, line in ipairs(lines) do copy[i] = tostring(line) end
+  return copy
+end
+
+local function signature(game, battle, top)
+  if not battle then return "none" end
+  local parts = { tostring(battle), tostring(top), battle.phase or "",
+    tostring(battle.turnCount or 0), tostring(#(battle.queue or {})),
+    tostring(battle.current), tostring(battle.msgWaiting),
+    tostring(battle.msgPrompt), tostring(battle.menuIndex),
+    tostring(battle.mimicIndex),
+    tostring(battle.safari and battle.safari.balls),
+    tostring(battle.ghost), tostring(battle.noCatch),
+    table.concat(visibleMessage(battle, top) or {}, "\n") }
+  for _, battler in ipairs({ battle.player, battle.enemy }) do
+    local mon = battler and battler.mon
+    parts[#parts + 1] = tostring(mon)
+    parts[#parts + 1] = tostring(mon and mon.hp)
+    parts[#parts + 1] = tostring(mon and mon.status)
+    parts[#parts + 1] = table.concat(battler and battler.curTypes or {}, ",")
+  end
+  for _, mon in ipairs(game.save.party or {}) do
+    parts[#parts + 1] = tostring(mon)
+    parts[#parts + 1] = tostring(mon.hp)
+    parts[#parts + 1] = tostring(mon.status)
+  end
+  local inventory = {}
+  for id, count in pairs(game.save.inventory or {}) do
+    if ItemEffects.isBall(id) or ItemEffects.isBattleMedicine(id) then
+      inventory[#inventory + 1] = id .. "=" .. tostring(count)
+    end
+  end
+  table.sort(inventory)
+  for _, item in ipairs(inventory) do parts[#parts + 1] = item end
+  return table.concat(parts, "|")
+end
+
+function BattleAPI:_revision(battle, top)
+  local nextSignature = signature(self.game, battle, top)
+  if nextSignature ~= self.signature then
+    self.signature = nextSignature
+    self.revision = self.revision + 1
+  end
+  return self.revision
+end
+
+local IMMUNITY_ONLY = { SPECIAL_DAMAGE_EFFECT = true,
+  SUPER_FANG_EFFECT = true, OHKO_EFFECT = true }
+
+local function movePreview(battle, move, def)
+  local record = battle.effectRecord and battle:effectRecord(def.effect)
+  local power, typeMult = def.power or 0
+  if power > 0 and move.id ~= "COUNTER" then
+    local raw = TypeChart.effectiveness(def.type, battle.enemy.curTypes or {})
+    if IMMUNITY_ONLY[def.effect] then
+      typeMult = raw == 0 and 0 or 10
+    elseif not (record and record.chooseDamage) then
+      typeMult = raw
+    end
+  end
+  local hitChance
+  if record and record.neverMiss then
+    hitChance = 100
+  elseif not (record and record.gate)
+      and (power > 0 or (record and record.accuracyChecked)) then
+    hitChance = battle.enemy.invulnerable and 0
+      or Damage.accuracyChance(battle.ruleset, def,
+        battle.player, battle.enemy)
+  end
+  local displayPower = power > 0 and move.id ~= "COUNTER"
+    and not IMMUNITY_ONLY[def.effect]
+    and not (record and record.chooseDamage) and power or nil
+  return typeMult, hitChance, displayPower
+end
+
+local function moveCopies(game, battle)
+  local out = {}
+  for slot, move in ipairs((battle.player and battle.player.curMoves) or {}) do
+    local def = game.data.moves[move.id] or {}
+    local mult, hitChance, displayPower = movePreview(battle, move, def)
+    out[slot] = { slot = slot, id = move.id, name = def.name or move.id,
+      pp = move.pp,
+      maxPp = (def.pp or move.pp or 0)
+        + (move.ppUps or 0) * math.floor((def.pp or 0) / 5),
+      type = def.type, power = def.power, accuracy = def.accuracy,
+      displayPower = displayPower, hitChance = hitChance,
+      effectiveness = mult,
+      disabled = battle.player.disabledSlot == slot }
+  end
+  return out
+end
+
+local function itemCopies(game, battle, catchable)
+  local out = {}
+  for id, count in pairs(game.save.inventory or {}) do
+    if count > 0
+        and (ItemEffects.isBall(id) or ItemEffects.isBattleMedicine(id)) then
+      local def = game.data.items[id] or {}
+      local ball = ItemEffects.isBall(id)
+      out[#out + 1] = { id = id, name = def.name or id, count = count,
+        ball = ball, needsTarget = not ball,
+        catchChance = ball and catchable and battle.catchChance
+          and battle:catchChance(id) or nil }
+    end
+  end
+  table.sort(out, function(a, b) return a.name < b.name end)
+  return out
+end
+
+local function mimicCopies(game, battle)
+  local out = {}
+  for i, move in ipairs(battle.mimicMoves or {}) do
+    local def = game.data.moves[move.id] or {}
+    out[i] = { index = i, slot = move.slot, id = move.id,
+      name = def.name or move.id }
+  end
+  return out
+end
+
+function BattleAPI:snapshot()
+  local game = self.game
+  local battle, top = activeBattle(game)
+  if not battle then return nil end
+  local kind = battle:battleKind()
+  local supported = kind ~= "oldman" and kind ~= "link"
+  local catchable = kind == "wild" and not battle.ghost and not battle.noCatch
+  local forcedParty = top and top.isPartyMenu and top.battle == battle
+    and top.forceSwitch
+  local canAdvance = supported and ((top == battle
+      and battle.phase == "messages" and battle.current
+      and (battle.msgWaiting or battle.msgPrompt))
+    or (top and top.isTextBox and not top.choice
+      and (top.waiting or top.done)))
+  local prompt = "locked"
+  if canAdvance then prompt = "advance"
+  elseif supported and forcedParty then prompt = "party"
+  elseif supported and top == battle and kind == "safari"
+      and battle.phase == "menu" then prompt = "safari"
+  elseif supported and top == battle and battle.phase == "mimicSelect" then
+    prompt = "mimic"
+  elseif supported and top == battle and battle.phase == "menu" then
+    prompt = "menu"
+  elseif supported and top == battle and battle.phase == "moveSelect" then
+    prompt = "moves"
+  end
+  local party = {}
+  for i, mon in ipairs(game.save.party or {}) do
+    party[i] = monCopy(game.data, mon,
+      battle.player and battle.player.mon == mon)
+    party[i].slot = i
+  end
+  return { revision = self:_revision(battle, top), kind = kind,
+    catchable = catchable, prompt = prompt,
+    message = visibleMessage(battle, top), turn = battle.turnCount or 0,
+    player = monCopy(game.data, battle.player and battle.player.mon, true),
+    enemy = monCopy(game.data, battle.enemy and battle.enemy.mon, true),
+    party = party, moves = moveCopies(game, battle),
+    items = itemCopies(game, battle, catchable),
+    safariBalls = battle.safari and battle.safari.balls or nil,
+    mimicMoves = mimicCopies(game, battle), mimicIndex = battle.mimicIndex }
+end
+
+local MENU_CHOICES = { fight = true, party = true, item = true, run = true }
+
+local function validSlot(slot)
+  return type(slot) == "number" and slot % 1 == 0 and slot >= 1
+end
+
+function BattleAPI:submit(intent)
+  if type(intent) ~= "table" then return nil, "intent must be a table" end
+  if type(intent.id) ~= "number" or intent.id % 1 ~= 0 or intent.id < 1 then
+    return nil, "intent id must be a positive integer"
+  end
+  if self.lastIntentId and intent.id <= self.lastIntentId then
+    return nil, "replayed intent"
+  end
+
+  local battle, top = activeBattle(self.game)
+  if not battle then return nil, "no battle" end
+  if intent.revision ~= self:_revision(battle, top) then
+    return nil, "stale battle context"
+  end
+  local kind = battle:battleKind()
+  if kind == "oldman" or kind == "link" or kind == "safari" then
+    return nil, "battle kind is not controllable"
+  end
+  if top ~= battle then return nil, "battle menu is covered" end
+
+  local ok, err
+  if intent.kind == "menu" then
+    if battle.phase ~= "menu" then return nil, "battle menu is not active" end
+    if not MENU_CHOICES[intent.choice] then
+      return nil, "unknown battle menu choice"
+    end
+    ok, err = battle:chooseMenu(intent.choice)
+  elseif intent.kind == "move" then
+    if battle.phase ~= "moveSelect" then
+      return nil, "move menu is not active"
+    end
+    if battle.moveSwapIndex then return nil, "move reorder is active" end
+    local move = validSlot(intent.slot) and battle.player
+      and battle.player.curMoves[intent.slot]
+    if not move then return nil, "invalid move slot" end
+    if (move.pp or 0) <= 0 then return nil, "move has no PP" end
+    if battle.player.disabledSlot == intent.slot then
+      return nil, "move is disabled"
+    end
+    ok, err = battle:chooseMove(intent.slot)
+  elseif intent.kind == "back" then
+    ok, err = battle:cancelMove()
+  else
+    return nil, "unknown battle intent"
+  end
+  if not ok then return nil, err end
+  self.lastIntentId = intent.id
+  self.signature = nil
+  return true
+end
+
+return BattleAPI

src/battle/BattleState.lua

@@ -38,6 +38,7 @@ local romText = RomText
 local BattleState = {}
 BattleState.__index = BattleState
 BattleState.isOpaque = true
+BattleState.isBattleState = true
 
 -- Category identity for per-category GAME SPEED (RFC 0007), the same
 -- style OverworldController.isOverworld already uses. Every battle --
@@ -156,6 +157,13 @@ function BattleState:caughtMarkerVisible()
                       function() return false end, self) == true
 end
 
+function BattleState:catchChance(ball, rateOverride)
+  if Runtime.wantsHook("catch.rate") then return nil end
+  return Catching.chance(ball, self.enemy.mon, self.enemy.def, rateOverride,
+    { ballDef = self:ballDef(ball), statuses = self.data.statuses,
+      battle = self })
+end
+
 function BattleState:moveGridNavigation()
   if self:wideLayout() then return true end
   if not Runtime.wantsHook("battle.move_grid_navigation") then return false end
@@ -316,6 +324,27 @@ function BattleState.trainerPicPath(data, trainer, oppClass, partyIndex)
   return base and base.pic or nil
 end
 
+-- trueColor on the trainer record, or on the basePic it reuses when the
+-- subclass does not set the flag itself.  Explicit false stays false.
+function BattleState.trainerTrueColor(data, trainer)
+  if not trainer then return false end
+  if trainer.trueColor ~= nil then
+    return trainer.trueColor and true or false
+  end
+  local base = trainer.basePic and data and data.trainers
+    and data.trainers[trainer.basePic]
+  return (base and base.trueColor) and true or false
+end
+
+-- Load a trainer frontpic through getImage so a trueColor portrait skips
+-- the 4-shade quantize the same way a species pic does.
+function BattleState.trainerSprite(data, trainer, oppClass, partyIndex)
+  return getImage(
+    BattleState.trainerPicPath(data, trainer, oppClass, partyIndex),
+    BattleState.trainerPalette(data, trainer),
+    BattleState.trainerTrueColor(data, trainer))
+end
+
 -- The battle-BGP fade variant of a pic (AnimationFlashScreen and the
 -- SetAnimationBGPalette effects remap the four BG shades; on the SGB
 -- the colorizer then colors the REMAPPED shade, so a faded pic shows
@@ -501,6 +530,9 @@ local function makeBattler(data, mon, isPlayer, save)
     badgeBoosts = badgeBoosts,
     statuses = data.statuses,
     shownHP = mon.hp, -- the HP the bar displays (UpdateHPBar drain)
+    -- the bar's own length in GetHPBarLength pixels; it trails shownHP
+    -- because UpdateHPBar_AnimateHPBar slides it one pixel at a time
+    shownPx = Timing.hpBarPixels(mon.hp, math.max(1, mon.stats.hp)),
     -- HUD status label (DrawHUDsAndHPBars); mon.status can land mid-move
     -- while the tilemap still shows the prior condition until the next
     -- post-action HUD refresh (core.asm after Execute*Move)
@@ -563,10 +595,6 @@ local function markOwned(game, species)
   local dex = game.save.pokedex
   if dex then
     dex.seen[species] = true
-    if not dex.owned[species] then
-      -- new dex page registered (SFX_DEX_PAGE_ADDED)
-      require("src.core.Sound").play(game.data, "Dex_Page_Added")
-    end
     dex.owned[species] = true
   end
 end
@@ -613,10 +641,49 @@ local function newBattle(game)
   self.phase = "intro"
   self.menuIndex = 1
   self.moveIndex = 1
+  self.playerMoveListIndex = 1
   self.frame = 0
   return self
 end
 
+local function scopedPlayerParty(game, indices)
+  if indices == nil then return nil, nil end
+  if type(indices) ~= "table" then
+    Logger.warn("trainer battle party scope is not a table; using full party")
+    return nil, nil
+  end
+  local count = #indices
+  local keyCount = 0
+  for key in pairs(indices) do
+    keyCount = keyCount + 1
+    if type(key) ~= "number" or key % 1 ~= 0 or key < 1 or key > count then
+      Logger.warn("trainer battle party scope is malformed; using full party")
+      return nil, nil
+    end
+  end
+  if count == 0 or keyCount ~= count then
+    Logger.warn("trainer battle party scope is empty or sparse; using full party")
+    return nil, nil
+  end
+  local party, normalized, seen = {}, {}, {}
+  for i = 1, count do
+    local index = indices[i]
+    if type(index) ~= "number" or index % 1 ~= 0
+        or not game.save.party[index] or seen[index] then
+      Logger.warn("trainer battle party scope contains an invalid index; using full party")
+      return nil, nil
+    end
+    seen[index] = true
+    normalized[i] = index
+    party[i] = game.save.party[index]
+  end
+  return party, normalized
+end
+
+function BattleState:playerPartyView()
+  return self.playerParty or self.game.save.party
+end
+
 -- opts.hooked: rod encounter, announced with _HookedMonAttackedText
 function BattleState.newWild(game, species, level, opts)
   local self = newBattle(game)
@@ -692,13 +759,15 @@ local function applySpecialMoves(data, oppClass, partyIndex, party)
   end
 end
 
-function BattleState.newTrainer(game, oppClass, partyIndex)
+function BattleState.newTrainer(game, oppClass, partyIndex, opts)
   local self = newBattle(game)
   self.kind = "trainer"
   self.oppClass = oppClass
   -- the object_event trainer arg (roster index).  computeMusicKind keys
   -- data/scripts/victories.lua on class#party, so keep it on the battle (#782).
   self.partyIndex = partyIndex or 1
+  self.playerParty, self.playerPartyIndices = scopedPlayerParty(game,
+    type(opts) == "table" and opts.playerPartyIndices or nil)
   self.trainer = game.data.trainers[oppClass]
   assert(self.trainer, "unknown trainer class " .. tostring(oppClass))
   -- pret GetTrainerName_: RIVAL1/2/3 copy wRivalName into wTrainerName
@@ -742,7 +811,7 @@ function BattleState.newTrainer(game, oppClass, partyIndex)
     end
   end
   self.enemyIndex = 1
-  local playerMon = Party.firstHealthy(game.save.party)
+  local playerMon = Party.firstHealthy(self:playerPartyView())
   if not playerMon then
     Logger.warn("trainer battle with no healthy party; skipping")
     self.dead = true
@@ -756,9 +825,8 @@ function BattleState.newTrainer(game, oppClass, partyIndex)
   -- MonsterPalettes[0] = PAL_MEWMON -- InitBattleCommon zeroes
   -- wEnemyMonSpecies2 before the intro's SET_PAL_BATTLE
   -- (engine/battle/core.asm:6682, engine/gfx/palettes.asm SetPal_Battle)
-  self.trainerPic = getImage(
-    BattleState.trainerPicPath(game.data, self.trainer, oppClass, partyIndex),
-    BattleState.trainerPalette(game.data, self.trainer))
+  self.trainerPic = BattleState.trainerSprite(
+    game.data, self.trainer, oppClass, partyIndex)
   self.introText = Strings("%s wants\nto fight!", self.trainer.name)
   return self
 end
@@ -929,6 +997,22 @@ function BattleState:sayNext(text)
   table.insert(self.queue, self.nextInsert, { text = text })
 end
 
+function BattleState:sayNextWaitSfx(text, sfx)
+  self.nextInsert = (self.nextInsert or 0) + 1
+  table.insert(self.queue, self.nextInsert, { text = text, waitForLearningSfx = sfx })
+end
+
+-- WaitForSoundToFinish for a sound an act() has already started: PlayCry
+-- ends in `jp WaitForSoundToFinish` (home/pokemon.asm), so every cry in
+-- Gen 1 holds whatever the ROM does next.  `src` is the audio source, or a
+-- getter the row calls at execution time when the source is only known then.
+function BattleState:waitSfxNext(src)
+  self.nextInsert = (self.nextInsert or 0) + 1
+  table.insert(self.queue, self.nextInsert,
+               { waitSound = type(src) == "function" and src
+                             or function() return src end })
+end
+
 -- sayNext for a page that ends in `text_end` (see sayAuto) (#765)
 function BattleState:sayNextAuto(text, delay)
   self.nextInsert = (self.nextInsert or 0) + 1
@@ -1016,22 +1100,39 @@ function BattleState:stepHPDrain()
          and b.shownHP >= b.drainFloor then
         goal = b.drainFloor
       end
+      local maxHP = math.max(1, b.mon.stats.hp)
+      local playerSide = (b == self.player)
+      local targetPx = Timing.hpBarPixels(b.shownHP, maxHP)
+      if not b.shownPx then b.shownPx = targetPx end
       if (b.drainHold or 0) > 0 then
         b.drainHold = b.drainHold - 1
         busy = true
+      elseif b.shownPx ~= targetPx then
+        -- .barAnimationLoop redraws the bar one pixel at a time, `ld c, 2 /
+        -- call DelayFrames` apiece (:141-148), so a single HP point that
+        -- spans several pixels still slides instead of jumping
+        b.shownPx = b.shownPx + ((b.shownPx > targetPx) and -1 or 1)
+        b.drainHold = Timing.HP_BAR_PIXEL_STEP - 1
+        busy = true
       elseif b.shownHP ~= goal then
-        local maxHP = math.max(1, b.mon.stats.hp)
-        local playerSide = (b == self.player)
-        local cost = 0
+        local spent = 0
         -- consume whole HP steps until this frame's budget is spent; on the
         -- enemy HUD several free steps can land in the same frame
-        while b.shownHP ~= goal and cost < 1 do
-          local nextHP = b.shownHP + ((b.shownHP > goal) and -1 or 1)
-          cost = cost + Timing.hpDrainStepFrames(b.shownHP, nextHP,
-                                                 maxHP, playerSide)
-          b.shownHP = nextHP
+        repeat
+          b.shownHP = b.shownHP + ((b.shownHP > goal) and -1 or 1)
+          spent = spent + (playerSide and Timing.HP_BAR_HP_STEP or 0)
+          targetPx = Timing.hpBarPixels(b.shownHP, maxHP)
+        until b.shownHP == goal or targetPx ~= b.shownPx or spent >= 1
+        if spent > 0 then
+          b.drainHold = spent - 1
+        elseif targetPx ~= b.shownPx then
+          -- the enemy HUD printed no number, so this frame is already the
+          -- first of the pixel step the crossing just asked for
+          b.shownPx = b.shownPx + ((b.shownPx > targetPx) and -1 or 1)
+          b.drainHold = Timing.HP_BAR_PIXEL_STEP - 1
+        else
+          b.drainHold = 0
         end
-        b.drainHold = math.max(0, cost - 1)
         b.draining = true
         busy = true
       elseif b.draining then
@@ -1073,7 +1174,7 @@ function BattleState:startMessage(item)
     local npos = text:find("[\n\v]", pos)
     local chunk = npos and text:sub(pos, npos - 1) or text:sub(pos)
     local codes = Font.encode(chunk)
-    self.lines[#self.lines + 1] = { codes = codes, cont = cont }
+    self.lines[#self.lines + 1] = { codes = codes, cont = cont, text = chunk }
     self.total = self.total + #codes
     if not npos then break end
     cont = text:sub(npos, npos) == "\v"
@@ -1106,6 +1207,18 @@ function BattleState:beginMsgLine()
   self.shown[#self.shown + 1] = {}
 end
 
+function BattleState:visibleText()
+  if self.phase ~= "messages" or not (self.current or self.animPlaying) then
+    return nil
+  end
+  local out, count = {}, #(self.shown or {})
+  for i = math.max(1, self.lineIndex - count + 1), self.lineIndex do
+    local line = self.lines and self.lines[i]
+    if line then out[#out + 1] = line.text or "" end
+  end
+  return #out > 0 and out or nil
+end
+
 function BattleState:updateQueue()
   if self.waitingUI then
     if self.game.stack:top() ~= self then return true end
@@ -1255,13 +1368,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 +1474,11 @@ function BattleState:updateQueue()
         self.current = nil
       end
     elseif not (item and item.choice) then
+      if item and item.waitForLearningSfx and not item.soundStarted then
+        item.soundStarted = true
+        self.waitingSound = item.waitForLearningSfx()
+        return true
+      end
       -- The page is typed out and waiting on the player: PromptText
       -- (home/text.asm:209-217) writes '▼' at (18,16) and ManualTextScroll
       -- blinks it until A/B, so the arrow belongs on a finished page and not
@@ -1420,7 +1538,7 @@ end
 function BattleState:playEntranceCry(battler)
   local mon = battler and battler.mon
   if not mon then return end
-  require("src.core.Sound").playCry(self.data, mon.species,
+  return require("src.core.Sound").playCry(self.data, mon.species,
     mon.status == "SLP" and 37 or 11)
 end
 
@@ -1544,7 +1662,23 @@ function BattleState:enter()
   -- default stays opaque for every other battle and for older saves.
   self.isOpaque = self:bgMode() ~= "world"
   self.introSlide = Timing.BATTLE_SLIDE_IN_FRAMES
-  self.showEnemyTrainer = self.kind == "trainer" and self.trainerPic ~= nil
+  -- GetTrainerInformation .linkBattle (home/trainers2.asm:26-31): the link
+  -- foe's pic is RedPicFront whatever either save looks like, and
+  -- InitBattleCommon loads and tilemaps it at hlcoord 12,0 for every
+  -- wIsInBattle == 2 battle (core.asm:6681-6688), the link one included.
+  -- wEnemyMonSpecies2 is zeroed under it, so the pic palette is PAL_MEWMON
+  -- exactly as it is for a trainer.
+  if self.kind == "link" and not self.trainerPic then
+    local frontPath, frontTrueColor =
+      require("src.pokemon.Sprites").playerPath(self.data, "front",
+        { kind = "battle", battle = self })
+    if frontPath and require("src.render.Assets").exists(frontPath) then
+      self.trainerPic = getImage(frontPath, namedPalette(self.data, "MEWMON"),
+                                 frontTrueColor)
+    end
+  end
+  self.showEnemyTrainer = (self.kind == "trainer" or self.kind == "link")
+                          and self.trainerPic ~= nil
   -- DrawAllPokeballs (common_text.asm:27) puts the party ball rows AND the
   -- HUD corner/underline tiles under them (PlacePlayerHUDTiles /
   -- PlaceEnemyHUDTiles, draw_hud_pokeball_gfx.asm:119-165) on screen with
@@ -1576,13 +1710,13 @@ function BattleState:enter()
   -- a different point in each battle kind, so queue it per branch
   local function queueEnemyCry()
     self:act(function()
-      self:playEntranceCry(self.enemy)
+      self:waitSfxNext(self:playEntranceCry(self.enemy))
     end)
   end
   -- PrintBeginningBattleText (engine/battle/common_text.asm:10-19): a wild
-  -- battle calls PlayCry BEFORE PrintText WildMonAppearedText, so the cry
-  -- sounds with the "Wild X appeared!" box instead of waiting on the A
-  -- press that clears its `prompt` (#303).  The Silph-Scope-less tower
+  -- battle calls PlayCry BEFORE PrintText WildMonAppearedText, and PlayCry
+  -- ends in WaitForSoundToFinish, so the cry runs to its end and only then
+  -- does the "Wild X appeared!" box open (#303).  The Silph-Scope-less tower
   -- ghost gets no cry at all (common_text.asm:43-48), and neither does the
   -- unveiled MAROWAK: .isMarowak never reaches PlayCry (#492).
   if self.kind ~= "trainer" and self.kind ~= "link"
@@ -1600,7 +1734,10 @@ function BattleState:enter()
   -- The sfx is extracted as "Trainer_Appeared" (tools/rom_manifest.json
   -- sfxHeaders, bank 8 / $42bb -- the same header pokered names
   -- SFX_Silph_Scope); nothing had ever played it.
-  if self.kind == "trainer" then
+  --
+  -- A link battle is wIsInBattle == 2, so PrintBeginningBattleText takes the
+  -- same .trainerBattle arm and owes the sfx too (common_text.asm:20-23).
+  if self.kind == "trainer" or self.kind == "link" then
     self:act(function()
       self.introSfx = require("src.core.Sound").play(self.data,
                                                      "Trainer_Appeared")
@@ -1618,13 +1755,17 @@ function BattleState:enter()
   -- battle -- not on a switch, and not when the beaten trainer's pic
   -- scrolls back in (#317, #282)
   self:act(function() self.introBalls = nil end)
-  if self.kind == "trainer" then
-    -- EnemySendOutFirstMon (core.asm:1308-1310): SlideTrainerPicOffScreen
-    -- walks the foe's pic off the RIGHT edge (hlcoord 18,0, a = 8 tiles,
-    -- one tile every 2 frames) BEFORE TrainerSentOutText -- the pic does
-    -- not blink out under the text (#317)
-    self:act(function() self:slidePic("foe", 0, 64, 4) end)
-    table.insert(self.queue, { wait = 16 })
+  if self.kind == "trainer" or self.kind == "link" then
+    local foeName = self.trainer and self.trainer.name
+                    or self.opponentName or Strings("FOE")
+    if self.showEnemyTrainer then
+      -- EnemySendOutFirstMon (core.asm:1308-1310): SlideTrainerPicOffScreen
+      -- walks the foe's pic off the RIGHT edge (hlcoord 18,0, a = 8 tiles,
+      -- one tile every 2 frames) BEFORE TrainerSentOutText -- the pic does
+      -- not blink out under the text (#317)
+      self:act(function() self:slidePic("foe", 0, 64, 4) end)
+      table.insert(self.queue, { wait = 16 })
+    end
     self:act(function()
       self.showEnemyTrainer = false
       -- the slot is EMPTY from here until AnimateSendingOutMon runs below:
@@ -1637,7 +1778,7 @@ function BattleState:enter()
       self.enemySendingOut = true
       self:slidePic("foe")
     end)
-    self:say(Strings("%s sent\nout %s!", self.trainer.name, self.enemy.name))
+    self:say(Strings("%s sent\nout %s!", foeName, self.enemy.name))
     self:act(function()
       -- EnemySendOutFirstMon (core.asm:1421-1434): after the text the
       -- pic grows out of the ball (AnimateSendingOutMon), then the cry
@@ -1645,18 +1786,6 @@ function BattleState:enter()
       self:startGrowIn(self.enemy)
     end)
     queueEnemyCry()
-  elseif self.kind == "link" then
-    -- Colosseum has no foe trainer pic, but the enemy mon still grows
-    -- out of the ball after "X sent out Y!" (not the wild "already there"
-    -- intro that LinkBattle previously inherited from newWild).
-    self.enemySendingOut = true
-    self:say(Strings("%s sent\nout %s!", self.opponentName or Strings("FOE"),
-                                          self.enemy.name))
-    self:act(function()
-      self.enemySendingOut = false
-      self:startGrowIn(self.enemy)
-    end)
-    queueEnemyCry()
   end
   -- StartBattle .foundFirstAliveEnemyMon (core.asm:152-156): the `call nz`
   -- gates only EnemySendOutFirstMon -- the `ld c, 40 / call DelayFrames`
@@ -1687,7 +1816,7 @@ function BattleState:enter()
       -- SendOutMon (core.asm:1757-1762): after the poof the mon grows
       -- out of the ball (AnimateSendingOutMon at hlcoord 4,11)
       self:startGrowIn(self.player)
-      self:playEntranceCry(self.player)
+      self:waitSfxNext(self:playEntranceCry(self.player))
     end)
     self:markParticipant()
   end
@@ -1746,6 +1875,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
@@ -1821,6 +1951,77 @@ function BattleState:playerHasPP()
   return false
 end
 
+-- One semantic path for the native command menu and mod.battle intents.
+function BattleState:chooseMenu(choice)
+  if self.phase ~= "menu" then return nil, "battle menu is not active" end
+  if not self.player or not self.player.mon or self.player.mon.hp <= 0
+      or self:menuLockedAction(self.player) then
+    return nil, "battle menu is not ready"
+  end
+  self:clearTurnFlinches()
+  if choice == "fight" and self.ghost then
+    self:say(Strings("%s is too\nscared to move!", self.player.name))
+    self.phase = "messages"
+    self.afterQueue = "menu"
+    self:act(function()
+      self:executeAction(self.enemy, self.player, self:enemyAction())
+    end)
+    -- A scared turn still ticks the player's residual effects.
+    self:queueResidual(self.player, self.enemy)
+    self:act(function() self:endOfTurn() end)
+  elseif choice == "fight" then
+    -- Trapping, Bide, and similar locks skip the move list.
+    local fightLock = self:fightLockedAction(self.player)
+    if fightLock then
+      self:resolveTurn(fightLock)
+    elseif not self:playerHasPP() then
+      -- No usable PP goes straight to Struggle.
+      self:say(Strings("%s has no\nmoves left!", self.player.name))
+      self:resolveTurn({ id = "STRUGGLE", pp = 1, struggle = true })
+    else
+      self.phase = "moveSelect"
+      self.moveIndex = math.min(self.moveIndex, #self.player.curMoves)
+      self.moveSwapIndex = nil
+    end
+  elseif choice == "run" then
+    self:tryRun()
+  elseif choice == "item" then
+    self:openItems()
+  elseif choice == "party" then
+    self:openParty()
+  else
+    return nil, "unknown battle menu choice"
+  end
+  return true
+end
+
+function BattleState:chooseMove(index)
+  if self.phase ~= "moveSelect" then return nil, "move menu is not active" end
+  local move = self.player.curMoves[index]
+  if not move then return nil, "invalid move slot" end
+  self.moveIndex = index
+  if self.player.disabledSlot == index then
+    self:say(self:romText("_MoveDisabledText", "The move is\ndisabled!"))
+    self.phase = "messages"
+    self.afterQueue = "menu"
+  elseif move.pp <= 0 then
+    self:say(self:romText("_MoveNoPPText", "No PP left for\nthis move!"))
+    self.phase = "messages"
+    self.afterQueue = "menu"
+  else
+    self.playerMoveListIndex = index
+    self:resolveTurn(move)
+  end
+  return true
+end
+
+function BattleState:cancelMove()
+  if self.phase ~= "moveSelect" then return nil, "move menu is not active" end
+  self.moveSwapIndex = nil
+  self.phase = "menu"
+  return true
+end
+
 function BattleState:swapMoves(i, j)
   if i == j then return end
   local moves = self.player.curMoves
@@ -1864,7 +2065,10 @@ function BattleState:update(dt)
   if self.phase == "menu" then
     for _, b in ipairs({ self.player, self.enemy }) do
       if b then
-        if b.shownHP then b.shownHP = b.mon.hp end
+        if b.shownHP then
+          b.shownHP = b.mon.hp
+          b.shownPx = Timing.hpBarPixels(b.mon.hp, math.max(1, b.mon.stats.hp))
+        end
         b.drainFloor = nil
         b.shownStatus = b.mon.status
       end
@@ -1949,7 +2153,7 @@ function BattleState:update(dt)
     -- loops the party menu until a healthy mon is picked, so B and
     -- fainted picks land back here and reopen it
     if self.player.mon.hp <= 0 then
-      if Party.firstHealthy(self.game.save.party) then
+      if Party.firstHealthy(self:playerPartyView()) then
         self:openReplacementMenu()
       end
       return
@@ -1987,42 +2191,7 @@ function BattleState:update(dt)
     self.menuIndex = row * 2 + col + 1
     if input:wasPressed("a") then
       require("src.core.Sound").play(self.data, "Press_AB")
-      local choice = ({ "fight", "pkmn", "item", "run" })[self.menuIndex]
-      if choice == "fight" and self.ghost then
-        self:say(Strings("%s is too\nscared to move!", self.player.name))
-        self.phase = "messages"
-        self.afterQueue = "menu"
-        self:act(function()
-          self:executeAction(self.enemy, self.player, self:enemyAction())
-        end)
-        -- the scared turn still ticks the player's residual (PrintGhostText
-        -- -> ExecutePlayerMoveDone, core.asm:3056, 3275-3279)
-        self:queueResidual(self.player, self.enemy)
-        self:act(function() self:endOfTurn() end)
-      elseif choice == "fight" then
-        -- After the menu: own trapping/Bide or foe Wrap skips the move
-        -- list and forces the locked action (core.asm:320-329)
-        local fightLock = self:fightLockedAction(self.player)
-        if fightLock then
-          self:resolveTurn(fightLock)
-          return
-        end
-        if not self:playerHasPP() then
-          -- _NoMovesLeftText, then Struggle engages
-          self:say(Strings("%s has no\nmoves left!", self.player.name))
-          self:resolveTurn({ id = "STRUGGLE", pp = 1, struggle = true })
-          return
-        end
-        self.phase = "moveSelect"
-        self.moveIndex = math.min(self.moveIndex, #self.player.curMoves)
-        self.moveSwapIndex = nil
-      elseif choice == "run" then
-        self:tryRun()
-      elseif choice == "item" then
-        self:openItems()
-      else
-        self:openParty()
-      end
+      self:chooseMenu(({ "fight", "party", "item", "run" })[self.menuIndex])
     end
     return
   end
@@ -2044,13 +2213,14 @@ 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")
-      self.moveSwapIndex = nil
-      self.phase = "menu"
+      self:cancelMove()
     elseif input:wasPressed("a") then
       require("src.core.Sound").play(self.data, "Press_AB")
       if self.moveSwapIndex then
@@ -2058,18 +2228,7 @@ function BattleState:update(dt)
         self.moveSwapIndex = nil
         return
       end
-      local mv = moves[self.moveIndex]
-      if self.player.disabledSlot == self.moveIndex then
-        self:say(self:romText("_MoveDisabledText", "The move is\ndisabled!"))
-        self.phase = "messages"
-        self.afterQueue = "menu"
-      elseif mv.pp <= 0 then
-        self:say(self:romText("_MoveNoPPText", "No PP left for\nthis move!"))
-        self.phase = "messages"
-        self.afterQueue = "menu"
-      else
-        self:resolveTurn(mv)
-      end
+      self:chooseMove(self.moveIndex)
     end
     return
   end
@@ -2279,10 +2438,10 @@ function BattleState:oldManThrow()
       return
     end
     self:ballChain("TOSS_ANIM", true, 3, "POKE_BALL")
-    self:actNext(function()
-      require("src.core.Sound").play(self.data, "Caught_Mon")
-    end)
-    self:sayNext(Strings("All right!\n%s was\ncaught!", self.enemy.name))
+    -- ItemUseBallText05: text_far, sound_caught_mon, text_promptbutton --
+    -- the fanfare follows the caught text and holds the prompt
+    self:sayNextWaitSfx(Strings("All right!\n%s was\ncaught!", self.enemy.name),
+      function() return require("src.core.Sound").play(self.data, "Caught_Mon") end)
   end)
 end
 
@@ -2423,11 +2582,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"
@@ -2435,7 +2592,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)
@@ -2466,7 +2625,7 @@ function BattleState:resolveSwitch(newMon)
       self.sendingOut = false
       -- SendOutMon (core.asm:1757-1762): poof, then the grow-in
       self:startGrowIn(self.player)
-      self:playEntranceCry(self.player)
+      self:waitSfxNext(self:playEntranceCry(self.player))
     end)
   end)
   self:act(function()
@@ -2945,7 +3104,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
@@ -3778,7 +3937,7 @@ function BattleState:onFaint(battler)
     if battler.isPlayer then
       -- RemoveFaintedPlayerMon (core.asm:1040-1042): the player mon's
       -- faint plays its ordinary species cry -- no Faint_Fall
-      Sound.playCry(self.data, battler.mon.species)
+      self.faintCry = Sound.playCry(self.data, battler.mon.species)
     elseif self.kind ~= "wild" then
       -- FaintEnemyPokemon (core.asm:732-771): the enemy faint plays no
       -- species cry; trainer battles get SFX_FAINT_FALL, then SFX_FAINT_THUD
@@ -3793,6 +3952,11 @@ function BattleState:onFaint(battler)
   end)
   self.nextInsert = (self.nextInsert or 0) + 1
   table.insert(self.queue, self.nextInsert, { wait = Timing.FAINT_SLIDE })
+  if battler.isPlayer then
+    -- RemoveFaintedPlayerMon ends `call PlayCry / jp PrintText`, and PlayCry
+    -- is `jp WaitForSoundToFinish`, so "X fainted!" waits out the cry
+    self:waitSfxNext(function() return self.faintCry end)
+  end
   if not battler.isPlayer and self.kind ~= "wild" then
     -- FaintEnemyPokemon's SFX_FAINT_THUD lands as the slide does (after
     -- Faint_Fall, before EnemyMonFaintedText)
@@ -3829,7 +3993,8 @@ function BattleState:awardExp()
   -- (RemoveFaintedPlayerMon), so it drops out of the divisor and only
   -- the surviving participants are counted and paid
   local participants, alive = 0, {}
-  for _, mon in ipairs(self.game.save.party) do
+  local playerParty = self:playerPartyView()
+  for _, mon in ipairs(playerParty) do
     if self.participants and self.participants[mon] then
       participants = participants + 1
       if mon.hp > 0 then table.insert(alive, mon) end
@@ -3839,9 +4004,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).
@@ -3865,7 +4033,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))
@@ -3877,9 +4045,11 @@ function BattleState:awardExp()
       -- experience.asm:248 fires per grew-level text
       require("src.world.PikachuFollower")
         .modifyHappiness(game.save, "LEVELUP", mon)
-      self:sayNext(Strings("%s grew\nto level %d!", name, lv))
+      -- GrewLevelText: text_far, sound_level_up, text_end (experience.asm:
+      -- 369-372); PrintStatsBox only runs once PrintText has returned
+      self:sayNextWaitSfx(Strings("%s grew\nto level %d!", name, lv),
+        function() return require("src.core.Sound").play(game.data, "Level_Up") end)
       self:uiNext(function()
-        require("src.core.Sound").play(game.data, "Level_Up")
         return StatBox.new(game, mon)
       end)
       -- After PrintStatsBox, experience.asm reloads the active battler's
@@ -3918,9 +4088,9 @@ function BattleState:awardExp()
       -- experience.asm:9-13); each mon gets its own GainedText with the
       -- "with EXP.ALL," tail (wBoostExpByExpAll) -- pokered prints no
       -- summary line
-      for _, mon in ipairs(self.game.save.party) do
+      for _, mon in ipairs(playerParty) do
         if mon.hp > 0 then
-          ctx.applyShare(mon, math.max(1, ctx.participants) * #self.game.save.party * 2, "expAll")
+          ctx.applyShare(mon, math.max(1, ctx.participants) * #playerParty * 2, "expAll")
         end
       end
     end
@@ -3961,7 +4131,7 @@ function BattleState:enemyMonFainted()
       local nextName = nextMon.nickname or self.data.pokemon[nextMon.species].name
       local style = tostring((self.game.save.options or {}).battleStyle or "shift")
         :lower()
-      local partyCount = #self.game.save.party
+      local partyCount = #self:playerPartyView()
       -- ReplaceFaintedEnemyMon (core.asm:892-896): DrawEnemyPokeballs puts the
       -- foe's party ball row -- and the HUD chrome PlaceEnemyHUDTiles lays
       -- down under it (draw_hud_pokeball_gfx.asm:9-11, 33-45, 134-141) -- into
@@ -3988,6 +4158,7 @@ function BattleState:enemyMonFainted()
             local game = self.game
             Screens.push(game, "PartyMenu", {
               battle = self,
+              party = self:playerPartyView(),
               forceSwitch = true,
               onSwitch = function(mon)
                 if mon ~= self.player.mon and mon.hp > 0 then
@@ -4024,7 +4195,7 @@ function BattleState:enemyMonFainted()
           self.enemySendingOut = false
           self:startGrowIn(self.enemy)
           self:actNext(function()
-            self:playEntranceCry(self.enemy)
+            self:waitSfxNext(self:playEntranceCry(self.enemy))
           end)
         end)
       end)
@@ -4063,7 +4234,7 @@ function BattleState:enemyMonFainted()
         self:actNext(function()
           self.sendingOut = false
           self:startGrowIn(self.player)
-          self:playEntranceCry(self.player)
+          self:waitSfxNext(self:playEntranceCry(self.player))
         end)
       end)
       return
@@ -4129,15 +4300,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
 
@@ -4158,7 +4331,7 @@ function BattleState.isOaksLabStarterRival(self)
 end
 
 function BattleState:playerMonFainted()
-  local nextMon = Party.firstHealthy(self.game.save.party)
+  local nextMon = Party.firstHealthy(self:playerPartyView())
   -- Being out of useable POKéMON blacks you out even when the battle was
   -- already decided in our favour.  A double faint -- our last mon dying
   -- to residual damage on the turn it lands the KO -- used to hit the
@@ -4231,6 +4404,7 @@ function BattleState:openReplacementMenu()
   self:ui(function()
     return self:buildScreen("PartyMenu", {
       battle = self,
+      party = self:playerPartyView(),
       -- ChooseNextMon: pick immediately (no SWITCH/STATS/CANCEL)
       forceSwitch = true,
       onSwitch = function(mon)
@@ -4257,7 +4431,7 @@ function BattleState:openReplacementMenu()
           self.sendingOut = false
           -- SendOutMon (core.asm:1757-1762): poof, then the grow-in
           self:startGrowIn(self.player)
-          self:playEntranceCry(self.player)
+          self:waitSfxNext(self:playEntranceCry(self.player))
         end)
       end,
     })
@@ -4301,11 +4475,10 @@ function BattleState:safariAction(choice)
       -- above DoBallTossSpecialEffects's <= ULTRA_BALL check)
       self:ballChain(self:tossAnimFor("SAFARI_BALL"), caught, shakes, "SAFARI_BALL")
       if caught then
-        -- ItemUseBallText05's sound_caught_mon: fanfare with the text
-        self:actNext(function()
-          require("src.core.Sound").play(self.data, "Caught_Mon")
-        end)
-        self:sayNext(Strings("All right!\n%s was\ncaught!", self.enemy.name))
+        -- ItemUseBallText05: text_far, sound_caught_mon, text_promptbutton --
+        -- the fanfare follows the caught text and holds the prompt
+        self:sayNextWaitSfx(Strings("All right!\n%s was\ncaught!", self.enemy.name),
+          function() return require("src.core.Sound").play(self.data, "Caught_Mon") end)
         -- same ItemUseBall .captured flow as a regular ball
         self:act(function() self:storeCaughtMon() end)
       else
@@ -4533,8 +4706,12 @@ function BattleState:storeCaughtMon()
   markOwned(game, species)
   stampOT(game.save, self.enemy.mon)
   if isNew then
-    -- _ItemUseBallText06 + ShowPokedexData
-    self:sayNext(Strings("New POKéDEX data\nwill be added for\n%s!", self.enemy.name))
+    -- _ItemUseBallText06 + ShowPokedexData: text_far, sound_dex_page_added,
+    -- text_promptbutton (item_effects.asm:624-629), so the fanfare follows
+    -- the box rather than firing when the dex bit is set
+    self:sayNextWaitSfx(
+      Strings("New POKéDEX data\nwill be added for\n%s!", self.enemy.name),
+      function() return require("src.core.Sound").play(self.data, "Dex_Page_Added") end)
     self:uiNext(function()
       return self:buildScreen("DexEntryMenu", species)
     end)
@@ -4684,12 +4861,10 @@ function BattleState:throwBall(ball)
     self:ballChain(self:tossAnimFor(ball), caught, shakes, ball)
     if caught then
       -- ItemUseBallText05 carries sound_caught_mon (item_effects.asm:
-      -- 608-614): the fanfare sounds with the caught message, before
-      -- the prompt, not after the text is dismissed
-      self:actNext(function()
-        require("src.core.Sound").play(self.data, "Caught_Mon")
-      end)
-      self:sayNext(Strings("All right!\n%s was\ncaught!", self.enemy.name))
+      -- 608-614): text_far, sound_caught_mon, text_promptbutton -- the
+      -- fanfare follows the caught message and holds the prompt
+      self:sayNextWaitSfx(Strings("All right!\n%s was\ncaught!", self.enemy.name),
+        function() return require("src.core.Sound").play(self.data, "Caught_Mon") end)
       self:act(function() self:storeCaughtMon() end)
     else
       self:sayNext(self:ballMissMessage(shakes))
@@ -4710,6 +4885,7 @@ function BattleState:openParty()
   self:ui(function()
     return self:buildScreen("PartyMenu", {
       battle = self,
+      party = self:playerPartyView(),
       onSwitch = function(mon)
         if mon == self.player.mon then
           self:say(Strings("%s is\nalready out!", self.player.name))
@@ -4756,8 +4932,8 @@ function BattleState:finish()
   -- here it did not, so say so rather than silently papering over it.
   -- The old-man / PROF.OAK demo also skips it: the party never fought
   -- (Yellow's Pallet intro runs before the player owns a mon at all).
-  if self.result ~= "lose" and not self.demo
-     and not Party.firstHealthy(self.game.save.party) then
+  if self.kind ~= "link" and self.result ~= "lose" and not self.demo
+     and not Party.firstHealthy(self:playerPartyView()) then
     Logger.warn("battle finished %s with no healthy party; forcing blackout",
                 tostring(self.result))
     self.result = "lose"
@@ -5176,7 +5352,8 @@ function BattleState:sgbBattlePals()
   local function bar(b)
     if not b then return pals.GREENBAR end
     local hp = b.shownHP or b.mon.hp
-    return pals[PaletteFX.barPalName(hp, b.mon.stats.hp)] or pals.GREENBAR
+    return pals[PaletteFX.barPalName(hp, b.mon.stats.hp, b.shownPx)]
+           or pals.GREENBAR
   end
   local function mon(b, placeholder)
     if placeholder or not b then return pals.MEWMON or pals.GREENBAR end
@@ -5574,7 +5751,7 @@ function BattleState:drawHUDs(slide)
     hudTile(0x73, 8, 16)
     drawHPBar(barData, 2, 2,
               { hp = shownHP(self.enemy), stats = self.enemy.mon.stats },
-              nil, grayFill)
+              nil, grayFill, nil, self.enemy.shownPx)
     hudTile(0x74, 8, 24)
     for i = 2, 9 do hudTile(0x76, i * 8, 24) end
     hudTile(0x78, 80, 24)
@@ -5637,7 +5814,7 @@ function BattleState:drawHUDs(slide)
     for i = 10, 17 do hudTile(0x76, i * 8, 88) end
     hudTile(0x6F, 72, 88)
     love.graphics.setColor(1, 1, 1, 1)
-    self:drawBallRow(self.playerParty or self.game.save.party, 88, 80, 8)
+    self:drawBallRow(self:playerPartyView(), 88, 80, 8)
   end
   local hidePlayer = self.safari or self.demo
   if showStatus and self.player and not hidePlayer and not self.showPlayerBack
@@ -5655,7 +5832,7 @@ function BattleState:drawHUDs(slide)
     end
     drawHPBar(barData, 10, 9,
               { hp = shownHP(self.player), stats = self.player.mon.stats },
-              1, grayFill) -- wHPBarType 1: the $6D cap
+              1, grayFill, nil, self.player.shownPx) -- wHPBarType 1: the $6D cap
     Font.draw(("%3d/%3d"):format(shownHP(self.player), self.player.mon.stats.hp), 88, 80)
     hudTile(0x73, 144, 80)
     hudTile(0x77, 144, 88)
@@ -5791,6 +5968,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/Catching.lua

@@ -27,6 +27,17 @@ Catching.BALLS = BALLS
 -- divisor, which is what the old per-field `or` defaults resolved to
 local DEFAULT_BALL = { randMax = 255, hpFactor = 12, wobbleFactor = 150 }
 
+local function stockFactors(def, targetMon, targetDef, rateOverride, statuses)
+  local rate = rateOverride or targetDef.catchRate
+  local record = Status.recordFor(statuses, targetMon.status)
+  local statusBonus = record and record.catchBonus or 0
+  local hpQuarter = math.max(1, math.floor(targetMon.hp / 4))
+  local factor = def.hpFactor or DEFAULT_BALL.hpFactor
+  local f = math.min(255, math.floor(math.floor(
+    targetMon.stats.hp * 255 / factor) / hpQuarter))
+  return rate, statusBonus, f, record
+end
+
 function Catching.registerInto(registry, _, owner)
   for id, record in pairs(BALLS) do
     registry:register(id, record, owner)
@@ -41,21 +52,9 @@ end
 local function stockAttempt(def, targetMon, targetDef, rng, rateOverride, statuses)
   if def.autoCatch then return true, 3 end
   local randMax = def.randMax
-  local rate = rateOverride or targetDef.catchRate
-
-  -- the status subtraction and the wobble bonus come off the merged
-  -- status record (SLP/FRZ 25 and +10, the rest 12 and +5)
   local s = targetMon.status
-  local record = Status.recordFor(statuses, s)
-  local statusBonus = record and record.catchBonus or 0
-
-  -- HP factor (X)
-  local maxhp = targetMon.stats.hp
-  local hpQuarter = math.max(1, math.floor(targetMon.hp / 4))
-  local factor = def.hpFactor or DEFAULT_BALL.hpFactor
-  -- the 255 cap applies only after BOTH divisions (ItemUseBall keeps
-  -- the intermediate in 16 bits); capping early collapses the value
-  local f = math.min(255, math.floor(math.floor(maxhp * 255 / factor) / hpQuarter))
+  local rate, statusBonus, f, record = stockFactors(
+    def, targetMon, targetDef, rateOverride, statuses)
 
   local function shakes()
     local ballFactor2 = def.wobbleFactor or DEFAULT_BALL.wobbleFactor
@@ -80,6 +79,22 @@ local function stockAttempt(def, targetMon, targetDef, rng, rateOverride, status
   return false, shakes()
 end
 
+-- Exact stock catch probability for read-only previews.  A custom attempt
+-- function may do anything, so nil is safer than presenting a plausible lie.
+function Catching.chance(ball, targetMon, targetDef, rateOverride, opts)
+  opts = opts or {}
+  local def = opts.ballDef or BALLS[ball] or DEFAULT_BALL
+  if def.attempt then return nil end
+  if def.autoCatch then return 100 end
+  local rate, statusBonus, f = stockFactors(
+    def, targetMon, targetDef, rateOverride, opts.statuses)
+  local outcomes = def.randMax + 1
+  local automatic = math.min(outcomes, math.max(0, statusBonus))
+  local passed = math.min(outcomes, math.max(0, rate + statusBonus + 1))
+  return (automatic + (passed - automatic) * (f + 1) / 256)
+    * 100 / outcomes
+end
+
 -- Returns caught, shakes (0-3).  rateOverride replaces the species catch
 -- rate (the Safari game's BAIT/ROCK-modified wEnemyMonActualCatchRate).
 -- opts (all optional): ballDef = the merged ball record, statuses = the

src/battle/Damage.lua

@@ -83,25 +83,35 @@ function Damage.critRoll(ruleset, attacker, moveId, rng, highCrit)
   return rng(0, 255) < b
 end
 
--- Accuracy test: rand(0..255) < floor(accuracy * 255 / 100) adjusted by
--- accuracy/evasion stages.  With oneIn256Miss a max-accuracy move still
--- misses on 255.
-function Damage.accuracyRoll(ruleset, move, attacker, defender, rng)
-  rng = rng or love.math.random
+-- Exact number of the 256 RNG outcomes that pass MoveHitTest.  Keeping the
+-- threshold public lets read-only UIs preview the same rules the roll uses.
+function Damage.accuracyThreshold(ruleset, move, attacker, defender)
   -- X ACCURACY sets USING_X_ACCURACY: the move simply never misses
   -- (MoveHitTest returns before any accuracy math, 1/256 included)
-  if attacker.xAccuracy then return true end
+  if attacker.xAccuracy then return 256 end
   local acc = math.floor(move.accuracy * 255 / 100)
+  local accuracyStage = attacker.stages and attacker.stages.accuracy or 0
+  local evasionStage = defender.stages and defender.stages.evasion or 0
   -- CalcHitChance scales by the accuracy stage and the evasion stage as
   -- two separate ratio multiplications, clamping each result
-  acc = math.min(255, Stats.applyStage(acc,
-          attacker.stages and attacker.stages.accuracy or 0))
-  acc = math.min(255, Stats.applyStage(acc,
-          -(defender.stages and defender.stages.evasion or 0)))
+  acc = math.min(255, Stats.applyStage(acc, accuracyStage))
+  acc = math.min(255, Stats.applyStage(acc, -evasionStage))
   if not ruleset.oneIn256Miss and move.accuracy >= 100
-     and (attacker.stages.accuracy or 0) >= (defender.stages.evasion or 0) then
-    return true
+     and accuracyStage >= evasionStage then
+    return 256
   end
+  return acc
+end
+
+function Damage.accuracyChance(ruleset, move, attacker, defender)
+  return Damage.accuracyThreshold(ruleset, move, attacker, defender) * 100 / 256
+end
+
+-- Accuracy test: rand(0..255) < the shared ruleset-aware threshold.
+function Damage.accuracyRoll(ruleset, move, attacker, defender, rng)
+  rng = rng or love.math.random
+  local acc = Damage.accuracyThreshold(ruleset, move, attacker, defender)
+  if acc == 256 then return true end
   return rng(0, 255) < acc
 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/WideBattle.lua

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

src/battle/gen2/Battle.lua

@@ -37,8 +37,10 @@ local Prize = require("src.battle.gen2.Prize")
 --   * Gen 1's `user` / `target` / `battler` are battler wrappers around a mon
 --     ({ mon = , name = , isPlayer = }); Gen 2's engine works on the party mon
 --     table directly, so that is what these payloads carry.
---   * Gen 1's `rng` is love.math.random (1..n); Gen 2's injected `random` is
---     the cart's BattleRandom convention (0..n-1).  Both keys are present.
+--   * Gen 1's `rng` is love.math.random (rng(n) → 1..n, rng(lo,hi) → lo..hi).
+--     Gen 2's cart BattleRandom is random(n) → 0..n-1.  Both live on the
+--     battle: `random` / `roller()` are BattleRandom for damage, accuracy,
+--     Magnitude, etc.; `rng` is the Gen 1 / love-style view of the same stream.
 local Runtime = require("src.mods.Runtime")
 -- The two battle lines that carry the cart's own `line` break: a marker-bearing
 -- literal has to stay reachable from a translation mod (#186, #245), which is
@@ -88,6 +90,19 @@ local function rand(random, n)
   return math.random(n) - 1
 end
 
+-- Gen 1 / love.math view of BattleRandom: rng(n) → 1..n, rng(lo,hi) → lo..hi.
+local function loveStyleRng(random)
+  return function(lo, hi)
+    if hi == nil then
+      local n = lo or 1
+      if n < 1 then n = 1 end
+      return (rand(random, n) or 0) + 1
+    end
+    if hi < lo then lo, hi = hi, lo end
+    return lo + (rand(random, hi - lo + 1) or 0)
+  end
+end
+
 -- data/trainers/leaders.asm.  The two lists are ONE array in the ROM: only
 -- KantoGymLeaders carries the -1 terminator, and GymLeaders falls through into
 -- it, so IsGymLeader matches all twenty-two classes while IsKantoGymLeader
@@ -212,12 +227,15 @@ Battle.KANTO_BADGE_ORDER = {
 --             this wild battle is BATTLETYPE_ROAMING; the caller built `wild`
 --             through Roamers.beginBattle and reads Battle.roaming back to
 --             bank the beast's HP afterwards
---   random(n) 0..n-1, injected so a test is deterministic
+--   random(n) 0..n-1, injected so a test is deterministic (BattleRandom)
+--   rng(lo,hi) / rng(n) Gen 1 / love.math contract; defaults over `random`
 function Battle.new(opts)
   opts = opts or {}
   local self = setmetatable({}, Battle)
   self.data = opts.data or {}
   self.random = opts.random 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
@@ -403,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
@@ -1604,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

src/battle/gen2/BattleAPI.lua

@@ -0,0 +1,172 @@
+-- Read-only Gen 2 battle state with the same shape as mod.battle on Gen 1.
+
+local BattleAPI = {}
+BattleAPI.__index = BattleAPI
+
+function BattleAPI.new(game)
+  return setmetatable({ game = game, revision = 0, signature = nil }, BattleAPI)
+end
+
+local function activeBattle(game)
+  local states = game and game.stack and game.stack.states or {}
+  local battle
+  for i = #states, 1, -1 do
+    local state = states[i]
+    if state.screenId == "Gen2BattleState" or state.isGen2BattleState then
+      battle = state
+      break
+    end
+  end
+  return battle, states[#states]
+end
+
+local function monCopy(data, mon, active)
+  if not mon then return nil end
+  local def = data and data.pokemon and data.pokemon[mon.species]
+  return { species = mon.species,
+    name = mon.nickname or (def and def.name) or mon.species,
+    level = mon.level, hp = mon.hp,
+    maxHp = mon.maxHp or (mon.stats and mon.stats.hp) or mon.hp,
+    status = mon.status, active = active and true or false }
+end
+
+local function messageCopy(screen)
+  if not screen.message then return nil end
+  local lines = {}
+  for line in tostring(screen.message):gmatch("[^\n]+") do
+    lines[#lines + 1] = line
+  end
+  return #lines > 0 and lines or nil
+end
+
+local function signature(game, screen, top)
+  if not screen then return "none" end
+  local battle = screen.battle or {}
+  local parts = { tostring(screen), tostring(top), tostring(screen.phase),
+    tostring(screen.message), tostring(screen.messageTimer),
+    tostring(screen.menuIndex), tostring(screen.moveIndex),
+    tostring(battle.turn), tostring(battle.over), tostring(battle.outcome) }
+  for _, mon in ipairs({ battle.player, battle.enemy }) do
+    parts[#parts + 1] = tostring(mon)
+    parts[#parts + 1] = tostring(mon and mon.hp)
+    parts[#parts + 1] = tostring(mon and mon.status)
+  end
+  for _, mon in ipairs((game.save and game.save.party) or battle.party or {}) do
+    parts[#parts + 1] = tostring(mon)
+    parts[#parts + 1] = tostring(mon.hp)
+    parts[#parts + 1] = tostring(mon.status)
+  end
+  return table.concat(parts, "|")
+end
+
+function BattleAPI:_revision(screen, top)
+  local nextSignature = signature(self.game, screen, top)
+  if nextSignature ~= self.signature then
+    self.signature = nextSignature
+    self.revision = self.revision + 1
+  end
+  return self.revision
+end
+
+local function moveCopies(game, battle)
+  local out = {}
+  for slot, move in ipairs((battle.player and battle.player.moves) or {}) do
+    local def = (game.data.moves or {})[move.id] or {}
+    out[slot] = { slot = slot, id = move.id, name = def.name or move.id,
+      pp = move.pp, maxPp = move.maxPp or def.pp or move.pp,
+      type = def.type, power = def.power, accuracy = def.accuracy,
+      disabled = battle:moveDisabled(battle.player, move.id) }
+  end
+  return out
+end
+
+local function battleKind(screen)
+  if screen.tutorial then return "oldman" end
+  return screen.battle and screen.battle.wild and "wild" or "trainer"
+end
+
+function BattleAPI:snapshot()
+  local game = self.game
+  local screen, top = activeBattle(game)
+  if not screen or not screen.battle then return nil end
+  local battle = screen.battle
+  local prompt = "locked"
+  if top == screen and screen.phase == "menu" then
+    prompt = "menu"
+  elseif top == screen and screen.phase == "moves" then
+    prompt = "moves"
+  elseif top == screen and screen.message then
+    prompt = "advance"
+  elseif top and top.screenId == "Gen2PartyMenu" then
+    prompt = "party"
+  end
+  local party = {}
+  for i, mon in ipairs((game.save and game.save.party) or battle.party or {}) do
+    party[i] = monCopy(game.data, mon, mon == battle.player)
+    party[i].slot = i
+  end
+  return { revision = self:_revision(screen, top), kind = battleKind(screen),
+    catchable = battle.wild and not screen.tutorial, prompt = prompt,
+    message = messageCopy(screen), turn = battle.turn or 0,
+    player = monCopy(game.data, battle.player, true),
+    enemy = monCopy(game.data, battle.enemy, true),
+    party = party, moves = moveCopies(game, battle),
+    -- Gold's PACK is pocketed and target selection is screen-owned.  Omit it
+    -- until the engine can expose the same semantic item records as Gen 1.
+    items = {} }
+end
+
+local MENU_CHOICES = { fight = true, party = true, item = true, run = true }
+
+local function validSlot(slot)
+  return type(slot) == "number" and slot % 1 == 0 and slot >= 1
+end
+
+function BattleAPI:submit(intent)
+  if type(intent) ~= "table" then return nil, "intent must be a table" end
+  if type(intent.id) ~= "number" or intent.id % 1 ~= 0 or intent.id < 1 then
+    return nil, "intent id must be a positive integer"
+  end
+  if self.lastIntentId and intent.id <= self.lastIntentId then
+    return nil, "replayed intent"
+  end
+
+  local screen, top = activeBattle(self.game)
+  if not screen or not screen.battle then return nil, "no battle" end
+  if intent.revision ~= self:_revision(screen, top) then
+    return nil, "stale battle context"
+  end
+  if screen.tutorial then return nil, "battle kind is not controllable" end
+  if top ~= screen then return nil, "battle menu is covered" end
+
+  local battle = screen.battle
+  local ok, err
+  if intent.kind == "menu" then
+    if screen.phase ~= "menu" then return nil, "battle menu is not active" end
+    if not MENU_CHOICES[intent.choice] then
+      return nil, "unknown battle menu choice"
+    end
+    ok, err = screen:chooseMenu(intent.choice)
+  elseif intent.kind == "move" then
+    if screen.phase ~= "moves" then return nil, "move menu is not active" end
+    if screen.moveSwapIndex then return nil, "move reorder is active" end
+    local move = validSlot(intent.slot) and battle.player
+      and battle.player.moves and battle.player.moves[intent.slot]
+    if not move then return nil, "invalid move slot" end
+    if (move.pp or 0) <= 0 then return nil, "move has no PP" end
+    if battle:moveDisabled(battle.player, move.id) then
+      return nil, "move is disabled"
+    end
+    ok, err = screen:chooseMove(intent.slot)
+  elseif intent.kind == "back" then
+    ok, err = screen:cancelMove()
+  else
+    return nil, "unknown battle intent"
+  end
+  if not ok then return nil, err end
+  self.lastIntentId = intent.id
+  self.signature = nil
+  return true
+end
+
+return BattleAPI

src/battle/gen2/Effects.lua

@@ -179,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
@@ -189,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
@@ -257,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

@@ -98,10 +98,69 @@ function Mon.stats(baseStats, dvs, level, statExp)
   }
 end
 
+-- The species string is the source of truth.  `mon.name` is a copy of that
+-- species' display name (GetPokemonName), kept so menus can print without a
+-- Data lookup.  It is NOT the nickname: an un-nicknamed mon has nickname nil
+-- and prints this copy.  Changing species without rewriting it leaves the
+-- previous species' name on the party list and the SUMMARY's top line.
+function Mon.syncIdentity(mon, data)
+  if type(mon) ~= "table" then return mon end
+  local def = data and data.pokemon and data.pokemon[mon.species]
+  if not def then return mon end
+  mon.name = def.name or mon.species
+  if def.types then mon.types = def.types end
+  if mon.dvs then
+    mon.gender = Mon.gender(def, mon.dvs,
+      { species = mon.species, level = mon.level })
+    mon.shiny = Mon.isShiny(mon.dvs,
+      { species = mon.species, def = def, level = mon.level })
+    if mon.species == Unown.SPECIES then
+      mon.unownLetter = Unown.letterFromDVs(mon.dvs)
+    else
+      mon.unownLetter = nil
+    end
+  end
+  return mon
+end
+
+-- Every screen that prints a mon without a Data lookup should go through here:
+-- nickname if the player set one, otherwise the species display copy `name`.
+-- Skipping `name` and jumping to `species` is how a swapped mon can still
+-- read as ABRA on one menu and RAYQUAZA on another.
+function Mon.displayName(mon)
+  if type(mon) ~= "table" then return "?" end
+  return mon.nickname or mon.name or mon.species or "?"
+end
+
+-- Party, boxes, both Day-Care sides, and a pending egg.  Editor CONTINUE and
+-- hydrate have to walk the same set: leaving dayCare.man.mon on the old
+-- `name` is the ABRA bug in a second closet.
+function Mon.eachSaveMon(save, fn)
+  if type(save) ~= "table" or type(fn) ~= "function" then return end
+  for _, mon in ipairs(save.party or {}) do fn(mon) end
+  for _, box in pairs(save.boxes or {}) do
+    if type(box) == "table" then
+      for _, mon in ipairs(box) do fn(mon) end
+    end
+  end
+  local dc = save.dayCare
+  if type(dc) == "table" then
+    if dc.man and dc.man.mon then fn(dc.man.mon) end
+    if dc.lady and dc.lady.mon then fn(dc.lady.mon) end
+    if dc.egg then fn(dc.egg) end
+  end
+  if save.daycare and save.daycare.mon then fn(save.daycare.mon) end
+end
+
+function Mon.syncSaveIdentity(save, data)
+  Mon.eachSaveMon(save, function(mon) Mon.syncIdentity(mon, data) end)
+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
+  Mon.syncIdentity(mon, data)
   -- engine/pokemon/move_mon.asm:1402
   local stats = Mon.stats(def.baseStats, mon.dvs, mon.level or 1, mon.statExp)
   mon.stats = stats

src/core/BattleCheckpoint.lua

@@ -44,6 +44,7 @@ local BATTLE_FIELDS = {
   "sideToxic", "isGymLeader", "musicKind", "lastBall", "lockedBall",
   "lowHealthAlarmDisabled", "lowHealthAlarmOn", "victoryMusicPlayed",
   "endBattleText",
+  "playerPartyIndices",
 }
 
 local function partyIndex(party, mon)
@@ -91,6 +92,23 @@ local function integer(value, min, max)
     and value >= (min or -math.huge) and value <= (max or math.huge)
 end
 
+local function exactIndexSet(indices, maxIndex, requireMember)
+  if type(indices) ~= "table" then return nil end
+  local count, keys = #indices, 0
+  for key in pairs(indices) do
+    keys = keys + 1
+    if not integer(key, 1, count) then return nil end
+  end
+  if keys ~= count or (requireMember and count == 0) then return nil end
+  local seen = {}
+  for i = 1, count do
+    local index = indices[i]
+    if not integer(index, 1, maxIndex) or seen[index] then return nil end
+    seen[index] = true
+  end
+  return seen
+end
+
 local function validateMoveList(data, moves)
   if type(moves) ~= "table" then return false end
   for _, move in ipairs(moves) do
@@ -200,6 +218,16 @@ function BattleCheckpoint.validate(game, checkpoint)
   if type(party) ~= "table" or not validateBattler(game.data, model.player, #party) then
     return nil, "invalid_content", "Player battle state is invalid."
   end
+  local scopedIndices
+  if model.playerPartyIndices ~= nil then
+    if model.kind ~= "trainer" then
+      return nil, "invalid_checkpoint", "Battle party scope is invalid."
+    end
+    scopedIndices = exactIndexSet(model.playerPartyIndices, #party, true)
+    if not scopedIndices or not scopedIndices[model.player.index] then
+      return nil, "invalid_checkpoint", "Battle party scope is invalid."
+    end
+  end
   if model.kind == "wild" then
     if not validateMon(game.data, model.enemyMon)
         or not validateBattler(game.data, model.enemy, 1) then
@@ -220,12 +248,15 @@ function BattleCheckpoint.validate(game, checkpoint)
     end
   end
   for _, indices in ipairs({ model.participants, model.leveledUp }) do
-    if type(indices) ~= "table" then
+    local referenced = exactIndexSet(indices, #party, false)
+    if not referenced then
       return nil, "invalid_checkpoint", "Battle party reference set is missing."
     end
-    for _, index in ipairs(indices) do
-      if not integer(index, 1, #party) then
-        return nil, "invalid_checkpoint", "Battle party reference is invalid."
+    if scopedIndices then
+      for index in pairs(referenced) do
+        if not scopedIndices[index] then
+          return nil, "invalid_checkpoint", "Battle party reference is invalid."
+        end
       end
     end
   end
@@ -276,7 +307,9 @@ function BattleCheckpoint.restore(game, checkpoint, copy)
   local model = checkpoint.runtime.battle
   local battle
   if model.kind == "trainer" then
-    battle = BattleState.newTrainer(game, model.oppClass, model.partyIndex)
+    battle = BattleState.newTrainer(game, model.oppClass, model.partyIndex, {
+      playerPartyIndices = model.playerPartyIndices,
+    })
     battle.enemyParty = assert(copy(model.enemyParty))
     battle.enemyIndex = model.enemyIndex
   else
@@ -334,6 +367,12 @@ function BattleCheckpoint.restore(game, checkpoint, copy)
     battle.player.mon.hp, battle.player.mon.status
   battle.enemy.shownHP, battle.enemy.shownStatus =
     battle.enemy.mon.hp, battle.enemy.mon.status
+  -- the bar's own pixel length is derived HUD state, not captured: it
+  -- settles with shownHP above (UpdateHPBar_AnimateHPBar's end position)
+  local Timing = require("src.core.Timing")
+  for _, b in ipairs({ battle.player, battle.enemy }) do
+    b.shownPx = Timing.hpBarPixels(b.mon.hp, math.max(1, b.mon.stats.hp))
+  end
 
   local ow = game.overworld
   if not ow or type(ow.restoreBattleContinuation) ~= "function"

src/core/Checkpoint.lua

@@ -313,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
@@ -394,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
@@ -474,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/Data.lua

@@ -14,6 +14,14 @@ local MODULES = {
 -- Optional for compatibility with developer and stale caches.
 local OPTIONAL = { "audio", "palettes", "icons" }
 
+-- Gold's extractor never writes these Gen 1 tables (RomExtractorGen2 has
+-- maps/text/pokemon/items, not text_pointers / trainer_headers / field).
+-- Desktop can still `require` Red's copies from the source tree, so Gold
+-- Edit appeared to work there; an Android APK has only the per-version
+-- cache, so Data:load used to throw on the first Gold Edit and take the
+-- activity down.  Empty tables are enough for seedDefaults / the editor.
+local GEN2_OPTIONAL = { text_pointers = true, trainer_headers = true, field = true }
+
 -- Vanilla defaults for rules exposed through the constants registry.  A
 -- value has to exist before a mod can patch it; each one matches the
 -- engine's no-mod behavior, so seeding them changes nothing on a vanilla
@@ -99,7 +107,11 @@ end
 -- Fills only what the cache is missing, so an importer that learns to
 -- stamp one of these keys silently takes over from the engine.
 function Data:seedDefaults()
-  local constants = self.constants
+  local constants = self.constants or {}
+  self.constants = constants
+  self.field = self.field or {}
+  self.maps = self.maps or {}
+  self.pokemon = self.pokemon or {}
   for key, value in pairs(CONSTANT_DEFAULTS) do
     if constants[key] == nil then constants[key] = copy(value) end
   end
@@ -108,7 +120,11 @@ function Data:seedDefaults()
   if constants.dexSize == nil then
     local highest = 0
     for _, def in pairs(self.pokemon) do
-      if def.dex and def.dex > highest then highest = def.dex end
+      -- Gold's pokemon.lua also carries growthRates / tmhmMoves / generation
+      -- scalars beside species rows.
+      if type(def) == "table" and def.dex and def.dex > highest then
+        highest = def.dex
+      end
     end
     constants.dexSize = highest
   end
@@ -212,36 +228,41 @@ local function loadModule(dir, name)
     if not chunk then return false, err end
     return pcall(chunk)
   end
-  local ok, mod = pcall(require, "data.generated." .. name)
-  if ok then return true, mod end
-  -- Fused PhysFS / Blue|Yellow prefix: load bytes from the active version's
-  -- cache explicitly when require cannot see the mounted tree.
   local CacheFs = require("src.import.CacheFs")
   local GameVersion = require("src.core.GameVersion")
   local path = "data/generated/" .. name .. ".lua"
   local bytes = CacheFs.readActive(path)
   if type(bytes) == "string" then
-    local chunk, err = loadstring(bytes, "@" .. GameVersion.cachePrefix() .. path)
-    if not chunk then return false, err or mod end
-    return pcall(chunk)
+    local chunk = loadstring(bytes, "@" .. GameVersion.cachePrefix() .. path)
+    if chunk then
+      local ok, res = pcall(chunk)
+      if ok then return true, res end
+    end
   end
-  return false, mod
+  local ok, mod = pcall(require, "data.generated." .. name)
+  if ok then return true, mod end
+  return false, nil
 end
 
 function Data:load()
   local dir = os.getenv("POKEPORT_DATA_DIR")
+  local gen2 = require("src.core.GameVersion").generation() == 2
   for _, name in ipairs(MODULES) do
     local ok, mod = loadModule(dir, name)
     if not ok then
-      if dir then
+      if gen2 and GEN2_OPTIONAL[name] then
+        self[name] = {}
+      elseif dir then
         error(("missing data module '%s/%s.lua' (POKEPORT_DATA_DIR).\n(%s)")
               :format(dir, name, mod))
+      else
+        error(("missing generated data module 'data/generated/%s.lua'.\n" ..
+               "Import the ROM again or rebuild developer data.\n(%s)")
+              :format(name, mod))
       end
-      error(("missing generated data module 'data/generated/%s.lua'.\n" ..
-             "Import the ROM again or rebuild developer data.\n(%s)")
-            :format(name, mod))
+    else
+      self[name] = mod
     end
-    self[name] = mod
   end
   for _, name in ipairs(OPTIONAL) do
     local ok, mod = loadModule(dir, name)
@@ -280,11 +301,14 @@ function Data:unloadGenerated()
       if not pristine[key] then self[key] = nil end
     end
   end
+  self._pristineKeys = nil
   for _, name in ipairs(MODULES) do
     package.loaded["data.generated." .. name] = nil
+    self[name] = nil
   end
   for _, name in ipairs(OPTIONAL) do
     package.loaded["data.generated." .. name] = nil
+    self[name] = nil
   end
 end
 

src/core/Game2.lua

@@ -73,7 +73,7 @@ end
 --
 -- Gold composites its own frame (Game2:draw / drawScene) and pumps its own pad
 -- (the FixedStep callback in Game2:load), so none of it goes through
--- src/render/Renderer.lua or src/core/Game.lua.  That explains why the six
+-- src/render/Renderer.lua or src/core/Game.lua.  That explains why the eight
 -- hooks below never used to fire here; it is not a reason they should not.  A
 -- hook is a contract about a MOMENT in the frame, and Gold has every one of
 -- these moments -- so each is raised under the Gen 1 NAME with the Gen 1
@@ -83,6 +83,7 @@ end
 --   input.pointer    uncaptured pointer events       (src/core/Game.lua:887)
 --   render.zones     the palette pass, pre-blit      (src/core/Game.lua:505)
 --   render.compose   the whole-window composite      (Renderer.lua:759)
+--   render.output*   the normal composed frame       (Renderer.lua:1063)
 --   render.letterbox the void around the 160x144 blit (Renderer.lua:840)
 --   render.hud       screen-space UI over the frame  (src/core/Game.lua:521)
 --
@@ -282,6 +283,9 @@ function Game2:continueGame(save)
   local modsDiff = SaveData.modsDiff(save, activeMods)
   self.save = save
   self:adoptSave(save)
+  -- Editor species swaps used to leave mon.name on the previous species.
+  -- CONTINUE rewrites party, boxes, and Day-Care copies from the live record.
+  require("src.battle.gen2.Mon").syncSaveIdentity(save, self.data)
   -- options.lua wins over anything a save file carries: options are a display
   -- preference that survives New Game and is edited from the launcher, so a
   -- save written before they moved out must not drag old values back in.
@@ -587,13 +591,13 @@ function Game2:useFieldItem(itemId)
       end
       if not allowed then
         self:say(("%s can't learn %s!"):format(
-          mon.nickname or mon.species or "?", moveName))
+          require("src.battle.gen2.Mon").displayName(mon), moveName))
         return
       end
       for _, move in ipairs(mon.moves or {}) do
         if move.id == moveId then
           self:say(("%s already knows %s!"):format(
-            mon.nickname or mon.species or "?", moveName))
+            require("src.battle.gen2.Mon").displayName(mon), moveName))
           return
         end
       end
@@ -689,10 +693,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
@@ -1366,12 +1386,14 @@ function Game2:draw()
   local zoned = type(zones) == "table" and zones[1] ~= nil
 
   -- A present canvas is paid for only when something reads it: the zone pass,
-  -- GBC FX, a mod post-process, or a render.compose subscriber about to be
-  -- handed the finished frame.  With none of them the frame draws straight to
-  -- the screen exactly as it always did.
+  -- GBC FX, a mod post-process, render.compose, or an enabled render.output
+  -- subscriber. With none of them the frame draws straight to the screen
+  -- exactly as it always did.
   local composing = ModRuntime.wantsHook("render.compose")
+  local hasOutputHook = ModRuntime.wantsHook("render.output")
+    and ModRuntime.call("render.output_enabled", function() return false end) == true
   local scene = nil
-  if zoned or fx or composing or Pipelines.wantsPresent() then
+  if zoned or fx or composing or Pipelines.wantsPresent() or hasOutputHook then
     scene = self:presentCanvas(1, w, h)
   end
   if not scene then
@@ -1403,7 +1425,7 @@ function Game2:draw()
   -- untinted one.  On its own the tint rides the final blit and no second
   -- canvas is paid for.
   local source = scene
-  local reread = fx or Pipelines.wantsPresent()
+  local reread = fx or Pipelines.wantsPresent() or hasOutputHook
   if zoned and reread then
     local tinted = self:presentCanvas(2, w, h)
     if tinted then
@@ -1423,15 +1445,25 @@ function Game2:draw()
     -- Post-process pipelines run over the finished composite and before GBC
     -- FX.  Each hands back a canvas; with none registered this returns `source`
     -- unchanged and the frame is byte-identical (Renderer.lua:1058).
-    local scale, _, _, dpi = self:frameFit(w, h)
+    local scale, ox, oy, dpi = self:frameFit(w, h)
     source = Pipelines.present(source, { width = w, height = h, scale = scale,
       dpi = dpi, dpiX = dpi, dpiY = dpi }) or source
-    if fx then
-      GBCFX.present(source, self:pixelScale(w, h))
-    else
-      G.setColor(1, 1, 1, 1)
-      G.draw(source, 0, 0)
-      G.setShader()
+    local outputHandled = hasOutputHook
+      and ModRuntime.call("render.output", function() return false end, {
+        canvas = source, width = w, height = h,
+        gameX = ox, gameY = oy,
+        gameWidth = 160 * scale, gameHeight = 144 * scale,
+        scale = scale, dpiX = dpi, dpiY = dpi,
+        generation = 2,
+      }) == true
+    if not outputHandled then
+      if fx then
+        GBCFX.present(source, self:pixelScale(w, h))
+      else
+        G.setColor(1, 1, 1, 1)
+        G.draw(source, 0, 0)
+        G.setShader()
+      end
     end
   end
   G.pop()

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/HostShell.lua

@@ -325,7 +325,8 @@ function HostShell.httpDownload(url, absPath, userAgent, accept, maxTime)
   if type(absPath) ~= "string" or absPath == "" then return nil, "missing path" end
   userAgent = userAgent or "gen1recomp"
   if HostShell.haveCurl() then
-    local cmd = ("curl -fsSL --connect-timeout 15 --max-time %d ")
+    local cmd = ("curl -fsSL --proto =http,https --proto-redir =http,https "
+      .. "--connect-timeout 15 --max-time %d ")
       :format(tonumber(maxTime) or 300)
       .. "-H " .. HostShell.quote("User-Agent: " .. userAgent) .. " "
     if accept then
@@ -370,7 +371,8 @@ function HostShell.httpGet(url, userAgent, accept, maxTime)
     -- BODY, and on the two services this talks to that body is the whole
     -- diagnosis: GitHub's 403 says "API rate limit exceeded for <ip>", which
     -- tells a user to wait rather than to go hunting for a broken index.
-    local cmd = ("curl -sSL --connect-timeout 10 --max-time %d ")
+    local cmd = ("curl -sSL --proto =http,https --proto-redir =http,https "
+      .. "--connect-timeout 10 --max-time %d ")
       :format(tonumber(maxTime) or 40)
       .. "-H " .. HostShell.quote("User-Agent: " .. userAgent) .. " "
     if accept then
@@ -415,4 +417,88 @@ function HostShell.httpGet(url, userAgent, accept, maxTime)
   return body
 end
 
+-- POST returning success/failure.  Strictly one-way: the response body is
+-- discarded, only the HTTP status class is surfaced (postLog callers never
+-- trust the reply).  curl --data-binary reads the payload from a pipe, so a
+-- large body never lands in the command line; the Android bridge has no POST
+-- transport, and httpPost reports that instead of half-working through
+-- httpDownload (a GET round-trip to a POST endpoint would be a lie).
+function HostShell.httpPost(url, body, contentType, userAgent, maxTime)
+  if type(url) ~= "string" or url == "" then return nil, "missing url" end
+  if type(body) ~= "string" then return nil, "missing body" end
+  userAgent = userAgent or "gen1recomp"
+  if HostShell.haveCurl() then
+    -- io.popen is one-way on Lua/LuaJIT: its mode is "r" or "w", never
+    -- "rw".  Stage the request body so the response can stay on a read
+    -- pipe.  The staging directory comes from the OS temp contract, never
+    -- tmpnam(): the CRT's tmpnam() can return a name relative to the process
+    -- working directory, and a game installed under Program Files has no
+    -- writable CWD -- io.open would fail before curl ever runs and postLog
+    -- would silently drop the send.  TEMP/TMP are per-user writable on
+    -- Windows; TMPDIR (with /tmp fallback) covers POSIX.  No love.filesystem:
+    -- the sandbox-era transport stays on plain io/os.
+    local function stagingPath()
+      local dir = os.getenv("TEMP") or os.getenv("TMP")
+      if not dir or dir == "" then dir = os.getenv("TMPDIR") or "/tmp" end
+      local sep = dir:find("\\") and "\\" or "/"
+      return dir .. sep .. ("gen1recomp-post-%d.tmp"):format(
+        (os.time() % 1000000) * 100 + math.random(0, 99))
+    end
+    local bodyPath = stagingPath()
+    local bodyFile, bodyOpenErr = io.open(bodyPath, "wb")
+    if not bodyFile then
+      pcall(os.remove, bodyPath)
+      return nil, "could not create request body: " .. tostring(bodyOpenErr)
+    end
+    local bodyOk, bodyErr = pcall(function()
+      assert(bodyFile:write(body))
+      assert(bodyFile:close())
+    end)
+    if not bodyOk then
+      pcall(function() bodyFile:close() end)
+      pcall(os.remove, bodyPath)
+      return nil, "could not write body: " .. tostring(bodyErr)
+    end
+
+    -- --data-binary @<file> keeps the payload out of argv (command-line length
+    -- limits on Windows) and preserves every byte including trailing
+    -- newlines.  The body is staged above because io.popen cannot be opened
+    -- for both writing and reading.  No -f, matching httpGet: the response
+    -- body is discarded anyway, and curl's stderr carries the diagnosis.
+    local cmd = ("curl -sSL --proto =http,https --proto-redir =http,https "
+      .. "--connect-timeout 10 --max-time %d ")
+      :format(tonumber(maxTime) or 40)
+      .. "-X POST "
+      .. "-H " .. HostShell.quote("User-Agent: " .. userAgent) .. " "
+    if contentType then
+      cmd = cmd .. "-H " .. HostShell.quote("Content-Type: " .. contentType) .. " "
+    end
+    cmd = cmd .. "-H " .. HostShell.quote("Content-Length: " .. tostring(#body)) .. " "
+      .. "--data-binary " .. HostShell.quote("@" .. bodyPath) .. " "
+      .. "-w " .. HostShell.quote(HTTP_MARK_FMT) .. " "
+      .. HostShell.quote(url) .. " 2>&1"
+    local pipe = HostShell.popen(cmd)
+    if not pipe then
+      pcall(os.remove, bodyPath)
+      return nil, "could not run curl"
+    end
+    local readOk, out = pcall(function() return pipe:read("*a") end)
+    HostShell.pclose(pipe)
+    pcall(os.remove, bodyPath)
+    if not readOk then
+      return nil, fetchError(url, nil, tostring(out))
+    end
+    local _, status, noise = splitCurlOutput(out)
+    if not status then return nil, fetchError(url, nil, noise) end
+    if status < 200 or status >= 300 then
+      return nil, fetchError(url, status, "log post rejected")
+    end
+    return true
+  end
+  if not haveBridge() then
+    return nil, "no network transport on this platform"
+  end
+  return nil, "no POST transport on this platform"
+end
+
 return HostShell

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).
@@ -779,9 +832,41 @@ local function tryMigrateLegacy(version, fs)
   return id
 end
 
+-- Scan the filesystem for orphaned slot files under saves/<version>/ when options.lua
+-- has no registered slots for this version (e.g. options.lua was reset or lost).
+local function scanDiskSlots(version, fs)
+  if not fs then return nil end
+  local dir = "saves/" .. version
+  local slots = {}
+  if fs.getDirectoryItems and fs.getInfo and fs.getInfo(dir) then
+    local items = pcall(fs.getDirectoryItems, dir) and fs.getDirectoryItems(dir) or {}
+    local numbers = {}
+    for _, item in ipairs(items) do
+      local slotId = item:match("^(slot%d+)%.lua$")
+      if slotId then
+        local n = tonumber(slotId:match("%d+"))
+        table.insert(numbers, { id = slotId, num = n or 0 })
+      end
+    end
+    table.sort(numbers, function(a, b) return a.num < b.num end)
+    for _, item in ipairs(numbers) do
+      table.insert(slots, item.id)
+    end
+  else
+    for i = 1, 30 do
+      local slotId = "slot" .. i
+      local path = dir .. "/" .. slotId .. ".lua"
+      if fs.getInfo and fs.getInfo(path) then
+        table.insert(slots, slotId)
+      end
+    end
+  end
+  return #slots > 0 and slots or nil
+end
+
 -- Resolve (once per version per process) which slot in-game saves use: an
 -- existing registry wins; otherwise a lazy legacy migration may create
--- slot1; otherwise false, meaning the flat legacy path.
+-- slot1; otherwise auto-recover disk slots; otherwise false (flat legacy path).
 local function ensureVersionSlots(version, fs)
   if slotsChecked[version] then return end
   slotsChecked[version] = true
@@ -795,7 +880,22 @@ local function ensureVersionSlots(version, fs)
     activeSlotCache[version] = reg.active or reg.list[1]
     return
   end
-  activeSlotCache[version] = tryMigrateLegacy(version, fs) or false
+  local migrated = tryMigrateLegacy(version, fs)
+  if migrated then
+    activeSlotCache[version] = migrated
+    return
+  end
+  -- Auto-recovery: if options.lua lost its slot registry, scan disk for orphaned slot files
+  local recovered = scanDiskSlots(version, fs)
+  if recovered and #recovered > 0 then
+    opts.saveSlots = opts.saveSlots or {}
+    opts.saveSlots[version] = { list = recovered, active = recovered[1] }
+    SaveData.saveOptions(opts, fs)
+    activeSlotCache[version] = recovered[1]
+    Logger.info("auto-recovered %d save slot(s) for %s from disk", #recovered, version)
+    return
+  end
+  activeSlotCache[version] = false
 end
 
 -- (body for the forward-declared saveNames.)  Resolves the ACTIVE slot for
@@ -818,9 +918,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 +948,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 +1934,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 +1946,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

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

@@ -764,9 +764,14 @@ end
 function Save.summary(save)
   if type(save) ~= "table" then return nil end
   local badges = 0
+  -- Continue_DisplayBadgeCount counts TWO bytes, wJohtoBadges then wKantoBadges
+  -- (engine/menus/intro_menu.asm:461-469).
   for _, has in pairs(save.player and save.player.badges or {}) do
     if has then badges = badges + 1 end
   end
+  for _, has in pairs(save.player and save.player.kantoBadges or {}) do
+    if has then badges = badges + 1 end
+  end
   local caught = 0
   for _, has in pairs(save.pokedex and save.pokedex.caught or {}) do
     if has then caught = caught + 1 end

src/import/CacheFs.lua

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

src/import/ExtractThread.lua

@@ -0,0 +1,50 @@
+-- ROM extraction, off the main thread.  The extractor's require closure needs
+-- only love.filesystem, love.image, love.math and love.system, none of which
+-- are main-thread-only, so it runs here instead of as a coroutine the frame
+-- loop resumed for 8ms out of every 16.7ms.
+--
+-- The caller clears the stale cache and writes the completion marker itself;
+-- this only fills the tree between those two steps, so the "marker appears
+-- last" order isReady() depends on stays on one thread.
+
+require("love.filesystem")
+require("love.image")
+require("love.math")
+require("love.system")
+require("love.timer")
+
+local version, prefix, romData, progressName, resultName = ...
+
+local progressChannel = love.thread.getChannel(progressName)
+local resultChannel = love.thread.getChannel(resultName)
+
+-- RomExtractor:tick fires per item, thousands of times per import; a channel
+-- push each would cost more than the work it reports.
+local PROGRESS_HZ = 20
+
+local ok, err = pcall(function()
+  local CacheFs = require("src.import.CacheFs")
+  CacheFs.prefix = prefix
+
+  local manifest = require("src.import.RomManifest").decode(version)
+  local RomExtractor = version == "gold"
+    and require("src.import.RomExtractorGen2")
+    or require("src.import.RomExtractor")
+
+  local lastPush, lastStage = 0, nil
+  local extractor = RomExtractor.new(romData, manifest,
+    function(progress, total, stage, current, stageTotal)
+      local now = love.timer.getTime()
+      -- Stage changes always go through, or the caption goes stale.
+      if stage ~= lastStage or now - lastPush >= 1 / PROGRESS_HZ then
+        lastPush, lastStage = now, stage
+        progressChannel:push({
+          progress = progress, total = total, stage = stage,
+          current = current, stageTotal = stageTotal,
+        })
+      end
+    end)
+  extractor:run()
+end)
+
+resultChannel:push({ ok = ok, error = ok and nil or tostring(err) })

src/import/LauncherSettings.lua

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

src/import/RomImporter.lua

@@ -316,18 +316,6 @@ function RomImporter.isReady(version)
 end
 
 -- Load the import manifest for a version and confirm it matches that ROM.
-local function decodeManifest(version)
-  local path = GameVersion.info(version).manifest
-  local raw, readError = love.filesystem.read(path)
-  if not raw then error("ROM import metadata is missing: " .. tostring(readError)) end
-  local Json = require("src.link.Json")
-  local manifest, decodeError = Json.decode(raw)
-  if not manifest then error("ROM import metadata is invalid: " .. tostring(decodeError)) end
-  assert(manifest.romSha1 == GameVersion.info(version).sha1,
-    "ROM import metadata version mismatch")
-  return manifest
-end
-
 local function sha1(data)
   local digest = love.data.hash("sha1", data)
   if type(digest) == "userdata" and digest.getString then
@@ -344,6 +332,14 @@ local function readExternalPath(path)
   return data
 end
 
+local function externalFileSize(path)
+  local file = io.open(path, "rb")
+  if not file then return nil end
+  local size = file:seek("end")
+  file:close()
+  return size
+end
+
 local function readDroppedFile(file)
   local ok, openError = file:open("r")
   if not ok then return nil, openError end
@@ -981,6 +977,25 @@ local function findPendingSav(preferAny, skip)
   return nil
 end
 
+local function pickerHasKind(kind)
+  local fn = love.system.pickFileKinds
+  if type(fn) ~= "function" then return false end
+  local ok, kinds = pcall(fn)
+  if not ok or type(kinds) ~= "string" then return false end
+  for token in kinds:gmatch("[^,%s]+") do
+    if token == kind then return true end
+  end
+  return false
+end
+
+local function findPendingRequiredImport()
+  local names = { "picked_required_import.bin", "picked_stadium.z64" }
+  for _, name in ipairs(names) do
+    if love.filesystem.getInfo(name, "file") then return name end
+  end
+  return nil
+end
+
 -- Retire an Android pick once it has been through the installer / importer,
 -- whether or not it worked: a pick left on disk wins the scans above forever,
 -- so the next tap re-runs the same failing file and the picker never reopens
@@ -1112,6 +1127,39 @@ local function chooseSav()
   return nil
 end
 
+-- Generic user-supplied dependency picker. Keep the native prompt entirely
+-- engine-owned: manifest labels are untrusted and must never enter shell
+-- command templates. The LÖVE modal already shows the specific import name.
+local function chooseRequiredFile()
+  local prompt = shellSafe(Strings("Choose required mod file"))
+  local platform = love.system.getOS()
+  if platform == "OS X" then
+    return commandOutput(
+      ([[osascript -e 'POSIX path of (choose file with prompt "%s")' 2>/dev/null]])
+        :format(prompt))
+  elseif platform == "Windows" then
+    local script = table.concat({
+      "Add-Type -AssemblyName System.Windows.Forms;",
+      "$d=New-Object System.Windows.Forms.OpenFileDialog;",
+      "$d.Title='" .. prompt .. "';",
+      "$d.Filter='All files (*.*)|*.*';",
+      "if($d.ShowDialog() -eq 'OK'){",
+      "$t=Join-Path $env:TEMP 'pokeport_required_import.bin';",
+      "Copy-Item -LiteralPath $d.FileName -Destination $t -Force;",
+      "[Console]::OutputEncoding=[Text.Encoding]::UTF8;",
+      "[Console]::Write($t)}",
+    })
+    return commandOutput(
+      'powershell -NoProfile -STA -Command "' .. script .. '"')
+  elseif platform == "Linux" then
+    local path = commandOutput(
+      ([[zenity --file-selection --title="%s" 2>/dev/null]]):format(prompt))
+    if path then return path end
+    return commandOutput([[kdialog --getopenfilename "$HOME" 2>/dev/null]])
+  end
+  return nil
+end
+
 -- The self-updater only surfaces on the real distributed build: a fused,
 -- interactive launcher with no scripted-run override.  A dev / source checkout
 -- (unfused, where Boot.run already no-ops) or an autopilot / driver /
@@ -1228,9 +1276,11 @@ function RomImporter.new(onComplete, opts)
     saveNotice = {},
     -- MODS panel state (pass 3): mods is the cached LauncherMods.list() array
     -- (refreshed lazily on first draw and after any toggle/install/delete);
-    -- modScroll is the list scroll offset (px, clamped in draw); modNotice is
-    -- the last install/delete result { ok, text } shown as a line above the list.
-    mods = nil, modScroll = 0, modNotice = nil,
+    -- modScroll is the current paged list's inner scroll offset (px, clamped
+    -- in draw); modNotice is the last install/delete result { ok, text }.
+    -- requiredImportNotice stays inside the imported-files modal so validation
+    -- failures are visible beside the file picker that caused them.
+    mods = nil, modScroll = 0, modNotice = nil, requiredImportNotice = nil,
     -- Which game the MODS panel is answering for (a GameVersion id, nil =
     -- every game).  Rows resolve their enable-state and their "runs here"
     -- verdict against it (src/mods/ModTargets.lua).
@@ -1420,7 +1470,13 @@ function RomImporter:focus(f)
     local text = "Could not read the picked file. Reopen the picker and choose "
       .. "it with the Files (Documents) app, or copy it into: "
       .. love.filesystem.getSaveDirectory()
-    if pickError:find("picked_mod", 1, true) then
+    if pickError:find("picked_required_import", 1, true)
+        or pickError:find("picked_stadium", 1, true) then
+      self.modNotice = { ok = false, text = text }
+      self.pickerPendingKind = nil
+      self.pickerPendingModId = nil
+      self.pickerPendingImportId = nil
+    elseif pickError:find("picked_mod", 1, true) then
       self.modNotice = { ok = false, text = text }
     elseif pickError:find("picked_save", 1, true) then
       local version = self.androidPendingVersion or self:_savedropTarget()
@@ -1431,6 +1487,20 @@ function RomImporter:focus(f)
     end
     return
   end
+  local requiredName = findPendingRequiredImport()
+  if requiredName then
+    local modId, importId = self.pickerPendingModId, self.pickerPendingImportId
+    self.pickerPendingKind = nil
+    self.pickerPendingModId, self.pickerPendingImportId = nil, nil
+    local imported = modId and importId
+      and self:_importRequiredSource(modId, importId, requiredName)
+    consumePick(self, requiredName, requiredName, imported)
+    if not modId or not importId then
+      self.modNotice = { ok = false,
+        text = "A picked dependency file had no pending mod request and was discarded." }
+    end
+    return
+  end
   local modName = findPendingMod(false, self.pickSkip)
   if modName then
     self:_installMod(modName)
@@ -1470,6 +1540,8 @@ function RomImporter:setError(message, version)
   self.detail = tostring(message)
   self.progress = 0
   self.worker = nil
+  -- Dropping the job stops collection; the next import clears the channels.
+  self._extract = nil
   self.romData = nil
   -- A headless import has no launcher to read this off: POKEPORT_IMPORT_ONLY
   -- only ever quits from onComplete, so an import that fails here would sit in
@@ -1536,23 +1608,65 @@ function RomImporter:startData(data, displayName)
   self.detail = displayName or info.displayName
   self.progress = 0
   self.romData = data
-  self.worker = coroutine.create(function()
-    self.status = "Preparing private game data"
-    coroutine.yield()
-    -- Redirect every cache write to this version's subtree, then clear only
-    -- that version's previous cache from both homes (save directory and, for
-    -- a portable install, the game folder).  The other version is untouched.
-    local CacheFs = require("src.import.CacheFs")
-    local prefix = info.cachePrefix
-    CacheFs.prefix = prefix
+  self.status = "Preparing private game data"
+
+  -- Clear this version's previous cache from both homes before anything
+  -- writes.  Stays on the main thread so delete-then-fill-then-mark keeps one
+  -- owner; the prefix is restored at once because the worker sets its own.
+  local CacheFs = require("src.import.CacheFs")
+  local prefix = info.cachePrefix
+  local savedPrefix = CacheFs.prefix
+  CacheFs.prefix = prefix
+  local cleared, clearError = pcall(function()
     removeTree(prefix .. "data/generated")
     removeTree(prefix .. "assets/generated")
     love.filesystem.remove(prefix .. MARKER_PATH)
     CacheFs.removeTree("data/generated")
     CacheFs.removeTree("assets/generated")
     CacheFs.remove(MARKER_PATH)
+  end)
+  CacheFs.prefix = savedPrefix
+  if not cleared then
+    self:setError(tostring(clearError), version)
+    return
+  end
 
-    local manifest = decodeManifest(version)
+  if self:_startExtractThread(version, prefix, data, displayName) then return end
+  self:_startExtractCoroutine(version, info, prefix, displayName)
+end
+
+-- False when threads are unavailable, so the coroutine path still covers
+-- that host.  POKEPORT_NO_THREAD=1 forces it, which is the only way to
+-- exercise the fallback on a desktop.
+function RomImporter:_startExtractThread(version, prefix, data, displayName)
+  if os.getenv("POKEPORT_NO_THREAD") == "1" then return false end
+  if not (love.thread and love.thread.newThread) then return false end
+  local ok, thread = pcall(love.thread.newThread, "src/import/ExtractThread.lua")
+  if not ok or not thread then return false end
+  local progressName = "rom_import_progress"
+  local resultName = "rom_import_result"
+  love.thread.getChannel(progressName):clear()
+  love.thread.getChannel(resultName):clear()
+  local started = pcall(thread.start, thread, version, prefix, data,
+    progressName, resultName)
+  if not started then return false end
+  self._extract = {
+    thread = thread, version = version, prefix = prefix,
+    displayName = displayName,
+    progress = love.thread.getChannel(progressName),
+    result = love.thread.getChannel(resultName),
+  }
+  -- The worker owns the bytes now; drop ours so the 1-2 MiB string can go.
+  self.romData = nil
+  return true
+end
+
+function RomImporter:_startExtractCoroutine(version, info, prefix, displayName)
+  self.worker = coroutine.create(function()
+    coroutine.yield()
+    local CacheFs = require("src.import.CacheFs")
+    CacheFs.prefix = prefix
+    local manifest = require("src.import.RomManifest").decode(version)
     local RomExtractor = version == "gold"
       and require("src.import.RomExtractorGen2")
       or require("src.import.RomExtractor")
@@ -1565,47 +1679,93 @@ function RomImporter:startData(data, displayName)
         coroutine.yield()
       end)
     extractor:run()
+    CacheFs.prefix = ""   -- restore the default so later writes stay at the root
     self.romData = nil
     collectgarbage("collect")
-    -- Written last: the marker is what isReady() checks, so it must only
-    -- appear once every required file is in place.
-    local ok, writeError = CacheFs.write(MARKER_PATH, markerFor(version))
-    CacheFs.prefix = ""   -- restore the default so later writes stay at the root
-    if not ok then error("could not finish the private cache: " .. tostring(writeError)) end
-    self.ready[version] = true
-    self.returning[version] = false
-    self.romName[version] = (displayName
-      and (displayName:match("[^/\\]+$") or displayName)) or self.romName[version]
-    -- Android: drop the consumed save-dir .gb/.gbc (picked_rom.gb or a USB copy)
-    -- so the next Choose / focus cannot treat it as a fresh pending ROM.
-    if self.mobileFileBridge and type(displayName) == "string"
-        and not displayName:find("[/\\]") then
-      love.filesystem.remove(displayName)
-    end
-    self.importing = nil
-    self.workState = "complete"
-    self.completeVersion = version
-    self.status = "Ready"
-    -- NX launcher stays put: keep the imports/ cleanup hint instead of
-    -- overwriting it with a "Starting…" line that never boots from here.
-    if self.launcher and self.isNX and type(displayName) == "string" then
-      self.detail = Strings("%s imported. You may delete the copy from "
-        .. "imports/ when finished.", displayName)
-    else
-      self.detail = "Starting " .. info.displayName .. "..."
-    end
-    self.progress = 1
-    if self.launcher then
-      -- Stay on the launcher; the player presses Play to boot the new game.
-      return
-    end
-    self._handedOff = true
-    resetPointerCursor(self)
-    if self._flex then require("src.import.LauncherView").detach(self) end
-    if self.onComplete then self.onComplete(version) end
+    self:_completeImport(version, prefix, displayName)
   end)
 end
 
+-- Everything after the tree is filled, shared by both worker paths.  Raises
+-- on a failed marker write; the thread path calls it inside a pcall.
+function RomImporter:_completeImport(version, prefix, displayName)
+  local info = GameVersion.info(version)
+  local CacheFs = require("src.import.CacheFs")
+  -- Written last: the marker is what isReady() checks, so it must only
+  -- appear once every required file is in place.
+  local savedPrefix = CacheFs.prefix
+  CacheFs.prefix = prefix
+  local ok, writeError = CacheFs.write(MARKER_PATH, markerFor(version))
+  CacheFs.prefix = savedPrefix
+  if not ok then
+    error("could not finish the private cache: " .. tostring(writeError))
+  end
+  self.ready[version] = true
+  self.returning[version] = false
+  self.romName[version] = (displayName
+    and (displayName:match("[^/\\]+$") or displayName)) or self.romName[version]
+  -- Android: drop the consumed save-dir .gb/.gbc (picked_rom.gb or a USB copy)
+  -- so the next Choose / focus cannot treat it as a fresh pending ROM.
+  if self.mobileFileBridge and type(displayName) == "string"
+      and not displayName:find("[/\\]") then
+    love.filesystem.remove(displayName)
+  end
+  self.importing = nil
+  self.workState = "complete"
+  self.completeVersion = version
+  self.status = "Ready"
+  -- NX launcher stays put: keep the imports/ cleanup hint instead of
+  -- overwriting it with a "Starting…" line that never boots from here.
+  if self.launcher and self.isNX and type(displayName) == "string" then
+    self.detail = Strings("%s imported. You may delete the copy from "
+      .. "imports/ when finished.", displayName)
+  else
+    self.detail = "Starting " .. info.displayName .. "..."
+  end
+  self.progress = 1
+  if self.launcher then
+    -- Stay on the launcher; the player presses Play to boot the new game.
+    return
+  end
+  self._handedOff = true
+  resetPointerCursor(self)
+  if self._flex then require("src.import.LauncherView").detach(self) end
+  if self.onComplete then self.onComplete(version) end
+end
+
+-- Drain the worker's progress and finish when it reports done.  One
+-- non-blocking poll per frame, like the other _pump* collectors above.
+function RomImporter:_pumpExtract()
+  local job = self._extract
+  if not job then return end
+  local msg = job.progress:pop()
+  while msg do
+    self.status = msg.stage
+    self.progress = msg.progress / msg.total
+    self.stageCurrent = msg.current
+    self.stageTotal = msg.stageTotal
+    msg = job.progress:pop()
+  end
+  local res = job.result:pop()
+  if not res then
+    -- A thread that died before pushing a result would strand the loader.
+    local threadError = job.thread.getError and job.thread:getError()
+    if threadError then
+      self._extract = nil
+      self:setError(tostring(threadError), job.version)
+    end
+    return
+  end
+  self._extract = nil
+  if not res.ok then
+    self:setError(tostring(res.error), job.version)
+    return
+  end
+  local ok, err = pcall(self._completeImport, self, job.version, job.prefix,
+    job.displayName)
+  if not ok then self:setError(tostring(err), job.version) end
+end
+
 function RomImporter:startPath(path)
   if not path then return end
   local data, readError = readExternalPath(path)
@@ -1649,7 +1809,7 @@ end
 function RomImporter:_installMod(source)
   if self.workState == "working" then return end
   self.tab = "mods"
-  local ok, installed, res = pcall(function()
+  local ok, installed, res, manifest = pcall(function()
     local LauncherMods = require("src.mods.LauncherMods")
     return LauncherMods.installZip(source)
   end)
@@ -1661,6 +1821,17 @@ function RomImporter:_installMod(source)
   if installed then
     pcall(self._refreshMods, self)
     self.modNotice = { ok = true, text = "Installed " .. tostring(res) }
+    local LauncherMods = require("src.mods.LauncherMods")
+    local checkTarget = manifest
+    if not checkTarget and type(res) == "string" then
+      checkTarget = { id = res }
+    end
+    if checkTarget and LauncherMods.checkDependencies then
+      local depCheck = LauncherMods.checkDependencies(checkTarget)
+      if depCheck and depCheck.hasIssues then
+        self._modDepResolver = depCheck
+      end
+    end
   else
     self.modNotice = { ok = false, text = tostring(res) }
   end
@@ -1727,6 +1898,152 @@ function RomImporter:chooseMod()
   if path then self:_installMod(path) end
 end
 
+local function requiredManifest(self, modId)
+  for _, row in ipairs(self.mods or {}) do
+    if row.id == modId then return row.manifest, row end
+  end
+  return nil
+end
+
+local function requiredSpec(manifest, importId)
+  for _, candidate in ipairs(require("src.mods.RequiredImports").specs(manifest)) do
+    if candidate.id == importId then return candidate end
+  end
+  return nil
+end
+
+local function requiredImportNotice(self, modId, importId, text)
+  self.requiredImportNotice = {
+    modId = modId,
+    importId = importId,
+    text = tostring(text),
+  }
+end
+
+function RomImporter:_importRequiredData(modId, importId, data)
+  local manifest = requiredManifest(self, modId)
+  if not manifest then
+    self.modNotice = { ok = false, text = "Required import failed: mod not found." }
+    return nil
+  end
+  local ok, result = require("src.mods.RequiredImports")
+    .importData(manifest, importId, data)
+  if ok then
+    self.requiredImportNotice = nil
+    self.modNotice = { ok = true, text = "Imported " .. tostring(importId)
+      .. " for " .. tostring(manifest.name or manifest.id) .. "." }
+    self:_refreshMods()
+    return true
+  end
+  -- Keep validation feedback on the imported-files page.  A general Mods-page
+  -- notice is hidden by this modal and made MD5 failures especially easy to miss.
+  requiredImportNotice(self, modId, importId, result)
+  self.modNotice = nil
+  return nil
+end
+
+function RomImporter:_importRequiredSource(modId, importId, source)
+  local manifest = requiredManifest(self, modId)
+  local spec = manifest and requiredSpec(manifest, importId)
+  if not spec then
+    requiredImportNotice(self, modId, importId, "Import declaration was not found.")
+    self.modNotice = nil
+    return nil
+  end
+  local info = love.filesystem.getInfo(source, "file")
+  local size = info and info.size or externalFileSize(source)
+  local sizeErr = require("src.mods.RequiredImports").sizeError(spec, size, false)
+  if sizeErr then
+    requiredImportNotice(self, modId, importId, sizeErr)
+    self.modNotice = nil
+    return nil
+  end
+  local data = love.filesystem.read(source)
+  if not data then data = readExternalPath(source) end
+  if not data then
+    requiredImportNotice(self, modId, importId, "Could not read the selected file.")
+    self.modNotice = nil
+    return nil
+  end
+  return self:_importRequiredData(modId, importId, data)
+end
+
+function RomImporter:_removeRequiredImport(modId, importId)
+  local manifest = requiredManifest(self, modId)
+  if not manifest then return end
+  local ok, err = require("src.mods.RequiredImports").remove(manifest, importId)
+  if ok then
+    self.requiredImportNotice = nil
+    self.modNotice = { ok = true, text = "Deleted " .. tostring(importId) .. "." }
+    self:_refreshMods()
+  else
+    requiredImportNotice(self, modId, importId, err)
+    self.modNotice = nil
+  end
+end
+
+-- Select and validate one manifest-declared file.  NX has no host picker, so
+-- its equivalent is an engine-owned imports/baseroms inbox that can be filled
+-- over MTP; every other native/mobile picker lands on the same validation path.
+function RomImporter:chooseRequiredImport(modId, importId)
+  if self.workState == "working" then return end
+  local manifest = requiredManifest(self, modId)
+  if not manifest then return end
+  local spec = requiredSpec(manifest, importId)
+  if not spec then return end
+
+  if self.isNX then
+    local inbox = "imports/baseroms"
+    love.filesystem.createDirectory(inbox)
+    local lastError
+    for _, name in ipairs(love.filesystem.getDirectoryItems(inbox) or {}) do
+      if name:sub(1, 1) ~= "." then
+        local path = inbox .. "/" .. name
+        local info = love.filesystem.getInfo(path, "file")
+        local sizeErr = info and require("src.mods.RequiredImports")
+          .sizeError(spec, info.size, false)
+        local data = not sizeErr and love.filesystem.read(path) or nil
+        if data and self:_importRequiredData(modId, importId, data) then return end
+        if sizeErr then lastError = sizeErr
+        elseif self.requiredImportNotice
+            and self.requiredImportNotice.modId == modId
+            and self.requiredImportNotice.importId == importId then
+          lastError = self.requiredImportNotice.text
+        end
+      end
+    end
+    requiredImportNotice(self, modId, importId, lastError
+      or "No matching file in imports/baseroms/. Copy it there over MTP, then try again.")
+    self.modNotice = nil
+    return
+  end
+  if self.nativePicker then
+    if self.mobileFileBridge and not pickerHasKind("required_import") then
+      requiredImportNotice(self, modId, importId,
+        "This app build cannot pick required mod files yet. Update the app and try again.")
+      self.modNotice = nil
+      return
+    end
+    self.pickerPendingKind = "required_import"
+    self.pickerPendingModId = modId
+    self.pickerPendingImportId = importId
+    if not pickFile("required_import") then
+      self.pickerPendingKind = nil
+      self.pickerPendingModId = nil
+      self.pickerPendingImportId = nil
+      requiredImportNotice(self, modId, importId, "Could not open the file picker.")
+      self.modNotice = nil
+    elseif self.android then
+      self.pickPending = true
+      self.pickTimer = 0
+    end
+    return
+  end
+
+  local path = chooseRequiredFile()
+  if path then self:_importRequiredSource(modId, importId, path) end
+end
+
 -- Which game a dropped .sav imports into: a .sav has no version signature of
 -- its own, so it lands on the active game tab.  When a non-game tab (mods) is
 -- showing, default to red -- the always-present first game -- rather than
@@ -2034,7 +2351,8 @@ function RomImporter:_pollPickedFiles(dt)
   if not found then
     for _, name in ipairs(love.filesystem.getDirectoryItems("")) do
       local n = name:lower()
-      if n:match("%.gbc?$") or n == "picked_mod.zip" or n == "picked_save.sav" then
+      if n:match("%.gbc?$") or n == "picked_mod.zip" or n == "picked_save.sav"
+          or n == "picked_required_import.bin" or n == "picked_stadium.z64" then
         found = true
         break
       end
@@ -2048,6 +2366,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
@@ -2067,6 +2394,7 @@ function RomImporter:update(dt)
   self:_pumpFindThumbs()
   self:_pumpModCheck()
   self:_pumpModInstall()
+  self:_pumpExtract()
   -- Dev harness: POKEPORT_LAUNCHER_SHOT=/path.png resizes the window from
   -- POKEPORT_WIN=WxH, lets the view settle, then captures one frame and
   -- quits, so a scripted run can see the real launcher at any window shape
@@ -2154,7 +2482,12 @@ function RomImporter:update(dt)
       local version = self.pickerPendingVersion
       self.pickerPendingKind = nil
       self.pickerPendingVersion = nil
-      if kind == "mod" then
+      if kind == "required_import" then
+        local modId, importId = self.pickerPendingModId, self.pickerPendingImportId
+        self.pickerPendingModId, self.pickerPendingImportId = nil, nil
+        if modId and importId then self:_importRequiredSource(modId, importId, path) end
+        if Platform.isUWP() then os.remove(path) end
+      elseif kind == "mod" then
         self:_installMod(path)
         if Platform.isUWP() and self.modNotice and self.modNotice.ok then
           os.remove(path)
@@ -2176,7 +2509,10 @@ function RomImporter:update(dt)
         local version = self.pickerPendingVersion or self:_savedropTarget()
         self.pickerPendingKind = nil
         self.pickerPendingVersion = nil
-        if kind == "mod" then
+        if kind == "required_import" then
+          self.modNotice = { ok = false, text = errorText }
+          self.pickerPendingModId, self.pickerPendingImportId = nil, nil
+        elseif kind == "mod" then
           self.modNotice = { ok = false, text = errorText }
         elseif kind == "sav" then
           self.saveNotice[version] = { ok = false, text = errorText }
@@ -2336,6 +2672,20 @@ function RomImporter:_updatePadCursor(dt)
     local ny = self._padCursor.y + dy * speed * dt
     self._padCursor.x = math.max(ox, math.min(ox + w, nx))
     self._padCursor.y = math.max(oy, math.min(oy + h, ny))
+    -- Pushing INTO the top/bottom edge scrolls the page instead of stalling.
+    -- The cursor is clamped to the safe area above, so on a short window the
+    -- rows below the fold are unreachable on a stickless handheld: no mouse
+    -- wheel, no touchscreen, and no right stick to feed the existing wheel
+    -- path.  Only the OVERSHOOT scrolls -- parking the cursor at the edge does
+    -- nothing, it has to be actively pushed -- and this block only runs on pad
+    -- input, so a real mouse is unaffected.  /48 matches the pixels-per-notch
+    -- LauncherView.draw multiplies back out.
+    local overY = 0
+    if ny > oy + h then overY = ny - (oy + h)
+    elseif ny < oy then overY = ny - oy end
+    if overY ~= 0 and self._flex then
+      require("src.import.LauncherView").wheelmoved(self, 0, -overY / 48)
+    end
     -- Desktop: FlexLove polls the real mouse, so warp it with the pad pointer.
     -- NX: the getPosition bridge already returns pad coords — skip setPosition.
     if not self.isNX and love.mouse.setPosition then
@@ -2436,9 +2786,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
@@ -2652,11 +3008,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
@@ -2698,6 +3057,43 @@ function RomImporter:fileUrl(path)
 end
 
 function RomImporter:keypressed(key)
+  if self._profileSavePrompt then
+    if key == "backspace" then
+      self._profileSavePrompt.text = utf8Back(self._profileSavePrompt.text or "")
+    elseif key == "return" or key == "kpenter" then
+      local txt = self._profileSavePrompt and self._profileSavePrompt.text
+      if txt and txt ~= "" then
+        local LauncherMods = require("src.mods.LauncherMods")
+        LauncherMods.saveProfile(txt)
+        self._profileSavePrompt = nil
+        self:_disarmTextInput()
+        if self._refreshMods then self:_refreshMods() end
+      end
+    elseif key == "escape" then
+      self._profileSavePrompt = nil
+      self:_disarmTextInput()
+    end
+    return
+  end
+  if self._profileRenamePrompt then
+    if key == "backspace" then
+      self._profileRenamePrompt.text = utf8Back(self._profileRenamePrompt.text or "")
+    elseif key == "return" or key == "kpenter" then
+      local txt = self._profileRenamePrompt and self._profileRenamePrompt.text
+      local old = self._profileRenamePrompt and self._profileRenamePrompt.oldName
+      if txt and txt ~= "" and old then
+        local LauncherMods = require("src.mods.LauncherMods")
+        LauncherMods.renameProfile(old, txt)
+        self._profileRenamePrompt = nil
+        self:_disarmTextInput()
+        if self._refreshMods then self:_refreshMods() end
+      end
+    elseif key == "escape" then
+      self._profileRenamePrompt = nil
+      self:_disarmTextInput()
+    end
+    return
+  end
   if self._settingsText then
     if key == "backspace" then
       self._settingsText.text = utf8Back(self._settingsText.text)
@@ -2740,12 +3136,21 @@ function RomImporter:keypressed(key)
     return
   end
   if self._modConfirm or self._modVersions or self._modReleaseNotes
-      or self._findDetails then
+      or self._findDetails or self._appPatchNotes 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
       elseif self._modReleaseNotes then
         self._modReleaseNotes = nil
+      elseif self._appPatchNotes then
+        self._appPatchNotes = nil
       else
         self._modConfirm = nil
         self._modVersions = nil
@@ -2860,6 +3265,14 @@ function RomImporter:_commitRename()
 end
 
 function RomImporter:textinput(text)
+  if self._profileSavePrompt then
+    self._profileSavePrompt.text = utf8Cap((self._profileSavePrompt.text or "") .. text, MAX_SLOT_LABEL)
+    return
+  end
+  if self._profileRenamePrompt then
+    self._profileRenamePrompt.text = utf8Cap((self._profileRenamePrompt.text or "") .. text, MAX_SLOT_LABEL)
+    return
+  end
   if self._settingsText then
     local st = self._settingsText
     st.text = utf8Cap(st.text .. text, st.maxLen or MAX_SLOT_LABEL)
@@ -3054,15 +3467,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
@@ -3070,7 +3487,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 = {
@@ -3082,7 +3499,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
 
@@ -3342,6 +3759,76 @@ function RomImporter:_pumpModInstall()
   else
     self.modNotice = { ok = true, text = text }
   end
+  local LauncherMods = require("src.mods.LauncherMods")
+  local depCheck = LauncherMods.checkDependencies({ id = spec.modId })
+  if depCheck and depCheck.hasIssues then
+    self._modDepResolver = depCheck
+  end
+end
+
+-- Start an async pull for a single dependency
+function RomImporter:_startDepPull(dep)
+  if not dep or not dep.github then return end
+  self._depPullState = self._depPullState or {}
+  local hFetch = require("src.mods.ModUpdate").beginFetchReleases(dep.github, dep.id, { force = true })
+  self._depPullState[dep.id] = {
+    dep = dep,
+    stage = "fetching",
+    fetchHandle = hFetch,
+  }
+end
+
+-- Pump all in-flight dependency pulls
+function RomImporter:_pumpDepPulls()
+  if not self._depPullState then return end
+  local ModUpdate = require("src.mods.ModUpdate")
+  local LauncherMods = require("src.mods.LauncherMods")
+
+  for depId, state in pairs(self._depPullState) do
+    if state.stage == "fetching" then
+      local done, releases, err = ModUpdate.pumpFetchReleases(state.fetchHandle)
+      if done then
+        if err or not releases or #releases == 0 then
+          state.stage = "error"
+          state.err = err or "No downloadable releases found on GitHub"
+        else
+          local rel = releases[1]
+          if not rel or not rel.zip or not rel.zip.url then
+            state.stage = "error"
+            state.err = "Latest release has no downloadable .zip asset"
+          else
+            local tmpName = ("dep_%s_%s.zip"):format(depId, tostring(rel.version or os.time()))
+            state.dlHandle = ModUpdate.beginDownloadZip(rel.zip.url, tmpName, rel.zip.size)
+            state.stage = "downloading"
+            state.targetVersion = rel.version
+          end
+        end
+      end
+    elseif state.stage == "downloading" then
+      local done, localPath, err, progress = ModUpdate.pumpDownloadZip(state.dlHandle)
+      state.progress = progress
+      if done then
+        if err or not localPath then
+          state.stage = "error"
+          state.err = err or "Download failed"
+        else
+          state.stage = "installing"
+          local okInst, versionRes = LauncherMods.installDownloadedZip(depId, localPath, state.targetVersion)
+          if okInst then
+            state.stage = "done"
+            pcall(self._refreshMods, self)
+            if self._modDepResolver and self._modDepResolver.targetMod then
+              local updated = LauncherMods.checkDependencies(self._modDepResolver.targetMod)
+              self._modDepResolver = updated
+            end
+          else
+            state.stage = "error"
+            state.err = tostring(versionRes or "Installation failed")
+          end
+        end
+      end
+    end
+  end
 end
 
 function RomImporter:_confirmModUpdate(modId, release)
@@ -3682,11 +4169,19 @@ end
 
 -- Turn finished thumbnail downloads into images.  Called from update(), so
 -- love.graphics.newImage runs on the render thread where it belongs.
+-- love.graphics.newImage decodes the PNG and uploads it, both on the render
+-- thread.  A page's worth of thumbnails landing in the same frame did that
+-- many times back to back and dropped the frame, so only this many are
+-- decoded per pass; the rest keep their spinner one frame longer.
+local THUMB_DECODES_PER_FRAME = 2
+
 function RomImporter:_pumpFindThumbs()
   local pending = self._findThumbFetch
   if not pending then return end
   local Fetch = require("src.net.Fetch")
+  local decoded = 0
   for id, item in pairs(pending) do
+    if decoded >= THUMB_DECODES_PER_FRAME then break end
     local st = Fetch.poll(item.job)
     if st.status ~= "pending" then
       Fetch.release(item.job)
@@ -3695,6 +4190,7 @@ function RomImporter:_pumpFindThumbs()
       if st.status == "ok" and st.path then
         local ok, img = pcall(love.graphics.newImage, st.path)
         image = ok and img or nil
+        decoded = decoded + 1
       end
       self._findThumbs = self._findThumbs or {}
       self._findThumbs[id] = image or false
@@ -3711,14 +4207,21 @@ end
 -- entry per frame so opening the tab cannot stall for the whole listing.
 -- The result is memoized per id for the session; a repo with no releases
 -- or a failed fetch resolves to an empty table so it is tried once.
-function RomImporter:_findStats(entry)
+-- PURE read: whatever is already known for a row, or nil.  Resolving a
+-- feed-published stat or a repo-less entry is memoization, not network, so it
+-- stays here; nothing in this function can start a fetch.  That matters
+-- because the sort comparator calls it for EVERY entry -- when queueing lived
+-- in here, sorting a 500-mod index by Popularity queued 500 GitHub requests
+-- on the first frame, blew the hourly rate limit, and the failures then
+-- re-queued together every 60s for as long as the tab was open.
+function RomImporter:_findStatsCached(entry)
   self._findStatsCache = self._findStatsCache or {}
   local cached = self._findStatsCache[entry.id]
   if cached then
     if cached.done or (cached.retryAt and os.time() < cached.retryAt) then
       return cached
     end
-    self._findStatsCache[entry.id] = nil  -- retry window open, refetch
+    return nil   -- retry window open; _requestFindStats decides what to do
   end
   if entry.downloads ~= nil or entry.first_release or entry.last_release then
     cached = { total = entry.downloads, first = entry.first_release,
@@ -3731,22 +4234,54 @@ function RomImporter:_findStats(entry)
     self._findStatsCache[entry.id] = cached
     return cached
   end
-  -- ASYNC (was a blocking fetch, one row per frame).  "One per frame" bounded
-  -- how many stalls happened at once, not how long each one lasted: every
-  -- frame that started a fetch blocked for the whole round trip, so scrolling
-  -- a listing juddered once per row.  Rows now queue a handle and fill in
-  -- when it lands; until then the row simply has no stats line.
-  self._findStatsPending = self._findStatsPending or {}
-  if not self._findStatsPending[entry.id] then
-    local ModUpdate = require("src.mods.ModUpdate")
-    self._findStatsPending[entry.id] = {
-      id = entry.id,
-      h = ModUpdate.beginFetchReleases(entry.github, entry.id, {}),
-    }
-  end
   return nil
 end
 
+-- Queue one row's release fetch.  Only rows actually on the page call this --
+-- the rule _findThumb already follows -- so the fan-out is a page, not the
+-- whole index.
+function RomImporter:_requestFindStats(entry)
+  if self:_findStatsCached(entry) then return end
+  if not entry.github or entry.github == "" then return end
+  local cached = self._findStatsCache[entry.id]
+  if cached then
+    if cached.retryAt and os.time() >= cached.retryAt then
+      self._findStatsCache[entry.id] = nil   -- retry window open, refetch
+    else
+      return
+    end
+  end
+  self._findStatsPending = self._findStatsPending or {}
+  if self._findStatsPending[entry.id] then return end
+  local ModUpdate = require("src.mods.ModUpdate")
+  self._findStatsPending[entry.id] = {
+    id = entry.id,
+    h = ModUpdate.beginFetchReleases(entry.github, entry.id, {}),
+  }
+end
+
+-- Request-and-read, for a row that is being drawn and for the detail modal.
+function RomImporter:_findStats(entry)
+  self:_requestFindStats(entry)
+  return self:_findStatsCached(entry)
+end
+
+-- How many rows are still waiting on a release check, for the panel's
+-- progress line.
+function RomImporter:_findStatsPendingCount()
+  local n = 0
+  for _ in pairs(self._findStatsPending or {}) do n = n + 1 end
+  return n
+end
+
+function RomImporter:_findStatsPendingFor(id)
+  return (self._findStatsPending and self._findStatsPending[id]) ~= nil
+end
+
+function RomImporter:_findThumbPending(id)
+  return (self._findThumbFetch and self._findThumbFetch[id]) ~= nil
+end
+
 -- Drive in-flight FIND MODS stats lookups.  Called from update().
 function RomImporter:_pumpFindStats()
   local pending = self._findStatsPending

src/import/RomManifest.lua

@@ -0,0 +1,25 @@
+-- The per-version import metadata (symbol table + ROM hash) that drives
+-- RomExtractor.  Split out of RomImporter so the extraction worker thread can
+-- decode it itself: shipping the decoded table across a love.thread channel
+-- would deep-copy every symbol for nothing.
+
+local GameVersion = require("src.core.GameVersion")
+
+local RomManifest = {}
+
+function RomManifest.decode(version)
+  local info = GameVersion.info(version)
+  local raw, readError = love.filesystem.read(info.manifest)
+  if not raw then
+    error("ROM import metadata is missing: " .. tostring(readError))
+  end
+  local Json = require("src.link.Json")
+  local manifest, decodeError = Json.decode(raw)
+  if not manifest then
+    error("ROM import metadata is invalid: " .. tostring(decodeError))
+  end
+  assert(manifest.romSha1 == info.sha1, "ROM import metadata version mismatch")
+  return manifest
+end
+
+return RomManifest

src/inventory/ItemEffects.lua

@@ -83,6 +83,12 @@ function ItemEffects.healsHP(id)
       or id == "REVIVE" or id == "MAX_REVIVE"
 end
 
+function ItemEffects.isBattleMedicine(id)
+  return HEAL_AMOUNT[id] ~= nil or STATUS_HEAL[id] ~= nil
+      or id == "MAX_POTION" or id == "FULL_RESTORE"
+      or id == "REVIVE" or id == "MAX_REVIVE"
+end
+
 -- Does this item need a party-member target?
 -- 'data' is optional for compat purposes; targeting falls back to itemDef/vanilla detection
 function ItemEffects.needsTarget(id, itemDef, data)
@@ -210,6 +216,17 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
   -- (ItemUsePokeFlute, engine/items/item_effects.asm); never consumed.
   if itemId == "POKE_FLUTE" then
     if not battle then
+      if ow and ow.map and ow.map.id == "PEWTER_POKECENTER"
+          and ow.pikachuPewterSleepScene then
+        local Follower = require("src.world.PikachuFollower")
+        local pika = Follower.current(ow)
+        local player = ow.player
+        if pika and player
+            and math.abs(pika.cellX - player.cellX) + math.abs(pika.cellY - player.cellY) == 1 then
+          return "flute_wake_pikachu", { romText(data, "_PlayedFluteHadEffectText",
+            "{PLAYER} played the\nPOKé FLUTE.") }
+        end
+      end
       -- standing next to a not-yet-beaten Snorlax: this is the ONLY way
       -- Snorlax wakes -- using the flute from the item-use menu, never
       -- just talking to it with the flute in the bag (see

src/link/LinkBattle.lua

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

src/link/LinkState.lua

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

src/mods/AssetTransform.lua

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

src/mods/Gen2Compat.lua

@@ -736,8 +736,9 @@ COVERAGE["src.pokemon.Boxes"] = {
 
 COVERAGE["src.world.WorldAPI"] = {
   kind = "alias", target = "src.world.gen2.WorldAPI",
-  backed = "new __index overworld current warpTo toggleObject replaceBlock "
-    .. "spawnNpc removeNpc npc queueScript invalidateMap",
+  backed = "new __index overworld current mapOverview warpTo toggleObject replaceBlock "
+    .. "spawnNpc removeNpc npc queueScript invalidateMap "
+    .. "availableFieldActions useFieldAction",
   warned = "setFlag getFlag",
   absent = "",
   notes = {
@@ -1797,7 +1798,8 @@ local function buildBattleState()
     "throwBall", "ballChain", "tossAnimFor", "ballFlicker", "ballMissMessage",
     "storeCaughtMon", "safariAction", "safariEnemyTurn", "drawBallRow",
     "drawClassic", "isWideBattleLayout", "wideLayout", "bgMode", "uiSize",
-    "sgbPalettes", "trainerPalette", "trainerPicPath", "invalidate",
+    "sgbPalettes", "trainerPalette", "trainerPicPath", "trainerTrueColor",
+    "trainerSprite", "invalidate",
     "imageBattleScale", "resolveBattleScale", "backPlacement",
     "frontPlacement", "StatBox", "enter", "exit",
   }) do
@@ -1884,7 +1886,8 @@ COVERAGE["src.battle.BattleState"] = {
   absent = "newWild newTrainer makeSafari makeGhost makeBattler resolveTurn "
     .. "computeDamage catchAttempt runRoll enter exit sgbPalettes "
     .. "isWideBattleLayout wideLayout bgMode uiSize letterboxWhite "
-    .. "holdsUIAnchors BG_WORLD_DIM trainerPalette trainerPicPath invalidate "
+    .. "holdsUIAnchors BG_WORLD_DIM trainerPalette trainerPicPath "
+    .. "trainerTrueColor trainerSprite invalidate "
     .. "backPlacement frontPlacement StatBox drawClassic drawBallRow "
     .. "safariAction safariEnemyTurn throwBall storeCaughtMon field ruleset "
     .. "rng oppClass partyIndex aiUses introText dead",

src/mods/Job.lua

@@ -0,0 +1,209 @@
+-- Background compute for sandboxed mods, behind the "background" permission.
+--
+-- mod.fetch covers work that is waiting on a server.  This covers work that is
+-- waiting on the CPU: a mod hands over a script from its own folder plus a
+-- table of plain data, and gets the return value back through the same
+-- handle/poll/release shape mod.fetch uses.
+--
+-- The worker (src/mods/job_worker.lua) builds the SAME Sandbox.envFor
+-- environment the main thread does before it loads the mod's chunk, so this
+-- is not the love.thread hole reopened: the mod's code still cannot see
+-- io, os, debug, ffi, package or love.filesystem, and require is refused
+-- outright inside a job.
+--
+-- One thread per job rather than a pool.  A pooled state would carry one
+-- mod's globals into the next mod's job, and resetting it properly is the
+-- same work as making a new one.
+
+local SafePath = require("src.mods.SafePath")
+
+local Job = {}
+
+Job.MAX_INFLIGHT = 2       -- per mod
+Job.MAX_GLOBAL = 4         -- across all mods, so jobs cannot eat every core
+Job.DEFAULT_SECONDS = 5
+Job.MAX_SECONDS = 30
+-- Depth cap on the data crossing the channel.  A cycle is caught by the seen
+-- set; this catches the merely absurd.
+Job.MAX_DEPTH = 16
+
+local nextId = 0
+local liveGlobal = 0
+
+-- Only plain data crosses a thread boundary: a function or userdata cannot be
+-- serialised, and letting one through would fail deep inside LÖVE instead of
+-- at the call the mod made.
+local function plain(value, depth, seen)
+  local t = type(value)
+  if t == "nil" or t == "boolean" or t == "number" or t == "string" then
+    return value
+  end
+  if t ~= "table" then
+    return nil, ("a job cannot carry a %s, only plain data"):format(t)
+  end
+  depth = (depth or 0) + 1
+  if depth > Job.MAX_DEPTH then
+    return nil, "a job's data is nested too deeply"
+  end
+  seen = seen or {}
+  if seen[value] then return nil, "a job cannot carry a cycle" end
+  seen[value] = true
+  local out = {}
+  for k, v in pairs(value) do
+    local kt = type(k)
+    if kt ~= "string" and kt ~= "number" then
+      return nil, ("a job cannot carry a %s key"):format(kt)
+    end
+    local copied, err = plain(v, depth, seen)
+    if err then return nil, err end
+    out[k] = copied
+  end
+  seen[value] = nil
+  return out
+end
+Job.plain = plain
+
+function Job.available()
+  return (love and love.thread and love.thread.newThread) ~= nil
+end
+
+local function bucket(loader, modId)
+  loader.jobs = loader.jobs or {}
+  local b = loader.jobs[modId]
+  if not b then b = {}; loader.jobs[modId] = b end
+  return b
+end
+
+local function inflight(b)
+  local n = 0
+  for _, job in pairs(b) do
+    if job.status == "pending" then n = n + 1 end
+  end
+  return n
+end
+
+-- `script` is relative to the mod's own folder, and goes through the same
+-- SafePath rules mod:read does -- a job is not a way to name a path.
+-- Argument checks come BEFORE the host check: a bad path or an unserialisable
+-- argument is the mod author's bug and should read the same on every machine,
+-- not be masked into "unavailable" on a build without threads.
+function Job.run(loader, modId, modPath, script, arg, opts)
+  if type(script) ~= "string" or script == "" then
+    return nil, "a job needs a script path inside your mod"
+  end
+  -- SafePath.require raises rather than returning, so the mod's bad path
+  -- comes back as a value here instead of unwinding its caller.
+  local okPath, safe = pcall(SafePath.join, modPath, script, "a job script")
+  if not okPath then return nil, tostring(safe) end
+  local payload, dataErr = plain(arg)
+  if dataErr then return nil, dataErr end
+  if not Job.available() then return nil, "background jobs are unavailable" end
+
+  local b = bucket(loader, modId)
+  if inflight(b) >= Job.MAX_INFLIGHT then
+    return nil, ("too many jobs in flight (limit %d); poll and release the "
+      .. "ones you have"):format(Job.MAX_INFLIGHT)
+  end
+  if liveGlobal >= Job.MAX_GLOBAL then
+    return nil, "the machine is already running as many jobs as it will"
+  end
+
+  opts = type(opts) == "table" and opts or {}
+  local seconds = tonumber(opts.maxSeconds) or Job.DEFAULT_SECONDS
+  if seconds > Job.MAX_SECONDS then seconds = Job.MAX_SECONDS end
+  if seconds < 1 then seconds = 1 end
+
+  nextId = nextId + 1
+  local argName = "modjob_arg_" .. nextId
+  local resultName = "modjob_result_" .. nextId
+  local argCh = love.thread.getChannel(argName)
+  local resCh = love.thread.getChannel(resultName)
+  argCh:clear()
+  resCh:clear()
+  argCh:push(payload == nil and false or payload)
+
+  local okNew, thread = pcall(love.thread.newThread, "src/mods/job_worker.lua")
+  if not okNew or not thread then return nil, "could not start a job thread" end
+  local Json = require("src.link.Json")
+  local permissions = select(2, pcall(Json.encode,
+    loader.mods and loader.mods[modId]
+      and loader.mods[modId].manifest.permissionSet or {})) or "{}"
+  local started = pcall(thread.start, thread, modId, safe, argName, resultName,
+    permissions)
+  if not started then return nil, "could not start a job thread" end
+
+  liveGlobal = liveGlobal + 1
+  local handle = {}
+  b[handle] = { thread = thread, resultCh = resCh, status = "pending",
+                deadline = love.timer.getTime() + seconds, seconds = seconds }
+  return handle
+end
+
+local function settle(job, status, value, err)
+  if job.status == "pending" then liveGlobal = math.max(0, liveGlobal - 1) end
+  job.status, job.value, job.err = status, value, err
+end
+
+function Job.poll(loader, modId, handle)
+  local job = bucket(loader, modId)[handle]
+  if not job then return { status = "error", err = "unknown job" } end
+  if job.status == "pending" then
+    local msg = job.resultCh:pop()
+    if msg then
+      if msg.ok then settle(job, "ok", msg.result)
+      else settle(job, "error", nil, msg.err) end
+    else
+      -- A worker that died before pushing anything (an error outside its own
+      -- pcall) would otherwise leave the mod polling forever.
+      local threadErr = job.thread.getError and job.thread:getError()
+      if threadErr then
+        settle(job, "error", nil, tostring(threadErr))
+      elseif love.timer.getTime() > job.deadline then
+        -- The budget bounds how long the MOD waits, not how long the work
+        -- runs: there is no way to stop a LÖVE thread, and every in-worker
+        -- attempt made things worse (see job_worker.lua).  A job that
+        -- overruns is reported here and its result dropped if it ever lands.
+        settle(job, "error", nil, ("job exceeded its %gs budget")
+          :format(job.seconds))
+      end
+    end
+  end
+  if job.status == "ok" then
+    -- A copy, so a mod cannot edit what a later poll returns.
+    return { status = "ok", result = (plain(job.value)) }
+  end
+  return { status = job.status, err = job.err }
+end
+
+function Job.release(loader, modId, handle)
+  local b = bucket(loader, modId)
+  local job = b[handle]
+  if not job then return false end
+  if job.status == "pending" then liveGlobal = math.max(0, liveGlobal - 1) end
+  b[handle] = nil
+  return true
+end
+
+-- There is no way to kill a LÖVE thread, so cancelling drops the result
+-- rather than stopping the work; the worker's own time budget is what bounds
+-- how long an abandoned job can run.
+function Job.cancel(loader, modId, handle)
+  local job = bucket(loader, modId)[handle]
+  if not job then return false end
+  if job.status == "pending" then
+    settle(job, "cancelled")
+  end
+  return true
+end
+
+function Job.releaseAll(loader, modId)
+  local b = loader.jobs and loader.jobs[modId]
+  if not b then return end
+  for handle, job in pairs(b) do
+    if job.status == "pending" then liveGlobal = math.max(0, liveGlobal - 1) end
+    b[handle] = nil
+  end
+  loader.jobs[modId] = nil
+end
+
+return Job

src/mods/LauncherMods.lua

@@ -36,10 +36,14 @@ 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 RequiredImports = require("src.mods.RequiredImports")
 
 local LauncherMods = {}
 
+local discover  -- forward declaration for helper functions above line 343
+
 -- ------- pure status derivation
 
 -- A hard-dependency / conflict / version verdict for one manifest.  mods is
@@ -84,31 +88,204 @@ local function statusFor(mods, id, enabledSet, enabled, version, forcedFor)
   -- resolveToggle would cascade-enable a merely-disabled dep rather than flag
   -- it, so the disabled case is judged straight off the manifest here.
   for _, spec in ipairs(m.dependencySpecs or {}) do
-    local dep = mods[spec.id]
-    if not dep then
-      return "warn", "Needs " .. spec.id .. " (not installed)"
-    elseif not enabledSet[spec.id] then
-      return "warn", "Needs " .. spec.id .. " (disabled)"
-    -- installed and on, but not for THIS game: the loader skips the
-    -- dependency and the skip is contagious (Loader:_enforceDependencies),
-    -- so a mod that runs everywhere still does not run here
-    elseif version
-        and not ModTargets.runsHere(dep, version, nil, forcedFor(spec.id)) then
-      return "warn", "Needs " .. spec.id .. " (not for "
-        .. ModTargets.gameLabel(version) .. ")"
-    elseif spec.range
-        and not Semver.satisfies(dep.version, spec.range) then
-      return "warn", "Needs " .. spec.id .. " " .. spec.range
+    if ModTargets.specApplies(spec, version) then
+      local dep = mods[spec.id]
+      if not dep then
+        return "warn", "Needs " .. spec.id .. " (not installed)"
+      elseif not enabledSet[spec.id] then
+        return "warn", "Needs " .. spec.id .. " (disabled)"
+      -- installed and on, but not for THIS game: the loader skips the
+      -- dependency and the skip is contagious (Loader:_enforceDependencies),
+      -- so a mod that runs everywhere still does not run here
+      elseif version
+          and not ModTargets.runsHere(dep, version, nil, forcedFor(spec.id)) then
+        return "warn", "Needs " .. spec.id .. " (not for "
+          .. ModTargets.gameLabel(version) .. ")"
+      elseif spec.range
+          and not Semver.satisfies(dep.version, spec.range) then
+        return "warn", "Needs " .. spec.id .. " " .. spec.range
+      end
     end
   end
   return "ok", "Ready"
 end
 
+-- Resolves the best-known GitHub owner/repo string for a dependency spec, if any.
+function LauncherMods.resolveDependencyRepo(depId, parentManifest, installedDep)
+  if not depId or depId == "" then return nil end
+  -- 1. Check spec hint if parentManifest dependencySpecs carries it
+  if parentManifest and parentManifest.dependencySpecs then
+    for _, spec in ipairs(parentManifest.dependencySpecs) do
+      if spec.id == depId and spec.github then
+        return spec.github
+      end
+    end
+  end
+  -- 2. Check parentManifest raw dependency_sources
+  if parentManifest and parentManifest.raw and type(parentManifest.raw.dependency_sources) == "table" then
+    local src = parentManifest.raw.dependency_sources[depId]
+    if src then
+      local ok, clean = pcall(Manifest.parseGithub, src)
+      if ok and clean then return clean end
+    end
+  end
+  -- 3. Check installed dependency manifest
+  if installedDep and installedDep.github then
+    return installedDep.github
+  end
+  -- 4. Check ModIndex entries if available
+  local okModIndex, ModIndex = pcall(require, "src.mods.ModIndex")
+  if okModIndex and ModIndex and type(ModIndex.sources) == "function" then
+    for _, src in ipairs(ModIndex.sources() or {}) do
+      local cached = ModIndex.readCache and ModIndex.readCache(src.feed)
+      if cached and type(cached.index) == "table" then
+        for _, entry in ipairs(cached.index) do
+          if type(entry) == "table" and entry.id == depId and entry.github then
+            local ok, clean = pcall(Manifest.parseGithub, entry.github)
+            if ok and clean then return clean end
+          end
+        end
+      end
+    end
+  end
+  return nil
+end
+
+-- Inspect manifest dependencies and conflicts against installed mods.
+-- Returns: { hasIssues = bool, targetMod = {...}, deps = [ { id, name, range, status, kind, installedVersion, github, safeUrl }, ... ] }
+function LauncherMods.checkDependencies(manifest, options, version, installedManifests)
+  if not manifest then
+    return { hasIssues = false, targetMod = { name = "Unknown" }, deps = {} }
+  end
+
+  local SaveData = require("src.core.SaveData")
+  local manifests = installedManifests or discover()
+  local installedMap = {}
+  for _, m in ipairs(manifests) do
+    installedMap[m.id] = m
+  end
+
+  local depsResult = {}
+  local hasIssues = false
+
+  -- 1. Hard Dependencies (dependencySpecs)
+  if type(manifest.dependencySpecs) == "table" then
+    for _, spec in ipairs(manifest.dependencySpecs) do
+      if not version or ModTargets.specApplies(spec, version) then
+        local depId = spec.id
+        local range = spec.range
+        local installedDep = installedMap[depId]
+        local status = "satisfied"
+        local installedVersion = installedDep and installedDep.version or nil
+
+        if not installedDep then
+          status = "missing"
+          hasIssues = true
+        elseif range and not Semver.satisfies(installedDep.version, range) then
+          status = "incompatible"
+          hasIssues = true
+        end
+
+        local ghRepo = LauncherMods.resolveDependencyRepo(depId, manifest, installedDep)
+        local safeUrl = ghRepo and ("https://github.com/" .. ghRepo) or nil
+
+        depsResult[#depsResult + 1] = {
+          id = depId,
+          name = (installedDep and installedDep.name) or depId,
+          range = range,
+          status = status,
+          kind = "dependency",
+          installedVersion = installedVersion,
+          github = ghRepo,
+          safeUrl = safeUrl,
+        }
+      end
+    end
+  end
+
+  -- 2. Conflicts / Incompatible Mods (conflictSpecs)
+  local conflictIdsSeen = {}
+  local scope = SaveData.modScope and SaveData.modScope(version) or version
+
+  local isEnabled = function(modId)
+    if not options then return true end
+    local dec = SaveData.modEnabled(options, modId, scope)
+    if dec ~= nil then return dec == true end
+    local m = installedMap[modId]
+    return m and not m.experimental
+  end
+
+  local function conflictApplies(spec, other)
+    return not spec.range or (other and other.version
+      and Semver.satisfies(other.version, spec.range))
+  end
+
+  -- (a) Conflicts declared by target manifest
+  if type(manifest.conflictSpecs) == "table" then
+    for _, spec in ipairs(manifest.conflictSpecs) do
+      local conflictId = spec.id
+      local installedOther = installedMap[conflictId]
+      if installedOther and isEnabled(conflictId)
+          and conflictApplies(spec, installedOther)
+          and not conflictIdsSeen[conflictId] then
+        conflictIdsSeen[conflictId] = true
+        hasIssues = true
+        depsResult[#depsResult + 1] = {
+          id = conflictId,
+          name = installedOther.name or conflictId,
+          status = "conflict",
+          kind = "conflict",
+          installedVersion = installedOther.version or "?",
+          github = nil,
+          safeUrl = nil,
+        }
+      end
+    end
+  end
+
+  -- (b) Reverse conflicts declared by installed mods against target manifest
+  if manifest.id then
+    local installedTarget = installedMap[manifest.id] or manifest
+    for _, other in ipairs(manifests) do
+      if other.id ~= manifest.id and isEnabled(other.id) and not conflictIdsSeen[other.id] then
+        local conflicts = other.conflictSpecs or {}
+        for _, spec in ipairs(conflicts) do
+          if spec.id == manifest.id and conflictApplies(spec, installedTarget) then
+            conflictIdsSeen[other.id] = true
+            hasIssues = true
+            depsResult[#depsResult + 1] = {
+              id = other.id,
+              name = other.name or other.id,
+              status = "conflict",
+              kind = "conflict",
+              installedVersion = other.version or "?",
+              github = nil,
+              safeUrl = nil,
+            }
+            break
+          end
+        end
+      end
+    end
+  end
+
+  return {
+    hasIssues = hasIssues,
+    targetMod = {
+      id = manifest.id,
+      name = manifest.name or manifest.id,
+      version = manifest.version or "?",
+    },
+    deps = depsResult,
+  }
+end
+
 -- deriveList(manifests, options [, version]) -> the panel row list, pure.
 -- manifests is an array of validated manifests (Manifest.validate output);
 -- options is the options table (options.mods, options.modsByVersion and
--- options.modsGen2 are read).  `version` is the game the panel is showing:
--- nil keeps the pre-per-game view, where the shared flag is the whole answer.
+-- options.modsGen2 are read).  `version` is the game the panel is showing;
+-- each row also carries its answer for every game so the launcher can render
+-- the coloured game checkboxes together.
 -- Rows come back sorted by id so the panel order is stable.
 function LauncherMods.deriveList(manifests, options, version)
   local ordered = {}
@@ -126,8 +303,7 @@ function LauncherMods.deriveList(manifests, options, version)
     -- this game's choice, then the shared flag, then the default: enabled,
     -- matching the loader -- except experimental mods, which stay off until
     -- the player opts in.  Scoped through modScope, so this reads exactly what
-    -- setEnabled writes and the loader loads: while per-game flags are a
-    -- preview the shared flag is the whole answer on every surface.
+    -- setEnabled writes and the loader loads for the selected game.
     local decided = SaveData.modEnabled(options, m.id, SaveData.modScope(version))
     if decided == nil then decided = not m.experimental end
     if decided then enabledSet[m.id] = true end
@@ -152,10 +328,20 @@ function LauncherMods.deriveList(manifests, options, version)
       badge = badge,
       description = m.description or "",
       enabled = enabled,
+      enabledByVersion = (function()
+        local answers = {}
+        for _, game in ipairs(GameVersion.ORDER) do
+          local answer = SaveData.modEnabled(options, m.id, game)
+          answers[game] = answer == true or (answer == nil and not m.experimental)
+        end
+        return answers
+      end)(),
       status = status,
       statusDetail = detail,
       github = m.github,
       experimental = m.experimental == true,
+      dependencySpecs = m.dependencySpecs,
+      manifest = m,
       -- what game this mod is for, and whether it will run on the one the
       -- panel is showing (src/mods/ModTargets.lua)
       targets = ModTargets.chip(m),
@@ -243,7 +429,7 @@ end
 -- Scan "mods/" one level deep for valid manifests (mirrors Loader:_discover,
 -- but validates only -- no entry chunk is ever loaded).  First id wins on a
 -- duplicate.  Returns an array of validated manifests.
-local function discover()
+discover = function()
   local fs = love and love.filesystem
   local out = {}
   if not (fs and fs.getInfo and fs.getDirectoryItems) then return out end
@@ -281,7 +467,39 @@ end
 function LauncherMods.list(version)
   local ok, result = pcall(function()
     local options = SaveData.loadOptions()
-    return LauncherMods.deriveList(discover(), options, version)
+    local manifests = discover()
+    -- Imports are private player grants. Never scan or copy another mod's
+    -- baseroms: a matching public digest is not permission to share the file.
+    local importState = {}
+    for _, manifest in ipairs(manifests) do
+      local rows, missing, missingOptional = RequiredImports.inspect(manifest)
+      importState[manifest.id] = { rows = rows, missing = missing,
+        missingOptional = missingOptional }
+    end
+    -- 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
+    local rows = LauncherMods.deriveList(manifests, options, version)
+    for _, row in ipairs(rows) do
+      local state = importState[row.id]
+        or { rows = {}, missing = 0, missingOptional = 0 }
+      local imports, missing = state.rows, state.missing
+      row.requiredImports, row.missingRequiredImports = imports, missing
+      row.imports = imports
+      row.missingOptionalImports = state.missingOptional or 0
+      if missing > 0 and row.status == "ok" then
+        row.status = "needs_import"
+        local first
+        for _, import in ipairs(imports) do
+          if not import.present then first = import break end
+        end
+        row.statusDetail = "Needs import: " .. (first and first.name or "required file")
+      end
+    end
+    return rows
   end)
   if not ok then
     -- a single bad options/mod file must not blank the launcher
@@ -364,14 +582,13 @@ function LauncherMods.translationStrings()
   return merged
 end
 
--- setEnabled(id, enabled [, version]): persist options.mods[id] in the exact
--- shape Loader:_saveState writes (a plain boolean), so the running game and
--- the in-game ManagerState pick it up unchanged.  With `version` the choice
--- lands in that game's overlay instead and no other game moves.
+-- setEnabled(id, enabled [, version]): with a game, persist just that game's
+-- answer.  The loader and the in-game manager use the same scope on next boot.
 function LauncherMods.setEnabled(id, enabled, version)
   local options = SaveData.loadOptions()
   SaveData.setModEnabled(options, id, enabled, SaveData.modScope(version))
   SaveData.saveOptions(options)
+  LauncherMods.syncActiveProfile(options)
   return true
 end
 
@@ -384,9 +601,18 @@ function LauncherMods.setAllEnabled(ids, enabled, version)
   local options = SaveData.loadOptions()
   local scope = SaveData.modScope(version)
   for _, id in ipairs(ids or {}) do
-    SaveData.setModEnabled(options, id, enabled, scope)
+    if scope then
+      SaveData.setModEnabled(options, id, enabled, scope)
+    elseif SaveData.PER_VERSION_MODS then
+      for _, game in ipairs(GameVersion.ORDER) do
+        SaveData.setModEnabled(options, id, enabled, game)
+      end
+    else
+      SaveData.setModEnabled(options, id, enabled)
+    end
   end
   SaveData.saveOptions(options)
+  LauncherMods.syncActiveProfile(options)
   return true
 end
 
@@ -485,6 +711,26 @@ local function copyTree(src, dst)
   return true
 end
 
+-- User-supplied baseroms are install state, not package content.  Snapshot
+-- them before replacing a mod tree so an update cannot make the player select
+-- the same cartridge again (or destroy their only reusable copy if the new
+-- archive later fails to copy).
+local function snapshotTree(path, into, relative)
+  local fs = love.filesystem
+  into, relative = into or {}, relative or ""
+  local info = fs.getInfo(path)
+  if not info then return into end
+  if info.type == "directory" then
+    for _, name in ipairs(fs.getDirectoryItems(path) or {}) do
+      local rel = relative == "" and name or (relative .. "/" .. name)
+      snapshotTree(path .. "/" .. name, into, rel)
+    end
+  elseif relative ~= "" and into[relative] == nil then
+    into[relative] = fs.read(path)
+  end
+  return into
+end
+
 -- Delete an installed mod subtree.  Enumeration stays on love.filesystem (the
 -- portable game folder is on its read path), but the deletes go through
 -- CacheFs so a portable install's real files actually go away instead of
@@ -652,9 +898,9 @@ function LauncherMods.adoptStrays() return scanStrays(true) end
 -- opts.replace = true uninstalls an existing same-id mod first (updates /
 -- rollbacks).  opts.expectId, when set, refuses a zip whose manifest id differs.
 function LauncherMods.installZip(source, opts)
-  local ok, result, err = pcall(LauncherMods._installZipInner, source, opts)
+  local ok, result, res2, res3 = pcall(LauncherMods._installZipInner, source, opts)
   if not ok then return nil, "import failed: " .. tostring(result) end
-  return result, err
+  return result, res2, res3
 end
 
 function LauncherMods._installZipInner(source, opts)
@@ -727,14 +973,28 @@ function LauncherMods._installZipInner(source, opts)
     return nil, ("zip is for '%s', expected '%s'")
       :format(manifest.id, opts.expectId)
   end
+  local packagedBaseroms = root .. "/baseroms"
+  if fs.getInfo(packagedBaseroms, "directory")
+      and #(fs.getDirectoryItems(packagedBaseroms) or {}) > 0 then
+    cleanup()
+    return nil, "mod archives must not include user-supplied baseroms/ files"
+  end
 
   local dest = "mods/" .. manifest.id
+  local baseromRecovery = "imports/baseroms-recovery/" .. manifest.id
   local existing, installedSomewhere = sameIdTrees(fs, manifest.id)
   if installedSomewhere and not opts.replace then
     cleanup()
     return nil, "a mod named '" .. manifest.id .. "' is already installed"
   end
+  local preservedBaseroms = {}
+  -- A previous failed update may have staged the user's files outside mods/ so
+  -- discovery cannot mistake recovery debris for an installed mod.
+  snapshotTree(baseromRecovery, preservedBaseroms)
   if #existing > 0 then
+    for _, path in ipairs(existing) do
+      snapshotTree(path .. "/baseroms", preservedBaseroms)
+    end
     -- drop every old tree before copy -- mods/<id> and any same-id folder
     -- under another name, or the survivor keeps winning discover()'s
     -- first-id-wins race after the "successful" update (#801).  A tree with
@@ -758,13 +1018,35 @@ function LauncherMods._installZipInner(source, opts)
   CacheFs.prefix = ""
   local copied, copyErr = copyTree(root, dest)
   if not copied then removeTree(dest) end
+  local preserveErr
+  for rel, bytes in pairs(preservedBaseroms) do
+    if bytes ~= nil then
+      local restored, restoreErr = CacheFs.write(dest .. "/baseroms/" .. rel, bytes)
+      if not restored and not preserveErr then
+        preserveErr = "could not preserve baseroms/" .. rel .. ": "
+          .. tostring(restoreErr)
+      end
+    end
+  end
+  if preserveErr then
+    -- Do not report a successful update that discarded user-owned input, and
+    -- do not leave a manifest-less baseroms tree that resembles an install.
+    removeTree(dest)
+    removeTree(baseromRecovery)
+    for rel, bytes in pairs(preservedBaseroms) do
+      if bytes ~= nil then CacheFs.write(baseromRecovery .. "/" .. rel, bytes) end
+    end
+    copied, copyErr = nil, preserveErr
+  elseif copied then
+    removeTree(baseromRecovery)
+  end
   CacheFs.prefix = savedPrefix
   if not copied then
     cleanup()
     return nil, copyErr or "could not copy the mod files"
   end
   cleanup()
-  return true, manifest.id
+  return true, manifest.id, manifest
 end
 
 -- Install (or replace) a mod from a GitHub release zip URL.
@@ -843,7 +1125,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 +1154,164 @@ function LauncherMods.uninstall(id)
   -- Drop the enable flag so a reinstall of the same id starts from the
   -- loader's default (enabled) rather than a stale false.
   local options = SaveData.loadOptions()
+  local changed = false
   if options.mods and options.mods[id] ~= nil then
     options.mods[id] = nil
+    changed = true
+  end
+  for _, version in ipairs(GameVersion.ORDER) do
+    local bucket = options.modsByVersion and options.modsByVersion[version]
+    if type(bucket) == "table" and bucket[id] ~= nil then
+      bucket[id] = nil
+      changed = true
+    end
+  end
+  if changed then
+    SaveData.saveOptions(options)
+  end
+  return true
+end
+
+-- ----------------------------------------------------------- Mod Profiles (#593)
+local ModProfile = require("src.mods.ModProfile")
+
+function LauncherMods.getProfiles(options)
+  options = options or SaveData.loadOptions()
+  local manifests = discover()
+  ModProfile.ensureFirst(options, manifests, options.modOptions)
+  return options.modProfiles or {}, options.activeProfile or "PROFILE 1"
+end
+
+function LauncherMods.applyProfile(profileName, options)
+  options = options or SaveData.loadOptions()
+  local profiles = options.modProfiles or {}
+  local targetProfile
+  for _, p in ipairs(profiles) do
+    if p.name == profileName then targetProfile = p; break end
+  end
+  if not targetProfile then return false end
+  ModProfile.restoreVersions(targetProfile, options)
+  options.activeProfile = profileName
+  SaveData.saveOptions(options)
+  return true
+end
+
+function LauncherMods.saveProfile(profileName, options)
+  options = options or SaveData.loadOptions()
+  local manifests = discover()
+  options.modProfiles = options.modProfiles or {}
+  local snap = ModProfile.capture(manifests, options.modOptions, options.modsByVersion)
+  snap.name = profileName
+  local existingIdx
+  for i, p in ipairs(options.modProfiles) do
+    if p.name == profileName then existingIdx = i; break end
+  end
+  if existingIdx then
+    options.modProfiles[existingIdx] = snap
+  else
+    options.modProfiles[#options.modProfiles + 1] = snap
+  end
+  options.activeProfile = profileName
+  SaveData.saveOptions(options)
+  return snap
+end
+
+local function copyTable(tbl)
+  if type(tbl) ~= "table" then return tbl end
+  local copy = {}
+  for k, v in pairs(tbl) do
+    copy[k] = type(v) == "table" and copyTable(v) or v
+  end
+  return copy
+end
+
+function LauncherMods.syncActiveProfile(options)
+  options = options or SaveData.loadOptions()
+  local activeName = options.activeProfile or "PROFILE 1"
+  local profiles = options.modProfiles or {}
+  local manifests = discover()
+  local snap = ModProfile.capture(manifests, options.modOptions, options.modsByVersion)
+  snap.name = activeName
+
+  local found = false
+  for i, p in ipairs(profiles) do
+    if p.name == activeName then
+      profiles[i] = snap
+      found = true
+      break
+    end
+  end
+  if not found then
+    profiles[#profiles + 1] = snap
+  end
+  options.modProfiles = profiles
+  options.activeProfile = activeName
+  SaveData.saveOptions(options)
+  return snap
+end
+
+function LauncherMods.duplicateProfile(sourceName, options)
+  options = options or SaveData.loadOptions()
+  local profiles = options.modProfiles or {}
+  local sourceProfile
+  for _, p in ipairs(profiles) do
+    if p.name == sourceName then sourceProfile = p; break end
+  end
+  if not sourceProfile then return nil end
+
+  local baseName = sourceName .. " (Copy)"
+  local newName = baseName
+  local n = 1
+  local taken = {}
+  for _, p in ipairs(profiles) do taken[p.name] = true end
+  while taken[newName] do
+    n = n + 1
+    newName = sourceName .. " (" .. n .. ")"
+  end
+
+  local snap = {
+    name = newName,
+    enabled = copyTable(sourceProfile.enabled),
+    options = copyTable(sourceProfile.options),
+    slots = copyTable(sourceProfile.slots),
+    enabledByVersion = copyTable(sourceProfile.enabledByVersion),
+  }
+  profiles[#profiles + 1] = snap
+  options.modProfiles = profiles
+  options.activeProfile = newName
+  SaveData.saveOptions(options)
+  return snap
+end
+
+function LauncherMods.renameProfile(oldName, newName, options)
+  options = options or SaveData.loadOptions()
+  if not newName or newName == "" then return false end
+  local profiles = options.modProfiles or {}
+  for i, p in ipairs(profiles) do
+    if p.name == oldName then
+      p.name = newName
+      if options.activeProfile == oldName then
+        options.activeProfile = newName
+      end
+      SaveData.saveOptions(options)
+      return true
+    end
+  end
+  return false
+end
+
+function LauncherMods.deleteProfile(profileName, options)
+  options = options or SaveData.loadOptions()
+  options.modProfiles = options.modProfiles or {}
+  local newProfiles = {}
+  for _, p in ipairs(options.modProfiles) do
+    if p.name ~= profileName then newProfiles[#newProfiles + 1] = p end
+  end
+  options.modProfiles = newProfiles
+  if options.activeProfile == profileName then
+    local fallback = newProfiles[1] and newProfiles[1].name or "PROFILE 1"
+    LauncherMods.applyProfile(fallback, options)
+  else
     SaveData.saveOptions(options)
   end
   return true

src/mods/LegacyCompat.lua

@@ -0,0 +1,956 @@
+local Logger = require("src.core.Logger")
+local SafePath = require("src.mods.SafePath")
+
+local okSave, SaveData = pcall(require, "src.core.SaveData")
+if not okSave then SaveData = nil end
+local okStorage, Storage = pcall(require, "src.mods.Storage")
+if not okStorage then Storage = nil end
+
+local LegacyCompat = {}
+
+local ROOT = "mod_compat"
+local OWN = "_own"
+local MAX_SEGMENTS = 24
+
+LegacyCompat.reports = {}
+
+function LegacyCompat.reset()
+  LegacyCompat.reports = {}
+end
+
+function LegacyCompat.report(modId)
+  if modId then
+    local entry = LegacyCompat.reports[modId]
+    return entry and entry.order or {}
+  end
+  local out = {}
+  for id, entry in pairs(LegacyCompat.reports) do
+    out[id] = entry.order
+  end
+  return out
+end
+
+local function note(ctx, call, advice)
+  local entry = LegacyCompat.reports[ctx.modId]
+  if not entry then
+    entry = { calls = {}, order = {} }
+    LegacyCompat.reports[ctx.modId] = entry
+  end
+  local row = entry.calls[call]
+  if row then
+    row.count = row.count + 1
+    return
+  end
+  row = { call = call, advice = advice, count = 1 }
+  entry.calls[call] = row
+  entry.order[#entry.order + 1] = row
+  Logger.warn("[%s] %s was removed from the mod sandbox; %s", ctx.modId, call,
+    advice)
+end
+
+local function refuse(ctx, call, advice)
+  note(ctx, call, advice)
+  return nil, ("%s is not available to mods; %s"):format(call, advice)
+end
+
+-- ------- path routing
+
+local function normalize(path)
+  if type(path) ~= "string" or path == "" then return nil end
+  path = path:gsub("\\", "/")
+  while path:find("//", 1, true) do path = (path:gsub("//", "/")) end
+  if path ~= "/" then path = (path:gsub("/$", "")) end
+  return path
+end
+
+local function flatten(path)
+  local parts = {}
+  for segment in path:gmatch("[^/]+") do
+    if segment ~= "." and segment ~= ".." then
+      parts[#parts + 1] = (segment:gsub("[^%w_%.%-]", "_"))
+    end
+  end
+  if #parts == 0 then return nil end
+  while #parts > MAX_SEGMENTS do table.remove(parts, 1) end
+  return table.concat(parts, "/")
+end
+
+local function storageKey(key)
+  local parts = {}
+  for segment in key:gmatch("[^/]+") do parts[#parts + 1] = segment end
+  if #parts == 0 then return nil end
+  parts[#parts] = (parts[#parts]:gsub("%.[^%.]*$", ""))
+  for i = 1, #parts do
+    local cleaned = (parts[i]:gsub("[^%w_%-]", "_"))
+    if cleaned == "" then return nil end
+    parts[i] = cleaned
+  end
+  return table.concat(parts, "/")
+end
+
+local function ownRelative(ctx, path)
+  if not ctx.modPath then return nil end
+  if path == ctx.modPath then return "" end
+  if path:sub(1, #ctx.modPath + 1) == ctx.modPath .. "/" then
+    return path:sub(#ctx.modPath + 2)
+  end
+  return nil
+end
+
+local function ownFull(ctx, rel)
+  if rel == "" then return ctx.modPath end
+  local safe = SafePath.safe(rel)
+  if not safe then return nil end
+  return ctx.modPath .. "/" .. safe
+end
+
+local function ownExists(ctx, rel)
+  local full = ownFull(ctx, rel)
+  local fs = ctx.fs
+  if not (full and fs and fs.getInfo) then return nil end
+  return fs.getInfo(full)
+end
+
+local function classify(ctx, path)
+  path = normalize(path)
+  if not path then return nil end
+
+  local root = ctx.virtualRoot
+  if path == root then return { key = "", dir = true } end
+  if path:sub(1, #root + 1) == root .. "/" then
+    return { key = flatten(path:sub(#root + 2)) }
+  end
+
+  local rel = ownRelative(ctx, path)
+  if not rel and path:sub(1, 1) ~= "/" and not path:match("^%a:")
+      and ownExists(ctx, path) then
+    rel = path
+  end
+  if rel then
+    if rel == "" then return { key = OWN, rel = "", dir = true } end
+    local flat = flatten(rel)
+    return { key = flat and (OWN .. "/" .. flat) or nil, rel = rel }
+  end
+
+  return { key = flatten(path) }
+end
+
+-- ------- the overlay
+
+local function persistFs(ctx)
+  if SaveData and SaveData.persistenceFs then
+    return SaveData.persistenceFs(ctx.fs)
+  end
+  return ctx.fs
+end
+
+local function overlayPath(ctx, key)
+  if key == nil or key == "" then return ROOT .. "/" .. ctx.modId end
+  return ROOT .. "/" .. ctx.modId .. "/" .. key
+end
+
+local function ensureParent(fs, path)
+  if not fs.createDirectory then return end
+  local dir = path:match("^(.*)/[^/]+$")
+  if not dir then return end
+  local built = nil
+  for segment in dir:gmatch("[^/]+") do
+    built = built and (built .. "/" .. segment) or segment
+    fs.createDirectory(built)
+  end
+end
+
+local function overlayRead(ctx, key)
+  local fs = persistFs(ctx)
+  if not (fs and fs.read and fs.getInfo) then return nil end
+  local path = overlayPath(ctx, key)
+  local info = fs.getInfo(path)
+  if not info or info.type == "directory" then return nil end
+  local body = fs.read(path)
+  if type(body) ~= "string" then return nil end
+  return body
+end
+
+local function overlayWrite(ctx, key, data)
+  local fs = persistFs(ctx)
+  if not (fs and fs.write) then
+    return false, "no writable filesystem is available"
+  end
+  local path = overlayPath(ctx, key)
+  ensureParent(fs, path)
+  local ok, err = fs.write(path, data)
+  if ok == false then return false, err or "write failed" end
+  return true
+end
+
+local function overlayRemove(ctx, key)
+  local fs = persistFs(ctx)
+  if not (fs and fs.remove and fs.getInfo) then return false end
+  local path = overlayPath(ctx, key)
+  if not fs.getInfo(path) then return false end
+  fs.remove(path)
+  return true
+end
+
+local function overlayInfo(ctx, key)
+  local fs = persistFs(ctx)
+  if not (fs and fs.getInfo) then return nil end
+  return fs.getInfo(overlayPath(ctx, key))
+end
+
+local function storageRead(ctx, key)
+  if not (Storage and key and key ~= "") then return nil end
+  if key:sub(1, #OWN + 1) == OWN .. "/" then return nil end
+  local game = ctx.game and ctx.game()
+  if not game then return nil end
+  local sk = storageKey(key)
+  if not sk then return nil end
+  ctx.storage = ctx.storage or Storage.new(ctx.modId, ctx.fs)
+  local ok, bytes = pcall(ctx.storage.readBytes, ctx.storage, game, sk)
+  if ok and type(bytes) == "string" then return bytes end
+  return nil
+end
+
+local function readPath(ctx, path)
+  local at = classify(ctx, path)
+  if not at then return nil, "invalid path" end
+  local body = at.key and overlayRead(ctx, at.key)
+  if body then return body end
+  if at.rel then
+    local full = ownFull(ctx, at.rel)
+    local fs = ctx.fs
+    if full and fs and fs.read then
+      local packaged = fs.read(full)
+      if type(packaged) == "string" then return packaged end
+    end
+  end
+  body = at.key and storageRead(ctx, at.key)
+  if body then return body end
+  return nil, "could not open " .. tostring(path)
+end
+
+local function writePath(ctx, path, data)
+  local at = classify(ctx, path)
+  if not (at and at.key) then return false, "invalid path" end
+  return overlayWrite(ctx, at.key, data)
+end
+
+local function infoPath(ctx, path)
+  local at = classify(ctx, path)
+  if not at then return nil end
+  if at.key then
+    local info = overlayInfo(ctx, at.key)
+    if info then
+      return { type = info.type, size = info.size, modtime = info.modtime }
+    end
+  end
+  if at.rel then
+    local info = ownExists(ctx, at.rel)
+    if info then
+      return { type = info.type, size = info.size, modtime = info.modtime }
+    end
+  end
+  local stored = at.key and storageRead(ctx, at.key)
+  if stored then return { type = "file", size = #stored } end
+  return nil
+end
+
+local function listPath(ctx, path)
+  local at = classify(ctx, path)
+  local seen, out = {}, {}
+  local function add(name)
+    if name and name ~= "" and not seen[name] then
+      seen[name] = true
+      out[#out + 1] = name
+    end
+  end
+  if at and at.rel then
+    local full = ownFull(ctx, at.rel)
+    local fs = ctx.fs
+    if full and fs and fs.getDirectoryItems then
+      for _, name in ipairs(fs.getDirectoryItems(full) or {}) do add(name) end
+    end
+  end
+  if at and at.key then
+    local fs = persistFs(ctx)
+    if fs and fs.getDirectoryItems then
+      for _, name in ipairs(fs.getDirectoryItems(overlayPath(ctx, at.key)) or {}) do
+        add(name)
+      end
+    end
+  end
+  table.sort(out)
+  return out
+end
+
+-- ------- buffered file handles
+
+local function openBuffer(ctx, path, mode)
+  mode = tostring(mode or "r"):gsub("b", "")
+  local writable = mode:find("[wa+]") ~= nil
+  local body
+  if mode:sub(1, 1) == "w" then
+    body = ""
+  else
+    body = readPath(ctx, path)
+    if not body then
+      if not writable then return nil, "could not open " .. tostring(path) end
+      body = ""
+    end
+  end
+  local state = {
+    ctx = ctx, path = path, buf = body, pos = 1,
+    writable = writable, closed = false, dirty = false,
+  }
+  if mode:sub(1, 1) == "a" then state.pos = #body + 1 end
+  return state
+end
+
+local function bufferFlush(state)
+  if not (state.writable and state.dirty) then return true end
+  local ok, err = writePath(state.ctx, state.path, state.buf)
+  if ok then state.dirty = false end
+  return ok, err
+end
+
+local function bufferWrite(state, text)
+  if not state.writable then return false, "file is not open for writing" end
+  local head = state.buf:sub(1, state.pos - 1)
+  if #head < state.pos - 1 then head = head .. string.rep("\0", state.pos - 1 - #head) end
+  local tail = state.buf:sub(state.pos + #text)
+  state.buf = head .. text .. tail
+  state.pos = state.pos + #text
+  state.dirty = true
+  return true
+end
+
+local function bufferRead(state, fmt)
+  if fmt == nil then fmt = "*l" end
+  if type(fmt) == "number" then
+    if fmt == 0 then return state.pos <= #state.buf and "" or nil end
+    if state.pos > #state.buf then return nil end
+    local chunk = state.buf:sub(state.pos, state.pos + fmt - 1)
+    state.pos = state.pos + #chunk
+    return chunk
+  end
+  fmt = tostring(fmt):gsub("^%*", "")
+  if fmt == "a" then
+    local rest = state.buf:sub(state.pos)
+    state.pos = #state.buf + 1
+    return rest
+  end
+  if fmt == "l" or fmt == "L" then
+    if state.pos > #state.buf then return nil end
+    local nl = state.buf:find("\n", state.pos, true)
+    local line
+    if nl then
+      line = state.buf:sub(state.pos, fmt == "L" and nl or nl - 1)
+      state.pos = nl + 1
+    else
+      line = state.buf:sub(state.pos)
+      state.pos = #state.buf + 1
+    end
+    return line
+  end
+  if fmt == "n" then
+    local rest = state.buf:sub(state.pos)
+    local text, after = rest:match("^%s*(%-?%d+%.?%d*[eE]?[-+]?%d*)()")
+    if not text then return nil end
+    state.pos = state.pos + after - 1
+    return tonumber(text)
+  end
+  return nil
+end
+
+local function bufferSeek(state, whence, offset)
+  whence = whence or "cur"
+  offset = offset or 0
+  if whence == "set" then state.pos = offset + 1
+  elseif whence == "cur" then state.pos = state.pos + offset
+  elseif whence == "end" then state.pos = #state.buf + offset + 1
+  else return nil, "bad seek base" end
+  if state.pos < 1 then state.pos = 1 end
+  return state.pos - 1
+end
+
+local function bufferClose(state)
+  if state.closed then return true end
+  local ok, err = bufferFlush(state)
+  state.closed = true
+  return ok, err
+end
+
+local function ioFile(ctx, path, mode)
+  local state, err = openBuffer(ctx, path, mode)
+  if not state then return nil, err end
+  local file = {}
+  function file:read(...)
+    local count = select("#", ...)
+    if count == 0 then return bufferRead(state, "*l") end
+    local out = {}
+    for i = 1, count do out[i] = bufferRead(state, (select(i, ...))) end
+    return unpack(out, 1, count)
+  end
+  function file:write(...)
+    for i = 1, select("#", ...) do
+      local value = select(i, ...)
+      local ok, writeErr = bufferWrite(state, tostring(value))
+      if not ok then return nil, writeErr end
+    end
+    return file
+  end
+  function file:lines(fmt)
+    return function() return bufferRead(state, fmt or "*l") end
+  end
+  function file:seek(whence, offset) return bufferSeek(state, whence, offset) end
+  function file:flush() bufferFlush(state) return file end
+  function file:close() return bufferClose(state) end
+  function file:setvbuf() return true end
+  return file
+end
+
+local function loveFile(ctx, path, mode)
+  local state = nil
+  local file = {}
+  function file:open(openMode)
+    local opened, err = openBuffer(ctx, path, openMode or mode or "r")
+    if not opened then return false, err end
+    state = opened
+    return true
+  end
+  function file:isOpen() return state ~= nil and not state.closed end
+  function file:read(bytes)
+    if not state and not file:open("r") then return nil, 0 end
+    local body = bytes and bufferRead(state, bytes) or bufferRead(state, "*a")
+    if not body then return nil, 0 end
+    return body, #body
+  end
+  function file:write(data, size)
+    if not state and not file:open(mode or "w") then return false end
+    data = tostring(data)
+    if size then data = data:sub(1, size) end
+    local ok, err = bufferWrite(state, data)
+    if not ok then return false, err end
+    bufferFlush(state)
+    return true
+  end
+  function file:lines()
+    if not state then file:open("r") end
+    return function() return state and bufferRead(state, "*l") or nil end
+  end
+  function file:seek(offset)
+    if not state then return false end
+    bufferSeek(state, "set", offset or 0)
+    return true
+  end
+  function file:tell() return state and (state.pos - 1) or 0 end
+  function file:getSize()
+    if state then return #state.buf end
+    local body = readPath(ctx, path)
+    return body and #body or 0
+  end
+  function file:flush() if state then bufferFlush(state) end return true end
+  function file:close()
+    if state then bufferClose(state) end
+    state = nil
+    return true
+  end
+  function file:getFilename() return path end
+  function file:getMode() return mode or "c" end
+  function file:setBuffer() return true end
+  if mode and mode ~= "c" then file:open(mode) end
+  return file
+end
+
+-- ------- the love.filesystem stand-in
+
+local function realFilesystem()
+  return _G.love and _G.love.filesystem or nil
+end
+
+local function filesystemShim(ctx)
+  local fsShim = {}
+
+  local function readAdvice() return "reads now come from mod:read and mod.storage" end
+
+  function fsShim.read(a, b, c)
+    local path, size = a, b
+    if (a == "string" or a == "data") and type(b) == "string" then
+      path, size = b, c
+    end
+    note(ctx, "love.filesystem.read", readAdvice())
+    local body, err = readPath(ctx, path)
+    if not body then return nil, err end
+    if size and size >= 0 then body = body:sub(1, size) end
+    return body, #body
+  end
+
+  function fsShim.write(path, data, size)
+    note(ctx, "love.filesystem.write",
+      "writes are rerouted to this mod's private compat storage; migrate to mod.storage")
+    data = tostring(data)
+    if size then data = data:sub(1, size) end
+    local ok, err = writePath(ctx, path, data)
+    if not ok then return false, err end
+    return true
+  end
+
+  function fsShim.append(path, data, size)
+    note(ctx, "love.filesystem.append",
+      "writes are rerouted to this mod's private compat storage; migrate to mod.storage")
+    data = tostring(data)
+    if size then data = data:sub(1, size) end
+    local existing = readPath(ctx, path) or ""
+    local ok, err = writePath(ctx, path, existing .. data)
+    if not ok then return false, err end
+    return true
+  end
+
+  function fsShim.lines(path)
+    note(ctx, "love.filesystem.lines", readAdvice())
+    local body = readPath(ctx, path)
+    if not body then error("could not open " .. tostring(path), 2) end
+    local pos = 1
+    return function()
+      if pos > #body then return nil end
+      local nl = body:find("\n", pos, true)
+      local line
+      if nl then
+        line = body:sub(pos, nl - 1)
+        pos = nl + 1
+      else
+        line = body:sub(pos)
+        pos = #body + 1
+      end
+      return line
+    end
+  end
+
+  function fsShim.load(path)
+    note(ctx, "love.filesystem.load",
+      "the chunk is compiled into this mod's sandbox; prefer require or mod:read plus load")
+    local body = readPath(ctx, path)
+    if not body then return nil, "could not open " .. tostring(path) end
+    if not ctx.compile then return nil, "no sandbox is bound yet" end
+    return ctx.compile(body, "@" .. tostring(path))
+  end
+
+  function fsShim.getInfo(path, a, b)
+    local info = infoPath(ctx, path)
+    local filter = type(a) == "string" and a or nil
+    local into = type(a) == "table" and a or (type(b) == "table" and b or nil)
+    if not info then return nil end
+    if filter and info.type ~= filter then return nil end
+    if into then
+      into.type, into.size, into.modtime = info.type, info.size, info.modtime
+      return into
+    end
+    return info
+  end
+
+  function fsShim.getDirectoryItems(path)
+    note(ctx, "love.filesystem.getDirectoryItems", "use mod.assets:list")
+    return listPath(ctx, path)
+  end
+
+  function fsShim.createDirectory(path)
+    local at = classify(ctx, path)
+    if not (at and at.key) then return false end
+    local fs = persistFs(ctx)
+    if not (fs and fs.createDirectory) then return false end
+    ensureParent(fs, overlayPath(ctx, at.key) .. "/.")
+    fs.createDirectory(overlayPath(ctx, at.key))
+    return true
+  end
+
+  function fsShim.remove(path)
+    local at = classify(ctx, path)
+    if not (at and at.key) then return false end
+    return overlayRemove(ctx, at.key)
+  end
+
+  function fsShim.exists(path) return infoPath(ctx, path) ~= nil end
+
+  function fsShim.isFile(path)
+    local info = infoPath(ctx, path)
+    return info ~= nil and info.type == "file"
+  end
+
+  function fsShim.isDirectory(path)
+    local info = infoPath(ctx, path)
+    return info ~= nil and info.type == "directory"
+  end
+
+  function fsShim.getSize(path)
+    local info = infoPath(ctx, path)
+    if not info then return nil, "could not open " .. tostring(path) end
+    return info.size or 0
+  end
+
+  function fsShim.getLastModified(path)
+    local info = infoPath(ctx, path)
+    if not info then return nil, "could not open " .. tostring(path) end
+    return info.modtime or 0
+  end
+
+  local function virtual(call)
+    note(ctx, call, "paths are virtual now; everything under the returned root "
+      .. "lands in this mod's private compat storage")
+    return ctx.virtualRoot
+  end
+
+  function fsShim.getSaveDirectory() return virtual("love.filesystem.getSaveDirectory") end
+  function fsShim.getWorkingDirectory() return virtual("love.filesystem.getWorkingDirectory") end
+  function fsShim.getUserDirectory() return virtual("love.filesystem.getUserDirectory") end
+  function fsShim.getAppdataDirectory() return virtual("love.filesystem.getAppdataDirectory") end
+  function fsShim.getSourceBaseDirectory() return virtual("love.filesystem.getSourceBaseDirectory") end
+  function fsShim.getRealDirectory() return ctx.virtualRoot end
+
+  function fsShim.getIdentity() return ctx.modId end
+
+  function fsShim.setIdentity()
+    note(ctx, "love.filesystem.setIdentity",
+      "a mod cannot repoint the save directory; the call does nothing")
+    return false
+  end
+
+  function fsShim.getRequirePath() return "" end
+  function fsShim.setRequirePath() return false end
+  function fsShim.getCRequirePath() return "" end
+  function fsShim.setCRequirePath() return false end
+
+  function fsShim.mount()
+    note(ctx, "love.filesystem.mount",
+      "mounting is refused; ship the files inside your mod and use mod:read")
+    return false
+  end
+  fsShim.unmount = fsShim.mount
+
+  function fsShim.newFile(path, mode) return loveFile(ctx, path, mode) end
+
+  function fsShim.newFileData(a, b)
+    local real = realFilesystem()
+    if type(a) == "string" and b == nil then
+      note(ctx, "love.filesystem.newFileData", readAdvice())
+      local body = readPath(ctx, a)
+      if not body then return nil, "could not open " .. tostring(a) end
+      if real and real.newFileData then return real.newFileData(body, a) end
+      return nil, "no filesystem"
+    end
+    if real and real.newFileData then return real.newFileData(a, b) end
+    return nil, "no filesystem"
+  end
+
+  function fsShim.isFused()
+    local real = realFilesystem()
+    return real and real.isFused and real.isFused() or false
+  end
+
+  function fsShim.areSymlinksEnabled() return false end
+  function fsShim.setSymlinksEnabled() return false end
+  function fsShim.init() return false end
+  function fsShim.setSource() return false end
+
+  return setmetatable(fsShim, { __index = function(_, key)
+    note(ctx, "love.filesystem." .. tostring(key),
+      "there is no compat stand-in for it; use mod.storage or mod:read")
+    return nil
+  end })
+end
+
+-- ------- the rest of the removed surface
+
+local function systemShim(ctx)
+  local function real() return _G.love and _G.love.system or nil end
+  -- tls* comes from the engine (Android JNI, or desktop gen1tls hung on
+  -- love.system at boot).  Forward those; keep clipboard / openURL stubbed.
+  local TLS = {
+    tlsOpen = true, tlsStatus = true, tlsSend = true,
+    tlsReceive = true, tlsError = true, tlsClose = true,
+  }
+  local shim = {
+    getOS = function()
+      local sys = real()
+      return sys and sys.getOS and sys.getOS() or "Unknown"
+    end,
+    getPowerInfo = function()
+      local sys = real()
+      if not (sys and sys.getPowerInfo) then return "unknown", nil, nil end
+      return sys.getPowerInfo()
+    end,
+    getProcessorCount = function()
+      local sys = real()
+      return sys and sys.getProcessorCount and sys.getProcessorCount() or 1
+    end,
+    getClipboardText = function()
+      note(ctx, "love.system.getClipboardText",
+        "clipboard access stays sandboxed; the call returns an empty string")
+      return ""
+    end,
+    setClipboardText = function()
+      note(ctx, "love.system.setClipboardText",
+        "clipboard access stays sandboxed; the call does nothing")
+      return false
+    end,
+    openURL = function()
+      note(ctx, "love.system.openURL",
+        "launching a URL stays sandboxed; the call does nothing")
+      return false
+    end,
+    vibrate = function(...)
+      local sys = real()
+      if sys and sys.vibrate then return sys.vibrate(...) end
+      return false
+    end,
+  }
+  return setmetatable(shim, {
+    __index = function(_, key)
+      if not TLS[key] then return nil end
+      local sys = real()
+      return sys and sys[key]
+    end,
+  })
+end
+
+local function eventShim(ctx)
+  local function real() return _G.love and _G.love.event or nil end
+  local shim = {
+    quit = function()
+      note(ctx, "love.event.quit",
+        "a mod cannot close the game out from under the player; the call does nothing")
+      return false
+    end,
+  }
+  shim.push = function(name, ...)
+    if name == "quit" then return shim.quit() end
+    local ev = real()
+    if ev and ev.push then return ev.push(name, ...) end
+    return false
+  end
+  return setmetatable(shim, { __index = function(_, key)
+    local ev = real()
+    return ev and ev[key] or nil
+  end })
+end
+
+local function ioShim(ctx)
+  local stream = {
+    write = function(self, ...)
+      for i = 1, select("#", ...) do io.write(tostring((select(i, ...)))) end
+      return self
+    end,
+    flush = function(self) return self end,
+    close = function() return true end,
+    read = function() return nil end,
+    lines = function() return function() return nil end end,
+    seek = function() return 0 end,
+    setvbuf = function() return true end,
+  }
+  local out = setmetatable({}, { __index = stream })
+  local shim = {
+    open = function(path, mode)
+      note(ctx, "io.open",
+        "the handle is backed by mod:read and this mod's private compat storage")
+      local file, err = ioFile(ctx, path, mode)
+      if not file then return nil, err, 2 end
+      return file
+    end,
+    lines = function(path, fmt)
+      if path == nil then return function() return nil end end
+      note(ctx, "io.lines",
+        "the handle is backed by mod:read and this mod's private compat storage")
+      local file, err = ioFile(ctx, path, "r")
+      if not file then error(err, 2) end
+      return file:lines(fmt)
+    end,
+    close = function(file) if file and file.close then return file:close() end return true end,
+    type = function(file)
+      if type(file) == "table" and file.read and file.close then return "file" end
+      return nil
+    end,
+    read = function() return nil end,
+    write = function(...) return out:write(...) end,
+    input = function() return out end,
+    output = function() return out end,
+    stdout = out,
+    stderr = out,
+    stdin = setmetatable({}, { __index = stream }),
+    popen = function()
+      return refuse(ctx, "io.popen", "spawning a process is refused")
+    end,
+    tmpfile = function()
+      return ioFile(ctx, ctx.virtualRoot .. "/io_tmpfile", "w+")
+    end,
+  }
+  return shim
+end
+
+local function osShim(ctx)
+  local HOME = { HOME = true, APPDATA = true, LOCALAPPDATA = true,
+                 USERPROFILE = true, XDG_DATA_HOME = true,
+                 XDG_CONFIG_HOME = true, TMPDIR = true, TEMP = true, TMP = true }
+  return {
+    getenv = function(name)
+      note(ctx, "os.getenv",
+        "the environment is hidden; home-like names answer with this mod's virtual root")
+      if type(name) == "string" and HOME[name:upper()] then
+        return ctx.virtualRoot
+      end
+      return nil
+    end,
+    remove = function(path)
+      note(ctx, "os.remove", "the delete lands in this mod's private compat storage")
+      local at = classify(ctx, path)
+      if not (at and at.key and overlayRemove(ctx, at.key)) then
+        return nil, tostring(path) .. ": no such file"
+      end
+      return true
+    end,
+    rename = function(from, to)
+      note(ctx, "os.rename", "the move lands in this mod's private compat storage")
+      local body = readPath(ctx, from)
+      if not body then return nil, tostring(from) .. ": no such file" end
+      local ok, err = writePath(ctx, to, body)
+      if not ok then return nil, err end
+      local at = classify(ctx, from)
+      if at and at.key then overlayRemove(ctx, at.key) end
+      return true
+    end,
+    tmpname = function()
+      return ctx.virtualRoot .. "/tmp/os_tmpname"
+    end,
+    execute = function()
+      note(ctx, "os.execute", "running a command is refused")
+      return false
+    end,
+    exit = function()
+      note(ctx, "os.exit",
+        "a mod cannot end the process; the call does nothing")
+      return false
+    end,
+    setlocale = function() return "C" end,
+  }
+end
+
+local function packageShim(ctx)
+  local shim = { path = "", cpath = "", preload = {}, loaded = {}, loaders = {} }
+  return setmetatable(shim, {
+    __index = function(_, key)
+      note(ctx, "package." .. tostring(key),
+        "the module loader is sandboxed; use require for the supported engine modules")
+      return nil
+    end,
+  })
+end
+
+-- ------- love callbacks
+
+local CALLBACKS = {
+  load = true, update = true, draw = true, quit = true, lowmemory = true,
+  threaderror = true, keypressed = true, keyreleased = true,
+  textinput = true, textedited = true, mousemoved = true,
+  mousepressed = true, mousereleased = true, wheelmoved = true,
+  mousefocus = true, touchpressed = true, touchreleased = true,
+  touchmoved = true, joystickadded = true, joystickremoved = true,
+  joystickpressed = true, joystickreleased = true, joystickaxis = true,
+  joystickhat = true, gamepadpressed = true, gamepadreleased = true,
+  gamepadaxis = true, focus = true, visible = true, resize = true,
+  filedropped = true, directorydropped = true, displayrotated = true,
+  audiodevicechanged = true, localechanged = true,
+}
+
+local REFUSED = {
+  run = "love.run is the engine's fixed-step loop; use mod.hooks and mod.events",
+  errorhandler = "love.errorhandler is how a crash reaches the player; "
+    .. "use mod.events",
+}
+
+-- ------- assembly
+
+function LegacyCompat.new(opts)
+  opts = opts or {}
+  local ctx = {
+    modId = opts.modId or "mod",
+    modPath = opts.modPath,
+    fs = opts.fs,
+    game = opts.game,
+    compile = nil,
+  }
+  ctx.virtualRoot = "/pokeport/" .. ctx.modId
+
+  local filesystem = filesystemShim(ctx)
+  local io_ = ioShim(ctx)
+  local system = systemShim(ctx)
+  local event = eventShim(ctx)
+
+  local compat = {
+    ctx = ctx,
+    love = { filesystem = filesystem, system = system, event = event },
+    os = osShim(ctx),
+    globals = {
+      io = io_,
+      package = packageShim(ctx),
+      loadfile = function(path)
+        note(ctx, "loadfile",
+          "the chunk is compiled into this mod's sandbox; prefer require or mod:read")
+        local body = readPath(ctx, path)
+        if not body then return nil, "could not open " .. tostring(path) end
+        if not ctx.compile then return nil, "no sandbox is bound yet" end
+        return ctx.compile(body, "@" .. tostring(path))
+      end,
+    },
+    modules = {
+      io = io_,
+      ["love.filesystem"] = filesystem,
+      ["love.system"] = system,
+      ["love.event"] = event,
+    },
+  }
+
+  compat.globals.dofile = function(path)
+    local chunk, err = compat.globals.loadfile(path)
+    if not chunk then error(err or ("could not open " .. tostring(path)), 2) end
+    return chunk()
+  end
+
+  function compat.module(name)
+    if type(name) ~= "string" then return nil end
+    local substitute = compat.modules[name]
+    if substitute then
+      note(ctx, ('require("%s")'):format(name),
+        "it now answers with the compat stand-in, not the real module")
+      return substitute
+    end
+    if name == "os" then
+      note(ctx, 'require("os")',
+        "it now answers with the compat stand-in, not the real module")
+      return compat.osTable
+    end
+    return nil
+  end
+
+  -- true when the assignment is a callback chain, which is what a mod
+  -- wrapping love.mousemoved did before the sandbox; false plus a reason for
+  -- the two names the engine owns, false alone for a module table.
+  function compat.assign(key, value)
+    if REFUSED[key] then
+      note(ctx, ("love.%s assignment"):format(key), REFUSED[key])
+      return false, ("[%s] %s"):format(ctx.modId, REFUSED[key])
+    end
+    if not CALLBACKS[key] then return false end
+    if value ~= nil and type(value) ~= "function" then return false end
+    note(ctx, ("love.%s assignment"):format(key),
+      "the callback lands on the real love table the way it did before the "
+      .. "sandbox; prefer mod.hooks and mod.events")
+    return true
+  end
+
+  function compat.bind(env, compile)
+    ctx.compile = compile
+    compat.osTable = env and env.os or nil
+  end
+
+  return compat
+end
+
+return LegacyCompat

src/mods/Loader.lua

@@ -4,6 +4,7 @@ local SaveData = require("src.core.SaveData")
 local Data = require("src.core.Data")
 local GameVersion = require("src.core.GameVersion")
 local Version = require("src.core.Version")
+local RequiredImports = require("src.mods.RequiredImports")
 local Assets = require("src.render.Assets")
 local ModUI = require("src.ui.ModUI")
 local DateTime = require("src.core.DateTime")
@@ -12,12 +13,18 @@ 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 LegacyCompat = require("src.mods.LegacyCompat")
 local Runtime = require("src.mods.Runtime")
+local Steps = require("src.mods.Steps")
+local Net = require("src.mods.Net")
+local Job = require("src.mods.Job")
 
 local Loader = {}
 Loader.__index = Loader
@@ -72,10 +79,12 @@ local function orderedIds(mods, filter)
   return ids
 end
 
--- ------- dev-mode permissions tripwire
--- Attribution only: the shim delegates unconditionally and blocks nothing.
--- Installed once per process and only when the loader runs in dev mode, so a
--- player build has zero interposition.
+-- ------- the require gate
+-- Two jobs in one interposition.  The engine_internals/network scan is
+-- attribution only and stays dev-mode: it warns and delegates.  The
+-- Sandbox.moduleDenial check is not -- require("io") would hand back
+-- package.loaded.io and undo the whole mod environment -- so it is installed
+-- in player builds too, for any boot that has mods on it.
 
 local devShim = { installed = false, permissions = {}, warned = {}, depth = 0 }
 
@@ -135,7 +144,8 @@ end
 
 local function scanRequire(name)
   local modId = Runtime.currentMod
-  if not modId or type(name) ~= "string" then return end
+  if type(modId) ~= "string" then modId = Runtime.modRequire end
+  if type(modId) ~= "string" or type(name) ~= "string" then return end
   local granted = devShim.permissions[modId] or {}
   local function warnOnce(permission)
     local key = modId .. "|" .. permission .. "|" .. name
@@ -188,6 +198,7 @@ function Loader:_installDevShim()
   for id, mod in pairs(self.mods) do
     devShim.permissions[id] = mod.manifest.permissionSet
   end
+  devShim.dev = self.dev
   if devShim.installed then return end
   devShim.installed = true
   local delegate = require
@@ -195,12 +206,22 @@ function Loader:_installDevShim()
     -- only the mod's own call is the mod's doing; whatever that module
     -- requires in turn is the engine wiring itself up
     if devShim.depth == 0 then
-      scanRequire(name)
+      -- Backstop for the deny list Sandbox.envFor's require already applies:
+      -- an engine module requiring io is the engine wiring itself up, a mod
+      -- doing it is the hole this closes, and any future path that runs mod
+      -- code without a sandbox env still lands here.
+      local owner = Runtime.currentMod or Runtime.modRequire
+      if owner or callerIsMod(3) then
+        local id = type(owner) == "string" and owner or nil
+        local denial = Sandbox.moduleDenial(name, devShim.permissions[id])
+        if denial then error(("[%s] %s"):format(id or "mod", denial), 0) end
+      end
+      if devShim.dev or devShim.generation ~= 1 then scanRequire(name) end
       -- The Gen 1 name a mod asked for, answered by the Gen 2 arm behind it.
       -- Engine code keeps the real module: src/render/PaletteFX.lua:776
       -- requires src.core.Game on both generations and means it.
       if devShim.generation ~= 1 and Gen2Compat.serves(name)
-          and callerIsMod(3) then
+          and (owner or callerIsMod(3)) then
         local adapter = Gen2Compat.resolve(name, Runtime.currentMod)
         if adapter then
           local key = "adapter|" .. name
@@ -235,7 +256,7 @@ function Loader.new(opts)
     events = Events.new(), hooks = Hooks.new(), content = {}, assets = {},
     exports = {}, migrations = {}, order = {},
     modSave = {}, modOptions = {}, optionSchemas = {}, imageCache = {},
-    modInput = {},
+    modInput = {}, modEnv = {}, stepsQueues = {},
     fs = (opts and opts.fs) or (love and love.filesystem),
     dev = dev,
     -- Which generation this boot is (1 or 2).  Fixed at construction: the
@@ -270,8 +291,7 @@ function Loader:_targetVersion()
   return version
 end
 
--- The version an enable flag is read and written under: this game once
--- per-game flags are live, nil (the shared flag) while they are a preview.
+-- The version an enable flag is read and written under: this running game.
 -- Reads and writes go through the same answer so the two can never drift.
 function Loader:_enableScope()
   return SaveData.modScope(self:_targetVersion())
@@ -358,11 +378,13 @@ function Loader:_writeOptionSchemas()
       -- demand; using it here means older mods do not need to migrate to
       -- mod.options:define just to appear in a launcher settings screen.
       if schema == nil and mod.manifest.options_schema and self.fs.load then
-        local chunk = self.fs.load(mod.path .. "/" .. mod.manifest.options_schema)
-        if chunk then
-          local ok, rows = pcall(chunk)
-          if ok and type(rows) == "table" then schema = rows end
-        end
+        local ok, rows = pcall(function()
+          local path = SafePath.join(mod.path, mod.manifest.options_schema,
+            "options_schema")
+          local chunk = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
+          return chunk and chunk()
+        end)
+        if ok and type(rows) == "table" then schema = rows end
       end
       if schema ~= nil then
         mods[id] = schema
@@ -547,7 +569,24 @@ function Loader:_validate()
     elseif manifest.assets_transforms
         and not self:_exists(mod.path .. "/" .. manifest.assets_transforms) then
       reason = "assets_transforms file missing: " .. manifest.assets_transforms
-    elseif manifest.game_version and not devEngine() then
+    end
+    if not reason and #(manifest.required_imports or {}) > 0 then
+      for _, import in ipairs(manifest.required_imports) do
+        local path = mod.path .. "/baseroms/" .. import.file
+        if not self:_exists(path) then
+          reason = "required import missing: " .. import.name
+          break
+        end
+        local valid, importErr = RequiredImports.validateStored(
+          manifest, import, self.fs)
+        if not valid then
+          reason = "required import invalid: " .. import.name
+            .. " (" .. tostring(importErr) .. ")"
+          break
+        end
+      end
+    end
+    if not reason and manifest.game_version and not devEngine() then
       local ok, err = Semver.satisfies(Version.engine, manifest.game_version)
       if not ok then
         reason = ("needs game version %s, engine is %s")
@@ -562,42 +601,46 @@ end
 -- hard dependencies must exist, be enabled, have survived, and satisfy their
 -- range; run to a fixpoint so failures propagate to dependents transitively
 function Loader:_enforceDependencies()
+  local targetVersion = self:_targetVersion()
+  local generation = self.generation
   local changed = true
   while changed do
     changed = false
     for _, id in ipairs(orderedIds(self.mods, isActive)) do
       local mod = self.mods[id]
       for _, spec in ipairs(mod.manifest.dependencySpecs) do
-        local dep = self.mods[spec.id]
-        local reason, skip
-        if not dep then
-          reason = "missing dependency: " .. spec.id
-        elseif not dep.enabled then
-          reason = ("dependency %s is disabled"):format(spec.id)
-        elseif dep.state == "wrong_generation" then
-          -- the gate's skip is contagious as a SKIP, not as a failure: the
-          -- dependency has no bug to report and neither does this mod, so
-          -- nothing here lands on the boot error list
-          skip = true
-          -- carry the dependency's own reason: it names the game or the
-          -- missing gen2compat, and a guess here would name the wrong one
-          reason = ("depends on %s, which does not run here (%s)")
-            :format(spec.id, dep.skipReason or "not made for this game")
-        elseif dep.failed then
-          reason = ("dependency %s failed to load"):format(spec.id)
-        elseif spec.range
-            and not Semver.satisfies(dep.manifest.version, spec.range) then
-          reason = ("needs %s@%s, found %s")
-            :format(spec.id, spec.range, dep.manifest.version)
-        end
-        if reason then
-          if skip then
-            self:_skip(mod, "wrong_generation", reason)
-          else
-            self:_fail(mod, "blocked_dependency", reason)
+        if ModTargets.specApplies(spec, targetVersion, generation) then
+          local dep = self.mods[spec.id]
+          local reason, skip
+          if not dep then
+            reason = "missing dependency: " .. spec.id
+          elseif not dep.enabled then
+            reason = ("dependency %s is disabled"):format(spec.id)
+          elseif dep.state == "wrong_generation" then
+            -- the gate's skip is contagious as a SKIP, not as a failure: the
+            -- dependency has no bug to report and neither does this mod, so
+            -- nothing here lands on the boot error list
+            skip = true
+            -- carry the dependency's own reason: it names the game or the
+            -- missing gen2compat, and a guess here would name the wrong one
+            reason = ("depends on %s, which does not run here (%s)")
+              :format(spec.id, dep.skipReason or "not made for this game")
+          elseif dep.failed then
+            reason = ("dependency %s failed to load"):format(spec.id)
+          elseif spec.range
+              and not Semver.satisfies(dep.manifest.version, spec.range) then
+            reason = ("needs %s@%s, found %s")
+              :format(spec.id, spec.range, dep.manifest.version)
+          end
+          if reason then
+            if skip then
+              self:_skip(mod, "wrong_generation", reason)
+            else
+              self:_fail(mod, "blocked_dependency", reason)
+            end
+            changed = true
+            break
           end
-          changed = true
-          break
         end
       end
     end
@@ -607,6 +650,8 @@ end
 -- Tarjan SCC over the hard-dependency graph: only a cycle's own members
 -- fail, so an unrelated mod beside a cycle still loads
 function Loader:_failCycles()
+  local targetVersion = self:_targetVersion()
+  local generation = self.generation
   local mods = self.mods
   local counter, stack, onStack, index, low = 0, {}, {}, {}, {}
   local cycles = {}
@@ -617,14 +662,16 @@ function Loader:_failCycles()
     onStack[id] = true
     local selfEdge = false
     for _, spec in ipairs(mods[id].manifest.dependencySpecs) do
-      local dep = mods[spec.id]
-      if spec.id == id then selfEdge = true end
-      if dep and isActive(dep) and spec.id ~= id then
-        if not index[spec.id] then
-          connect(spec.id)
-          if low[spec.id] < low[id] then low[id] = low[spec.id] end
-        elseif onStack[spec.id] and index[spec.id] < low[id] then
-          low[id] = index[spec.id]
+      if ModTargets.specApplies(spec, targetVersion, generation) then
+        local dep = mods[spec.id]
+        if spec.id == id then selfEdge = true end
+        if dep and isActive(dep) and spec.id ~= id then
+          if not index[spec.id] then
+            connect(spec.id)
+            if low[spec.id] < low[id] then low[id] = low[spec.id] end
+          elseif onStack[spec.id] and index[spec.id] < low[id] then
+            low[id] = index[spec.id]
+          end
         end
       end
     end
@@ -675,6 +722,8 @@ end
 -- Kahn over the surviving graph with the ready set kept in (priority, id)
 -- order, so dependencies come first and the rest matches the v1 contract
 function Loader:_order()
+  local targetVersion = self:_targetVersion()
+  local generation = self.generation
   local pending, indegree, dependents = {}, {}, {}
   for _, id in ipairs(orderedIds(self.mods, isActive)) do
     pending[id], indegree[id] = true, 0
@@ -687,9 +736,17 @@ function Loader:_order()
       dependents[depId][#dependents[depId] + 1] = id
       indegree[id] = indegree[id] + 1
     end
-    for _, spec in ipairs(manifest.dependencySpecs) do edge(spec.id) end
+    for _, spec in ipairs(manifest.dependencySpecs) do
+      if ModTargets.specApplies(spec, targetVersion, generation) then
+        edge(spec.id)
+      end
+    end
     -- optional dependencies order without requiring anything
-    for _, spec in ipairs(manifest.optionalSpecs) do edge(spec.id) end
+    for _, spec in ipairs(manifest.optionalSpecs) do
+      if ModTargets.specApplies(spec, targetVersion, generation) then
+        edge(spec.id)
+      end
+    end
   end
   local ordered = {}
   local function nextId()
@@ -981,6 +1038,102 @@ 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)(),
+    -- Background HTTP, behind the "network" permission the player already
+    -- sees.  This is what love.thread is NOT: the worker runs engine code in
+    -- an engine-owned pool, so a mod gets asynchrony without getting a Lua
+    -- state the sandbox cannot reach.  get() hands back an opaque handle;
+    -- poll() is non-blocking, so nothing here can hang a frame.
+    fetch = (function()
+      if mod.manifest.permissionSet.network then
+        return {
+          available = function() return Net.available() end,
+          get = function(_, url, opts) return Net.get(loader, modId, url, opts) end,
+          poll = function(_, handle) return Net.poll(loader, modId, handle) end,
+          release = function(_, handle) return Net.release(loader, modId, handle) end,
+          cancel = function(_, handle) return Net.cancel(loader, modId, handle) end,
+        }
+      end
+      local function refuse()
+        error(('[%s] mod.fetch needs the "network" permission in '
+          .. "manifest.json"):format(modId), 2)
+      end
+      return { available = function() return false end,
+               get = refuse, poll = refuse, release = refuse, cancel = refuse }
+    end)(),
+    -- One-way crash-log reporting to the https URL the manifest declares in
+    -- log_url.  The destination is reviewed at load, not chosen per call, so
+    -- a mod cannot aim this at arbitrary hosts; the response body is never
+    -- returned, and the worker pool bounds the transfer.  Same handle/poll/
+    -- release shape as mod.fetch, so mod.job's sibling patterns carry over.
+    postLog = (function()
+      if mod.manifest.permissionSet.network and mod.manifest.log_url then
+        return function(_, body, opts)
+          return Net.postLog(loader, modId, mod.manifest.log_url, body, opts)
+        end
+      end
+      local function refuse()
+        error(('[%s] mod.postLog needs the "network" permission and a '
+          .. "log_url in manifest.json"):format(modId), 2)
+      end
+      return refuse
+    end)(),
+    -- Background compute, behind the "background" permission.  The worker
+    -- rebuilds this mod's sandbox before loading the script, so a job is the
+    -- one thing love.thread is not: off the main thread without a Lua state
+    -- that escapes the sandbox.  Plain data in, plain data out.
+    job = (function()
+      if mod.manifest.permissionSet.background then
+        return {
+          available = function() return Job.available() end,
+          run = function(_, script, arg, opts)
+            return Job.run(loader, modId, mod.path, script, arg, opts)
+          end,
+          poll = function(_, handle) return Job.poll(loader, modId, handle) end,
+          release = function(_, handle) return Job.release(loader, modId, handle) end,
+          cancel = function(_, handle) return Job.cancel(loader, modId, handle) end,
+        }
+      end
+      local function refuse()
+        error(('[%s] mod.job needs the "background" permission in '
+          .. "manifest.json"):format(modId), 2)
+      end
+      return { available = function() return false end,
+               run = refuse, poll = refuse, release = refuse, cancel = refuse }
+    end)(),
     -- namespaced per mod; M11 backs these with save.modData /
     -- options.modOptions, the shape mods compile against is already final
     save = {
@@ -999,7 +1152,8 @@ function Loader:_api(mod)
         bucket[key] = value
       end,
     },
-    -- Data-only state independent of the vanilla progress checkpoint. The
+    -- Data-only and opaque-byte state independent of the vanilla progress
+    -- checkpoint. The
     -- engine binds version/playthrough/mod scope and portable persistence;
     -- callers never receive paths or a raw filesystem handle.
     storage = {
@@ -1007,6 +1161,10 @@ function Loader:_api(mod)
       selected = function(_, game) return storage:selected(game) end,
       write = function(_, game, key, value) return storage:write(game, key, value) end,
       read = function(_, game, key) return storage:read(game, key) end,
+      writeBytes = function(_, game, key, bytes)
+        return storage:writeBytes(game, key, bytes)
+      end,
+      readBytes = function(_, game, key) return storage:readBytes(game, key) end,
       list = function(_, game, prefix) return storage:list(game, prefix) end,
       delete = function(_, game, key) return storage:delete(game, key) end,
     },
@@ -1088,12 +1246,47 @@ function Loader:_api(mod)
     api.content[alias] = self:_contentApi(mod, self.content[canonical],
       ("the %s registry is deprecated; use %s"):format(alias, canonical))
   end
+  -- A relative path inside this mod, or the mod root when relative is
+  -- omitted.  Empty is the one listing case SafePath.safe rejects on
+  -- purpose (it is not a file), so it is special-cased here.
+  local function ownPath(relative, what)
+    if relative == nil or relative == "" then return mod.path end
+    return SafePath.join(mod.path, relative, what)
+  end
+
+  -- Shallow directory listing, the sandboxed stand-in for
+  -- love.filesystem.getDirectoryItems.  Names only, sorted, never a host
+  -- path.  A missing directory is an empty list, not an error.
+  local function listOwn(_, relative)
+    local dir = ownPath(relative, "mod:list")
+    local fs = loader.fs
+    if not (fs and fs.getDirectoryItems) then return {} end
+    local items = fs.getDirectoryItems(dir) or {}
+    local out = {}
+    for i = 1, #items do out[i] = items[i] end
+    table.sort(out)
+    return out
+  end
+
+  -- love.filesystem.getInfo for a path inside this mod.  type is "file" or
+  -- "directory"; size is set for files.  nil when the path does not exist.
+  local function infoOwn(_, relative)
+    local path = ownPath(relative, "mod:info")
+    local fs = loader.fs
+    if not (fs and fs.getInfo) then return nil end
+    local info = fs.getInfo(path)
+    if not info then return nil end
+    return { type = info.type, size = info.size }
+  end
+
   -- assets keeps the v1 alias to the content accessors and adds the file
   -- helpers on top, so mod.assets.pokemon and mod.assets:image both resolve
   api.assets = setmetatable({
-    path = function(_, relative) return mod.path .. "/" .. relative end,
+    path = function(_, relative)
+      return SafePath.join(mod.path, relative, "mod.assets:path")
+    end,
     image = function(_, relative)
-      local full = mod.path .. "/" .. relative
+      local full = SafePath.join(mod.path, relative, "mod.assets:image")
       local cached = loader.imageCache[full]
       if cached then return cached end
       assert(love and love.graphics,
@@ -1102,15 +1295,20 @@ function Loader:_api(mod)
       loader.imageCache[full] = image
       return image
     end,
+    list = listOwn,
+    info = infoOwn,
   }, { __index = api.content })
+  -- the mod's own directory and nothing above it: PhysFS already refuses a
+  -- climb, but loader.fs is injectable and has no such floor
   function api:read(relative)
-    local path = self.path .. "/" .. relative
-    return loader.fs.read(path)
+    return loader.fs.read(SafePath.join(self.path, relative, "mod:read"))
   end
+  api.list = listOwn
+  api.info = infoOwn
   -- 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
   -- acts on is still being wired when the entry chunk runs
-  local world
+  local world, battle
   setmetatable(api, { __index = function(_, key)
     -- mod.game is the live service owner, resolved per generation the way
     -- mod.world is: src/core/Game.lua's singleton under Gen 1, the Game2
@@ -1119,9 +1317,17 @@ function Loader:_api(mod)
     -- entry chunk runs.  This is what a mod should hold instead of requiring
     -- src.core.Game, which under Gold hands back a table nothing instantiated.
     if key == "game" then return loader:_game() end
+    local game = loader:_game()
+    if key == "battle" then
+      if battle then return battle end
+      local module = game and engineRequire(loader.generation == 2
+        and "src.battle.gen2.BattleAPI" or "src.battle.BattleAPI")
+      if not module then return nil end
+      battle = module.new(game)
+      return battle
+    end
     if key ~= "world" then return nil end
     if world then return world end
-    local game = loader:_game()
     -- one facade name, one arm per generation: Gold's world is not a stack
     -- state and its flags are a bitfield, so the resolution differs even
     -- where the method set does not (src/world/gen2/WorldAPI.lua)
@@ -1149,9 +1355,33 @@ 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
+    local loader = self
+    local compat = LegacyCompat.new({
+      modId = id, modPath = mod.path, fs = self.fs,
+      game = function() return loader:_game() end,
+    })
+    env = Sandbox.envFor({ modId = id, permissions = mod.manifest.permissionSet,
+      compat = compat })
+    self.modEnv[id] = env
+  end
+  return env
+end
+
+-- Which pre-sandbox calls each loaded mod actually took, for the manager's
+-- "needs updating" badge; nil id answers for every mod.
+function Loader:legacyReport(modId)
+  return LegacyCompat.report(modId)
+end
+
 function Loader:_loadMod(mod)
-  local path = mod.path .. "/" .. mod.manifest.entry
-  local chunk, err = self.fs.load(path)
+  local path = SafePath.join(mod.path, mod.manifest.entry, "manifest entry")
+  local chunk, err = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
   if not chunk then error(err or ("unable to load " .. path)) end
   local api = self:_api(mod)
   local result = chunk(api)
@@ -1183,6 +1413,9 @@ function Loader:_rollback(modId)
   self.optionSchemas[modId] = nil
   self.migrations[modId] = nil
   self.modSave[modId] = nil
+  self.stepsQueues[modId] = nil
+  Net.releaseAll(self, modId)
+  Job.releaseAll(self, modId)
 end
 
 -- a mod that explicitly swears it stays link-compatible while writing into a
@@ -1306,13 +1539,30 @@ function Loader:load(data)
   require("src.mods.Builtins").install(self.content, data, self.generation)
   self:_loadState()
   self:_discover()
+  -- Existing installs stored one shared answer.  Once their manifests are
+  -- known, split that answer across every game before the next launcher/game
+  -- toggle can change one independently.  _loadState already used the same
+  -- fallback, so this write cannot change the current boot's result.
+  do
+    local options = SaveData.loadOptions(self.fs)
+    local installed = {}
+    for id, mod in pairs(self.mods) do
+      installed[#installed + 1] = {
+        id = id,
+        experimental = mod.manifest and mod.manifest.experimental == true,
+      }
+    end
+    if SaveData.migrateModEnablement(options, installed) and self.fs.write then
+      SaveData.saveOptions(options, self.fs)
+    end
+  end
   -- Experimental mods stay off until the player opts in: a missing
   -- options.mods entry normally means enabled, but experimental flips that.
   do
     local options = SaveData.loadOptions(self.fs)
-    local modsOpt = options.mods or {}
+    local scope = self:_enableScope()
     for id, mod in pairs(self.mods) do
-      if not self.disabled[id] and modsOpt[id] == nil
+      if not self.disabled[id] and SaveData.modEnabled(options, id, scope) == nil
           and mod.manifest.experimental then
         self.disabled[id] = true
       end
@@ -1349,10 +1599,12 @@ function Loader:load(data)
   -- every touch: a mod captures the facade at file scope, before Game2 has a
   -- save or a world (src/mods/Gen2Compat.lua).
   Gen2Compat.bind(function() return self:_game() end)
-  -- Dev mode wants the permissions tripwire; a Gold boot with mods on it wants
-  -- the Gen 1-only require report, which is the difference between "the mod
-  -- does nothing" and knowing why.  A Gold boot with no mods pays nothing.
-  if self.dev or (self.generation ~= 1 and next(self.mods) ~= nil) then
+  -- Any boot with mods on it needs the gate, because require("io") is how a
+  -- mod would walk out of Sandbox.envFor.  Dev mode adds the permissions
+  -- tripwire on top, and a Gold boot the Gen 1-only require report -- the
+  -- difference between "the mod does nothing" and knowing why.  A boot with no
+  -- mods pays nothing.
+  if self.dev or next(self.mods) ~= nil then
     self:_installDevShim()
   end
   for _, mod in ipairs(ordered) do

src/mods/ManagerState.lua

@@ -8,6 +8,8 @@ local Font = require("src.render.Font")
 local GameVersion = require("src.core.GameVersion")
 local ModTargets = require("src.mods.ModTargets")
 local Runtime = require("src.mods.Runtime")
+local SafePath = require("src.mods.SafePath")
+local Sandbox = require("src.mods.Sandbox")
 local SaveData = require("src.core.SaveData")
 local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
@@ -735,8 +737,7 @@ function ManagerState:toggleGen2Force(m)
   }, apply)
 end
 
--- Where the loader persisted an enable flag: this game's slot once it keeps
--- them per game, the shared flag until then (SaveData.modScope).
+-- Where the loader persists an enable flag: this running game's slot.
 function ManagerState:enableScope()
   return SaveData.modScope((self:targetGame()))
 end
@@ -936,13 +937,18 @@ function ManagerState:schemaFor(m)
   local schema = loader.optionSchemas and loader.optionSchemas[m.id]
   if schema == nil and m.options_schema and m.path
       and loader.fs and loader.fs.load then
-    local chunk = loader.fs.load(m.path .. "/" .. m.options_schema)
-    if chunk then
-      local ok, rows = pcall(chunk)
-      if ok and type(rows) == "table" then
-        schema = rows
-        if loader.optionSchemas then loader.optionSchemas[m.id] = schema end
-      end
+    -- mod-authored code, so it runs in the same sandbox the entry chunk does
+    local ok, rows = pcall(function()
+      local path = SafePath.join(m.path, m.options_schema, "options_schema")
+      local mod = loader.mods and loader.mods[m.id]
+      local env = mod and loader._modEnv and loader:_modEnv(mod)
+        or Sandbox.envFor()
+      local chunk = Sandbox.loadFile(loader.fs, path, env)
+      return chunk and chunk()
+    end)
+    if ok and type(rows) == "table" then
+      schema = rows
+      if loader.optionSchemas then loader.optionSchemas[m.id] = schema end
     end
   end
   return schema
@@ -980,12 +986,45 @@ end
 function ManagerState:buildOptionRows(m, schema)
   local rows = {}
   local modId = m.id
+  local byKey, visibilityKeys = {}, {}
+  for _, row in ipairs(schema) do
+    if type(row) == "table" and type(row.key) == "string" then
+      byKey[row.key] = row
+      local condition = row.visible_if
+      if type(condition) == "table" and type(condition.key) == "string" then
+        visibilityKeys[condition.key] = true
+      end
+    end
+  end
+  local function visible(row)
+    local condition = row.visible_if
+    if condition == nil then return true end
+    if type(condition) ~= "table" or type(condition.key) ~= "string" then
+      return false
+    end
+    local dependency = byKey[condition.key] or { key = condition.key }
+    local value = self:optionValue(modId, dependency)
+    if condition.equals ~= nil then return value == condition.equals end
+    if condition.not_equals ~= nil then return value ~= condition.not_equals end
+    return false
+  end
+  local function refresh(key)
+    if not visibilityKeys[key] then return end
+    local preferred = rows[self.cursor] and rows[self.cursor].id
+    self.optionRows = self:buildOptionRows(m, schema)
+    for index, candidate in ipairs(self.optionRows) do
+      if candidate.id == preferred then self.cursor = index break end
+    end
+    self.cursor = clampIndex(self.cursor, #self.optionRows)
+  end
   for _, row in ipairs(schema) do
     if type(row) ~= "table" or type(row.key) ~= "string" or row.key == ""
         or not OPTION_TYPES[row.type] then
       -- malformed rows are skipped, reported where the errors screen reads
       Runtime.reportError(modId, "options row skipped: "
         .. tostring(type(row) == "table" and (row.key or row.type) or row))
+    elseif not visible(row) then
+      -- Keep the row in the schema and stored options, only hide its menu row.
     elseif row.type == "toggle" then
       rows[#rows + 1] = { id = row.key, label = row.label or row.key,
         value = function()
@@ -993,6 +1032,7 @@ function ManagerState:buildOptionRows(m, schema)
         end,
         step = function()
           self:setOption(modId, row.key, not self:optionValue(modId, row))
+          refresh(row.key)
           return true
         end }
     elseif row.type == "choice" then
@@ -1015,6 +1055,7 @@ function ManagerState:buildOptionRows(m, schema)
           end
           index = clampIndex(index + dir, #choices)
           self:setOption(modId, row.key, choices[index][2])
+          refresh(row.key)
           return true
         end }
     elseif row.type == "number" then
@@ -1030,6 +1071,7 @@ function ManagerState:buildOptionRows(m, schema)
         step = function(_, dir)
           local cur = tonumber(self:optionValue(modId, row)) or 0
           self:setOption(modId, row.key, clamp(cur + dir * (row.step or 1)))
+          refresh(row.key)
           return true
         end,
         activate = function()
@@ -1038,7 +1080,10 @@ function ManagerState:buildOptionRows(m, schema)
             max = row.max or 99,
             start = math.max(1, tonumber(self:optionValue(modId, row)) or 1),
             onDone = function(qty)
-              if qty then self:setOption(modId, row.key, clamp(qty)) end
+              if qty then
+                self:setOption(modId, row.key, clamp(qty))
+                refresh(row.key)
+              end
             end,
           }))
         end }
@@ -1055,6 +1100,7 @@ function ManagerState:buildOptionRows(m, schema)
             default = self:optionValue(modId, row),
             onDone = function(name)
               self:setOption(modId, row.key, name)
+              refresh(row.key)
             end,
           }))
         end }
@@ -1069,6 +1115,8 @@ function ManagerState:buildOptionRows(m, schema)
           self:setOption(modId, row.key, row.default)
         end
       end
+      self.optionRows = self:buildOptionRows(m, schema)
+      self.cursor = clampIndex(self.cursor, #self.optionRows)
       self:notify("DEFAULTS RESTORED")
     end }
   return rows