Merge pull request #1652 from bryanthaboi/dev

skin studio fix

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @bryanthaboi

.github/workflows/ci.yml

@@ -12,10 +12,11 @@ name: ci
 #
 on:
   push:
-    # Integration branch + release branch. PRs already run via pull_request
-    # (any base); this list is only for post-merge push runs.
     branches: [dev, main]
+  # PRs into dev only: a dev -> main ship PR reuses the required checks the
+  # dev push already put on the same head SHA, so it needs no second run.
   pull_request:
+    branches: [dev]
 
 # a force-push while CI is mid-run should cancel the stale run, not queue
 concurrency:
@@ -318,52 +319,10 @@ jobs:
         run: |
           set -euo pipefail
           scripts/build_linux_arm64.sh --version 0.0.0
+      # Shared with the release workflow so shipped images get the same
+      # self-contained / glibc-floor checks as PR builds.
       - name: Verify the AppImage is self-contained and bullseye-compatible
-        run: |
+        run: bash scripts/linux-arm64/verify_appimage.sh dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage
-          set -euo pipefail
-          image="dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage"
-
-          # --appimage-extract needs no FUSE, so this works on a runner
-          # without /dev/fuse and still exercises the real payload.
-          "$image" --appimage-extract >/dev/null
-          for required in AppRun bin/love game.love lib/liblove-11.5.so; do
-            [ -e "squashfs-root/$required" ] \
-              || { echo "::error::AppImage is missing $required"; exit 1; }
-          done
-
-          # Every bundled object must resolve once AppRun's LD_LIBRARY_PATH is
-          # applied; an unresolved soname here is a user-visible launch crash.
-          #
-          # This runs on a HEADLESS runner on purpose, and that is the point.
-          # The first version of this build bundled Debian's SDL2, which
-          # hard-links libpulse/libasound/libX11/libwayland, so it only ever
-          # started on a full desktop -- a bare runner is what exposed it.
-          missing="$(LD_LIBRARY_PATH="$PWD/squashfs-root/lib" \
-            ldd squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
-            | grep 'not found' || true)"
-          [ -z "$missing" ] || { echo "::error::unresolved deps:"; echo "$missing"; exit 1; }
-
-          # Nothing may hard-link a driver, session or audio-stack library:
-          # those must be reached through dlopen so the AppImage runs on a box
-          # with only ALSA, only Wayland, or only KMSDRM.
-          linked="$(for f in squashfs-root/bin/love squashfs-root/lib/*.so*; do
-            objdump -p "$f" 2>/dev/null | awk '/NEEDED/{print $2}'
-          done | sort -u | grep -E '^lib(pulse|asound|X11|wayland|GL|EGL|drm|gbm|xcb|cairo|sndio|dbus)' || true)"
-          [ -z "$linked" ] \
-            || { echo "::error::these must be dlopened, not linked:"; echo "$linked"; exit 1; }
-
-          # The whole point of compiling on bullseye. If a future change moves
-          # the builder to a newer base, the glibc floor silently rises and
-          # every user on an older distro gets "GLIBC_2.xx not found" -- catch
-          # it here instead of in a release.
-          floor="$(objdump -T squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
-            | grep -o 'GLIBC_[0-9.]*' | sort -V | tail -1)"
-          echo "highest required glibc symbol version: $floor"
-          [ -n "$floor" ] \
-            || { echo "::error::found no versioned glibc symbols -- objdump read nothing"; exit 1; }
-          highest="$(printf '%s\n' "$floor" "GLIBC_2.31" | sort -V | tail -1)"
-          [ "$highest" = "GLIBC_2.31" ] \
-            || { echo "::error::AppImage requires $floor, above the bullseye 2.31 floor"; exit 1; }
       - name: Upload the AppImage
         uses: actions/upload-artifact@v7
         with:
@@ -400,7 +359,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - run: sudo apt-get update && sudo apt-get install -y luajit
       - run: python3 -m pip install --upgrade pillow
 
       # the fixture PNGs are committed (they are 8x8 placeholders, not
@@ -421,13 +379,8 @@ jobs:
           print(f"\n{len(paths)} fixture assets valid")
           PY
 
-      # the fingerprint golden is the parity tripwire; prove it still
+      # the fingerprint parity gates (gate_fingerprint / gate_meta_coverage)
-      # matches the dataset on a clean checkout
+      # run in the headless job via run_engine; this job only guards the PNGs
-      - name: fingerprint gate
-        run: luajit tests/engine/gate_fingerprint.lua
-
-      - name: parity-guarantee meta-test
-        run: luajit tests/engine/gate_meta_coverage.lua
 
   # Only the differ is under test here, and the job is named for that.  The
   # capture half of the golden pipeline does not exist: a POKEPORT_DRIVER

.github/workflows/release.yml

@@ -161,6 +161,8 @@ jobs:
           scripts/build_linux_arm64.sh \
             --version "${{ needs.version.outputs.version }}" \
             --game-love .bazinga/work/game.love
+      - name: Verify the AppImage is self-contained and bullseye-compatible
+        run: bash scripts/linux-arm64/verify_appimage.sh "dist/linux-arm64/gen1recomp-${{ needs.version.outputs.version }}-linux-arm64.AppImage"
       - name: Upload Linux arm64 release
         uses: actions/upload-artifact@v7
         with:
@@ -285,7 +287,7 @@ jobs:
           retention-days: 1
 
   release:
-    needs: [version, xbox-uwp, linux-arm64, native-tls-win]
+    needs: [version, love-payload, xbox-uwp, linux-arm64, native-tls-win]
     runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
 
     steps:
@@ -307,6 +309,15 @@ jobs:
           name: gen1tls-win-x64
           path: dist/native/win-x64
 
+      # The same game.love the arm64 AppImage and Xbox UWP builds fused, so
+      # every release asset ships one identical payload (build.sh's own pack
+      # would omit PATCH_NOTES.md and mobile/ios/app-repo.json).
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-release-love
+          path: dist/payload
+
       - name: Import signing certificate into a temporary keychain
         if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
@@ -357,14 +368,36 @@ jobs:
             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
+          scripts/build.sh all --version "${{ needs.version.outputs.version }}" --no-notarize \
+            --game-love dist/payload/game.love
           unzip -l dist/win/gen1recomp-win64.zip | grep -F gen1tls.dll \
             || { echo "::error::Windows zip is missing gen1tls.dll"; exit 1; }
 
-      - name: Build Android
+      - name: Materialize Android release signing key
+        env:
+          KEYSTORE_B64: ${{ secrets.ANDROID_RELEASE_KEYSTORE_B64 }}
         run: |
           set -euo pipefail
-          scripts/build_android.sh --version "${{ needs.version.outputs.version }}"
+          [ -n "$KEYSTORE_B64" ] || {
+            echo "::error::ANDROID_RELEASE_KEYSTORE_B64 is required for a publishable Android update"
+            exit 1
+          }
+          python3 - <<'PY'
+          import base64, os, pathlib
+          encoded = os.environ["KEYSTORE_B64"]
+          path = pathlib.Path(os.environ["RUNNER_TEMP"]) / "gen1recomp-android-release.keystore"
+          path.write_bytes(base64.b64decode(encoded, validate=True))
+          PY
+
+      - name: Build Android
+        env:
+          GEN1RECOMP_ANDROID_KEYSTORE: ${{ runner.temp }}/gen1recomp-android-release.keystore
+          GEN1RECOMP_ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_RELEASE_KEYSTORE_PASSWORD }}
+          GEN1RECOMP_ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_RELEASE_KEY_ALIAS }}
+          GEN1RECOMP_ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_RELEASE_KEY_PASSWORD }}
+        run: |
+          set -euo pipefail
+          scripts/build_android.sh --release --version "${{ needs.version.outputs.version }}"
 
       - name: Install xcbeautify
         run: |
@@ -486,8 +519,8 @@ jobs:
           [ -f "$arm64_appimage" ] || { echo "::error::$arm64_appimage not found (expected from the linux-arm64 job)"; exit 1; }
           cp "$arm64_appimage" "$outdir/gen1recomp-${v}-linux-arm64.AppImage"
           chmod +x "$outdir/gen1recomp-${v}-linux-arm64.AppImage"
-          apk="$(find dist/android/debug -name '*.apk' | head -1)"
+          apk="$(find dist/android/release -name '*.apk' | head -1)"
-          [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
+          [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/release"; exit 1; }
           cp "$apk" "$outdir/gen1recomp-${v}-android.apk"
 
           ipa="dist/ios/gen1recomp++.ipa"

CONTRIBUTING-mods.md

@@ -140,17 +140,17 @@ ship text.
 
 ### 4. `games` (and the legacy `gen2compat`)
 
-Pokemon Gold is Gen 2, and it runs its own battle engine, overworld, script
+Pokemon Gold and Silver are Gen 2, and they run their own battle engine,
-VM and save format. The mod API is shared across both generations (same hook
+overworld, script VM and save format. The mod API is shared across both
-names, same event names, same registry names) but Gold cannot serve all of it
+generations (same hook names, same event names, same registry names) but Gen 2
-yet, so Gen 2 is opt-in. Say which games the mod is for:
+cannot serve all of it yet, so it is opt-in. Say which games the mod is for:
 
 ```json
 "games": ["gen1", "gen2"]
 ```
 
-Each entry is a version id (`"red"`, `"blue"`, `"yellow"`, `"gold"`), a
+Each entry is a version id (`"red"`, `"blue"`, `"yellow"`, `"gold"`,
-generation (`"gen1"`, `"gen2"`) or `"all"`;
+`"silver"`), a generation (`"gen1"`, `"gen2"`) or `"all"`;
 `src/mods/ModTargets.lua` resolves them off `GameVersion.ORDER` so nothing
 restates the game list. `python3 tools/modkit.py scaffold my_mod --games
 gen1,gen2` writes the key for you. The mod still installs to one directory,
@@ -159,10 +159,10 @@ gen1,gen2` writes the key for you. The mod still installs to one directory,
 Absent means Gen 1 only, which is what every mod written before the key existed
 was tested as. `"gen2compat": true` is the legacy spelling, still accepted and
 purely additive (it *adds* the Gen 2 games), so no manifest can lose a game it
-already ran on. On a Gold boot a mod claiming no Gen 2 game is not loaded at
+already ran on. On a Gold or Silver boot a mod claiming no Gen 2 game is not
-all: the manager lists it as `ENABLED (NOT THIS GAME)` and says why, because a
+loaded at all: the manager lists it as `ENABLED (NOT THIS GAME)` and says why,
-mod that half-applies reads as a broken mod. Claim Gen 2 once you have actually
+because a mod that half-applies reads as a broken mod. Claim Gen 2 once you
-run your mod on Gold.
+have actually run your mod on Gold or Silver.
 
 Every token is enforced, per game: the loader gates on the same
 `ModTargets.supports` answer both mod surfaces draw, so `"games": ["blue"]`
@@ -173,7 +173,7 @@ before the key existed changes behavior; list both generations or say `"all"`
 when you mean everywhere.
 
 `docs/mod-api-gen2-compat.md` is the compatibility matrix: what works on Gold
-today (40 of the 46 registries, 40 event and 43 hook names shared with Gen 1,
+and Silver today (40 of the 46 registries, 40 event and 44 hook names shared with Gen 1,
 and 24 Gen 2-only ones), which registries have no Gen 2 home and drop their
 writes with a report, and which hooks and events are still to come.
 `docs/preparing-your-mod-for-gen2.md` is the step-by-step migration guide for a

README.md

@@ -53,18 +53,17 @@ And before you say, "that's not a recomp", you're wrong. Recomp is an acronym. *
 
 ### Watch the latest update video
 
-[![Watch the latest update video](https://img.youtube.com/vi/8IOgqbe4YvA/maxresdefault.jpg)](https://www.youtube.com/watch?v=8IOgqbe4YvA)
+[![Watch the latest update video](https://img.youtube.com/vi/yi7LkWQPKKM/maxresdefault.jpg)](https://youtu.be/yi7LkWQPKKM)
-
 
 This project does not include a ROM, emulate the Game Boy, transpile assembly,
-or download a disassembly. A canonical US Poke Red, Blue, Yellow, or Gold ROM
+or download a disassembly. A canonical US Poke Red, Blue, Yellow, Gold, or
-is the only game content input.
+Silver ROM is the only game content input.
 
 The ROM is verified, used during import, and then released from memory. It is
 not copied into the cache. Later launches load the private generated cache and
-do not ask for the ROM again. Red, Blue, Yellow, and Gold can all be imported
+do not ask for the ROM again. Red, Blue, Yellow, Gold, and Silver can all be
-side by side. Gold is Gen 2 Phase 1 (import + launcher; see
+imported side by side. Gold and Silver are Gen 2 Phase 1 (import + launcher;
-`docs/gold-phase1.md`): the Gen 2 engine is still under construction.
+see `docs/gold-phase1.md`): the Gen 2 engine is still under construction.
 
 ## Quick Start
 
@@ -72,13 +71,14 @@ Open the desktop app. On first boot, choose your legally obtained `.gb` /
 `.gbc` file or drop it onto the window. Import takes a few seconds and the
 game starts automatically.
 
-Only the canonical US Red, Blue, Yellow (1 MiB), and Gold (2 MiB) ROMs are
+Only the canonical US Red, Blue, Yellow (1 MiB), Gold, and Silver (2 MiB)
-accepted. The importer verifies SHA-1 before creating any game data:
+ROMs are accepted. The importer verifies SHA-1 before creating any game data:
 
 - Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
 - Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
 - Yellow: `cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1`
 - Gold: `d8b8a3600a465308c9953dfa04f0081c05bdcb94`
+- Silver: `49b163f7e57702bc939d642a18f591de55d92dae`
 
 The packaged app contains neither a ROM nor pre-extracted game data. Music,
 sound effects, and cries are synthesized while the game runs from compact
@@ -219,7 +219,7 @@ entry: a desktop shortcut per game, a Steam entry, or a handheld frontend.
 
 | Option | Effect |
 | --- | --- |
-| `--game=red` | boot Red, skipping the launcher (`blue` and `yellow` too, or just `r` / `b` / `y`) |
+| `--game=red` | boot Red, skipping the launcher (`blue`, `yellow`, `gold` and `silver` too, or just `r` / `b` / `y` / `g` / `s`) |
 | `--slot=2` | load that save slot; takes a slot number or a slot id |
 | `--launcher` | open the launcher anyway, so you can edit a shortcut you already made |
 

build-linux-arm-sbc.sh

@@ -133,6 +133,8 @@ mkdir -p "$GAME_SRC"
 (cd "$SOURCE_DIR" && zip -q -9 -r "$WORK/game-payload.zip" \
   main.lua conf.lua src libs data assets tools/save-editor \
   tools/rom_manifest.json tools/rom_manifest_blue.json \
+  tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+  tools/rom_manifest_silver.json \
   -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
 if unzip -Z1 "$WORK/game-payload.zip" \
     | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/'; then

build-rg34xxsp.sh

@@ -92,6 +92,7 @@ mkdir -p "$GAME_SRC"
   main.lua conf.lua src libs data assets tools/save-editor \
   tools/rom_manifest.json tools/rom_manifest_blue.json \
   tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+  tools/rom_manifest_silver.json \
   -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
 payload_list="$(unzip -Z1 "$WORK/game-payload.zip")"
 printf '%s\n' "$payload_list" \
@@ -99,6 +100,8 @@ printf '%s\n' "$payload_list" \
   && fail "payload unexpectedly contains generated ROM data"
 printf '%s\n' "$payload_list" | grep -qxF "tools/rom_manifest_gold.json" \
   || fail "payload is missing tools/rom_manifest_gold.json"
+printf '%s\n' "$payload_list" | grep -qxF "tools/rom_manifest_silver.json" \
+  || fail "payload is missing tools/rom_manifest_silver.json"
 unzip -q "$WORK/game-payload.zip" -d "$GAME_SRC"
 rm -f "$WORK/game-payload.zip"
 
@@ -193,6 +196,26 @@ get_controls
 [ -f "${controlfolder}/mod_${CFW_NAME}.txt" ] && source "${controlfolder}/mod_${CFW_NAME}.txt"
 
 GAMEDIR="$SHDIR/gen1recomp"
+# Anbernic stock keeps the launcher and the game folder side by side, so the
+# SHDIR-relative path above is correct there and is tried first.
+#
+# Other firmwares (muOS, and PortMaster's layout on several devices) keep
+# launcher scripts and port data in SEPARATE trees -- scripts under roms/ports,
+# data under ports -- so the sibling folder holds no game.
+#
+# Probe for the BINARY, not the directory: on a split layout this script has
+# usually already created "$SHDIR/gen1recomp/conf" and log.txt on an earlier
+# failed run (see mkdir/tee below), so an existence test matches a decoy of our
+# own making. Stock is unaffected -- its sibling holds the real binary and wins
+# on the first test.
+if [ ! -f "$GAMEDIR/bin/love.aarch64" ]; then
+  for candidate in "/$directory/ports/gen1recomp" \
+                   "/mnt/sdcard/ports/gen1recomp" \
+                   "/mnt/mmc/ports/gen1recomp" \
+                   "/roms/ports/gen1recomp"; do
+    if [ -f "$candidate/bin/love.aarch64" ]; then GAMEDIR="$candidate"; break; fi
+  done
+fi
 CONFDIR="$GAMEDIR/conf"
 mkdir -p "$CONFDIR"
 

data/scripts/celadon_eevee.lua

@@ -25,8 +25,10 @@
 local Menu = require("src.ui.Menu")
 local TextBox = require("src.render.TextBox")
 
--- TMNotebookText (data/text/text_2.asm) has no leading underscore, so the
+-- TMNotebookText (data/text/text_2.asm) has no leading underscore, but the
--- extractor never collects it and the pamphlet's text is inlined.
+-- extractor now collects any top-level label in a dedicated text file
+-- regardless (tools/extract/text.py), so this is the real ROM label --
+-- the literal below is only the fallback for a catalog without it.
 local TM_NOTEBOOK_TEXT = "It's a pamphlet\non TMs.\f...\f"
   .. "There are 50 TMs\nin all.\f"
   .. "There are also 5\nHMs that can be\vused repeatedly.\f"
@@ -70,7 +72,8 @@ return {
       return true
     end
     if fx == 3 and fy == 4 then
-      game.stack:push(TextBox.new(game, TM_NOTEBOOK_TEXT))
+      local text = game.data.text or {}
+      game.stack:push(TextBox.new(game, text.TMNotebookText or TM_NOTEBOOK_TEXT))
       return true
     end
     return false

data/scripts/flavor/bike_shop.lua

@@ -5,8 +5,27 @@
 -- voucher exchange and the BICYCLE/CANCEL price window need more than
 -- command rows (#568).
 
+local TextBox = require("src.render.TextBox")
+
+-- data/events/hidden_events.asm:542
+local BIKE_DISPLAYS = {
+  { 1, 0 }, { 2, 1 }, { 1, 2 }, { 3, 2 }, { 0, 4 }, { 1, 5 },
+}
+
 return {
   BIKE_SHOP = {
+    -- engine/events/hidden_events/new_bike.asm:1
+    onInteract = function(game, ow, fx, fy)
+      for _, c in ipairs(BIKE_DISPLAYS) do
+        if c[1] == fx and c[2] == fy then
+          game.stack:push(TextBox.new(game,
+            (game.data.text or {})._NewBicycleText or "A shiny new\nBICYCLE!"))
+          return true
+        end
+      end
+      return false
+    end,
+
     talk = {
       -- BikeShopMiddleAgedWomanText (pokered/scripts/BikeShop.asm):
       -- always shows the same flavor line, no branching.

data/scripts/flavor/ss_anne_kitchen.lua

@@ -15,10 +15,10 @@ return {
       -- pick the dish: bit 7 set (~50%) -> Salmon du Salad, else bit 4
       -- set (~25%) -> Eels au Barbecue, else (~25%) -> Prime Beef Steak.
       -- The three dish texts (SSAnneKitchenCook7SalmonDuSaladText /
-      -- ...EelsAuBarbecueText / ...PrimeBeefSteakText) aren't extracted
+      -- ...EelsAuBarbecueText / ...PrimeBeefSteakText) have no leading
-      -- into data/generated/text.lua (no leading underscore in
+      -- underscore in pokered/text/SSAnneKitchen.asm, but the extractor
-      -- pokered/text/SSAnneKitchen.asm), so their literal strings are
+      -- collects them regardless (tools/extract/text.py); the literals
-      -- ported here verbatim.
+      -- below are only the fallback for a catalog without them.
       TEXT_SSANNEKITCHEN_COOK7 = function(game, ow, npc, done)
         local t = game.data.text
         push(game, t._SSAnneKitchenCook7MainCourseIsText
@@ -27,13 +27,16 @@ return {
           local dish
           if roll <= 2 then
             -- bit 7 of hRandomAdd set (~50%)
-            dish = "Salmon du Salad!\fLes guests may\ngripe it's fish\vagain, however!"
+            dish = t.SSAnneKitchenCook7SalmonDuSaladText
+              or "Salmon du Salad!\fLes guests may\ngripe it's fish\vagain, however!"
           elseif roll == 3 then
             -- bit 4 set, bit 7 clear (~25%)
-            dish = "Eels au Barbecue!\fLes guests will\nmutiny, I fear."
+            dish = t.SSAnneKitchenCook7EelsAuBarbecueText
+              or "Eels au Barbecue!\fLes guests will\nmutiny, I fear."
           else
             -- neither bit set (~25%)
-            dish = "Prime Beef Steak!\fBut, have I enough\nfillets du beef?"
+            dish = t.SSAnneKitchenCook7PrimeBeefSteakText
+              or "Prime Beef Steak!\fBut, have I enough\nfillets du beef?"
           end
           push(game, dish, done)
         end)

data/scripts/flavor/viridian_city.lua

@@ -60,22 +60,23 @@ M.VIRIDIAN_CITY = {
     -- you want to know about the two kinds of caterpillar Pokemon;
     -- YES -> CATERPIE/WEEDLE description, NO -> "Oh, OK then!".
     -- ViridianCityYoungster2OkThenText and
-    -- ViridianCityYoungster2CaterpieAndWeedleDescriptionText are
+    -- ViridianCityYoungster2CaterpieAndWeedleDescriptionText are defined
-    -- defined without a leading underscore in pokered/text/ViridianCity.asm
+    -- without a leading underscore in pokered/text/ViridianCity.asm, but
-    -- and aren't present in data/generated/text.lua, so we fall back to
+    -- tools/extract/text.py now collects them regardless -- the literal
-    -- the literal strings from pokered.  Those fallbacks have to carry the
+    -- strings below are only the fallback for a catalog without them.
-    -- extractor's markers, not plain newlines: line -> \n, cont -> \v,
+    -- Those fallbacks have to carry the extractor's markers, not plain
-    -- para -> \f.  Spelling cont/para as \n and \n\n put all six lines on
+    -- newlines: line -> \n, cont -> \v, para -> \f.  Spelling cont/para as
-    -- one page with nothing to wait on, so the whole speech scrolled past
+    -- \n and \n\n put all six lines on one page with nothing to wait on,
-    -- without a button press (#250).
+    -- so the whole speech scrolled past without a button press (#250).
     TEXT_VIRIDIANCITY_YOUNGSTER2 = function(game, ow, npc, done)
       local t = text(game)
       ask(game, t._ViridianCityYoungster2YouWantToKnowAboutText
         or "You want to know\nabout the 2 kinds\vof caterpillar\vPOKéMON?", function(yes)
         if yes then
-          push(game, "CATERPIE has no\npoison, but\vWEEDLE does.\fWatch out for its\nPOISON STING!", done)
+          push(game, t.ViridianCityYoungster2CaterpieAndWeedleDescriptionText
+            or "CATERPIE has no\npoison, but\vWEEDLE does.\fWatch out for its\nPOISON STING!", done)
         else
-          push(game, "Oh, OK then!", done)
+          push(game, t.ViridianCityYoungster2OkThenText or "Oh, OK then!", done)
         end
       end)
     end,

data/scripts/gyms.lua

@@ -38,6 +38,22 @@ local function retryTmGive(game, ow, victoryKey, done)
   return true
 end
 
+-- The badge line + its jingle, armed for the battle screen the way
+-- SaveEndBattleTextPointers does (PewterGym.asm:117-119) (#1606)
+local function badgeEndBattleText(game, victoryKey)
+  local reward = victoryKey and require("data.scripts.victories")[victoryKey]
+  if not (reward and reward.dialogue) then return nil end
+  local text = game.data.text or {}
+  local pages = {}
+  for _, label in ipairs(reward.dialogue) do
+    if text[label] and text[label] ~= "" then
+      pages[#pages + 1] = text[label]
+    end
+  end
+  if #pages == 0 then return nil end
+  return table.concat(pages, "\f"), reward.badgeSound
+end
+
 -- scripts/PewterGym.asm PewterGymBrockText (text_asm): CheckEvent
 -- EVENT_BEAT_BROCK branches his dialogue.  Before the badge he prints
 -- _PewterGymBrockPreBattleText and engages the leader battle
@@ -58,7 +74,8 @@ M.PEWTER_GYM.talk = {
         game.data.text._PewterGymBrockPostBattleAdviceText
         or "Go to the GYM in\nCERULEAN and test\nyour abilities!", done))
     else
-      ow:engageTrainer(npc, done)
+      local text, sound = badgeEndBattleText(game, "OPP_BROCK#1")
+      ow:engageTrainer(npc, done, text, nil, sound)
     end
   end,
 }
@@ -91,7 +108,8 @@ local function leaderTalk(beatFlag, adviceLabel, fallback, afterAdvice, victoryK
       game.stack:push(TextBox.new(game,
         game.data.text[adviceLabel] or fallback, finish))
     else
-      ow:engageTrainer(npc, done)
+      local text, sound = badgeEndBattleText(game, victoryKey)
+      ow:engageTrainer(npc, done, text, nil, sound)
     end
   end
 end

data/scripts/oaks_lab.lua

@@ -168,6 +168,7 @@ return {
       { "jump_if_true", "come_see" },
       { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
       { "give_item", "POKE_BALL", 5, false },
+      { "text_sound", "Get_Key_Item" },  -- OaksLab.asm:1060
       { "show_text", "_OaksLabOak1ReceivedPokeballsText" },
       { "show_text", "_OaksLabGivePokeballsExplanationText" },
       { "jump", "end" },

data/scripts/story.lua

@@ -837,13 +837,14 @@ M.SILPH_CO_11F = {
             -- every Silph rocket leaves off-screen (the street rockets are
             -- handled by M.SAFFRON_CITY.onEnter in story4.lua).  Queued, not
             -- run here: the battle's own callbacks are still unwinding, so
-            -- queueScript starts it on the first idle overworld frame --
+            -- queueScript starts it on the first idle overworld frame (#722).
-            -- after the end-battle "Arrgh!!" box victories.lua OPP_GIOVANNI#2
-            -- pushes (#722).
             if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
               ow:queueScript(silphAftermathRows())
             end
-          end, nil, true)
+          end,
+          -- "Arrgh!!" is armed for the battle screen, not the map
+          -- (scripts/SilphCo11F.asm:264-266 SaveEndBattleTextPointers) #1606
+          game.data.text._SilphCo10FGiovanniILostAgainText, true)
         end)
       end))
     return true

data/scripts/story4.lua

@@ -216,7 +216,10 @@ local function dojoMasterGate(game, ow, x, y)
   if not master or ow:trainerDefeated(master) then return false end
   ow.player.facing = "right"
   master:facePlayer(ow.player)
-  ow:engageTrainer(master)
+  -- scripts/FightingDojo.asm:117-119 SaveEndBattleTextPointers (#1606)
+  ow:engageTrainer(master, nil,
+    ((game.data or {}).text or {})._FightingDojoKarateMasterDefeatedText,
+    nil, nil, false)
   return true
 end
 
@@ -516,7 +519,17 @@ M.ROUTE_24 = {
           push(game, text(game)._Route24CooltrainerM1YouCouldBecomeATopLeaderText,
             done)
         else
-          ow:engageTrainer(npc, done)
+          -- scripts/Route24.asm:125
+          ow:engageTrainer(npc, function()
+            if ow:trainerDefeated(npc) then
+              -- scripts/Route24.asm:62
+              push(game,
+                text(game)._Route24CooltrainerM1YouCouldBecomeATopLeaderText,
+                done)
+            else
+              done()
+            end
+          end, text(game)._Route24CooltrainerM1DefeatedText, true)
         end
       end
       if not flags.EVENT_GOT_NUGGET then

data/scripts/story5.lua

@@ -122,9 +122,8 @@ M.CINNABAR_LAB_METRONOME_ROOM = {
 -- TM42 Dream Eater (scripts/ViridianCity.asm, the fisher).  The fisher's
 -- YouCanHaveThisText prints before GiveItem, so this gift needs a pre
 -- text (#775).  Like the SilphCo2F worker (#393) that label carries no
--- leading underscore, and on Red it sits outside the extractor's symbol
+-- leading underscore; tools/extract/text.py now collects it regardless,
--- set, so the literal from text/ViridianCity.asm rides along as the
+-- so preFallback below is just the safety net for a catalog without it.
--- fallback; Yellow resolves the ROM string instead.
 M.VIRIDIAN_CITY = {
   talk = {
     TEXT_VIRIDIANCITY_FISHER = gift({
@@ -146,9 +145,11 @@ M.SILPH_CO_2F = {
   talk = {
     TEXT_SILPHCO2F_SILPH_WORKER_F = gift({
       flag = "EVENT_GOT_TM36", item = "TM_SELFDESTRUCT",
-      -- the label carries no leading underscore: pokered keeps this one in
+      -- the label carries no leading underscore (#393); collected like any
-      -- the script bank, not the far-text bank (#393)
+      -- other text/*.asm label now, preFallback is just the safety net
       pre = "SilphCo2FSilphWorkerFPleaseTakeThisText",
+      preFallback = "Eeek!\nNo! Stop! Help!\fOh, you're not\nwith TEAM ROCKET."
+        .. "\vI thought...\vI'm sorry. Here,\vplease take this!",
       received = "_SilphCo2FSilphWorkerFReceivedTM36Text",
       explain = "_SilphCo2FSilphWorkerFTM36ExplanationText",
       noRoom = "_SilphCo2FSilphWorkerFTM36NoRoomText",
@@ -646,27 +647,29 @@ end
 local rocketRows = {
   { "face_player" },                                           -- 1
   { "check_flag", "EVENT_GOT_TM28" },                          -- 2
-  { "jump_if_true", 15 },                                      -- 3 → CeruleanHideRocket
+  { "jump_if_true", 16 },                                      -- 3 → CeruleanHideRocket
   { "check_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },        -- 4
-  { "jump_if_true", 9 },                                       -- 5
+  { "jump_if_true", 10 },                                      -- 5
   { "show_text", "_CeruleanCityRocketText" },                  -- 6
-  { "start_battle", "trainer", "OPP_ROCKET", 5 },              -- 7
+  -- scripts/CeruleanCity.asm:297 SaveEndBattleTextPointers
-  { "jump_if_false", "end" },                                  -- 8
+  { "save_end_battle_text", "_CeruleanCityRocketIGiveUpText" }, -- 7
-  { "show_text", "_CeruleanCityRocketIllReturnTheTMText" },    -- 9
+  { "start_battle", "trainer", "OPP_ROCKET", 5 },              -- 8
-  { "set_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },          -- 10
+  { "jump_if_false", "end" },                                  -- 9
-  { "give_item", "TM_DIG", 1, false },                         -- 11 (row 13 prints)
+  { "show_text", "_CeruleanCityRocketIllReturnTheTMText" },    -- 10
-  { "set_flag", "EVENT_GOT_TM28" },                            -- 12
+  { "set_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },          -- 11
-  { "show_text", "_CeruleanCityRocketReceivedTM28Text" },      -- 13
+  { "give_item", "TM_DIG", 1, false },                         -- 12 (row 14 prints)
-  { "show_text", "_CeruleanCityRocketIBetterGetMovingText" },  -- 14
+  { "set_flag", "EVENT_GOT_TM28" },                            -- 13
-  { "fade", "out" },                                           -- 15 GBFadeOutToBlack
+  { "show_text", "_CeruleanCityRocketReceivedTM28Text" },      -- 14
+  { "show_text", "_CeruleanCityRocketIBetterGetMovingText" },  -- 15
+  { "fade", "out" },                                           -- 16 GBFadeOutToBlack
   -- CeruleanHideRocket while black: GUARD1 (28,12) appears, GUARD2
   -- (27,12) and the ROCKET go.  GUARD2 blocks the trashed-house south
   -- door neighbour -- the swap reconnects the city (Bill's ticket does
   -- the same in story.lua; either route is enough).
-  { "show_object", "CERULEAN_CITY", "CERULEANCITY_GUARD1" },   -- 16
+  { "show_object", "CERULEAN_CITY", "CERULEANCITY_GUARD1" },   -- 17
-  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_GUARD2" },   -- 17
+  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_GUARD2" },   -- 18
-  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_ROCKET" },   -- 18
+  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_ROCKET" },   -- 19
-  { "fade", "in" },                                            -- 19 GBFadeInFromBlack
+  { "fade", "in" },                                            -- 20 GBFadeInFromBlack
 }
 
 M.CERULEAN_CITY = {

data/scripts/story6.lua

@@ -7,9 +7,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
 
 -- PrintText on a text_end string returns with the box still drawn and
@@ -236,7 +236,6 @@ M.CINNABAR_GYM = {
           if yes == machine.yes then
             -- CinnabarGymQuizCorrectText: item jingle, then the gate
             -- slides open (SFX_GO_INSIDE) if it was still locked
-            Sound.play(game.data, "Get_Item1")
             push(game, t._CinnabarGymQuizCorrectText
               or "You're absolutely\ncorrect!\fGo on through!", function()
               if not game.save.flags[gymGateFlag(index)] then
@@ -244,7 +243,9 @@ M.CINNABAR_GYM = {
                 Sound.play(game.data, "Go_Inside")
               end
               applyGymGates(game, ow)
-            end)
+            end, { preSound = function()
+              return Sound.play(game.data, "Get_Item1")
+            end })
             return
           end
           Sound.play(game.data, "Denied")

data/scripts/yellow_beach_house.lua

@@ -17,9 +17,9 @@ local function surfingPikachu(game)
   return nil
 end
 
-local function push(game, text, done)
+local function push(game, text, done, opts)
   local TextBox = require("src.render.TextBox")
-  game.stack:push(TextBox.new(game, text, done))
+  game.stack:push(TextBox.new(game, text, done, opts))
 end
 
 -- the two-variant posters: the surf-capable line once a surfing
@@ -69,11 +69,11 @@ return {
 
       TEXT_SUMMERBEACHHOUSE_PIKACHU = function(game, ow, npc, done)
         local t = game.data.text
+        -- scripts/SummerBeachHouse.asm:68
         push(game, t._SummerBeachHousePikachuText or "PIKACHU: Pikaa!",
-          function()
+          done, { auto = { wait = true, delay = 0, sound = function()
-            require("src.core.Sound").playCry(game.data, "PIKACHU")
+            return require("src.core.Sound").playCry(game.data, "PIKACHU")
-            done()
+          end } })
-          end)
       end,
 
       TEXT_SUMMERBEACHHOUSE_POSTER1 = poster(1),

docs/linux-arm64-build.md

@@ -105,8 +105,9 @@ trixie.
 This is a statement about the *compile environment*, not about where the
 artifact runs — building on your own newer distro would silently raise that
 floor and strand every user on an older one, with no symptom until they
-download it. CI enforces the floor: `linux-arm64-build` fails if the highest
+download it. `scripts/linux-arm64/verify_appimage.sh` enforces the floor in
-required glibc symbol version climbs above 2.31.
+both CI (`linux-arm64-build`) and the release workflow: the build fails if
+the highest required glibc symbol version climbs above 2.31.
 
 ### Why five libraries are built from source
 
@@ -172,13 +173,15 @@ Three jobs, path-gated on `scripts/build_linux_arm64.sh`,
   exclude list still classifies known sonames correctly, that AppRun still
   launches `game.love` with `--fused`, and that the host-arch guard actually
   fires. Needs no container and no arm64 machine.
-- **`linux-arm64-build`** (`ubuntu-24.04-arm`) — the real build, then extracts
+- **`linux-arm64-build`** (`ubuntu-24.04-arm`) — the real build, then
-  the artifact and asserts the layout, that every bundled object resolves
+  `scripts/linux-arm64/verify_appimage.sh` extracts the artifact and asserts
-  under AppRun's `LD_LIBRARY_PATH`, and that the glibc floor is still ≤ 2.31.
+  the layout, that every bundled object resolves under AppRun's
-  Uploads the AppImage for 7 days.
+  `LD_LIBRARY_PATH`, and that the glibc floor is still ≤ 2.31. Uploads the
+  AppImage for 7 days.
 - **release** — `linux-arm64` runs on `ubuntu-24.04-arm`, reuses the shared
-  `game.love` from the `love-payload` job, and the AppImage is staged and
+  `game.love` from the `love-payload` job, runs the same
-  published like every other release asset.
+  `verify_appimage.sh` checks on the shipped image, and the AppImage is
+  staged and published like every other release asset.
 
 Unlike the Switch job, none of this needs secrets or self-hosted hardware, so
 it runs on fork PRs too.

docs/mod-api-gen2-compat.md

@@ -24,7 +24,7 @@ The short version, for an author deciding what to write:
   merged.** The write is taken, dropped, and named once per mod in the same
   error feed the mod manager shows -- in both directions, so a Red boot writing
   to `decorations` is told exactly as a Gold boot writing to `map_scripts` is.
-- **40 event names and 43 hook names have a call site in both generations**, so
+- **40 event names and 44 hook names have a call site in both generations**, so
   one subscription serves both games. `tests/engine/gate_gen2_mod_api.lua`
   reads those names back out of the source and fails if a site is renamed or
   deleted on either side, and fails again if a new shared site appears without
@@ -55,9 +55,10 @@ The short version, for an author deciding what to write:
 ```
 
 `games` is an optional array of version ids (`"red"`, `"blue"`, `"yellow"`,
-`"gold"`), generations (`"gen1"`, `"gen2"`, case-insensitive) or `"all"`.
+`"gold"`, `"silver"`), generations (`"gen1"`, `"gen2"`, case-insensitive) or
-`src/mods/ModTargets.lua` resolves the tokens off `GameVersion.ORDER` and
+`"all"`. `src/mods/ModTargets.lua` resolves the tokens off `GameVersion.ORDER`
-`GameVersion.generation`, so nothing anywhere restates the game list.
+and `GameVersion.generation`, so nothing anywhere restates the game list.
+`"gen2"` now expands to both Gold and Silver.
 `Manifest.validate` stores the resolved, ORDER-sorted ids on `manifest.games`
 and **derives** `manifest.gen2compat` from them, which is the one field the
 loader's gate reads.
@@ -538,7 +539,8 @@ gains a field instead of the name gaining a prefix.
   `battle.damage_dealt`, `battle.fainted`, `battle.status_inflicted`,
   `battle.battler_switched`, `battle.ball_thrown`, `battle.exp_gained`,
   `pokemon.level_up`, `pokemon.move_learned`; hooks `battle.damage`,
-  `battle.crit`, `battle.accuracy`, `battle.turn_order`,
+  `battle.crit`, `battle.accuracy`, `battle.charge_required`,
+  `battle.turn_order`,
   `battle.enemy_action`, `battle.run`, `battle.exp_award`, `exp.gain`,
   `catch.rate`, `trainer.party`, `battle.overlay`, `battle.low_health_alarm`,
   `battle.catch_exp`, `battle.bottom_ui_visible`,

docs/modding.md

@@ -81,7 +81,7 @@ Every mod contains a root `manifest.json` defining its metadata, supported games
 | `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"]`. |
+| `games` | `array` | Supported game versions: `["gen1"]`, `["gen2"]`, `["red"]`, `["blue"]`, `["yellow"]`, `["gold"]`, `["silver"]`, 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. |
@@ -122,21 +122,40 @@ Each object requires a stable `id`, a display `name`, a destination `file`
 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
+per-import ceiling when an exact size is not appropriate. The engine hard limit
-has an engine-enforced 128 MiB ceiling and is rejected before hashing when its
+is 2 GiB. Imports above 128 MiB receive an explicit free-space confirmation and
-filesystem reports an invalid size.
+use the launcher's streaming large-file path rather than being materialized as
+one Lua string.
 
 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
+because its manifest names the same digest. Small sources can still be read
-example `mod:read("baseroms/stadium2.z64")`; no host path or new filesystem
+with the existing scoped `mod:read` API, for example
+`mod:read("baseroms/stadium2.z64")`. For large sources, prefer the bounded
+`mod.imports` facade described below; no host path or new general 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.
 
+#### Bounded access to validated imports
+
+A loaded mod can address only ids declared by its own `required_imports` or
+`optional_imports` arrays:
+
+```lua
+local info, err = mod.imports:info("stadium2")
+local header, err = mod.imports:read("stadium2", 0, 4096)
+```
+
+`read` uses zero-based offsets and is capped at 8 MiB per call. The engine
+rechecks the stored import before exposing it, seeks into the engine-owned
+copy, and never gives the mod a host path or file handle. This is intended for
+large source formats whose table/index can be parsed with small reads before
+selectively reading the payloads a transform actually needs.
+
 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
@@ -441,6 +460,28 @@ default** (1x front, 2x back).
   ball-to-pic grow multiplies your scale through each stage, so a rescaled
   mon still grows into place from the ball, grounded the whole way.
 
+## Installation-scoped generated cache
+
+Generated data derived from a validated user source often belongs to the mod
+installation rather than to one Pokémon save. `mod.cache` is that namespace:
+
+```lua
+local ok, err = mod.cache:write("extract/v1/arena.bin", encodedArena)
+local bytes, err = mod.cache:read("extract/v1/arena.bin")
+local info = mod.cache:info("extract/v1/arena.bin")
+mod.cache:delete("extract/v1/arena.bin")
+```
+
+The physical root is engine-owned (`mod_cache/<mod-id>/`) and never exposed to
+the mod. Keys are safe relative paths and a single write is capped at 64 MiB.
+The cache does not rewind with checkpoints and is not scoped to game version,
+slot, or playthrough. The mod owns its generated format, fingerprints, rebuild
+policy, and completion marker; the engine treats the bytes as opaque data.
+
+Use `mod.storage` instead when the data belongs to one playthrough. Use
+`mod.cache` when it is a reproducible installation artifact that can be rebuilt
+from a declared user source.
+
 ## Durable tool storage and runtime checkpoints
 
 `mod.save` remains the right place for state that should travel with the next
@@ -633,6 +674,17 @@ 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.
 
+Both battle engines expose the guarded `battle.charge_required` hook when a
+charge-capable move is selected for its initial turn and the active ruleset
+would otherwise charge it. The wrapper receives `(next, ctx)`, where `ctx` is
+`{ battle, user, target, move, charge = true, isCalled }`. Return `false` to
+skip only that initial charge and continue through the ordinary move pipeline;
+call `next(ctx)` to keep it. The hook does not run for the release turn or when
+the active ruleset already skips charging (for example, Gold Solarbeam in
+sun). PP use, accuracy, damage, animation, and secondary effects remain owned
+by the engine. With no subscriber, the vanilla decision runs without building
+the hook context.
+
 ## Developer console
 
 Boot with developer mode on to unlock the in-game console and hot-reload

docs/new-features.md

@@ -11,10 +11,13 @@ Features intentionally added beyond the original Pokémon Red, Blue, and Yellow
 * **Persistent custom options** stored separately from game saves
 * **Optional widescreen battle layout**
 * **Mobile touch controls** with editable layouts, vibration, and orientation settings
-* **Touch skins** in RetroArch overlay format, with bezel art, per-button press states, and Super Game Boy borders
+* **Screen position setting** (center, upper, top) shared across all games, for clamp-on controllers that cover the lower screen
+* **Touch skins** in RetroArch overlay format and Delta `.deltaskin` (including PDF-wrapped bezel art), with per-button press states and Super Game Boy borders
 * **Pokédex diploma and printer image exports**
+* **Shareable mod lists** over save sync, optionally carrying the options set for those mods, which the receiving device is asked about before anything is changed
 
 ## Gen 2 Specifics
 
+* **Pokémon Silver** as an importable, launcher-selectable version alongside Gold
 * **Mod manager** with Gen 1 mod adapters, per-game targeting, and `modkit gen2check`
 * **Followers** for mods, plus Gen 2-only registries and hooks

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

@@ -176,7 +176,7 @@ something the filesystem encodes.
 
 | token | means |
 | --- | --- |
-| `"red"`, `"blue"`, `"yellow"`, `"gold"` | that one game (a version id from `GameVersion.ORDER`) |
+| `"red"`, `"blue"`, `"yellow"`, `"gold"`, `"silver"` | that one game (a version id from `GameVersion.ORDER`) |
 | `"gen1"`, `"gen2"` | every game of that generation (case-insensitive; `"gen 2"` also parses) |
 | `"all"` | every game this engine has |
 

docs/required-to-function.md

@@ -1,7 +1,8 @@
 # What This Port Requires
 
 The packaged desktop app requires one user-supplied input on first boot: a
-canonical 1 MiB US Pokemon Red, Blue, or Yellow ROM.
+canonical 1 MiB US Pokemon Red, Blue, or Yellow ROM, or a canonical 2 MiB US
+Pokemon Gold or Silver ROM.
 
 The importer verifies the SHA-1 for the game (see `src/core/GameVersion.lua`
 for specific hashes). Other revisions and Virtual Console releases are rejected
@@ -15,7 +16,8 @@ Python and Pillow are not required by the packaged app.
 
 Assembly removes high-level names and some relationships that the Lua port
 needs. The version-specific files `tools/rom_manifest.json`,
-`tools/rom_manifest_blue.json`, and `tools/rom_manifest_yellow.json` therefore
+`tools/rom_manifest_blue.json`, `tools/rom_manifest_yellow.json`,
+`tools/rom_manifest_gold.json`, and `tools/rom_manifest_silver.json` therefore
 contain:
 
 - the ROM symbol addresses actually read by the extractor

docs/rfcs/0008-streamed-mod-imports-and-install-cache.md

@@ -0,0 +1,141 @@
+# RFC 0008 — Streamed mod imports and installation-scoped generated cache
+
+## Motivation
+
+`required_imports`/`optional_imports` can now describe files up to 2 GiB, but
+the existing launcher and public mod API still assume imported bytes are small:
+
+* the Windows desktop picker stages a selected required import through a fixed
+  `%TEMP%/pokeport_required_import.bin` path before validation;
+* the fallback import path materializes the selected file as one Lua string;
+* after validation a mod can only use `mod:read("baseroms/...")`, which also
+  materializes the whole file;
+* `mod.storage` is intentionally scoped to one Pokémon playthrough, so it is
+  not an appropriate home for a one-time generated asset cache shared by every
+  save using the same installed mod.
+
+This makes optical-disc-sized user sources impractical even though the manifest
+schema already accepts them. A failed temporary staging copy can also turn a
+valid large source into a smaller temporary file and produce a misleading
+"wrong file size" rejection.
+
+A mod should be able to consume its own already-validated source incrementally
+and compile derived runtime data once, without receiving a host path or general
+filesystem access.
+
+## Decision being extended
+
+This extends the same legal/sandbox direction as **D11 asset transforms**
+(`src/mods/AssetTransform.lua`): mods distribute recipes and derive bytes from
+user-owned sources rather than shipping ROM-derived data. It also follows the
+**D14 parity-gate** contract referenced by `tests/harness.lua` and
+`tests/engine/gate_meta_coverage.lua` (the `21-testing-and-ci` plan): additive
+extension points ship public-API coverage, no-mod parity coverage, and docs in
+the same change.
+
+The historical D11 plan document is referenced by source comments but is not
+present in the current repository tree; this RFC is the checked-in design
+record for the new surface.
+
+## Exact API delta
+
+No manifest field changes. Existing `required_imports` and `optional_imports`
+remain the declaration/validation authority.
+
+Two additive facades are added to the `mod` object.
+
+### `mod.imports`
+
+```lua
+local info, err = mod.imports:info("source_id")
+local bytes, err = mod.imports:read("source_id", offset, length)
+```
+
+* `source_id` must name an import declared by the calling mod.
+* the import is rechecked through `RequiredImports.validateStored` before it is
+  exposed, so missing, replaced, or invalid optional imports are not readable;
+* `offset` and `length` are zero-based byte coordinates;
+* one read is capped at 8 MiB;
+* no host path or file handle is returned;
+* production reads seek into the engine-owned stored copy instead of reading
+  the whole source.
+
+`info()` returns declaration metadata plus stored size. It does not expose a
+host path.
+
+### `mod.cache`
+
+```lua
+mod.cache:write("extract/v1/model.bin", bytes)
+local bytes = mod.cache:read("extract/v1/model.bin")
+local info = mod.cache:info("extract/v1/model.bin")
+mod.cache:delete("extract/v1/model.bin")
+```
+
+The cache is rooted at `mod_cache/<mod-id>/`, follows the engine persistence
+backend, and is independent of game version, launcher slot, and playthrough.
+Paths are checked with `SafePath`; `..`, absolute paths, drive paths, and other
+escapes remain unavailable. A single cache write is capped at 64 MiB so large
+generated datasets are naturally split into independently replaceable files.
+
+The engine does not interpret cache bytes. Mods own generated-format versioning,
+fingerprints, transactional completion markers, and rebuild policy.
+
+## Launcher/import transport delta
+
+For large raw required imports:
+
+1. desktop pickers return the original selected path instead of staging it
+   through a fixed temporary file;
+2. the engine opens that source itself;
+3. bytes are copied directly to the existing engine-owned
+   `mods/<id>/baseroms/<file>` destination in 4 MiB chunks;
+4. MD5 is updated incrementally during the copy;
+5. the normal size/MD5 validation receipt is written only after the complete
+   destination passes validation;
+6. partial destinations are removed on short reads, write failure, size
+   mismatch, or digest mismatch.
+
+N64 imports stay on the existing canonicalization path because byte-order and
+copier-header normalization require transformation rather than a raw copy.
+
+If a validation receipt for an already-stored large raw import is missing, the
+engine rebuilds it with streaming MD5 rather than a whole-file read.
+
+## Backward compatibility / migration
+
+**Existing mods do nothing.** This is additive.
+
+* manifest v1/v2 fields are unchanged;
+* `mod:read`, `mod.storage`, registries, events, hooks, and legacy compatibility
+  retain their existing behavior;
+* small required imports retain the existing in-memory validation path;
+* N64 imports retain canonicalization and existing accepted byte orders;
+* a mod that never touches `mod.imports` or `mod.cache` creates no new cache
+  files and observes no new behavior.
+
+The mod API integer is not bumped because no existing member changes meaning or
+shape.
+
+## Security and legal posture
+
+The launcher remains the authority that validates user-supplied bytes. The new
+facade narrows access rather than widening it: a mod can read only ids declared
+in its own manifest, only after validation, and only in bounded ranges. It does
+not receive host paths, `io`, or a raw filesystem handle.
+
+`mod.cache` is writable only beneath the calling mod's generated-cache root.
+Nothing in this RFC permits packaged ROM-derived bytes; `modkit lint/pack`
+continue to enforce the existing legal posture.
+
+## Parity guarantee
+
+The change ships with:
+
+* a no-mod/API-v1 parity test proving an empty load and an existing v1-style
+  `mod:read` load do not create cache data or change the old surface;
+* a public mod-API test that reaches `mod.imports` and `mod.cache` through a
+  real `Loader` load, including bounded reads, undeclared/missing imports,
+  cache isolation, and traversal rejection;
+* incremental MD5 vectors and a large-import streaming regression test;
+* the existing engine suite, required-import suite, and mod lint gates.

docs/rfcs/0011-battle-charge-required.md

@@ -0,0 +1,92 @@
+# RFC 0011: Charge-required battle hook
+
+## Status
+
+Proposed.
+
+## Motivation
+
+A battle-mechanics mod can change damage through `battle.damage` and register
+move effects, but it cannot conditionally skip the first turn of an existing
+charge move. In Gen 1, the engine decides and stores the charge continuation
+before any public effect callback can run. Reaching into `user.charging`,
+`user.chargeReady`, or generation-specific volatile state is private,
+checkpoint-fragile, and would require a mod to duplicate move-pipeline policy.
+
+Weather is the immediate example: a portable sun rule needs Solarbeam to
+resolve on selection while leaving Fly, Dig, PP use, hit resolution, animation,
+and secondary effects to the engine. The capability is generic and useful to
+other ruleset and move-mechanics mods.
+
+## Decision and plan extended
+
+This implements **D-AT-002: charge-stage policy remains mod authority through a
+generic guarded engine decision seam**. The consuming design is tracked in the
+Adaptive Trainers implementation plan,
+[`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 8. The delta follows the additive, guarded hook convention documented by
+Route B in `CONTRIBUTING-mods.md`; it contains no weather, move-id, trainer, or
+Adaptive Trainers policy.
+
+## Exact API delta
+
+Both the Gen 1 and Gen 2 battle engines add this guarded hook:
+
+```lua
+mod.hooks:wrap("battle.charge_required", function(next, ctx)
+  -- ctx = {
+  --   battle = live battle controller,
+  --   user = attacking battler,
+  --   target = defending battler,
+  --   move = merged move record,
+  --   charge = true,
+  --   isCalled = false,
+  -- }
+  if should_resolve_now(ctx) then return false end
+  return next(ctx)
+end)
+```
+
+The call site is the initial-use charge decision, after announcement and PP
+handling but before charge state, invulnerability, charge animation, or charge
+text is created. It runs only when the active engine rules would otherwise
+require a charge. It does not run on the release turn. Returning exactly
+`false` skips that initial charge and continues through the engine-owned move
+pipeline. Any other downstream return preserves the charge. `isCalled` is true
+when Metronome or Mirror Move selected the move.
+
+Gold keeps its native sun decision first, so Solarbeam in native sun already
+requires no charge and does not invoke the hook. Gen 1 link battles use the
+shared Gen 1 move pipeline and therefore receive the same seam; normal link
+mod-compatibility rules continue to govern deterministic peers.
+
+The hot path first calls `Runtime.wantsHook("battle.charge_required")`. With no
+subscriber, no hook payload table is allocated and the existing branch runs
+unchanged.
+
+## Migration and compatibility
+
+Existing mods change nothing. The hook name and payload are additive. With no
+wrapper installed, Red, Blue, Yellow, Gold, and Silver retain their previous
+charge state, PP use, text, animation, accuracy, damage, and native weather
+behavior. Existing charge-move data and effect records require no migration.
+
+A mod adopting the seam should call `next(ctx)` unless it deliberately wants to
+skip this charge. It should not mutate private charge fields or re-run the move.
+
+## Verification
+
+- `tests/engine/battle_charge_required.lua` exercises the real Gen 1 and Gen 2
+  engines through a sandboxed public mod, including false-to-skip, next-to-keep,
+  release-turn behavior, called-move PP semantics, shared payload shape, and
+  native Gold sun behavior.
+- The same test proves no-mod charge/release parity and replaces
+  `Runtime.call` with a sentinel behind a false `Runtime.wantsHook` guard.
+- `tests/engine/gate_hooks.lua` discovers the new catalog name and proves empty
+  chains preserve vanilla values and allocation behavior.
+- `tests/engine/gate_gen2_mod_api.lua` requires a guarded site in both
+  generations and keeps the compatibility reference list complete.
+
+## Deprecation etiquette
+
+Nothing is removed, renamed, superseded, or deprecated.

docs/skin-studio.md

@@ -1,11 +1,11 @@
 # Touch skins and the Skin Studio
 
 A **skin** replaces the on-screen controls wholesale: a bezel image, a
-control layout, and the rectangle the Game Boy screen is drawn into. Engine:
+control layout, and a screen-placement anchor. Engine:
 `src/core/TouchSkin.lua` (model, parsers, zip export), `src/core/TouchControls.lua`
-(draw and input), `src/render/Renderer.lua` (the screen viewport),
+(draw and input), `src/render/Renderer.lua` (screen placement),
 `src/core/DeltaSkin.lua` (Delta `.deltaskin` import and export),
-`src/ui/SkinStudio.lua` (the desktop editor). Tests:
+`src/ui/SkinStudio.lua` (the responsive skin editor). Tests:
 `tests/engine/touch_skin_test.lua`, `tests/engine/skin_studio_test.lua`,
 `tests/engine/skin_studio_ux.lua`,
 `tests/engine/skin_studio_image_import.lua`,
@@ -13,8 +13,10 @@ control layout, and the rectangle the Game Boy screen is drawn into. Engine:
 `tests/engine/launcher_skins_tab.lua`,
 `tests/engine/launcher_skins_ux.lua`.
 
-Skins are picked in the launcher's **Skins** tab, which also imports them and
+The launcher's **Skins** tab imports skins, shows the enabled skin, exports it,
-opens the studio. `options.touchControls.skin` holds the folder name.
+and is the one place that turns skin use off. **My Skins** holds the visual
+grid, pagination, edit, delete and per-skin export actions.
+`options.touchControls.skin` holds the folder name.
 
 ## Formats
 
@@ -30,7 +32,7 @@ as-is. Supported keys:
 | `overlays` | page count |
 | `overlayN_name` | page name, the target of `next_target` |
 | `overlayN_overlay` | bezel image |
-| `overlayN_full_screen` | stretch the page to the window |
+| `overlayN_full_screen` | cover the window with the page without deforming its artwork |
 | `overlayN_rect` | page placement, default `0,0,1,1` |
 | `overlayN_aspect_ratio` | design aspect; the overlay letterboxes to it even when full screen |
 | `overlayN_range_mod`, `overlayN_alpha_mod` | desc defaults |
@@ -95,18 +97,22 @@ auto-rotates like a RetroArch one. Item `frame` rects are top-left plus size in
 `extendedEdges` merge per key into the reach fields; `mask: "circle"` becomes a
 radial hitbox. A `dpad` or `thumbstick` item expands into the 3x3 grid, so the
 corners fire two directions. `screens[1].outputFrame` (or the legacy
-`gameScreenFrame`) becomes the screen cutout, and the skin stretches to the
+`gameScreenFrame`) becomes the screen cutout. A portrait page with neither
-window the way Delta does rather than letterboxing. Host functions map to
+keeps `mappingSize` as the overlay aspect, sits at the bottom of the
+window, and puts the Game Boy picture in the leftover space above -- the
+usual GBA4iOS controller-deck layout. Pages that name a screen rect fit the
+game into it. Host functions map to
 engine hotkeys: `menu` to `menu_toggle`, `fastForward` to
 `hold_fast_forward`, `toggleFastForward` to `toggle_fast_forward`;
 `quickSave` and `quickLoad` have nothing to bind to and drop to decoration.
 Both `com.rileytestut.delta.game.*` and Manic's `public.aoshuang.game.*`
 identifiers are accepted, and a non Game Boy system warns instead of failing.
 
-PDF artwork is the one thing that does not come across: Delta's own templates
+PDF artwork is usually a JPEG wrapped so iOS can scale it (Delta's
-are all-PDF and this engine has no rasterizer, so such a skin is refused with
+Image-to-PDF skins, Preview exports, and the like). Import extracts that
-the message asking for a PNG version. GBA4iOS `.gbcskin` / `.gbaskin` files are
+JPEG and draws it; a true vector PDF with no embedded image is still refused,
-an older, incompatible schema and are refused by name.
+with a message asking for a PNG version. GBA4iOS `.gbcskin` / `.gbaskin` files
+are an older, incompatible schema and are refused by name.
 
 ## Bindable actions
 
@@ -131,7 +137,7 @@ to decoration and never captures a touch.
 As an extension to the format, `key:<name>` presses any keyboard key, which is
 how a skin button reaches a mod hotkey.
 
-## The screen viewport
+## Screen placement
 
 `overlayN_viewport` is the cutout the picture is fitted into. The Game Boy
 screen keeps its whole-pixel scale and letterboxes inside that rect rather than
@@ -142,6 +148,17 @@ that lets a widescreen bezel take the filling survey-zoom world view instead.
 A viewport also implies the faithful-ratio lock. Without it the world pass
 expands to fill the cutout and you get more map instead of a Game Boy screen.
 
+Zoom still steps around that hole: OUT shows more map inside it, IN enlarges
+the world, and the start menu stays at the hole's fit scale instead of
+shrinking with the map.
+
+An image-backed portrait overlay that has no explicit vertical anchor is treated
+as a controller deck: it is contained without deformation and pinned to the
+bottom on taller screens. The spare space belongs to the game above it.
+
+When a skin is active, **SCREEN POS** reads **SKIN**: placement comes from the
+skin rather than the normal Center / Upper / Top setting.
+
 Border art often ships with a transparent hole and no `viewport` key. **Detect
 screen from bezel** in the studio measures the hole out of the art's alpha
 channel and writes the rect.
@@ -149,10 +166,8 @@ channel and writes the rect.
 ## Bezels versus pads
 
 A skin whose active page binds nothing is a frame rather than a pad: a TV
-surround, a handheld shell, a Super Game Boy border. Those draw on **desktop**
+surround, a handheld shell, a Super Game Boy border. Selected skins draw on
-as well, where the touch overlay itself does not, and a gamepad does not hide
+**desktop** as well as mobile; a gamepad does not hide them.
-them. Anything that binds a button still follows the usual mobile /
-`POKEPORT_TOUCH` rule.
 
 ## Installing
 
@@ -186,9 +201,32 @@ shipping branding.
 
 ## The studio
 
-Launcher, Skins tab, **Open Skin Studio**, or the gear on any skin row to open
+Launcher, Skins tab, **My Skins** opens the Studio library on desktop and
-that skin. Desktop only: the launcher does not offer it on Android or iOS,
+mobile. **My Skins** is the only visual grid: real bezel previews plus create
-because it wants a mouse, typed coordinates and room for an inspector.
+and import actions, with each card owning Edit, Export and (for installed
+skins) Delete. Choosing Edit opens a separate, canvas-first editor; the old
+New/Load workspace controls are deliberately not duplicated inside that editor.
+
+The editor keeps its canvas unobstructed and puts the contextual actions in a
+compact lower tray: add/control binding, button and bezel artwork, pages,
+screen placement, freeform/10:9 screen shape and deletion. **Screen** opens
+cutout, bezel-hole detect, **Detect this screen**, and the canvas presets.
+**Detect this screen** (also on the tray) sets the mock device to the live
+window size so a phone skin is authored at that phone's form factor rather
+than a generic 1080x1920 16:9. **Zoom −** shrinks the mock device inside the
+workspace so the screen hole can be dragged larger than the bezel while the
+handles stay grabable; **Fit** restores contain. The mouse wheel over the
+canvas, and `-` / `=` / `0` on a keyboard, do the same. Touches select, drag and resize the
+same controls that a mouse edits on desktop.
+
+My Skins and the editor chrome sit inside the platform safe area (notch,
+status bar, home indicator), the same inset the launcher uses. The mock
+device still represents the full window, because a skin covers the whole
+screen at play time.
+
+The launcher’s **Turn skins off** button clears the selected skin and disables
+skin use. With no skin enabled, mobile falls back to the built-in pad; that pad
+is not itself a skin card.
 
 **Canvas.** A mock device at a chosen preset, so a phone skin is authored at
 phone proportions on a desktop monitor.
@@ -196,6 +234,7 @@ phone proportions on a desktop monitor.
 | Preset | Size |
 | --- | --- |
 | Phone portrait / landscape | 1080x1920, 1920x1080 |
+| This screen | the live window, so a phone is authored at its own height |
 | Tablet portrait / landscape | 1536x2048, 2048x1536 |
 | Steam Deck | 1280x800 |
 | Desktop 1080p | 1920x1080 |
@@ -212,13 +251,16 @@ and of the page itself when it comes within a few pixels, and the guide it
 snapped to is drawn. X / Y / W / H are in canvas pixels, so a control can be
 typed to the coordinate its art was drawn at. **Back** and **Front** move the
 selection through the draw order. Bind, hitbox shape, hit reach and idle and
-pressed images are per control; the bezel, the pages and the screen cutout are
+pressed images are per control; the bezel, the pages and the screen anchor are
-per page. The cutout is itself a draggable element with a 10:9 lock.
+per page. The SCREEN anchor is itself draggable and resizable; its default
+shape is freeform, with an optional 10:9 lock.
 
 **Bind** opens a grid of every bind the engine understands: the eight Game Boy
-buttons, the diagonal pairs, every hotkey, a few `key:` entries, and
+buttons, the diagonal pairs, every hotkey, desktop hotkeys and decoration.
-decoration. The COMBINE chips at the top toggle one part at a time, which is
+The desktop section exposes `-` / `=`, `1` through `5`, `F1`, `F2` and `F10`
-how a pipe bind like `left|down` is built without typing it.
+as `key:` controls, so a mobile button invokes the exact same game path as
+its desktop shortcut. The COMBINE chips at the top toggle one part at a time,
+which is how a pipe bind like `left|down` is built without typing it.
 
 **Undo** and **Redo** in the top bar cover every edit (ctrl+Z / ctrl+Y, or
 `u` / shift+`u` without a keyboard modifier). The stack holds the last 50
@@ -243,12 +285,13 @@ the **Import** button there and beside each row opens the host file picker (`src
 zenity/kdialog) and copies the chosen PNG or JPG into `img/` under the name in
 the SKIN field, then assigns it to that slot. Dropping a PNG or JPG on the
 window does the same for whichever slot was last touched. A new bezel does not
-move the screen cutout: press **Detect screen from bezel** to measure it out of
+move the screen anchor: press **Detect screen from bezel** to measure it out of
 the art's alpha.
 
-**Testing.** **Test** makes the canvas live: clicking presses real Game Boy
+**Testing.** **Test** renders a game-composition preview behind the live overlay:
-buttons and the footer reports what is held. **Play** saves the skin, selects
+the 160x144 picture letterboxes inside the screen cutout, matching gameplay.
-it, and boots the game with it.
+Clicking presses real Game Boy buttons and the footer reports what is held.
+**Play** saves the skin, selects it, and boots the game with it.
 
 **Saving.** **Save** writes `skins/<name>/skin.lua` and copies every image the
 skin names, so the folder stands alone. **Export** offers three formats, and
@@ -268,6 +311,7 @@ exported file** opens that folder.
 
 ## Not implemented
 
-Delta skins whose art is PDF only. Rasterizing them needs a PDF renderer this
+True vector Delta skins (PDF artwork with no embedded JPEG). Those still need
-engine does not carry, so they are refused with a message rather than imported
+a PDF renderer this engine does not carry, so they are refused with a message
-half-drawn.
+rather than imported half-drawn. PDF files that wrap a JPEG, the usual Delta
+skin case, extract on import.

docs/switch-install.md

@@ -91,14 +91,14 @@ Do **not** launch from the Album applet path for normal play.
 
 This project ships **no** game data. On first launch:
 
-1. Put your own legally obtained Pokémon Red, Blue (`.gb`), Yellow, or
+1. Put your own legally obtained Pokémon Red, Blue (`.gb`), Yellow, Gold, or
-   Gold (`.gbc`) dump into `switch/gen1recomp/pokemon-love2d/imports/` (the
+   Silver (`.gbc`) dump into `switch/gen1recomp/pokemon-love2d/imports/` (the
-   launcher also shows the live save-dir path). All four can sit in the
+   launcher also shows the live save-dir path). All five can sit in the
    same folder.
-2. Use **Scan again** on that game's tab (Red / Blue / Yellow / Gold).
+2. Use **Scan again** on that game's tab (Red / Blue / Yellow / Gold /
-   Rescan matches by ROM SHA-1 for the open tab only. A Red dump never
+   Silver). Rescan matches by ROM SHA-1 for the open tab only. A Red dump
-   imports from the Yellow tab (and vice versa). Gold is Beta in the
+   never imports from the Yellow tab (and vice versa). Gold and Silver are
-   launcher; a clean US Gold dump is enough to Play.
+   Beta in the launcher; a clean US dump of either is enough to Play.
 
 ## 5. Import / Export a raw `.sav`
 
@@ -111,10 +111,12 @@ SD / FTP, same transfer methods as ROMs. Paths are **per game**:
 | Blue | `imports/saves/blue/` | `exports/blue/` |
 | Yellow | `imports/saves/yellow/` | `exports/yellow/` |
 | Gold | `imports/saves/gold/` | `exports/gold/` |
+| Silver | `imports/saves/silver/` | `exports/silver/` |
 
 (Under the save dir `pokemon-love2d/`. The zip already creates these folders.
-Gold cart `.sav` import/export is not supported yet -- the folders exist so
+Gold and Silver cart `.sav` import/export is not supported yet -- the folders
-MTP browsing matches the other games. Gold progress still saves in-engine.)
+exist so MTP browsing matches the other games. Gold and Silver progress still
+saves in-engine.)
 
 1. Copy a Gen 1 `.sav` (32 KB) into that game's inbox under the save dir
    ([switch-transfer.md](switch-transfer.md)).

docs/switch-transfer.md

@@ -22,8 +22,8 @@ Player install (what to download, title override) stays in
 | Loose iteration pair | `sdmc:/switch/gen1recomp/gen1recomp.nro` **and** `game.love` beside it |
 | ROM inbox | LÖVE save dir → `imports/` (launcher shows the live `getSaveDirectory()` path; under MTP often `1: SD Card/<save identity>/imports/`) |
 | Mod zip inbox | Same save dir → `imports/mods/` then MODS → **Scan again** |
-| Save `.sav` inbox | Same save dir → `imports/saves/red\|blue\|yellow\|gold/` then that game's SAVE FILES → **Import save** (Gold cart `.sav` not supported yet) |
+| Save `.sav` inbox | Same save dir → `imports/saves/red\|blue\|yellow\|gold\|silver/` then that game's SAVE FILES → **Import save** (Gold / Silver cart `.sav` not supported yet) |
-| Save exports | Same save dir → `exports/red\|blue\|yellow\|gold/` (pull after **Export save**; Gold cart `.sav` not supported yet) |
+| Save exports | Same save dir → `exports/red\|blue\|yellow\|gold\|silver/` (pull after **Export save**; Gold / Silver cart `.sav` not supported yet) |
 | Opt-in diagnostics | Empty `switch-debug.txt` in the save dir → `switch.log` |
 | Lua error log | `lua-error.log` in the save dir |
 
@@ -54,7 +54,8 @@ macOS, not a Mac-only requirement.
 3. Create `switch/gen1recomp/` if needed; extract the release zip at SD root
    (or copy NRO / `game.love` for loose).
 4. For ROMs/mods/saves, open the save-dir `imports/`, `imports/mods/`,
-   `imports/saves/<red|blue|yellow|gold>/`, or `exports/<red|blue|yellow|gold>/`
+   `imports/saves/<red|blue|yellow|gold|silver>/`, or
+   `exports/<red|blue|yellow|gold|silver>/`
    path the launcher prints.
 5. Wait for the queue; refresh; exit MTP responder; title-override launch.
 

docs/updater.md

@@ -64,7 +64,8 @@ mounted or deleted as stale; the launcher directs the player to a full package.
 
 Each tagged release `vX.Y.Z` carries the existing per-platform archives
 (`gen1recomp-X.Y.Z-macos.zip`, `-windows.zip`, `-linux.zip`,
-`-android.apk`) plus two assets the updater itself consumes:
+`-linux-arm64.AppImage`, `-android.apk`, `-ios.ipa`, `-switch.zip`, Xbox and
+PortMaster archives) plus two assets the updater itself consumes:
 
 - `gen1recomp-X.Y.Z.love` - the payload, matched by the exact pattern
   `gen1recomp-<version>.love` (see `isPayloadName` in `Boot.lua` and
@@ -75,8 +76,9 @@ Each tagged release `vX.Y.Z` carries the existing per-platform archives
   filename otherwise to match the asset name exactly.
 
 A release missing either asset is treated as "no in-place update available":
-`Check` reports `needs_full` and sends the player to `Check.releaseUrl()`
+`Check` reports `needs_full`. It also selects the exact current platform asset
-(`https://github.com/bryanthaboi/gen1recomp/releases/latest`).
+from the same release and persists the requirement, so it is visible again on
+every launch, including offline launches.
 
 ## Save-directory layout
 
@@ -85,6 +87,7 @@ Under the save directory (identity `pokemon-love2d`):
 ```
 updates/gen1recomp-<X.Y.Z>.love   downloaded payload(s)
 updates/pending.txt                crash-guard marker
+updates/full-update.json           persistent native-package requirement
 ```
 
 `pending.txt` holds the filename of the payload currently being chainloaded.
@@ -106,7 +109,8 @@ bundled game, in that case.
    against the GitHub releases API; safe to call every frame, it is a no-op
    once a check is in flight or has reached a terminal state. `Check.state()`
    reports `idle | checking | uptodate | available | downloading | ready |
-   needs_full | error` plus the latest version and download progress.
+   needs_full | full_downloading | full_ready | error` plus the latest version,
+   download progress, and (when applicable) the selected full-package asset.
 3. **Download + verify**: on `available`, `Check.download()` tells the
    worker to fetch the payload, polling the growing `.part` file for
    progress. On completion the worker re-fetches `sha256sums.txt`, verifies
@@ -117,6 +121,14 @@ bundled game, in that case.
 4. **Restart to apply**: a `ready` payload just sits in `updates/` until the
    player relaunches; the next launch's Boot step (1) is what actually
    mounts and runs it. There is no in-session hot-swap.
+5. **Native-package requirement**: when `minShell` or `payloadHost` is
+   incompatible, the worker writes `full-update.json` and surfaces a
+   persistent launcher control. Android downloads the release APK, verifies
+   its SHA-256 entry from `sha256sums.txt`, then invokes Android's Package
+   Installer. The installer asks the user for consent and enforces package,
+   version-code, and signing-certificate compatibility. iOS links the
+   sideload repository for a re-sideload; Xbox, desktop, and PortMaster builds
+   link their correctly named full package. Switch keeps its native OTA flow.
 
 ## Known limitations
 
@@ -140,6 +152,13 @@ bundled game, in that case.
   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")`.
+- **Android full updates are user-confirmed and certificate-bound.** The app
+  uses a private `FileProvider` cache path plus
+  `Intent.ACTION_INSTALL_PACKAGE`, checks Android 8+'s per-app
+  "install unknown apps" setting, and never requests a silent install. The
+  release job must use the original long-lived Android signing key; a new key
+  causes Android to reject an in-place update and requires a one-time manual
+  reinstall. See [mobile/ANDROID.md](../mobile/ANDROID.md).
 - **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

@@ -302,6 +302,8 @@ local function makeLauncher()
     forceImport = forceImport,
     onEditSave = openEditor,
     onEditTouchControls = openTouchControlsEditor,
+    -- Skin Studio owns a touch-first layout as well as the desktop workspace.
+    -- Keep the compatibility predicate so external hosts using it still work.
     onOpenSkinStudio = require("src.ui.SkinStudio").available_desktop()
       and openSkinStudio or nil,
   })
@@ -327,6 +329,7 @@ local function returnToLauncher()
   if love.audio and love.audio.stop then
     pcall(love.audio.stop)
   end
+  pcall(function() require("src.render.SecondScreen").setEnabled(false) end)
 
   local GameVersion = require("src.core.GameVersion")
   local currentVersion = GameVersion.get()
@@ -386,11 +389,12 @@ function bootGame(version)
     love.window.setTitle(Version.title(
       GameVersion.info().displayName .. " (Gen 1 Recompilation Project)"))
   end
-  -- Gold: Gen 1 Game:load cannot consume a Gen 2 cache -- different generated
+  -- Gen 2: Gen 1 Game:load cannot consume a Gen 2 cache -- different generated
-  -- tables, save shape and screen registry -- so Gold boots its own service
+  -- tables, save shape and screen registry -- so Gold and Silver boot their
-  -- owner, which mounts src/world/gen2 (walk / warps / connections) and the
+  -- own service owner, which mounts src/world/gen2 (walk / warps /
-  -- Gen 2 screens instead of src/core/Game.lua's Gen 1 wiring.
+  -- connections) and the Gen 2 screens instead of src/core/Game.lua's Gen 1
-  if GameVersion.isGold() then
+  -- wiring.
+  if GameVersion.generation() == 2 then
     Game = require("src.core.Game2").new()
     Game:load()
   else
@@ -875,6 +879,8 @@ love.handlers = love.handlers or {}
 function love.handlers.audiosuspend()
   local ChipAudio = package.loaded["src.core.ChipAudio"]
   if ChipAudio then pcall(ChipAudio.setSuspended, true) end
+  local Sound = package.loaded["src.core.Sound"]
+  if Sound then pcall(Sound.onDeviceReset) end
 end
 
 function love.handlers.audioreset()
@@ -927,7 +933,7 @@ function love.touchpressed(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchpressed(id, x, y)
   end
-  if Studio then return end
+  if Studio then return Studio.touchpressed(id, x, y) end
   if Importer then
     -- Both mobiles: FlexLove scroll needs the real touch stream. Clicks are
     -- polled inside the view; the istouch filter on mousepressed still drops
@@ -944,7 +950,7 @@ function love.touchmoved(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchmoved(id, x, y)
   end
-  if Studio then return end
+  if Studio then return Studio.touchmoved(id, x, y) end
   if Importer then
     return Importer:touchmoved(id, x, y, dx, dy, pressure)
   end
@@ -958,7 +964,7 @@ function love.touchreleased(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchreleased(id, x, y)
   end
-  if Studio then return end
+  if Studio then return Studio.touchreleased(id, x, y) end
   if Importer then
     return Importer:touchreleased(id, x, y, dx, dy, pressure)
   end
@@ -1011,7 +1017,12 @@ function love.mousepressed(x, y, button, istouch)
     if love.system.getOS() == "Android" then return end
     return TouchEditor.mousepressed(x, y, button)
   end
-  if Studio then return Studio.mousepressed(x, y, button) end
+  if Studio then
+    -- Mobile LÖVE sends both a touch event and an `istouch` mouse twin.
+    -- Studio consumes the real finger stream above, so discard the twin.
+    if istouch and (love.system.getOS() == "Android" or love.system.getOS() == "iOS") then return end
+    return Studio.mousepressed(x, y, button)
+  end
   if Importer then
     -- love.touchpressed already forwards the primary touch into FlexLove for
     -- scroll. LÖVE ALSO synthesizes a mouse press for that same touch; if both
@@ -1046,7 +1057,10 @@ function love.mousereleased(x, y, button, istouch)
     if love.system.getOS() == "Android" then return end
     return TouchEditor.mousereleased(x, y, button)
   end
-  if Studio then return Studio.mousereleased(x, y, button) end
+  if Studio then
+    if istouch and (love.system.getOS() == "Android" or love.system.getOS() == "iOS") then return end
+    return Studio.mousereleased(x, y, button)
+  end
   if Importer then return end
   if editorMode and EditorApp.mousereleased then
     return EditorApp.mousereleased(x, y, button)
@@ -1064,7 +1078,10 @@ function love.mousemoved(x, y, dx, dy, istouch)
     if love.system.getOS() == "Android" then return end
     return TouchEditor.mousemoved(x, y)
   end
-  if Studio then return Studio.mousemoved(x, y) end
+  if Studio then
+    if istouch and (love.system.getOS() == "Android" or love.system.getOS() == "iOS") then return end
+    return Studio.mousemoved(x, y)
+  end
   if editorMode or Importer then return end
   if mouseTouch then
     if Game and love.mouse.isDown(1) then Game:touchmoved("mouse", x, y) end

mobile/ANDROID.md

@@ -93,8 +93,9 @@ transport, exactly as a missing curl does.
 love-android 11.5a expects:
 
 - **JDK 17**
-- Android SDK with **API 34**
+- Android SDK with **API 36** (Android 16; latest 36.x Build-Tools)
 - NDK **25.2.9519653** (Apple Silicon host supported)
+- **minSdk 19** (Android 4.4), **targetSdk 36** (Android 16)
 
 Set `ANDROID_SDK_ROOT` (or `ANDROID_HOME`), or let the script write
 `local.properties` when it finds `~/Library/Android/sdk`.
@@ -109,10 +110,10 @@ The APK lands under `app/build/outputs/apk/embedNoRecord/debug/`.
 
 `app/src/embed/assets/game.love` - zip of `main.lua`, `conf.lua`, `src/`,
 `libs/` (the vendored FlexLove toolkit the launcher UI needs), `data/`,
-`assets/`, and the Red, Blue, and Yellow ROM manifests. The Android
+`assets/`, and the Red, Blue, Yellow, Gold, and Silver ROM manifests. The
-packer verifies the Yellow manifest before it packages; if a partial source
+Android packer verifies the Yellow, Gold, and Silver manifests before it
-export omitted it, it restores the file from this checkout's Git data and then
+packages; if a partial source export omitted one, it restores the file from
-falls back to the project's GitHub copy. Generated game data,
+this checkout's Git data and then falls back to the project's GitHub copy. Generated game data,
 scripts, tests, and mobile build sources are excluded.
 
 ## Branding (applied by the build script)
@@ -122,15 +123,24 @@ scripts, tests, and mobile build sources are excluded.
 | `app.application_id` | `com.theboisclub.pokemonred` |
 | `app.name` | Pokemon Red |
 | `app.orientation` | `fullUser`. This is only the manifest default: SDL requests FULL_SENSOR at window creation (resizable window, no `SDL_HINT_ORIENTATIONS`), and `GameActivity.setOrientationBis` remaps that to FULL_USER so the device's rotation lock is honoured. |
-| `app.version_name` / `app.version_code` | set from `--version X.Y.Z` (code = major*10000 + minor*100 + patch); left as-is if `--version` is omitted |
+| `app.version_name` / `app.version_code` | set from `--version X.Y.Z` (code = major*1,000,000 + minor*1,000 + patch); left as-is if `--version` is omitted |
-| Permissions | RECORD_AUDIO / WRITE_EXTERNAL_STORAGE stripped; VIBRATE + BLUETOOTH + INTERNET (link play, mod index) + ACTIVITY_RECOGNITION (step bridge) kept |
+| Permissions | RECORD_AUDIO / WRITE_EXTERNAL_STORAGE stripped; VIBRATE + BLUETOOTH + INTERNET (link play, mod index) + ACTIVITY_RECOGNITION (step bridge) kept; REQUEST_INSTALL_PACKAGES is limited to the user-confirmed full-update installer |
 
 ## Releases
 
 `.github/workflows/release.yml` builds the APK with `--version` set to the
 release version and publishes it alongside the macOS/Windows/Linux builds as
-`PokemonRed-<version>-android.apk`.
+`gen1recomp-<version>-android.apk`.
 
 ## Signing
 
-Signed with the default Android keystore (no setup required).
+Production APKs are built with `scripts/build_android.sh --release`. They must
+be signed with the same long-lived certificate as the currently installed app:
+Android's Package Installer rejects an update with a different signing
+certificate. Store that keystore and its passwords only in CI secrets, expose
+them as `GEN1RECOMP_ANDROID_KEYSTORE`,
+`GEN1RECOMP_ANDROID_KEYSTORE_PASSWORD`, `GEN1RECOMP_ANDROID_KEY_ALIAS`, and
+`GEN1RECOMP_ANDROID_KEY_PASSWORD`, and never commit the keystore. A newly
+created certificate cannot update users who have an APK signed by a different
+legacy key; those users need one final manual reinstall before in-app updates
+can take over.

mobile/android/README.md

@@ -41,7 +41,7 @@ Quick Start:
 Before you start, install JDK 17 (not later not earlier). If you intend to build from Android Studio, skip this step as
 Android Studio bundles its own JDK 17.
 
-Install Android SDK with SDK API 34 (34.x.y) and Android NDK 25.2.9519653, set the environment variable
+Install Android SDK with SDK API 36 (latest 36.x Build-Tools) and Android NDK 25.2.9519653, set the environment variable
 `ANDROID_SDK_ROOT` to your Android SDK location and run:
 
 ```

mobile/android/app/build.gradle

@@ -10,9 +10,12 @@ android {
         applicationId project.properties["app.application_id"]
         versionCode project.properties["app.version_code"].toInteger()
         versionName project.properties["app.version_name"]
-        minSdk 16
+        // NDK r25 no longer supports API 16; API 19 is Android 4.4 and keeps
-        compileSdk 34
+        // the native toolchain and package-installer bridge on a supported ABI.
-        targetSdk 34
+        minSdk 19
+        // Android 16 / API 36: current Android distribution target.
+        compileSdk 36
+        targetSdk 36
         
         def getAppName = {
             def nameArray = project.properties["app.name_byte_array"]
@@ -38,10 +41,31 @@ android {
             ORIENTATION:project.properties["app.orientation"],
         ]
     }
+    // Release signing lives outside the repository. The release build script
+    // requires all five values below, while debug builds intentionally remain
+    // usable without them.
+    def releaseStore = System.getenv("GEN1RECOMP_ANDROID_KEYSTORE")
+    def releaseStorePassword = System.getenv("GEN1RECOMP_ANDROID_KEYSTORE_PASSWORD")
+    def releaseKeyAlias = System.getenv("GEN1RECOMP_ANDROID_KEY_ALIAS")
+    def releaseKeyPassword = System.getenv("GEN1RECOMP_ANDROID_KEY_PASSWORD")
+    def hasReleaseSigning = releaseStore && releaseStorePassword && releaseKeyAlias && releaseKeyPassword
+
+    if (hasReleaseSigning) {
+        signingConfigs {
+            release {
+                storeFile file(releaseStore)
+                storePassword releaseStorePassword
+                keyAlias releaseKeyAlias
+                keyPassword releaseKeyPassword
+            }
+        }
+    }
+
     buildTypes {
         release {
             minifyEnabled true
             proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            if (hasReleaseSigning) signingConfig signingConfigs.release
         }
     }
     flavorDimensions = ['mode', 'recording']

mobile/android/app/src/main/AndroidManifest.xml

@@ -8,6 +8,10 @@
        the link screen shows as "(Operation not permitted)" (issue #287).
        scripts/build_android.sh must not strip this again. -->
   <uses-permission android:name="android.permission.INTERNET" />
+  <!-- Required only to hand a checksum-verified, user-selected GitHub release
+       APK to Android's own Package Installer. Android still shows the install
+       confirmation and enforces package/signing-key/version compatibility. -->
+  <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
   <!-- Step bridge: love.system.syncHealthSteps reads the hardware step
        counter, which Android 10+ gates behind this runtime permission.
        Requested only on the first sync call (the Pokéwalker mod's SYNC
@@ -35,10 +39,22 @@
     <meta-data
         android:name="android.allow_multiple_resumed_activities"
         android:value="true" />
+    <!-- The full-update APK is copied into this small cache subdirectory
+         before it is handed to Package Installer. Keep the provider private
+         and expose only that directory, never a storage root. -->
+    <provider
+        android:name="androidx.core.content.FileProvider"
+        android:authorities="${applicationId}.full_update_provider"
+        android:exported="false"
+        android:grantUriPermissions="true">
+      <meta-data
+          android:name="android.support.FILE_PROVIDER_PATHS"
+          android:resource="@xml/full_update_paths" />
+    </provider>
     <activity
         android:name="org.love2d.android.GameActivity"
         android:exported="true"
-        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation"
+        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation|uiMode|density|fontScale|locale|layoutDirection|colorMode"
         android:label="${NAME}"
         android:launchMode="singleTask"
         android:screenOrientation="${ORIENTATION}"
@@ -55,7 +71,7 @@
     </activity>
     <activity
         android:name="org.love2d.android.GameActivity$SecondaryActivity"
-        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation"
+        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation|uiMode|density|fontScale|locale|layoutDirection|colorMode"
         android:excludeFromRecents="true"
         android:exported="false"
         android:launchMode="singleTask"

mobile/android/app/src/main/res/values/colors.xml

@@ -8,4 +8,5 @@
     <color name="shortcut_blue">#1E88E5</color>
     <color name="shortcut_yellow">#FDD835</color>
     <color name="shortcut_gold">#D4AF37</color>
+    <color name="shortcut_silver">#BEC6D2</color>
 </resources>

mobile/android/app/src/main/res/xml/full_update_paths.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Deliberately narrow: FileProvider may grant only the staged APK, never
+     arbitrary app, external, or shared storage. -->
+<paths xmlns:android="http://schemas.android.com/apk/res/android">
+    <cache-path name="full_update" path="full-update/" />
+</paths>

mobile/android/build.gradle

@@ -18,7 +18,8 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.1.1'
+        // Android 16 / API 36 requires Android Gradle Plugin 8.9+.
+        classpath 'com.android.tools.build:gradle:8.9.2'
 
         // NOTE: Do not place your application dependencies here; they belong
         // in the individual module build.gradle files

mobile/android/gradle.properties

@@ -15,7 +15,6 @@ app.version_name=11.5a
 # No need to modify anything past this line!
 android.enableJetifier=false
 android.useAndroidX=true
-android.defaults.buildfeatures.buildconfig=true
 android.nonTransitiveRClass=true
 android.nonFinalResIds=true
 app.name=gen1recomp

mobile/android/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
 networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

mobile/android/love/build.gradle

@@ -10,9 +10,9 @@ android {
     ndkVersion '25.2.9519653'
 
     defaultConfig {
-        minSdk 16
+        minSdk 19
-        compileSdk 34
+        compileSdk 36
-        targetSdk 34
+        targetSdk 36
         externalNativeBuild {
             ndkBuild {
                 arguments "-j" + Runtime.runtime.availableProcessors()
@@ -63,8 +63,7 @@ android {
 
     buildTypes {
         release {
-            minifyEnabled true
+            minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
         }
         debug {
             ndk {

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

@@ -283,6 +283,40 @@ bool restartApp()
 	return result;
 }
 
+bool installApk(const char *path)
+{
+	if (path == nullptr || path[0] == '\0')
+		return false;
+
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	// This may be called from Lua's main thread, but use the activity object
+	// class just like httpDownload so a future worker caller does not depend on
+	// the system JNI class loader finding the app class.
+	void *rawActivity = SDL_AndroidGetActivity();
+	if (rawActivity == nullptr)
+		return false;
+	jobject activityObj = (jobject) rawActivity;
+	jclass activity = env->GetObjectClass(activityObj);
+	env->DeleteLocalRef(activityObj);
+
+	jmethodID method = env->GetStaticMethodID(activity, "installApk",
+		"(Ljava/lang/String;Ljava/lang/String;)Z");
+	if (method == nullptr)
+	{
+		env->ExceptionClear();
+		env->DeleteLocalRef(activity);
+		return false;
+	}
+
+	jstring jpath = env->NewStringUTF(path);
+	jstring jroot = env->NewStringUTF(bridgeSaveDirectory());
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jpath, jroot);
+	env->DeleteLocalRef(jroot);
+	env->DeleteLocalRef(jpath);
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
 bool updateAppShortcuts(const std::vector<std::string> &versions)
 {
 	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();

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

@@ -90,6 +90,12 @@ bool syncHealthSteps();
  **/
 bool restartApp();
 
+/**
+ * Stages a checksum-verified APK from the current save directory and starts
+ * Android's user-confirmed Package Installer flow. Android-only.
+ **/
+bool installApk(const char *path);
+
 /**
  * Dynamic App Shortcuts: updates Android ShortcutManager with ready game versions.
  **/

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

@@ -245,6 +245,16 @@ bool System::restartApp() const
 #endif
 }
 
+bool System::installApk(const char *path) const
+{
+#ifdef LOVE_ANDROID
+	return love::android::installApk(path);
+#else
+	LOVE_UNUSED(path);
+	return false;
+#endif
+}
+
 bool System::updateShortcuts(const std::vector<std::string> &versions) const
 {
 #ifdef LOVE_ANDROID

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

@@ -143,6 +143,9 @@ public:
 	 **/
 	virtual bool restartApp() const;
 
+	/** Starts Android's user-confirmed install flow for a verified APK. */
+	virtual bool installApk(const char *path) const;
+
 	virtual bool updateShortcuts(const std::vector<std::string> &versions) const;
 	virtual std::string getLaunchGame() const;
 

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

@@ -132,6 +132,13 @@ int w_restartApp(lua_State *L)
 	return 1;
 }
 
+int w_installApk(lua_State *L)
+{
+	const char *path = luaL_checkstring(L, 1);
+	luax_pushboolean(L, instance()->installApk(path));
+	return 1;
+}
+
 int w_httpDownload(lua_State *L)
 {
 	const char *url = luaL_checkstring(L, 1);
@@ -325,6 +332,7 @@ static const luaL_Reg functions[] =
 	{ "createFile", w_createFile },
 	{ "syncHealthSteps", w_syncHealthSteps },
 	{ "restartApp", w_restartApp },
+	{ "installApk", w_installApk },
 	{ "updateShortcuts", w_updateShortcuts },
 	{ "getLaunchGame", w_getLaunchGame },
 	{ "httpDownload", w_httpDownload },

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

@@ -45,6 +45,7 @@ import android.app.AlarmManager;
 import android.app.AlertDialog;
 import android.app.PendingIntent;
 import android.content.Context;
+import android.content.ClipData;
 import android.content.DialogInterface;
 import android.content.Intent;
 import android.content.SharedPreferences;
@@ -77,6 +78,7 @@ import android.view.*;
 
 import androidx.annotation.Keep;
 import androidx.core.app.ActivityCompat;
+import androidx.core.content.FileProvider;
 
 public class GameActivity extends SDLActivity {
     private static DisplayMetrics metrics = null;
@@ -398,11 +400,15 @@ public class GameActivity extends SDLActivity {
 
     @Override
     protected void onDestroy() {
+        secondaryHostResumed = false;
         if (vibrator != null) {
             Log.d("GameActivity", "Cancelling vibration");
             vibrator.cancel();
         }
         unregisterSecondaryDisplayListener();
+        teardownSecondaryDisplay();
+        secondaryEnabled = false;
+        synchronized (secondaryFrameLock) { secondaryFrame = null; }
         unregisterAudioDeviceCallback();
         abandonAudioFocus();
         onHostDestroy();
@@ -411,6 +417,7 @@ public class GameActivity extends SDLActivity {
 
     @Override
     protected void onPause() {
+        secondaryHostResumed = false;
         if (vibrator != null) {
             Log.d("GameActivity", "Cancelling vibration");
             vibrator.cancel();
@@ -426,6 +433,7 @@ public class GameActivity extends SDLActivity {
     @Override
     public void onResume() {
         super.onResume();
+        secondaryHostResumed = true;
         onHostResume();
         requestGameAudioFocus();
         registerAudioDeviceCallback();
@@ -690,6 +698,103 @@ public class GameActivity extends SDLActivity {
         return true; // unreachable, but keeps the JNI signature honest
     }
 
+    /**
+     * Stages a verified release APK in cache and asks Android's Package
+     * Installer to update this package. This never silently installs an APK:
+     * the platform owns both the unknown-sources consent and final install
+     * confirmation. `updateRoot` comes from the native save directory and is
+     * checked before any file is read, so a Lua caller cannot turn this into a
+     * general-purpose local-file sharing bridge.
+     */
+    @Keep
+    public static boolean installApk(final String sourcePath, final String updateRoot) {
+        final GameActivity self = (GameActivity) mSingleton;
+        if (self == null || sourcePath == null || updateRoot == null) return false;
+        final File source;
+        try {
+            source = new File(sourcePath).getCanonicalFile();
+            File root = new File(updateRoot, "updates").getCanonicalFile();
+            String rootPath = root.getPath() + File.separator;
+            if (!source.getPath().startsWith(rootPath)
+                    || !source.isFile() || source.length() == 0
+                    || !source.getName().matches("gen1recomp-[0-9]+\\.[0-9]+\\.[0-9]+-android\\.apk")) {
+                return false;
+            }
+        } catch (IOException e) {
+            Log.d("GameActivity", "invalid update APK path: " + e.getMessage());
+            return false;
+        }
+
+        // Android 8+ lets the user decide whether this app is trusted to
+        // request package installs. Send them to the per-app setting first;
+        // they deliberately tap Install again after granting it.
+        if (android.os.Build.VERSION.SDK_INT >= 26
+                && !self.getPackageManager().canRequestPackageInstalls()) {
+            try {
+                Intent settings = new Intent(Settings.ACTION_MANAGE_UNKNOWN_APP_SOURCES,
+                    Uri.parse("package:" + self.getPackageName()));
+                self.startActivity(settings);
+                return true;
+            } catch (Exception e) {
+                Log.d("GameActivity", "could not open install-source settings: " + e.getMessage());
+                return false;
+            }
+        }
+
+        // Copying an APK can be large; keep both I/O and checksum-verified
+        // source access off the UI thread. The FileProvider exposes this cache
+        // child only after it has been fully written and renamed.
+        new Thread(new Runnable() {
+            @Override public void run() {
+                File stagedDir = new File(self.getCacheDir(), "full-update");
+                File partial = new File(stagedDir, "update.apk.part");
+                File staged = new File(stagedDir, "update.apk");
+                try {
+                    if (!stagedDir.exists() && !stagedDir.mkdirs()) return;
+                    copyFile(source, partial);
+                    if (staged.exists() && !staged.delete()) return;
+                    if (!partial.renameTo(staged)) return;
+                    self.runOnUiThread(new Runnable() {
+                        @Override public void run() { launchPackageInstaller(self, staged); }
+                    });
+                } catch (Exception e) {
+                    Log.d("GameActivity", "could not stage update APK: " + e.getMessage());
+                } finally {
+                    if (partial.exists()) partial.delete();
+                }
+            }
+        }, "gen1recomp-apk-stage").start();
+        return true;
+    }
+
+    private static void copyFile(File source, File destination) throws IOException {
+        InputStream in = new BufferedInputStream(new FileInputStream(source));
+        OutputStream out = new BufferedOutputStream(new FileOutputStream(destination));
+        try {
+            byte[] buffer = new byte[32768];
+            int count;
+            while ((count = in.read(buffer)) != -1) out.write(buffer, 0, count);
+        } finally {
+            try { out.close(); } catch (IOException ignored) {}
+            try { in.close(); } catch (IOException ignored) {}
+        }
+    }
+
+    private static void launchPackageInstaller(GameActivity activity, File apk) {
+        try {
+            Context context = activity.getApplicationContext();
+            Uri uri = FileProvider.getUriForFile(context,
+                context.getPackageName() + ".full_update_provider", apk);
+            Intent install = new Intent(Intent.ACTION_INSTALL_PACKAGE);
+            install.setData(uri);
+            install.setClipData(ClipData.newRawUri("apk", uri));
+            install.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
+            activity.startActivity(install);
+        } catch (Exception e) {
+            Log.d("GameActivity", "could not open package installer: " + e.getMessage());
+        }
+    }
+
     @Keep
     public static String getLaunchGame() {
         return initialGame != null ? initialGame : "";
@@ -1933,6 +2038,7 @@ public class GameActivity extends SDLActivity {
     private static volatile int secondaryActivityTarget = Display.INVALID_DISPLAY;
     private static volatile long secondaryRetryAfter;
     private static volatile boolean secondaryEnabled = false;
+    private static volatile boolean secondaryHostResumed = false;
     private static volatile int secondaryTarget = SECONDARY_TARGET_AUTO;
     private static volatile int dualScreenDisplayMode = -1;
     private static volatile byte[] secondaryFrame;
@@ -1963,7 +2069,7 @@ public class GameActivity extends SDLActivity {
         if (self == null) return;
         self.runOnUiThread(new Runnable() {
             @Override public void run() {
-                if (on) {
+                if (on && secondaryHostResumed) {
                     self.refreshDualScreenDisplayMode();
                     self.registerSecondaryDisplayListener();
                     rebindSecondaryDisplay();
@@ -2035,9 +2141,11 @@ public class GameActivity extends SDLActivity {
 
     private static void rebindSecondaryDisplay() {
         GameActivity self = (GameActivity) mSingleton;
-        if (self == null || !secondaryEnabled || secondaryOutputIsPreferred(self)) return;
+        if (self == null || !secondaryHostResumed || !secondaryEnabled
+                || secondaryOutputIsPreferred(self)) return;
         self.runOnUiThread(() -> {
-            if (!secondaryEnabled || secondaryOutputIsPreferred(self)) return;
+            if (!secondaryHostResumed || !secondaryEnabled
+                    || secondaryOutputIsPreferred(self)) return;
             teardownSecondaryDisplay();
             setupSecondaryDisplay();
         });
@@ -2045,7 +2153,8 @@ public class GameActivity extends SDLActivity {
 
     private static void setupSecondaryDisplay() {
         GameActivity self = (GameActivity) mSingleton;
-        if (self == null || !secondaryEnabled || secondaryPresentation != null
+        if (self == null || !secondaryHostResumed || !secondaryEnabled
+                || secondaryPresentation != null
                 || secondaryActivity != null || secondaryActivityPending
                 || android.os.SystemClock.elapsedRealtime() < secondaryRetryAfter) return;
         try {

mobile/ios/app-repo.json

@@ -12,6 +12,69 @@
       "tintColor": "3b5ca8",
       "category": "games",
       "versions": [
+        {
+          "version": "0.2.16",
+          "date": "2026-08-21",
+          "size": 13769300,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.16/gen1recomp++-0.2.16-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1367 Android auto scrolling  down bug\n- #1570 Pokemon Gold isn't noticing my controller inputs on...ANY controller I own, despite all of them working in the other games, and in the main launcher\n- #1585 Power-saving mode or dark mode closes the game on Android.\n- #1611 bug: keyboard gets stuck IOS\n- #1612 Fold 7 infinite scrolling mouse.\n- #1636 Game freezes when trainer battle starts\n- #1638 Game screen orientation on smartphone\n- #1641 [Gold] [Android] PKMN Evolutions sequence freezes the Game \n\n## Contributors\n\n- @1Jamie\n- @bryanthaboi\n- @HighDrexler\n- MaxTomahawk"
+        },
+        {
+          "version": "0.2.15",
+          "date": "2026-08-21",
+          "size": 13753007,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.15/gen1recomp++-0.2.15-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1589 Player sprite still blinking on the Town Map\n- #1595 Pokedex completion certificate is not displaying correctly\n- #1597 Link cable looks broken\n- #1613 Visual differences in Pokemon trades\n- #1619 Save Menu cutting off and Put into another place\n\n## Contributors\n\n- @1Jamie\n- @bryanthaboi"
+        },
+        {
+          "version": "0.2.14",
+          "date": "2026-08-20",
+          "size": 13749372,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.14/gen1recomp++-0.2.14-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.2.13",
+          "date": "2026-08-20",
+          "size": 13749377,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.13/gen1recomp++-0.2.13-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1474 (Pokémon Gold) Pokédex mode not being saved\n- #1475 (Pokémon Gold) Vital Throw attacking before the opponent\n- #1477 (Pokémon Gold) Map when using fly keeps the arrow from the pokégear\n- #1478 (Pokémon Gold) Wrong move layout in battles\n- #1479 [Gold] tiles broken at Route 28 and Mt Silver\n- #1482 (Pokémon Gold) Nothing happens when trying to use Coin Case\n- #1488 Pokemon EXP calculation after trading went back to issue #984\n- #1510 Title Screen Transition is Missing\n- #1511 Broken Trainer Rival Name Layout\n- #1512 Gen 2 Post battle interactions don't exist\n- #1514 Health damage timing\n- #1516 Move learning timing\n- #1521 Different Item Menu\n- #1522 Wrong Save Game Layout\n- #1545 Pikachu not sliding out when switching Pokemon.\n- #1557 (Gold) Impossible to get TM 03 in Celadon Mansion at night\n- #1558 (Gold) Missing colors and symbol in stats screen\n- #1563 Player mon pic cuts away instead of shrinking when recalled\n- #1565 Thrash doesn't lock in when the first use misses\n- #1566 Center PC missing the PKMN LEAGUE entry after the Hall of Fame\n- #1569 Goldenrod Gift Spearow Bugged\n- #1577 Thrash has no animation past the first turn\n- #1578 Hitting yourself in confusion animation missing\n- #1579 Missing dialogue for Cerulean City Rocket\n- #1594 Pokemon menu closing too soon when using rare candy\n- #1596 Evolution dialogue & missing jingle\n- #1606 Misty dialogue issue\n- #1608 \"There's no will to fight!\" message issues\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.2.12",
+          "date": "2026-08-20",
+          "size": 13737259,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.12/gen1recomp++-0.2.12-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1582 Sync not working between steamdeck and windows\n- #1583 Can’t sync between iOS and windows\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi\n- @thibautbus"
+        },
+        {
+          "version": "0.2.11",
+          "date": "2026-08-20",
+          "size": 13735190,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.11/gen1recomp++-0.2.11-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #393 silph co. npc missing some dialogue\n- #1600 allow my uncle's neighbor to sit at the big kids table\n- #1603 pocket taco - type option \"screen position\"\n\n## Contributors\n\n- @1Jamie\n- @bryanthaboi\n- @dburton95\n- @mleo2003\n- @thibautbus"
+        },
+        {
+          "version": "0.2.10",
+          "date": "2026-08-19",
+          "size": 13662645,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.10/gen1recomp++-0.2.10-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #998 Jingles not finishing before game proceeds\n- #1472 Message for sending out Pokemon not closing automatically\n- #1526 No screen shake when getting poisoned\n- #1529 Messages missing when interacting with PC\n- #1530 No message for interacting with bikes in the bike shop\n- #1532 Thrash animation incomplete\n- #1534 Dialogue missing when switching out Pokemon\n- #1547 Save states can be used to bypass certain NPCs\n- #1549 Menu Cartridge 3D model has visual issues\n- #1550 Nugget Bridge Rocket repeating dialogue\n- #1551 No scripted dialogue after beating Nugget Bridge Rocket\n\n## Contributors\n\n- @bryanthaboi\n- @castdrian"
+        },
+        {
+          "version": "0.2.9",
+          "date": "2026-08-19",
+          "size": 13656293,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.9/gen1recomp++-0.2.9-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.2.8",
+          "date": "2026-08-19",
+          "size": 13653911,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.8/gen1recomp++-0.2.8-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1502 Gold doesn't show trainer balls\n- #1533 Retroarch Skin Problem 2 (#1503)\n\n## Contributors\n\n- @1Jamie\n- @AverageConsumer\n- @bryanthaboi\n- @castdrian\n- @thibautbus"
+        },
         {
           "version": "0.2.7",
           "date": "2026-08-18",

mobile/ios/native/GRBootstrap.m

@@ -6,6 +6,27 @@
 // Registered from a constructor so no LÖVE/SDL source needs to know about it.
 
 #import <UIKit/UIKit.h>
+#import <sys/utsname.h>
+
+@interface GRDeviceBridge : NSObject
++ (NSString *)deviceModel;
+@end
+
+@implementation GRDeviceBridge
++ (NSString *)deviceModel
+{
+#if TARGET_OS_SIMULATOR
+    NSString *simulatorModel = NSProcessInfo.processInfo.environment[@"SIMULATOR_MODEL_IDENTIFIER"];
+    if (simulatorModel.length > 0) return simulatorModel;
+#endif
+    struct utsname systemInfo;
+    if (uname(&systemInfo) == 0) {
+        NSString *model = [NSString stringWithUTF8String:systemInfo.machine];
+        if (model.length > 0) return model;
+    }
+    return @"";
+}
+@end
 
 __attribute__((constructor))
 static void GRBootstrapInstall(void)

mobile/ios/patch_love_src.py

@@ -156,6 +156,7 @@ int w_syncHealthSteps(lua_State *L)
 """ % MARKER
 
 WRAP_REGISTRATION = """#ifdef LOVE_IOS
+	{ "getDeviceModel", w_getDeviceModel },
 	{ "pickFile", w_pickFile },
 	{ "pickFileKinds", w_pickFileKinds },
 	{ "createFile", w_createFile },
@@ -202,6 +203,7 @@ int w_syncHealthSteps(lua_State *L)
 """
 
 WRAP_SYNC_REGISTRATION = """#ifdef LOVE_IOS
+	{ "getDeviceModel", w_getDeviceModel },
 	{ "syncHealthSteps", w_syncHealthSteps },
 	{ "httpDownload", w_httpDownload },
 	{ "httpRequest", w_httpRequest },
@@ -210,6 +212,33 @@ WRAP_SYNC_REGISTRATION = """#ifdef LOVE_IOS
 
 BRIDGE_EXTRA_FUNCS = """
 #ifdef LOVE_IOS
+int w_getDeviceModel(lua_State *L)
+{
+	Class cls = objc_getClass("GRDeviceBridge");
+	if (cls == nullptr)
+	{
+		lua_pushnil(L);
+		return 1;
+	}
+	typedef id (*GRObj)(Class, SEL);
+	id value = ((GRObj)objc_msgSend)(cls, sel_registerName("deviceModel"));
+	if (value == nullptr)
+	{
+		lua_pushnil(L);
+		return 1;
+	}
+	typedef const char *(*GRUTF8)(id, SEL);
+	const char *bytes = ((GRUTF8)objc_msgSend)(value,
+	                                           sel_registerName("UTF8String"));
+	if (bytes == nullptr || bytes[0] == '\\0')
+	{
+		lua_pushnil(L);
+		return 1;
+	}
+	lua_pushstring(L, bytes);
+	return 1;
+}
+
 int w_httpDownload(lua_State *L)
 {
 	const char *url = luaL_checkstring(L, 1);

mods/examples/example_silly_oak/CHANGELOG.md

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

mods/examples/example_silly_oak/README.md

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

mods/examples/example_silly_oak/main.lua

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

mods/examples/example_silly_oak/manifest.json

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

mods/examples/example_silly_oak/mod.card

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

mods/examples/example_silly_oak/tests/example_silly_oak_test.lua

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

scripts/build.sh

@@ -6,6 +6,7 @@
 #
 # Usage: scripts/build.sh [mac|win|linux|android|ios|all] [--version X.Y.Z] [--identity "Developer ID Application: ..."]
 #                          [--notary-profile NAME] [--no-notarize]
+#                          [--game-love PATH]  # fuse a prebuilt payload (scripts/pack_love.sh) instead of packing one
 #                          [--release]   # ios only: release config instead of debug
 #
 # Output: dist/mac/gen1recomp-macos.zip
@@ -36,6 +37,7 @@ NOTARY_PROFILE="notary-profile"
 NOTARIZE=true
 IOS_RELEASE=false
 IOS_IPA=false
+GAME_LOVE_IN=""
 
 say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
 warn() { printf '\033[1;33mwarn:\033[0m %s\n' "$*" >&2; }
@@ -48,6 +50,7 @@ while [ $# -gt 0 ]; do
     --identity) IDENTITY="$2"; shift ;;
     --notary-profile) NOTARY_PROFILE="$2"; shift ;;
     --no-notarize) NOTARIZE=false ;;
+    --game-love) GAME_LOVE_IN="${2:?--game-love needs a path}"; shift ;;
     --release) IOS_RELEASE=true ;;
     --ipa) IOS_IPA=true ;;
     *) fail "unknown argument: $1" ;;
@@ -62,16 +65,23 @@ mkdir -p "$CACHE" "$WORK" "$DIST/mac" "$DIST/win" "$DIST/linux"
 # launcher's Edit button on a save row opens it in-process (main.lua), and
 # `--editor` / POKEPORT_EDITOR=1 opens it standalone.  It is required through
 # love.filesystem's require path, so it has to live inside the archive.
-say "packing game.love"
 LOVE_FILE="$WORK/game.love"
 rm -f "$LOVE_FILE"
-# The launcher UI kit lives at src/ui/kit (inside src/, packed wholesale);
+if [ -n "$GAME_LOVE_IN" ]; then
-# the vendored libs/flexlove tree it replaced is gone.
+  [ -f "$GAME_LOVE_IN" ] || fail "--game-love: no such file: $GAME_LOVE_IN"
-(cd "$ROOT" && zip -q -9 -r "$LOVE_FILE" \
+  say "using prebuilt payload: $GAME_LOVE_IN"
-  main.lua conf.lua src data assets tools/save-editor \
+  cp "$GAME_LOVE_IN" "$LOVE_FILE"
-  tools/rom_manifest.json tools/rom_manifest_blue.json \
+else
-  tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+  say "packing game.love"
-  -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
+  # The launcher UI kit lives at src/ui/kit (inside src/, packed wholesale);
+  # the vendored libs/flexlove tree it replaced is gone.
+  (cd "$ROOT" && zip -q -9 -r "$LOVE_FILE" \
+    main.lua conf.lua src data assets tools/save-editor \
+    tools/rom_manifest.json tools/rom_manifest_blue.json \
+    tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+    tools/rom_manifest_silver.json \
+    -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
+fi
 # Materialize the listing once and grep the file: piping unzip straight into
 # grep -q under `set -o pipefail` SIGPIPEs unzip when grep exits early on a
 # match, and the pipeline's failure reads as "missing <file>" for whichever
@@ -90,7 +100,8 @@ for required in tools/save-editor/App.lua tools/save-editor/Kit.lua \
                 tools/save-editor/panels/Party.lua \
                 src/ui/kit/Kit.lua \
                 tools/rom_manifest.json tools/rom_manifest_blue.json \
-                tools/rom_manifest_yellow.json tools/rom_manifest_gold.json; do
+                tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+                tools/rom_manifest_silver.json; do
   grep -qxF "$required" "$LOVE_LISTING" \
     || fail "game.love is missing $required"
 done
@@ -105,18 +116,26 @@ say "game.love: $(du -h "$LOVE_FILE" | cut -f1)"
 # mistaken for a release. The stamp is then read back out of the archive and the
 # build fails if it did not take.
 if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
-  say "stamping engine version $VERSION into game.love"
+  if [ -n "$GAME_LOVE_IN" ]; then
-  stamp_dir="$WORK/stamp"
+    version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
-  rm -rf "$stamp_dir"
+    unzip -p "$LOVE_FILE" src/core/Version.lua \
-  mkdir -p "$stamp_dir/src/core"
+      | grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
-  sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+      || fail "prebuilt payload does not report engine $VERSION (pack it with pack_love.sh --version $VERSION)"
-    "$ROOT/src/core/Version.lua" > "$stamp_dir/src/core/Version.lua"
+    say "prebuilt payload already stamped: $VERSION"
-  (cd "$stamp_dir" && zip -q "$LOVE_FILE" src/core/Version.lua)
+  else
-  version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+    say "stamping engine version $VERSION into game.love"
-  unzip -p "$LOVE_FILE" src/core/Version.lua \
+    stamp_dir="$WORK/stamp"
-    | grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+    rm -rf "$stamp_dir"
-    || fail "version stamp failed: game.love does not report engine $VERSION"
+    mkdir -p "$stamp_dir/src/core"
-  say "stamped engine version: $VERSION"
+    sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+      "$ROOT/src/core/Version.lua" > "$stamp_dir/src/core/Version.lua"
+    (cd "$stamp_dir" && zip -q "$LOVE_FILE" src/core/Version.lua)
+    version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+    unzip -p "$LOVE_FILE" src/core/Version.lua \
+      | grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+      || fail "version stamp failed: game.love does not report engine $VERSION"
+    say "stamped engine version: $VERSION"
+  fi
 else
   say "version '$VERSION' is not X.Y.Z,  shipping default engine (no stamp)"
 fi

scripts/build_android.sh

@@ -1,19 +1,20 @@
 #!/usr/bin/env bash
 # Packages the LÖVE2D Pokémon Red port into an Android APK via love-android 11.5a.
 #
-# Usage: scripts/build_android.sh [--version X.Y.Z] [--package-only]
+# Usage: scripts/build_android.sh [--version X.Y.Z] [--release] [--package-only]
 #
 #   --version X.Y.Z  set app.version_name / app.version_code (else left as-is)
+#   --release        build the production-signed release APK (requires the
+#                    GEN1RECOMP_ANDROID_* signing environment variables)
 #   --package-only   zip game.love + apply branding; skip gradle
 #
 # Prerequisites:
 #   - mobile/android vendored love-android tree at tag 11.5a (in-repo; see mobile/ANDROID.md)
-#   - Android SDK + NDK (SDK API 34, NDK 25.2.9519653)
+#   - Android SDK + NDK (SDK API 36, NDK 25.2.9519653)
 #   - JDK 17
 #
 # Output (after gradle):
-#   dist/android/debug/*.apk (convenience copy)
+#   dist/android/debug/*.apk (normal local build) or dist/android/release/*.apk
-#   mobile/android/app/build/outputs/apk/embedNoRecord/debug/*.apk
 
 set -euo pipefail
 
@@ -26,13 +27,17 @@ APP_NAME="gen1recomp"
 APPLICATION_ID="com.theboisclub.pokemonred"
 LOVE_ANDROID_VERSION="11.5a"
 NDK_VERSION="25.2.9519653"
+ANDROID_API="36"
 YELLOW_MANIFEST_RELATIVE="tools/rom_manifest_yellow.json"
 YELLOW_MANIFEST_URL="${YELLOW_MANIFEST_URL:-https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/tools/rom_manifest_yellow.json}"
 GOLD_MANIFEST_RELATIVE="tools/rom_manifest_gold.json"
 GOLD_MANIFEST_URL="${GOLD_MANIFEST_URL:-https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/tools/rom_manifest_gold.json}"
+SILVER_MANIFEST_RELATIVE="tools/rom_manifest_silver.json"
+SILVER_MANIFEST_URL="${SILVER_MANIFEST_URL:-https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/tools/rom_manifest_silver.json}"
 
 VERSION=""
 PACKAGE_ONLY=false
+RELEASE=false
 
 say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
 warn() { printf '\033[1;33mwarn:\033[0m %s\n' "$*" >&2; }
@@ -42,11 +47,12 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --version) VERSION="$2"; shift ;;
     --package-only) PACKAGE_ONLY=true ;;
+    --release) RELEASE=true ;;
     -h|--help)
       sed -n '2,20p' "$0"
       exit 0
       ;;
-    *) fail "unknown argument: $1 (try --version X.Y.Z or --package-only)" ;;
+    *) fail "unknown argument: $1 (try --version X.Y.Z, --release, or --package-only)" ;;
   esac
   shift
 done
@@ -60,7 +66,22 @@ if [ -n "$VERSION" ]; then
   rest="${VERSION#*.}"
   minor="${rest%%.*}"
   patch="${rest##*.}"
-  VERSION_CODE=$((major * 10000 + minor * 100 + patch))
+  # Reserve three digits for each lower component. This stays monotonic across
+  # 1.0.100 -> 1.1.0, unlike the old two-digit encoding, and remains inside
+  # Android's signed 32-bit versionCode range for normal release versions.
+  if [ "$minor" -gt 999 ] || [ "$patch" -gt 999 ] || [ "$major" -gt 2099 ]; then
+    fail "--version components exceed Android versionCode limits"
+  fi
+  VERSION_CODE=$((major * 1000000 + minor * 1000 + patch))
+fi
+
+if $RELEASE; then
+  for var in GEN1RECOMP_ANDROID_KEYSTORE GEN1RECOMP_ANDROID_KEYSTORE_PASSWORD \
+    GEN1RECOMP_ANDROID_KEY_ALIAS GEN1RECOMP_ANDROID_KEY_PASSWORD; do
+    [ -n "${!var:-}" ] || fail "--release requires $var"
+  done
+  [ -f "$GEN1RECOMP_ANDROID_KEYSTORE" ] \
+    || fail "Android signing keystore does not exist: $GEN1RECOMP_ANDROID_KEYSTORE"
 fi
 
 # --------------------------------------------------------------- preconditions
@@ -177,6 +198,54 @@ ensure_gold_manifest() {
   fail "Gold import manifest is unavailable. Git recovery failed and could not download $GOLD_MANIFEST_URL"
 }
 
+silver_manifest_is_valid() {
+  local path="$1"
+  python3 - "$path" <<'PY'
+import json, pathlib, sys
+
+try:
+    manifest = json.loads(pathlib.Path(sys.argv[1]).read_text())
+except (OSError, ValueError):
+    raise SystemExit(1)
+
+raise SystemExit(0 if manifest.get("romSha1") ==
+                 "49b163f7e57702bc939d642a18f591de55d92dae" else 1)
+PY
+}
+
+ensure_silver_manifest() {
+  local manifest="$ROOT/$SILVER_MANIFEST_RELATIVE"
+  local staged
+  staged="$(mktemp)"
+
+  if silver_manifest_is_valid "$manifest"; then
+    rm -f "$staged"
+    return
+  fi
+
+  warn "Silver import manifest is missing or invalid; recovering it before packaging"
+  if git -C "$ROOT" show "HEAD:$SILVER_MANIFEST_RELATIVE" > "$staged" 2>/dev/null \
+      && silver_manifest_is_valid "$staged"; then
+    mkdir -p "$(dirname "$manifest")"
+    mv "$staged" "$manifest"
+    say "restored Silver import manifest from this checkout's Git data"
+    return
+  fi
+
+  if command -v curl >/dev/null 2>&1 \
+      && curl --fail --location --retry 2 --connect-timeout 15 \
+          --output "$staged" "$SILVER_MANIFEST_URL" \
+      && silver_manifest_is_valid "$staged"; then
+    mkdir -p "$(dirname "$manifest")"
+    mv "$staged" "$manifest"
+    say "downloaded Silver import manifest from the project repository"
+    return
+  fi
+
+  rm -f "$staged"
+  fail "Silver import manifest is unavailable. Git recovery failed and could not download $SILVER_MANIFEST_URL"
+}
+
 # --------------------------------------------------------------- branding
 # love-android 11.5+ reads app id / name / orientation from gradle.properties.
 # Manifest still gets permission trims. Re-applied every build so refreshing
@@ -242,6 +311,7 @@ pack_game_love() {
   say "packing game.love for love-android embed flavor"
   ensure_yellow_manifest
   ensure_gold_manifest
+  ensure_silver_manifest
   mkdir -p "$EMBED_ASSETS"
   rm -f "$LOVE_FILE"
   # tools/save-editor ships with the app: the launcher's Edit button on a save
@@ -256,6 +326,7 @@ pack_game_love() {
     main.lua conf.lua src data assets tools/save-editor \
     tools/rom_manifest.json tools/rom_manifest_blue.json \
     tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+    tools/rom_manifest_silver.json \
     -x '*.DS_Store' -x '*/.git/*' -x '*/.DS_Store' \
     -x 'data/generated/*' -x 'assets/generated/*')
   # List once and match against the captured text: piping unzip straight into
@@ -277,6 +348,8 @@ pack_game_love() {
     || fail "game.love is missing the Yellow ROM import manifest"
   grep -qx 'tools/rom_manifest_gold.json' <<< "$archive_entries" \
     || fail "game.love is missing the Gold ROM import manifest"
+  grep -qx 'tools/rom_manifest_silver.json' <<< "$archive_entries" \
+    || fail "game.love is missing the Silver ROM import manifest"
   # This gate exists because the launcher's UI toolkit once lived outside
   # src/ (libs/flexlove) and was added to scripts/build.sh's payload and to
   # no other packager, so Android and iOS built an APK/IPA whose launcher
@@ -335,13 +408,18 @@ require_android_sdk() {
     export ANDROID_SDK_ROOT=\$HOME/Library/Android/sdk
   or create mobile/android/local.properties with:
     sdk.dir=/path/to/Android/sdk
-  love-android $LOVE_ANDROID_VERSION expects SDK API 34 and NDK $NDK_VERSION
+  love-android $LOVE_ANDROID_VERSION expects SDK API $ANDROID_API and NDK $NDK_VERSION
   (see mobile/ANDROID.md)."
   fi
 
   export ANDROID_SDK_ROOT="$sdk"
   export ANDROID_HOME="$sdk"
 
+  if [ ! -d "$sdk/platforms/android-$ANDROID_API" ]; then
+    fail "Android SDK platform android-$ANDROID_API is not installed.
+  Install Android $ANDROID_API (and the latest 36.x Build-Tools) in SDK Manager."
+  fi
+
   local props="$ANDROID_DIR/local.properties"
   # Always rewrite so a leftover Docker sdk.dir=/opt/android-sdk cannot stick.
   printf 'sdk.dir=%s\n' "$sdk" > "$props"
@@ -358,7 +436,12 @@ require_android_sdk() {
 
 # --------------------------------------------------------------- gradle
 run_gradle() {
-  local task="assembleEmbedNoRecordDebug"
+  local variant="debug"
+  $RELEASE && variant="release"
+  # Keep this compatible with macOS's bundled Bash 3.2 (no ${var^}).
+  local variant_title="Debug"
+  $RELEASE && variant_title="Release"
+  local task="assembleEmbedNoRecord$variant_title"
   local build_dir="$ANDROID_DIR"
 
   # ndk-build is GNU make underneath and cannot cope with spaces anywhere in
@@ -393,12 +476,12 @@ run_gradle() {
   You can still iterate on the .love payload with: scripts/build_android.sh --package-only"
   fi
 
-  local out_dir="$build_dir/app/build/outputs/apk/embedNoRecord/debug"
+  local out_dir="$build_dir/app/build/outputs/apk/embedNoRecord/$variant"
   if [ -d "$out_dir" ]; then
     say "APK output:"
     find "$out_dir" -name '*.apk' -exec ls -lh {} \;
 
-    local dist_dir="$DIST/debug"
+    local dist_dir="$DIST/$variant"
     rm -rf "$dist_dir"
     mkdir -p "$dist_dir"
     find "$out_dir" -name '*.apk' -exec cp {} "$dist_dir/" \;

scripts/linux-arm64/build_appimage.sh

@@ -366,6 +366,8 @@ cp "$IN/game.love" "$APPDIR/game.love"
 unzip -Z1 "$APPDIR/game.love" > "$WORK/love-listing.txt"
 grep -qxF "tools/rom_manifest_gold.json" "$WORK/love-listing.txt" \
   || fail "game.love is missing tools/rom_manifest_gold.json"
+grep -qxF "tools/rom_manifest_silver.json" "$WORK/love-listing.txt" \
+  || fail "game.love is missing tools/rom_manifest_silver.json"
 # The .desktop's Icon= resolves against the AppDir root by basename, and
 # .DirIcon is what appimaged and file-manager thumbnailers read.
 cp "$IN/icon.png" "$APPDIR/$APP_NAME.png"

scripts/linux-arm64/selftest_build_linux_arm64.sh

@@ -169,5 +169,7 @@ unzip -p "$temp_dir/game.love" src/core/Version.lua \
   || fail "shared payload version was not stamped"
 grep -qxF "tools/rom_manifest_gold.json" "$temp_dir/love-listing.txt" \
   || fail "shared payload is missing tools/rom_manifest_gold.json"
+grep -qxF "tools/rom_manifest_silver.json" "$temp_dir/love-listing.txt" \
+  || fail "shared payload is missing tools/rom_manifest_silver.json"
 
 say "Linux arm64 self-test passed"

scripts/linux-arm64/verify_appimage.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Verifies a built arm64 AppImage is self-contained and bullseye-compatible.
+# Usage: scripts/linux-arm64/verify_appimage.sh <AppImage>
+
+set -euo pipefail
+
+image="${1:?usage: verify_appimage.sh <AppImage>}"
+[ -f "$image" ] || { echo "::error::no such AppImage: $image"; exit 1; }
+image="$(cd "$(dirname "$image")" && pwd)/$(basename "$image")"
+
+workdir="$(mktemp -d)"
+trap 'rm -rf "$workdir"' EXIT
+cd "$workdir"
+
+# --appimage-extract needs no FUSE, so this works on a runner
+# without /dev/fuse and still exercises the real payload.
+"$image" --appimage-extract >/dev/null
+for required in AppRun bin/love game.love lib/liblove-11.5.so; do
+  [ -e "squashfs-root/$required" ] \
+    || { echo "::error::AppImage is missing $required"; exit 1; }
+done
+
+# Every bundled object must resolve once AppRun's LD_LIBRARY_PATH is
+# applied; an unresolved soname here is a user-visible launch crash.
+#
+# This runs on a HEADLESS runner on purpose, and that is the point.
+# The first version of this build bundled Debian's SDL2, which
+# hard-links libpulse/libasound/libX11/libwayland, so it only ever
+# started on a full desktop -- a bare runner is what exposed it.
+missing="$(LD_LIBRARY_PATH="$PWD/squashfs-root/lib" \
+  ldd squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
+  | grep 'not found' || true)"
+[ -z "$missing" ] || { echo "::error::unresolved deps:"; echo "$missing"; exit 1; }
+
+# Nothing may hard-link a driver, session or audio-stack library:
+# those must be reached through dlopen so the AppImage runs on a box
+# with only ALSA, only Wayland, or only KMSDRM.
+linked="$(for f in squashfs-root/bin/love squashfs-root/lib/*.so*; do
+  objdump -p "$f" 2>/dev/null | awk '/NEEDED/{print $2}'
+done | sort -u | grep -E '^lib(pulse|asound|X11|wayland|GL|EGL|drm|gbm|xcb|cairo|sndio|dbus)' || true)"
+[ -z "$linked" ] \
+  || { echo "::error::these must be dlopened, not linked:"; echo "$linked"; exit 1; }
+
+# The whole point of compiling on bullseye. If a future change moves
+# the builder to a newer base, the glibc floor silently rises and
+# every user on an older distro gets "GLIBC_2.xx not found" -- catch
+# it here instead of in a release.
+floor="$(objdump -T squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
+  | grep -o 'GLIBC_[0-9.]*' | sort -V | tail -1)"
+echo "highest required glibc symbol version: $floor"
+[ -n "$floor" ] \
+  || { echo "::error::found no versioned glibc symbols -- objdump read nothing"; exit 1; }
+highest="$(printf '%s\n' "$floor" "GLIBC_2.31" | sort -V | tail -1)"
+[ "$highest" = "GLIBC_2.31" ] \
+  || { echo "::error::AppImage requires $floor, above the bullseye 2.31 floor"; exit 1; }
+
+echo "AppImage verified: $image"

scripts/pack_love.sh

@@ -50,6 +50,7 @@ rm -f "$OUTPUT"
   main.lua conf.lua src data assets tools/save-editor \
   tools/rom_manifest.json tools/rom_manifest_blue.json \
   tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+  tools/rom_manifest_silver.json \
   -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
 if [ -f "$ROOT/PATCH_NOTES.md" ]; then
   (cd "$ROOT" && zip -q "$OUTPUT" PATCH_NOTES.md)
@@ -94,6 +95,7 @@ for required in tools/save-editor/App.lua tools/save-editor/Kit.lua \
                 tools/save-editor/panels/Party.lua \
                 tools/rom_manifest.json tools/rom_manifest_blue.json \
                 tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+                tools/rom_manifest_silver.json \
                 src/ui/kit/Kit.lua \
                 src/import/LauncherView.lua; do
   grep -qxF "$required" "$LISTING" \

scripts/run.sh

@@ -17,7 +17,9 @@ fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
 
 if [ ! -f "$ROOT/data/generated/maps.lua" ] \
     && [ ! -f "$ROOT/blue/data/generated/maps.lua" ] \
-    && [ ! -f "$ROOT/yellow/data/generated/maps.lua" ]; then
+    && [ ! -f "$ROOT/yellow/data/generated/maps.lua" ] \
+    && [ ! -f "$ROOT/gold/data/generated/maps.lua" ] \
+    && [ ! -f "$ROOT/silver/data/generated/maps.lua" ]; then
   fail "generated data missing,  run scripts/setup.sh first"
 fi
 

scripts/switch/pack_sd_zip.sh

@@ -71,15 +71,15 @@ First install or update (same steps):
      your saves, imported ROMs, mods, and options. Re-extracting only
      replaces the NRO(s) and these help files.
   3. Launch with title override (hold R on HOME, open any title → hbmenu).
-  4. Copy a legal Pokemon Red/Blue .gb or Yellow/Gold .gbc into:
+  4. Copy a legal Pokemon Red/Blue .gb or Yellow/Gold/Silver .gbc into:
        switch/gen1recomp/pokemon-love2d/imports/
      then use Scan again in the launcher if needed.
 
 Inboxes (drop files here via MTP / SD / FTP):
   imports/                      — ROM .gb / .gbc
   imports/mods/                 — community mod .zip
-  imports/saves/red|blue|yellow|gold/  — raw .sav import (Gold cart .sav not yet)
+  imports/saves/red|blue|yellow|gold|silver/  — raw .sav import (Gold/Silver cart .sav not yet)
-  exports/red|blue|yellow|gold/        — pull after Export save (Gold not yet)
+  exports/red|blue|yellow|gold|silver/        — pull after Export save (Gold/Silver not yet)
 
 Full guide: https://github.com/bryanthaboi/gen1recomp/blob/main/docs/switch-install.md
 EOF
@@ -92,7 +92,7 @@ write_readme() {
 }
 
 write_readme "$SAVE_ROOT/imports/README.txt" \
-  "Put a legal Pokemon Red/Blue .gb or Yellow/Gold .gbc here, then Scan again in the launcher."
+  "Put a legal Pokemon Red/Blue .gb or Yellow/Gold/Silver .gbc here, then Scan again in the launcher."
 write_readme "$SAVE_ROOT/imports/mods/README.txt" \
   "Put community mod .zip files here, then MODS → Scan again."
 write_readme "$SAVE_ROOT/imports/saves/red/README.txt" \
@@ -103,6 +103,8 @@ write_readme "$SAVE_ROOT/imports/saves/yellow/README.txt" \
   "Put a Yellow .sav (32 KB) here, then Yellow tab → SAVE FILES → Import save."
 write_readme "$SAVE_ROOT/imports/saves/gold/README.txt" \
   "Gold cart .sav import is not supported yet. Folder reserved so MTP matches the other games."
+write_readme "$SAVE_ROOT/imports/saves/silver/README.txt" \
+  "Silver cart .sav import is not supported yet. Folder reserved so MTP matches the other games."
 write_readme "$SAVE_ROOT/exports/red/README.txt" \
   "After Export save (Red), copy the .sav out of this folder via MTP / SD / FTP."
 write_readme "$SAVE_ROOT/exports/blue/README.txt" \
@@ -111,6 +113,8 @@ write_readme "$SAVE_ROOT/exports/yellow/README.txt" \
   "After Export save (Yellow), copy the .sav out of this folder via MTP / SD / FTP."
 write_readme "$SAVE_ROOT/exports/gold/README.txt" \
   "Gold cart .sav export is not supported yet. Folder reserved so MTP matches the other games."
+write_readme "$SAVE_ROOT/exports/silver/README.txt" \
+  "Silver cart .sav export is not supported yet. Folder reserved so MTP matches the other games."
 
 rm -f "$OUT_ZIP"
 (
@@ -140,10 +144,12 @@ REQUIRED=(
   "switch/gen1recomp/pokemon-love2d/imports/saves/blue/README.txt"
   "switch/gen1recomp/pokemon-love2d/imports/saves/yellow/README.txt"
   "switch/gen1recomp/pokemon-love2d/imports/saves/gold/README.txt"
+  "switch/gen1recomp/pokemon-love2d/imports/saves/silver/README.txt"
   "switch/gen1recomp/pokemon-love2d/exports/red/README.txt"
   "switch/gen1recomp/pokemon-love2d/exports/blue/README.txt"
   "switch/gen1recomp/pokemon-love2d/exports/yellow/README.txt"
   "switch/gen1recomp/pokemon-love2d/exports/gold/README.txt"
+  "switch/gen1recomp/pokemon-love2d/exports/silver/README.txt"
 )
 for rel in "${REQUIRED[@]}"; do
   printf '%s\n' "$LISTING" | grep -Fq "$rel" || fail "zip missing $rel"

scripts/switch/selftest_build_switch.sh

@@ -271,10 +271,12 @@ for rel in \
   "switch/gen1recomp/pokemon-love2d/imports/saves/blue/README.txt" \
   "switch/gen1recomp/pokemon-love2d/imports/saves/yellow/README.txt" \
   "switch/gen1recomp/pokemon-love2d/imports/saves/gold/README.txt" \
+  "switch/gen1recomp/pokemon-love2d/imports/saves/silver/README.txt" \
   "switch/gen1recomp/pokemon-love2d/exports/red/README.txt" \
   "switch/gen1recomp/pokemon-love2d/exports/blue/README.txt" \
   "switch/gen1recomp/pokemon-love2d/exports/yellow/README.txt" \
-  "switch/gen1recomp/pokemon-love2d/exports/gold/README.txt"
+  "switch/gen1recomp/pokemon-love2d/exports/gold/README.txt" \
+  "switch/gen1recomp/pokemon-love2d/exports/silver/README.txt"
 do
   printf '%s\n' "$ZIP_LIST" | grep -Fq "$rel" || PACK_MISSING="${PACK_MISSING} ${rel}"
 done

scripts/test.sh

@@ -67,6 +67,7 @@ run_tier() {
 # ------- ROM-free tiers: these are what CI runs
 
 run_tier "T0 ROM builder version routing" python3 tests/build_rom_data_cli_test.py
+run_tier "T0 ROM manifest generator pin/overrides" python3 tests/rom_manifest_generator_test.py
 run_tier "T0 switch CI workflow content gate" "$LUA" tests/switch_ci_workflows_test.lua
 run_tier "T0 switch transfer docs gate" "$LUA" tests/switch_transfer_docs_test.lua
 # NX Blue/Yellow asset overlay: ROM-free, must run on every checkout so a

src/battle/BattleSafety.lua

@@ -8,6 +8,7 @@ local BattleSafety = {}
 local BATTLE_BUSY_FIELDS = {
   "current", "afterQueue", "nextInsert", "pendingHit", "waitingUI",
   "waitingSound", "waitFrames", "draining", "animPlaying", "growIn",
+  "shrinkOut",
   "introSlide", "ghostReveal", "mimicCtx", "mimicMoves", "result",
 }
 

src/battle/BattleState.lua

@@ -1008,9 +1008,23 @@ end
 -- flickers the OBJ palette, DoBallTossSpecialEffects)
 function BattleState:animNext(name, isPlayer, shakes, ball)
   self.nextInsert = (self.nextInsert or 0) + 1
-  table.insert(self.queue, self.nextInsert,
+  local row = { anim = name, attackerIsPlayer = isPlayer, shakes = shakes,
-               { anim = name, attackerIsPlayer = isPlayer, shakes = shakes,
+                ball = ball }
-                 ball = ball })
+  table.insert(self.queue, self.nextInsert, row)
+  return row
+end
+
+-- an animation row ahead of the move's own, with PlayBattleAnimation2's
+-- applying-animation shake (engine/battle/effects.asm:1461-1471)
+function BattleState:animBeforeMove(name, isPlayer)
+  local at
+  for i, item in ipairs(self.queue) do
+    if item == self.moveAnimRow then at = i break end
+  end
+  self.nextInsert = (self.nextInsert or 0) + 1
+  table.insert(self.queue, at or self.nextInsert,
+               { anim = name, attackerIsPlayer = isPlayer, animDelayed = true,
+                 hit = { animType = isPlayer and 6 or 3 } })
 end
 
 -- insert an act right after the current queue item
@@ -1350,7 +1364,7 @@ function BattleState:updateQueue()
     -- subanimation (or just the coarse fx when animations are off).
     -- item.hit carries the target's blink + damage sound, applied when
     -- the animation ends (hitRow rows carry a hit with no animation --
-    -- thrash/rage continuation turns that skip the announcement).
+    -- Mimic, whose animation waits on a successful copy).
     if item.anim or item.hitRow then
       -- PlayMoveAnimation writes wAnimationID, calls Delay3, and only then
       -- jumps to MoveAnimation (core.asm:6635-6640), so three frames pass
@@ -1554,8 +1568,13 @@ end
 function BattleState:sendOutText(name)
   local e = self.enemy and self.enemy.mon
   local pct = 100
-  if e and e.hp > 0 and math.floor(e.stats.hp / 4) > 0 then
+  if e and e.hp > 0 then
-    pct = math.floor(e.hp * 25 / math.floor(e.stats.hp / 4))
+    -- the same routine stamps wLastSwitchInEnemyMonHP
+    -- (engine/battle/common_text.asm:105-110)
+    self.lastSwitchInEnemyHP = e.hp
+    if math.floor(e.stats.hp / 4) > 0 then
+      pct = math.floor(e.hp * 25 / math.floor(e.stats.hp / 4))
+    end
   end
   if pct >= 70 then return Strings("Go! %s!", name) end
   if pct >= 40 then return Strings("Do it! %s!", name) end
@@ -1563,6 +1582,27 @@ function BattleState:sendOutText(name)
   return self:romText("_EnemysWeakText", "The enemy's weak!\nGet'm! %s!", name)
 end
 
+-- RetreatMon / PlayerMon2Text (engine/battle/common_text.asm:167-243): the
+-- adjective reads the enemy HP lost since this mon switched in
+function BattleState:withdrawText(name)
+  local e = self.enemy and self.enemy.mon
+  local drop = 0
+  if e and self.lastSwitchInEnemyHP and math.floor(e.stats.hp / 4) > 0 then
+    drop = math.floor((self.lastSwitchInEnemyHP - e.hp) * 25
+                      / math.floor(e.stats.hp / 4))
+  end
+  local word = ""
+  if drop <= 0 then
+    word = self:romText("_EnoughText", "enough!")
+  elseif drop >= 70 then
+    word = self:romText("_GoodText", "good!")
+  elseif drop >= 30 then
+    word = self:romText("_OKExclamationText", "OK!")
+  end
+  return self:romText("_PlayerMon2Text", "%s ", name) .. word
+         .. self:romText("_ComeBackText", "\nCome back!")
+end
+
 -- The cry a mon makes as it takes the field.  Yellow does not run its
 -- starter Pikachu through PlayCry at all: SendOutMon branches to
 -- .starterPikachu (engine/battle/core.asm:1807-1817) and voices PCM
@@ -1678,9 +1718,14 @@ function BattleState:enter()
     -- _PlayerBlackedOutText2 (data/text/text_2.asm:896): the two paragraphs
     -- playerMonFainted queues on the battle screen; there is no battle
     -- screen to queue them on here, so they print over the map.
+    -- _PlayerBlackedOutText (no "2") extracts to the identical wording from
+    -- a different ROM address and is unused anywhere in this engine -- not
+    -- a fallback for this one, just pokered printing the same paragraph
+    -- from a second call site elsewhere.
     self.game.stack:push(require("src.render.TextBox").new(self.game,
-      Strings("%s is out of\nuseable POKéMON!", name) .. "\f"
+      self:romText("_PlayerBlackedOutText2",
-      .. Strings("%s blacked\nout!", name), blackedOut))
+        "%s is out of\nuseable POKéMON!\f%s blacked\nout!", name, name),
+      blackedOut))
     return
   end
   self.musicKind = self:computeMusicKind()
@@ -1816,7 +1861,9 @@ function BattleState:enter()
       self.enemySendingOut = true
       self:slidePic("foe")
     end)
-    self:say(Strings("%s sent\nout %s!", foeName, self.enemy.name))
+    -- _TrainerSentOutText ends `done`, not `prompt` (data/text/text_2.asm:923)
+    self:sayAuto(self:romText("_TrainerSentOutText", "%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
@@ -1845,7 +1892,8 @@ function BattleState:enter()
       self.sendingOut = true
       self:slidePic("back")
     end)
-    self:say(self:sendOutText(self.player.name))
+    -- _GoText.._PlayerMon1Text carry no prompt (data/text/text_2.asm:1274-1294)
+    self:sayAuto(self:sendOutText(self.player.name))
     -- then the POOF plays and the mon appears with its cry
     -- (SendOutMon: message -> AnimateSendingOutMon -> PlayCry)
     self:queueSendOutAnim(true)
@@ -2447,9 +2495,12 @@ function BattleState:openOldManBag()
     -- POKé BALLs; pokeyellow's SimulatedInputBattleItemList, shared by
     -- the Viridian tutorial and Oak's catch, has one.
     local qty = require("src.core.GameVersion").isYellow() and "x1" or "x50"
+    -- the tutorial bag rides DisplayBagMenu's LIST_MENU_BOX over the battle
+    -- screen (engine/battle/core.asm:2210)
     list = ListMenu.new(game, "ITEMS", {
       { value = "POKE_BALL", label = Strings("POKé BALL"), right = qty },
     }, {
+      itemBox = true,
       script = function(l)
         l.scriptTimer = (l.scriptTimer or 0) + 1
         if l.scriptTimer == 81 then
@@ -2659,22 +2710,30 @@ function BattleState:resolveSwitch(newMon)
   self.phase = "messages"
   self.afterQueue = "menu"
   self:act(function()
-    self:restoreMimicked(self.player) -- the battle copy leaves with it
+    -- SwitchPlayerMon (core.asm:2419-2423): RetreatMon prints over the
-    local previous = self.player
+    -- outgoing pic and holds 50 frames, then AnimateRetreatingPlayerMon
-    self.player = makeBattler(self.data, newMon, true, self.game.save)
+    -- runs before the mon is recalled
-    -- SendOutMon (core.asm:1761-1762): player's send-out clears the
+    self:sayNextAuto(self:withdrawText(self.player.name),
-    -- foe's USING_TRAPPING_MOVE -- Wrap/Bind/etc. ends on any switch
+                     Timing.SWITCH_PLAYER_MON)
-    clearTrapping(self.enemy)
+    self:queueRetreatAnim()
-    self:syncSides()
+    self:actNext(function()
-    Runtime.emit("battle.battler_switched", {
+      self:restoreMimicked(self.player) -- the battle copy leaves with it
-      battle = self, side = self.sides[1], battler = self.player,
+      local previous = self.player
-      previous = previous,
+      self.player = makeBattler(self.data, newMon, true, self.game.save)
-    })
+      -- SendOutMon (core.asm:1761-1762): player's send-out clears the
-    self:markParticipant()
+      -- foe's USING_TRAPPING_MOVE -- Wrap/Bind/etc. ends on any switch
-    sendOutMonCursors(self)
+      clearTrapping(self.enemy)
-    self.sendingOut = true
+      self:syncSides()
-    self:sayNext(self:sendOutText(self.player.name))
+      Runtime.emit("battle.battler_switched", {
-    self:queueSendOutAnim(false)
+        battle = self, side = self.sides[1], battler = self.player,
+        previous = previous,
+      })
+      self:markParticipant()
+      sendOutMonCursors(self)
+      self.sendingOut = true
+      self:sayNextAuto(self:sendOutText(self.player.name))
+      self:queueSendOutAnim(false)
+    end)
   end)
   self:act(function()
     self:executeAction(self.enemy, self.player, self:enemyAction())
@@ -2703,7 +2762,12 @@ function BattleState:residualFor(b, opp)
   if b.residualDone then return end
   b.residualDone = true
   local msgs = Status.residual(b, opp, self)
+  local rec = Status.recordFor(self.data and self.data.statuses, b.mon.status)
   for _, m in ipairs(msgs) do self:sayNext(prefixEnemy(m, b)) end
+  -- engine/battle/core.asm:490-493
+  if rec and rec.residual then
+    self:animNext("BURN_PSN_ANIM", b.isPlayer)
+  end
   if b.leechSeeded and b.mon.hp > 0 then
     -- the drain plays the ABSORB animation from the healing side
     -- (core.asm:506-517 flips hWhoseTurn before PlayMoveAnimation)
@@ -3263,6 +3327,26 @@ function BattleState:queueSendOutAnim(append)
   if append then self:act(fn) else self:actNext(fn) end
 end
 
+-- AnimateRetreatingPlayerMon (core.asm:1769-1796); the Yellow starter Pikachu
+-- slides off instead (pokeyellow core.asm:1862-1866, animations.asm:1259)
+function BattleState:queueRetreatAnim()
+  if self:starterPikachuSendOut() then
+    self:actNext(function() self:slidePic("playerMon", 0, -64, 8, 3) end)
+    self:waitNext(24)
+    self:actNext(function()
+      -- .clearScreenArea keeps the 7x7 area blank until the swap
+      -- (pokeyellow core.asm:1867-1871) (#1545)
+      self.sendingOut = true
+      self:slidePic("playerMon")
+    end)
+  else
+    self:actNext(function()
+      self.shrinkOut = { battler = self.player, frame = 0 }
+    end)
+    self:waitNext(7)
+  end
+end
+
 -- Should the low-health alarm sound this frame?  pokered keys it off
 -- the drawn bar color: DrawPlayerHUDAndHPBar (core.asm:1846-1875) sets
 -- wLowHealthAlarm bit 7 when GetHealthBarColor says the player bar is
@@ -3479,6 +3563,12 @@ function BattleState:updateFx()
     self.growIn.frame = self.growIn.frame + 1
     if self.growIn.frame >= 12 then self.growIn = nil end
   end
+  -- the retreat shrink (AnimateRetreatingPlayerMon): 4+3 frames, then the
+  -- 7x7 area holds cleared (scale 0) until the swap replaces the battler
+  if self.shrinkOut then
+    self.shrinkOut.frame = self.shrinkOut.frame + 1
+    if self.shrinkOut.battler ~= self.player then self.shrinkOut = nil end
+  end
   -- low-HP alarm (audio/low_health_alarm.asm): the two-tone siren
   -- loops while the player's bar is red; see lowHealthAlarmActive
   local Sound = require("src.core.Sound")
@@ -3585,9 +3675,20 @@ function BattleState:executeAction(user, target, action)
       })
       self.aiUses = self:aiUsesFor()
       markSeen(self.game, self.enemy.mon.species)
-      -- _AIBattleWithdrawText: "X with-/drew Y!"
+      self:sayNext(self:romText("_AIBattleWithdrawText", "%s with-\ndrew %s!",
-      self:sayNext(Strings("%s with-\ndrew %s!", self.trainer.name, oldName))
+        self.trainer.name, oldName))
-      self:sayNext(Strings("%s sent\nout %s!", self.trainer.name, self.enemy.name))
+      -- EnemySendOut falls into EnemySendOutFirstMon: TrainerSentOutText,
+      -- then AnimateSendingOutMon and PlayCry (core.asm:1276-1434)
+      self.enemySendingOut = true
+      self:sayNextAuto(self:romText("_TrainerSentOutText", "%s sent\nout %s!",
+        self.trainer.name, self.enemy.name))
+      self:actNext(function()
+        self.enemySendingOut = false
+        self:startGrowIn(self.enemy)
+        self:actNext(function()
+          self:waitSfxNext(self:playEntranceCry(self.enemy))
+        end)
+      end)
       return
     end
 
@@ -3732,6 +3833,8 @@ function BattleState:statusInterrupt(user, target, selectedId)
                                    { rng = self.rng, forceCrit = false, typeless = true,
                                      screens = target })
     self:sayNext(self:romText("_HurtItselfText", "It hurt itself in\nits confusion!"))
+    -- HandleSelfConfusionDamage (core.asm:3706-3714, enemy side :5807-5811)
+    self:animNext("POUND", not user.isPlayer)
     self:clearVolatiles(user, true)
     self:applyDamage(user, dmg)
     if user.mon.hp <= 0 then self:onFaint(user) end
@@ -3824,18 +3927,28 @@ function BattleState:performMove(user, target, moveInst, isCalled)
   end
 
   self.moveAnimRow = nil
-  if not (user.thrashTurns and moveInst == user.thrashMove and user.thrashAnnounced) then
+  local thrashing = user.thrashTurns and moveInst == user.thrashMove
-    self:sayNextAuto(self:romText("_ItemUseText001", "%s\nused %s!", displayName(user), move.name))
+    and user.thrashAnnounced or false
-    -- the move's animation plays right after the announcement; the
+  if thrashing then
-    -- damage path attaches the target's hit blink to this row so the
+    -- .ThrashingAboutCheck (core.asm:3531-3552)
-    -- blink follows the animation (pokered's order).  Mimic is the
+    self:sayNextAuto(self:romText("_ThrashingAboutText", "%s's\nthrashing about!",
-    -- exception (announceAnim = false): PlayCurrentMoveAnimation runs
+                                  displayName(user)))
-    -- only after a successful copy, never on a miss -- applyMimic queues it
+    user.thrashTurns = user.thrashTurns - 1
-    if not (record and record.announceAnim == false) then
+    if user.thrashTurns <= 0 then
-      self.nextInsert = (self.nextInsert or 0) + 1
+      user.thrashTurns, user.thrashMove, user.thrashAnnounced = nil, nil, nil
-      self.moveAnimRow = { anim = move.id, attackerIsPlayer = user.isPlayer }
+      if not user.confusedTurns then user.confusedTurns = self.rng(2, 5) end
-      table.insert(self.queue, self.nextInsert, self.moveAnimRow)
     end
+  else
+    self:sayNextAuto(self:romText("_ItemUseText001", "%s\nused %s!", displayName(user), move.name))
+  end
+  -- PlayCurrentMoveAnimation follows the announcement; Mimic (announceAnim
+  -- = false) queues it from applyMimic after a successful copy
+  if not (record and record.announceAnim == false) then
+    self.nextInsert = (self.nextInsert or 0) + 1
+    -- ld a, THRASH / ld [wPlayerMoveNum] (core.asm:3534-3535, :5909-5910) #1577
+    self.moveAnimRow = { anim = thrashing and "THRASH" or move.id,
+                         attackerIsPlayer = user.isPlayer }
+    table.insert(self.queue, self.nextInsert, self.moveAnimRow)
   end
   Runtime.emit("battle.move_used", {
     battle = self, user = user, target = target, move = move,
@@ -3843,6 +3956,9 @@ function BattleState:performMove(user, target, moveInst, isCalled)
   })
 
   local ctx = EffectRegistry.makeCtx(self, user, target, move, moveInst, isCalled)
+  -- .ThrashingAboutCheck jumps past JumpMoveEffect into PlayerCalcMoveDamage
+  -- (core.asm:3540), so SpecialEffectsCont never re-runs on a locked turn
+  ctx.thrashing = thrashing
 
   -- Metronome / Mirror Move re-entry; a nil pick means the record
   -- already said its failure text
@@ -3864,7 +3980,17 @@ function BattleState:performMove(user, target, moveInst, isCalled)
   -- record (chargeText) and the invulnerability from semiInvulnerable,
   -- falling back to the id tables (Fly AND Dig go semi-invulnerable:
   -- ChargeEffect sets INVULNERABLE for both)
-  if record and record.charge and not releasing then
+  local chargeRequired = record and record.charge ~= nil and not releasing
+  if chargeRequired and Runtime.wantsHook("battle.charge_required") then
+    local required = Runtime.call("battle.charge_required", function(c)
+      return c.charge
+    end, {
+      battle = self, user = user, target = target, move = move,
+      charge = true, isCalled = isCalled or false,
+    })
+    chargeRequired = required ~= false
+  end
+  if chargeRequired then
     self:cancelMoveAnim()
     user.charging = moveInst
     user.chargeReady = true
@@ -4079,8 +4205,12 @@ function BattleState:onFaint(battler)
     -- acknowledged core.asm:797-798 bug.)
     self:actNext(function() self:playVictoryMusic() end)
   end
-  -- _EnemyMonFaintedText "Enemy X fainted!" / _PlayerMonFaintedText
+  -- _EnemyMonFaintedText already carries its own "Enemy" wording, so this
-  self:sayNext(Strings("%s\nfainted!", displayName(battler)))
+  -- passes the raw name -- displayName's separate Strings("Enemy %s", ...)
+  -- would double it up
+  self:sayNext(battler.isPlayer
+    and self:romText("_PlayerMonFaintedText", "%s\nfainted!", battler.name)
+    or self:romText("_EnemyMonFaintedText", "Enemy %s\nfainted!", battler.name))
   if battler.isPlayer then
     self:act(function() self:playerMonFainted() end)
   else
@@ -4111,8 +4241,11 @@ function BattleState:awardExp()
   end
   local function applyShare(mon, split, announce)
     local playerId = self.game.save.player and self.game.save.player.id
-    local traded = mon.traded == true
+    -- GainExperience (engine/battle/experience.asm:69-88) compares the
-      or (mon.otId ~= nil and playerId ~= nil and mon.otId ~= playerId)
+    -- stored MON_OTID against wPlayerID every award; no persistent flag
+    -- mon.traded covers otId-less mons (repairTradedOtIds, old link peers) #1488
+    local traded = playerId ~= nil and ((mon.otId ~= nil and mon.otId ~= playerId)
+      or (mon.otId == nil and mon.traded == true))
     local levels, gained = Experience.apply(self.data, mon, self.enemy.def,
                                             self.enemy.mon.level, self.kind == "trainer",
                                             split, traded)
@@ -4256,27 +4389,52 @@ function BattleState:enemyMonFainted()
         -- "X is" off so "about to use" stays above the name, instead of the
         -- page ending on a bare nick (#565).  Then para "Will PLAYER" /
         -- "change POKéMON?" with YES/NO.
+        --
+        -- _TrainerAboutToUseText combines both \f-paged, but unlike
+        -- _ItemUseBallText00's say()+say() merge above, this is say()+
+        -- sayChoice(): tried merging into one romText/sayChoice call and
+        -- confirmed via tests/engine/trainer_shift_prompt_bug565.lua that
+        -- the battle queue's own \f handling (not TextBox.lua's) does not
+        -- page a sayChoice string the same way -- left as two calls.
         self:say(Strings("%s is\nabout to use\v%s!", self.trainer.name, nextName))
+        -- EnemySendOutFirstMon .next9/.next8 (core.asm:1390-1409) and
+        -- HasMonFainted's NoWillText (core.asm:1473-1488)
         self:sayChoice(
           Strings("Will %s\nchange POKéMON?", self.game.save.player.name),
           function(yes)
             if not yes then return end
             local game = self.game
-            Screens.push(game, "PartyMenu", {
+            local shiftOpts, reopenShift
+            reopenShift = function(text)
+              table.insert(self.queue, 1, { ui = function()
+                return self:buildScreen("PartyMenu", shiftOpts)
+              end })
+              table.insert(self.queue, 1, { text = text })
+            end
+            shiftOpts = {
               battle = self,
               party = self:playerPartyView(),
               forceSwitch = true,
               onSwitch = function(mon)
-                if mon ~= self.player.mon and mon.hp > 0 then
+                if mon == self.player.mon then
+                  reopenShift(self:romText("_AlreadyOutText",
+                    "%s is\nalready out!", self.player.name))
+                elseif mon.hp <= 0 then
+                  reopenShift(self:romText("_NoWillText", "There's no will\nto fight!"))
+                else
                   shiftSwitchMon = mon
                 end
               end,
-            })
+            }
+            Screens.push(game, "PartyMenu", shiftOpts)
           end, { box = Theme.trainerSwitchBox })
       end
       self:act(function()
         local previous = self.enemy
         self.enemy = makeBattler(self.data, self.enemyParty[self.enemyIndex], false)
+        -- EnemySendOutFirstMon (core.asm:1359-1363): the fresh foe's HP is the
+        -- new wLastSwitchInEnemyMonHP baseline RetreatMon measures from
+        self.lastSwitchInEnemyHP = self.enemy.mon.hp
         -- EnemySendOutFirstMon (core.asm:1314-1315): clears player's trap
         clearTrapping(self.player)
         self:syncSides()
@@ -4296,7 +4454,8 @@ function BattleState:enemyMonFainted()
         -- (AnimateSendingOutMon) with the cry; no POOF -- that animation
         -- belongs to the player-side SendOutMon (core.asm:1757-1762)
         self.enemySendingOut = true
-        self:sayNext(Strings("%s sent\nout %s!", self.trainer.name, self.enemy.name))
+        self:sayNextAuto(self:romText("_TrainerSentOutText", "%s sent\nout %s!",
+          self.trainer.name, self.enemy.name))
         self:actNext(function()
           self.enemySendingOut = false
           self:startGrowIn(self.enemy)
@@ -4309,34 +4468,42 @@ function BattleState:enemyMonFainted()
       self:act(function()
         local mon = shiftSwitchMon
         if not mon then return end
-        local previous = self.player
+        -- SwitchPlayerMon (core.asm:2419-2423): RetreatMon, the 50-frame
-        self.player = makeBattler(self.data, mon, true, self.game.save)
+        -- hold, AnimateRetreatingPlayerMon, then the recall and the send-out
-        clearTrapping(self.enemy)
-        self:syncSides()
-        Runtime.emit("battle.battler_switched", {
-          battle = self, side = self.sides[1],
-          battler = self.player, previous = previous,
-        })
-        -- Taking the SHIFT offer ZEROES wPartyGainExpFlags and
-        -- wPartyFoughtCurrentEnemyFlags before jumping to SwitchPlayerMon
-        -- (EnemySendOutFirstMon tail, core.asm:1436-1443), and SwitchPlayerMon
-        -- then FLAG_SETs only the mon coming in (core.asm:2424-2433).  Without
-        -- the reset the mon that was out when the enemy fainted -- marked by
-        -- the send-out act above, which mirrors EnemySendOut's own re-flag
-        -- (core.asm:1276-1289) -- stayed a participant, so the exp divisor in
-        -- enemyMonFainted counted two mons and the switch-in earned half the
-        -- next KO (#275).  Voluntary switches (resolveSwitch) and post-faint
-        -- replacements (openReplacementMenu) must NOT do this: pokered's
-        -- party-menu SwitchPlayerMon keeps the outgoing mon flagged, which is
-        -- the deliberate exp-share, and a fainted mon is already dropped by
-        -- onFaint mirroring RemoveFaintedPlayerMon (core.asm:1002-1007).
-        self.participants = {}
-        self:markParticipant()
         self.nextInsert = 0
-        sendOutMonCursors(self)
+        self:sayNextAuto(self:withdrawText(self.player.name),
-        self.sendingOut = true
+                         Timing.SWITCH_PLAYER_MON)
-        self:sayNext(self:sendOutText(self.player.name))
+        self:queueRetreatAnim()
-        self:queueSendOutAnim(false)
+        self:actNext(function()
+          local previous = self.player
+          self.player = makeBattler(self.data, mon, true, self.game.save)
+          clearTrapping(self.enemy)
+          self:syncSides()
+          Runtime.emit("battle.battler_switched", {
+            battle = self, side = self.sides[1],
+            battler = self.player, previous = previous,
+          })
+          -- Taking the SHIFT offer ZEROES wPartyGainExpFlags and
+          -- wPartyFoughtCurrentEnemyFlags before jumping to SwitchPlayerMon
+          -- (EnemySendOutFirstMon tail, core.asm:1436-1443), and SwitchPlayerMon
+          -- then FLAG_SETs only the mon coming in (core.asm:2424-2433).  Without
+          -- the reset the mon that was out when the enemy fainted -- marked by
+          -- the send-out act above, which mirrors EnemySendOut's own re-flag
+          -- (core.asm:1276-1289) -- stayed a participant, so the exp divisor in
+          -- enemyMonFainted counted two mons and the switch-in earned half the
+          -- next KO (#275).  Voluntary switches (resolveSwitch) and post-faint
+          -- replacements (openReplacementMenu) must NOT do this: pokered's
+          -- party-menu SwitchPlayerMon keeps the outgoing mon flagged, which is
+          -- the deliberate exp-share, and a fainted mon is already dropped by
+          -- onFaint mirroring RemoveFaintedPlayerMon (core.asm:1002-1007).
+          self.participants = {}
+          self:markParticipant()
+          self.nextInsert = 0
+          sendOutMonCursors(self)
+          self.sendingOut = true
+          self:sayNextAuto(self:sendOutText(self.player.name))
+          self:queueSendOutAnim(false)
+        end)
       end)
       return
     end
@@ -4378,9 +4545,22 @@ function BattleState:enemyMonFainted()
       -- TrainerNamePointers aims those entries at wTrainerName).  The tag
       -- prints once, so a `para` page carries no second copy (#566).
       local tag = self.trainer and self.trainer.name
+      -- the badge jingle (sound_get_item_1 and friends) rides the armed
+      -- line's first page, as the script's text command would (#1606)
+      local sfx = self.endBattleSound
+      local data = self.data
       for page in (self.endBattleText .. "\f"):gmatch("(.-)\f") do
         if page ~= "" then
-          self:sayNext(tag and (tag .. ": " .. page) or page)
+          local line = tag and (tag .. ": " .. page) or page
+          if sfx then
+            local id = sfx
+            self:sayNextWaitSfx(line, function()
+              return require("src.core.Sound").play(data, id)
+            end)
+            sfx = nil
+          else
+            self:sayNext(line)
+          end
           tag = nil
         end
       end
@@ -4526,7 +4706,7 @@ function BattleState:openReplacementMenu()
         self.nextInsert = 0
         sendOutMonCursors(self)
         self.sendingOut = true
-        self:sayNext(self:sendOutText(self.player.name))
+        self:sayNextAuto(self:sendOutText(self.player.name))
         self:queueSendOutAnim(false)
       end,
     })
@@ -4805,7 +4985,8 @@ function BattleState:storeCaughtMon()
     -- 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),
+      self:romText("_ItemUseBallText06",
+        "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)
@@ -4826,9 +5007,12 @@ function BattleState:storeCaughtMon()
     if boxNum then
       askCaughtNickname()
       -- _ItemUseBallText07/08 keyed on EVENT_MET_BILL
-      local pc = (game.save.flags and game.save.flags.EVENT_MET_BILL)
+      local metBill = game.save.flags and game.save.flags.EVENT_MET_BILL
-                 and "BILL's PC" or Strings("someone's PC")
+      self:sayNext(self:romText(
-      self:sayNext(Strings("%s was\ntransferred to\n%s!", self.enemy.name, pc))
+        metBill and "_ItemUseBallText07" or "_ItemUseBallText08",
+        metBill and "%s was\ntransferred to\nBILL's PC!"
+                or "%s was\ntransferred to\nsomeone's PC!",
+        self.enemy.name))
     else
       self:sayNext(Strings("But every BOX\nis full!"))
     end
@@ -4934,8 +5118,18 @@ function BattleState:throwBall(ball)
       -- RESTLESS SOUL dodges balls even once the scope has revealed it,
       -- so it is not a ghost battle any more (#444)
       self:animNext(self:tossAnimFor(ball), true, nil, ball)
-      self:sayNext(Strings("It dodged the\nthrown BALL!"))
+      -- _ItemUseBallText00 is one label for both lines, \f-paged.  Unlike
-      self:sayNext(Strings("This POKéMON\ncan't be caught!"))
+      -- TextBox.new() (which splits \f itself), the battle queue's own
+      -- startMessage() only splits on \n/\v -- confirmed live: the \f
+      -- landed mid-line and the second sentence overflowed off the box
+      -- instead of starting a fresh page.  Resolve the label once, then
+      -- split it the same way TextBox.lua does and queue one sayNext per
+      -- page, so the two ROM sentences still render as two pages.
+      local dodgeText = self:romText("_ItemUseBallText00",
+        "It dodged the\nthrown BALL!\fThis POKéMON\ncan't be caught!")
+      for page in (dodgeText .. "\f"):gmatch("(.-)\f") do
+        self:sayNext(page)
+      end
       self:act(function()
         self:executeAction(self.enemy, self.player, self:enemyAction())
       end)
@@ -4982,10 +5176,14 @@ function BattleState:openParty()
       battle = self,
       party = self:playerPartyView(),
       onSwitch = function(mon)
+        -- PartyMenuOrRockOrRun's SWITCH .partyMonDeselected (core.asm:2396-2408)
         if mon == self.player.mon then
-          self:say(Strings("%s is\nalready out!", self.player.name))
+          self:say(self:romText("_AlreadyOutText",
+            "%s is\nalready out!", self.player.name))
+          self:act(function() self:openParty() end)
         elseif mon.hp <= 0 then
           self:say(self:romText("_NoWillText", "There's no will\nto fight!"))
+          self:act(function() self:openParty() end)
         else
           self:resolveSwitch(mon)
         end
@@ -5129,6 +5327,16 @@ function BattleState:growInScale(battler)
   return f < 3 and 0 or f < 7 and 3 / 7 or 5 / 7
 end
 
+-- AnimateRetreatingPlayerMon's CopyDownscaledMonTiles stages
+-- (core.asm:1769-1796)
+function BattleState:shrinkOutScale(battler)
+  local shrink = self.shrinkOut
+  if not shrink or shrink.battler ~= battler then return nil end
+  -- scale 0 past Delay3: the area stays cleared until the swap
+  -- (core.asm:1790-1796) (#1563)
+  return shrink.frame < 4 and 5 / 7 or shrink.frame < 7 and 3 / 7 or 0
+end
+
 -- battler hidden this frame? (damage blink)
 --
 -- AnimationBlinkMon hides the pic, waits DelayFrames 5, shows it, waits
@@ -5765,15 +5973,18 @@ function BattleState:drawPicsLayer(slide, sx, sy, onlySide, skipMenuClip)
     local s = BattleState.resolveBattleScale(self.data, "back",
       imagePathOf(self.player.sprite),
       self.player.mon and self.player.mon.species)
-    local gs = self:growInScale(self.player)
+    local gs = self:growInScale(self.player) or self:shrinkOutScale(self.player)
     if gs then
-      -- the player-side AnimateSendingOutMon grow (after the poof,
+      -- the player-side AnimateSendingOutMon grow (core.asm:1757-1762) and
-      -- core.asm:1757-1762): feet pinned at y=96, horizontal centre
+      -- the AnimateRetreatingPlayerMon shrink (core.asm:1769-1796)
-      -- pinned, mod scale composed with the grow stage
       local eff = s * gs
       if eff > 0 then
+        -- the retreat stages sit one tile right of the grow-in's
+        -- (hlcoord 3,7 / 4,9 vs 2,7 / 3,9, core.asm:1770-1788) (#1563)
+        local shrinkX = self.shrinkOut
+          and self.shrinkOut.battler == self.player and 8 or 0
         love.graphics.draw(img,
-          8 - padL * s + img:getWidth() * s * (1 - gs) / 2 + sx,
+          8 + shrinkX - padL * s + img:getWidth() * s * (1 - gs) / 2 + sx,
           96 - (img:getHeight() - pad) * eff + sy, 0, eff, eff)
       end
     else

src/battle/EffectRegistry.lua

@@ -92,15 +92,33 @@ local function hitCount(ctx, record)
   return dist[r + 1]
 end
 
+-- engine/battle/effects.asm:119-151 (poison), :194-255 (burn/freeze/paralyze)
+local FBP_SIDE_STATUS = { BRN = true, FRZ = true, PAR = true }
+
+local function secondaryStatusFx(battle, user, status)
+  if status == "PSN" then
+    local row = battle:animNext(user.isPlayer and "ENEMY_HUD_SHAKE_ANIM"
+                                or "SHAKE_SCREEN_ANIM", user.isPlayer)
+    row.animDelayed = true
+    row.hit = { animType = user.isPlayer and 6 or 3 }
+  elseif FBP_SIDE_STATUS[status] and user.isPlayer then
+    battle:animNext("ENEMY_HUD_SHAKE_ANIM", true).animDelayed = true
+  end
+end
+
 -- The damaging pipeline, extracted from the performMove monolith: every
 -- stage keeps the original's exact check order and rng consumption
--- (invulnerability -> gate -> hit count -> pre-accuracy -> accuracy ->
+-- (pre-accuracy -> invulnerability -> gate -> hit count -> accuracy ->
 -- damage choice -> hits -> messages -> after-damage -> secondary run).
 function EffectRegistry.runDamaging(battle, ctx, record)
   local user, target = ctx.user, ctx.target
   local move, moveInst = ctx.move, ctx.moveInst
   local neverMiss = record and record.neverMiss
 
+  -- SpecialEffectsCont's JumpMoveEffect (core.asm:3129-3133) runs before
+  -- MoveHitTest's INVULNERABLE test (:3150), mid-Fly/Dig included (#1565)
+  if record and record.beforeAccuracy then record.beforeAccuracy(ctx) end
+
   -- Swift ignores semi-invulnerability (MoveHitTest returns hit for
   -- SWIFT_EFFECT before the INVULNERABLE check)
   if target.invulnerable and not neverMiss then
@@ -129,8 +147,6 @@ function EffectRegistry.runDamaging(battle, ctx, record)
 
   local hits = hitCount(ctx, record)
 
-  if record and record.beforeAccuracy then record.beforeAccuracy(ctx) end
-
   if not neverMiss then
     if not battle:accuracyRoll(move, user, target) then
       -- Explosion/Selfdestruct still animate on a miss (HandleIfPlayerMoveMissed)
@@ -207,7 +223,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   -- replay PlayMoveAnimation per strike (pokered: GetPlayerAnimationType
   -- / GetEnemyAnimationType loop on wNumAttacksLeft); hit 1 reuses the
   -- announcement-time moveAnimRow, later hits queue fresh anim rows.
-  -- Thrash/rage continuations have no announcement anim -- a bare
+  -- Mimic queues no announcement anim (announceAnim = false) -- a bare
   -- hitRow carries the blink instead.
   -- PlayApplyingAttackSound (engine/battle/animations.asm, the routine after
   -- PlayApplyingAttackAnimation) picks the sound off wDamageMultipliers -- 10
@@ -318,7 +334,12 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   -- secondary side effects (blocked by fainting)
   if record and record.run and record.kind ~= "primary"
      and target.mon.hp > 0 and totalDealt > 0 then
-    for _, m in ipairs(record.run(ctx)) do
+    local hadStatus = target.mon.status
+    local msgs = record.run(ctx)
+    if target.mon.status and target.mon.status ~= hadStatus then
+      secondaryStatusFx(battle, user, target.mon.status)
+    end
+    for _, m in ipairs(msgs) do
       battle:sayNext(m)
     end
   end

src/battle/MoveEffects.lua

@@ -581,22 +581,16 @@ MoveEffects.full = {
     end,
   },
   THRASH_PETAL_DANCE_EFFECT = {
-    afterDamage = function(ctx)
+    -- ThrashPetalDanceEffect (effects.asm:791-808) runs before damage
+    -- (data/battle/special_effects.asm:22, core.asm:3531-3552)
+    beforeAccuracy = function(ctx)
       local user = ctx.user
-      if not user.thrashTurns then
+      if ctx.thrashing or user.thrashTurns then return end
-        user.thrashTurns = ctx.rng(2, 3) -- 3-4 attacks total, then confusion
+      user.thrashTurns = ctx.rng(2, 3) -- 3-4 attacks total, then confusion
-        user.thrashMove = ctx.moveInst
+      user.thrashMove = ctx.moveInst
-        user.thrashAnnounced = true
+      user.thrashAnnounced = true
-      else
+      ctx.battle:animBeforeMove(
-        user.thrashTurns = user.thrashTurns - 1
+        user.isPlayer and "SHRINKING_SQUARE_ANIM" or "ANIM_B1", user.isPlayer)
-        if user.thrashTurns <= 0 then
-          user.thrashTurns, user.thrashMove, user.thrashAnnounced = nil, nil, nil
-          if not user.confusedTurns then
-            user.confusedTurns = ctx.rng(2, 5)
-            ctx.say(romText(ctx.battle.data, "_BecameConfusedText", "%s\nbecame confused!", displayName(user)))
-          end
-        end
-      end
     end,
   },
   JUMP_KICK_EFFECT = {

src/battle/gen2/Battle.lua

@@ -166,6 +166,9 @@ Battle.SUBSTATUS_ITEMS = {
 -- be run from or Roared away.
 Battle.BATTLETYPE_FORCESHINY = 7
 Battle.BATTLETYPE_TRAP = 9
+-- LostBattle's .canlose arm (engine/battle/core.asm:2766): the only battle
+-- type whose loss still prints the trainer's own line instead of a whiteout.
+Battle.BATTLETYPE_CANLOSE = 1
 
 -- BadgeStatBoosts (engine/battle/core.asm:6534): each of these Johto badges
 -- raises the PLAYER's in-battle stat by 1/8.  The routine walks every other
@@ -889,10 +892,13 @@ Battle.PRIORITY = {
   EFFECT_ENDURE = 3,
   EFFECT_COUNTER = -1,
   EFFECT_MIRROR_COAT = -1,
-  EFFECT_VITAL_THROW = -1,
+  EFFECT_FORCE_SWITCH = -1,  -- Whirlwind, Roar: priority 0, below BASE
 }
 
 function Battle:movePriority(moveId)
+  -- GetMovePriority `cp VITAL_THROW / ld a, 0 / ret z`
+  -- (engine/battle/core.asm:787-789).
+  if moveId == "VITAL_THROW" then return -1 end
   local def = self:moveDef(moveId)
   return (def and Battle.PRIORITY[def.effect]) or 0
 end
@@ -1488,6 +1494,15 @@ function Battle:useMove(attacker, defender, moveId)
   if def.effect == "EFFECT_SOLARBEAM" and self.weather == "sun" then
     charge = nil
   end
+  if charge and not charging and Runtime.wantsHook("battle.charge_required") then
+    local required = Runtime.call("battle.charge_required", function(c)
+      return c.charge
+    end, {
+      battle = self, user = attacker, target = defender, move = def,
+      charge = true, isCalled = (self.copyDepth or 0) > 0,
+    })
+    if required == false then charge = nil end
+  end
   if charge and not charging then
     state.chargeMove = moveId
     state.vanished = charge.vanish or nil
@@ -2403,10 +2418,11 @@ Battle.MOVE_EFFECTS.EFFECT_BATON_PASS = function(self, attacker)
     self.enemy = party[target]
     self.enemy.volatile = carried
   end
-  self:emit({ kind = "send", side = side,
+  local sent = side == "player" and self.player or self.enemy
-    mon = side == "player" and self.player or self.enemy,
+  self:emit({ kind = "send", side = side, mon = sent,
-    text = "Go! " .. self:monName(side == "player" and self.player
+    hp = sent.hp or 0, status = sent.status or false,
-      or self.enemy) .. "!" })
+    level = sent.level, experience = sent.experience,
+    text = "Go! " .. self:monName(sent) .. "!" })
 end
 
 -- BattleCommand_TrapTarget's .Traps table, one line per move: target first,
@@ -2665,6 +2681,8 @@ Battle.MOVE_EFFECTS.EFFECT_FORCE_SWITCH = function(self, attacker, defender,
     self.stages.enemy = Battle.newStages()
   end
   self:emit({ kind = "send", side = self:sideOf(incoming), mon = incoming,
+    hp = incoming.hp or 0, status = incoming.status or false,
+    level = incoming.level, experience = incoming.experience,
     text = self:monName(incoming) .. " was dragged out!" })
   self:breakTrapsOnSend(incoming)
   self:spikesDamage(incoming)
@@ -3084,6 +3102,7 @@ function Battle:resolveFaints()
       if self.trainer then
         self:emit({ kind = "message",
           text = (self.trainer.name or "TRAINER") .. " was defeated!" })
+        self:printWinLossText("win")
         self:awardPrizeMoney()
       end
       -- CheckPayDay, on the win arm only (engine/battle/core.asm:7971-7976,
@@ -3110,6 +3129,8 @@ function Battle:resolveFaints()
     -- can offer a shift on (engine/battle/core.asm:2241-2278).
     self:emit({ kind = "send", side = "enemy", mon = self.enemy,
       replacement = true,
+      hp = self.enemy.hp or 0, status = self.enemy.status or false,
+      level = self.enemy.level, experience = self.enemy.experience,
       text = (self.trainer and self.trainer.name or "Foe") .. " sent out "
         .. self:monName(self.enemy) .. "!" })
     Runtime.emit("battle.battler_switched", {
@@ -3152,6 +3173,11 @@ function Battle:resolveFaints()
     local nextIndex = Battle.firstHealthy(self.party)
     if not nextIndex then
       self:emit({ kind = "message", text = "You have no more POKéMON!" })
+      -- LostBattle (engine/battle/core.asm:2763-2782): only BATTLETYPE_CANLOSE
+      -- reaches PrintWinLossText on a loss; every other loss whites out.
+      if self.battleType == Battle.BATTLETYPE_CANLOSE then
+        self:printWinLossText("lose")
+      end
       self:endBattle("lose")
       return true
     end
@@ -3177,14 +3203,23 @@ function Battle:resolveFaints()
   return false
 end
 
--- WinTrainerBattle's money arm, which runs after BattleText_EnemyWasDefeated
+-- WinTrainerBattle (engine/battle/core.asm:2310-2323), LostBattle's .canlose
--- and the frontpic slide: the four quarters are dealt between the wallet and
+-- arm (:2769-2782), PrintWinLossText (home/trainers.asm:230)
--- Mom's savings and then one StdBattleTextbox names the figure.
+function Battle:printWinLossText(result)
---
+  local trainer = self.trainer
--- The `ld a, [wDebugFlags] / bit DEBUG_BATTLE_F` skip in front of
+  if not trainer then return end
--- PrintWinLossText is the trainer's own after-battle line, which this port
+  -- The DEBUG_BATTLE_F skip sits in front of PrintWinLossText alone, behind
--- runs from the script on the way out of the battle rather than from here.
+  -- the slide (engine/battle/core.asm:2310, :2320-2323).
--- The payout is not gated on it either way.
+  -- The CANLOSE loss arm runs ClearBox first (:2770-2773).
+  self:emit({ kind = "trainer-return", cleared = result == "lose" or nil })
+  local text = (result == "lose") and trainer.lossText or trainer.winText
+  if type(text) ~= "string" or text == "" then return end
+  -- FarPrintText prints the pointer alone: no trainer-name tag in front of
+  -- it, unlike Gen 1's TrainerEndBattleText (pokered home/trainers.asm:355).
+  self:emit({ kind = "win-text", text = text })
+end
+
+-- WinTrainerBattle's money arm (engine/battle/core.asm:2310-2323)
 function Battle:awardPrizeMoney()
   local save = self.save
   if not (save and save.player) then return nil end
@@ -3505,6 +3540,8 @@ function Battle:switch(index)
   self.participants[index] = true
   self.stages.player = Battle.newStages()
   self:emit({ kind = "send", side = "player", mon = mon,
+    hp = mon.hp or 0, status = mon.status or false,
+    level = mon.level, experience = mon.experience,
     text = "Go! " .. self:monName(mon) .. "!" })
   -- battle.battler_switched, the payload BattleState:resolveSwitch emits on
   -- Gen 1: the side record, whoever walked in, and whoever walked out.
@@ -3969,6 +4006,8 @@ function Battle:enemyTrySwitchOrItem()
     self:clearVolatile(self.enemy)
     self.stages.enemy = Battle.newStages()
     self:emit({ kind = "send", side = "enemy", mon = self.enemy,
+      hp = self.enemy.hp or 0, status = self.enemy.status or false,
+      level = self.enemy.level, experience = self.enemy.experience,
       text = (self.trainer.name or "TRAINER") .. " sent out "
         .. self:monName(self.enemy) .. "!" })
     Runtime.emit("battle.battler_switched", {

src/core/DeltaSkin.lua

@@ -116,11 +116,13 @@ function DeltaSkin.pickAsset(assets, opts, pdfFiles)
   if type(assets) ~= "table" then return nil end
   pdfFiles = pdfFiles or {}
   local raster = {}
+  local pdfName
   for _, key in ipairs(DeltaSkin.ASSET_LADDER) do
     local name = pick(assets, key)
     if key == "medium" and type(name) ~= "string" then name = pick(assets, "normal") end
     if type(name) == "string" and name ~= "" then
       if name:lower():match("%.pdf$") then
+        pdfName = name
         pdfFiles[#pdfFiles + 1] = name
       else
         raster[#raster + 1] = { key = key, name = name }
@@ -130,12 +132,14 @@ function DeltaSkin.pickAsset(assets, opts, pdfFiles)
   local resizable = pick(assets, "resizable")
   if type(resizable) == "string" and resizable ~= "" then
     if resizable:lower():match("%.pdf$") then
+      pdfName = resizable
       pdfFiles[#pdfFiles + 1] = resizable
     else
       raster[#raster + 1] = { key = "large", name = resizable }
     end
   end
-  if #raster == 0 then return nil end
+  local pdfPath = pdfName and DeltaSkin.resolveName(pdfName, opts) or nil
+  if #raster == 0 then return nil, pdfPath end
 
   local target = numOr(opts and opts.targetWidth, DeltaSkin.DEFAULT_TARGET_WIDTH)
   local chosen
@@ -145,7 +149,7 @@ function DeltaSkin.pickAsset(assets, opts, pdfFiles)
     end
   end
   if not chosen then chosen = raster[#raster].name end
-  return DeltaSkin.resolveName(chosen, opts)
+  return DeltaSkin.resolveName(chosen, opts), nil
 end
 
 function DeltaSkin.mergeEdges(base, item)
@@ -288,10 +292,12 @@ function DeltaSkin.buildPage(obj, orient, opts, warnings, pdfFiles)
     addWarning(warnings, orient .. " has no mappingSize; assuming 320x240")
   end
 
+  local imagePath, pdfPath = DeltaSkin.pickAsset(pick(obj, "assets"), opts, pdfFiles)
   local page = {
     name = orient,
     orient = orient,
-    imagePath = DeltaSkin.pickAsset(pick(obj, "assets"), opts, pdfFiles),
+    imagePath = imagePath,
+    pdfPath = pdfPath,
     fullScreen = true,
     normalized = true,
     pixelCoords = false,
@@ -309,6 +315,14 @@ function DeltaSkin.buildPage(obj, orient, opts, warnings, pdfFiles)
   if screen then
     page.viewport = screen
     page.viewportFill = false
+  else
+    -- mappingSize is the overlay, not the device.  Portrait controller
+    -- skins (GBA4iOS-era 320x240 decks, this Pikachu skin, etc.) keep
+    -- that aspect, sit at the bottom, and leave the leftover for the
+    -- Game Boy picture.  A screens/gameScreenFrame rect still fills.
+    page.aspectFromCfg = true
+    page.screenFit = "remainder"
+    if orient == "portrait" then page.anchor = "bottom" end
   end
 
   local baseEdges = pick(obj, "extendedEdges")
@@ -368,9 +382,6 @@ function DeltaSkin.parse(text, opts)
     end
   end
   if #pages == 0 then return nil, "info.json has no usable representation" end
-  if #pdfFiles > 0 then
-    addWarning(warnings, "PDF artwork cannot be imported yet")
-  end
 
   return {
     pages = pages,
@@ -390,6 +401,10 @@ function DeltaSkin.needsConversion(skin)
   local files = skin.pdfFiles
   if type(files) ~= "table" or #files == 0 then return nil end
   for _, page in ipairs(skin.pages or {}) do
+    -- A raster asset, or a JPEG recovered from the PDF at load, means the
+    -- skin can draw.  Parse-only callers still see pdfOnly because they
+    -- have not run extract yet.
+    if page.rasterData then return nil end
     if page.imagePath then return nil end
   end
   return { pdfOnly = true, files = files }

src/core/Game.lua

@@ -326,6 +326,9 @@ function Game:logicSpeed()
   if self.linkSession or (self.linkNet and not self.linkNet.closed) then
     return 1
   end
+  if Game.isFixedSpeedInStack and Game.isFixedSpeedInStack(self.stack) then
+    return 1
+  end
   if self.speedOverride then return GameSpeed.clamp(self.speedOverride) end
   -- Clamp here too, not just in _resolveLogicSpeed's vanilla path: a mod's
   -- core.logic_speed hook can return anything (0, negative, nil, NaN) and
@@ -475,6 +478,15 @@ function Game.speedCategoryInStack(stack)
   return "menu"
 end
 
+function Game.isFixedSpeedInStack(stack)
+  local states = stack and stack.states
+  for i = #(states or {}), 1, -1 do
+    local state = states[i]
+    if state and (state.isFixedSpeed or state.isMinigame) then return true end
+  end
+  return false
+end
+
 -- Whether a state on the stack composes its own screen and so wants the
 -- edge anchors held off (BattleState.holdsUIAnchors).  Whole-stack, like
 -- everything else here: the text box and YES/NO a battle puts up are states
@@ -597,9 +609,10 @@ function Game:draw()
   -- ...and for the same reason the UI's own scale has to know the world is
   -- still the backdrop while an opaque menu covers it.  Renderer:uiScale
   -- steps the UI down with the survey zoom only while a world is behind it,
-  -- gated on this frame's world pass -- which the party menu and the bag end
+  -- gated on this frame's world pass -- which the party menu ends by being
-  -- by being opaque.  Without this hold they lose the step-down and blit at
+  -- opaque (the bag's item box shows the map around it, #1521).  Without
-  -- full fit scale over a battle drawn at the zoomed-out one.
+  -- this hold it loses the step-down and blits at full fit scale over a
+  -- battle drawn at the zoomed-out one.
   Renderer.uiWorldHold = Renderer.battleDim ~= nil
   -- ...and a battle keeps its dialogue box and YES/NO inside its own screen
   -- instead of letting them dock to the window edge.
@@ -906,16 +919,7 @@ function Game:gamepadaxis(joystick, axis, value)
   Input:gamepadaxis(joystick, axis, value)
 end
 
--- conf.lua turns the mobile accelerometer-joystick off (#468), but guard the
+local isAccelerometer = GamepadMap.isAccelerometer
--- generic joystick path anyway: any sensor-style device that still reaches us
--- has gravity pinning an axis past the deadzone, which would hide the touch
--- overlay every instant and steer the player by tilt through the axis-1/2
--- mapping (#459).  Real controllers arrive as SDL gamepads or named sticks,
--- never as "* Accelerometer".
-local function isAccelerometer(joystick)
-  local name = joystick and joystick.getName and joystick:getName()
-  return name ~= nil and name:lower():find("accelerometer", 1, true) ~= nil
-end
 
 -- BindingsMenu's raw-stick capture rides the same top-state routing as the
 -- keyboard and gamepad paths (#632).  Only a stick SDL does not recognize
@@ -970,7 +974,11 @@ end
 -- parked the player until every direction was re-pressed (#799).
 function Game:focus(f)
   Input:reset()
-  if f then Input:reconcile() end
+  if f then
+    Input:reconcile()
+    local eng = self:syncEngine()
+    if eng then pcall(eng.noteResumed, eng) end
+  end
   TouchControls:reset()
   self:cancelPointers()
 end
@@ -990,6 +998,8 @@ function Game:onResume()
   Input:reconcile()
   TouchControls:reset()
   self:cancelPointers()
+  local eng = self:syncEngine()
+  if eng then pcall(eng.noteResumed, eng) end
   -- Chip music may survive NX suspend as a duplicate stream; stop it and let
   -- the active screen re-cue on the next frame (hardware audio check: T19).
   -- Desktop/mobile window-visible flips must not kill overworld music.
@@ -1197,18 +1207,26 @@ end
 
 function Game:syncEngine()
   if self._syncOff then return nil end
-  if self._syncEngineRef then return self._syncEngineRef end
+  local eng = self._syncEngineRef
-  local ok, SyncEngine = pcall(require, "src.sync.SyncEngine")
-  if not ok or type(SyncEngine) ~= "table" then
-    self._syncOff = true
-    return nil
-  end
-  local eng = SyncEngine.shared()
   if not eng then
-    self._syncOff = true
+    local ok, SyncEngine = pcall(require, "src.sync.SyncEngine")
-    return nil
+    if not ok or type(SyncEngine) ~= "table" then
+      self._syncOff = true
+      return nil
+    end
+    eng = SyncEngine.shared()
+    if not eng then
+      self._syncOff = true
+      return nil
+    end
+    self._syncEngineRef = eng
+  end
+  if type(eng.protectPlaythrough) == "function" then
+    local meta = self.save and self.save.meta
+    eng:protectPlaythrough(
+      (self.save and self.save.version) or require("src.core.GameVersion").get(),
+      type(meta) == "table" and meta.playthroughId or nil)
   end
-  self._syncEngineRef = eng
   return eng
 end
 
@@ -1248,6 +1266,7 @@ function Game:applyOptions(opts)
   -- after VideoMode: a faithful-resolution lock is an exact window size, so
   -- it has to be the last word on the window (it drops fullscreen to hold)
   require("src.core.FaithfulRes").applyOptions(opts)
+  require("src.core.ScreenPosition").applyOptions(opts)
   -- normalizes a nil/garbage cap to the 60 default, so old saves with no
   -- fpsCap key pace at the standard rate (issue #88)
   require("src.core.FrameCap").applyOptions(opts)

src/core/Game2.lua

@@ -3,7 +3,7 @@
 -- everything under src/*/gen2 reaches shared services through here.  Gen 1
 -- Game:load cannot consume a Gen 2 cache -- different generated tables, save
 -- shape and screen registry -- so main.lua's bootGame picks this owner when
--- GameVersion.isGold(), and the two never branch into each other.
+-- GameVersion.generation() == 2, and the two never branch into each other.
 --
 -- Boot: copyright → GameFreak Presents → GS intro stub → title
 -- (tilemap + Ho-Oh flap / clouds / trails) → Oak speech (Marill + shrink)
@@ -18,6 +18,7 @@ local Chrome = require("src.ui.gen2.Chrome")
 local Clock = require("src.core.gen2.Clock")
 local FixedStep = require("src.core.FixedStep")
 local Font = require("src.render.Font")
+local GamepadMap = require("src.core.GamepadMap")
 local Input = require("src.core.Input")
 local Music = require("src.core.Music")
 local Save = require("src.core.gen2.Save")
@@ -57,20 +58,6 @@ Game2.__index = Game2
 
 local function noop() end
 
-for _, name in ipairs({
-  "joystickpressed", "joystickreleased", "joystickaxis", "joystickhat",
-  "joystickadded",
-}) do
-  Game2[name] = noop
-end
-
--- Not a noop, because the overlay has to come back on its own: a player who
--- unplugs the only controller would otherwise have to tap a blind screen to
--- get the pad back (src/core/Game.lua:869 does the same).
-function Game2:joystickremoved()
-  TouchControls:joystickremoved()
-end
-
 -- THE FRAME AND INPUT SEAMS.
 --
 -- Gold composites its own frame (Game2:draw / drawScene) and pumps its own pad
@@ -1660,8 +1647,9 @@ function Game2:drawScene(w, h)
       -- row to opt into the step-down half, so CENTERED is the whole rule
       -- here.
       local s = self.world:fitScale()
+      local ox, oy = Chrome.fitOrigin(w, h, s)
       G.push()
-      G.translate(math.floor((w - 160 * s) / 2), math.floor((h - 144 * s) / 2))
+      G.translate(ox, oy)
       G.scale(s, s)
       self.stack:draw()
       G.pop()
@@ -1702,7 +1690,7 @@ function Game2:hotkey(key)
     self:writeSave()
     return true
   elseif key == "f2" then
-    local loaded = Save.load("gold")
+    local loaded = Save.load()
     if loaded then self:continueGame(loaded) end
     return true
   elseif key == "1" then
@@ -1967,7 +1955,11 @@ function Game2:applyOptions()
   local options = self.options or {}
   Music.applyOptions(options)
   require("src.core.Sound").applyOptions(options)
-  require("src.render.Zoom").applyOptions(options)
+  local Zoom = require("src.render.Zoom")
+  Zoom.applyOptions(options)
+  local caps = require("src.core.Performance").applyOptions(options)
+  Zoom.allowSurvey = caps.survey
+  if not caps.survey and Zoom.offset < 0 then Zoom.offset = 0 end
   require("src.render.Tilt").applyOptions(options)
   require("src.render.GbcPalette").applyOptions(options)
   -- engine/gfx/load_font.asm:29 LoadFrame, off options.lua's wTextboxFrame.
@@ -1982,6 +1974,7 @@ function Game2:applyOptions()
     haptics = options.haptics,
   })
   require("src.core.VideoMode").applyOptions(options)
+  require("src.core.ScreenPosition").applyOptions(options)
   require("src.core.FrameCap").applyOptions(options)
   require("src.world.gen2.BorderFill").applyOptions(options)
   local GBCFX = require("src.render.GBCFX")
@@ -1991,6 +1984,13 @@ function Game2:applyOptions()
   end
 end
 
+function Game2:_cycleSpeed(dir)
+  local GameSpeed = require("src.core.GameSpeed")
+  self.options.speed = GameSpeed.cycle(self.options.speed, dir)
+  if self.save then self.save.options = self.options end
+  self:persistOptions()
+end
+
 -- `back` -- SDL's name for the small left-hand menu button: Xbox VIEW, the PS
 -- CREATE/SHARE beside the touchpad, the Switch MINUS -- is SELECT, and has been
 -- since src/core/GamepadMap.lua's DEFAULT_GAMEPAD_BINDINGS was written
@@ -2001,27 +2001,49 @@ end
 -- the PACK's move-item, the party menu's reorder and half the soft-reset chord
 -- (A+B+SELECT+START) were all unreachable from a pad, and pressing the button
 -- to find out killed the process.  It reaches Input like every other button now.
-function Game2:gamepadpressed(_joystick, button)
+function Game2:gamepadpressed(joystick, button)
   -- a controller is being used: the touch overlay steps aside until the next
   -- screen touch (mobile only; a no-op elsewhere)
   TouchControls:noteGamepad()
-  -- The shoulders cycle GAME SPEED, as they do in the Gen 1 path.
+  local selectHeld = Input:isDown("select")
-  if button == "rightshoulder" or button == "leftshoulder" then
+  if not selectHeld and joystick and joystick.isGamepadDown then
-    local GameSpeed = require("src.core.GameSpeed")
+    local ok, down = pcall(function()
-    local dir = button == "rightshoulder" and 1 or -1
+      return joystick:isGamepadDown("back")
-    self.options.speed = GameSpeed.cycle(self.options.speed, dir)
+    end)
-    if self.save then self.save.options = self.options end
+    selectHeld = ok and down == true
-    self:persistOptions()
+  end
+  -- shoulders and triggers cycle GAME SPEED, as in src/core/Game.lua:881
+  if not selectHeld then
+    if button == "rightshoulder" or button == "righttrigger" then
+      self:_cycleSpeed(1)
+      return
+    elseif button == "leftshoulder" or button == "lefttrigger" then
+      self:_cycleSpeed(-1)
+      return
+    end
+  end
+  local top = self.stack and self.stack:top()
+  if top and top.onGamepadPressed then
+    top:onGamepadPressed(button)
     return
   end
+  if selectHeld then
+    local digit = GamepadMap.displayChordDigit(button)
+    if digit then
+      self:keypressed(digit)
+      return
+    end
+  end
   -- START opens the start menu in the overworld; it used to quit, from before
   -- there was a menu to open.
 
-  Input:gamepadpressed(_joystick, button)
+  Input:gamepadpressed(joystick, button)
 end
 
 function Game2:gamepadreleased(joystick, button)
   Input:gamepadreleased(joystick, button)
+  local top = self.stack and self.stack:top()
+  if top and top.onGamepadReleased then top:onGamepadReleased(button) end
 end
 
 function Game2:gamepadaxis(joystick, axis, value)
@@ -2030,4 +2052,61 @@ function Game2:gamepadaxis(joystick, axis, value)
   Input:gamepadaxis(joystick, axis, value)
 end
 
+-- The raw joystick road, same bodies as src/core/Game.lua:935 (#620, #632, #1570).
+local function isRawStick(joystick)
+  return not (joystick and joystick.isGamepad and joystick:isGamepad())
+end
+
+function Game2:joystickpressed(joystick, button)
+  if GamepadMap.isAccelerometer(joystick) then return end
+  TouchControls:noteGamepad()
+  local top = self.stack and self.stack:top()
+  if isRawStick(joystick) and top and top.onJoystickPressed then
+    top:onJoystickPressed(button)
+    return
+  end
+  Input:joystickpressed(joystick, button)
+end
+
+function Game2:joystickreleased(joystick, button)
+  if GamepadMap.isAccelerometer(joystick) then return end
+  Input:joystickreleased(joystick, button)
+  local top = self.stack and self.stack:top()
+  if isRawStick(joystick) and top and top.onJoystickReleased then
+    top:onJoystickReleased(button)
+  end
+end
+
+function Game2:joystickaxis(joystick, axis, value)
+  if GamepadMap.isAccelerometer(joystick) then return end
+  if math.abs(value) > 0.5 then TouchControls:noteGamepad() end
+  Input:joystickaxis(joystick, axis, value)
+end
+
+function Game2:joystickhat(joystick, hat, direction)
+  if GamepadMap.isAccelerometer(joystick) then return end
+  if direction ~= "c" then TouchControls:noteGamepad() end
+  Input:joystickhat(joystick, hat, direction)
+end
+
+-- src/core/Game.lua:1015 (#799)
+function Game2:recoverInput()
+  Input:reset()
+  Input:reconcile()
+  TouchControls:reset()
+  if self.mods and self.mods.releaseModInput then self.mods:releaseModInput() end
+  self:cancelPointers()
+end
+
+function Game2:joystickadded()
+  self:recoverInput()
+end
+
+-- The overlay comes back on its own when the last pad is unplugged
+-- (src/core/Game.lua:1044).
+function Game2:joystickremoved()
+  self:recoverInput()
+  TouchControls:joystickremoved()
+end
+
 return Game2

src/core/GameVersion.lua

@@ -1,5 +1,5 @@
 -- Which game this process is running: Red (the historical default), Blue,
--- Yellow, or Gold.  One source of truth for everything that differs by
+-- Yellow, Gold, or Silver.  One source of truth for everything that differs by
 -- version -- the accepted ROM hash, the import manifest, where the
 -- extracted cache lives, and the save-file suffix -- so the importer,
 -- cache mount, SaveData, title screen and palette all agree.
@@ -8,7 +8,8 @@
 -- saves are untouched, but its extracted cache lives under red/ like Blue,
 -- Yellow, and Gold (issue #899); a legacy root cache is moved into red/ once
 -- by CacheFs.migrateLegacyRedCache.  All supported versions can be imported
--- and selected side by side.  Gold is Gen 2 (see docs/gold-phase1.md).
+-- and selected side by side.  Gold and Silver are Gen 2 (see
+-- docs/gold-phase1.md).
 --
 -- Zero requires, so it loads during love.conf and under plain Lua for tools
 -- and tests.  The active version is a process-global set once at boot from
@@ -61,13 +62,26 @@ GameVersion.VERSIONS = {
     manifest = "tools/rom_manifest_gold.json",
     cachePrefix = "gold/",    -- gold/data/generated, gold/assets/generated
     saveSuffix = "_gold",     -- save_gold.lua / .bak / .tmp
-    -- The only row that carries one; absent reads as 1 (GameVersion.generation)
+    -- Absent reads as 1 (GameVersion.generation)
+    generation = 2,
+  },
+  -- Gold's engine with edition-selected data; the manifest is derived from
+  -- Gold's by tools/make_silver_manifest.py.
+  silver = {
+    id = "silver",
+    label = "Silver",
+    displayName = "Pokemon Silver",
+    launcherName = "Silver (Beta)",
+    sha1 = "49b163f7e57702bc939d642a18f591de55d92dae",
+    manifest = "tools/rom_manifest_silver.json",
+    cachePrefix = "silver/",  -- silver/data/generated, silver/assets/generated
+    saveSuffix = "_silver",   -- save_silver.lua / .bak / .tmp
     generation = 2,
   },
 }
 
 -- Launcher column order.
-GameVersion.ORDER = { "red", "blue", "yellow", "gold" }
+GameVersion.ORDER = { "red", "blue", "yellow", "gold", "silver" }
 
 GameVersion.current = "red"
 

src/core/GamepadMap.lua

@@ -106,6 +106,17 @@ function GamepadMap.ignoreRawForJoystick(joystick)
   return ok and isPad == true
 end
 
+-- conf.lua turns the mobile accelerometer-joystick off (#468), but guard the
+-- generic joystick path anyway: any sensor-style device that still reaches us
+-- has gravity pinning an axis past the deadzone, which would hide the touch
+-- overlay every instant and steer the player by tilt through the axis-1/2
+-- mapping (#459).  Real controllers arrive as SDL gamepads or named sticks,
+-- never as "* Accelerometer".
+function GamepadMap.isAccelerometer(joystick)
+  local name = joystick and joystick.getName and joystick:getName()
+  return name ~= nil and name:lower():find("accelerometer", 1, true) ~= nil
+end
+
 function GamepadMap.mapRawButton(index)
   if nxActive() then
     local nx = GamepadMap.NX_RAW_BUTTON_BINDINGS[index]

src/core/Input.lua

@@ -281,6 +281,7 @@ end
 
 function Input:joystickpressed(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   noteCapture(self, "joy", "pressed", button)
   local btn = self.joyBindings[button]
   if btn then press(self, btn, "joy:" .. button) end
@@ -288,6 +289,7 @@ end
 
 function Input:joystickreleased(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   noteCapture(self, "joy", "released", button)
   local btn = self.joyBindings[button]
   if btn then release(self, btn, "joy:" .. button) end
@@ -330,6 +332,7 @@ end
 
 function Input:joystickaxis(joystick, axis, value)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   if axis == 1 then
     self:gamepadaxis(joystick, "leftx", value)
   elseif axis == 2 then
@@ -343,6 +346,7 @@ end
 -- directions on top of a direction rebind.
 function Input:joystickhat(joystick, hat, direction)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   local source = "hat:" .. hat
   for _, btn in ipairs(self.hatDirs[hat] or {}) do
     release(self, btn, source)
@@ -380,7 +384,8 @@ function Input:reconcile()
   local ok, joysticks = pcall(js.getJoysticks)
   if not ok or type(joysticks) ~= "table" then return end
   for _, j in ipairs(joysticks) do
-    if GamepadMap.ignoreRawForJoystick(j) then
+    if GamepadMap.isAccelerometer(j) then
+    elseif GamepadMap.ignoreRawForJoystick(j) then
       -- SDL-recognized pad: buttons + left stick, the gamepad surfaces
       if j.isGamepadDown then
         for button, btn in pairs(self.padBindings) do

src/core/IssueReport.lua

@@ -6,6 +6,49 @@ local IssueReport = {}
 local FORM_URL = "https://github.com/bryanthaboi/gen1recomp/issues/new"
 local TEMPLATE = "bug_report.yml"
 
+local APPLE_MODELS = {
+  ["iPhone14,2"] = "iPhone 13 Pro",
+  ["iPhone14,3"] = "iPhone 13 Pro Max",
+  ["iPhone14,4"] = "iPhone 13 mini",
+  ["iPhone14,5"] = "iPhone 13",
+  ["iPhone14,7"] = "iPhone 14",
+  ["iPhone14,8"] = "iPhone 14 Plus",
+  ["iPhone15,2"] = "iPhone 14 Pro",
+  ["iPhone15,3"] = "iPhone 14 Pro Max",
+  ["iPhone15,4"] = "iPhone 15",
+  ["iPhone15,5"] = "iPhone 15 Plus",
+  ["iPhone16,1"] = "iPhone 15 Pro",
+  ["iPhone16,2"] = "iPhone 15 Pro Max",
+  ["iPhone17,1"] = "iPhone 16 Pro",
+  ["iPhone17,2"] = "iPhone 16 Pro Max",
+  ["iPhone17,3"] = "iPhone 16",
+  ["iPhone17,4"] = "iPhone 16 Plus",
+  ["iPhone17,5"] = "iPhone 16e",
+  ["Mac14,2"] = "MacBook Air (13-inch, M2)",
+  ["Mac14,3"] = "Mac mini (M2)",
+  ["Mac14,5"] = "MacBook Pro (14-inch, M2 Max)",
+  ["Mac14,6"] = "MacBook Pro (16-inch, M2 Max)",
+  ["Mac14,7"] = "MacBook Pro (13-inch, M2)",
+  ["Mac14,9"] = "MacBook Pro (14-inch, M2 Pro)",
+  ["Mac14,10"] = "MacBook Pro (16-inch, M2 Pro)",
+  ["Mac14,12"] = "Mac mini (M2 Pro)",
+  ["Mac14,13"] = "Mac Studio (M2 Max)",
+  ["Mac14,14"] = "Mac Studio (M2 Ultra)",
+  ["Mac14,15"] = "MacBook Air (15-inch, M2)",
+  ["Mac15,3"] = "MacBook Pro (14-inch, M3)",
+  ["Mac15,6"] = "MacBook Pro (14-inch, M3 Pro)",
+  ["Mac15,7"] = "MacBook Pro (16-inch, M3 Pro)",
+  ["Mac15,12"] = "MacBook Air (13-inch, M3)",
+  ["Mac15,13"] = "MacBook Air (15-inch, M3)",
+  ["Mac16,1"] = "MacBook Pro (14-inch, M4)",
+  ["Mac16,5"] = "MacBook Pro (16-inch, M4 Max)",
+  ["Mac16,6"] = "MacBook Pro (14-inch, M4 Max)",
+  ["Mac16,7"] = "MacBook Pro (16-inch, M4 Pro)",
+  ["Mac16,8"] = "MacBook Pro (14-inch, M4 Pro)",
+  ["Mac16,10"] = "Mac mini (M4)",
+  ["Mac16,11"] = "Mac mini (M4 Pro)",
+}
+
 local function clean(value)
   if value == nil then return nil end
   local text = tostring(value):gsub("^%s+", ""):gsub("%s+$", "")
@@ -36,6 +79,16 @@ local function commandValue(command)
   return clean(value)
 end
 
+local function commandText(command)
+  if not io or type(io.popen) ~= "function" then return nil end
+  local ok, pipe = pcall(io.popen, command, "r")
+  if not ok or not pipe then return nil end
+  local readOK, value = pcall(pipe.read, pipe, "*a")
+  pcall(pipe.close, pipe)
+  if not readOK then return nil end
+  return clean(value)
+end
+
 local function percentEncode(value)
   local text = tostring(value or "")
   return (text:gsub("([^%w%-_%.~])", function(char)
@@ -66,6 +119,25 @@ local function loveVersion()
   return result
 end
 
+local function friendlyModel(identifier)
+  identifier = clean(identifier)
+  if not identifier then return nil end
+  return APPLE_MODELS[identifier] or identifier
+end
+
+local function macModel()
+  local details = commandText("system_profiler SPHardwareDataType 2>/dev/null")
+  if details then
+    local name = clean(details:match("Model Name:%s*([^\r\n]+)"))
+    local chip = clean(details:match("Chip:%s*([^\r\n]+)"))
+    if name and chip and not name:find(chip, 1, true) then
+      return name .. " (" .. chip .. ")"
+    end
+    if name then return name end
+  end
+  return friendlyModel(commandValue("sysctl -n hw.model 2>/dev/null"))
+end
+
 local function appVersion()
   local version = clean(Version.engine)
   if not version or version == "0.0.0" or version == "0.0.0-dev" then return "" end
@@ -73,20 +145,25 @@ local function appVersion()
 end
 
 local function deviceModel(rawOS, system)
-  local model = clean(call(system.getModel))
+  local nativeModel = clean(call(system.getDeviceModel))
-  if model then return model end
+  if nativeModel then return friendlyModel(nativeModel) end
   if rawOS == "OS X" or rawOS == "macOS" then
-    return commandValue("sysctl -n hw.model 2>/dev/null")
+    return macModel()
+  end
+  local model = clean(call(system.getModel))
+  if model and not model:lower():find("gpu", 1, true)
+      and not model:lower():find("renderer", 1, true) then
+    return friendlyModel(model)
   end
   if rawOS == "Windows" then
-    return commandValue("powershell.exe -NoProfile -NonInteractive -Command \"(Get-CimInstance Win32_ComputerSystem).Model\" 2>NUL")
+    return friendlyModel(commandValue("powershell.exe -NoProfile -NonInteractive -Command \"(Get-CimInstance Win32_ComputerSystem).Model\" 2>NUL"))
   end
   if rawOS == "Linux" then
-    return commandValue("cat /sys/devices/virtual/dmi/id/product_name 2>/dev/null")
+    return friendlyModel(commandValue("cat /sys/devices/virtual/dmi/id/product_name 2>/dev/null")
-      or commandValue("cat /sys/devices/virtual/dmi/id/model 2>/dev/null")
+      or commandValue("cat /sys/devices/virtual/dmi/id/model 2>/dev/null"))
   end
   if rawOS == "Android" then
-    return commandValue("getprop ro.product.model 2>/dev/null")
+    return friendlyModel(commandValue("getprop ro.product.model 2>/dev/null"))
   end
   return nil
 end
@@ -121,7 +198,7 @@ local function metadata(options, context)
   local window = love and love.window or {}
   local rawOS = clean(call(system.getOS))
   local model = deviceModel(rawOS, system)
-  local renderer, rendererVersion, _, rendererDevice = call(graphics.getRendererInfo)
+  local renderer, rendererVersion = call(graphics.getRendererInfo)
   local width, height = call(graphics.getDimensions)
   local pixelWidth, pixelHeight = call(graphics.getPixelDimensions)
   local modeWidth, modeHeight, flags = call(window.getMode)
@@ -134,11 +211,7 @@ local function metadata(options, context)
     if value then lines[#lines + 1] = "- " .. label .. ": " .. value end
   end
   add("Platform", formOS(rawOS))
-  local hardware = model
+  add("Device", model)
-  if rendererDevice and rendererDevice ~= model then
-    hardware = hardware and (hardware .. " (" .. rendererDevice .. ")") or rendererDevice
-  end
-  add("Device", hardware)
   local rendererDetails = clean(renderer)
   if rendererDetails and clean(rendererVersion) then
     rendererDetails = rendererDetails .. " " .. clean(rendererVersion)

src/core/LaunchOptions.lua

@@ -39,6 +39,7 @@ local function normalizeVersion(v)
     b = "blue", blue = "blue",
     y = "yellow", yellow = "yellow",
     g = "gold", gold = "gold",
+    s = "silver", silver = "silver",
   }
   v = alias[v] or v
   if GameVersion.VERSIONS and not GameVersion.VERSIONS[v] then return nil end

src/core/Music.lua

@@ -230,7 +230,7 @@ end
 
 function Music.play(data, song, loop, ctx)
   if not song then return end
-  if not love.audio then return end -- headless test stub
+  if not (love and love.audio) then return end -- headless test stub
   ctx = ctx or {}
   song = selectSong(song, ctx)
 

src/core/Orientation.lua

@@ -1,4 +1,4 @@
--- Screen orientation lock, Android only (#592, #716).
+-- Screen orientation lock, Android and iOS (#592, #716, #1638).
 --
 -- Persisted as options.orientation: "auto" | "portrait" | "landscape" |
 -- "reverseLandscape".  The lock travels through SDL_HINT_ORIENTATIONS:
@@ -10,16 +10,12 @@
 -- rotation lock"; LANDSCAPE allows both landscapes (SENSOR_LANDSCAPE ->
 -- USER_LANDSCAPE); REVERSE LANDSCAPE is SDL's LandscapeRight alone.
 --
--- SDL only re-reads the hint when the window is created or its resizable
+-- Android only re-reads the hint at window creation or on a resizable-flag
--- flag changes (SDL_androidwindow.c: Android_CreateWindow /
+-- change (SDL_androidwindow.c), and SDL_SetWindowResizable early-returns on
--- Android_SetWindowResizable both call Android_JNI_SetOrientation).  LOVE
+-- a fullscreen window (SDL_video.c:2237) -- which LOVE's Android window
--- 11.5 exposes neither hints nor a resizable setter, so apply() goes through
+-- always is -- so the hint never reached a running activity (#1638).
--- the FFI to SDL's C API: set the hint, then pulse the window's resizable
+-- apply() sets the hint for a later window, then goes over JNI for the live
--- flag off and back on -- each edge makes the Android backend recompute the
+-- one.  iOS needs only the hint.  Desktop and headless stubs no-op.
--- requested orientation, so a change from the launcher or the OPTION menu
--- takes hold immediately, and the flag ends where it started (conf.lua sets
--- resizable on mobile).  Everything is pcall-guarded: desktop, iOS (the
--- Info.plist governs there) and headless stubs make this a no-op.
 
 local Orientation = {}
 
@@ -58,6 +54,11 @@ function Orientation.isAndroid()
   return love.system.getOS() == "Android"
 end
 
+function Orientation.isIOS()
+  if not love or not love.system or not love.system.getOS then return false end
+  return love.system.getOS() == "iOS"
+end
+
 function Orientation.cycle(mode, dir)
   local cur, idx = Orientation.normalize(mode), 1
   for i, m in ipairs(Orientation.MODES) do
@@ -67,6 +68,15 @@ function Orientation.cycle(mode, dir)
   return Orientation.MODES[(idx - 1 + (dir or 1)) % n + 1]
 end
 
+-- ActivityInfo constants, what setOrientationBis lands on per hint after
+-- GameActivity's *_SENSOR -> *_USER remap (#716).
+local REQUESTED = {
+  auto = 13,
+  portrait = 1,
+  landscape = 11,
+  reverseLandscape = 8,
+}
+
 -- The SDL2 C API this module needs.  cdef errors on redefinition, so run it
 -- once and remember whether it took; ffi itself may be absent (plain Lua
 -- test interpreters), hence the pcall'd require.
@@ -77,33 +87,79 @@ local function sdlFfi()
   if cdefOk == nil then
     cdefOk = pcall(ffi.cdef, [[
       typedef struct SDL_Window SDL_Window;
+      typedef union { int32_t i; int64_t pad; } love_jvalue;
       int SDL_SetHint(const char *name, const char *value);
       SDL_Window *SDL_GL_GetCurrentWindow(void);
       void SDL_SetWindowResizable(SDL_Window *window, int resizable);
+      void *SDL_AndroidGetJNIEnv(void);
+      void *SDL_AndroidGetActivity(void);
     ]])
   end
   if not cdefOk then return nil end
   return ffi
 end
 
--- Push the mode into the live activity.  Returns true when the hint reached
+-- Slot numbers in JNINativeInterface (jni.h).
--- SDL (the symbols resolved), false on any non-Android / stubbed platform.
+local JNI_EXCEPTION_CLEAR = 17
+local JNI_DELETE_LOCAL_REF = 23
+local JNI_GET_OBJECT_CLASS = 31
+local JNI_GET_METHOD_ID = 33
+local JNI_CALL_VOID_METHOD_A = 63
+
+-- What Android_JNI_SetOrientation reaches, called directly: the hint path
+-- cannot re-run on a live fullscreen window (SDL_video.c:2237).
+local function setRequestedOrientation(ffi, requested)
+  local env = ffi.C.SDL_AndroidGetJNIEnv()
+  if env == nil then return false end
+  local activity = ffi.C.SDL_AndroidGetActivity()
+  if activity == nil then return false end
+  local fns = ffi.cast("void***", env)[0]
+  local getObjectClass = ffi.cast("void *(*)(void *, void *)", fns[JNI_GET_OBJECT_CLASS])
+  local getMethodID = ffi.cast(
+    "void *(*)(void *, void *, const char *, const char *)", fns[JNI_GET_METHOD_ID])
+  local callVoidMethodA = ffi.cast(
+    "void (*)(void *, void *, void *, love_jvalue *)", fns[JNI_CALL_VOID_METHOD_A])
+  local deleteLocalRef = ffi.cast("void (*)(void *, void *)", fns[JNI_DELETE_LOCAL_REF])
+  local exceptionClear = ffi.cast("void (*)(void *)", fns[JNI_EXCEPTION_CLEAR])
+
+  local ok = false
+  local cls = getObjectClass(env, activity)
+  if cls ~= nil then
+    local mid = getMethodID(env, cls, "setRequestedOrientation", "(I)V")
+    if mid ~= nil then
+      local args = ffi.new("love_jvalue[1]")
+      args[0].pad = 0
+      args[0].i = requested
+      callVoidMethodA(env, activity, mid, args)
+      ok = true
+    end
+    exceptionClear(env)
+    deleteLocalRef(env, cls)
+  end
+  deleteLocalRef(env, activity)
+  return ok
+end
+
+-- Returns true only when the request actually landed, never unconditionally
+-- as it once did (#1638).
 function Orientation.apply(mode)
-  if not Orientation.isAndroid() then return false end
+  local android = Orientation.isAndroid()
+  if not (android or Orientation.isIOS()) then return false end
   local ffi = sdlFfi()
   if not ffi then return false end
   mode = Orientation.normalize(mode)
-  local ok = pcall(function()
+  local ok, reached = pcall(function()
-    -- "SDL_IOS_ORIENTATIONS" is SDL_HINT_ORIENTATIONS's name (SDL_hints.h);
+    -- SDL_HINT_ORIENTATIONS is "SDL_IOS_ORIENTATIONS" in the SDL2 Android
-    -- despite the IOS in the string, the Android backend reads it too.
+    -- ships and "SDL_ORIENTATIONS" in the SDL3 the iOS app links; each
+    -- engine ignores the other's key.
     ffi.C.SDL_SetHint("SDL_IOS_ORIENTATIONS", HINTS[mode])
-    local win = ffi.C.SDL_GL_GetCurrentWindow()
+    ffi.C.SDL_SetHint("SDL_ORIENTATIONS", HINTS[mode])
-    if win ~= nil then
+    -- On iOS the hint is the lock: UIKit re-asks on every rotation
-      ffi.C.SDL_SetWindowResizable(win, 0)
+    -- (SDL_uikitviewcontroller.m supportedInterfaceOrientations).
-      ffi.C.SDL_SetWindowResizable(win, 1)
+    if not android then return true end
-    end
+    return setRequestedOrientation(ffi, REQUESTED[mode])
   end)
-  return ok
+  return ok and reached == true
 end
 
 function Orientation.applyOptions(opts)

src/core/PdfImage.lua

@@ -0,0 +1,115 @@
+-- Recover a raster from a PDF that is really a wrapped JPEG.  Delta skins
+-- ship artwork that way so iOS can scale it; LOVE has no PDF renderer, so
+-- import pulls the embedded image out instead of refusing the skin.  True
+-- vector PDFs (no Image XObject, no JPEG) still fail.
+
+local PdfImage = {}
+
+local function isPdf(bytes)
+  return type(bytes) == "string" and bytes:sub(1, 5) == "%PDF-"
+end
+
+-- After the `stream` keyword the spec allows \n or \r\n before the bytes.
+-- `endstream` also contains the letters "stream", so skip that match.
+local function streamDataStart(bytes, from)
+  local s, e = bytes:find("stream", from, true)
+  while s do
+    if s == 1 or bytes:sub(s - 3, s - 1) ~= "end" then
+      local p = e + 1
+      if bytes:sub(p, p) == "\r" then p = p + 1 end
+      if bytes:sub(p, p) == "\n" then p = p + 1 end
+      return p, s
+    end
+    s, e = bytes:find("stream", e + 1, true)
+  end
+  return nil
+end
+
+local function dictWindow(bytes, imageAt)
+  local from = imageAt > 400 and (imageAt - 400) or 1
+  local to = math.min(#bytes, imageAt + 800)
+  return bytes:sub(from, to)
+end
+
+local function dictNumber(window, key)
+  -- Prefer an indirect ref so `/Length 5 0 R` is not read as length 5.
+  if window:find("/" .. key .. "%s+%d+%s+%d+%s+R") then return nil end
+  return tonumber(window:match("/" .. key .. "%s+(%d+)"))
+end
+
+local function dictFilter(window)
+  local named = window:match("/Filter%s*/(%w+)")
+  if named then return named end
+  return window:match("/Filter%s*%[%s*/(%w+)")
+end
+
+local function jpegIn(bytes, from, to)
+  if from < 1 then from = 1 end
+  if not to or to > #bytes then to = #bytes end
+  if to < from then return nil end
+  local region = bytes:sub(from, to)
+  local soi = region:find("\255\216\255", 1, true)
+  if not soi then return nil end
+  local eoi = region:find("\255\217", soi + 3, true)
+  if not eoi then return nil end
+  return region:sub(soi, eoi + 1)
+end
+
+local function candidate(data, width, height, ext)
+  if not data or data == "" then return nil end
+  return {
+    data = data,
+    ext = ext or "jpg",
+    width = width or 0,
+    height = height or 0,
+  }
+end
+
+local function bigger(a, b)
+  if not a then return b end
+  if not b then return a end
+  local as = (a.width or 0) * (a.height or 0)
+  local bs = (b.width or 0) * (b.height or 0)
+  if bs ~= as then return bs > as and b or a end
+  return #b.data > #a.data and b or a
+end
+
+-- Walk Image XObjects and take the largest DCTDecode (JPEG) stream.
+local function fromImageXObjects(bytes)
+  local best
+  local i = 1
+  while true do
+    local s, e = bytes:find("/Subtype%s*/Image", i)
+    if not s then break end
+    local window = dictWindow(bytes, s)
+    local filter = dictFilter(window)
+    local width = dictNumber(window, "Width")
+    local height = dictNumber(window, "Height")
+    local dataStart = streamDataStart(bytes, e)
+    i = e + 1
+    if dataStart and filter == "DCTDecode" then
+      local es = bytes:find("endstream", dataStart, true)
+      local jpeg = jpegIn(bytes, dataStart, es and (es - 1) or nil)
+      best = bigger(best, candidate(jpeg, width, height, "jpg"))
+    end
+  end
+  return best
+end
+
+-- Image-to-PDF converters (3-Heights, Preview, etc.) leave a single JPEG
+-- body even when /Length is an indirect object we do not resolve.
+local function fromBareJpeg(bytes)
+  local jpeg = jpegIn(bytes, 1, #bytes)
+  if not jpeg then return nil end
+  return candidate(jpeg, 0, 0, "jpg")
+end
+
+function PdfImage.extract(bytes)
+  if not isPdf(bytes) then return nil, "not a pdf" end
+  local best = fromImageXObjects(bytes)
+  if not best then best = fromBareJpeg(bytes) end
+  if not best then return nil, "no extractable image" end
+  return best
+end
+
+return PdfImage

src/core/Performance.lua

@@ -86,8 +86,11 @@ function Performance.detect()
   local cores = processorCount()
 
   -- PortMaster-style ARM Linux handhelds (e.g. the RG34XXSP the project
-  -- already ships a build for): the weakest target here.
+  -- already ships a build for): the weakest target here.  Desktop ARM
-  if isArm and os ~= "Android" and os ~= "iOS" then
+  -- (Apple Silicon "OS X", Windows-on-ARM) is not a handheld — those
+  -- used to resolve AUTO → LOW, which stripped survey zoom-out from
+  -- OPTIONS so the ZOOM row only offered IN.
+  if isArm and os == "Linux" then
     return "low"
   end
   -- Phones and tablets: GBC FX is already force-disabled here (issue #136);

src/core/SaveData.lua

@@ -285,6 +285,7 @@ function SaveData.defaultOptions()
     -- lock the window to an exact 160x144 multiple, 1..4 (0 = OFF); see
     -- src/core/FaithfulRes.lua.  Ignored on mobile.
     faithfulRes = 0,
+    screenPos = "center",
     -- hard render frame-rate cap; render-only pacing (issue #88, FrameCap.lua)
     fpsCap = 60,
     -- graphics performance tier: auto | high | balanced | low.  "auto"
@@ -1279,13 +1280,26 @@ function SaveData.ensurePlaythroughId(save, injectedFs)
   local isFresh = save == freshPlaythrough
   if isFresh then freshPlaythrough = nil end
   local byVersion = opts.playthroughIds and opts.playthroughIds[version]
-  id = not isFresh and byVersion and byVersion[scope] or nil
+  local existing = byVersion and byVersion[scope]
+  id = not isFresh and existing or nil
   if type(id) ~= "string" or id == "" then
     id = SaveData.newPlaythroughId()
-    opts.playthroughIds = opts.playthroughIds or {}
+    -- A fresh skeleton still gets its own id (two unsaved New Games sharing a
-    opts.playthroughIds[version] = opts.playthroughIds[version] or {}
+    -- slot must stay distinct), and it is still persisted when the slot has no
-    opts.playthroughIds[version][scope] = id
+    -- binding yet -- that is the contract a tool relies on to resolve
-    SaveData.saveOptions(opts, injectedFs)
+    -- `selected` at the title after a restart, before any normal SAVE.
+    --
+    -- What it must NOT do is OVERWRITE a binding that already exists. newGame()
+    -- marks a skeleton on the boot frame, before any save is loaded, and mods
+    -- initialise inside that window -- so a mod touching storage at init
+    -- replaced the real save's id with a throwaway, stranding that save's mod
+    -- storage and repeating on every launch.
+    if not (isFresh and type(existing) == "string" and existing ~= "") then
+      opts.playthroughIds = opts.playthroughIds or {}
+      opts.playthroughIds[version] = opts.playthroughIds[version] or {}
+      opts.playthroughIds[version][scope] = id
+      SaveData.saveOptions(opts, injectedFs)
+    end
   end
   save.meta.playthroughId = id
   return id

src/core/ScreenPosition.lua

@@ -0,0 +1,71 @@
+local ScreenPosition = {}
+
+ScreenPosition.MODES = { "center", "upper", "top" }
+ScreenPosition.DEFAULT = "center"
+ScreenPosition.mode = ScreenPosition.DEFAULT
+
+local LABELS = { center = "CENTER", upper = "UPPER", top = "TOP" }
+
+function ScreenPosition.normalize(v)
+  if LABELS[v] then return v end
+  return ScreenPosition.DEFAULT
+end
+
+function ScreenPosition.label(v)
+  if ScreenPosition.skinActive() then return "SKIN" end
+  return LABELS[ScreenPosition.normalize(v)]
+end
+
+function ScreenPosition.cycle(v, dir)
+  if ScreenPosition.skinActive() then return ScreenPosition.normalize(v) end
+  v = ScreenPosition.normalize(v)
+  local modes = ScreenPosition.MODES
+  local cur = 1
+  for i, mode in ipairs(modes) do
+    if mode == v then cur = i break end
+  end
+  return modes[(cur - 1 + (dir or 1)) % #modes + 1]
+end
+
+function ScreenPosition.setMode(v)
+  ScreenPosition.mode = ScreenPosition.normalize(v)
+end
+
+function ScreenPosition.applyOptions(opts)
+  ScreenPosition.setMode(opts and opts.screenPos)
+end
+
+function ScreenPosition.safeTop()
+  local ok, SafeArea = pcall(require, "src.core.SafeArea")
+  if not ok then return 0 end
+  local okr, _, y = pcall(SafeArea.rect)
+  if not okr then return 0 end
+  return math.max(0, tonumber(y) or 0)
+end
+
+function ScreenPosition.skinActive(w, h)
+  local ok, TouchSkin = pcall(require, "src.core.TouchSkin")
+  if not ok or type(TouchSkin.viewport) ~= "function" then return false end
+  if (not w or not h) and love and love.graphics and love.graphics.getDimensions then
+    w, h = love.graphics.getDimensions()
+  end
+  local okv, x = pcall(TouchSkin.viewport, w, h)
+  return okv and x ~= nil
+end
+
+function ScreenPosition.lift(viewH, contentH, safeTop)
+  if ScreenPosition.mode == "center" then return 0 end
+  viewH = tonumber(viewH) or 0
+  contentH = tonumber(contentH) or 0
+  local slack = viewH - contentH
+  if slack <= 0 then return 0 end
+  local centered = math.floor(slack / 2)
+  local target = ScreenPosition.mode == "top" and 0 or math.floor(slack / 4)
+  safeTop = math.floor(tonumber(safeTop) or 0)
+  if safeTop > 0 and target < safeTop then
+    target = math.min(safeTop, centered)
+  end
+  return centered - target
+end
+
+return ScreenPosition

src/core/Sound.lua

@@ -154,8 +154,14 @@ local function newSfxSource(data, key, def, pitch, tempo, plain)
   return newFileSource(def)
 end
 
+local function deviceSuspended()
+  local ChipAudio = package.loaded["src.core.ChipAudio"]
+  return ChipAudio ~= nil and ChipAudio.isSuspended()
+end
+
 local function playPath(data, key, def, pitch, tempo, plain)
   if not love.audio or not def then return nil end
+  if deviceSuspended() then return nil end
   local src = cache[key]
   if src == false then return nil end -- known bad, already logged
   if not src then
@@ -602,6 +608,7 @@ end
 -- cache carries no clips (Red/Blue) or headless.
 function Sound.playPikaCry(data, n)
   if not love.audio then return nil end
+  if deviceSuspended() then return nil end
   local count = data.audio and data.audio.pikaCries
   if not count then return nil end
   n = math.max(1, math.min(count, n or 1))
@@ -633,6 +640,7 @@ end
 -- like the original's PlayCry -> WaitForSoundToFinish can poll it
 function Sound.playCry(data, species, pikaClip)
   if not love.audio then return nil end
+  if deviceSuspended() then return nil end
   -- Yellow voices every Pikachu cry with the PCM clips (the chip cry is
   -- never used for the species there).  Which clip is a property of the
   -- call site in the original -- every caller of PlayPikachuSoundClip sets

src/core/TouchControls.lua

@@ -218,7 +218,7 @@ function TouchControls.defaultLayout(ww, wh, ox, oy, scale)
   local ssW = dpadW * 0.30
   local margin = dpadW * 0.12
   local ok, GameVersion = pcall(require, "src.core.GameVersion")
-  if ok and GameVersion.isGold and GameVersion.isGold() then
+  if ok and GameVersion.generation and GameVersion.generation() == 2 then
     margin = math.max(margin, math.min(ww * 0.10, 72))
   end
   return {
@@ -293,7 +293,9 @@ function TouchControls:applyOptions(opts)
   -- launcher editor round-trips through config() (#806)
   self.haptics = TouchControls.normalizeHaptics(opts and opts.haptics)
   TouchSkin.setOverlayLive(self.active)
-  self:selectSkin(cfg.skin)
+  -- Off means off everywhere: do not leave a hidden selected skin behind to
+  -- influence renderer placement on desktop or with a controller attached.
+  self:selectSkin(cfg.enabled and cfg.skin or nil)
   self.layouts = cfg.layouts
   self.layoutW, self.layoutH = nil, nil
   self.layoutOx, self.layoutOy = nil, nil
@@ -335,7 +337,10 @@ function TouchControls:visible()
   local art = TouchSkin.active ~= nil or self.img ~= nil
   if self.preview then return art end
   if self.enabled == false or not art then return false end
-  if TouchSkin.active and TouchSkin.decorativeOnly() then return true end
+  -- A selected skin is also a desktop/TV bezel.  Input remains gated in
+  -- touchpressed, but the artwork must not disappear when a controller is
+  -- connected or the platform is not touch-first.
+  if TouchSkin.active then return true end
   return self.active and not self.controllerHidden
 end
 
@@ -778,12 +783,19 @@ local function drawIcon(img, zone, pressed, alphaMul)
                      zone.cy - img:getHeight() * scale / 2, 0, scale, scale)
 end
 
-local function drawStretched(img, x, y, w, h, alpha)
+local function drawCovered(img, x, y, w, h, alpha)
   if not img or alpha <= 0 then return end
   local iw, ih = img:getWidth(), img:getHeight()
   if iw <= 0 or ih <= 0 then return end
+  -- Cover the assigned box with one uniform scale and crop the excess.  The
+  -- old independent X/Y scale made portrait art visibly squash on wide
+  -- displays (and vice versa).
+  local s = math.max(w / iw, h / ih)
+  local dw, dh = iw * s, ih * s
   love.graphics.setColor(1, 1, 1, math.min(1, alpha))
-  love.graphics.draw(img, x, y, 0, w / iw, h / ih)
+  love.graphics.setScissor(x, y, w, h)
+  love.graphics.draw(img, x + (w - dw) * 0.5, y + (h - dh) * 0.5, 0, s, s)
+  love.graphics.setScissor()
 end
 
 function TouchControls:drawSkin(alphaMul)
@@ -795,7 +807,7 @@ function TouchControls:drawSkin(alphaMul)
 
   love.graphics.push("all")
   love.graphics.origin()
-  drawStretched(page.image, bx, by, bw, bh, opacity)
+  drawCovered(page.image, bx, by, bw, bh, opacity)
 
   local pressed = {}
   for _, touch in pairs(self.touches or {}) do
@@ -810,7 +822,7 @@ function TouchControls:drawSkin(alphaMul)
         TouchSkin.controlGeometry(page, ctl, ww, wh, sox, soy)
       local alpha = opacity
       if down and not ctl.pressedImage then alpha = opacity * ctl.alphaMod end
-      drawStretched(img, cx - halfW, cy - halfH, halfW * 2, halfH * 2, alpha)
+      drawCovered(img, cx - halfW, cy - halfH, halfW * 2, halfH * 2, alpha)
     end
   end