Merge pull request #1726 from bryanthaboi/dev

- Introduced `teardownMountedSession` to handle cleanup of mounted versions, generated data, and mod states during transitions between the editor and launcher.
- Added `flushEditorPackageLoaded` to evict save-editor modules from `package.loaded` dynamically, ensuring a clean state for subsequent sessions.
- Implemented `Game:reset` and `Game2:reset` methods to clear session-specific fields, allowing for a fresh start when returning to the launcher.
- Enhanced `Renderer` and `TileRenderer` to release GPU resources immediately, preventing memory leaks during rapid transitions.
- Updated `MagnetTrainRide` to support OAM priority overlays and manage background rendering with new shader functionality.

This commit improves the stability and performance of the application during in-process transitions, particularly on Android.

fixes Yellow color palette for title screen

fixes #1662 #1643 #1536 and finishes fixing #1597

.github/workflows/ci.yml

@@ -468,3 +468,24 @@ jobs:
           if [ "$found" = "0" ]; then
             echo "no committed mods to lint"
           fi
+
+  luacheck:
+    name: engine lint (luacheck)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: install luacheck
+        run: |
+          set -e
+          sudo apt-get update
+          sudo apt-get install -y lua5.4 liblua5.4-dev luarocks
+          sudo luarocks install luacheck || sudo apt-get install -y lua-check
+          luacheck --version
+
+      - name: luacheck gate (undefined globals, unreachable code)
+        run: ./scripts/lint.sh --gate
+
+      - name: luacheck full report (advisory)
+        continue-on-error: true
+        run: ./scripts/lint.sh

.luacheckrc

@@ -23,6 +23,10 @@ read_globals = {
   -- LuaJIT 2.1 ships table.unpack even though the bare 5.1 `table` std lacks
   -- it; without this, every `table.unpack` reads as an undefined field.
   table = { fields = { "unpack" } },
+  "POKEPORT_DISPLAY_COMPANION",
+  "POKEPORT_EDITOR_MODE",
+  "rawlen",
+  package = { fields = { "searchers" } },
 }
 
 -- Vendored/native trees and the test suites have their own conventions.
@@ -30,6 +34,7 @@ exclude_files = {
   "mobile/",
   "tests/",
   "tools/save-editor/",
+  "tools/save_convert/vendor/",
 }
 
 ignore = {

CONTRIBUTING-mods.md

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

data/scripts/safari.lua

@@ -111,7 +111,7 @@ local function joinPrompt(game, ow, done)
   local t = game.data.text
   local back = function(text)
     game.stack:push(TextBox.new(game, text, function()
-      ow:scriptMove(ow.player, "down", 1, done)
+      ow:scriptMove(ow.player, "down", 1, done, { collide = true })
     end))
   end
   game.stack:push(TextBox.new(game,

data/scripts/story.lua

@@ -127,7 +127,7 @@ M.VIRIDIAN_CITY = {
     game.stack:push(TextBox.new(game,
       game.data.text._ViridianCityOldManSleepyPrivatePropertyText
       or "You can't go\nthrough here!\fThis is private\nproperty!",
-      function() ow:scriptMove(ow.player, "down", 1) end))
+      function() ow:scriptMove(ow.player, "down", 1, nil, { collide = true }) end))
     return true
   end,
 }
@@ -356,7 +356,7 @@ M.VERMILION_CITY = {
     if shipLeft then
       game.stack:push(TextBox.new(game,
         t._VermilionCitySailor1ShipSetSailText or "The ship set sail.",
-        function() ow:scriptMove(ow.player, "up", 1) end))
+        function() ow:scriptMove(ow.player, "up", 1, nil, { collide = true }) end))
       return true
     end
     -- Walk-past is never facing-right / inFrontOfOrBehindGuardCoords, so
@@ -377,7 +377,7 @@ M.VERMILION_CITY = {
       ask .. "\f"
       .. (t._VermilionCitySailor1YouNeedATicketText
           or "You need a ticket\nto get aboard."),
-      function() ow:scriptMove(ow.player, "up", 1) end))
+      function() ow:scriptMove(ow.player, "up", 1, nil, { collide = true }) end))
     return true
   end,
   talk = {

data/scripts/story2.lua

@@ -414,7 +414,7 @@ local function saffronGate(guardText, triggers, horizontal)
       game.stack:push(TextBox.new(game,
         t._SaffronGateGuardGeeImThirstyText or "Gee, I'm thirsty\nthough!\nThe road's closed.",
         function()
-          ow:scriptMove(ow.player, back, 1)
+          ow:scriptMove(ow.player, back, 1, nil, { collide = true })
         end))
       return true
     end,
@@ -769,7 +769,7 @@ M.MUSEUM_1F = {
     if y == 4 and (x == 9 or x == 10)
        and not game.save.flags.EVENT_BOUGHT_MUSEUM_TICKET then
       museumClerk(game, ow, nil, function()
-        ow:scriptMove(ow.player, "down", 1)
+        ow:scriptMove(ow.player, "down", 1, nil, { collide = true })
       end)
       return true
     end

data/scripts/story3.lua

@@ -176,7 +176,7 @@ M.POKEMON_TOWER_6F = {
           -- .did_not_defeat: one simulated step right, off the trigger,
           -- so fleeing does not leave you standing on a cell that
           -- immediately re-fires.
-          ow:scriptMove(ow.player, "right", 1)
+          ow:scriptMove(ow.player, "right", 1, nil, { collide = true })
         end
         ow:afterBattle(result, battle)
       end

data/scripts/story4.lua

@@ -734,7 +734,7 @@ local function e4ExitSeal(flag, closedBlock, openBlock, dontRunText, autoFlag)
       local TextBox = require("src.render.TextBox")
       game.stack:push(TextBox.new(game,
         game.data.text[dontRunText] or "Don't run away!", function()
-        ow:scriptMove(ow.player, "up", 1)
+        ow:scriptMove(ow.player, "up", 1, nil, { collide = true })
       end))
       return true
     end,

data/scripts/story5.lua

@@ -240,7 +240,7 @@ local function stepGate(opts)
     push(game, text(game)[opts.text] or opts.fallback, function()
       ow.player.facing = opts.push
       if not ow:checkLedgeHop(opts.push) then
-        ow:scriptMove(ow.player, opts.push, 1)
+        ow:scriptMove(ow.player, opts.push, 1, nil, { collide = true })
       end
     end)
     return true
@@ -820,7 +820,8 @@ M.PEWTER_POKECENTER = {
 -- on the west-side cells and walks you back
 local function bikeGateGuard(coords, stopText, explainText)
   return function(game, ow, x, y)
-    if game.save.inventory.BICYCLE then return false end
+    local bike = game.save.inventory.BICYCLE
+    if bike and bike ~= 0 then return false end
     if not inCoords(coords, x, y) then return false end
     -- walk the player up to the tile beside the counter, no further:
     -- (matchedY - closestY) tiles, 0 when already next to it
@@ -842,10 +843,10 @@ local function bikeGateGuard(coords, stopText, explainText)
         -- (PlayerMovingRightScript). Without it the player was left
         -- parked beside the guard's counter with no way past. #518
         local function shoveRight()
-          ow:scriptMove(ow.player, "right", 1)
+          ow:scriptMove(ow.player, "right", 1, nil, { collide = true })
         end
         if dist > 0 then
-          ow:scriptMove(ow.player, "up", dist, shoveRight)
+          ow:scriptMove(ow.player, "up", dist, shoveRight, { collide = true })
         else
           shoveRight()
         end

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
@@ -539,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`,
@@ -549,6 +550,17 @@ gains a field instead of the name gaining a prefix.
   screen has no `.data` field, so the Gen 2 site **adds** `ctx.data` beside the
   Gen 1 keys. A mod that calls `nextFn` is unaffected; one that reaches through
   `ctx.battle.data` instead gets nil on Gold.
+  `battle.exp_award`'s `ctx.applyShare(mon, split, announce)` reads its third
+  argument on both generations: truthy prints the mon's GainedText, falsy pays
+  it silently, so one mod source can print a single summary line for a
+  party-wide award instead of a box per recipient. Gold honours it **only when
+  it is passed**, by argument count -- `applyShare(mon, split)` was written
+  against a seam that always announced on Gold and keeps announcing there,
+  while `applyShare(mon, split, nil)` is silent on both. Pass the argument
+  explicitly and the two generations agree; omit it and Gen 1 stays silent
+  where Gold speaks. Only the line is affected: the exp, the stat exp,
+  `battle.exp_gained`, the level-up line, learned moves and the forget prompt
+  happen either way.
 - *The catch and the evolution:* `pokemon.caught`, `pokemon.evolved`; hook
   `evolution.check`. `src/ui/gen2/BattleState.lua:pushCaught` emits
   `pokemon.caught` once the mon is in the party or the box, and

docs/modding.md

@@ -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/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/rfcs/0012-gen2-exp-award-announce.md

@@ -0,0 +1,140 @@
+# RFC 0012: `applyShare`'s announce argument on Gen 2
+
+## Status
+
+Proposed.
+
+## Motivation
+
+`battle.exp_award` hands a mod `ctx.applyShare(mon, split, announce)` on both
+generations. On Gen 1 the third argument decides whether the mon's GainedText
+box is printed (`src/battle/BattleState.lua`, `if announce then`), which is how
+a mod that pays the whole party prints **one** summary line instead of a box
+per recipient.
+
+Gold accepts the argument and ignores it, as its own comment above the hook
+call says. So the same mod source, running the same code, prints one line on
+Red and six on Gold — one for the participant plus one for every bench mon it
+paid.
+
+This is not hypothetical. The [Exp Share](https://github.com/ShaneMcGovernIE/exp_share)
+mod declares `"games": ["gen1", "gen2"]` and its description promises "a single
+shared-exp line instead of one message per Pokemon". It passes `true` for the
+fighters and `nil` for the bench, exactly as the Gen 1 seam asks. On Gold every
+one of those `nil` calls announces anyway, so a five-mon party turns every KO
+into six boxes to click through.
+
+There is no mod-side fix. The announcement is emitted inside
+`Battle:giveExperiencePass`, behind no hook, and a mod cannot ask for silence
+because the argument that means "quietly" is discarded. The only workaround is
+to intercept the battle's event queue afterwards and delete the boxes, which is
+what a mod written for this had to do — a mod reaching into engine internals to
+undo something the public seam should never have done.
+
+## Decision and plan extended
+
+This does not add a seam. It finishes one: `battle.exp_award` is documented as
+"the same hook `BattleState:awardExp` calls on Gen 1 and with the same ctx",
+and `docs/mod-api-gen2-compat.md` lists it among the hooks shared with Gen 1.
+The third `applyShare` argument is the one part of that ctx whose meaning did
+not survive the crossing, so the promise the catalog already makes is what this
+change delivers.
+
+The delta follows Route B's additive, guarded convention in
+`CONTRIBUTING-mods.md`: nothing is renamed, nothing is removed, and no mod that
+exists today changes behaviour.
+
+## Exact API delta
+
+`ctx.applyShare(mon, split, announce)` on Gen 2 now reads `announce`:
+
+| Call | Gen 1 | Gen 2 before | Gen 2 after |
+|---|---|---|---|
+| `applyShare(mon, split)` | silent | announces | **announces** (unchanged) |
+| `applyShare(mon, split, nil)` | silent | announces | **silent** |
+| `applyShare(mon, split, false)` | silent | announces | **silent** |
+| `applyShare(mon, split, true)` | announces | announces | announces |
+| `applyShare(mon, split, "expAll")` | announces | announces | announces |
+
+The argument is honoured **only when it is actually passed**, decided by
+argument count rather than by value:
+
+```lua
+local function applyShare(mon, split, ...)
+  local announce = ...
+  local silent = select("#", ...) > 0 and not announce
+  ...
+end
+```
+
+`select("#", ...)` counts an explicit `nil`, so `applyShare(mon, split)` and
+`applyShare(mon, split, nil)` are distinguishable — and they have to be, because
+the first is a Gen 2-era call written against a seam that always announced, and
+the second is a deliberate "pay this one quietly".
+
+Only the `{ kind = "experience" }` event is affected. A silent award is still a
+whole award: the exp, the stat exp, the `battle.exp_gained` event, the
+`grew to level` line, learned moves and the interactive forget-a-move prompt all
+happen exactly as before, in the same order.
+
+Internally `Battle:giveExperiencePass` takes a sixth parameter, `silent`. It
+defaults to announcing, so both of the cart's own passes are untouched.
+
+## Migration and compatibility
+
+**Existing mods change nothing.** A Gen 2 mod calling `applyShare(mon, split)`
+gets the behaviour it was written against. A Gen 1 mod is untouched: no Gen 1
+file is modified. The v1 surface — `content.X:register/override/get`,
+`events:on`, `hooks:wrap`, `mod.log`, `mod:read`, the manifest v1 fields and
+`pokemon.before_give` — is not involved; `mods/example_mew_starter` neither
+calls this seam nor loads differently.
+
+A mod that wants parity passes the argument explicitly, which is what the Gen 1
+seam has always documented. Exp Share already does, and needs no edit to get
+its own README's behaviour on Gold.
+
+One residual difference is deliberate and now documented rather than silent: an
+**omitted** third argument still means "silent" on Gen 1 and "announce" on
+Gold. Closing that would change what an existing Gen 2 mod prints, which Route
+B rejects. Passing the argument makes the two generations agree, so the rule an
+author needs is one sentence: *say what you mean and both games do the same
+thing.*
+
+## Verification
+
+- `tests/gen2_exp_share_test.lua` grows two sections and 14 checks, and the 23
+  checks it already had are unchanged — which is itself the vanilla-parity
+  evidence for this file.
+  - **The no-mod test.** With nothing subscribed to `battle.exp_award`, a solo
+    participant still prints one line and the EXP.SHARE double pass still
+    prints both. The hot path is unchanged: `Runtime.wantsHook` still guards
+    the ctx allocation, and `vanillaAward` never passes `silent`.
+  - **The mod-API test.** The seam is driven through `hooks:wrap` on a real
+    `Runtime.install`ed bus, not by calling internals: the omitted argument
+    announces, an explicit `nil` and an explicit `false` are silent, a truthy
+    value (including Gen 1's `"expAll"`) announces, the exp and stat exp paid
+    are identical either way, and no `experience` event leaks into the queue on
+    a silent pass.
+- `tests/engine/gate_gen2_mod_api.lua` (943 checks),
+  `tests/engine/gate_hooks.lua` (493) and `tests/engine/gate_events.lua` (529)
+  pass unchanged; `battle.exp_award` was already in the shared catalog, so no
+  gate list moves.
+- `tests/gen2_battle_test.lua` (690), `gen2_battle_end_test.lua` (32),
+  `gen2_battle_items_test.lua` (99), `gen2_badge_boosts_test.lua` (34) and
+  `gen2_battle_loss_test.lua` (15) pass unchanged.
+
+## Docs with the change
+
+`docs/mod-api-gen2-compat.md` gains the `applyShare` reading beside the
+existing `battle.low_health_alarm` payload note, in the same section that lists
+`battle.exp_award` as shared — including the argument-count rule and the
+residual difference above.
+
+No registry or schema field changes, so `src/mods/Schemas.lua` is untouched and
+`tools/gen_registry_docs.lua` has nothing new to emit.
+
+## Deprecation etiquette
+
+Nothing is removed, renamed, superseded or deprecated. The two-argument call is
+not deprecated either — it keeps its current Gen 2 meaning permanently, and the
+docs name the explicit form as the one that behaves the same on both games.

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 |
@@ -98,8 +100,8 @@ corners fire two directions. `screens[1].outputFrame` (or the legacy
 `gameScreenFrame`) becomes the screen cutout. A portrait page with neither
 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 still
+usual GBA4iOS controller-deck layout. Pages that name a screen rect fit the
-stretch to the window the way Delta does. Host functions map to
+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.
@@ -135,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
@@ -146,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.
@@ -153,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
 
@@ -190,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.
@@ -200,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 |
@@ -216,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
@@ -247,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

docs/updater.md

@@ -126,9 +126,12 @@ bundled game, in that case.
    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
+   version-code, and signing-certificate compatibility. A legacy APK without
-   sideload repository for a re-sideload; Xbox, desktop, and PortMaster builds
+   the installer bridge links its full package for one manual bootstrap
-   link their correctly named full package. Switch keeps its native OTA flow.
+   update, including when its downloaded payload already reports the latest
+   engine version. 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
 

main.lua

@@ -24,10 +24,10 @@ local GameViewport = require("src.render.GameViewport")
 
 -- Lua errors: persist a redacted trace in the save dir and surface a hint.
 do
-  local defaultErrorHandler = love.errorhandler
+  local defaultErrorHandler = love.errorhandler or love.errhand
   function love.errorhandler(msg)
-    local hint = SwitchDiagnostics.logLuaError(msg)
+    local ok, hint = pcall(SwitchDiagnostics.logLuaError, msg)
-    if hint and type(msg) == "string" then
+    if ok and hint and type(msg) == "string" then
       msg = msg .. "\n\n" .. hint
     end
     if defaultErrorHandler then
@@ -82,6 +82,43 @@ end
 local editorHost, editorVersion, editorWindow
 local closeEditor  -- forward declaration: openEditor hands it to the editor
 
+-- Drop CacheFs / Data / mod Runtime / Assets / LegacyCompat for one mounted
+-- version session (save editor or game).  closeEditor and returnToLauncher
+-- both go through here so neither path can forget a singleton the other resets.
+local function teardownMountedSession(version)
+  if version then
+    require("src.import.CacheFs").unmountVersion(version)
+  end
+  require("src.core.Data"):unloadGenerated()
+  local Runtime = require("src.mods.Runtime")
+  if Runtime.reset then Runtime.reset() end
+  local Assets = require("src.render.Assets")
+  if Assets.installLoader then Assets.installLoader(nil) end
+  local okCompat, LegacyCompat = pcall(require, "src.mods.LegacyCompat")
+  if okCompat and LegacyCompat.reset then LegacyCompat.reset() end
+end
+
+-- Evict every save-editor module from package.loaded without a hardcoded
+-- panel whitelist.  Flat require names (App, Party, …) resolve under
+-- tools/save-editor/; path-style keys may also appear.  A key is flushed
+-- when it names a save-editor path or when tools/save-editor/{panels/}K.lua
+-- exists for a flat name K -- new panels are picked up automatically.
+local function flushEditorPackageLoaded()
+  local fs = love and love.filesystem
+  local function isEditorFlat(name)
+    if not (fs and fs.getInfo) then return false end
+    if name:find("[./]") then return false end
+    return fs.getInfo("tools/save-editor/" .. name .. ".lua") ~= nil
+      or fs.getInfo("tools/save-editor/panels/" .. name .. ".lua") ~= nil
+  end
+  for k in pairs(package.loaded) do
+    if type(k) == "string"
+        and (k:find("save%-editor", 1, false) or isEditorFlat(k)) then
+      package.loaded[k] = nil
+    end
+  end
+end
+
 -- The editor's modules use flat names (require("Kit"), require("Party")), so
 -- their directories have to be on the require path.  It must be
 -- love.filesystem's path, not package.path: in a packaged build these files
@@ -180,9 +217,9 @@ local function openEditor(version, slotId)
     if EditorApp.unload then pcall(EditorApp.unload) end
     EditorApp = nil
     if version then
-      require("src.import.CacheFs").unmountVersion(version)
+      teardownMountedSession(version)
-      require("src.core.Data"):unloadGenerated()
     end
+    flushEditorPackageLoaded()
     restoreWindow()
     Importer = editorHost
     editorHost = nil
@@ -197,21 +234,17 @@ end
 -- Back to the launcher.  Everything the editor mounted or cached has to come
 -- back out: the version overlay (CacheFs) and the generated modules require
 -- cached behind it (Data), or pressing Play on the OTHER game would boot it
--- with this one's data.
+-- with this one's data.  Also reset Runtime / Assets / LegacyCompat so the
+-- next Edit or Play does not inherit the editor's dead mod loader.
 function closeEditor()
   local version = editorVersion
   editorMode = false
   if EditorApp and EditorApp.unload then EditorApp.unload() end
   EditorApp = nil
   if version then
-    require("src.import.CacheFs").unmountVersion(version)
+    teardownMountedSession(version)
-    require("src.core.Data"):unloadGenerated()
-  end
-  for k in pairs(package.loaded) do
-    if type(k) == "string" and (k:find("save%-editor") or k == "App" or k == "Kit" or k == "State" or k == "Catalog" or k == "SaveIO" or k == "Ops" or k == "MonOps" or k == "ItemOps" or k == "PadInput" or k == "Gen" or k == "Theme") then
-      package.loaded[k] = nil
-    end
   end
+  flushEditorPackageLoaded()
   editorVersion = nil
   restoreWindow()
   Importer = editorHost
@@ -302,6 +335,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,
   })
@@ -331,16 +366,11 @@ local function returnToLauncher()
 
   local GameVersion = require("src.core.GameVersion")
   local currentVersion = GameVersion.get()
-  if currentVersion then
+  teardownMountedSession(currentVersion)
-    require("src.import.CacheFs").unmountVersion(currentVersion)
-  end
-  require("src.core.Data"):unloadGenerated()
 
-  local Runtime = require("src.mods.Runtime")
+  if Game.reset then
-  if Runtime.reset then
+    pcall(function() Game:reset() end)
-    Runtime.reset()
   end
-
   Game = nil
   autopilot = nil
   driverCo = nil
@@ -877,6 +907,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()
@@ -929,7 +961,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
@@ -946,7 +978,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
@@ -960,7 +992,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
@@ -1013,7 +1045,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
@@ -1048,7 +1085,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)
@@ -1066,7 +1106,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/app/src/main/AndroidManifest.xml

@@ -54,7 +54,7 @@
     <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}"
@@ -71,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/ios/app-repo.json

@@ -12,6 +12,41 @@
       "tintColor": "3b5ca8",
       "category": "games",
       "versions": [
+        {
+          "version": "0.2.19",
+          "date": "2026-08-22",
+          "size": 13778435,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.19/gen1recomp++-0.2.19-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1274 Choose ROM imports a different version than the one selected when several dumps are pending (Linux, no file picker)\n- #1484 (Pokémon Gold) Bill's PC doesn't show equipped items + missing orange filter on pokémon sprite\n- #1486 (Pokémon Gold) Can't deposit key items\n- #1513 Experience share issue different case from #1464\n- #1517 Game Crash Opening Stats\n- #1548 Colisión\n- #1556 (Gold) Missing SFX for a lot of actions\n- #1564 Bide's storing turn is missing the screen shake\n- #1567 TM/HM case not in order\n- #1663 transition pops the top state, destroying anything pushed from a midpoint callback\n- #1664 gold bide spends pp every turn instead of only the turn it is selected\n- #1665 gold has no bide lock-in, so a mid-bide switch of move strands the counter\n- #1666 sleep talk is inert in gold: EFFECT_SLEEP_TALK has no move effect entry\n- #1667 gold: a fainted party mon keeps its exp participant credit and halves the survivor's exp\n- #1668 summary page 2 formats a move's pp with no numeric guard\n- #1670 gold tm/hm pocket capacity is an invented 64 where the cart has 57 slots\n- #1672 bill's pc move screen is missing the box name arrows\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi\n- @colsonrice\n- @jramiresbrito"
+        },
+        {
+          "version": "0.2.18",
+          "date": "2026-08-21",
+          "size": 13772120,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.18/gen1recomp++-0.2.18-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.2.17",
+          "date": "2026-08-21",
+          "size": 13771903,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.17/gen1recomp++-0.2.17-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "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",

scripts/lint.sh

@@ -7,7 +7,8 @@
 # the nil global), unused values, unreachable code. The .luacheckrc mutes the
 # cosmetic categories the codebase lives with, so what prints is worth a look.
 #
-#   scripts/lint.sh            lint src/
+#   scripts/lint.sh            full advisory report over every shipped tree
+#   scripts/lint.sh --gate     only the codes CI blocks on (0xx, 1xx, 511)
 #   scripts/lint.sh src tools  lint specific paths
 #
 # Install once with:  luarocks install luacheck
@@ -15,9 +16,27 @@
 set -uo pipefail
 cd "$(dirname "$0")/.."
 
+DEFAULT_PATHS=(main.lua conf.lua src data/scripts mods tools)
+
+GATE=0
+if [ "${1:-}" = "--gate" ]; then
+  GATE=1
+  shift
+fi
+
 if ! command -v luacheck >/dev/null 2>&1; then
   echo "luacheck not found on PATH (install: luarocks install luacheck)" >&2
   exit 2
 fi
 
-luacheck "${@:-src}"
+if [ "$#" -gt 0 ]; then
+  PATHS=("$@")
+else
+  PATHS=("${DEFAULT_PATHS[@]}")
+fi
+
+if [ "$GATE" = "1" ]; then
+  exec luacheck "${PATHS[@]}" -q --codes --only 0 1 511
+fi
+
+luacheck "${PATHS[@]}"

scripts/test.sh

@@ -66,6 +66,15 @@ run_tier() {
 
 # ------- ROM-free tiers: these are what CI runs
 
+if command -v luacheck >/dev/null 2>&1; then
+  run_tier "T0 luacheck gate (undefined globals, unreachable code)" \
+    ./scripts/lint.sh --gate
+else
+  echo ""
+  echo "-- T0 luacheck gate: skipped (no luacheck on PATH --"
+  echo "   luarocks install luacheck; CI installs and gates on it regardless)"
+fi
+
 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

src/battle/BattleState.lua

@@ -538,6 +538,7 @@ end
 
 local function makeBattler(data, mon, isPlayer, save)
   local def = data.pokemon[mon.species]
+  require("src.pokemon.Stats").ensure(def, mon)
   local badgeBoosts = data.constants and data.constants.badgeBoosts
   local badges = nil
   if isPlayer and save then
@@ -3980,7 +3981,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

src/battle/MoveEffects.lua

@@ -645,7 +645,9 @@ MoveEffects.full = {
       user.bideTurns = ctx.rng(2, 3)
       user.bideDamage = 0
       ctx.battle:cancelMoveAnim()
-      ctx.anim(user.isPlayer and "XSTATITEM_ANIM" or "XSTATITEM_DUPLICATE_ANIM")
+      ctx.battle:animBeforeMove(
+        user.isPlayer and "XSTATITEM_ANIM" or "XSTATITEM_DUPLICATE_ANIM",
+        user.isPlayer)
       ctx.say(Strings("%s\nis storing energy!", displayName(user)))
     end,
   },

src/battle/gen2/Battle.lua

@@ -903,8 +903,16 @@ function Battle:movePriority(moveId)
   return (def and Battle.PRIORITY[def.effect]) or 0
 end
 
+-- engine/battle/effect_commands.asm:192-197 (enemy twin :383-390)
+Battle.SLEEP_BYPASS_MOVES = { SNORE = true, SLEEP_TALK = true }
+
 -- Can this mon act?  Returns true, or false plus the message the cart prints.
-function Battle:canAct(mon)
+-- `moveId` is wCurPlayerMove / wCurEnemyMove (effect_commands.asm:193).
+local function clearBide(state)
+  state.bideTurns, state.bideStored, state.bideMove = nil, nil, nil
+end
+
+local function checkTurn(self, mon, moveId)
   local name = self:monName(mon)
   -- SUBSTATUS_RECHARGE, and it is checked BEFORE status: CheckPlayerTurn reads
   -- it first, clears it, prints MustRechargeText and jumps to EndTurn, so a mon
@@ -925,7 +933,11 @@ function Battle:canAct(mon)
   local beforeMove = record and record.beforeMove
   if beforeMove
       and (record.beforeMovePriority or 0) > Battle.VOLATILE_PRIORITY then
-    return beforeMove(self, mon, name) and true or false
+    -- engine/battle/effect_commands.asm:188-200
+    local bypass = mon.status == "sleep" and Battle.SLEEP_BYPASS_MOVES[moveId]
+    local acted = beforeMove(self, mon, name) and true or false
+    if acted or not bypass then return acted end
+    beforeMove = nil
   end
   -- SUBSTATUS_FLINCHED, read and cleared right after the freeze check
   -- (CheckPlayerTurn / CheckEnemyTurn `.not_frozen`).  Set this turn by the
@@ -959,6 +971,14 @@ function Battle:canAct(mon)
   return true
 end
 
+-- CantMove (engine/battle/effect_commands.asm:344-353) clears BIDE on every
+-- arm of CheckPlayerTurn / CheckEnemyTurn that spends the turn.
+function Battle:canAct(mon, moveId)
+  local acted = checkTurn(self, mon, moveId)
+  if not acted then clearBide(self:volatile(mon)) end
+  return acted
+end
+
 -- STRUGGLE, the move a mon with nothing left to spend falls back to
 -- (engine/battle/core.asm `.CheckPlayerHasUsableMoves` for the player and
 -- `.struggle` for the enemy).  It lives in the move table like any other move
@@ -1234,10 +1254,15 @@ function Battle:dealDamage(attacker, defender, damage, opts)
   if opts.critical then
     self:emit({ kind = "message", text = "A critical hit!" })
   end
+  -- SuperEffectiveText / NotVeryEffectiveText (data/text/battle.asm:603,608).
+  -- The cart breaks both across the box's two lines and hyphenates "super-"
+  -- to do it, and the not-very line ends on the single ellipsis glyph Gold's
+  -- charmap carries at $75, not three periods.
   if opts.effectiveness and opts.effectiveness > 10 then
-    self:emit({ kind = "message", text = "It's super effective!" })
+    self:emit({ kind = "message", text = Strings("It's super-\neffective!") })
   elseif opts.effectiveness and opts.effectiveness < 10 then
-    self:emit({ kind = "message", text = "It's not very effective..." })
+    self:emit({ kind = "message",
+      text = Strings("It's not very\neffective…") })
   end
   if endured then
     self:emit({ kind = "message",
@@ -1389,9 +1414,18 @@ function Battle:useMove(attacker, defender, moveId)
   -- free of PP and obedience in exactly the same way.
   local rolling = state.rolloutLock == moveId
 
-  if not (charging or rampaging or rolling) then
+  -- engine/battle/effect_commands.asm:977-979, data/moves/effects.asm:795-800,
+  -- engine/battle/move_effects/bide.asm:62-68
+  local biding = def.effect == "EFFECT_BIDE" and state.bideTurns ~= nil
+
+  -- engine/battle/effect_commands.asm:6222-6234, :949-951
+  local called = (self.copyDepth or 0) > 0
+
+  if not (charging or rampaging or rolling or biding or called) then
     if move and (move.pp or 0) <= 0 then
-      self:emit({ kind = "message", text = "No PP left for this move!" })
+      -- BattleText_TheresNoPPLeftForThisMove (data/text/battle.asm:315).
+      self:emit({ kind = "message",
+        text = Strings("There's no PP left\nfor this move!") })
       return
     end
     if move then move.pp = (move.pp or 1) - 1 end
@@ -1471,9 +1505,38 @@ function Battle:useMove(attacker, defender, moveId)
     return
   end
 
+  -- engine/battle/move_effects/sleep_talk.asm:2, :16-19, :61
+  if def.effect == "EFFECT_SLEEP_TALK" then
+    local picked
+    if attacker.status == "sleep" and (self.copyDepth or 0) == 0 then
+      -- engine/battle/move_effects/sleep_talk.asm:40-44, :117-141
+      local pool = {}
+      for _, own in ipairs(attacker.moves or {}) do
+        local ownDef = self:moveDef(own.id)
+        local effect = ownDef and ownDef.effect
+        if own.id ~= moveId and not self:moveDisabled(attacker, own.id)
+            and not Effects.CHARGE[effect] and effect ~= "EFFECT_BIDE" then
+          pool[#pool + 1] = own.id
+        end
+      end
+      if #pool > 0 then picked = pool[rand(self.random, #pool) + 1] end
+    end
+    if not picked then
+      self:markMissed()
+      self:emit({ kind = "message", text = "But it failed!" })
+      return
+    end
+    state.lastMove = nil
+    self.copyDepth = (self.copyDepth or 0) + 1
+    self:useMove(attacker, defender, picked)
+    self.copyDepth = self.copyDepth - 1
+    return
+  end
+
   -- Everything past here counts as "the user's last move" for Mirror Move,
-  -- Encore and Disable.
+  -- Encore and Disable.  A called move skips the write
-  state.lastMove = moveId
+  -- (engine/battle/used_move_text.asm:30-36).
+  if (self.copyDepth or 0) == 0 then state.lastMove = moveId end
   state.turnsTaken = (state.turnsTaken or 0) + 1
   state.usedMoves = state.usedMoves or {}
   local seen = false
@@ -1494,6 +1557,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
@@ -1507,6 +1579,13 @@ function Battle:useMove(attacker, defender, moveId)
     return
   end
 
+  -- BattleCommand_Snore (engine/battle/move_effects/snore.asm:1-9)
+  if def.effect == "EFFECT_SNORE" and attacker.status ~= "sleep" then
+    self:markMissed()
+    self:emit({ kind = "message", text = "But it failed!" })
+    return
+  end
+
   -- Counter and Mirror Coat answer what the user took this turn, at double,
   -- and fail outright when nothing of the right kind landed.
   local counterKind = Effects.COUNTER[def.effect]
@@ -1738,8 +1817,12 @@ function Battle:useMove(attacker, defender, moveId)
       landed = landed + 1
     end
     if landed > 1 then
-      self:emit({ kind = "message",
+      -- PlayerHitTimesText / EnemyHitTimesText (data/text/battle.asm:749,755)
-        text = ("Hit %d time(s)!"):format(landed) })
+      -- are "Hit @ times!".  Gen 2 has no singular form of this line, so the
+      -- plural stands even at one hit rather than the "(s)" this printed.
+      -- Gen 1 already says it this way (src/battle/EffectRegistry.lua,
+      -- _HitXTimesText).
+      self:emit({ kind = "message", text = Strings("Hit %d times!", landed) })
     end
 
     -- move_effects/pay_day.asm:13
@@ -1959,8 +2042,11 @@ Battle.MOVE_EFFECTS.EFFECT_PERISH_SONG = function(self)
   if mine.perish and theirs.perish then return fail(self) end
   if not mine.perish then mine.perish = Effects.PERISH_TURNS end
   if not theirs.perish then theirs.perish = Effects.PERISH_TURNS end
+  -- StartPerishText (data/text/battle.asm:986).  What shipped here was a
+  -- sentence no cart prints; the Gen 2 line names both sides and counts in
+  -- digits.
   self:emit({ kind = "message",
-    text = "All POKéMON hearing the song will faint in three turns!" })
+    text = Strings("Both POKéMON will\nfaint in 3 turns!") })
 end
 
 -- BattleCommand_Encore: 3-6 turns locked into the move the target last used.
@@ -2090,6 +2176,11 @@ Battle.MOVE_EFFECTS.EFFECT_SPIKES = function(self, attacker, defender)
   local side = self:sideOf(defender)
   if self.spikes[side] then return fail(self) end
   self.spikes[side] = true
+  -- SpikesText (data/text/battle.asm:974) is three rows, the third scrolled
+  -- (`cont`) and carrying <TARGET>.  The battle message path has no `cont`:
+  -- src/ui/gen2/BattleState.lua sets self.message straight from the event and
+  -- printMessage cuts past two rows, so the cart's line cannot be told here
+  -- yet without the name being dropped on screen.  Left as it stands.
   self:emit({ kind = "message", text = "Spikes were scattered all around!" })
 end
 
@@ -2124,6 +2215,8 @@ Battle.MOVE_EFFECTS.EFFECT_BIDE = function(self, attacker, defender, def, moveId
   if not state.bideTurns then
     state.bideTurns = Effects.bideTurns(self.random)
     state.bideStored = 0
+    -- engine/battle/core.asm:574-576
+    state.bideMove = moveId
     self:emit({ kind = "message",
       text = self:monName(attacker) .. " is storing energy!" })
     return
@@ -2135,7 +2228,7 @@ Battle.MOVE_EFFECTS.EFFECT_BIDE = function(self, attacker, defender, def, moveId
     return
   end
   local damage = Effects.bideDamage(state.bideStored)
-  state.bideTurns, state.bideStored = nil, nil
+  state.bideTurns, state.bideStored, state.bideMove = nil, nil, nil
   self:emit({ kind = "message",
     text = self:monName(attacker) .. " unleashed energy!" })
   if damage <= 0 then return fail(self) end
@@ -2325,7 +2418,9 @@ Battle.MOVE_EFFECTS.EFFECT_BEAT_UP = function(self, attacker, defender, def)
       { move = def, moveId = def and def.id })
     landed = landed + 1
   end
-  self:emit({ kind = "message", text = ("Hit %d time(s)!"):format(landed) })
+  -- BattleCommand_EndLoop prints the same line for Beat Up, and Beat Up can
+  -- land exactly once, which is the case the cart still prints as "times".
+  self:emit({ kind = "message", text = Strings("Hit %d times!", landed) })
 end
 
 -- BattleCommand_Heal (effect_commands.asm:5986): Recover and Rest are both
@@ -2408,6 +2503,8 @@ Battle.MOVE_EFFECTS.EFFECT_BATON_PASS = function(self, attacker)
     self.enemyIndex = target
     self.enemy = party[target]
     self.enemy.volatile = carried
+    -- engine/battle/move_effects/baton_pass.asm:59
+    self:resetParticipants()
   end
   local sent = side == "player" and self.player or self.enemy
   self:emit({ kind = "send", side = side, mon = sent,
@@ -2670,6 +2767,8 @@ Battle.MOVE_EFFECTS.EFFECT_FORCE_SWITCH = function(self, attacker, defender,
     self.enemyIndex = pick
     self.enemy = incoming
     self.stages.enemy = Battle.newStages()
+    -- ForceEnemySwitch (engine/battle/core.asm:2937)
+    self:resetParticipants()
   end
   self:emit({ kind = "send", side = self:sideOf(incoming), mon = incoming,
     hp = incoming.hp or 0, status = incoming.status or false,
@@ -3079,6 +3178,12 @@ end
 
 -- Faint bookkeeping and experience.  Returns true when the battle ended.
 function Battle:resolveFaints()
+  -- engine/battle/core.asm:2551-2556, :7116-7130, :3033-3037
+  if (self.player.hp or 0) <= 0 and self.participantsCleared ~= self.player then
+    self.participantsCleared = self.player
+    if self.playerIndex then self.participants[self.playerIndex] = nil end
+  end
+
   if (self.enemy.hp or 0) <= 0 then
     self:emit({ kind = "faint", side = "enemy",
       text = (self.wild and "Wild " or "") .. self:monName(self.enemy)
@@ -3263,7 +3368,16 @@ end
 -- `count` is the pass's own divisor -- the participant count for the first
 -- pass, the holder count for the EXP.SHARE pass -- and `halved` is whether
 -- any Share holder taxed the whole pool.
-function Battle:giveExperiencePass(loser, def, recipients, count, halved)
+--
+-- `silent` suppresses only the GainedText line.  It exists for the
+-- battle.exp_award seam below, where a mod paying the bench wants one summary
+-- line rather than a box per mon; the cart's own two passes never pass it, so
+-- vanilla prints exactly what it always did.  Everything else about the pass
+-- -- the exp, the stat exp, battle.exp_gained, "grew to level", learned moves
+-- and the forget prompt -- is unaffected, because a silent award is still an
+-- award.
+function Battle:giveExperiencePass(loser, def, recipients, count, halved,
+                                   silent)
   for _, index in ipairs(recipients) do
     local mon = self.party[index]
     if mon and (mon.hp or 0) > 0 and not mon.isEgg then
@@ -3314,10 +3428,12 @@ function Battle:giveExperiencePass(loser, def, recipients, count, halved)
           index = index,
         })
       end
+      if not silent then
         self:emit({ kind = "experience", index = index, amount = amount,
           -- BoostedExpPointsText, keyed on the traded arm alone.
           text = self:monName(mon) .. " gained "
             .. (traded and "a boosted " or "") .. amount .. " EXP. Points!" })
+      end
       if result.levels > 0 then
         -- "level up happiness mod", the cart's own comment, sitting right
         -- after the stat recalc and before the "grew to level" text.  It fires
@@ -3332,7 +3448,9 @@ function Battle:giveExperiencePass(loser, def, recipients, count, halved)
           local moveDef = self:moveDef(moveId)
           local moveName = (moveDef and moveDef.name) or moveId
           if ok then
+            -- data/text/common_3.asm:119
             self:emit({ kind = "message",
+              sfx = "Sfx_DexFanfare5079", waitSfx = true,
               text = self:monName(mon) .. " learned " .. moveName .. "!" })
           elseif reason == "full" then
             -- LearnMove's full-moveset arm calls ForgetMove, which asks with
@@ -3411,22 +3529,38 @@ function Battle:awardExperience(loser)
 
   -- battle.exp_award, the same hook BattleState:awardExp calls on Gen 1 and
   -- with the same ctx: the participant COUNT, the live participants, and an
-  -- applyShare(mon, split) a mod can call to pay one mon its own share.  The
+  -- applyShare(mon, split, announce) a mod can call to pay one mon its own
-  -- third applyShare argument is Gen 1's EXP.ALL announcement variant; Gen 2
+  -- share.  `recipients`, `holders` and `halved` are the Gen 2 additions.
-  -- has no EXP.ALL (the EXP.SHARE pass below is its replacement), so it is
+  --
-  -- accepted and ignored rather than changing what is printed.  `recipients`,
+  -- `announce` is Gen 1's third argument (src/battle/BattleState.lua
-  -- `holders` and `halved` are the Gen 2 additions.
+  -- applyShare) and means the same thing here: truthy prints the mon's
+  -- GainedText, falsy pays it silently.  That is what lets one mod source
+  -- print ONE summary line for a party-wide award on both generations instead
+  -- of a box per mon -- which is what the Exp Share mod documents and could
+  -- not do on Gold, because this argument used to be accepted and ignored.
+  --
+  -- It is honoured only when it is actually PASSED, by argument count rather
+  -- than by value.  A Gen 2-era mod calling applyShare(mon, split) was written
+  -- against a seam that always announced and keeps announcing; a caller that
+  -- passes the argument -- including an explicit nil, which is what a "pay
+  -- this one quietly" call looks like -- gets Gen 1's reading.  So no existing
+  -- mod changes behaviour, and a mod that opts in gets parity.
   if Runtime.wantsHook("battle.exp_award") then
     local alive = {}
     for _, index in ipairs(participants) do
       local mon = self.party[index]
       if mon and (mon.hp or 0) > 0 then alive[#alive + 1] = mon end
     end
-    local function applyShare(mon, split)
+    local function applyShare(mon, split, ...)
+      local announce = ...
+      -- select("#") counts an explicit nil; `announce == nil` alone could not
+      -- tell applyShare(mon, split) from applyShare(mon, split, nil), and
+      -- those two have to mean different things here.
+      local silent = select("#", ...) > 0 and not announce
       for index, candidate in ipairs(self.party) do
         if candidate == mon then
           return self:giveExperiencePass(loser, def, { index },
-            math.max(1, split or 1), halved)
+            math.max(1, split or 1), halved, silent)
         end
       end
     end
@@ -3441,8 +3575,7 @@ function Battle:awardExperience(loser)
 
   -- GiveExperiencePoints .done falls through ResetBattleParticipants into
   -- AddBattleParticipant (engine/battle/core.asm:7116 and :3033).
-  self.participants = {}
+  self:resetParticipants()
-  if self.playerIndex then self.participants[self.playerIndex] = true end
 end
 
 -- The answer to a `choose-forget`: drop the move in `slot` and put the
@@ -3463,7 +3596,9 @@ function Battle:resolveForget(index, slot, entry, moveName)
   end
   self:emit({ kind = "message",
     text = "1, 2 and… " .. self:monName(mon) .. " forgot " .. oldName .. "!" })
+  -- engine/pokemon/learn.asm:115, data/text/common_3.asm:119
   self:emit({ kind = "message",
+    sfx = "Sfx_DexFanfare5079", waitSfx = true,
     text = self:monName(mon) .. " learned "
       .. (moveName or (entry and entry.id) or "?") .. "!" })
   -- The forget path writes the slot itself rather than going through
@@ -3502,6 +3637,13 @@ function Battle:switchLocked()
   return self:volatile(self.enemy).trapsTarget == true
 end
 
+-- ResetBattleParticipants falls through into AddBattleParticipant
+-- (engine/battle/core.asm:3033 and :3037).
+function Battle:resetParticipants()
+  self.participants = {}
+  if self.playerIndex then self.participants[self.playerIndex] = true end
+end
+
 -- EnemySwitch's shift arm zeroes both participant bitfields before PlayerSwitch
 -- (engine/battle/core.asm:2959-2961).
 function Battle:shiftSwitch(index)
@@ -3524,6 +3666,7 @@ function Battle:switch(index)
   -- A mon that comes back (a REVIVE, or a second battle) has to be able to
   -- announce its own faint again; see resolveFaints.
   self.faintAnnounced = nil
+  self.participantsCleared = nil
   -- ForcePlayerMonChoice has been answered, so the next faint may ask again.
   self.pendingSwitch = nil
   self.player = mon
@@ -3761,19 +3904,41 @@ function Battle:lockedInMove(mon)
   return nil
 end
 
+-- ParsePlayerAction's bide arm (engine/battle/core.asm:569-576), enemy twin
+-- at :5650
+function Battle:fightLockedMove(mon)
+  local state = self:volatile(mon)
+  if state.bideTurns then return state.bideMove end
+  return nil
+end
+
+-- engine/battle/core.asm:627-629
+function Battle:cancelBide(mon)
+  clearBide(self:volatile(mon))
+end
+
 -- Encore forces the move; Disable forbids one.  Both are read by the screen
 -- (to grey out the move list) and by the enemy's own choice below.
+-- engine/battle/core.asm:561-566
+local function encoredMove(state, mon)
+  if not state.encore then return nil end
+  for _, move in ipairs(mon.moves or {}) do
+    if move.id == state.encore and (move.pp or 0) > 0 then
+      return state.encore
+    end
+  end
+  state.encore, state.encoreTurns = nil, nil
+  return nil
+end
+
 function Battle:forcedMove(mon)
   local locked = self:lockedInMove(mon)
   if locked then return locked end
-  local state = self:volatile(mon)
+  -- ParsePlayerAction reads SUBSTATUS_ENCORED ahead of the bide arm
-  if not state.encore then return nil end
+  -- (engine/battle/core.asm:561-566).
-  for _, move in ipairs(mon.moves or {}) do
+  local encored = encoredMove(self:volatile(mon), mon)
-    if move.id == state.encore and (move.pp or 0) > 0 then return state.encore end
+  if encored then return encored end
-  end
+  return self:fightLockedMove(mon)
-  -- Encore ends early when the move runs out of PP.
-  state.encore, state.encoreTurns = nil, nil
-  return nil
 end
 
 function Battle:moveDisabled(mon, moveId)
@@ -3787,8 +3952,9 @@ function Battle:usableMoves(mon)
   -- .CheckPlayerHasUsableMoves (core.asm:533-556), so a Rollout or a rampage
   -- that spent its last PP on the opening turn keeps running: no later turn
   -- of the lock spends any.  Encore is not in this exemption -- forcedMove
-  -- ends it the moment the encored move runs dry.
+  -- ends it the moment the encored move runs dry.  Bide is exempt too:
-  local locked = self:lockedInMove(mon)
+  -- .CheckPlayerHasUsableMoves lives inside MoveSelectionScreen (core.asm:5058).
+  local locked = self:lockedInMove(mon) or self:fightLockedMove(mon)
   local out = {}
   for _, move in ipairs(mon.moves or {}) do
     local ok = (move.pp or 0) > 0 and not self:moveDisabled(mon, move.id)
@@ -3990,6 +4156,8 @@ function Battle:enemyTrySwitchOrItem()
         .. self:monName(outgoing) .. "!" })
     self.enemyIndex = target
     self.enemy = self.enemyParty[target]
+    -- AI_Switch (engine/battle/ai/items.asm:697)
+    self:resetParticipants()
     -- ResetEnemyBattleVars (engine/battle/core.asm:3016) zeroes wCurEnemyMove
     -- and wLastEnemyMove and NewEnemyMonStatus wipes the substatus bytes, so
     -- the mon coming IN starts from an empty area -- the same pair of clears
@@ -4080,9 +4248,16 @@ function Battle:vanillaEnemyMove()
   -- move answers "TYPHLOSION's attack missed!", so Hitmonlee cannot be damaged
   -- by anything, at any level.  Fifteen straight attempts at the Elite Four
   -- died there, and no amount of grinding could ever have got past it.
-  local charged = self:volatile(self.enemy).chargeMove
+  local enemyState = self:volatile(self.enemy)
+  local charged = enemyState.chargeMove
   if charged then return charged end
 
+  -- engine/battle/core.asm:5524-5533: the encore arm runs ahead of
+  -- CheckEnemyLockedIn (:5650).
+  local encored = encoredMove(enemyState, self.enemy)
+  if encored then return encored end
+  if enemyState.bideTurns then return enemyState.bideMove end
+
   -- Encore and Disable narrow the pool before the AI ever scores it.
   local moves = self:usableMoves(self.enemy)
   if #moves == 0 then
@@ -4176,6 +4351,7 @@ local function runTurn(self, action)
     -- (engine/battle/core.asm:5035-5038), which reopens the 2x2 menu with the
     -- turn unspent -- so a refused RUN never bought the enemy a free attack.
     if self.runRefused then return self:takeEvents() end
+    self:cancelBide(self.player)
     action = { kind = "skip" }
   end
 
@@ -4191,6 +4367,9 @@ local function runTurn(self, action)
   if action.kind == "item" and Battle.X_ITEMS[action.item] then
     Happiness.change(self.player, "USEDXITEM")
   end
+  -- engine/battle/core.asm:572-573 into :627-629; a switch takes :570-571
+  -- instead and keeps the store.
+  if action.kind == "item" then self:cancelBide(self.player) end
 
   -- AI_SwitchOrTryItem runs BEFORE the move is chosen: a trainer that decides
   -- to rotate or drink a potion spends its whole turn on it.
@@ -4239,7 +4418,6 @@ local function runTurn(self, action)
 
   local function playerAttack()
     if action.kind ~= "move" then return end
-    if not self:canAct(self.player) then return end
     local move = action.move
     -- An encored mon has no choice, whatever the menu said.
     local forced = self:forcedMove(self.player)
@@ -4259,13 +4437,20 @@ local function runTurn(self, action)
     -- player's own mon spends the rest of the battle underground.
     local stored = self:volatile(self.player).chargeMove
     if stored then move = stored end
+    -- engine/battle/core.asm:558-598 settles wCurPlayerMove before
+    -- engine/battle/effect_commands.asm:193 reads it.
+    if not self:canAct(self.player, move) then return end
     -- CheckPlayerLockedIn quits before .CheckPlayerHasUsableMoves and before
     -- checkobedience, so a locked Rollout or Thrash is exempt from the
     -- Struggle substitution and the obedience roll the same way the second
     -- half of a charge move is.
     local charging = self:volatile(self.player).chargeMove == move
       or self:lockedInMove(self.player) == move
-    if not charging and not self:hasUsableMoves(self.player) then
+    -- engine/battle/core.asm:5058, and data/moves/effects.asm:796 keeps
+    -- `checkobedience`.
+    local bideLocked = self:fightLockedMove(self.player) == move
+    if not charging and not bideLocked
+        and not self:hasUsableMoves(self.player) then
       self:emit({ kind = "message",
         text = self:monName(self.player) .. " has no moves left!" })
       move = Battle.STRUGGLE
@@ -4303,7 +4488,7 @@ local function runTurn(self, action)
       -- against a trainer, could not be escaped either.
       enemyMoveId = Battle.STRUGGLE
     end
-    if not self:canAct(self.enemy) then return end
+    if not self:canAct(self.enemy, enemyMoveId) then return end
     -- CheckEnemyTurn's disabled arm (engine/battle/effect_commands.asm:562-574):
     -- the AI chose before the player's Disable landed, so the turn is spent here.
     if self:moveDisabled(self.enemy, enemyMoveId) then

src/core/Game.lua

@@ -919,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
@@ -1390,4 +1381,26 @@ function Game:restoreCheckpointBattle(battle)
   if battle.resumeCheckpoint then battle:resumeCheckpoint() end
 end
 
+-- Drop every session-owned field so the next Game:load() starts clean when
+-- the process returns to the launcher in-place (Android / intent_game).
+-- main.lua must not guess field names: new systems (Game.network, …) are
+-- cleared automatically because only functions (methods) are kept.
+function Game:reset()
+  if self.stack and self.stack.clear then
+    pcall(function() self.stack:clear() end)
+  end
+  if self.renderer and self.renderer.releaseCanvases then
+    pcall(function() self.renderer:releaseCanvases() end)
+  end
+  local keys = {}
+  for key, value in pairs(self) do
+    if type(value) ~= "function" then
+      keys[#keys + 1] = key
+    end
+  end
+  for _, key in ipairs(keys) do
+    self[key] = nil
+  end
+end
+
 return Game

src/core/Game2.lua

@@ -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
@@ -496,8 +483,10 @@ function Game2:learnMoveOn(mon, moveId, onDone)
     if onDone then onDone(learned) end
   end
   if ok then
+    -- data/text/common_3.asm:119
     return self:say(("%s learned\n%s!"):format(name, moveName),
-      function() finish(true) end)
+      function() finish(true) end,
+      TextBox.soundOpts(self, "Sfx_DexFanfare5079"))
   end
   if reason ~= "full" then return finish(false) end
   local askForget, pickMove, askStop
@@ -552,9 +541,11 @@ function Game2:learnMoveOn(mon, moveId, onDone)
         -- The slot is written here rather than through Mon.learnMove, so
         -- pokemon.move_learned is raised here too.
         ModRuntime.emit("pokemon.move_learned", { mon = mon, moveId = moveId })
+        -- engine/pokemon/learn.asm:115, data/text/common_3.asm:119
         self:say(("1, 2 and… Poof!\f%s forgot\n%s.\fAnd…\f%s learned\n%s!")
           :format(name, oldName, name, moveName),
-          function() finish(true) end)
+          function() finish(true) end,
+          TextBox.soundOpts(self, "Sfx_DexFanfare5079"))
       end,
     })
   end
@@ -719,7 +710,9 @@ function Game2:usePartyItem(itemId)
       })
     elseif action == "candy" then
       self:consumeItem(itemId)
-      self:say(result.text, function() self:afterRareCandy(mon, result) end)
+      -- data/text/common_1.asm:86
+      self:say(result.text, function() self:afterRareCandy(mon, result) end,
+        result.sfx and TextBox.soundOpts(self, result.sfx) or nil)
     else
       self:consumeItem(itemId)
       self:say(result.text)
@@ -778,8 +771,10 @@ function Game2:useSelectItem()
     local name = (items[itemId] and items[itemId].name) or itemId
     self:say(Strings("{PLAYER} used the\n%s.", name))
   elseif outcome == "trophy_sent" then
+    -- data/text/common_3.asm:372
     self:say(Strings(
-      "There was a trophy\ninside!\fThe trophy was\nsent home."))
+      "There was a trophy\ninside!\fThe trophy was\nsent home."),
+      nil, TextBox.soundOpts(self, "Sfx_DexFanfare5079"))
   end
   -- Anything else (a fishing bite, the ITEMFINDER's queued script) already
   -- drives its own presentation off World:step -- nothing left to print here.
@@ -791,9 +786,9 @@ end
 -- onDone that popped again ate the state UNDER the box: dismissing a message
 -- over the PACK closed the PACK with it, and over an empty overworld stack it
 -- was a silent extra pop.
-function Game2:say(text, onDone)
+function Game2:say(text, onDone, opts)
   local TextBox = require("src.render.TextBox")
-  self.stack:push(TextBox.new(self, text, onDone))
+  self.stack:push(TextBox.new(self, text, onDone, opts))
 end
 
 -- The landmark the player is standing in, for the Pokegear map's marker.
@@ -948,6 +943,12 @@ function Game2:load()
   self.data.gen2Scripts = loadGenerated("data/generated/scripts.lua")
   self.data.gen2StdScripts = loadGenerated("data/generated/std_scripts.lua")
   self.data.gen2Text = loadGenerated("data/generated/text.lua")
+  -- The engine's own strings, keyed by the disassembly's label.  gen2Text
+  -- above is the script text and is keyed by bank:address for the overworld
+  -- VM, so the two are different tables and both are loaded.  This one is
+  -- what src/core/RomText.lua reads, which is why it lands on `text`: that
+  -- helper is shared with Gen 1 and looks up data.text[label].
+  self.data.text = loadGenerated("data/generated/rom_text.lua") or {}
   -- data/generated/events.lua: the side tables a script command NAMES rather
   -- than carries -- the phone book, the in-game trades, the elevator's floor
   -- labels, the decoration descriptions.  Keyed for World's own `eventTables`
@@ -1968,7 +1969,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.
@@ -1993,6 +1998,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
@@ -2003,27 +2015,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)
@@ -2032,4 +2066,79 @@ 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
+
+-- In-process return-to-launcher (Android / intent_game): drop session fields
+-- so a later Game2.new() + load is not sharing a live stack or mod loader.
+-- Methods live on the class table; pairs(self) only sees instance state.
+function Game2:reset()
+  if self.stack and self.stack.clear then
+    pcall(function() self.stack:clear() end)
+  end
+  local keys = {}
+  for key, value in pairs(self) do
+    if type(value) ~= "function" then
+      keys[#keys + 1] = key
+    end
+  end
+  for _, key in ipairs(keys) do
+    self[key] = nil
+  end
+end
+
 return Game2

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

@@ -1700,6 +1700,14 @@ local function clamp(n, lo, hi, fallback)
   return n
 end
 
+-- PP and the PP Up count are unsigned bit fields of one byte
+-- (constants/pokemon_data_constants.asm:101-102)
+local function ppInt(v, fallback)
+  local n = tonumber(v)
+  if n == nil or n ~= n or n == math.huge or n == -math.huge then return fallback end
+  return math.max(0, math.floor(n))
+end
+
 local function ensureOrphaned(save)
   if not save.orphaned then
     save.orphaned = { mons = {}, items = {} }
@@ -1763,7 +1771,7 @@ local function scrubKnownMon(mon, data)
   -- (status_screen.asm:66-76, add_mon.asm _MoveMon); deriving once here means
   -- every later reader (menus, battle, items, SGB bar zones, the link
   -- fingerprint) sees a party-shaped mon.  Runs after the level clamp above
-  -- so the derived stats use a sane level.  A save that already has stats is
+  -- so the derived stats use a sane level.  A complete stat block is
   -- untouched.
   Stats.ensure(data.pokemon and data.pokemon[mon.species], mon)
   local moves = mon.moves
@@ -1783,6 +1791,18 @@ local function scrubKnownMon(mon, data)
       moves[1] = { id = fallback, pp = def.pp }
     end
   end
+  -- the replacement PP mirrors AddBonusPP (engine/items/item_effects.asm:2418);
+  -- Mimic rewrites the move id and not the PP (engine/battle/effects.asm:1266)
+  for j = 1, #moves do
+    local slot = moves[j]
+    if type(slot) == "table" then
+      local mdef = data.moves and data.moves[slot.id]
+      local base = ppInt(mdef and mdef.pp, 0)
+      local ppUps = math.min(3, ppInt(slot.ppUps, 0))
+      if slot.ppUps ~= nil then slot.ppUps = ppUps end
+      slot.pp = ppInt(slot.pp, base + ppUps * math.floor(base / 5))
+    end
+  end
 end
 
 local function scrubMonList(list, where, save, data, report)

src/core/ScreenPosition.lua

@@ -12,10 +12,12 @@ function ScreenPosition.normalize(v)
 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
@@ -44,6 +46,9 @@ 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

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

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

src/core/TouchSkin.lua

@@ -294,7 +294,6 @@ function TouchSkin.parse(text)
       page.viewport = { x = num(vp[1], 0), y = num(vp[2], 0),
                         w = num(vp[3], 1), h = num(vp[4], 1) }
       page.viewportFill = toBool(kv[p .. "_viewport_fill"])
-      page.viewportExpand = toBool(kv[p .. "_viewport_expand"])
     end
 
     page.pixelCoords = not page.normalized
@@ -447,7 +446,6 @@ function TouchSkin.parseNative(text)
       page.viewport = { x = num(raw.viewport.x, 0), y = num(raw.viewport.y, 0),
                         w = num(raw.viewport.w, 1), h = num(raw.viewport.h, 1) }
       page.viewportFill = raw.viewport.fill == true
-      page.viewportExpand = raw.viewport.expand == true
     end
     for _, c in ipairs(raw.controls or {}) do
       local buttons, hotkeys, keys, decorative = parseBinds(c.bind or "nul")
@@ -526,7 +524,6 @@ function TouchSkin.toNative(skin)
         x = page.viewport.x, y = page.viewport.y,
         w = page.viewport.w, h = page.viewport.h,
         fill = page.viewportFill or nil,
-        expand = page.viewportExpand or nil,
       }
     end
     for _, ctl in ipairs(page.controls or {}) do
@@ -636,6 +633,19 @@ local function applyPixelScale(page)
   return true
 end
 
+-- An overlay image is its own design canvas.  Older RetroArch cfg files often
+-- omit `aspect_ratio`; reading the dimensions here keeps that legacy art and
+-- all of its normalized controls on the same uniform scale.
+function TouchSkin.applyImageAspect(page)
+  if not page or page.aspectFromCfg or not page.image
+     or not page.image.getDimensions then return false end
+  local iw, ih = page.image:getDimensions()
+  if not iw or not ih or iw <= 0 or ih <= 0 then return false end
+  page.aspect = iw / ih
+  page.aspectFromImage = true
+  return true
+end
+
 function TouchSkin.load(root, id)
   local cfgPath, format, prefix = findConfig(root)
   if not cfgPath then return nil, "no skin.lua, .cfg or info.json in " .. root end
@@ -665,6 +675,7 @@ function TouchSkin.load(root, id)
     elseif page.pdfPath then
       rasterizePdfPage(page, root)
     end
+    TouchSkin.applyImageAspect(page)
     if not applyPixelScale(page) then
       return nil, "could not read " .. tostring(page.imagePath)
         .. ", which " .. page.name .. " measures its coordinates against"
@@ -771,6 +782,28 @@ function TouchSkin.find(id)
   return nil
 end
 
+-- Remove only a user-installed skin.  Bundled skins are shipped with the
+-- game and intentionally have no delete affordance.
+function TouchSkin.remove(id)
+  local entry = TouchSkin.find(id)
+  if not entry then return nil, "no skin " .. tostring(id) end
+  if entry.source ~= "user" then return nil, "bundled skins cannot be deleted" end
+  if not (love and love.filesystem and love.filesystem.remove) then
+    return nil, "no writable filesystem"
+  end
+  local function removeTree(path)
+    if isDir(path) and love.filesystem.getDirectoryItems then
+      for _, name in ipairs(love.filesystem.getDirectoryItems(path)) do
+        local ok, err = removeTree(path .. "/" .. name)
+        if not ok then return nil, err end
+      end
+    end
+    local ok, err = love.filesystem.remove(path)
+    return ok and true or nil, err
+  end
+  return removeTree(entry.archive or (TouchSkin.USER_ROOT .. "/" .. entry.id))
+end
+
 function TouchSkin.assetPaths(skin)
   local out, seen = {}, {}
   local function add(rel)
@@ -886,7 +919,6 @@ function TouchSkin.toRetroArchConfig(skin)
     if page.viewport then
       out[#out + 1] = p .. "_viewport = " .. fmtRect(page.viewport)
       if page.viewportFill then out[#out + 1] = p .. "_viewport_fill = true" end
-      if page.viewportExpand then out[#out + 1] = p .. "_viewport_expand = true" end
     end
     local controls = {}
     for _, ctl in ipairs(page.controls or {}) do
@@ -1284,7 +1316,7 @@ function TouchSkin.pageBox(page, w, h, ox, oy)
   -- full_screen means "relative to the window, not the game viewport".
   -- When the cfg also names an aspect_ratio, that window is then fitted
   -- to the overlay's design aspect so buttons do not stretch.  #1503
-  local fit = ((not page.fullScreen) or page.aspectFromCfg)
+  local fit = ((not page.fullScreen) or page.aspectFromCfg or page.aspectFromImage)
     and page.aspect and page.aspect > 0 and h > 0
   if fit then
     local displayAspect = w / h
@@ -1306,6 +1338,11 @@ function TouchSkin.pageBox(page, w, h, ox, oy)
         by = oy + extra
       elseif anchor == "top" then
         by = oy
+      elseif page.aspect < 1 then
+        -- A portrait bezel with controls is a controller deck.  On an
+        -- unusually tall display, pin the deck to the lower edge and leave
+        -- the additional room for the game above it.
+        by = oy + extra
       else
         by = oy + extra * 0.5
       end
@@ -1359,8 +1396,10 @@ function TouchSkin.decorativeOnly()
 end
 
 function TouchSkin.drawable()
-  if not TouchSkin.active then return false end
+  -- A selected skin is a presentation choice, not a mobile-only input mode.
-  return TouchSkin.overlayLive or TouchSkin.decorativeOnly()
+  -- Its artwork and screen placement therefore belong on every platform;
+  -- `overlayLive` still controls whether touch input is available.
+  return TouchSkin.active ~= nil
 end
 
 function TouchSkin.hasViewport()
@@ -1391,6 +1430,16 @@ local function remainderBox(ox, oy, w, h, bx, by, bw, bh)
   return best[1], best[2], best[3], best[4]
 end
 
+-- The deck box pinned to the lower edge (see pageBox) leaves room above it
+-- that belongs to the game, so a screen rect flush with the top of the deck
+-- grows into it instead of showing a black band.
+local function deckHeadroom(y, vh, by, bh, oy, h)
+  if by <= oy + 0.5 then return y, vh end
+  if by + bh < oy + h - 0.5 then return y, vh end
+  if y - by > math.max(2, bh * 0.01) then return y, vh end
+  return oy, vh + (y - oy)
+end
+
 function TouchSkin.pageViewport(page, w, h, ox, oy)
   if not page then return nil end
   ox, oy = ox or 0, oy or 0
@@ -1400,16 +1449,27 @@ function TouchSkin.pageViewport(page, w, h, ox, oy)
     local x, y = bx + v.x * bw, by + v.y * bh
     local vw, vh = v.w * bw, v.h * bh
     if vw <= 0 or vh <= 0 then return nil end
-    return x, y, vw, vh, page.viewportFill == true, page.viewportExpand == true
+    y, vh = deckHeadroom(y, vh, by, bh, oy, h)
+    return x, y, vw, vh, page.viewportFill == true
   end
   if page.screenFit == "remainder" then
     local x, y, vw, vh = remainderBox(ox, oy, w, h, bx, by, bw, bh)
     if not x then return nil end
-    return x, y, vw, vh, false, false
+    return x, y, vw, vh, false
   end
   return nil
 end
 
+-- Centre of the page's screen cutout.  The renderer fits the 160x144
+-- picture into that rect; this helper is for the studio preview.
+function TouchSkin.screenCenter(w, h, ox, oy, page)
+  page = page or TouchSkin.page()
+  if not page then return nil end
+  local x, y, vw, vh = TouchSkin.pageViewport(page, w, h, ox, oy)
+  if not x then return nil end
+  return x + vw * 0.5, y + vh * 0.5
+end
+
 function TouchSkin.viewport(w, h, ox, oy)
   local page = TouchSkin.page()
   if not page or not TouchSkin.drawable() then return nil end

src/core/gen2/ItemEffects.lua

@@ -240,6 +240,8 @@ local function rareCandy(mon, data)
     used = true,
     level = newLevel,
     learned = learned,
+    -- data/text/common_1.asm:86
+    sfx = "Sfx_DexFanfare5079",
     text = ("%s grew to\nlevel %d!"):format(monName(mon), newLevel),
   }
 end

src/import/CacheFs.lua

@@ -287,6 +287,43 @@ function CacheFs.write(rel, data)
   return love.filesystem.write(rel, data)
 end
 
+-- Open a cache-relative file for streaming replacement. The returned handle
+-- has write(bytes) and close() methods and follows the same portable/save-dir
+-- routing as CacheFs.write without forcing the caller to hold the whole file
+-- in one Lua string.
+function CacheFs.openWrite(rel)
+  rel = withPrefix(rel)
+  local root = CacheFs.root()
+  if root then
+    ensureParents(root, rel)
+    local f, err = io.open(realPath(root, rel), "wb")
+    if not f then return nil, err end
+    return {
+      write = function(_, data)
+        local ok, writeErr = f:write(data)
+        if not ok then return nil, writeErr end
+        return true
+      end,
+      close = function() f:close() end,
+    }
+  end
+  if not (love and love.filesystem and love.filesystem.newFile) then
+    return nil, "streaming cache writes are unavailable"
+  end
+  local parent = rel:match("^(.*)/[^/]+$")
+  if parent and not love.filesystem.createDirectory(parent) then
+    local info = love.filesystem.getInfo(parent)
+    local reason = info and ("a " .. info.type .. " already exists there")
+      or "unknown reason"
+    return nil, "could not create " .. parent .. ": " .. reason
+  end
+  local file, makeErr = love.filesystem.newFile(rel)
+  if not file then return nil, makeErr or "could not create cache file" end
+  local ok, openErr = file:open("w")
+  if not ok then return nil, openErr or "could not open cache file" end
+  return file
+end
+
 -- read cache-relative `rel`; returns the bytes or nil
 function CacheFs.read(rel)
   rel = withPrefix(rel)
@@ -577,14 +614,18 @@ function CacheFs.mountVersion(version)
   return true
 end
 
--- Undo mountVersion.  A process normally mounts exactly one version and then
+-- Undo mountVersion in LIFO order relative to mountVersion: generated-tree
--- boots it, but the launcher can open the save editor on one game's save,
+-- overlays first (assets, then data -- reverse of mountGeneratedTrees), then
--- close it, and press Play on another: with the first version's subtree
+-- the version folder.  PHYSFS resolves by stack order; peeling the wrong
--- still prepended, the other's require("data.generated.*") and generated
+-- layer first can leave another version's generated files winning a name.
--- art would silently resolve to the first game's files.  Callers must also
+--
--- drop the generated modules from package.loaded
+-- A process normally mounts exactly one version and then boots it, but the
--- (src.core.Data:unloadGenerated) -- unmounting alone only fixes the read
+-- launcher can open the save editor on one game's save, close it, and press
--- path, not what require already cached.
+-- Play on another: with the first version's subtree still prepended, the
+-- other's require("data.generated.*") and generated art would silently
+-- resolve to the first game's files.  Callers must also drop the generated
+-- modules from package.loaded (src.core.Data:unloadGenerated) -- unmounting
+-- alone only fixes the read path, not what require already cached.
 --
 -- Returns true when nothing was mounted or the unmount took.
 function CacheFs.unmountVersion(version)
@@ -596,6 +637,16 @@ function CacheFs.unmountVersion(version)
     base = love.filesystem.getSaveDirectory()
   end
   local done = false
+  -- LIFO vs mountGeneratedTrees: assets/generated, then data/generated.
+  if love.filesystem and love.filesystem.unmount then
+    local generated = {
+      prefix .. "assets/generated",
+      prefix .. "data/generated",
+    }
+    for _, src in ipairs(generated) do
+      done = love.filesystem.unmount(src) or done
+    end
+  end
   local fn = resolveUnmount()
   if fn and base then
     done = fn(base .. SEP .. sub) or done

src/import/ImageWriter.lua

@@ -125,6 +125,26 @@ function ImageWriter.columnsToRows(raw, tilesWide, tilesHigh, bytesPerTile)
   return out
 end
 
+-- Inverse of pret tools/gfx --interleave (pokecrystal tools/gfx.c).
+-- Build-time interleave stores each vertical 8x16 pair as consecutive 8x8
+-- tiles for OBJ mode; this restores row-major sheet order for PNGs.
+function ImageWriter.deinterleave(raw, width, bytesPerTile)
+  bytesPerTile = bytesPerTile or 16
+  local widthTiles = width / 8
+  local numTiles = #raw / bytesPerTile
+  local out = {}
+  for i = 0, numTiles - 1 do
+    local row = math.floor(i / widthTiles)
+    local src = i * 2 - (row % 2 == 1
+      and widthTiles * (row + 1) - 1
+      or widthTiles * row)
+    for offset = 1, bytesPerTile do
+      out[i * bytesPerTile + offset] = raw[src * bytesPerTile + offset]
+    end
+  end
+  return out
+end
+
 function ImageWriter.save(image, path)
   local ok, fileData = pcall(image.encode, image, "png")
   if not ok then error("could not encode " .. path .. ": " .. tostring(fileData)) end

src/import/LauncherSettings.lua

@@ -6,8 +6,8 @@
 -- options.lua table (src/core/SaveData.loadOptions/saveOptions) and lets the
 -- next boot's applyOptions pick the values up.  Every ladder mirrors
 -- OptionsMenu's semantics and stored values; when editing one, keep the two
--- in sync.  ZOOM is deliberately absent: its range depends on the live
+-- in sync.  ZOOM uses the live window's integer fit (same 160×144 rule as
--- renderer's fit scale (Renderer:fitScale), which does not exist here.
+-- Renderer:fitScale) so the row can offer OUT/FIT/IN without a running game.
 --
 -- Rows are the same descriptor idiom OptionRows draws in game:
 --   { label, value = fn() -> string, step = fn(dir) -> changed,
@@ -278,6 +278,16 @@ local function coreRows(opts, hooks)
       end)
   end
 
+  local okZ, Zoom = pcall(require, "src.render.Zoom")
+  if okZ then
+    add(Strings("ZOOM"),
+      function() return Zoom.offsetLabel(opts.zoom or 0) end,
+      function(dir)
+        Zoom.nudgeOptions(opts, dir, Zoom.windowFitScale())
+        return true
+      end)
+  end
+
   local okTile, TileRenderer = pcall(require, "src.render.TileRenderer")
   if okTile and TileRenderer.VOID_FILLS then
     add(Strings("VOID FILL"),
@@ -303,15 +313,12 @@ local function coreRows(opts, hooks)
       end)
   end
 
-  -- ORIENTATION (#592): Android only -- the lock rides SDL's orientation
+  -- ORIENTATION (#592, #1638): mobile only.  Unlike the other launcher rows
-  -- hint, which iOS reads only at startup (the Info.plist governs there) and
+  -- this one live-applies: the window exists here too, and rotating under
-  -- desktop ignores.  Unlike the other launcher rows this one live-applies:
+  -- the player's finger is the only feedback that reads.
-  -- the window exists here too, and rotating under the player's finger is
-  -- the only feedback that reads.
   do
-    local osName = love.system and love.system.getOS and love.system.getOS()
     local okOr, Orientation = pcall(require, "src.core.Orientation")
-    if okOr and osName == "Android" then
+    if okOr and (Orientation.isAndroid() or Orientation.isIOS()) then
       add(Strings("ORIENTATION"),
         function() return Strings(Orientation.modeLabel(opts.orientation)) end,
         function(dir)
@@ -646,6 +653,16 @@ local function gen2Rows(opts, hooks)
       end)
   end
 
+  local okZ, Zoom = pcall(require, "src.render.Zoom")
+  if okZ then
+    add(Strings("ZOOM"),
+      function() return Zoom.offsetLabel(opts.zoom or 0) end,
+      function(dir)
+        Zoom.nudgeOptions(opts, dir, Zoom.windowFitScale())
+        return true
+      end)
+  end
+
   local okFill, BorderFill = pcall(require, "src.world.gen2.BorderFill")
   if okFill and BorderFill.VOID_FILLS then
     add(Strings("VOID FILL"),

src/import/LauncherView.lua

@@ -753,12 +753,15 @@ local function cartridgeButton(imp, x, y, w, h, key, version, gameName, action)
     -- and one below the top-right corner notch, like the DMG cart.
     local grooveW = w * 0.115
     local grooveH = math.max(1, h * 0.009)
+    local grooveScale = { 1.22, 1.10, 1.00, 1.00, 1.10, 1.22 }
+    local grooveInset = w * 0.02
     for i = 0, 5 do
       local ry = mainTop + h * 0.014 + i * h * 0.021
-      cartPolygon(cartQuad(project, -halfW + w * 0.02, ry,
+      local gw = grooveW * grooveScale[i + 1]
-        grooveW, grooveH, faceZ), side, 0.7)
+      cartPolygon(cartQuad(project, -halfW + grooveInset, ry,
-      cartPolygon(cartQuad(project, halfW - grooveW - w * 0.02, ry,
+        gw, grooveH, faceZ), side, 0.7)
-        grooveW, grooveH, faceZ), side, 0.7)
+      cartPolygon(cartQuad(project, halfW - gw - grooveInset, ry,
+        gw, grooveH, faceZ), side, 0.7)
     end
     -- The thin diagonal mold ridge cut into each long side a little below
     -- the grip grooves, mirrored left/right.
@@ -774,12 +777,14 @@ local function cartridgeButton(imp, x, y, w, h, key, version, gameName, action)
         { project(x1 + nx * t, y1 + ny * t, faceZ) },
       }, side, 0.7)
     end
-    local dgY = mainTop + h * 0.20
+    local dgY = mainTop + h * 0.25
     diagonal(-halfW + w * 0.006, dgY, -halfW + w * 0.085, dgY + h * 0.038)
     diagonal(halfW - w * 0.006, dgY, halfW - w * 0.085, dgY + h * 0.038)
-    -- The Nintendo GAME BOY recess: one stadium pill sunk into the shell.
+    -- The pill recess: one stadium pill sunk into the shell.
-    local pillX, pillW = -halfW + w * 0.17, w * 0.62
+    local pillX, pillW = -halfW + w * 0.19, w * 0.62
-    local pillY, pillH = mainTop + h * 0.024, h * 0.115
+    local pillY, pillH = mainTop + h * 0.015, h * 0.115
+    -- log out pillH
+ 
     cartPill(project, pillX, pillY, pillW, pillH, faceZ + 0.5, side, 0.55)
     local inX, inY = w * 0.008, h * 0.008
     cartPill(project, pillX + inX, pillY + inY,
@@ -1062,9 +1067,22 @@ local GAME_TABS = {
 local HEADER_TABS = {
   { id = "mods",   key = "tab-mods" },
   { id = "find",   key = "tab-find" },
-  { id = "skins",  key = "tab-skins", glyph = true },
+  { id = "skins",  key = "tab-skins", glyph = true, beta = true },
   { id = "bug",    key = "tab-bug" },
 }
+
+local BETA_TAG_OPTS = { fill = true, bold = true, ink = PAL.inverse }
+
+local function drawBetaTag(x, y, w, h)
+  Kit.tag(x, y, w, h, "BETA", PAL.yellow, BETA_TAG_OPTS)
+end
+
+local function overlayBeta(tx, ty, w, tabH, m)
+  local bh = math.floor(11 * m.s)
+  local bw = math.min(w, Kit.textWidth("micro", "BETA") + math.floor(10 * m.s))
+  drawBetaTag(tx + (w - bw) / 2, ty + tabH - bh - math.floor(2 * m.s), bw, bh)
+end
+
 for _, t in ipairs(HEADER_TABS) do
   t.opts = { face = "tab", font = "tab", color = t.color, letter = t.letter }
   if t.glyph then
@@ -1268,6 +1286,7 @@ local function buildHeader(imp, m)
     o.image = t.icon
     o.action = chrome.tab[t.id]
     btn(imp, tx, ty, w, tabH, t.key, "", o)
+    if t.beta then overlayBeta(tx, ty, w, tabH, m) end
     tx = tx + w + tabGap
   end
   -- The bug-report chip sits LAST, past the sync chip.
@@ -1285,10 +1304,7 @@ local function buildHeader(imp, m)
     local o = chrome.sync
     o.active = imp._syncModal ~= nil
     btn(imp, tx, ty, w, tabH, "tab-sync", "", o)
-    local bh = math.floor(11 * m.s)
+    overlayBeta(tx, ty, w, tabH, m)
-    local bw = math.min(w, Kit.textWidth("micro", "BETA") + math.floor(10 * m.s))
-    Kit.tag(tx + (w - bw) / 2, ty + tabH - bh - math.floor(2 * m.s), bw, bh,
-      "BETA", o.active and PAL.inverse or PAL.yellow)
     local eng = imp._sync
     if eng and eng.busy and eng:busy() then
       Kit.spinner(tx + w - math.floor(8 * m.s), ty + math.floor(8 * m.s),
@@ -1304,7 +1320,7 @@ local function buildHeader(imp, m)
   return y + math.floor(10 * m.s)
 end
 
--- The state of the self-updater, as a top-right control.
+-- The state of the self-updater, shown in the launcher footer.
 -- Returns status, label, action, glow.
 function LauncherView._updateControl(imp)
   if not imp.Check then return nil end
@@ -2142,16 +2158,20 @@ local function buildModsPanel(imp, x, y, w, availH, m)
     + math.floor(8 * m.s)
   local listTop = cy
 
-  -- One continuous list: every row is laid out, the region scroll moves
+  -- One continuous list: derive the rows that can touch the viewport before
-  -- through all of it, and only rows inside the region's viewport draw --
+  -- entering the loop. Drawing was already culled, but scanning every
-  -- so the per-frame cost stays bounded by the window, not the list.
+  -- installed row to discover that defeats the point on a large mod library.
   local view = imp._tabRegionRect
   local viewTop = view and view.y or listTop
   local viewBot = view and (view.y + view.h) or (listTop + availH)
-  for i = 1, #mods do
+  local stride = rowH + gap
+  local first = math.max(1,
+    math.ceil((viewTop - rowH - listTop) / stride) + 1)
+  local last = math.min(#mods,
+    math.floor((viewBot - listTop) / stride) + 1)
+  for i = first, last do
     local mod = mods[i]
     local ry = listTop + (i - 1) * (rowH + gap)
-    if ry + rowH >= viewTop and ry <= viewBot then
     local rowKey = rowKeyFor(imp, "mod-row-", mod.id)
     local isFullyDisabled = true
     if mod.enabledByVersion then
@@ -2261,7 +2281,6 @@ local function buildModsPanel(imp, x, y, w, availH, m)
         px, ly, PAL.detail)
     end
   end
-  end
 
   local contentH = #mods * rowH + (#mods - 1) * gap
   return (listTop + contentH + gap) - y
@@ -2269,8 +2288,8 @@ end
 
 -- ---------------------------------------------------------- find mods panel
 
--- SKINS tab: pick the on-screen skin, import one, or open the desktop studio.
+-- SKINS tab: pick the on-screen skin, import one, or open Skin Studio.
-local function buildSkinsPanel(imp, x, y, w, availH, m)
+local function buildSkinsPanelLegacy(imp, x, y, w, availH, m)
   local skins = imp:_ensureSkins()
   local active = imp:_activeSkin()
   local gap = m.gap
@@ -2324,7 +2343,7 @@ local function buildSkinsPanel(imp, x, y, w, availH, m)
   end
   cy = cy + urlH + math.floor(8 * m.s)
 
-  -- Studio button.  Desktop only: the host supplies the hook nowhere else.
+  -- The Studio reflows to a touch-first canvas plus inspector on phones.
   if imp.onOpenSkinStudio then
     local label = Strings("Open Skin Studio")
     local bw = math.min(w, Kit.textWidth("small", label) + math.floor(40 * m.s))
@@ -2344,6 +2363,64 @@ local function buildSkinsPanel(imp, x, y, w, availH, m)
   Kit.caption(x, cy, Strings("INSTALLED"))
   cy = cy + Kit.textHeight("small") + math.floor(6 * m.s)
 
+  -- Keep the actionable list below for detailed metadata and exports, but
+  -- lead with a visual picker: skins are much easier to recognize by their
+  -- bezel than by a folder name.  Cards use the same loaded art that the
+  -- runtime draws, so they cannot drift from the selected skin.
+  local previewGap = math.floor(8 * m.s)
+  local previewCols = w >= math.floor(420 * m.s) and 2 or 1
+  local previewW = (w - previewGap * (previewCols - 1)) / previewCols
+  local previewH = math.max(108 * m.s, Kit.tapMin() * 2)
+  local previewCount = #skins
+  for i, entry in ipairs(skins) do
+    local n = i - 1
+    local px = x + (n % previewCols) * (previewW + previewGap)
+    local py = cy + math.floor(n / previewCols) * (previewH + previewGap)
+    local key = "skin-preview-" .. entry.id
+    local selected = active == entry.id
+    local focused = Kit.focusable(key, px, py, previewW, previewH)
+    Kit.card(px, py, previewW, previewH, selected and "selected"
+      or (focused or Kit.hover(px, py, previewW, previewH)))
+    local pad = math.floor(8 * m.s)
+    local artH = math.floor(previewH * 0.60)
+    Theme.fillRounded(px + pad, py + pad, previewW - pad * 2, artH,
+      PAL.bg, 1, Theme.cardRadius() * 0.6)
+    local art = entry.preview
+    if art and art.getDimensions then
+      local iw, ih = art:getDimensions()
+      if iw > 0 and ih > 0 then
+        local scale = math.min((previewW - pad * 4) / iw, (artH - pad * 2) / ih)
+        love.graphics.setColor(1, 1, 1, 1)
+        love.graphics.draw(art, px + (previewW - iw * scale) * 0.5,
+          py + pad + (artH - ih * scale) * 0.5, 0, scale, scale)
+      end
+    else
+      Theme.strokeRounded(px + previewW * 0.23, py + pad + artH * 0.15,
+        previewW * 0.54, artH * 0.42, PAL.line, Theme.A.hairline, 1, 2)
+      Theme.fillRounded(px + previewW * 0.20, py + pad + artH * 0.64,
+        previewW * 0.22, artH * 0.17, PAL.steel, 0.75, 3)
+      Theme.fillRounded(px + previewW * 0.60, py + pad + artH * 0.61,
+        previewW * 0.12, artH * 0.22, PAL.steel, 0.75, artH * 0.11)
+      Theme.fillRounded(px + previewW * 0.75, py + pad + artH * 0.56,
+        previewW * 0.12, artH * 0.22, PAL.steel, 0.75, artH * 0.11)
+    end
+    Kit.text("mono", Kit.ellipsize("mono", entry.id, previewW - pad * 2),
+      px + pad, py + pad + artH + math.floor(5 * m.s),
+      selected and PAL.green or PAL.heading)
+    if selected then
+      Kit.text("micro", Strings("IN USE"), px + pad,
+        py + previewH - pad - Kit.textHeight("micro"), PAL.green)
+    end
+    if Kit.press(px, py, previewW, previewH) or Kit._activateId == key then
+      queueAction(imp, key, function() imp:_useSkin(entry.id) end)
+    end
+  end
+  if previewCount > 0 then
+    cy = cy + math.ceil(previewCount / previewCols) * previewH
+      + math.max(0, math.ceil(previewCount / previewCols) - 1) * previewGap
+      + gap
+  end
+
   local rowH = math.max(Kit.tapMin(), math.floor(44 * m.s))
   imp._skinGear = imp._skinGear
     or love.graphics.newImage("assets/launcher/gear.png")
@@ -2457,6 +2534,69 @@ local function buildSkinsPanel(imp, x, y, w, availH, m)
   return cy + hintH - y
 end
 
+-- The launcher is the short path: bring a skin in, see what is enabled, or
+-- turn skin use off.  Browsing, pagination and per-skin editing/export live
+-- together in My Skins, where they are useful instead of competing here.
+local function buildSkinsPanel(imp, x, y, w, availH, m)
+  local cy, gap, bh = y, m.gap, m.btnH
+  local active = imp:_activeSkin()
+
+  Kit.text("button", Strings("Skins"), x, cy, PAL.heading)
+  local importW = math.min(w * 0.46,
+    Kit.textWidth("small", imp:_skinsImportButtonLabel()) + math.floor(24 * m.s))
+  btn(imp, x + w - importW, cy, importW, bh, "skins-import",
+    imp:_skinsImportButtonLabel(), { kind = "accent", font = "small",
+      action = function() imp:chooseSkin() end })
+  cy = cy + bh + gap
+
+  if imp._skinNotice then
+    cy = cy + Kit.textWrapped("small", imp._skinNotice.text, x, cy, w,
+      imp._skinNotice.ok and PAL.green or PAL.red, 2) + gap
+  end
+
+  local addW = Kit.textWidth("small", Strings("Add")) + math.floor(24 * m.s)
+  if imp._skinFetch then
+    Loader.inline(x, cy, w, bh, Strings("Downloading %s...",
+      tostring(imp._skinFetch.name or "")))
+  else
+    btn(imp, x + w - addW, cy, addW, bh, "skins-url-add", Strings("Add"), {
+      kind = "accent", font = "small", action = function() imp:_addSkinFromUrl() end })
+    textField(imp, x, cy, w - addW - gap, bh, "skins-url", imp.skinUrl or "",
+      Strings("Paste a skin link (.zip, .cfg, .deltaskin)"),
+      imp._skinUrlFocus == true, function() imp:_toggleSkinUrlFocus() end)
+  end
+  cy = cy + bh + gap
+
+  local currentH = active and (bh * 2 + gap * 2) or (bh + gap * 2)
+  Kit.card(x, cy, w, currentH)
+  Kit.caption(x + gap, cy + gap, "CURRENT SKIN")
+  local current = active and tostring(active) or Strings("No skin enabled")
+  Kit.text("mono", Kit.ellipsize("mono", current, w - gap * 2), x + gap,
+    cy + gap + Kit.textHeight("small") + math.floor(4 * m.s),
+    active and PAL.green or PAL.muted)
+  local buttonY = cy + bh + gap
+  local half = (w - gap * 3) * 0.5
+  if active then
+    btn(imp, x + gap, buttonY, half, bh, "skins-export-current",
+      Strings("Export current"), { font = "small",
+        action = function() imp:_exportSkin(active, "native") end })
+    btn(imp, x + gap * 2 + half, buttonY, half, bh, "skins-off",
+      Strings("Turn skins off"), { kind = "danger", font = "small",
+        action = function() imp:_disableSkins() end })
+  end
+  cy = cy + currentH + gap
+
+  if imp.onOpenSkinStudio then
+    btn(imp, x, cy, w, bh, "skins-my-skins", Strings("My Skins"), {
+      kind = "accent", font = "small",
+      action = function() imp.onOpenSkinStudio(imp.modScope or "red", active) end })
+    cy = cy + bh + gap
+  end
+  Kit.textWrapped("small", Strings("Import from a file or link, then manage, edit and export individual skins in My Skins."),
+    x, cy, w, PAL.muted, 3)
+  return cy + Kit.wrapHeight("small", Strings("Import from a file or link, then manage, edit and export individual skins in My Skins."), w, 3) - y
+end
+
 local function buildBugPanel(imp, x, y, w, availH, m)
   local SaveData = require("src.core.SaveData")
   local gap = m.gap
@@ -3017,9 +3157,13 @@ local function buildTextModal(imp, m, key, title, body, closeFn)
   local h = math.floor(math.min(m.H - 2 * m.pad, 460 * m.s))
   local px, py, pw, ph = modalPanel(m, w, h)
   local cy = py + pad
-  Kit.text("button", Kit.ellipsize("button", title, pw - 2 * pad),
+  local xW = math.max(Kit.tapMin(), math.floor(30 * m.s))
+  Kit.text("button", Kit.ellipsize("button", title,
+    pw - 2 * pad - xW - math.floor(8 * m.s)),
     px + pad, cy, PAL.heading)
-  cy = cy + Kit.textHeight("button") + math.floor(10 * m.s)
+  btn(imp, px + pw - pad - xW, cy, xW, xW, key .. "-x", "X",
+    { font = "small", action = closeFn })
+  cy = cy + math.max(Kit.textHeight("button"), xW) + math.floor(10 * m.s)
 
   local pagerH = math.max(Kit.tapMin(), math.floor(30 * m.s))
   local bodyH = (py + ph - pad) - cy - m.btnH - math.floor(10 * m.s)
@@ -4357,8 +4501,8 @@ local function syncTitle(imp, m, px, py, pw, pad)
   Kit.text("button", label, px + pad, py, PAL.heading)
   local bh = math.floor(15 * m.s)
   local bw = Kit.textWidth("micro", "BETA") + math.floor(14 * m.s)
-  Kit.tag(px + pad + Kit.textWidth("button", label) + math.floor(8 * m.s),
+  drawBetaTag(px + pad + Kit.textWidth("button", label) + math.floor(8 * m.s),
-    py + (Kit.textHeight("button") - bh) / 2, bw, bh, "BETA", PAL.yellow)
+    py + (Kit.textHeight("button") - bh) / 2, bw, bh)
   return py + Kit.textHeight("button") + math.floor(12 * m.s)
 end
 
@@ -5071,6 +5215,7 @@ function LauncherView.draw(imp)
   -- whole stage draws shielded (no clicks, no hover, no focus ring) while
   -- one is up; buildModals lowers the shield for the modal's own controls.
   imp._modalUpNow = modalUp(imp)
+  if imp._modalUpNow then imp:_blurPanelFields() end
   Kit.blockClicks = imp._modalUpNow
 
   local step = Kit.scrollStep(m.s)

src/import/RomExtractorGen2.lua

@@ -27,7 +27,7 @@ RomExtractorGen2.__index = RomExtractorGen2
 -- scripts, pokemon, moves, items, marts, encounters, trainers, pokedex,
 -- landmarks, intro movie, menu gfx, title, credits, diploma, trade animation,
 -- audio, stubs
-local STAGE_COUNT = 26
+local STAGE_COUNT = 27
 local Opcodes = require("src.script.gen2.Opcodes")
 
 -- BG palette slots inside one loaded 8-palette set (constants/tileset_constants.asm
@@ -136,6 +136,18 @@ local TEXT_NO_GLYPH = {
   [0x13] = true, [0x15] = true,
 }
 
+-- The three runtime name slots.  PlaceMoveUsersName, PlaceMoveTargetsName and
+-- PlaceEnemysName (home/text.asm:302, :307, :327) swap these for a battler's
+-- own name as the line prints, so they are markers rather than glyphs.  They
+-- decode to the same shape Gen 1 uses, which src/core/RomText.lua already
+-- fills in argument order.  Dropped, SubTookDamageText read "took damage
+-- for" with nothing after it.
+local NAME_SLOT = {
+  ["<USER>"] = "{USER}",
+  ["<TARGET>"] = "{TARGET}",
+  ["<ENEMY>"] = "{ENEMY}",
+}
+
 local ROOF_TILES = 9
 local SPRITEDATA_LENGTH = 6
 
@@ -2596,6 +2608,8 @@ function RomExtractorGen2:decodeGen2Text(bank, address, charmap, buffers)
         out[#out + 1] = ch
       elseif ch == "<……>" or b == 0x56 then
         out[#out + 1] = "……"
+      elseif NAME_SLOT[ch] then
+        out[#out + 1] = NAME_SLOT[ch]
       elseif not ch then
         out[#out + 1] = ("{BYTE:%02X}"):format(b)
       end
@@ -3698,6 +3712,37 @@ function RomExtractorGen2:splashGfx()
   }
 end
 
+-- The engine's own strings, keyed by the label the disassembly gives them.
+--
+-- This is what extractOakSpeech has always done for _OakText1-7: resolve the
+-- label, decode from the cart, key by name.  What is new is that the list of
+-- labels comes from the manifest instead of being written out here, so all of
+-- data/text/ arrives rather than seven strings.  Gen 1 has had the same table
+-- since RomExtractor:extractText; this is the Gen 2 side of it, and it is
+-- what lets src/core/RomText.lua work on Gold and Silver at all.
+--
+-- Written as `rom_text` rather than `text`: data/generated/text.lua is
+-- already the script text, keyed by bank:address for the overworld VM, and
+-- these are a different table with different keys.
+function RomExtractorGen2:extractText()
+  self:beginStage("Dialogue")
+  local charmap = self.manifest.charmap or {}
+  local labels = (self.manifest.text or {}).labels or {}
+  local texts = {}
+  for index, label in ipairs(labels) do
+    local location = self.symbols[label]
+    -- A label the manifest names but the symbol table does not carry would
+    -- be a generator bug, not a cart difference: make_gold_manifest.py
+    -- resolves every one of these before it writes the list.
+    if location then
+      texts[label] = self:decodeGen2Text(location[1], location[2], charmap)
+    end
+    self:tick("Dialogue", index, #labels)
+  end
+  self:write("rom_text", texts)
+  return texts
+end
+
 -- OakSpeech (engine/menus/intro_menu.asm): named _OakText* strings plus the
 -- POKEMON_PROF / CAL trainer pics shown before NamePlayer.  Also pulls
 -- Shrink1/2 pics and the GameFreak splash sheets for the boot cinema.
@@ -5151,6 +5196,7 @@ function RomExtractorGen2:extractMenuGfx()
   }
   out.pack = pack
   out.pokedex = self:pokedexGfx()
+  out.billsPc = self:billsPcGfx()
   out.pokegear = self:pokegearGfx()
   out.trainerCard = self:trainerCardGfx()
   out.unownPuzzle = self:unownPuzzleGfx()
@@ -5258,80 +5304,213 @@ function RomExtractorGen2:extractMenuGfx()
   end
 
   -- Goldenrod Game Corner: Slot Machine graphics assets
+  local CacheFs = require("src.import.CacheFs")
+  local function packBytes(bytes)
+    local chars = {}
+    for i = 1, #bytes do chars[i] = string.char(bytes[i]) end
+    return table.concat(chars)
+  end
+  local function writeRaw(relative, bytes)
+    local ok, writeError = CacheFs.write(
+      "assets/generated/" .. relative, packBytes(bytes))
+    if not ok then
+      error("could not write " .. relative .. ": " .. tostring(writeError))
+    end
+  end
+
+  -- Canonical sheet sizes match the cart art the UI indexes (and pret's
+  -- gfx/slots + gfx/card_flip PNGs).  ROM LZ streams are those sheets after
+  -- Makefile gfx transforms; reverse what the decompressed bytes still carry.
+  local SLOTS1_W, SLOTS1_H = 16, 152
+  local SLOTS2_W, SLOTS2_H = 16, 256
+  local SLOTS3_W, SLOTS3_H = 24, 240
+  local CARD1_W, CARD1_H = 128, 32
+  local CARD2_W, CARD2_H = 24, 160
+  local CARD3_W, CARD3_H = 8, 56
+
+  local function pad2bpp(raw, width, height)
+    local need = width * height / 4
+    while #raw < need do raw[#raw + 1] = 0 end
+    while #raw > need do table.remove(raw) end
+    return raw
+  end
+
+  local function writeSheet(raw, width, height, relative, transparent)
+    self:write2bpp(pad2bpp(raw, width, height), width, height, relative,
+      transparent)
+  end
+
+  -- Slots3LZ is unique 8x16 OBJ columns (interleave + remove-duplicates +
+  -- remove-xflip).  Rebuild the 24x240 actor sheet the UI quads expect from
+  -- OAMData_SlotsGolem / Chansey* / Egg (data/sprite_anims/oam.asm), same
+  -- pattern as title-screen Ho-Oh frame composition above.
+  local function composeSlotsActors(raw)
+    local tileCount = math.floor(#raw / 16)
+    local tiles = {}
+    for index = 0, tileCount - 1 do
+      local one = {}
+      for b = 1, 16 do one[b] = raw[index * 16 + b] or 0 end
+      tiles[index] = ImageWriter.decode2bpp(one, 8, 8, true)
+    end
+    local sheet = ImageWriter.blank(SLOTS3_W, SLOTS3_H, 1, 1, 1, 0)
+    local function blit8x16(tileId, dx, dy, flipX)
+      local top, bot = tiles[tileId], tiles[tileId + 1]
+      if not (top and bot) then return end
+      ImageWriter.blit(sheet, top, dx, dy, 0, 0, 8, 8, flipX)
+      ImageWriter.blit(sheet, bot, dx, dy + 8, 0, 0, 8, 8, flipX)
+    end
+    local function blitPose(poseY, base, entries)
+      for _, e in ipairs(entries) do
+        blit8x16(base + e.t, (e.x + 2) * 8, poseY + (e.y + 2) * 8, e.xf)
+      end
+    end
+    local golem = {
+      { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+      { x = 0, y = -2, t = 0x00, xf = true },
+      { x = -2, y = 0, t = 0x04 }, { x = -1, y = 0, t = 0x06 },
+      { x = 0, y = 0, t = 0x04, xf = true },
+    }
+    local chansey = {
+      {
+        { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+        { x = 0, y = -2, t = 0x04 },
+        { x = -2, y = 0, t = 0x06 }, { x = -1, y = 0, t = 0x08 },
+        { x = 0, y = 0, t = 0x0a },
+      },
+      {
+        { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+        { x = 0, y = -2, t = 0x04 },
+        { x = -2, y = 0, t = 0x0c }, { x = -1, y = 0, t = 0x0e },
+        { x = 0, y = 0, t = 0x10 },
+      },
+      {
+        { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+        { x = 0, y = -2, t = 0x04 },
+        { x = -2, y = 0, t = 0x12 }, { x = -1, y = 0, t = 0x14 },
+        { x = 0, y = 0, t = 0x16 },
+      },
+      {
+        { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+        { x = 0, y = -2, t = 0x04 },
+        { x = -2, y = 0, t = 0x18 }, { x = -1, y = 0, t = 0x1a },
+        { x = 0, y = 0, t = 0x1c },
+      },
+      {
+        { x = -2, y = -2, t = 0x1e }, { x = -1, y = -2, t = 0x20 },
+        { x = 0, y = -2, t = 0x22 },
+        { x = -2, y = 0, t = 0x24 }, { x = -1, y = 0, t = 0x26 },
+        { x = 0, y = 0, t = 0x28 },
+      },
+    }
+    blitPose(0, 0x00, golem)
+    blitPose(32, 0x08, golem)
+    for index, frame in ipairs(chansey) do
+      blitPose(32 + index * 32, 0x10, frame)
+    end
+    blit8x16(0x3a, 0, 224, false)
+    return sheet
+  end
+
+  -- card_flip_2.2bpp uses --remove-whitespace: blank tiles in column 2 of the
+  -- 3-wide header strip (indices 2,5,...,23) are dropped from the ROM stream.
+  -- Re-insert them so HEADER_TILE_MAP / MON_ANCHORS (pret sheet indices) work.
+  local function expandCardFlip2(compact)
+    local need = CARD2_W * CARD2_H / 4
+    local out = {}
+    for i = 1, need do out[i] = 0 end
+    local whitespace = {
+      [2] = true, [5] = true, [8] = true, [11] = true,
+      [14] = true, [17] = true, [20] = true, [23] = true,
+    }
+    local src = 0
+    for tile = 0, 59 do
+      if not whitespace[tile] then
+        for b = 1, 16 do
+          out[tile * 16 + b] = compact[src * 16 + b] or 0
+        end
+        src = src + 1
+      end
+    end
+    return out
+  end
+
+  local slots = nil
   if self.symbols["Slots1LZ"] then
+    -- --trim-whitespace drops the final empty tile (37 of 38).
     local raw1 = self:decompressLz3Symbol("Slots1LZ")
-    self:write2bpp(raw1, 16, #raw1 / 4, "slots/gold_slots_1.png")
+    writeSheet(raw1, SLOTS1_W, SLOTS1_H, "slots/gold_slots_1.png")
+    slots = slots or {}
+    slots.sheet1 = "assets/generated/slots/gold_slots_1.png"
   end
   if self.symbols["Slots2LZ"] then
-    local raw2 = self:decompressLz3Symbol("Slots2LZ")
+    local raw2 = ImageWriter.deinterleave(
-    -- In Pokemon Gold ROM, Seven symbol (first 4 tiles = 64 bytes) has inverted bit polarity
+      self:decompressLz3Symbol("Slots2LZ"), SLOTS2_W)
+    -- Commercial Gold stores the Seven symbol with inverted bit polarity.
     for i = 1, math.min(64, #raw2) do
       raw2[i] = bit.band(bit.bnot(raw2[i]), 0xFF)
     end
-    self:write2bpp(raw2, 16, #raw2 / 4, "slots/gold_slots_2.png")
+    writeSheet(raw2, SLOTS2_W, SLOTS2_H, "slots/gold_slots_2.png")
+    slots = slots or {}
+    slots.sheet2 = "assets/generated/slots/gold_slots_2.png"
   end
   if self.symbols["Slots3LZ"] then
     local raw3 = self:decompressLz3Symbol("Slots3LZ")
-    self:write2bpp(raw3, 24, #raw3 / 6, "slots/gold_slots_3.png", true)
+    local actors = composeSlotsActors(raw3)
-    -- Slots3LZ is a 24px-wide (3 tiles), 240px-tall (30 tiles) sprite sheet containing:
+    self:save(actors, "slots/gold_slots_3.png")
-    --   Y=0:   Golem 1 (Standing, 24x32)
+    self:save(actors, "slots/gold_slots_actors.png")
-    --   Y=32:  Golem 2 (Ball, 24x32)
+    slots = slots or {}
-    --   Y=64:  Chansey 1 (Standing / Step 1, 24x32)
+    slots.sheet3 = "assets/generated/slots/gold_slots_3.png"
-    --   Y=96:  Chansey 2 (Step 2, 24x32)
-    --   Y=128: Chansey 3 (Step 3, 24x32)
-    --   Y=160: Chansey 4 (Arm raised / Step 4, 24x32)
-    --   Y=192: Chansey 5 (Egg Drop pose, 24x32)
-    --   Y=224: Egg (8x16 at X=0)
-    self:write2bpp(raw3, 24, #raw3 / 6, "slots/gold_slots_actors.png", true)
   end
   if self.symbols["SlotsTilemap"] then
     local symbol = self:symbol("SlotsTilemap")
     local tm = self.rom:bytes(symbol.bank, symbol.address, 20 * 12)
-    self:save(tm, "slots/gold_slots.tilemap")
+    writeRaw("slots/gold_slots.tilemap", tm)
+    slots = slots or {}
+    slots.tilemap = "assets/generated/slots/gold_slots.tilemap"
   end
+  if slots then out.slots = slots end
 
   -- Goldenrod Game Corner: Card Flip graphics assets
+  local cardFlip = nil
   if self.symbols["CardFlipLZ01"] then
+    -- --trim-whitespace: 62 of 64 tiles in the ROM stream.
     local raw1 = self:decompressLz3Symbol("CardFlipLZ01")
-    self:write2bpp(raw1, 128, #raw1 / 32, "card_flip/card_flip_1.png")
+    writeSheet(raw1, CARD1_W, CARD1_H, "card_flip/card_flip_1.png")
+    cardFlip = cardFlip or {}
+    cardFlip.sheet1 = "assets/generated/card_flip/card_flip_1.png"
   end
   if self.symbols["CardFlipLZ02"] then
-    local raw2 = self:decompressLz3Symbol("CardFlipLZ02")
+    local raw2 = expandCardFlip2(self:decompressLz3Symbol("CardFlipLZ02"))
-    self:write2bpp(raw2, 24, #raw2 / 6, "card_flip/card_flip_2.png")
+    writeSheet(raw2, CARD2_W, CARD2_H, "card_flip/card_flip_2.png")
+    cardFlip = cardFlip or {}
+    cardFlip.sheet2 = "assets/generated/card_flip/card_flip_2.png"
   end
   if self.symbols["CardFlipLZ03"] then
     local raw3 = self:decompressLz3Symbol("CardFlipLZ03")
-    self:write2bpp(raw3, 8, #raw3 / 2, "card_flip/card_flip_3.png")
+    writeSheet(raw3, CARD3_W, CARD3_H, "card_flip/card_flip_3.png")
+    cardFlip = cardFlip or {}
+    cardFlip.sheet3 = "assets/generated/card_flip/card_flip_3.png"
   end
   if self.symbols["CardFlipOnButtonGFX"] then
     local symbol = self:symbol("CardFlipOnButtonGFX")
     self:write2bpp(self.rom:bytes(symbol.bank, symbol.address, 16), 8, 8, "card_flip/on.png")
+    cardFlip = cardFlip or {}
+    cardFlip.on = "assets/generated/card_flip/on.png"
   end
   if self.symbols["CardFlipOffButtonGFX"] then
     local symbol = self:symbol("CardFlipOffButtonGFX")
     self:write2bpp(self.rom:bytes(symbol.bank, symbol.address, 16), 8, 8, "card_flip/off.png")
+    cardFlip = cardFlip or {}
+    cardFlip.off = "assets/generated/card_flip/off.png"
   end
   if self.symbols["CardFlipTilemap"] then
     local symbol = self:symbol("CardFlipTilemap")
     local tm = self.rom:bytes(symbol.bank, symbol.address, 11 * 12)
-    self:save(tm, "card_flip/card_flip.tilemap")
+    writeRaw("card_flip/card_flip.tilemap", tm)
+    cardFlip = cardFlip or {}
+    cardFlip.tilemap = "assets/generated/card_flip/card_flip.tilemap"
   end
-
+  if cardFlip then out.cardFlip = cardFlip end
-  out.slots = {
-    sheet1 = "assets/generated/slots/gold_slots_1.png",
-    sheet2 = "assets/generated/slots/gold_slots_2.png",
-    sheet3 = "assets/generated/slots/gold_slots_3.png",
-    tilemap = "assets/generated/slots/gold_slots.tilemap",
-  }
-
-  out.cardFlip = {
-    sheet1 = "assets/generated/card_flip/card_flip_1.png",
-    sheet2 = "assets/generated/card_flip/card_flip_2.png",
-    sheet3 = "assets/generated/card_flip/card_flip_3.png",
-    on = "assets/generated/card_flip/on.png",
-    off = "assets/generated/card_flip/off.png",
-    tilemap = "assets/generated/card_flip/card_flip.tilemap",
-  }
 
   self:write("menu_gfx", out)
   self:tick("Menu graphics", 1, 1)
@@ -5564,6 +5743,25 @@ function RomExtractorGen2:pokedexGfx()
   return dex
 end
 
+-- BillsPC_InitGFX's four tiles at vTiles2 $5c
+-- (engine/pokemon/bills_pc.asm:2170-2173)
+function RomExtractorGen2:billsPcGfx()
+  if not self.symbols["PCMailGFX"] then return nil end
+  local pc = {}
+  local gfx = self:symbol("PCMailGFX")
+  self:write2bpp(self.rom:bytes(gfx.bank, gfx.address, 4 * 16),
+    32, 8, "pc/mail_item.png")
+  pc.icons = "assets/generated/pc/mail_item.png"
+  pc.firstTile = 0x5c
+  pc.palette = self:predefPal(PREDEFPAL_POKEDEX)
+  -- gfx/pc/orange.pal
+  if self.symbols["BillsPCOrangePalette"] then
+    local orange = self:symbol("BillsPCOrangePalette")
+    pc.orangePalette = self:colors(orange.bank, orange.address, 4)
+  end
+  return pc
+end
+
 -- Reads a `tile, count` RLE tilemap (Pokegear_LoadTilemapRLE).  The routine's
 -- own comment says "repeat count, tile ID" and has it backwards: it loads b
 -- from the first byte, c from the second, and writes `b` c times.  $ff ends
@@ -6130,6 +6328,7 @@ function RomExtractorGen2:run()
   results.sprites = self:extractSprites()
   results.stdScripts = self:extractStdScripts()
   results.scripts = self:extractScriptsAndText(results.maps, results.stdScripts)
+  results.text = self:extractText()
   results.pokemon = self:extractPokemon()
   results.moves = self:extractMoves()
   results.items = self:extractItems()

src/import/RomImporter.lua

@@ -104,6 +104,12 @@ local VERSION_REQUIRED_FILES_OVERRIDE = {
     "data/generated/sprites.lua", -- OW sheets (Chris + NPCs)
     "data/generated/scripts.lua", -- disassembled map scripts
     "data/generated/text.lua", -- decoded Gen 2 dialogue strings
+    -- The engine's own strings, keyed by label rather than by address.  A
+    -- cache built before RomExtractorGen2:extractText has none, and every
+    -- line that reads through src/core/RomText.lua would silently keep
+    -- printing its Lua fallback, so this re-imports those caches rather than
+    -- bumping CACHE_FORMAT and dragging Red, Blue and Yellow through it too.
+    "data/generated/rom_text.lua",
     "data/generated/pokemon.lua",
     "data/generated/tilesets.lua",
     "data/generated/audio.lua",
@@ -140,6 +146,14 @@ local VERSION_REQUIRED_FILES_OVERRIDE = {
     -- before the four ball tiles were extracted (#1502).
     "assets/generated/battle/hud/balls.png",
     "assets/generated/audio/programs.bin",
+    -- Goldenrod Game Corner reel + board art (#1581).  menu_gfx.lua used to
+    -- advertise these paths even when Slots*LZ / CardFlip* were absent from
+    -- the manifest, so a cache that never wrote the PNGs still looked
+    -- complete and SlotMachine crashed on its labelled-cell fallback.
+    "assets/generated/slots/gold_slots_1.png",
+    "assets/generated/card_flip/card_flip_1.png",
+    -- PCMailGFX (engine/pokemon/bills_pc.asm:2170-2173)
+    "assets/generated/pc/mail_item.png",
   },
 }
 -- Same Gen 2 extract, so a Silver cache is complete when the same files exist.
@@ -382,6 +396,142 @@ local function externalFileSize(path)
   return size
 end
 
+local function openImportSource(path)
+  -- Desktop picker paths live outside LÖVE's virtual filesystem. Prefer the
+  -- native file handle so a 1.46 GiB disc is never copied to a temp file or
+  -- read into one Lua string before validation.
+  local native = io.open(path, "rb")
+  if native then
+    local size, sizeErr = native:seek("end")
+    if size == nil or size == false then
+      native:close()
+      return nil, sizeErr or "could not determine source file size"
+    end
+    local reset, resetErr = native:seek("set", 0)
+    if reset == nil or reset == false then
+      native:close()
+      return nil, resetErr or "could not rewind source file"
+    end
+    return {
+      size = size,
+      read = function(_, n) return native:read(n) end,
+      close = function() native:close() end,
+    }
+  end
+  if love and love.filesystem and love.filesystem.newFile then
+    local file, makeErr = love.filesystem.newFile(path)
+    if not file then return nil, makeErr or "could not open source file" end
+    local ok, openErr = file:open("r")
+    if not ok then return nil, openErr or "could not open source file" end
+    local size = file.getSize and file:getSize() or nil
+    return {
+      size = size,
+      read = function(_, n) return file:read(n) end,
+      close = function() file:close() end,
+    }
+  end
+  return nil, "streaming source access is unavailable"
+end
+local function streamRequiredImport(manifest, importId, source)
+  local RequiredImports = require("src.mods.RequiredImports")
+  local spec = RequiredImports.spec(manifest, importId)
+  if not spec then return nil, "Import declaration was not found." end
+  if spec.format == "n64" then
+    return nil, "streaming canonicalization is unavailable for N64 imports"
+  end
+  local input, openErr = openImportSource(source)
+  if not input then return nil, openErr end
+  local sizeErr = RequiredImports.sizeError(spec, input.size, false)
+  if sizeErr then input:close(); return nil, sizeErr end
+
+  local CacheFs = require("src.import.CacheFs")
+  local destination = RequiredImports.path(manifest, spec)
+  local savedPrefix = CacheFs.prefix
+  local output
+  local inputClosed, outputClosed = false, false
+
+  local function closeInput()
+    if inputClosed then return end
+    inputClosed = true
+    pcall(function() input:close() end)
+  end
+
+  local function closeOutput()
+    if outputClosed or not output then return end
+    outputClosed = true
+    pcall(function() output:close() end)
+  end
+
+  local resultOk, resultDetail
+  CacheFs.prefix = ""
+  local ran, thrown = xpcall(function()
+    CacheFs.remove(RequiredImports.receiptPath(manifest, spec))
+    CacheFs.remove(destination)
+    local makeErr
+    output, makeErr = CacheFs.openWrite(destination)
+    if not output then
+      resultDetail = makeErr or "could not create imported file"
+      return
+    end
+
+    local MD5 = require("src.mods.StreamMD5")
+    local md5 = MD5.new()
+    local total, chunkBytes = 0, 4 * 1024 * 1024
+    while true do
+      local chunk = input:read(chunkBytes)
+      if not chunk or #chunk == 0 then break end
+      md5:update(chunk)
+      local wrote, writeErr = output:write(chunk)
+      if wrote == false or wrote == nil then
+        resultDetail = "could not copy import: "
+.. tostring(writeErr or "write failed")
+        return
+      end
+      total = total + #chunk
+      if #chunk < chunkBytes then break end
+    end
+
+    closeInput()
+    closeOutput()
+    if input.size and total ~= input.size then
+      resultDetail = ("source read ended early (expected %d bytes, copied %d)")
+        :format(input.size, total)
+      return
+    end
+    local storedSizeErr = RequiredImports.sizeError(spec, total, true)
+    if storedSizeErr then resultDetail = storedSizeErr; return end
+    local digest = md5:final()
+
+    -- acceptStoredDigest uses the normal engine path/receipt rules, so
+    -- restore the caller's prefix before handing control to it.
+    CacheFs.prefix = savedPrefix
+    local accepted, detail = RequiredImports.acceptStoredDigest(
+      manifest, importId, digest, love.filesystem)
+    if not accepted then resultDetail = detail; return end
+    resultOk, resultDetail = true, detail
+  end, function(err)
+    if debug and debug.traceback then
+      return debug.traceback(tostring(err), 2)
+    end
+    return tostring(err)
+  end)
+
+  -- finally: resource handles and the process-global CacheFs prefix must
+  -- be restored even when a read/hash/write helper raises a Lua error.
+  closeInput()
+  closeOutput()
+  CacheFs.prefix = ""
+  if not ran or not resultOk then
+    pcall(function() CacheFs.remove(destination) end)
+  end
+  CacheFs.prefix = savedPrefix
+
+  if not ran then
+    return nil, "could not copy import: " .. tostring(thrown)
+  end
+  if not resultOk then return nil, resultDetail end
+  return true, resultDetail
+end
 local function readDroppedFile(file)
   local ok, openError = file:open("r")
   if not ok then return nil, openError end
@@ -942,13 +1092,19 @@ end
 -- naive "first ROM wins" scan would re-import Red when the player tries to
 -- add Blue (issue #167).  Yellow and Gold carts are typically .gbc (Gold is
 -- 2 MiB).
-local function findPendingRom(ready)
+-- `wanted` narrows the scan to one version.  A Choose names the cart it is
+-- for, so without it several dumps sitting in the save directory answered in
+-- listing order and the selection was dropped: picking Red imported Blue
+-- (#1274).  The callers that are not a Choose, the Android USB-drop scans,
+-- pass nothing and still take the first pending cart of any version.
+local function findPendingRom(ready, wanted)
   for _, name in ipairs(love.filesystem.getDirectoryItems("")) do
     if name:lower():match("%.gbc?$") and love.filesystem.getInfo(name, "file") then
       local data = love.filesystem.read(name)
       if type(data) == "string" and isAcceptedRomSize(#data) then
         local version = GameVersion.forSha1(sha1(data))
-        if version and not ready[version] then
+        if version and not ready[version]
+            and (wanted == nil or version == wanted) then
           return name, data
         end
       end
@@ -1228,11 +1384,13 @@ local function chooseRequiredFile()
       "$d=New-Object System.Windows.Forms.OpenFileDialog;",
       "$d.Title='" .. prompt .. "';",
       "$d.Filter='All files (*.*)|*.*';",
+      -- Required imports can be multi-gigabyte optical-disc images. Do NOT
+      -- stage them through %TEMP%: that doubles free-space requirements and a
+      -- failed Copy-Item can leave a plausible-looking truncated temp file.
+      -- Stream the selected source directly into the mod-owned destination.
       "if($d.ShowDialog() -eq 'OK'){",
-      "$t=Join-Path $env:TEMP 'pokeport_required_import.bin';",
-      "Copy-Item -LiteralPath $d.FileName -Destination $t -Force;",
       "[Console]::OutputEncoding=[Text.Encoding]::UTF8;",
-      "[Console]::Write($t)}",
+      "[Console]::Write($d.FileName)}",
     })
     return commandOutput(
       'powershell -NoProfile -STA -Command "' .. script .. '"')
@@ -2072,8 +2230,13 @@ function RomImporter:_importRequiredSource(modId, importId, source, confirmed)
     return nil
   end
   local RequiredImports = require("src.mods.RequiredImports")
+  -- A desktop picker returns a host path. Ask the host file handle first;
+  -- love.filesystem.getInfo is only authoritative for virtual/save paths.
+  local size = externalFileSize(source)
+  if not size then
     local info = love.filesystem.getInfo(source, "file")
-  local size = info and info.size or externalFileSize(source)
+    size = info and info.size or nil
+  end
   local sizeErr = RequiredImports.sizeError(spec, size, false)
   if sizeErr then
     requiredImportNotice(self, modId, importId, sizeErr)
@@ -2096,6 +2259,20 @@ function RomImporter:_importRequiredSource(modId, importId, source, confirmed)
     }
     return nil
   end
+  if type(size) == "number" and size > RequiredImports.LARGE_WARN_BYTES
+      and spec.format ~= "n64" then
+    local ok, result = streamRequiredImport(manifest, importId, source)
+    if ok then
+      self.requiredImportNotice = nil
+      self.modNotice = { ok = true, text = "Imported " .. tostring(importId)
+        .. " for " .. tostring(manifest.name or manifest.id) .. "." }
+      self:_refreshMods()
+      return true
+    end
+    requiredImportNotice(self, modId, importId, result)
+    self.modNotice = nil
+    return nil
+  end
   local data = love.filesystem.read(source)
   if not data then data = readExternalPath(source) end
   if not data then
@@ -2410,8 +2587,9 @@ function RomImporter:choose(version)
   if self.android then
     -- Prefer a not-yet-imported .gb/.gbc already in the save dir (USB copy, or
     -- a fresh SAF pick).  Never reuse an already-imported cart's file -- that
-    -- was the #167 failure mode (second Choose just re-extracted Red).
+    -- was the #167 failure mode (second Choose just re-extracted Red).  This
-    local name, data = findPendingRom(self.ready)
+    -- is a Choose, so it takes the cart that was asked for and nothing else.
+    local name, data = findPendingRom(self.ready, self.chooseVersion)
     if name then
       self:startData(data, name)
     elseif consumePickedRomError(self) then
@@ -2439,8 +2617,10 @@ function RomImporter:choose(version)
   -- Handheld Linux (Anbernic stock OS / PortMaster) rarely has zenity or
   -- kdialog.  Fall back to the same "drop a .gb/.gbc next to the game" scan
   -- used on Android, which works when the game is launched as an unpacked
-  -- directory (see build-rg34xxsp.sh).
+  -- directory (see build-rg34xxsp.sh).  Narrowed to the chosen version: with
-  local name, data = findPendingRom(self.ready)
+  -- four dumps in the folder the unnarrowed scan answered in listing order,
+  -- so Choose Red imported and decoded Blue (#1274).
+  local name, data = findPendingRom(self.ready, self.chooseVersion)
   if name then
     self:startData(data, name)
     return
@@ -2848,6 +3028,7 @@ function RomImporter:_updatePadCursor(dt)
     local overY = 0
     if ny > oy + h then overY = ny - (oy + h)
     elseif ny < oy then overY = ny - oy end
+    if math.abs(ay) > PAD_DEAD and not self._padStickCentered then overY = 0 end
     if overY ~= 0 and self._flex then
       require("src.import.LauncherView").wheelmoved(self, 0, -overY / 48)
     end
@@ -2907,7 +3088,11 @@ end
 function RomImporter:gamepadaxis(_, axis, value)
   if axis == "leftx" or axis == "lefty" or axis == "righty" then
     self._padAxis[axis] = value
-    if math.abs(value) > PAD_DEAD then self:_activatePadCursor() end
+    if math.abs(value) > PAD_DEAD then
+      self:_activatePadCursor()
+    elseif axis == "lefty" then
+      self._padStickCentered = true
+    end
   end
 end
 
@@ -2916,18 +3101,21 @@ end
 -- fire the virtual cursor's click twice off one A press (#620).
 function RomImporter:joystickpressed(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   local padButton = GamepadMap.mapRawToGamepadButton(button)
   if padButton then self:gamepadpressed(joystick, padButton) end
 end
 
 function RomImporter:joystickreleased(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   local padButton = GamepadMap.mapRawToGamepadButton(button)
   if padButton then self:gamepadreleased(joystick, padButton) end
 end
 
 function RomImporter: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
@@ -2937,6 +3125,7 @@ end
 
 function RomImporter:joystickhat(joystick, hat, direction)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   for _, dir in ipairs(self._rawHatDirs[hat] or {}) do
     self._padDir[dir] = nil
   end
@@ -3182,6 +3371,10 @@ function RomImporter:_ensureSkins(force)
       format = skin and skin.format or nil,
       pages = skin and #skin.pages or 0,
       controls = controls,
+      -- The launcher owns the visual skin picker, so retain the already
+      -- loaded first-page bezel for its preview card instead of decoding it
+      -- again every frame.
+      preview = page and page.image or nil,
       screen = page ~= nil
         and (page.viewport ~= nil or page.screenFit == "remainder"),
       ok = skin ~= nil,
@@ -3194,7 +3387,7 @@ end
 function RomImporter:_activeSkin()
   local opts = require("src.core.SaveData").loadOptions()
   local tc = type(opts.touchControls) == "table" and opts.touchControls or {}
-  return tc.skin
+  return tc.enabled == false and nil or tc.skin
 end
 
 function RomImporter:_useSkin(id)
@@ -3211,6 +3404,16 @@ function RomImporter:_useSkin(id)
   }
 end
 
+function RomImporter:_disableSkins()
+  local SaveData = require("src.core.SaveData")
+  local opts = SaveData.loadOptions()
+  local tc = type(opts.touchControls) == "table" and opts.touchControls or {}
+  tc.enabled, tc.skin = false, nil
+  opts.touchControls = tc
+  SaveData.saveOptions(opts)
+  self._skinNotice = { ok = true, text = "Skins are off. Mobile will use the built-in pad when needed." }
+end
+
 function RomImporter:_installSkinZip(source)
   if self.workState == "working" then return end
   self.tab = "skins"
@@ -3997,6 +4200,18 @@ function RomImporter:_disarmTextInput()
   end
 end
 
+function RomImporter:_blurPanelFields()
+  if not (self._findSearchFocus or self._skinUrlFocus) then return end
+  if self._indexPrompt or self._rename or self._settingsText
+      or self._profileSavePrompt or self._profileRenamePrompt
+      or (self._syncModal and self._syncFocus) then
+    return
+  end
+  self._findSearchFocus = false
+  self._skinUrlFocus = false
+  self:_disarmTextInput()
+end
+
 function RomImporter:_beginRename(version, id)
   local label
   for _, slot in ipairs(self.slots[version] or {}) do
@@ -4127,7 +4342,6 @@ function RomImporter:_refreshMods()
     end
     self.mods = kept
   end
-  self:_syncModUpdateInfo(false)
 end
 
 -- Point the MODS panel at one game (or nil for all of them) and relist, so
@@ -4141,15 +4355,12 @@ function RomImporter:_ensureMods()
   if not self.mods then self:_refreshMods() end
 end
 
--- Resolve cached (or freshly fetched) GitHub status for every mod that
+-- Resolve GitHub status for every installed mod that declares a github field.
--- declares a github field. force=true bypasses the 6h cache on every repo.
+-- This is deliberately opt-in: only the explicit "Check for updates" action
--- Results live on self.modUpdateInfo[id] = { status, latest, best, releases }.
+-- calls it. Opening, scrolling, toggling, or relisting the MODS tab must not
--- ASYNC (was synchronous).  This runs on every _refreshMods -- boot, and any
+-- create a burst of release work behind the list. force=true bypasses the 6h
--- toggle or install -- and used to make one blocking curl call per mod with a
+-- cache on every repo. Results live on self.modUpdateInfo[id] = {
--- github field, in a loop, on the render thread.  A handful of mods was a
+-- status, latest, best, releases } and resolve asynchronously across frames.
--- multi-second freeze of the whole launcher.  Now each mod gets a handle and
--- they resolve together across later frames; a mod whose cache is still fresh
--- resolves on the first pump with no network at all.
 function RomImporter:_syncModUpdateInfo(force)
   local ModUpdate = require("src.mods.ModUpdate")
   self.modUpdateInfo = self.modUpdateInfo or {}

src/inventory/Bag.lua

@@ -10,13 +10,14 @@
 local Bag = {}
 
 -- MAX_ITEMS / MAX_BALLS / MAX_KEY_ITEMS, and the TM/HM pocket holds one of
--- every TM plus the seven HMs (NUM_TMS + NUM_HMS).  A `mods` bagSize override
+-- every TM plus the seven HMs (NUM_TMS + NUM_HMS -- ram/wram.asm:2421 is
+-- `wTMsHMs:: ds NUM_TMS + NUM_HMS`, 57 bytes).  A `mods` bagSize override
 -- replaces the ITEM pocket only, the way the Gen 1 single-bag config did.
 local POCKET_CAPACITY = {
   ITEM = 20,
   BALL = 12,
   KEY_ITEM = 25,
-  TM_HM = 64,
+  TM_HM = 57,
 }
 local DEFAULT_CAPACITY = 20
 

src/mods/Gen2Compat.lua

@@ -808,6 +808,33 @@ local function buildOverworld()
   local Movement = rawRequire("src.script.gen2.Movement")
   local HiddenItems = rawRequire("src.world.gen2.HiddenItems")
   local Bike = rawRequire("src.world.gen2.Bike")
+  local FieldMoves = rawRequire("src.world.gen2.FieldMoves")
+
+  -- home/map.asm:1869
+  local function stepAllowed(world, entity, dir, cx, cy)
+    local d = Map2.DELTA[dir]
+    if not (world.map and d and entity) then return true end
+    cx, cy = cx or entity.cellX, cy or entity.cellY
+    if not (cx and cy) then return true end
+    if not Permissions.stepPermitted(
+         function(px, py) return world:cellCollisionAcross(world.map, px, py) end,
+         cx, cy, dir) then
+      return false
+    end
+    local map = world.map
+    if entity == world.player and FieldMoves.isSurfing(world.playerState) then
+      map = world:surfMap(world.map)
+    end
+    local tx, ty = cx + d[1], cy + d[2]
+    if not map:inBounds(tx, ty) or not map:isWalkable(tx, ty) then return false end
+    for _, e in ipairs(world.entities or {}) do
+      if e ~= entity and not e.passable then
+        if e.cellX == tx and e.cellY == ty then return false end
+        if e.moving and e.targetX == tx and e.targetY == ty then return false end
+      end
+    end
+    return true
+  end
 
   local api = nil
   -- one WorldAPI instance, so queueScript reuses the five-verb allow list
@@ -1011,20 +1038,33 @@ local function buildOverworld()
 
   -- Gold has ONE movement slot; a second concurrent call is refused with a
   -- reason rather than dropped (src/world/gen2/WorldAPI.lua:171's recipe).
-  function ow.scriptMove(entity, dir, tiles, onDone)
+  function ow.scriptMove(entity, dir, tiles, onDone, opts)
     local world = w("scriptMove")
     if not world then return nil, "no overworld" end
     if world.moveState then return nil, "a movement is already running" end
     local step = Movement.stepByte(dir)
     if not step then return nil, "unknown direction: " .. tostring(dir) end
-    local bytes = {}
-    for _ = 1, math.max(0, tiles or 1) do bytes[#bytes + 1] = step end
-    bytes[#bytes + 1] = Movement.STEP_END
     local objectId = objectIdOf(world, entity)
     if not objectId then
       return nil, "no Gen 2 objectId for that entity: only the player and a "
         .. "mapped object (def.index) can be moved"
     end
+    local n = math.max(0, tiles or 1)
+    if opts and opts.collide and n > 0 then
+      local d = Map2.DELTA[dir]
+      local cx, cy = entity.cellX, entity.cellY
+      local allowed = 0
+      for _ = 1, n do
+        if not stepAllowed(world, entity, dir, cx, cy) then break end
+        allowed = allowed + 1
+        if d and cx and cy then cx, cy = cx + d[1], cy + d[2] end
+      end
+      if allowed < n then entity.facing = dir end
+      n = allowed
+    end
+    local bytes = {}
+    for _ = 1, n do bytes[#bytes + 1] = step end
+    bytes[#bytes + 1] = Movement.STEP_END
     world:beginMovement(objectId, bytes, onDone)
     return true
   end
@@ -1401,7 +1441,8 @@ COVERAGE[OW] = {
       .. "objectId 1 is wLastTalked, not object zero",
     scriptMove = "the player maps to objectId 0 and a mapped object to "
       .. "def.index + 1; an entity with neither (a mod's own guest) is "
-      .. "REFUSED with a reason rather than moving the last-talked NPC",
+      .. "REFUSED with a reason rather than moving the last-talked NPC; "
+      .. "opts.collide truncates the walk at the first blocked step",
     connectionLanding = "Gen 1's five values (destDef, tilesetDef, x, y, "
       .. "conn); `conn` is Gold's connection record, keyed map/mapId + offset",
     timeOfDay = "recomputed from the clock every call and never cached, so a "

src/mods/ImportAccess.lua

@@ -0,0 +1,174 @@
+-- Scoped access to a mod's launcher-validated required/optional imports and
+-- to installation-wide generated cache data.
+--
+-- This intentionally does not expose host paths or raw filesystem handles.
+-- Import reads are bounded and can only address ids declared by the calling
+-- mod's manifest. Cache paths are confined to mod_cache/<mod-id>/ and are not
+-- tied to a Pokémon playthrough.
+
+local RequiredImports = require("src.mods.RequiredImports")
+local SafePath = require("src.mods.SafePath")
+local SaveData = require("src.core.SaveData")
+
+local ImportAccess = {}
+
+ImportAccess.MAX_READ_BYTES = 8 * 1024 * 1024
+ImportAccess.MAX_CACHE_WRITE_BYTES = 64 * 1024 * 1024
+
+local function specMap(manifest)
+  local out = {}
+  for _, spec in ipairs(RequiredImports.specs(manifest)) do out[spec.id] = spec end
+  return out
+end
+
+local function parentOf(path)
+  return path:match("^(.*)/[^/]+$")
+end
+
+local function copyInfo(info)
+  if not info then return nil end
+  return { type = info.type, size = info.size, modtime = info.modtime }
+end
+
+local function fsReadRange(fs, path, offset, length)
+  if fs and type(fs.readRange) == "function" then
+    return fs.readRange(path, offset, length)
+  end
+  local newFile = fs and fs.newFile
+  if newFile then
+    local file, makeErr = newFile(path)
+    if not file then return nil, makeErr or "could not open import" end
+    local ok, openErr = file:open("r")
+    if not ok then return nil, openErr or "could not open import" end
+    local seekOk, seekErr = file:seek(offset)
+    if seekOk == nil or seekOk == false then
+      file:close()
+      return nil, seekErr or "could not seek import"
+    end
+    local data, readErr = file:read(length)
+    file:close()
+    return data, readErr
+  end
+  -- Injectable headless filesystems may expose only read(). Production
+  -- love.filesystem has newFile(), so large imports are never materialized
+  -- into one Lua string by this fallback.
+  if fs and fs.read then
+    local data = fs.read(path)
+    if type(data) ~= "string" then return nil, "could not read import" end
+    return data:sub(offset + 1, offset + length)
+  end
+  return nil, "random-access import reads are unavailable"
+end
+
+local function validatedInfo(manifest, spec, fs)
+  local ok, detail = RequiredImports.validateStored(manifest, spec, fs)
+  if not ok then return nil, detail or "import is not validated" end
+  local path = RequiredImports.path(manifest, spec)
+  local info = fs.getInfo and fs.getInfo(path, "file") or nil
+  if not info then return nil, "import is missing" end
+  return info, detail
+end
+
+local function makeCache(modId, fs)
+  local root = "mod_cache/" .. modId
+  local function pathFor(rel, what)
+    rel = SafePath.require(rel, what or "mod.cache path")
+    return root .. "/" .. rel
+  end
+  local cache = {}
+
+  function cache:write(rel, bytes)
+    if type(bytes) ~= "string" then
+      return nil, "mod.cache:write expects a byte string"
+    end
+    if #bytes > ImportAccess.MAX_CACHE_WRITE_BYTES then
+      return nil, "mod.cache:write payload exceeds 64 MiB; split generated data into smaller files"
+    end
+    local path = pathFor(rel, "mod.cache:write")
+    local parent = parentOf(path)
+    if parent and fs.createDirectory then
+      local ok = fs.createDirectory(parent)
+      if ok == false then return nil, "could not create cache directory" end
+    end
+    if not fs.write then return nil, "cache writes are unavailable" end
+    return fs.write(path, bytes)
+  end
+
+  function cache:read(rel)
+    local path = pathFor(rel, "mod.cache:read")
+    if not fs.read then return nil, "cache reads are unavailable" end
+    return fs.read(path)
+  end
+
+  function cache:info(rel)
+    local path = pathFor(rel, "mod.cache:info")
+    if not fs.getInfo then return nil end
+    return copyInfo(fs.getInfo(path))
+  end
+
+  function cache:exists(rel)
+    local info = self:info(rel)
+    return info ~= nil and info.type == "file"
+  end
+
+
+  function cache:delete(rel)
+    local path = pathFor(rel, "mod.cache:delete")
+    if not fs.remove then return nil, "cache deletion is unavailable" end
+    return fs.remove(path)
+  end
+
+  return cache
+end
+
+function ImportAccess.new(manifest, fs)
+  local specs = specMap(manifest)
+  local cacheFs = SaveData.persistenceFs(fs) or fs
+  local imports = {}
+
+  function imports:info(id)
+    local spec = specs[id]
+    if not spec then return nil, "undeclared import: " .. tostring(id) end
+    local info, digestOrErr = validatedInfo(manifest, spec, fs)
+    if not info then return nil, digestOrErr end
+    return {
+      id = spec.id,
+      name = spec.name,
+      file = spec.file,
+      size = info.size,
+      md5 = digestOrErr,
+      required = spec.required ~= false,
+    }
+  end
+
+  function imports:read(id, offset, length)
+    local spec = specs[id]
+    if not spec then return nil, "undeclared import: " .. tostring(id) end
+    offset, length = tonumber(offset), tonumber(length)
+    if not offset or offset < 0 or offset % 1 ~= 0 then
+      return nil, "offset must be a non-negative integer"
+    end
+    if not length or length < 0 or length % 1 ~= 0 then
+      return nil, "length must be a non-negative integer"
+    end
+    if length > ImportAccess.MAX_READ_BYTES then
+      return nil, "single import read exceeds 8 MiB"
+    end
+
+    local info, err = validatedInfo(manifest, spec, fs)
+    if not info then return nil, err end
+    local size = tonumber(info.size) or tonumber(spec.size)
+    if size and offset + length > size then return nil, "import read is out of bounds" end
+    if length == 0 then return "" end
+
+    local path = RequiredImports.path(manifest, spec)
+    local data, readErr = fsReadRange(fs, path, offset, length)
+    if not data then return nil, readErr end
+    if #data ~= length then return nil, "short import read" end
+    return data
+  end
+
+  return imports, makeCache(manifest.id, cacheFs)
+end
+
+return ImportAccess

src/mods/Loader.lua

@@ -119,6 +119,17 @@ local GEN1_ONLY_MODULES = {
   ["src.ui.OptionsMenu"] = true,
 }
 
+local function crossGenerationDenial(name, generation)
+  if type(name) ~= "string" or generation ~= 1 then return nil end
+  if not (name:find("^src%.[%w_]+%.gen2%.") or name == "src.core.Game2") then
+    return nil
+  end
+  return ("%s is a Gen 2 engine module and this is a Gen 1 game; the structs "
+    .. "it reads and writes are not this game's, so anything it stores lands "
+    .. "on the save in the wrong shape. Take the game from mod.game and the "
+    .. "world from mod.world, which resolve per generation"):format(name)
+end
+
 -- the src.* modules the mod surface points authors at: another mod's
 -- exports carry a version string that wants range-checking before use, and
 -- ChipAsm is the authoring path for chip music and sfx
@@ -214,6 +225,7 @@ function Loader:_installDevShim()
       if owner or callerIsMod(3) then
         local id = type(owner) == "string" and owner or nil
         local denial = Sandbox.moduleDenial(name, devShim.permissions[id])
+          or (id and crossGenerationDenial(name, devShim.generation))
         if denial then error(("[%s] %s"):format(id or "mod", denial), 0) end
       end
       if devShim.dev or devShim.generation ~= 1 then scanRequire(name) end
@@ -962,6 +974,8 @@ function Loader:_api(mod)
   local Storage = engineRequire("src.mods.Storage")
   local storage = Storage and Storage.new(modId, loader.fs)
   local Checkpoint = engineRequire("src.core.Checkpoint")
+  local ImportAccess = engineRequire("src.mods.ImportAccess")
+  local importApi, installCache = ImportAccess.new(mod.manifest, loader.fs)
   local api = {
     id = modId,
     version = mod.manifest.version,
@@ -1161,6 +1175,12 @@ function Loader:_api(mod)
     -- checkpoint. The
     -- engine binds version/playthrough/mod scope and portable persistence;
     -- callers never receive paths or a raw filesystem handle.
+    -- Read-only bounded access to this mod's manifest-declared, launcher-validated
+    -- imports. No host path is exposed; large sources are read in bounded ranges.
+    imports = importApi,
+    -- Installation-scoped generated data, independent from Pokémon save slots.
+    -- This is where ROM-derived caches belong; mod.storage remains playthrough-scoped.
+    cache = installCache,
     storage = {
       context = function(_, game) return storage:context(game) end,
       selected = function(_, game) return storage:selected(game) end,

src/mods/RequiredImports.lua

@@ -120,6 +120,36 @@ local function accepts(spec, digest)
   return false
 end
 
+local function specById(manifest, importId)
+  for _, candidate in ipairs(allSpecs(manifest)) do
+    if candidate.id == importId then return candidate end
+  end
+  return nil
+end
+
+RequiredImports.spec = specById
+
+local function streamDigest(fs, path, chunkBytes)
+  if not (fs and fs.newFile) then return nil, "streaming file access is unavailable" end
+  local file, makeErr = fs.newFile(path)
+  if not file then return nil, makeErr or "could not open stored import" end
+  local ok, openErr = file:open("r")
+  if not ok then return nil, openErr or "could not open stored import" end
+  local MD5 = require("src.mods.StreamMD5")
+  local ctx = MD5.new()
+  chunkBytes = chunkBytes or (4 * 1024 * 1024)
+  while true do
+    local data, readErr = file:read(chunkBytes)
+    if data and #data > 0 then ctx:update(data) end
+    if not data or #data < chunkBytes then
+      if readErr then file:close(); return nil, readErr end
+      break
+    end
+  end
+  file:close()
+  return ctx:final()
+end
+
 function RequiredImports.path(manifest, spec)
   return manifest.path .. "/baseroms/" .. spec.file
 end
@@ -180,6 +210,47 @@ local function removeReceipt(manifest, spec, fs)
   end
 end
 
+-- Finalize a caller-streamed import after the destination bytes have already
+-- been copied into the engine-owned baseroms path. This keeps large imports
+-- out of a single Lua string while preserving the same size/MD5 receipt rules.
+function RequiredImports.acceptStoredDigest(manifest, importId, digest, fs)
+  fs = fs or (love and love.filesystem)
+  local spec = specById(manifest, importId)
+  if not spec then return nil, "unknown required import: " .. tostring(importId) end
+  digest = tostring(digest or ""):lower()
+  if not accepts(spec, digest) then
+    return nil, ("MD5 mismatch (got %s)"):format(digest ~= "" and digest or "unavailable")
+  end
+  local path = RequiredImports.path(manifest, spec)
+  local info = fs and fs.getInfo and fs.getInfo(path, "file") or nil
+  if not info then return nil, "copied import is missing" end
+  local sizeErr = RequiredImports.sizeError(spec, info.size, true)
+  if sizeErr then return nil, sizeErr end
+  if love and fs == love.filesystem then
+    local savedPrefix = CacheFs.prefix
+    local ok, prefixErr = xpcall(function()
+      CacheFs.prefix = ""
+      CacheFs.remove(removedMarker(manifest, spec))
+      CacheFs.prefix = savedPrefix
+      -- writeReceipt has its own temporary CacheFs prefix switch. Keep it
+      -- inside this guard too so a write error cannot leak global state.
+      writeReceipt(manifest, spec, digest, info, fs)
+    end, function(err)
+      return tostring(err)
+    end)
+    CacheFs.prefix = savedPrefix
+    if not ok then
+      return nil, "could not finalize import receipt: " .. tostring(prefixErr)
+    end
+    return true, digest
+  elseif fs and fs.remove then
+    fs.remove(removedMarker(manifest, spec))
+  end
+  writeReceipt(manifest, spec, digest, info, fs)
+  return true, digest
+end
+
+
 -- Validate bytes against a declaration.  The returned data is canonicalized
 -- (notably for N64 byte order/header variants) and is what must be stored.
 function RequiredImports.validateData(spec, data, hashFn)
@@ -217,6 +288,22 @@ function RequiredImports.validateStored(manifest, spec, fs, hashFn)
   local cached = cachedDigest(manifest, spec, fs, info)
   if cached then return true, cached, true end
   removeReceipt(manifest, spec, fs)
+  -- Large raw imports (GameCube discs, future optical images, etc.) must never
+  -- be materialized into one Lua string merely because their validation
+  -- receipt was lost. Stream the MD5 directly from the installed file. N64
+  -- sources stay on the canonicalization path because byte-order/header
+  -- normalization is part of their validation contract.
+  if info.size and info.size > RequiredImports.LARGE_WARN_BYTES
+      and spec.format ~= "n64" and fs.newFile then
+    local digest, hashErr = streamDigest(fs, path)
+    if not digest then return nil, hashErr end
+    if not accepts(spec, digest) then
+      return nil, ("MD5 mismatch (got %s)"):format(digest)
+    end
+    info = fs.getInfo(path, "file") or info
+    writeReceipt(manifest, spec, digest, info, fs)
+    return true, digest, false
+  end
   if not fs.read then return nil, "file could not be read" end
   local data = fs.read(path)
   local normalized, detail = RequiredImports.validateStoredData(spec, data, hashFn)

src/mods/StreamMD5.lua

@@ -0,0 +1,101 @@
+local bitlib = rawget(_G, "bit") or rawget(_G, "bit32")
+if not bitlib then error("StreamMD5 requires bit or bit32") end
+
+local band, bor, bxor, bnot = bitlib.band, bitlib.bor, bitlib.bxor, bitlib.bnot
+local lshift, rshift = bitlib.lshift, bitlib.rshift
+local rol = bitlib.rol or bitlib.lrotate
+
+local K = {
+  0xd76aa478,0xe8c7b756,0x242070db,0xc1bdceee,0xf57c0faf,0x4787c62a,0xa8304613,0xfd469501,
+  0x698098d8,0x8b44f7af,0xffff5bb1,0x895cd7be,0x6b901122,0xfd987193,0xa679438e,0x49b40821,
+  0xf61e2562,0xc040b340,0x265e5a51,0xe9b6c7aa,0xd62f105d,0x02441453,0xd8a1e681,0xe7d3fbc8,
+  0x21e1cde6,0xc33707d6,0xf4d50d87,0x455a14ed,0xa9e3e905,0xfcefa3f8,0x676f02d9,0x8d2a4c8a,
+  0xfffa3942,0x8771f681,0x6d9d6122,0xfde5380c,0xa4beea44,0x4bdecfa9,0xf6bb4b60,0xbebfbc70,
+  0x289b7ec6,0xeaa127fa,0xd4ef3085,0x04881d05,0xd9d4d039,0xe6db99e5,0x1fa27cf8,0xc4ac5665,
+  0xf4292244,0x432aff97,0xab9423a7,0xfc93a039,0x655b59c3,0x8f0ccc92,0xffeff47d,0x85845dd1,
+  0x6fa87e4f,0xfe2ce6e0,0xa3014314,0x4e0811a1,0xf7537e82,0xbd3af235,0x2ad7d2bb,0xeb86d391,
+}
+local S = {
+  7,12,17,22, 7,12,17,22, 7,12,17,22, 7,12,17,22,
+  5,9,14,20, 5,9,14,20, 5,9,14,20, 5,9,14,20,
+  4,11,16,23, 4,11,16,23, 4,11,16,23, 4,11,16,23,
+  6,10,15,21, 6,10,15,21, 6,10,15,21, 6,10,15,21,
+}
+
+local function add32(a,b,c,d)
+  local n = (a or 0) + (b or 0) + (c or 0) + (d or 0)
+  return band(n, 0xffffffff)
+end
+
+local function le32_from(s, i)
+  local b1,b2,b3,b4 = s:byte(i, i+3)
+  return bor(b1, lshift(b2,8), lshift(b3,16), lshift(b4,24))
+end
+
+local function le32_bytes(x)
+  return string.char(
+    band(x,0xff), band(rshift(x,8),0xff),
+    band(rshift(x,16),0xff), band(rshift(x,24),0xff))
+end
+
+local M = {}
+local StreamMD5 = {}
+StreamMD5.__index = StreamMD5
+
+function StreamMD5.new()
+  return setmetatable({
+    a=0x67452301, b=0xefcdab89, c=0x98badcfe, d=0x10325476,
+    bytes=0, buffer="", done=false,
+  }, StreamMD5)
+end
+
+function StreamMD5:_block(block)
+  for j=1,16 do M[j] = le32_from(block, (j-1)*4+1) end
+  local a,b,c,d = self.a,self.b,self.c,self.d
+  for i=0,63 do
+    local f,g
+    if i < 16 then
+      f = bor(band(b,c), band(bnot(b),d)); g=i
+    elseif i < 32 then
+      f = bor(band(d,b), band(bnot(d),c)); g=(5*i+1)%16
+    elseif i < 48 then
+      f = bxor(b,c,d); g=(3*i+5)%16
+    else
+      f = bxor(c, bor(b,bnot(d))); g=(7*i)%16
+    end
+    local tmp=d
+    d=c
+    c=b
+    b=add32(b, rol(add32(a,f,K[i+1],M[g+1]), S[i+1]))
+    a=tmp
+  end
+  self.a=add32(self.a,a); self.b=add32(self.b,b)
+  self.c=add32(self.c,c); self.d=add32(self.d,d)
+end
+
+function StreamMD5:update(data)
+  assert(not self.done, "StreamMD5 context already finalized")
+  assert(type(data)=="string", "StreamMD5:update expects a string")
+  self.bytes = self.bytes + #data
+  local s = self.buffer .. data
+  local full = #s - (#s % 64)
+  for i=1,full,64 do self:_block(s:sub(i,i+63)) end
+  self.buffer = s:sub(full+1)
+  return self
+end
+
+function StreamMD5:final()
+  assert(not self.done, "StreamMD5 context already finalized")
+  local originalBytes = self.bytes
+  local padLen = (56 - ((originalBytes + 1) % 64)) % 64
+  local bits = originalBytes * 8
+  local lo = bits % 4294967296
+  local hi = math.floor(bits / 4294967296) % 4294967296
+  self:update("\128" .. string.rep("\0", padLen) .. le32_bytes(lo) .. le32_bytes(hi))
+  assert(#self.buffer == 0, "MD5 finalization left a partial block")
+  self.done=true
+  local raw = le32_bytes(self.a)..le32_bytes(self.b)..le32_bytes(self.c)..le32_bytes(self.d)
+  return (raw:gsub(".", function(ch) return string.format("%02x", ch:byte()) end))
+end
+
+return StreamMD5

src/pokemon/Stats.lua

@@ -51,11 +51,20 @@ end
 -- (engine/pokemon/status_screen.asm:66-76, "mon is in a box or daycare" ->
 -- CalcStats) and when one is moved back into the party
 -- (engine/pokemon/add_mon.asm _MoveMon tail).  The stored current HP is
--- kept (box_struct does hold it) but clamped to the recalculated maximum so
+-- kept (box_struct does hold it) but clamped to the recalculated maximum.
--- a tampered save cannot overfill the bar.  A mon that already has stats is
+-- A complete stat block is returned untouched; an incomplete one is rebuilt,
--- returned untouched, so a vanilla save round-trips.  #233, #304
+-- because CalcStats writes all NUM_STATS stats or none
+-- (home/move_mon.asm:33-48).  #233, #304, #1517
+local function statsComplete(stats)
+  for _, key in ipairs(ORDER) do
+    if type(stats[key]) ~= "number" then return false end
+  end
+  return true
+end
+
 function Stats.ensure(speciesDef, mon)
-  if type(mon) ~= "table" or type(mon.stats) == "table" then return mon end
+  if type(mon) ~= "table" then return mon end
+  if type(mon.stats) == "table" and statsComplete(mon.stats) then return mon end
   if type(speciesDef) ~= "table" or type(speciesDef.baseStats) ~= "table" then
     return mon
   end

src/render/PaletteFX.lua

@@ -397,9 +397,12 @@ function PaletteFX.uiSpriteRedraws()
 end
 
 -- Active named-palette table for COLORS: RED++ uses data/palettes_gbc.lua,
--- everything else uses the ROM-imported data.palettes.
+-- Yellow uses data/palettes_yellow.lua, everything else uses the ROM-imported data.palettes.
 function PaletteFX.pack(data)
-  if PaletteFX.usesGbcPack() then
+  if GameVersion.isYellow() then
+    local y = PaletteFX.yellowPack()
+    if y then return y end
+  elseif PaletteFX.usesGbcPack() then
     local g = PaletteFX.gbcPack()
     if g then return g end
   end
@@ -449,24 +452,27 @@ function PaletteFX.pal(data, name)
     local fromRom = romNamedPal(data, name)
     if fromRom then return fromRom end
   end
+  if GameVersion.isYellow() then
     if PaletteFX.usesYellowCgb() then
       local fromCgb = yellowCgbNamedPal(data, name)
       if fromCgb then return fromCgb end
     end
-  local p = PaletteFX.pack(data)
-  local c = p and p.palettes and p.palettes[name]
-  if c then return c end
-  if GameVersion.isYellow() then
     local y = PaletteFX.yellowPack()
     local yc = y and y.palettes and y.palettes[name]
     if yc then return yc end
+    local fromRom = romNamedPal(data, name)
+    if fromRom then return fromRom end
   end
+  local p = PaletteFX.pack(data)
+  local c = p and p.palettes and p.palettes[name]
+  if c then return c end
   if PaletteFX.usesGbcPack() then
     return romNamedPal(data, name)
   end
   return nil
 end
 
+
 -- the species' palette (data/pokemon/palettes.asm), MEWMON for unknowns.
 -- transformed forces PAL_GRAYMON (Ditto's palette) regardless of species
 -- (engine/gfx/palettes.asm DeterminePaletteID: bit TRANSFORMED, a; a

src/render/Playfield.lua

@@ -3,8 +3,6 @@ local TouchSkin = require("src.core.TouchSkin")
 
 local Playfield = {}
 
-Playfield.WIDTH, Playfield.HEIGHT = 160, 144
-
 Playfield.entered = false
 Playfield.box = nil
 
@@ -35,14 +33,9 @@ function Playfield.cutout(sw, sh)
 end
 
 function Playfield.rect(sw, sh)
-  local x, y, w, h, _, expand = Playfield.cutout(sw, sh)
+  local x, y, w, h = Playfield.cutout(sw, sh)
   if not x then return 0, 0, sw or 0, sh or 0, false end
-  if expand then return x, y, w, h, true end
+  return x, y, w, h, true
-  local s = math.max(1, math.floor(math.min(w / Playfield.WIDTH,
-    h / Playfield.HEIGHT)))
-  local pw = math.min(w, Playfield.WIDTH * s)
-  local ph = math.min(h, Playfield.HEIGHT * s)
-  return x + math.floor((w - pw) / 2), y + math.floor((h - ph) / 2), pw, ph, true
 end
 
 function Playfield.enter(x, y, w, h)

src/render/Renderer.lua

@@ -87,12 +87,12 @@ local function displayMetrics()
   if dpiX < 1e-6 then dpiX = 1 end
   if dpiY < 1e-6 then dpiY = 1 end
   local vx, vy = 0, 0
-  local cut, grow = false, false
+  local cut = false
-  local sx, sy, sw, sh, _, expand = Playfield.cutout(pw, ph)
+  local sx, sy, sw, sh = Playfield.cutout(pw, ph)
   if sx then
-    vx, vy, pw, ph, cut, grow = sx, sy, sw, sh, true, expand
+    vx, vy, pw, ph, cut = sx, sy, sw, sh, true
   end
-  return ww, wh, pw, ph, dpiX, dpiY, vx, vy, cut, grow
+  return ww, wh, pw, ph, dpiX, dpiY, vx, vy, cut
 end
 
 local function positionLift(ph, contentPx, dpiY, cut)
@@ -100,10 +100,30 @@ local function positionLift(ph, contentPx, dpiY, cut)
   return ScreenPosition.lift(ph, contentPx, ScreenPosition.safeTop() * dpiY)
 end
 
+-- Free GPU canvases immediately.  Overwriting the Lua reference alone leaves
+-- VRAM allocated until LOVE's GC runs, which is too slow when Android loops
+-- Play → launcher → Play in one process.
+local function releaseCanvas(canvas)
+  if canvas and canvas.release then pcall(canvas.release, canvas) end
+end
+
+function Renderer:releaseCanvases()
+  releaseCanvas(self.canvas); self.canvas = nil
+  releaseCanvas(self.battleHUDCanvas); self.battleHUDCanvas = nil
+  releaseCanvas(self.worldCanvas); self.worldCanvas = nil
+  releaseCanvas(self.uprightCanvas); self.uprightCanvas = nil
+  self.worldActive = false
+  self.uprightActive = false
+  self.worldOverride = nil
+end
+
 function Renderer:init()
   -- 160x144 real pixels, never DPI-scaled: see src/render/PixelCanvas.lua
   -- (#208).  Every canvas below is sized in framebuffer pixels for the same
   -- reason -- worldViewSize() already works in drawable pixels.
+  -- Release any prior session's surfaces before reallocating (in-process
+  -- return-to-launcher reuses this Renderer singleton).
+  self:releaseCanvases()
   self.uiWidth, self.uiHeight = self.WIDTH, self.HEIGHT
   self.canvas = PixelCanvas.new(self.uiWidth, self.uiHeight, "nearest")
   self.battleHUDCanvas = nil
@@ -275,7 +295,7 @@ end
 -- corners; flat mode returns exactly today's size (growth factor is 1 when
 -- tilt is inactive).
 function Renderer:worldViewSize()
-  local _, _, pw, ph, _, dpiY, _, _, cut, grow = displayMetrics()
+  local _, _, pw, ph, _, dpiY, _, _, cut = displayMetrics()
   -- FAITHFUL RATIO on mobile.  The world pass deliberately expands to cover the
   -- WHOLE display, so letterbox voids become more map instead of black bars.
   -- That is why the lock appeared to do nothing in the overworld: it shrank
@@ -287,7 +307,6 @@ function Renderer:worldViewSize()
   -- this is the same sum with the viewport standing in for the window, so
   -- both platforms show the same map area at the same zoom.
   local cap = FaithfulRes.scaleCap()
-  if not cap and cut and not grow then cap = self:fitScale() end
   if cap then
     local uiw, uih = self:uiSize()
     pw = cut and math.min(pw, uiw * cap) or uiw * cap

src/render/TileRenderer.lua

@@ -951,6 +951,13 @@ function TileRenderer.invalidate()
   frameImages = {}
   toggleImages = {}
   stripData = {}
+  -- RED++ per-map atlases are large Images; clear and release so an
+  -- in-process Play → launcher → Play loop does not keep every prior
+  -- session's bake in VRAM / Lua heap.
+  for key, img in pairs(gbcAtlasCache) do
+    safeRelease(img)
+    gbcAtlasCache[key] = nil
+  end
 end
 
 Assets.register(TileRenderer.invalidate)

src/render/Transition.lua

@@ -85,7 +85,9 @@ function Transition.new(game, onMidpoint, onDone, warp)
 end
 
 function Transition:finish()
-  self.game.stack:pop()
+  if self.done then return end
+  self.done = true
+  if not self.offStack then self.game.stack:pop() end
   if self.onDone then self.onDone() end
 end
 
@@ -96,10 +98,16 @@ function Transition:update(dt)
     self.t = 0
     if self.phase == "out" then
       self.phase = "in"
-      if self.onMidpoint then self.onMidpoint() end
       -- LoadGBPal restores the palettes in one write, so with no fade in the
       -- map is simply there on the next frame
-      if (self.framesIn or 0) <= 0 then self:finish() end
+      if (self.framesIn or 0) <= 0 then
+        self.offStack = true
+        self.game.stack:pop()
+        if self.onMidpoint then self.onMidpoint() end
+        self:finish()
+      elseif self.onMidpoint then
+        self.onMidpoint()
+      end
     else
       self:finish()
     end

src/render/Zoom.lua

@@ -19,6 +19,8 @@ Zoom.allowSurvey = true
 
 -- legal offset range for a given fit scale (vanilla: survey at 1 px/world
 -- through 2× fit).  zoom.range may widen or shrink the window.
+-- When the window only fits 1×, 1-S is 0 and there would be no OUT
+-- levels; keep three survey steps so OPTIONS always has zoom-out.
 function Zoom.offsetRange(S)
   S = math.max(1, math.floor(tonumber(S) or 1))
   local lo, hi = 1 - S, S
@@ -30,7 +32,11 @@ function Zoom.offsetRange(S)
   end
   -- LOW performance tier: no survey (negative offsets), even if a mod's
   -- zoom.range widened it.  == false so nil/true stays permissive.
-  if Zoom.allowSurvey == false and lo < 0 then lo = 0 end
+  if Zoom.allowSurvey == false then
+    if lo < 0 then lo = 0 end
+  elseif lo > -3 then
+    lo = -3
+  end
   return lo, hi
 end
 
@@ -44,6 +50,8 @@ function Zoom.scale(S)
   local maxScale = math.max(minScale, S + hi)
   if s < minScale then s = minScale end
   if s > maxScale then s = maxScale end
+  -- Integer offset below 1px/world (OPTIONS OUT on a 1× window): 1/2, 1/4, …
+  if s < 1 then s = 0.5 ^ (1 - s) end
   if s < 0.25 then s = 0.25 end
   return s
 end
@@ -79,6 +87,30 @@ function Zoom.applyOptions(opts)
   Zoom.offset = math.floor(tonumber(opts and opts.zoom) or 0)
 end
 
+-- Integer fit used when OPTIONS has no live renderer (launcher, title).
+function Zoom.windowFitScale()
+  if love and love.graphics and love.graphics.getDimensions then
+    local ww, wh = love.graphics.getDimensions()
+    ww, wh = tonumber(ww) or 0, tonumber(wh) or 0
+    if ww >= 160 and wh >= 144 then
+      return math.max(1, math.floor(math.min(ww / 160, wh / 144)))
+    end
+  end
+  return 1
+end
+
+-- One step of the OPTIONS ZOOM row (dir +1 in, -1 out).  Shared by Red
+-- and Gold so both ladders offer OUT / FIT / IN.
+function Zoom.nudgeOptions(options, dir, S)
+  S = math.max(1, math.floor(tonumber(S) or Zoom.windowFitScale()))
+  local lo, hi = Zoom.offsetRange(S)
+  local off = math.floor(tonumber(options and options.zoom) or 0) + (dir or 1)
+  if off > hi then off = lo elseif off < lo then off = hi end
+  if options then options.zoom = off end
+  Zoom.offset = off
+  return off
+end
+
 -- FIT / OUT1 / OUT2 / … / IN1 / IN2 / …
 function Zoom.offsetLabel(offset)
   offset = math.floor(tonumber(offset) or 0)

src/ui/OptionsMenu.lua

@@ -381,14 +381,7 @@ local function buildRows(game)
         return Zoom.offsetLabel(g.save.options.zoom or 0)
       end,
       step = function(g, dir)
-        local o = g.save.options
+        Zoom.nudgeOptions(g.save.options, dir, Renderer:fitScale())
-        local S = Renderer:fitScale()
-        local lo, hi = Zoom.offsetRange(S)
-        local off = (o.zoom or 0) + dir
-        if off > hi then off = lo
-        elseif off < lo then off = hi end
-        o.zoom = off
-        Zoom.offset = off
         return true
       end },
     { id = "voidFill", label = Strings("VOID FILL"),
@@ -580,8 +573,8 @@ local function buildRows(game)
     end
     rows = filtered
   end
-  -- ORIENTATION only on Android, the one platform Orientation.apply reaches.
+  -- ORIENTATION only on the platforms Orientation.apply reaches (#1638).
-  if not Orientation.isAndroid() then
+  if not (Orientation.isAndroid() or Orientation.isIOS()) then
     local filtered = {}
     for _, row in ipairs(rows) do
       if row.id ~= "orientation" then filtered[#filtered + 1] = row end

src/ui/PadCursor.lua

@@ -151,6 +151,7 @@ end
 
 function PadCursor.joystickpressed(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return nil end
+  if GamepadMap.isAccelerometer(joystick) then return nil end
   local padButton = GamepadMap.mapRawToGamepadButton(button)
   if padButton then return PadCursor.gamepadpressed(joystick, padButton) end
   return nil
@@ -158,12 +159,14 @@ end
 
 function PadCursor.joystickreleased(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   local padButton = GamepadMap.mapRawToGamepadButton(button)
   if padButton then PadCursor.gamepadreleased(joystick, padButton) end
 end
 
 function PadCursor.joystickaxis(joystick, axisIndex, value)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   if axisIndex == 1 then
     PadCursor.gamepadaxis(joystick, "leftx", value)
   elseif axisIndex == 2 then
@@ -173,6 +176,7 @@ end
 
 function PadCursor.joystickhat(joystick, hat, direction)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   for _, d in ipairs(rawHatDirs[hat] or {}) do
     dir[d] = nil
   end

src/ui/TradeAnim.lua

@@ -34,10 +34,12 @@ local DEFAULT_ART = {
   cableBall = "assets/generated/trade/cable_ball.png",
   cableBallAlt = "assets/generated/trade/cable_ball_alt.png",
   bubble = "assets/generated/trade/bubble.png",
+  moveAnim0 = "assets/generated/battle/anims/move_anim_0.png",
+  balls = "assets/generated/battle/balls.png",
 }
 
 local function tryImage(path)
-  if not path then return nil end
+  if not (path and love and love.graphics and love.graphics.newImage) then return nil end
   local ok, img = pcall(love.graphics.newImage, path)
   return ok and img or nil
 end
@@ -89,6 +91,92 @@ local SEQ = {
   "done",
 }
 
+-- FrameBlocks 03..08 definition for move_anim_0.png (128x40, 16 tiles/row, 8x8 per tile)
+local FRAME_BLOCKS = {
+  -- FrameBlock03: Pokeball normal (16x16)
+  [3] = {
+    { tile = 2,  dx = 0, dy = 0, xflip = false, yflip = false },
+    { tile = 2,  dx = 8, dy = 0, xflip = true,  yflip = false },
+    { tile = 18, dx = 0, dy = 8, xflip = false, yflip = false },
+    { tile = 18, dx = 8, dy = 8, xflip = true,  yflip = false },
+  },
+  -- FrameBlock04: Pokeball tilted left (16x16)
+  [4] = {
+    { tile = 6,  dx = 0, dy = 0, xflip = false, yflip = false },
+    { tile = 7,  dx = 8, dy = 0, xflip = false, yflip = false },
+    { tile = 22, dx = 0, dy = 8, xflip = false, yflip = false },
+    { tile = 23, dx = 8, dy = 8, xflip = false, yflip = false },
+  },
+  -- FrameBlock05: Pokeball tilted right (16x16)
+  [5] = {
+    { tile = 7,  dx = 0, dy = 0, xflip = true,  yflip = false },
+    { tile = 6,  dx = 8, dy = 0, xflip = true,  yflip = false },
+    { tile = 23, dx = 0, dy = 8, xflip = true,  yflip = false },
+    { tile = 22, dx = 8, dy = 8, xflip = true,  yflip = false },
+  },
+  -- FrameBlock06: Small Poof smoke cloud (32x32)
+  [6] = {
+    { tile = 0x23, dx = 8,  dy = 0,  xflip = false, yflip = false },
+    { tile = 0x32, dx = 0,  dy = 8,  xflip = false, yflip = false },
+    { tile = 0x33, dx = 8,  dy = 8,  xflip = false, yflip = false },
+    { tile = 0x23, dx = 16, dy = 0,  xflip = true,  yflip = false },
+    { tile = 0x33, dx = 16, dy = 8,  xflip = true,  yflip = false },
+    { tile = 0x32, dx = 24, dy = 8,  xflip = true,  yflip = false },
+    { tile = 0x32, dx = 0,  dy = 16, xflip = false, yflip = true  },
+    { tile = 0x33, dx = 8,  dy = 16, xflip = false, yflip = true  },
+    { tile = 0x23, dx = 8,  dy = 24, xflip = false, yflip = true  },
+    { tile = 0x33, dx = 16, dy = 16, xflip = true,  yflip = true  },
+    { tile = 0x32, dx = 24, dy = 16, xflip = true,  yflip = true  },
+    { tile = 0x23, dx = 16, dy = 24, xflip = true,  yflip = true  },
+  },
+  -- FrameBlock07: Medium Poof smoke cloud (32x32)
+  [7] = {
+    { tile = 0x20, dx = 0,  dy = 0,  xflip = false, yflip = false },
+    { tile = 0x21, dx = 8,  dy = 0,  xflip = false, yflip = false },
+    { tile = 0x30, dx = 0,  dy = 8,  xflip = false, yflip = false },
+    { tile = 0x31, dx = 8,  dy = 8,  xflip = false, yflip = false },
+    { tile = 0x21, dx = 16, dy = 0,  xflip = true,  yflip = false },
+    { tile = 0x20, dx = 24, dy = 0,  xflip = true,  yflip = false },
+    { tile = 0x31, dx = 16, dy = 8,  xflip = true,  yflip = false },
+    { tile = 0x30, dx = 24, dy = 8,  xflip = true,  yflip = false },
+    { tile = 0x30, dx = 0,  dy = 16, xflip = false, yflip = true  },
+    { tile = 0x31, dx = 8,  dy = 16, xflip = false, yflip = true  },
+    { tile = 0x20, dx = 0,  dy = 24, xflip = false, yflip = true  },
+    { tile = 0x21, dx = 8,  dy = 24, xflip = false, yflip = true  },
+    { tile = 0x31, dx = 16, dy = 16, xflip = true,  yflip = true  },
+    { tile = 0x30, dx = 24, dy = 16, xflip = true,  yflip = true  },
+    { tile = 0x21, dx = 16, dy = 24, xflip = true,  yflip = true  },
+    { tile = 0x20, dx = 24, dy = 24, xflip = true,  yflip = true  },
+  },
+  -- FrameBlock08: Large Poof smoke cloud (32x32)
+  [8] = {
+    { tile = 0x22, dx = 0,  dy = 0,  xflip = false, yflip = false },
+    { tile = 0x23, dx = 8,  dy = 0,  xflip = false, yflip = false },
+    { tile = 0x32, dx = 0,  dy = 8,  xflip = false, yflip = false },
+    { tile = 0x33, dx = 8,  dy = 8,  xflip = false, yflip = false },
+    { tile = 0x23, dx = 16, dy = 0,  xflip = true,  yflip = false },
+    { tile = 0x22, dx = 24, dy = 0,  xflip = true,  yflip = false },
+    { tile = 0x33, dx = 16, dy = 8,  xflip = true,  yflip = false },
+    { tile = 0x32, dx = 24, dy = 8,  xflip = true,  yflip = false },
+    { tile = 0x32, dx = 0,  dy = 16, xflip = false, yflip = true  },
+    { tile = 0x33, dx = 8,  dy = 16, xflip = false, yflip = true  },
+    { tile = 0x22, dx = 0,  dy = 24, xflip = false, yflip = true  },
+    { tile = 0x23, dx = 8,  dy = 24, xflip = false, yflip = true  },
+    { tile = 0x33, dx = 16, dy = 16, xflip = true,  yflip = true  },
+    { tile = 0x32, dx = 24, dy = 16, xflip = true,  yflip = true  },
+    { tile = 0x23, dx = 16, dy = 24, xflip = true,  yflip = true  },
+    { tile = 0x22, dx = 24, dy = 24, xflip = true,  yflip = true  },
+  },
+}
+
+-- BallMoveDistances1 (engine/battle/animations.asm:881)
+-- Pokéball jumps up into the open link cable nozzle: -12, -12, -8 (3 frames each)
+local BALL_SUCTION_DISTANCES = { -12, -12, -8 }
+
+-- BallMoveDistances2 (engine/battle/animations.asm:922)
+-- Incoming Pokéball bounces out of nozzle onto the ground: 11, 12, -12, -7, 7, 12, -8, 8 (5 frames each)
+local BALL_BOUNCE_DISTANCES = { 11, 12, -12, -7, 7, 12, -8, 8 }
+
 function TradeAnim.new(game, opts)
   opts = opts or {}
   local self = setmetatable({}, TradeAnim)
@@ -120,6 +208,8 @@ function TradeAnim.new(game, opts)
     cableBall = tryImage(art.cableBall or DEFAULT_ART.cableBall),
     cableBallAlt = tryImage(art.cableBallAlt or DEFAULT_ART.cableBallAlt),
     bubble = tryImage(art.bubble or DEFAULT_ART.bubble),
+    moveAnim0 = tryImage(DEFAULT_ART.moveAnim0),
+    balls = tryImage(DEFAULT_ART.balls),
   }
   self.sentSprite, self.sentSpriteTrueColor = spriteOf(game, self.sent)
   self.recvSprite, self.recvSpriteTrueColor = spriteOf(game, self.received)
@@ -136,6 +226,14 @@ function TradeAnim.new(game, opts)
   self.monVisible = true
   self.waitingText = false
   self.cableFlash = false
+  self.activeBallBlock = nil
+  self.activeBallX = 0
+  self.activeBallY = 0
+  self.activePoofBlock = nil
+  self.activePoofX = 0
+  self.activePoofY = 0
+  self.wx = 0
+  self.slidingBox = false
   return self
 end
 
@@ -151,52 +249,100 @@ function TradeAnim:advance()
   self.sub = nil
   self.flash = false
   self.cableFlash = false
-  self.poof = nil
+  self.activeBallBlock = nil
+  self.activePoofBlock = nil
+  self.slidingBox = false
+  self.wx = 0
+
   if self.phase == "done" then
     self.game.stack:pop()
     if self.onDone then self.onDone() end
   elseif self.phase == "show_enemy" then
     self.monVisible = false
+    self.activeBallBlock = 4
+    self.activeBallX, self.activeBallY = 72, 40
+    self.activePoofBlock = nil
+    self.cableSlideOut = 0
   elseif self.phase == "transfer_lr" then
-    -- wBaseCoord $54, $1c OAM -> screen (76, 12)
+    -- BaseCoord $54, $1c -> Screen (92, 28) for 16x16 icon (center 100, 36)
-    self.monX, self.monY = 76, 12
+    self.monX, self.monY = 92, 28
+    self.scx = 0
   elseif self.phase == "transfer_rl" then
-    -- wBaseCoord $64, $44 OAM -> screen (92, 52), right GB on screen
+    -- BaseCoord $64, $44 -> Screen (108, 68) for 16x16 icon (center 116, 76)
-    self.monX, self.monY = 92, 52
+    self.monX, self.monY = 108, 68
-    self.scx = 160
+    self.scx = 256
   elseif self.phase == "ball_enter" then
-    -- lb bc, $20, $60: b = Y, c = X (Trade_AnimateBallEnteringLinkCable)
+    -- Pokéball sits at BaseCoord $48 (Screen 72, 64) before shake and suction
+    self.activeBallBlock = 3
+    self.activeBallX, self.activeBallY = 72, 64
     self.ballX, self.ballY = 0x60, 0x20
   elseif self.phase == "open_cable" or self.phase == "open_cable2" then
-    -- SCX $a0 -> $f0: cable slides in from the right, open end rests at x64
+    -- SCX $a0 (160) -> $f0 (240): cable slides in from right, open end rests at x64
-    self.scx = 0x50
+    self.scx = 80
+    if self.phase == "open_cable" then
+      self.activeBallBlock = 3
+      self.activeBallX, self.activeBallY = 72, 64
+    end
     Sound.play(self.game.data, "Heal_HP")
   end
 end
 
-function TradeAnim:say(text, delay, thenFn)
+function TradeAnim:skipHeld()
-  self.waitingText = true
+  return self.game.input:wasPressed("a") or self.game.input:wasPressed("b")
-  self.game.stack:push(TextBox.new(self.game, text, function()
-    self.waitingText = false
-    if thenFn then thenFn() else self:advance() end
-  end, { auto = { delay = delay or 80 } }))
 end
 
-function TradeAnim:skipHeld()
+function TradeAnim:drawFrameBlock(blockId, x, y)
-  return self.game.input:wasPressed("a") or self.game.input:isDown("a")
+  local block = FRAME_BLOCKS[blockId]
+  if not block then return end
+  if self.img.moveAnim0 then
+    local iw, ih = self.img.moveAnim0:getDimensions()
+    for _, tile in ipairs(block) do
+      local tx = (tile.tile % 16) * 8
+      local ty = math.floor(tile.tile / 16) * 8
+      local quad = love.graphics.newQuad(tx, ty, 8, 8, iw, ih)
+      local sx = tile.xflip and -1 or 1
+      local sy = tile.yflip and -1 or 1
+      local ox = tile.xflip and 8 or 0
+      local oy = tile.yflip and 8 or 0
+      love.graphics.draw(self.img.moveAnim0, quad, x + tile.dx + ox, y + tile.dy + oy, 0, sx, sy)
+    end
+  else
+    if blockId == 3 or blockId == 4 or blockId == 5 then
+      love.graphics.setColor(0.9, 0.2, 0.2, 1)
+      love.graphics.arc("fill", x + 8, y + 8, 7, math.pi, 0)
+      love.graphics.setColor(0.9, 0.9, 0.9, 1)
+      love.graphics.arc("fill", x + 8, y + 8, 7, 0, math.pi)
+      love.graphics.setColor(0, 0, 0, 1)
+      love.graphics.circle("line", x + 8, y + 8, 7)
+      love.graphics.line(x + 1, y + 8, x + 15, y + 8)
+      love.graphics.circle("fill", x + 8, y + 8, 2)
+      love.graphics.setColor(1, 1, 1, 1)
+    elseif blockId == 6 or blockId == 7 or blockId == 8 then
+      local r = (blockId - 5) * 5
+      love.graphics.setColor(0.8, 0.8, 0.8, 0.8)
+      love.graphics.circle("fill", x + 16, y + 16, r)
+      love.graphics.setColor(1, 1, 1, 1)
+    end
+  end
 end
 
 function TradeAnim:update(dt)
   if self.waitingText or self.phase == "done" then return end
-  local skip = self.game.input:wasPressed("a")
+  local skip = self:skipHeld()
   self.t = self.t + 1
   local p = self.phase
 
   if p == "show_player" then
-    -- slide from SCX $86 -> 0, hold 80, poof, cry (Trade_ShowPlayerMon)
+    -- Trade_ShowPlayerMon:
+    -- 1. Slide from SCX $7e (126) -> 0 at 2px/frame (63 frames)
+    -- 2. Hold 80 frames
+    -- 3. TRADE_BALL_POOF_ANIM at BaseCoord $72 (Screen 64, 48): 3 frames x 6 ticks = 18 ticks
+    -- 4. TRADE_BALL_DROP_ANIM: mon vanishes, ball drops $41 (72, 56) -> $48 (72, 64) over 36 ticks
+    -- 5. PlayCry while ball sits on ground at (72, 64)
     if not self.sub then self.sub = "slide" end
+
     if self.sub == "slide" then
-      self.scx = math.max(0, 0x86 - self.t * 2)
+      self.scx = math.max(0, 126 - self.t * 2)
       if skip or self.scx <= 0 then
         self.scx = 0
         self.sub = "hold"
@@ -206,52 +352,131 @@ function TradeAnim:update(dt)
       if skip or self.t >= 80 then
         self.sub = "poof"
         self.t = 0
-        self.monVisible = false
         Sound.play(self.game.data, "Ball_Poof")
       end
     elseif self.sub == "poof" then
-      self.poof = math.max(0, 16 - self.t)
+      local step = math.floor(self.t / 6)
-      if skip or self.t >= 16 then
+      if step >= 3 or skip then
+        self.sub = "ball_drop"
+        self.t = 0
+        self.activePoofBlock = nil
+        self.monVisible = false
+      else
+        self.activePoofBlock = 6 + step
+        self.activePoofX, self.activePoofY = 64, 48
+      end
+    elseif self.sub == "ball_drop" then
+      if skip or self.t >= 36 then
+        self.sub = "cry"
+        self.t = 0
+        self.activeBallBlock = 3
+        self.activeBallX, self.activeBallY = 72, 64
         Sound.playCry(self.game.data, self.sent.species)
+      else
+        local step = math.floor(self.t / 6)
+        if step == 0 then
+          self.activeBallBlock = 3
+          self.activeBallX, self.activeBallY = 72, 56
+        else
+          local blocks = { 3, 4, 3, 5, 3 }
+          self.activeBallBlock = blocks[step] or 3
+          self.activeBallX, self.activeBallY = 72, 64
+        end
+      end
+    elseif self.sub == "cry" then
+      if skip or self.t >= 40 then
         self.sub = nil
         self:advance()
       end
     end
 
   elseif p == "open_cable" or p == "open_cable2" then
-    -- 20 steps of 4px, matching the SCX loop
+    -- Trade_DrawOpenEndOfLinkCable: SCX $a0 (160) -> $f0 (240) in 20 steps of 4px
-    self.scx = math.max(0, 0x50 - self.t * 4)
+    self.scx = math.max(0, 80 - self.t * 4)
     if skip or self.scx <= 0 then
       self.scx = 0
       self:advance()
     end
 
   elseif p == "ball_enter" then
-    -- TRADE_BALL_SHAKE then ball rides the cable; X from $60 toward $a0
+    -- Trade_AnimateBallEnteringLinkCable:
-    if self.t < 20 then
+    -- 1. TRADE_BALL_SHAKE_ANIM (16 ticks) + TradeShakePokeball suction jump (-12, -12, -8 over 9 ticks):
-      if skip then self.t = 20 end
+    --    - Shakes at (72, 64) for 16 ticks (FrameBlock 04, 03, 05, 03)
-      return
+    --    - Jumps up: Y=52 (3 ticks), Y=40 (3 ticks), Y=32 (3 ticks)
+    --    - Ball cleared, SFX_TRADE_MACHINE plays
+    -- 2. DelayFrames 10 (chills for 10 frames)
+    -- 3. Ball inside horizontal cable: 16 steps of +4px every 3 frames (48 frames) with Tink sfx & bulge toggle
+    -- 4. Delay3
+    if not self.sub then self.sub = "shake" end
+
+    if self.sub == "shake" then
+      if skip or self.t >= 16 then
+        self.sub = "jump_up"
+        self.t = 0
+      else
+        local shakeBlocks = { 4, 3, 5, 3 }
+        local step = math.floor(self.t / 4) + 1
+        self.activeBallBlock = shakeBlocks[step] or 3
+        self.activeBallX, self.activeBallY = 72, 64
+      end
+    elseif self.sub == "jump_up" then
+      local step = math.floor(self.t / 3) + 1
+      if step > #BALL_SUCTION_DISTANCES or skip then
+        self.sub = "chill"
+        self.t = 0
+        self.activeBallBlock = nil
+        Sound.play(self.game.data, "Trade_Machine")
+      else
+        local yPos = 64
+        for i = 1, step do
+          yPos = yPos + BALL_SUCTION_DISTANCES[i]
+        end
+        self.activeBallBlock = 3
+        self.activeBallX, self.activeBallY = 72, yPos
+      end
+    elseif self.sub == "chill" then
+      if skip or self.t >= 10 then
+        self.sub = "suction"
+        self.t = 0
+        self.ballX = 0x60
+      end
+    elseif self.sub == "suction" then
+      local step = math.floor(self.t / 3)
+      if step >= 16 or skip then
+        self.sub = "exit_pause"
+        self.t = 0
+        self.ballX = 0xA0
+      else
+        self.ballX = 0x60 + step * 4
+        self.flash = (step % 2 == 1)
+        if self.t % 3 == 0 and step < 16 then
+          Sound.play(self.game.data, "Tink")
+        end
+      end
+    elseif self.sub == "exit_pause" then
+      if skip or self.t >= 3 then
+        self.sub = nil
+        self:advance()
       end
-    local step = self.t - 20
-    if step % 3 == 0 then
-      self.ballX = 0x60 + math.floor(step / 3) * 4
-      self.flash = not self.flash
-      if self.ballX < 0xA0 then Sound.play(self.game.data, "Tink") end
     end
-    if skip then self.ballX = 0xA0 end
-    if self.ballX >= 0xA0 then self:advance() end
 
   elseif p == "transfer_lr" then
-    -- scroll left GB off while the mon rides the cable, then the sprite
+    -- 16 units of 16px (256px total scroll) at 2px/frame = 128 frames (SCX 0 -> 256)
-    -- itself moves right and down into the right GB (Trade_AnimMonMoveVertical)
+    if self.t <= 128 then
-    if self.t <= 80 then
+      self.scx = math.min(256, self.t * 2)
-      self.scx = math.min(160, self.t * 2)
+      self.monX, self.monY = 92, 28
-      self.monX, self.monY = 76, 12
+    elseif self.t <= 128 + 32 then
-    elseif self.t <= 80 + 32 then
+      local step = math.floor((self.t - 128) / 8) + 1
-      self.monX = 76 + math.floor((self.t - 80) / 8) * 4
+      step = math.min(4, step)
-    elseif self.t <= 80 + 64 then
+      self.scx = 256
-      self.monX = 92
+      self.monX = 92 + step * 4
-      self.monY = 12 + math.floor((self.t - 112) / 8) * 10
+      self.monY = 28
+    elseif self.t <= 128 + 64 then
+      local step = math.floor((self.t - 160) / 8) + 1
+      step = math.min(4, step)
+      self.scx = 256
+      self.monX = 108
+      self.monY = 28 + step * 10
     else
       self:advance()
       return
@@ -260,17 +485,22 @@ function TradeAnim:update(dt)
     if skip then self:advance() end
 
   elseif p == "transfer_rl" then
-    -- mirror: sprite climbs out of the right GB, then the screen scrolls
+    -- 64 frames vertical ascent + 128 frames horizontal scroll (SCX 256 -> 0)
-    -- back to the left GB
     if self.t <= 32 then
-      self.scx = 160
+      local step = math.floor(self.t / 8) + 1
-      self.monX, self.monY = 92, 52 - math.floor(self.t / 8) * 10
+      step = math.min(4, step)
+      self.scx = 256
+      self.monX = 108
+      self.monY = 68 - step * 10
     elseif self.t <= 64 then
-      self.monX = 92 - math.floor((self.t - 32) / 8) * 4
+      local step = math.floor((self.t - 32) / 8) + 1
-      self.monY = 12
+      step = math.min(4, step)
-    elseif self.t <= 64 + 80 then
+      self.scx = 256
-      self.scx = math.max(0, 160 - (self.t - 64) * 2)
+      self.monX = 108 - step * 4
-      self.monX, self.monY = 76, 12
+      self.monY = 28
+    elseif self.t <= 64 + 128 then
+      self.scx = math.max(0, 256 - (self.t - 64) * 2)
+      self.monX, self.monY = 92, 28
     else
       self:advance()
       return
@@ -282,54 +512,185 @@ function TradeAnim:update(dt)
     if skip or self.t >= 100 then self:advance() end
 
   elseif p == "went_to" then
+    if not self.sub then
+      self.sub = "text"
+      self.t = 0
       local text = expand(self.game, "_TradeWentToText", {
         ["RAM:wStringBuffer"] = speciesName(self.game, self.sent),
         ["RAM:wLinkEnemyTrainerName"] = self.enemyName,
       })
-    self:say(text, 200)
+      self.dialogText = text
+    end
+
+    if self.sub == "text" then
+      if skip or self.t >= 200 then
+        self.sub = "slide_hold"
+        self.t = 0
+      end
+    elseif self.sub == "slide_hold" then
+      if skip or self.t >= 50 then
+        self.sub = "slide_off"
+        self.t = 0
+        self.slidingBox = true
+      end
+    elseif self.sub == "slide_off" then
+      self.wx = math.min(160, self.t * 2)
+      if skip or self.wx >= 160 then
+        self.wx = 160
+        self.sub = "slide_end_pause"
+        self.t = 0
+      end
+    elseif self.sub == "slide_end_pause" then
+      if skip or self.t >= 10 then
+        self.slidingBox = false
+        self.dialogText = nil
+        self.sub = nil
+        self:advance()
+      end
+    end
 
   elseif p == "for_sends" then
-    local a = expand(self.game, "_TradeForText", {
+    if not self.sub then
+      self.sub = "for_text"
+      self.t = 0
+      self.dialogText = expand(self.game, "_TradeForText", {
         ["RAM:wStringBuffer"] = speciesName(self.game, self.sent),
       })
-    local b = expand(self.game, "_TradeSendsText", {
+    end
+
+    if self.sub == "for_text" then
+      if skip or self.t >= 80 then
+        self.sub = "sends_text"
+        self.t = 0
+        self.dialogText = expand(self.game, "_TradeSendsText", {
           ["RAM:wLinkEnemyTrainerName"] = self.enemyName,
           ["RAM:wNameBuffer"] = nameOf(self.game, self.received),
         })
-    self.waitingText = true
+      end
-    self.game.stack:push(TextBox.new(self.game, a, function()
+    elseif self.sub == "sends_text" then
-      self.game.stack:push(TextBox.new(self.game, b, function()
+      if skip or self.t >= 80 then
-        self.waitingText = false
+        self.dialogText = nil
+        self.sub = nil
         self:advance()
-      end, { auto = { delay = 80 } }))
+      end
-    end, { auto = { delay = 80 } }))
+    end
 
   elseif p == "farewell" then
-    local a = expand(self.game, "_TradeWavesFarewellText", {
+    if not self.sub then
+      self.sub = "farewell_text"
+      self.t = 0
+      self.dialogText = expand(self.game, "_TradeWavesFarewellText", {
         ["RAM:wLinkEnemyTrainerName"] = self.enemyName,
       })
-    local b = expand(self.game, "_TradeTransferredText", {
+    end
+
+    if self.sub == "farewell_text" then
+      if skip or self.t >= 80 then
+        self.sub = "transferred_text"
+        self.t = 0
+        self.dialogText = expand(self.game, "_TradeTransferredText", {
           ["RAM:wNameBuffer"] = nameOf(self.game, self.received),
         })
-    self.waitingText = true
+      end
-    self.game.stack:push(TextBox.new(self.game, a, function()
+    elseif self.sub == "transferred_text" then
-      self.game.stack:push(TextBox.new(self.game, b, function()
+      if skip or self.t >= 80 then
-        self.waitingText = false
+        self.sub = "slide_hold"
+        self.t = 0
+      end
+    elseif self.sub == "slide_hold" then
+      if skip or self.t >= 50 then
+        self.sub = "slide_off"
+        self.t = 0
+        self.slidingBox = true
+      end
+    elseif self.sub == "slide_off" then
+      self.wx = math.min(160, self.t * 2)
+      if skip or self.wx >= 160 then
+        self.wx = 160
+        self.sub = "slide_end_pause"
+        self.t = 0
+      end
+    elseif self.sub == "slide_end_pause" then
+      if skip or self.t >= 10 then
+        self.slidingBox = false
+        self.dialogText = nil
+        self.sub = nil
         self:advance()
-      end, { auto = { delay = 80 } }))
+      end
-    end, { auto = { delay = 80 } }))
+    end
 
   elseif p == "show_enemy" then
-    if self.t == 1 then
+    -- Trade_ShowEnemyMon (engine/movie/trade.asm:354):
-      Sound.play(self.game.data, "Ball_Poof")
+    -- 1. TRADE_BALL_TILT_ANIM with TradeJumpPokeball (8 bounce steps, 5 ticks each = 40 ticks):
+    --    - Starts at BaseCoord $84 (Screen X=72, Y=40)
+    --    - Moves Y by BallMoveDistances2 (+11, +12, -12, -7, +7, +12, -8, +8)
+    --    - On each step: Cable slides off-screen right by 8px
+    --    - Plays SFX_SWAP on impacts
+    -- 2. ClearScreen, Info box at (4, 10), Mon front sprite at (7, 2)
+    -- 3. TRADE_BALL_POOF_ANIM: FrameBlock 06, 07, 08 (18 ticks), SFX_BALL_POOF, revealing mon
+    -- 4. PlayCry
+    -- 5. Trade_Delay100
+    -- 6. Info box cleared, PrintTradeTakeCareText (80 ticks)
+    -- 7. Trade_Delay100 -> finish
+    if not self.sub then
+      self.sub = "ball_bounce"
+      self.t = 0
+      self.cableSlideOut = 0
+      self.activeBallBlock = 4
+      self.activeBallX, self.activeBallY = 72, 40
+    end
+
+    if self.sub == "ball_bounce" then
+      local step = math.floor(self.t / 5) + 1
+      if step > #BALL_BOUNCE_DISTANCES or skip then
+        self.sub = "poof"
+        self.t = 0
+        self.activeBallBlock = nil
         self.monVisible = true
-    elseif self.t == 20 then
+        self.cableSlideOut = nil
+        Sound.play(self.game.data, "Ball_Poof")
+      else
+        local yPos = 40
+        for i = 1, step do
+          yPos = yPos + BALL_BOUNCE_DISTANCES[i]
+        end
+        self.activeBallBlock = 4
+        self.activeBallX, self.activeBallY = 72, yPos
+        self.cableSlideOut = (step - 1) * 8
+        if self.t % 5 == 0 and (BALL_BOUNCE_DISTANCES[step] == 12 or step == #BALL_BOUNCE_DISTANCES) then
+          Sound.play(self.game.data, "Swap")
+        end
+      end
+    elseif self.sub == "poof" then
+      local step = math.floor(self.t / 6)
+      if step >= 3 or skip then
+        self.sub = "cry"
+        self.t = 0
+        self.activePoofBlock = nil
         Sound.playCry(self.game.data, self.received.species)
-    elseif self.t >= 120 or skip then
+      else
-      local text = expand(self.game, "_TradeTakeCareText", {
+        self.activePoofBlock = 6 + step
+        self.activePoofX, self.activePoofY = 64, 48
+      end
+    elseif self.sub == "cry" then
+      if skip or self.t >= 100 then
+        self.sub = "take_care"
+        self.t = 0
+        self.dialogText = expand(self.game, "_TradeTakeCareText", {
           ["RAM:wNameBuffer"] = nameOf(self.game, self.received),
         })
-      self:say(text, 80)
+      end
+    elseif self.sub == "take_care" then
+      if skip or self.t >= 80 then
+        self.sub = "delay_end"
+        self.t = 0
+        self.dialogText = nil
+      end
+    elseif self.sub == "delay_end" then
+      if skip or self.t >= 100 then
+        self.sub = nil
+        self:advance()
+      end
     end
   end
 end
@@ -337,10 +698,18 @@ end
 local function drawCableHoriz(self, y, x0, x1)
   local w = math.max(0, x1 - x0)
   if w <= 0 then return end
+  if self.cableFlash then
+    love.graphics.setColor(0.65, 0.65, 0.65, 1)
+  else
+    love.graphics.setColor(1, 1, 1, 1)
+  end
   if self.img.cableHoriz then
     local iw, ih = self.img.cableHoriz:getDimensions()
-    local quad = love.graphics.newQuad(0, 0, math.min(w, iw), ih, iw, ih)
+    for x = x0, x1 - 1, iw do
-    love.graphics.draw(self.img.cableHoriz, quad, x0, y)
+      local drawW = math.min(iw, x1 - x)
+      local quad = love.graphics.newQuad(0, 0, drawW, ih, iw, ih)
+      love.graphics.draw(self.img.cableHoriz, quad, x, y)
+    end
   elseif self.img.cableSeg then
     for x = x0, x1 - 8, 8 do
       love.graphics.draw(self.img.cableSeg, x, y)
@@ -348,13 +717,11 @@ local function drawCableHoriz(self, y, x0, x1)
   else
     love.graphics.setColor(0.2, 0.2, 0.2, 1)
     love.graphics.rectangle("fill", x0, y + 1, w, 6)
-    love.graphics.setColor(1, 1, 1, 1)
   end
+  love.graphics.setColor(1, 1, 1, 1)
 end
 
 function TradeAnim:drawMonInfo(mon, ot, otId, boxTy)
-  -- Trade_PrintPlayerMonInfoText: rows +0/+2/+4/+6 from the box top; the
-  -- No. line replaces part of the top border (hlcoord 5, 0 in trade2.asm)
   Font.drawBox(4, boxTy, 12, 8)
   local y0 = boxTy * 8
   local no = ("No.%03d"):format(dexOf(self.game, mon))
@@ -368,16 +735,6 @@ function TradeAnim:drawMonInfo(mon, ot, otId, boxTy)
   love.graphics.setColor(1, 1, 1, 1)
 end
 
--- Trade_WriteCircledMonOAM: the mon crosses the cable as its party-menu
--- sprite (wMonPartySpriteSpecies -> WriteMonPartySpriteOAMBySpecies), not as
--- its battle pic, and Trade_AnimCircledMon flips both it and the ring to
--- their second frame every step.  The ring is four OAM blocks --
--- Trade_CircleOAMBlocks .OAMBlock0-3 at (8,8) (24,8) (8,24) (24,24) with the
--- X/Y flips -- so the 16x32 bubble sheet holds one quadrant per frame and the
--- circle it makes is 32x32 around the 16x16 icon.  The icon rides OAM
--- block 0 and the circle blocks 1-4 (Trade_WriteCircleOAMBlock counts a up
--- from 1), and the lower OAM index wins overlap on DMG, so the icon draws
--- on top of the circle's filled interior.  #750
 function TradeAnim:drawIconInBubble(mon, x, y)
   if self.img.bubble then
     if not self.bubbleQuad then
@@ -415,11 +772,14 @@ function TradeAnim:drawGameBoy(x, y)
 end
 
 function TradeAnim:drawLeftGB()
-  -- cable from GB to the right edge
+  if self.cableFlash then
+    love.graphics.setColor(0.65, 0.65, 0.65, 1)
+  end
   if self.img.cableConn then
     love.graphics.draw(self.img.cableConn, 88, 32)
   end
-  drawCableHoriz(self, 32, 96, 160)
+  love.graphics.setColor(1, 1, 1, 1)
+  drawCableHoriz(self, 32, 96, 256)
   self:drawGameBoy(40, 24)
   Font.drawBox(4, 12, 9, 4)
   love.graphics.setColor(0, 0, 0, 1)
@@ -429,6 +789,9 @@ end
 
 function TradeAnim:drawRightGB()
   drawCableHoriz(self, 32, 0, 112)
+  if self.cableFlash then
+    love.graphics.setColor(0.65, 0.65, 0.65, 1)
+  end
   if self.img.cableCorner then love.graphics.draw(self.img.cableCorner, 112, 32) end
   if self.img.cableVert then
     for i = 1, 4 do
@@ -437,6 +800,7 @@ function TradeAnim:drawRightGB()
   end
   if self.img.cableEnd then love.graphics.draw(self.img.cableEnd, 112, 72) end
   if self.img.cableConn then love.graphics.draw(self.img.cableConn, 104, 72) end
+  love.graphics.setColor(1, 1, 1, 1)
   self:drawGameBoy(56, 64)
   Font.drawBox(6, 0, 9, 4)
   love.graphics.setColor(0, 0, 0, 1)
@@ -444,6 +808,24 @@ function TradeAnim:drawRightGB()
   love.graphics.setColor(1, 1, 1, 1)
 end
 
+function TradeAnim:drawDialog()
+  if not self.dialogText then return end
+  love.graphics.push()
+  if self.slidingBox then
+    love.graphics.translate(self.wx, 0)
+  end
+  Font.drawBox(0, 12, 20, 6)
+  love.graphics.setColor(0, 0, 0, 1)
+  local lines = {}
+  for line in self.dialogText:gmatch("[^\n]+") do
+    lines[#lines + 1] = line
+  end
+  if lines[1] then Font.draw(lines[1], 8, 112) end
+  if lines[2] then Font.draw(lines[2], 8, 128) end
+  love.graphics.setColor(1, 1, 1, 1)
+  love.graphics.pop()
+end
+
 function TradeAnim:draw()
   love.graphics.setColor(1, 1, 1, 1)
   love.graphics.rectangle("fill", 0, 0, 160, 144)
@@ -452,10 +834,7 @@ function TradeAnim:draw()
   if p == "show_player" then
     love.graphics.push()
     love.graphics.translate(-self.scx, 0)
-    -- mon pic on the BG at hlcoord 7, 2; info box on the window at
-    -- hWY $50, so it sits in the bottom half of the screen
     if self.monVisible and self.sentSprite then
-      -- engine/movie/trade.asm:751
       love.graphics.draw(self.sentSprite, 56 + self.sentSprite:getWidth(), 16, 0, -1, 1)
       if self.sentSpriteTrueColor then
         require("src.render.PaletteFX").markTrueColor(
@@ -464,25 +843,32 @@ function TradeAnim:draw()
     end
     self:drawMonInfo(self.sent, self.playerOt, self.playerOtId, 10)
     love.graphics.pop()
-    if self.poof and self.poof > 0 then
+
-      love.graphics.setColor(0, 0, 0, self.poof / 16)
+    if self.activePoofBlock then
-      love.graphics.circle("fill", 80, 40, 20 - (self.poof or 0))
+      self:drawFrameBlock(self.activePoofBlock, self.activePoofX, self.activePoofY)
-      love.graphics.setColor(1, 1, 1, 1)
+    end
+    if self.activeBallBlock then
+      self:drawFrameBlock(self.activeBallBlock, self.activeBallX, self.activeBallY)
     end
 
   elseif p == "open_cable" or p == "open_cable2" then
     love.graphics.push()
     love.graphics.translate(self.scx, 0)
     if self.img.openCable then
-      love.graphics.draw(self.img.openCable, 64, 16) -- open end at SCX $f0
+      love.graphics.draw(self.img.openCable, 64, 16)
     end
     love.graphics.pop()
+    if p == "open_cable" and self.activeBallBlock then
+      self:drawFrameBlock(self.activeBallBlock, self.activeBallX, self.activeBallY)
+    end
 
   elseif p == "ball_enter" then
     if self.img.openCable then
       love.graphics.draw(self.img.openCable, 64, 16)
     end
-    -- OAM coords carry a (+8, +16) hardware offset
+    if self.activeBallBlock then
+      self:drawFrameBlock(self.activeBallBlock, self.activeBallX, self.activeBallY)
+    elseif self.sub == "suction" or self.sub == "exit_pause" then
       local ball = self.flash and (self.img.cableBallAlt or self.img.cableBall)
                   or self.img.cableBall
       if ball then
@@ -492,36 +878,44 @@ function TradeAnim:draw()
         love.graphics.circle("fill", self.ballX, self.ballY - 8, 6)
         love.graphics.setColor(1, 1, 1, 1)
       end
+    end
 
   elseif p == "transfer_lr" or p == "transfer_rl" then
-    -- two-screen world: left GB scene at x0, right GB scene at x160;
-    -- the mon icon stays in screen space like the OAM sprite it ports
     love.graphics.push()
     love.graphics.translate(-self.scx, 0)
     self:drawLeftGB()
-    love.graphics.translate(160, 0)
+    love.graphics.translate(256, 0)
     self:drawRightGB()
     love.graphics.pop()
     local mon = p == "transfer_lr" and self.sent or self.received
     self:drawIconInBubble(mon, self.monX, self.monY)
-    if self.cableFlash then
-      love.graphics.setColor(1, 1, 1, 0.15)
-      love.graphics.rectangle("fill", 0, 32, 160, 8)
-      love.graphics.setColor(1, 1, 1, 1)
-    end
 
   elseif p == "show_enemy" then
+    if self.cableSlideOut and self.img.openCable then
+      love.graphics.push()
+      love.graphics.translate(self.cableSlideOut, 0)
+      love.graphics.draw(self.img.openCable, 64, 16)
+      love.graphics.pop()
+    end
     if self.monVisible and self.recvSprite then
-      -- engine/movie/trade.asm:751
       love.graphics.draw(self.recvSprite, 56 + self.recvSprite:getWidth(), 16, 0, -1, 1)
       if self.recvSpriteTrueColor then
         require("src.render.PaletteFX").markTrueColor(
           56, 16, self.recvSprite:getDimensions())
       end
     end
+    if self.monVisible and self.sub ~= "take_care" and self.sub ~= "delay_end" then
       self:drawMonInfo(self.received, self.enemyName, self.enemyOtId, 10)
     end
-  -- went_to / for_sends / farewell / delay: cleared window; TextBox draws
+    if self.activeBallBlock then
+      self:drawFrameBlock(self.activeBallBlock, self.activeBallX, self.activeBallY)
+    end
+    if self.activePoofBlock then
+      self:drawFrameBlock(self.activePoofBlock, self.activePoofX, self.activePoofY)
+    end
+  end
+
+  self:drawDialog()
 end
 
 return TradeAnim

src/ui/gen2/BattleState.lua

@@ -2707,7 +2707,9 @@ function BattleState:pushCaught(enemy, itemId)
   -- so the contest branch is BELOW them (item_effects.asm:528-546), and
   -- CheckReceivedDex gates the pair (:532-533).
   if not knew and self:hasPokedex() then
+    -- data/text/common_3.asm:285
     self:push({ kind = "message",
+      sfx = "Sfx_SlotMachineStart", waitSfx = true,
       text = self:name(enemy) .. "'s data was newly added to the #DEX." })
     self:push({ kind = "dex-entry", species = enemy.species })
   end

src/ui/gen2/BoxMenu.lua

@@ -47,6 +47,7 @@ local Font = require("src.render.Font")
 local GbcPalette = require("src.render.GbcPalette")
 local Mail = require("src.core.gen2.Mail")
 local Palettes = require("src.world.gen2.Palettes")
+local PartyMenu = require("src.ui.gen2.PartyMenu")
 local Screens = require("src.ui.Screens")
 local Sound = require("src.core.Sound")
 local Unown = require("src.core.gen2.Unown")
@@ -65,6 +66,21 @@ local PIC_X, PIC_Y = 1, 4
 -- 7-size blank tiles per column (engine/gfx/load_pics.asm:342-386).
 local PIC_PAD = { [7] = { 0, 0 }, [6] = { 1, 1 }, [5] = { 1, 2 } }
 
+-- gfx/pc/orange.pal
+local BILLS_PC_ORANGE = {
+  { 255, 123, 0 }, { 189, 99, 0 }, { 123, 58, 0 }, { 0, 0, 0 },
+}
+
+-- PCMonInfo prints the held-item icon at hlcoord 7, 12
+-- (engine/pokemon/bills_pc.asm:1093).
+local ICON_X, ICON_Y = 7, 12
+
+-- $5f at hlcoord 8, 1 and $5e at hlcoord 19, 1, off a PCMailGFX sheet that
+-- starts at $5c (engine/pokemon/bills_pc.asm:957-963).
+local ARROW_ROW = 1
+local ARROW_LEFT = { 3, 8 }
+local ARROW_RIGHT = { 2, 19 }
+
 -- wBillsPC_LoadedBox: 0 is the PARTY, 1..NUM_BOXES are the boxes.  Only the
 -- MOVE screen ever loads box 0; the withdraw and deposit lists are one list
 -- each (BillsPC_BoxName reads the same byte for all three).
@@ -272,6 +288,8 @@ function BoxMenu:beginMove()
     -- to the submenu; here the message holds until a button clears it and the
     -- list comes back, which is the same place the player ends up.
     self.phase = nil
+    -- engine/pokemon/bills_pc.asm:1607
+    self:playSfx("Sfx_Wrong")
     self.message = reason
     return
   end
@@ -299,9 +317,13 @@ end
 function BoxMenu:doWithdraw()
   local ok, result = Boxes.withdraw(self.save, self.boxIndex, self.index)
   if not ok then
+    -- engine/pokemon/bills_pc.asm:1845
+    self:playSfx("Sfx_Wrong")
     self.message = result
     return
   end
+  -- engine/pokemon/bills_pc.asm:1817
+  self:playMonCry(result)
   self.message = nil
   self.phase = nil
   self:clampIndex()
@@ -311,9 +333,13 @@ end
 function BoxMenu:doDeposit()
   local ok, result = Boxes.deposit(self.save, self.index, self.boxIndex)
   if not ok then
+    -- engine/pokemon/bills_pc.asm:1790
+    self:playSfx("Sfx_Wrong")
     self.message = result
     return
   end
+  -- engine/pokemon/bills_pc.asm:1762
+  self:playMonCry(result)
   self.message = nil
   self.phase = nil
   self.index, self.scroll = 1, 0
@@ -486,6 +512,8 @@ function BoxMenu:update(_dt)
       if not ok then
         -- .no_space: `dec [hl]` puts the jumptable back on .PrepInsertCursor,
         -- so the refusal leaves the cursor exactly where it was.
+        -- engine/pokemon/bills_pc.asm:1567
+        self:playSfx("Sfx_Wrong")
         self.message = reason
       else
         self:insertMon()
@@ -528,6 +556,14 @@ function BoxMenu:playSfx(name)
   if sfx and sfx[Sound.resolve(data, name)] then Sound.play(data, name) end
 end
 
+-- PlayMonCry: `call GetCryIndex / jr c, .done` (home/pokemon.asm:113-114)
+function BoxMenu:playMonCry(mon)
+  local data = self.game and self.game.data
+  if not (data and mon and mon.species) or mon.isEgg then return end
+  local cries = data.audio and data.audio.cries
+  if cries and cries[mon.species] then Sound.playCry(data, mon.species) end
+end
+
 -- BillsPC's RELEASE, which the model has always supported and nothing on
 -- screen reached.  The cart asks first and starts the prompt on NO, the way
 -- every irreversible choice in the game does.
@@ -541,6 +577,8 @@ function BoxMenu:askRelease()
     local allowed, refusal = self:checkMailPreventBlackout()
     if not allowed then
       self.phase = nil
+      -- engine/pokemon/bills_pc.asm:1607
+      self:playSfx("Sfx_Wrong")
       self.message = refusal
       return
     end
@@ -568,6 +606,8 @@ function BoxMenu:askRelease()
       self.message = err
       return
     end
+    -- engine/pokemon/bills_pc.asm:1866
+    self:playMonCry(mon)
     self.message = name .. " was released."
     self.phase = nil
     self:clampIndex()
@@ -627,14 +667,31 @@ function BoxMenu:picFor(mon)
   return self:image(path)
 end
 
+-- engine/gfx/cgb_layouts.asm:284-300, engine/pokemon/bills_pc.asm:356-369
+function BoxMenu:panelColors(speciesId, shiny)
+  if self.phase == "submenu" or self.phase == "insert" then
+    return self.palettes
+      and Palettes.monColors(self.palettes, speciesId, shiny)
+  end
+  local gfx = (self.menuGfx or {}).billsPc
+  return (gfx and gfx.orangePalette) or BILLS_PC_ORANGE
+end
+
+-- ClearBox runs before `cp -1 / ret z` (engine/pokemon/bills_pc.asm:1009-1021)
+function BoxMenu:fillPicBlock(colors)
+  local G = love.graphics
+  local blank = colors and GbcPalette.color(colors, 1) or { 255, 255, 255 }
+  G.setColor(blank[1] / 255, blank[2] / 255, blank[3] / 255, 1)
+  G.rectangle("fill", PIC_X * 8, PIC_Y * 8, 7 * 8, 7 * 8)
+  G.setColor(1, 1, 1, 1)
+end
+
 -- PCMonInfo lays the padded pic as one 7x7 block at hlcoord 1, 4
 -- (engine/pokemon/bills_pc.asm:1023-1042), the pad tiles at the palette's 0.
 function BoxMenu:drawPicBlock(image, colors)
   if not image then return end
   local G = love.graphics
-  local blank = colors and GbcPalette.color(colors, 1) or { 255, 255, 255 }
+  self:fillPicBlock(colors)
-  G.setColor(blank[1] / 255, blank[2] / 255, blank[3] / 255, 1)
-  G.rectangle("fill", PIC_X * 8, PIC_Y * 8, 7 * 8, 7 * 8)
 
   local pad = PIC_PAD[math.floor(image:getWidth() / 8)] or PIC_PAD[7]
   G.setColor(1, 1, 1, 1)
@@ -650,12 +707,12 @@ function BoxMenu:drawPicBlock(image, colors)
 end
 
 function BoxMenu:drawPic(mon)
-  local image = self:picFor(mon)
-  if not image then return end
   -- _CGB_BillsPC hands wTempMonDVs to GetPlayerOrMonPalettePointer, so the box
   -- pic takes the shiny row (engine/gfx/cgb_layouts.asm:292-293).
-  local colors = self.palettes
+  local colors = self:panelColors(mon.species, mon.shiny)
-    and Palettes.monColors(self.palettes, mon.species, mon.shiny)
+  local image = self:picFor(mon)
+  -- engine/pokemon/bills_pc.asm:1009-1011
+  if not image then return self:fillPicBlock(colors) end
   self:drawPicBlock(image, colors)
 end
 
@@ -664,17 +721,14 @@ end
 -- with the party list's ICON_EGG standing in for a cache built before that.
 function BoxMenu:drawEggPic(mon)
   local G = love.graphics
-  local colors = self.palettes
+  local colors = self:panelColors("EGG", mon and mon.shiny)
-    and Palettes.monColors(self.palettes, "EGG", mon and mon.shiny)
   local gfx = (self.menuGfx or {}).eggHatch
   local image = self:image(gfx and gfx.egg)
   if image then return self:drawPicBlock(image, colors) end
+  self:fillPicBlock(colors)
   local entry = self.icons and self.icons.icons and self.icons.icons.ICON_EGG
   image = self:image(entry and entry.image)
   if not image then return end
-  local blank = colors and GbcPalette.color(colors, 1) or { 255, 255, 255 }
-  G.setColor(blank[1] / 255, blank[2] / 255, blank[3] / 255, 1)
-  G.rectangle("fill", PIC_X * 8, PIC_Y * 8, 7 * 8, 7 * 8)
   -- The ICON_EGG sheet stacks its frames; the first is the egg at rest.
   local w = entry.width or 16
   local h = math.min(entry.height or 16, image:getHeight())
@@ -694,6 +748,58 @@ function BoxMenu:drawEggPic(mon)
   G.setColor(1, 1, 1, 1)
 end
 
+-- ItemIsMail picks $5c over $5d at hlcoord 7, 12
+-- (engine/pokemon/bills_pc.asm:1079-1094)
+function BoxMenu:drawHeldIcon(mon)
+  local row = PartyMenu.heldMarkerRow(mon)
+  if not row then return end
+  local gfx = (self.menuGfx or {}).billsPc
+  local image = self:image(gfx and gfx.icons)
+  if not image then return end
+  local ok, quad = pcall(love.graphics.newQuad, row * 8, 0, 8, 8,
+    image:getDimensions())
+  if not ok then return end
+  local G = love.graphics
+  G.setColor(1, 1, 1, 1)
+  local function body() G.draw(image, quad, ICON_X * 8, ICON_Y * 8) end
+  local colors = gfx and gfx.palette
+  if colors and GbcPalette.available() then
+    GbcPalette.with(colors, body)
+  else
+    body()
+  end
+  G.setColor(1, 1, 1, 1)
+end
+
+-- _MovePKMNWithoutMail only (engine/pokemon/bills_pc.asm:545, :698)
+function BoxMenu:drawBoxArrows()
+  if self.mode ~= "move" then return end
+  local gfx = (self.menuGfx or {}).billsPc
+  local image = self:image(gfx and gfx.icons)
+  if not image then return end
+  local G = love.graphics
+  local quads = {}
+  for _, arrow in ipairs({ ARROW_LEFT, ARROW_RIGHT }) do
+    local ok, quad = pcall(love.graphics.newQuad, arrow[1] * 8, 0, 8, 8,
+      image:getDimensions())
+    if not ok then return end
+    quads[#quads + 1] = { quad, arrow[2] }
+  end
+  G.setColor(1, 1, 1, 1)
+  local function body()
+    for _, entry in ipairs(quads) do
+      G.draw(image, entry[1], entry[2] * 8, ARROW_ROW * 8)
+    end
+  end
+  local colors = gfx and gfx.palette
+  if colors and GbcPalette.available() then
+    GbcPalette.with(colors, body)
+  else
+    body()
+  end
+  G.setColor(1, 1, 1, 1)
+end
+
 -- The PC does not mark the selected row with a ▶: BillsPC_UpdateSelectionCursor
 -- lays 20 OBJs as a frame *around* the row -- ten tiles wide by two tall, top
 -- left at pixel (71, 25), stepping 16 pixels per row.  Those cursor tiles are
@@ -740,6 +846,7 @@ function BoxMenu:drawPanel()
   -- Textbox at (8,0) with a 10x1 interior and the name at (10,1).
   Chrome.box(8, 0, 12, 3)
   Chrome.print(self:title(), 10, 1)
+  self:drawBoxArrows()
   Chrome.box(8, 2, 12, 12)
   -- BillsPC_RefreshTextboxes overwrites its own top corners with '└'/'┘'
   -- (engine/pokemon/bills_pc.asm:1204-1211) so the list reads as hanging
@@ -793,7 +900,10 @@ function BoxMenu:drawPanel()
         Chrome.print("\xe2\x99\x80", 5, 12)
       end
       Chrome.print(mon.name or mon.species or "?", PIC_X, 14)
+      self:drawHeldIcon(mon)
     end
+  else
+    self:fillPicBlock(self:panelColors())
   end
 
   -- BillsPC_PlaceString: Textbox at (0,15) with a one-row interior, string at
@@ -838,8 +948,7 @@ function BoxMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/CardFlip.lua

@@ -49,9 +49,9 @@
 --                           Textbox at (0,12) with an 18x4 interior
 --
 -- The cart's own art (gfx/card_flip/card_flip_1..3.2bpp.lz and
--- gfx/card_flip/card_flip.tilemap) is NOT in the cache: no `cardFlip` entry is
+-- gfx/card_flip/card_flip.tilemap) is extracted into assets/generated/card_flip/
--- written into menu_gfx.lua yet, so the board draws as labelled cells until one
+-- when the Gold/Silver manifest carries CardFlip*.  Until those files exist,
--- appears.
+-- the board draws as labelled cells.
 
 local Chrome = require("src.ui.gen2.Chrome")
 local CoinCase = require("src.core.gen2.CoinCase")
@@ -616,10 +616,8 @@ local TILEMAP = nil
 local function getCardFlipTilemap()
   if TILEMAP == nil then
     local path = "assets/generated/card_flip/card_flip.tilemap"
-    local f = io.open(path, "rb")
+    local data = love and love.filesystem and love.filesystem.read(path)
-    if f then
+    if data and #data > 0 then
-      local data = f:read("*a")
-      f:close()
       TILEMAP = {}
       for i = 1, #data do
         TILEMAP[i] = string.byte(data, i)
@@ -974,8 +972,7 @@ function CardFlip:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/CenterPcMenu.lua

@@ -313,8 +313,7 @@ function CenterPcMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/ContestMenu.lua

@@ -180,8 +180,7 @@ function ContestMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/CopyrightSplash.lua

@@ -108,8 +108,7 @@ function CopyrightSplash:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - SCREEN_H * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/Credits.lua

@@ -845,8 +845,7 @@ function Credits:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - SCREEN_H * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/DecorationMenu.lua

@@ -267,8 +267,7 @@ function DecorationMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/EggHatchAnim.lua

@@ -43,8 +43,6 @@ local EggHatchAnim = {}
 EggHatchAnim.__index = EggHatchAnim
 EggHatchAnim.isOpaque = true
 
-local SCREEN_W, SCREEN_H = 160, 144
-
 -- Hatch_UpdateFrontpicBGMapCenter is called twice with different hlcoords:
 -- the egg sits at (7,4) and the hatchling at (6,3).  Both are `lb bc, 7, 7`
 -- PlaceGraphic boxes, and the pic inside that box has already been padded to
@@ -446,8 +444,7 @@ function EggHatchAnim:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - SCREEN_H * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/EvolutionAnim.lua

@@ -40,8 +40,6 @@ local EvolutionAnim = {}
 EvolutionAnim.__index = EvolutionAnim
 EvolutionAnim.isOpaque = true
 
-local SCREEN_W, SCREEN_H = 160, 144
-
 -- PrepMonFrontpic's box: hlcoord 7, 2, `lb bc, 7, 7`.
 local PIC_TILE_X, PIC_TILE_Y, PIC_TILES = 7, 2, 7
 
@@ -252,6 +250,8 @@ function EvolutionAnim:setPhase(phase)
         full = self.full,
       })
     end
+    local stack = self.game and self.game.stack
+    if stack and stack.top and stack:top() == self then stack:pop() end
     return
   end
 end
@@ -321,8 +321,18 @@ end
 function EvolutionAnim:update(_dt)
   local input = self.game and self.game.input
   local phase = self.phase
-  -- onDone has already fired; the caller pops this state on its own beat.
+  -- onDone has already fired.
-  if phase == "done" then return end
+  if phase == "done" then
+    local stack = self.game and self.game.stack
+    if stack and stack.top and stack:top() == self then stack:pop() end
+    return
+  end
+
+  if phase == "waitingLearn" then
+    local stack = self.game and self.game.stack
+    if stack and stack.top and stack:top() == self then self:nextLearn() end
+    return
+  end
 
   if phase == "flash" then
     return self:updateFlash(input)
@@ -561,8 +571,7 @@ function EvolutionAnim:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - SCREEN_H * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/GameFreakPresents.lua

@@ -372,8 +372,7 @@ function GameFreakPresents:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - SCREEN_H * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/GoldSilverIntro.lua

@@ -1033,8 +1033,7 @@ function GoldSilverIntro:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - SCREEN_H * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/HallOfFame.lua

@@ -657,8 +657,7 @@ function HallOfFame:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - SCREEN_H * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/ItemPcMenu.lua

@@ -320,12 +320,15 @@ function ItemPcMenu:leaveDeposit()
 end
 
 function ItemPcMenu:offerToDeposit(id, count)
-  -- .TryDepositItem's `.no_toss` arm is a bare ret: a KEY ITEM or HM stays in
-  -- the bag with no message at all.
-  if self:cantToss(id) then return end
   if (count or 0) < 1 then return end
   local def = self:def(id)
   local name = (def and def.name) or id
+  -- .DepositItem (engine/events/pokecenter_pc.asm:504): an item with no
+  -- quantity is always x1 and never reaches .AskQuantity.
+  if self:cantToss(id) then
+    self:deposit(id, name, 1)
+    return
+  end
   self:askQuantity(count,
     { "How many do you", "want to deposit?" },
     function(qty) self:deposit(id, name, qty) end)
@@ -518,9 +521,10 @@ function ItemPcMenu:drawList()
       local entry = self.rows[i]
       if i == self.listIndex then Chrome.cursor(5, ty) end
       Chrome.print(entry.name, 6, ty)
-      -- PlaceMenuItemQuantity (engine/menus/menu_2.asm:24): the xNN is the
+      -- PlaceMenuItemQuantity (engine/menus/menu_2.asm:18, :24)
-      -- entry's second line, right-aligned in a blank-padded 2-digit field.
+      if not self:cantToss(entry.id) then
         Chrome.print(TIMES .. Chrome.number(entry.count, 2), 7, ty + 1)
+      end
     elseif i == self:listTotal() then
       if i == self.listIndex then Chrome.cursor(5, ty) end
       Chrome.print("CANCEL", 6, ty)
@@ -592,8 +596,7 @@ function ItemPcMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/MagnetTrainRide.lua

@@ -22,12 +22,14 @@
 --     PAL_BG_YELLOW, out of a TOWN palette set at the current time of day
 --     (the routine pushes wEnvironment, forces TOWN, and pops it back).
 --
--- Two hardware details are not reproduced.  The four player OBJs all carry
+-- Two hardware details from the cart are faithfully reproduced:
--- OAM_PRIO, so on the cart they sit behind background colours 1-3 and only
+-- 1. Viewport wrapping: the 256x144 background scrolls in 3 LY override bands,
--- show through the window's colour 0; here they are drawn straight over the
+--    wrapped strictly within the 160x144 GB screen so pixels do not bleed into
--- background, which looks the same everywhere the window is transparent and
+--    the widescreen surround.
--- differs only if the sprite drifts over solid train tiles.  And the ride
+-- 2. OAM Priority (OAM_PRIO): the four player OBJs sit behind background
--- cannot be skipped, exactly as on the cart: the loop reads no input at all.
+--    colours 1-3 and only show through the window's colour 0.  This is drawn
+--    via a base background pass, the player sprite, and an overlay pass where
+--    shade 0 is transparent and solid train tiles mask the sprite.
 
 local Assets = require("src.render.Assets")
 local Chrome = require("src.ui.gen2.Chrome")
@@ -46,6 +48,30 @@ local BG_W = 256           -- TILEMAP_WIDTH * 8
 local TILES_PER_ROW = 16   -- every 2bpp sheet the importer writes
 local BLACK = { 0, 0, 0 }
 
+-- Overlay shader for OAM_PRIO: shade 0 is transparent; shades 1-3 are solid
+-- palette colors, masking any sprites beneath solid background tiles.
+local OVERLAY_SHADER_SOURCE = [[
+extern vec3 pal0;
+extern vec3 pal1;
+extern vec3 pal2;
+extern vec3 pal3;
+
+vec4 effect(vec4 tint, Image tex, vec2 uv, vec2 screen) {
+  vec4 px = Texel(tex, uv);
+  float shade = floor((1.0 - px.r) * 3.0 + 0.5);
+  vec3 rgb = pal0;
+  if (shade > 2.5) {
+    rgb = pal3;
+  } else if (shade > 1.5) {
+    rgb = pal2;
+  } else if (shade > 0.5) {
+    rgb = pal1;
+  }
+  float alpha = shade < 0.5 ? 0.0 : px.a;
+  return vec4(rgb, alpha) * tint;
+}
+]]
+
 function MagnetTrainRide:wantsFillScale() return true end
 
 -- opts: toGoldenrod (the wScriptVar the officer's script set), onDone()
@@ -97,7 +123,7 @@ function MagnetTrainRide:palette(slot)
 end
 
 --------------------------------------------------------------------------
--- Sheets
+-- Sheets & Shaders
 --------------------------------------------------------------------------
 
 local function sheetFor(path)
@@ -159,22 +185,66 @@ function MagnetTrainRide:playerQuad(vtile)
   return quad
 end
 
+function MagnetTrainRide:overlayShader()
+  if self.ovShader ~= nil then return self.ovShader or nil end
+  if not (love and love.graphics and love.graphics.newShader) then
+    self.ovShader = false
+    return nil
+  end
+  local ok, result = pcall(love.graphics.newShader, OVERLAY_SHADER_SOURCE)
+  self.ovShader = ok and result or false
+  return self.ovShader or nil
+end
+
+local function palChannel(colors, index)
+  local c = colors and colors[index]
+  if not c then return 0, 0, 0 end
+  return (c[1] or 0) / 255, (c[2] or 0) / 255, (c[3] or 0) / 255
+end
+
+function MagnetTrainRide:useOverlayShader(colors)
+  local sh = self:overlayShader()
+  if not sh then return false end
+  local resolved = GbcPalette.resolve(colors)
+  for i = 0, 3 do
+    local u = "pal" .. i
+    if sh:hasUniform(u) then
+      local r, g, b = palChannel(resolved, i + 1)
+      sh:send(u, { r, g, b })
+    end
+  end
+  love.graphics.setShader(sh)
+  return true
+end
+
+
 --------------------------------------------------------------------------
--- The baked background
+-- The baked backgrounds (Base + OAM_PRIO Overlay)
 --------------------------------------------------------------------------
 
--- DrawMagnetTrain plus SetMagnetTrainPals, rendered once into a 256x144
+-- DrawMagnetTrain plus SetMagnetTrainPals, rendered once into 256x144 canvases.
--- canvas.  Tiles are drawn palette group by palette group so the three
+-- Base canvas contains the full opaque background; Overlay canvas contains
--- palettes cost three shader switches rather than one per tile.
+-- solid shades 1-3 with shade 0 transparent for OAM_PRIO window masking.
-function MagnetTrainRide:background()
+function MagnetTrainRide:backgrounds()
-  if self.bgCanvas ~= nil then return self.bgCanvas or nil end
+  if self.bgCanvas ~= nil then
+    return self.bgCanvas or nil, self.bgOverlayCanvas or nil
+  end
   self.bgCanvas = false
+  self.bgOverlayCanvas = false
   local rows = self.ride:tilemap()
   local sheet = self:tileSheet()
-  if not (rows and sheet) then return nil end
+  if not (rows and sheet) then return nil, nil end
-  local ok, canvas = pcall(love.graphics.newCanvas, BG_W, SCREEN_H)
+
-  if not ok then return nil end
+  local ok1, baseCanvas = pcall(love.graphics.newCanvas, BG_W, SCREEN_H)
-  canvas:setFilter("nearest", "nearest")
+  if not ok1 then return nil, nil end
+  baseCanvas:setFilter("nearest", "nearest")
+
+  local ok2, overlayCanvas = pcall(love.graphics.newCanvas, BG_W, SCREEN_H)
+  if ok2 and overlayCanvas then
+    overlayCanvas:setFilter("nearest", "nearest")
+  else
+    overlayCanvas = nil
+  end
 
   local groups = {}
   for row = 1, #rows do
@@ -188,11 +258,12 @@ function MagnetTrainRide:background()
 
   local G = love.graphics
   local previous = G.getCanvas()
-  -- A canvas does not reset the transform: without this the map lands under
+  G.push("all")
-  -- the renderer's letterbox scale and off the edge.
-  G.push()
   G.origin()
-  G.setCanvas(canvas)
+  G.setScissor()
+
+  -- 1. Base background canvas (shades 0-3)
+  G.setCanvas(baseCanvas)
   G.clear(0, 0, 0, 1)
   G.setColor(1, 1, 1, 1)
   local shader = GbcPalette.available()
@@ -205,10 +276,35 @@ function MagnetTrainRide:background()
     end
   end
   if shader then GbcPalette.clear() end
+
+  -- 2. Overlay canvas for OAM_PRIO (shades 1-3 solid, shade 0 transparent)
+  if overlayCanvas then
+    G.setCanvas(overlayCanvas)
+    G.clear(0, 0, 0, 0)
+    G.setColor(1, 1, 1, 1)
+    local ovShader = self:overlayShader()
+    for slot, list in pairs(groups) do
+      local colors = self:palette(slot)
+      if ovShader and colors then self:useOverlayShader(colors) end
+      for _, cell in ipairs(list) do
+        local quad = sheet.quads[cell[1]]
+        if quad then G.draw(sheet.image, quad, cell[2], cell[3]) end
+      end
+    end
+    if ovShader then G.setShader() end
+  end
+
   G.setCanvas(previous)
   G.pop()
-  self.bgCanvas = canvas
+
-  return canvas
+  self.bgCanvas = baseCanvas
+  self.bgOverlayCanvas = overlayCanvas
+  return baseCanvas, overlayCanvas
+end
+
+function MagnetTrainRide:background()
+  local base = self:backgrounds()
+  return base
 end
 
 --------------------------------------------------------------------------
@@ -240,19 +336,24 @@ function MagnetTrainRide:update(_dt)
   end
 end
 
-function MagnetTrainRide:drawBackground()
+-- Draws the 3 LY override bands strictly wrapped inside the 160px GB screen.
-  local canvas = self:background()
+function MagnetTrainRide:drawBands(canvas)
   if not canvas then return end
   local G = love.graphics
   G.setColor(1, 1, 1, 1)
   self.bandQuad = self.bandQuad
-    or love.graphics.newQuad(0, 0, BG_W, 1, BG_W, SCREEN_H)
+    or love.graphics.newQuad(0, 0, SCREEN_W, 1, BG_W, SCREEN_H)
   for _, band in ipairs(self.ride:bands()) do
     local top, bottom, scx = band[1], band[2], band[3] % BG_W
     local height = bottom - top + 1
-    self.bandQuad:setViewport(0, top, BG_W, height, BG_W, SCREEN_H)
+    local w1 = math.min(SCREEN_W, BG_W - scx)
-    G.draw(canvas, self.bandQuad, -scx, top)
+    self.bandQuad:setViewport(scx, top, w1, height, BG_W, SCREEN_H)
-    G.draw(canvas, self.bandQuad, -scx + BG_W, top)
+    G.draw(canvas, self.bandQuad, 0, top)
+    if w1 < SCREEN_W then
+      local w2 = SCREEN_W - w1
+      self.bandQuad:setViewport(0, top, w2, height, BG_W, SCREEN_H)
+      G.draw(canvas, self.bandQuad, w1, top)
+    end
   end
 end
 
@@ -277,6 +378,7 @@ function MagnetTrainRide:drawPlayer()
   if colors then GbcPalette.use(colors) end
   G.setColor(1, 1, 1, 1)
   for _, entry in ipairs(oam) do
+    if entry.x >= -8 and entry.x < SCREEN_W and entry.y >= -16 and entry.y < SCREEN_H then
       local quad = self:playerQuad(entry.tile)
       if quad then
         G.draw(sheet.image, quad,
@@ -284,9 +386,11 @@ function MagnetTrainRide:drawPlayer()
           entry.xflip and -1 or 1, 1)
       end
     end
+  end
   if colors then GbcPalette.clear() end
 end
 
+
 -- The backdrop is BG colour 0 of the gray palette the train body uses; on the
 -- cart it is what shows wherever nothing was drawn.
 function MagnetTrainRide:backdrop()
@@ -299,13 +403,24 @@ function MagnetTrainRide:drawPanel()
   G.setColor(backdrop[1] / 255, backdrop[2] / 255, backdrop[3] / 255, 1)
   G.rectangle("fill", 0, 0, SCREEN_W, SCREEN_H)
   G.setColor(1, 1, 1, 1)
-  self:drawBackground()
+
+  local base, overlay = self:backgrounds()
+  -- 1. Base background (bushes, train body, window aperture)
+  self:drawBands(base)
+  -- 2. Player sprite (OAM_PRIO: sits behind train body, visible through window)
   self:drawPlayer()
+  -- 3. Train body / frame overlay (colors 1-3 mask sprite; color 0 is transparent)
+  self:drawBands(overlay)
+
   G.setColor(1, 1, 1, 1)
 end
 
 function MagnetTrainRide:draw()
+  local G = love.graphics
+  G.push("all")
+  G.setScissor(0, 0, SCREEN_W, SCREEN_H)
   self:drawPanel()
+  G.pop()
 end
 
 -- MagnetTrain_LoadGFX_PlayMusic opens on ClearBGPalettes / ClearSprites
@@ -323,7 +438,8 @@ function MagnetTrainRide:drawWidescreen(winW, winH)
   G.setColor(1, 1, 1, 1)
   local scale = Chrome.fitScale(winW, winH)
   local ox, oy = Chrome.fitOrigin(winW, winH, scale)
-  G.push()
+  G.push("all")
+  G.setScissor(ox, oy, SCREEN_W * scale, SCREEN_H * scale)
   G.translate(ox, oy)
   G.scale(scale, scale)
   self:drawPanel()
@@ -331,3 +447,6 @@ function MagnetTrainRide:drawWidescreen(winW, winH)
 end
 
 return MagnetTrainRide
+
+
+

src/ui/gen2/MailCompose.lua

@@ -341,8 +341,7 @@ function MailCompose:drawWidescreen(winW, winH)
   G.setColor(1, 1, 1, 1)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/MailRead.lua

@@ -94,8 +94,7 @@ function MailRead:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/MainMenu.lua

@@ -218,8 +218,7 @@ function MainMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/NamePick.lua

@@ -225,8 +225,7 @@ function NamePick:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/OptionsMenu.lua

@@ -123,13 +123,11 @@ local ROWS = {
   { label = "ZOOM", key = "zoom", port = true,
     cycle = function(options, delta, game)
       local Zoom = require("src.render.Zoom")
-      local scale = (game and game.world and game.world.fitScale
+      local scale = Zoom.windowFitScale()
-        and game.world:fitScale()) or 1
+      if game and game.world and game.world.fitScale then
-      local lo, hi = Zoom.offsetRange(scale)
+        scale = game.world:fitScale()
-      local offset = (options.zoom or 0) + delta
+      end
-      if offset > hi then offset = lo elseif offset < lo then offset = hi end
+      Zoom.nudgeOptions(options, delta, scale)
-      options.zoom = offset
-      Zoom.offset = offset
     end,
     text = function(options)
       return require("src.render.Zoom").offsetLabel(options.zoom or 0)
@@ -466,8 +464,7 @@ function OptionsMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PackMenu.lua

@@ -16,6 +16,9 @@ local PackGfx = require("src.ui.gen2.PackGfx")
 local Screens = require("src.ui.Screens")
 local Strings = require("src.core.Strings")
 
+-- constants/sfx_constants.asm:3, :28
+local SFX_DEX_FANFARE_50_79, SFX_WRONG = 0, 25
+
 local PackMenu = {}
 PackMenu.__index = PackMenu
 PackMenu.isOpaque = true
@@ -192,6 +195,14 @@ function PackMenu:pocketOf(itemId)
   return (def and def.pocket) or "ITEM"
 end
 
+-- engine/items/tmhm.asm:341
+function PackMenu:tmhmKey(itemId)
+  local def = self.items and self.items[itemId]
+  local n = def and tonumber(def.tmNumber)
+  if n then return n end
+  return 1000 + ((def and tonumber(def.index)) or 0)
+end
+
 -- The name on the row.  An inventory key with no ItemAttributes row behind it
 -- (an older cache, a mod's own item, a driver seeding an id that is not in
 -- items.lua) still has to draw something a person can read, so the id stands
@@ -239,6 +250,14 @@ function PackMenu:rebuild()
       }
     end
   end
+  -- engine/items/tmhm.asm:341
+  if pocket == "TM_HM" then
+    table.sort(rows, function(a, b)
+      local ka, kb = self:tmhmKey(a.id), self:tmhmKey(b.id)
+      if ka ~= kb then return ka < kb end
+      return a.id < b.id
+    end)
+  end
   self.rows = rows
   self.index = math.min(self.index, #rows + 1)
   if self.index < 1 then self.index = 1 end
@@ -359,6 +378,9 @@ function PackMenu:useSelected()
       -- with sound_dex_fanfare_50_79 between them; the PACK's box here holds
       -- all four rows at once, the way OAK_THIS_ISNT_THE_TIME's three fit.
       -- World has already set the decoration's flag and taken the box.
+      if world.playSfxNamed then
+        world:playSfxNamed("Sfx_DexFanfare5079", SFX_DEX_FANFARE_50_79)
+      end
       self.message = { "There was a trophy", "inside!",
                        "{PLAYER} sent the", "trophy home." }
       self:rebuild()
@@ -641,6 +663,11 @@ function PackMenu:openTeachParty(row)
         if id == moveId then allowed = true end
       end
       if not allowed then
+        -- engine/items/tmhm.asm:131
+        local world = game.world
+        if world and world.playSfxNamed then
+          world:playSfxNamed("Sfx_Wrong", SFX_WRONG)
+        end
         if game.say then
           game:say(("%s can't learn %s!"):format(
             require("src.battle.gen2.Mon").displayName(mon), moveName))
@@ -740,7 +767,9 @@ function PackMenu:update(_dt)
 end
 
 -- engine/items/pack.asm:1290 Pack_InterpretJoypad .select
+-- engine/items/tmhm.asm:207 -- the TM/HM pocket's joypad filter drops SELECT.
 function PackMenu:armSwitch()
+  if self:pocket().id == "TM_HM" then return end
   if self:isCancel() then return end
   if not self.rows[self.index] then return end
   self.switching = self.index
@@ -1027,8 +1056,7 @@ function PackMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PartyMenu.lua

@@ -849,8 +849,7 @@ function PartyMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PcMenu.lua

@@ -453,8 +453,7 @@ function PcMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PokedexMenu.lua

@@ -1462,8 +1462,7 @@ function PokedexMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PrizeMenu.lua

@@ -560,8 +560,7 @@ function PrizeMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/SaveMenu.lua

@@ -228,8 +228,7 @@ function SaveMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/SlotMachine.lua

@@ -39,11 +39,9 @@
 --                         tiles at (2,13),(3,13),(2,14),(3,14) and the ▼ at
 --                         (18,17)
 --
--- The cart's own reel art (gfx/slots/slots_1..3.2bpp.lz plus
+-- Reel art (gfx/slots/slots_1..3.2bpp.lz + slots.tilemap) is extracted into
--- gfx/slots/slots.tilemap) is NOT in the cache: src/import/RomExtractorGen2.lua
+-- assets/generated/slots/ when the Gold/Silver manifest carries Slots*LZ.
--- writes no `slots` entry into menu_gfx.lua yet.  SlotMachine:sheet() reads one
+-- Until those files exist, drawReels falls back to labelled cells.
--- the moment it appears and falls back to labelled cells until then, the same
--- way src/ui/gen2/PackGfx.lua degrades.
 
 local Chrome = require("src.ui.gen2.Chrome")
 local CoinCase = require("src.core.gen2.CoinCase")
@@ -1160,10 +1158,8 @@ local TILEMAP = nil
 local function getTilemap()
   if TILEMAP == nil then
     local path = "assets/generated/slots/gold_slots.tilemap"
-    local f = io.open(path, "rb")
+    local data = love and love.filesystem and love.filesystem.read(path)
-    if f then
+    if data and #data > 0 then
-      local data = f:read("*a")
-      f:close()
       TILEMAP = {}
       for i = 1, #data do
         TILEMAP[i] = string.byte(data, i)
@@ -1175,6 +1171,14 @@ local function getTilemap()
   return TILEMAP or nil
 end
 
+-- Placeholder 2x2 symbol cell used when reel sheets are not in the cache yet.
+local function cell(tx, ty, label)
+  local G = love.graphics
+  G.setColor(0, 0, 0, 1)
+  G.rectangle("line", tx * 8, ty * 8, 16, 16)
+  Chrome.print(label, tx, ty + 1)
+end
+
 function SlotMachine:sheets()
   if self.sheet1 == nil then
     self.sheet1 = TileSheet.new({ path = "assets/generated/slots/gold_slots_1.png", wide = 2, firstTile = 0 })
@@ -1253,6 +1257,9 @@ function SlotMachine:drawReels()
     -- Draw 4 consecutive 2x2 symbols from bottom to top, exactly matching SlotMachine.window
     for row = 0, 3 do
       local sym = strip[a + row + 1]
+      if type(sym) ~= "number" then
+        cell(REEL_X[i], REEL_ROW[row + 1], "?")
+      else
         local py = 64 - (row * 16) + dy
         local pal = GBC_PALS.obj[math.floor(sym / 4)] or GBC_PALS.obj[0]
         s2.palette = pal
@@ -1286,6 +1293,7 @@ function SlotMachine:drawReels()
         end
       end
     end
+  end
 end
 
 function SlotMachine:actorsImage()
@@ -1439,6 +1447,9 @@ function SlotMachine:drawMessage()
       and self.phase == "payoutText" then
     local _, s2 = self:sheets()
     local sym = self.matched
+    if type(sym) ~= "number" then
+      cell(PAYOUT_SYMBOL_X, PAYOUT_SYMBOL_Y, "?")
+    else
       local pal = GBC_PALS.obj[math.floor(sym / 4)] or GBC_PALS.obj[0]
       s2.palette = pal
       local t0 = s2:quad(sym + 0)
@@ -1463,7 +1474,8 @@ function SlotMachine:drawMessage()
           drawWin()
         end
       else
-      cell(PAYOUT_SYMBOL_X, PAYOUT_SYMBOL_Y, SlotMachine.LABELS[self.matched] or "?")
+        cell(PAYOUT_SYMBOL_X, PAYOUT_SYMBOL_Y, SlotMachine.LABELS[sym] or "?")
+      end
     end
   end
 end
@@ -1523,8 +1535,7 @@ function SlotMachine:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/SummaryMenu.lua

@@ -1175,8 +1175,7 @@ function SummaryMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/TradeAnim.lua

@@ -58,8 +58,6 @@ local TradeAnimView = {}
 TradeAnimView.__index = TradeAnimView
 TradeAnimView.isOpaque = true
 
-local SCREEN_W, SCREEN_H = 160, 144
-
 -- PlaceGraphic's box and the stats panel's Textbox, in tiles.
 local PIC_TILE_X, PIC_TILE_Y, PIC_TILES = 7, 2, 7
 local PANEL_X, PANEL_Y = 3, 0
@@ -876,8 +874,7 @@ function TradeAnimView:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - SCREEN_H * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/TrainerCard.lua

@@ -437,8 +437,7 @@ function TrainerCard:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/UnownPuzzle.lua

@@ -580,8 +580,7 @@ function UnownPuzzle:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
-    math.floor((winH - 144 * scale) / 2))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/kit/Kit.lua

@@ -749,12 +749,23 @@ function Kit.chip(x, y, w, h, label, on, color, id)
 end
 
 -- A status label with no interaction: outlined text, the "INSTALLED"/"UPDATE"
--- markers on mod rows.
+-- markers on mod rows.  Pass opts.fill for a solid chip (BETA badges); ink
-function Kit.tag(x, y, w, h, label, color)
+-- then defaults to PAL.inverse so the label stays readable on the fill.
+function Kit.tag(x, y, w, h, label, color, opts)
   if not G then return end
+  opts = opts or {}
+  if opts.fill then
+    Theme.fillRounded(x, y, w, h, color or PAL.yellow, 1, h / 2)
+  else
     Theme.strokeRounded(x, y, w, h, color or PAL.line, 0.7, 1)
-  Kit.textCenter("micro", label, x, y + (h - Kit.textHeight("micro")) / 2, w,
+  end
-    color or PAL.muted)
+  local ink = opts.ink or (opts.fill and PAL.inverse) or color or PAL.muted
+  local ty = y + (h - Kit.textHeight("micro")) / 2
+  if opts.bold then
+    Kit.textCenterBold("micro", label, x, ty, w, ink)
+  else
+    Kit.textCenter("micro", label, x, ty, w, ink)
+  end
 end
 
 -- Checkbox row.  Returns (newChecked, changed).

src/update/Check.lua

@@ -58,6 +58,13 @@ function Check.fullAssetName(version, osName, arch, port)
   return fullAssetName(version, osName, arch, port)
 end
 
+-- A legacy Android APK can run a newer downloaded payload while still lacking
+-- the native bridge that installs future APK updates. It needs one manual
+-- package update even when that payload already reports the latest engine.
+function Check.androidNeedsInstallerBootstrap(osName, hasInstaller)
+  return osName == "Android" and not hasInstaller
+end
+
 local CMD = "update_check_cmd"
 local STATE = "update_check_state"
 
@@ -266,13 +273,16 @@ function Check.fullUpdateAction()
   local st = Check.state()
   if st.status ~= "needs_full" and st.status ~= "full_ready" then return nil end
   local osName = love and love.system and love.system.getOS and love.system.getOS() or ""
-  if osName == "Android" and type(love.system.installApk) == "function"
+  if osName == "Android" and type(st.full) == "table"
-      and type(st.full) == "table" and type(st.full.url) == "string" then
+      and type(st.full.url) == "string" then
+    if type(love.system.installApk) == "function" then
       if st.status == "full_ready" and type(st.full.path) == "string" then
         return { label = "Install Android update", kind = "install" }
       end
       return { label = "Download Android update", kind = "download" }
     end
+    return { label = "Update app manually", url = st.full.url }
+  end
   if osName == "iOS" then
     return { label = "Re-sideload app", url =
       "https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json" }

src/update/check_worker.lua

@@ -243,6 +243,12 @@ local function doCheck(target)
     return
   end
 
+  if Check.androidNeedsInstallerBootstrap(osName,
+      type(love.system.installApk) == "function") then
+    postFullRequirement(rel, "native_installer_missing")
+    return
+  end
+
   if compareVersions(rel.version, currentEngine) <= 0 then
     -- We are now running a native shell at least as new as GitHub's latest
     -- release, so a former minShell/payloadHost prompt no longer applies.

src/world/OverworldController.lua

@@ -150,6 +150,21 @@ local function pooledNPC(pool, data, mapId, obj)
 end
 OverworldState.pooledNPC = pooledNPC -- exposed for tests
 
+local function nearestWalkableCell(map, x, y)
+  for r = 1, 8 do
+    for dy = -r, r do
+      for dx = -r, r do
+        if math.abs(dx) == r or math.abs(dy) == r then
+          local nx, ny = x + dx, y + dy
+          if map:inBounds(nx, ny) and map:isWalkableCell(nx, ny) then
+            return nx, ny
+          end
+        end
+      end
+    end
+  end
+end
+
 -- connection hops rendered around the current map: two, so
 -- corner-adjacent maps (connections of connections) don't pop in and
 -- out of the survey zoom at the seams (constants.world.neighborHops)
@@ -414,6 +429,15 @@ function OverworldState:setMap(mapId, x, y, facing, opts)
       table.insert(self.npcs, npc)
     end
   end
+  if opts and opts.via == "boot" and self.map:inBounds(x, y)
+     and not self.map:isWalkableCell(x, y) and not self.map:isWaterCell(x, y) then
+    local rx, ry = nearestWalkableCell(self.map, x, y)
+    if rx then
+      Logger.warn("saved position %s (%d,%d) is not walkable; moved to (%d,%d)",
+                  mapId, x, y, rx, ry)
+      x, y = rx, ry
+    end
+  end
   if self.player then
     self.player.cellX, self.player.cellY = x, y
     self.player.px, self.player.py = x * 16, y * 16
@@ -4113,7 +4137,7 @@ function OverworldState:checkBadgeGate()
         Game.stack:push(TextBox.new(Game,
           (t["_" .. g.failText] or Strings("You don't have the\nBOULDERBADGE yet!"))
           .. (t._Route22GateGuardICantLetYouPassText or ""), function()
-            self:scriptMove(p, "down", 1)
+            self:scriptMove(p, "down", 1, nil, { collide = true })
           end))
         return true
       end
@@ -4141,7 +4165,7 @@ function OverworldState:checkBadgeGate()
         local text = (t["_" .. g.failText] or
                       Strings("You don't have the\n{RAM} yet!")):gsub("{RAM:wNameBuffer}", badgeName)
         Game.stack:push(TextBox.new(Game, text, function()
-          self:scriptMove(p, "down", 1)
+          self:scriptMove(p, "down", 1, nil, { collide = true })
         end))
         return true
       end
@@ -4181,7 +4205,7 @@ function OverworldState:checkForcedMovement()
             function()
               local back = ({ up = "down", down = "up",
                               left = "right", right = "left" })[p.facing]
-              self:scriptMove(p, back, 1)
+              self:scriptMove(p, back, 1, nil, { collide = true })
             end))
           return true
         end
@@ -4222,6 +4246,7 @@ function OverworldState:checkSeafoamCurrent()
         -- push so the B3F stair warps underfoot cannot bounce you back.
         self.forcedWarp = false
         require("src.core.Sound").play(Game.data, "Collision")
+        -- home/overworld.asm:1891
         self:scriptMove(p, "up", c.y == 17 and 2 or 1)
         return true
       end
@@ -4780,9 +4805,10 @@ end
 -- scripted movement
 -- -------------------------------------------------------------------------
 
-function OverworldState:scriptMove(entity, dir, tiles, onDone)
+function OverworldState:scriptMove(entity, dir, tiles, onDone, opts)
   table.insert(self.scriptMoves, {
     entity = entity, dir = dir, remaining = tiles, onDone = onDone,
+    collide = opts and opts.collide or nil,
   })
 end
 
@@ -4822,16 +4848,22 @@ function OverworldState:updateScriptMoves()
         e.moving = true
         e.marching = true
         e.progress = 0
+        mv.remaining = mv.remaining - 1
+      elseif mv.collide
+             and not Collision.canMove(self.map, self.entities, e, mv.dir) then
+        -- home/overworld.asm:1224
+        e.facing = mv.dir
+        mv.remaining = 0
       else
         e.facing = mv.dir
         local tx, ty = Collision.target(e.cellX, e.cellY, mv.dir)
         e.targetX, e.targetY = tx, ty
         e.moving = true
         e.progress = 0
-      end
         mv.remaining = mv.remaining - 1
       end
     end
+  end
   -- march_in_place toggles: re-arm the in-place cycle each time it ends.
   -- Not a scriptMove, so an ambient marcher never trips the input lockout.
   for entity in pairs(self.marchers or {}) do

src/world/gen2/World.lua

@@ -83,6 +83,7 @@ local SFX = {
   WARP_TO = 19,
   EXIT_BUILDING = 35,
   JUMP_OVER_LEDGE = 0x16,
+  BUMP = 0x24,
 }
 local EMOTE_SHOCK = 0
 
@@ -2183,6 +2184,13 @@ function World:playSfxNamed(want, fallbackId)
   self:playSfx(self:sfxIdNamed(want, fallbackId))
 end
 
+-- .BumpSound (engine/overworld/player_movement.asm:771), CheckSFX at
+-- home/audio.asm:477
+function World:bumpSound()
+  if Sound.sfxBusy() then return end
+  self:playSfxNamed("Sfx_Bump", SFX.BUMP)
+end
+
 -- Script_specialsound (engine/overworld/scripting.asm:476) is not a fixed cue:
 -- it farcalls CheckItemPocket (engine/items/items.asm:512), which writes
 -- wCurItem's pocket into wItemAttributeValue, and rings SFX.GET_TM for the
@@ -9031,6 +9039,9 @@ function World:movePlayer(dir)
   elseif result == "blocked" or result == "edge" then
     self.turningDirection = nil
   end
+  -- .NotMoving and .Ice's own arm (player_movement.asm:102 and :87), which
+  -- .TryJump's carry (:376) returns above.
+  if result == "blocked" then self:bumpSound() end
   -- NormalStep, in order (engine/overworld/movement.asm:657-674): InitStep has
   -- already moved OBJECT_TILE_COLLISION onto the destination.
   if result == "moved" then self:playerStepGrass() end
@@ -9738,7 +9749,8 @@ function World:stepBody()
 
   local result = self:movePlayer(dir)
   if result == "edge" then
-    self:tryConnection(dir)
+    -- A border block is a wall: engine/overworld/player_movement.asm:264
+    if not self:tryConnection(dir) then self:bumpSound() end
   elseif result == "blocked" and p.facing == dir then
     -- .CheckNPC came back 2: something movable is in the way.  The step is
     -- lost either way, and the boulder is what moves.

tests/drivers/bide_anim_bug375_test.lua

@@ -83,15 +83,36 @@ return function(game)
   -- the announcement-time row performMove inserts directly as well as the
   -- ones animNext adds, which is the whole difference the fix makes.
   local function watchAnims(battle)
-    local seen, mark = {}, {}
+    local seen, mark, types = {}, {}, {}
     return seen, function()
       for _, row in ipairs(battle.queue) do
         if row.anim and not mark[row] then
           mark[row] = true
           seen[#seen + 1] = row.anim
+          types[row.anim] = row.hit and row.hit.animType or false
         end
       end
+    end, types
   end
+
+  -- engine/battle/animations.asm:427-437
+  local function rideAndSample(battle, poll, frames, shotPath)
+    local peak, shot = 0, false
+    for i = 1, frames do
+      poll()
+      if i % 6 == 0 then U.tap(battle.game, "a") end
+      local fx = battle.fx
+      if fx and fx.shakeX and not battle.animPlaying then
+        local dx = math.abs(fx.shakeX)
+        if dx > peak then peak = dx end
+        if dx > 0 and not shot then
+          shot = true
+          U.shot(battle.game, shotPath)
+        end
+      end
+      U.wait(1)
+    end
+    return peak
   end
 
   local function listOf(seen)
@@ -136,23 +157,28 @@ return function(game)
   local battle = BattleState.newWild(game, "PIDGEY", 8)
   battle.onFinish = function() end
   ow:pushBattle(battle)
-  local seen, poll = watchAnims(battle)
+  local seen, poll, types = watchAnims(battle)
   check("the battle reached the menu", waitPhase(battle, "menu", 60, poll))
   check("BIDE is the move on the list", pickBide(battle, poll))
   for _ = 1, 20 do poll() U.wait(1) end
   U.shot(game, DIR .. "/bug375_store_spiral.png")
-  for _ = 1, 30 do poll() U.wait(1) end
+
+  local peak = rideAndSample(battle, poll, 180,
+                             DIR .. "/bug1564_store_shake.png")
   U.shot(game, DIR .. "/bug375_store_text.png")
 
   check("the storing turn queued XSTATITEM_ANIM", has(seen, "XSTATITEM_ANIM"))
   check("and not BIDE's hit animation: " .. listOf(seen), not has(seen, "BIDE"))
   check("BIDE locked in for " .. tostring(battle.player.bideTurns) .. " turns",
         battle.player.bideTurns ~= nil)
+  check("the storing spiral carries wAnimationType 6 (#1564)",
+        types["XSTATITEM_ANIM"] == 6)
+  check(("the screen shook, peak dx = %d px (want 3)"):format(peak), peak == 3)
 
   -- ride out the locked turns: the storing text needs A presses and the menu
   -- never comes back until BIDE unleashes
   local released = false
-  for _ = 1, 120 do
+  for _ = 1, 220 do
     U.tap(game, "a")
     for _ = 1, 6 do poll() U.wait(1) end
     if has(seen, "BIDE") then
@@ -179,7 +205,7 @@ return function(game)
   foeBattle.enemy.mon.moves = { { id = "BIDE", pp = 10 } }
   foeBattle.enemy.curMoves = foeBattle.enemy.mon.moves
   ow:pushBattle(foeBattle)
-  local foeSeen, foePoll = watchAnims(foeBattle)
+  local foeSeen, foePoll, foeTypes = watchAnims(foeBattle)
   check("the foe's battle reached the menu",
         waitPhase(foeBattle, "menu", 60, foePoll))
   pickBide(foeBattle, foePoll) -- ours does not matter here, the foe's does
@@ -192,10 +218,20 @@ return function(game)
   check("the foe's storing turn queued XSTATITEM_DUPLICATE_ANIM: "
           .. listOf(foeSeen), has(foeSeen, "XSTATITEM_DUPLICATE_ANIM"))
 
+  local foePeak = rideAndSample(foeBattle, foePoll, 180,
+                                DIR .. "/bug1564_enemy_store_shake.png")
+  check("the foe's spiral carries wAnimationType 3 (#1564)",
+        foeTypes["XSTATITEM_DUPLICATE_ANIM"] == 3)
+  check(("the foe's shake peaked at %d px (want 6)"):format(foePeak),
+        foePeak == 6)
+
   U.log("The pad is yours in a battle where both sides know only BIDE, so")
   U.log("pick FIGHT then BIDE and watch turn one: the screen palette flashes")
-  U.log("white and balls spiral inward, silently, and then it says storing")
+  U.log("white and balls spiral inward, silently. Then, still in silence, the")
-  U.log("energy. No flash on the RATTATA and no BIDE thud until the turn it")
+  U.log("whole battle screen creeps sideways 1 px at a time out to 3 px and")
+  U.log("back, twice, and only then does it say storing energy. On the foe's")
+  U.log("turn the same creep goes out to 6 px and takes twice as long.")
+  U.log("No flash on the RATTATA and no BIDE thud until the turn it")
   U.log("unleashes, where the thud and its animation come after the text and")
   U.log("before the enemy HP bar slides down. The foe's spiral looks the same.")
 

tests/drivers/bike_gate_wall_bug1548_test.lua

@@ -0,0 +1,101 @@
+-- scripts/Route16Gate1F.asm:38 / home/overworld.asm:1224
+-- data/maps/force_bike_surf.asm:5
+--   POKEPORT_DRIVER=tests/drivers/bike_gate_wall_bug1548_test.lua \
+--   POKEPORT_IDENTITY=bug1548 POKEPORT_TOUCH=0 POKEPORT_VERSION=red love .
+-- Watch the sprite after each teleport: it must never overlap the gate
+-- building's black outline.  Compare .bazinga/august21p2/media/1548-1.jpg.
+return function(game)
+  local U = dofile("tests/drivers/util.lua")
+  local Pokemon = require("src.pokemon.Pokemon")
+  local OverworldState = require("src.world.OverworldController")
+
+  local SHOT_DIR = os.getenv("SHOT_DIR") or "/tmp/shots"
+  local ok = true
+  local function check(label, pass)
+    U.log(pass and "PASS" or "FAIL", label)
+    if not pass then ok = false end
+    return pass
+  end
+
+  local function settle()
+    for _ = 1, 12 do
+      if game.stack:top() == game.overworld then break end
+      U.tap(game, "a")
+      U.wait(25)
+    end
+    U.wait(60)
+  end
+  local function landed()
+    local ow = game.overworld
+    local p = ow.player
+    return p.cellX, p.cellY, ow.map:isWalkableCell(p.cellX, p.cellY)
+  end
+  local function bikeless()
+    game.save.inventory.BICYCLE = nil
+    game.save.onBike, game.save.forcedBike = false, nil
+  end
+
+  game.save.player.name = "PROBE"
+  game.save.party = { Pokemon.new(game.data, "CHARIZARD", 50) }
+  bikeless()
+
+  local fm = game.data.field.forcedMovement
+  check("field.forcedMovement carries the Route 16 cells",
+        fm and fm.tiles and fm.tiles.ROUTE_16 ~= nil)
+
+  for _, c in ipairs({ { "ROUTE_16", 17, 10 }, { "ROUTE_16", 17, 11 },
+                       { "ROUTE_18", 33,  8 }, { "ROUTE_18", 33,  9 } }) do
+    bikeless()
+    U.teleport(game, c[1], c[2], c[3], "left")
+    U.wait(20)
+    settle()
+    local x, y, walk = landed()
+    U.log(("%s (%d,%d) facing left -> (%d,%d) walkable=%s")
+          :format(c[1], c[2], c[3], x, y, tostring(walk)))
+    check(("%s (%d,%d): the refusal leaves the player on a walkable cell")
+          :format(c[1], c[2], c[3]), walk)
+  end
+
+  bikeless()
+  U.teleport(game, "ROUTE_16", 17, 10, "left")
+  U.wait(20)
+  settle()
+  U.shot(game, SHOT_DIR .. "/bug1548_route16_after.png")
+
+  bikeless()
+  U.teleport(game, "ROUTE_16", 16, 10, "right")
+  U.wait(20)
+  U.hold(game, "right", 24)
+  settle()
+  local bx, by = landed()
+  U.log(("stepped onto ROUTE_16 (17,10) from the west -> (%d,%d)"):format(bx, by))
+  check("a shove with open ground behind it still moves one cell",
+        bx == 16 and by == 10)
+
+  bikeless()
+  while game.stack:top() do game.stack:pop() end
+  game.stack:push(OverworldState, "ROUTE_16", 18, 10, "left")
+  game.overworld:setMap("ROUTE_16", 18, 10, "left", { via = "boot" })
+  U.wait(20)
+  local cx, cy, cwalk = landed()
+  U.log(("boot inside the wall (18,10) -> (%d,%d) walkable=%s")
+        :format(cx, cy, tostring(cwalk)))
+  check("a save parked inside the gate wall is lifted out on load", cwalk)
+  settle()
+  local dx, dy, dwalk = landed()
+  U.log(("after the refusal that follows -> (%d,%d) walkable=%s")
+        :format(dx, dy, tostring(dwalk)))
+  check("and the refusal it lands on cannot push it back in", dwalk)
+  U.shot(game, SHOT_DIR .. "/bug1548_repaired.png")
+
+  game.save.inventory.BICYCLE = 1
+  game.save.onBike, game.save.forcedBike = false, nil
+  U.teleport(game, "ROUTE_16", 17, 10, "left")
+  U.wait(30)
+  local ex, ey, ewalk = landed()
+  check("with a BICYCLE the forced tile mounts instead of shoving",
+        game.save.onBike == true and ex == 17 and ey == 10 and ewalk)
+
+  U.log(ok and "all clear" or "a check failed")
+  while true do coroutine.yield() end
+end

tests/drivers/errorhandler_probe_bug1517_test.lua

@@ -0,0 +1,46 @@
+-- Driver: #1517's other half, the error handler that hid the crash.
+--
+-- boot.lua's deferErrhand picks `love.errorhandler or love.errhand`, so a
+-- love.errorhandler that returns nil ends love.run's `while func do` loop and
+-- the process leaves to the OS with no error screen and nothing on stdout.
+-- LOVE 11.5 pre-populates love.errhand only, so main.lua capturing
+-- love.errorhandler captured nil and every Lua error in every shipped build
+-- exited silently.  Measured on the installed 11.5:
+--   love.errorhandler type: nil / love.errhand type: function
+--
+-- Nothing here can be a unit test: the deliverable is whether a human sees
+-- LOVE's blue error screen or an app that vanishes.
+--
+--   POKEPORT_TOUCH=0 \
+--     POKEPORT_DRIVER=tests/drivers/errorhandler_probe_bug1517_test.lua love .
+--
+-- Pre-fix: the window closes on the first drawn frame after the probe arms,
+-- exit 1, no output.  Post-fix: the blue screen reads "bug1517: error-handler
+-- probe" plus the lua-error.log hint, and stays up until it is dismissed.
+return function(game)
+  local U = dofile("tests/drivers/util.lua")
+
+  U.log("[1517] love.errorhandler at boot was: "
+          .. (rawget(love, "errorhandler") and "a function" or "nil"))
+  U.log("[1517] love.errhand is: " .. type(rawget(love, "errhand")))
+
+  U.wait(30)
+
+  -- Raise from a draw callback, not from this coroutine: main.lua resumes the
+  -- driver under coroutine.resume and prints its errors itself, which is the
+  -- one path that does NOT reach love.errorhandler.  StateStack:draw only
+  -- calls the states it is actually holding, so the probe goes on the live
+  -- top state rather than on game.overworld, which is not on the stack while
+  -- the title screen or the load menu is up.
+  local target = game.stack:top()
+  U.log("[1517] arming the probe on " .. tostring(target and target.screenId))
+  local realDraw = target.draw
+  target.draw = function(self, ...)
+    if realDraw then realDraw(self, ...) end
+    error("bug1517: error-handler probe")
+  end
+
+  U.log("[1517] armed; the next drawn frame raises from love.draw")
+  U.log("[1517] you should now see LOVE's blue error screen, not a closed app")
+  while true do coroutine.yield() end
+end

tests/drivers/gold_bide_lock_bug1664_1665.lua

@@ -0,0 +1,171 @@
+-- BIDE on the real Gold battle screen: the PP counter in the move list, and
+-- the lock that keeps a storing mon on the move it started (#1664, #1665).
+--
+--   POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/gold_bide_lock_bug1664_1665.lua \
+--     POKEPORT_SHOT_DIR=/tmp/gold-bide love .
+--
+-- data/moves/effects.asm:795-800 puts `storeenergy` ahead of `doturn`, and
+-- BattleCommand_DoTurn masks SUBSTATUS_BIDE out of the PP spend
+-- (engine/battle/effect_commands.asm:977-979), so the whole three-turn Bide
+-- costs the one PP the opening turn paid.  The shots are the point: the
+-- number beside BIDE in the move list must read the same on 01, 02 and 03.
+--
+-- The lock is ParsePlayerAction's own arm (engine/battle/core.asm:569-576),
+-- which sits INSIDE the FIGHT branch and skips MoveSelectionScreen only -- so
+-- the 2x2 menu still opens, a switch is still legal, and using an item runs
+-- .reset_bide (:627-629) and CANCELS the store.  Block 2 submits TACKLE in
+-- the middle of a Bide on purpose: the engine has to answer with the Bide.
+--
+-- NOT covered here, and deliberately: src/ui/gen2/BattleState.lua still draws
+-- the move list on a storing turn.  The cart jumps past it.  That half is a
+-- screen change and is called out in the fix report rather than faked.
+local U = require("tests.drivers.util")
+
+local Mon = require("src.battle.gen2.Mon")
+
+local function battleScreen(game)
+  for _ = 1, 900 do
+    local top = game.stack:top()
+    if top and top.battle then return top end
+    U.wait(1)
+  end
+  error("battle screen never came up")
+end
+
+local function drain(game, screen, frames)
+  for _ = 1, (frames or 400) do
+    if screen.phase == "menu" and #screen.queue == 0 and not screen.anim then
+      return true
+    end
+    U.tap(game, "a")
+    U.wait(3)
+  end
+  return false
+end
+
+local function giveMoves(mon, game, moves)
+  mon.moves = {}
+  for i, id in ipairs(moves) do
+    local def = assert(game.data.moves[id], id .. " is not in moves.lua")
+    mon.moves[i] = { id = id, pp = def.pp, maxPp = def.pp }
+  end
+  return mon
+end
+
+local function newWild(game, species, level, moves)
+  local mon = Mon.new(game.data, species, level)
+  if moves then giveMoves(mon, game, moves) end
+  return mon
+end
+
+return function(game)
+  local out = os.getenv("POKEPORT_SHOT_DIR") or "/tmp/gold-bide"
+  U.wait(45)
+  local world = game.world
+  assert(world and world.map, "gold world did not boot")
+  local failures = {}
+  local function check(ok, what)
+    print((ok and "[ok] " or "[FAIL] ") .. what)
+    if not ok then failures[#failures + 1] = what end
+  end
+  local function pp(mon, slot) return mon.moves[slot].pp end
+
+  -- ------------------------------------------------------------------ 1
+  -- One Bide, start to finish, with the move list open between turns.  The
+  -- foe is a SPLASH-only RATTATA so nothing interrupts the store.
+  local player = Mon.new(game.data, "SNORLAX", 40)
+  giveMoves(player, game, { "BIDE", "TACKLE" })
+  game.save.party = { player }
+  game.save.inventory = { POTION = 5 }
+  local foe = newWild(game, "RATTATA", 20, { "TACKLE" })
+  assert(world:startBattle({ wild = foe }), "startBattle failed")
+  local screen = battleScreen(game)
+  drain(game, screen, 200)
+  local opening = pp(player, 1)
+  print(("[driver] BIDE opens at %d PP"):format(opening))
+
+  screen:submit({ kind = "move", move = "BIDE" })
+  drain(game, screen, 400)
+  U.shot(game, out .. "/01-selected.png")
+  local afterSelect = pp(player, 1)
+  print(("[driver] after the SELECTION turn: %d PP"):format(afterSelect))
+  check(afterSelect == opening - 1,
+    "the opening turn pays its one PP through doturn")
+  check(screen.battle:forcedMove(player) == "BIDE",
+    "and ParsePlayerAction's bide arm holds the FIGHT choice")
+
+  -- The middle of the store, with TACKLE deliberately submitted: the cart
+  -- never re-reads the move list, so wCurPlayerMove is still the BIDE.
+  local tackleBefore = pp(player, 2)
+  screen:submit({ kind = "move", move = "TACKLE" })
+  drain(game, screen, 400)
+  U.shot(game, out .. "/02-storing.png")
+  print(("[driver] after a STORING turn: BIDE %d PP, TACKLE %d PP")
+    :format(pp(player, 1), pp(player, 2)))
+  check(pp(player, 1) == afterSelect, "a storing turn spends no PP at all")
+  check(pp(player, 2) == tackleBefore,
+    "and the move the menu offered was never run")
+
+  -- The release.  Whatever the roll, the store is two or three turns
+  -- (UnleashEnergy's `BattleRandom / and 1 / inc a / inc a`,
+  -- move_effects/bide.asm:88-92), so keep pressing FIGHT until it lets go.
+  local foeBefore = foe.hp
+  for _ = 1, 3 do
+    if not screen.battle:forcedMove(player) then break end
+    screen:submit({ kind = "move", move = "BIDE" })
+    drain(game, screen, 400)
+  end
+  U.shot(game, out .. "/03-unleashed.png")
+  print(("[driver] after the RELEASE: %d PP, foe %d -> %d HP")
+    :format(pp(player, 1), foeBefore, foe.hp))
+  check(pp(player, 1) == afterSelect,
+    "the whole Bide cost exactly one PP, the way the cart charges it")
+  check(screen.battle:forcedMove(player) == nil, "and the lock is released")
+  for _ = 1, 400 do
+    if not game.stack:top() or not game.stack:top().battle then break end
+    U.tap(game, "a")
+    U.wait(3)
+  end
+  U.wait(60)
+
+  -- ------------------------------------------------------------------ 2
+  -- .reset_bide: a nonzero wBattlePlayerAction that is not
+  -- BATTLEPLAYERACTION_SWITCH clears SUBSTATUS_BIDE (core.asm:572-573,
+  -- :627-629), so opening the PACK mid-store throws the stored damage away.
+  local bider = Mon.new(game.data, "SNORLAX", 40)
+  giveMoves(bider, game, { "BIDE", "TACKLE" })
+  bider.hp = math.max(1, bider.hp - 30)
+  game.save.party = { bider }
+  game.save.inventory = { POTION = 5 }
+  local foe2 = newWild(game, "RATTATA", 20, { "TACKLE" })
+  assert(world:startBattle({ wild = foe2 }), "startBattle failed")
+  screen = battleScreen(game)
+  drain(game, screen, 200)
+  screen:submit({ kind = "move", move = "BIDE" })
+  drain(game, screen, 400)
+  check(screen.battle:forcedMove(bider) == "BIDE", "the second Bide is up")
+  screen:useItem("POTION")
+  drain(game, screen, 400)
+  U.shot(game, out .. "/04-item-cancelled.png")
+  print("[driver] after the PACK: forcedMove="
+    .. tostring(screen.battle:forcedMove(bider)))
+  check(screen.battle:forcedMove(bider) == nil,
+    "using an item cancels the Bide, as .reset_bide does")
+  check(screen.battle:volatile(bider).bideStored == nil,
+    "and the damage it had banked goes with it")
+  for _ = 1, 400 do
+    if not game.stack:top() or not game.stack:top().battle then break end
+    U.tap(game, "a")
+    U.wait(3)
+  end
+
+  print("[driver] NOTE: the move list is still drawn on a storing turn; the "
+    .. "cart's bide arm skips MoveSelectionScreen and that half lives in "
+    .. "src/ui/gen2/BattleState.lua")
+  if #failures > 0 then
+    for _, what in ipairs(failures) do print("[FAIL] " .. what) end
+    error(#failures .. " bide checks failed")
+  end
+  print("[driver] all bide checks passed")
+  print("[driver] shots in " .. out)
+end

tests/drivers/gold_billspc_arrows_bug1672.lua

@@ -0,0 +1,113 @@
+-- #1672: Bill's PC MOVE screen -- the box-name arrows.
+--
+--   POKEPORT_IDENTITY=gold-dev POKEPORT_GAME=gold POKEPORT_TOUCH=0 \
+--     POKEPORT_DRIVER=tests/drivers/gold_billspc_arrows_bug1672.lua \
+--     perl -e 'alarm 420; exec @ARGV' \
+--     python3 -c "import pty; pty.spawn(['love','.'])"
+--   POKEPORT_SHOT_DIR=/tmp/gold-bug1672-arrows   (default)
+--
+-- BillsPC_MoveMonWOMail_BoxNameAndArrows writes $5f at hlcoord 8, 1 and $5e at
+-- hlcoord 19, 1 (engine/pokemon/bills_pc.asm:957-963), replacing the box-name
+-- Textbox's own side borders.  Only _MovePKMNWithoutMail calls it: .Init (:545)
+-- and .PrepInsertCursor (:698).  The withdraw (:299) and deposit (:56) inits
+-- call bare BillsPC_BoxName (:965) and are the negative controls here.
+--
+-- What to look for in each shot: a solid LEFT-pointing triangle in the left
+-- border of the name box and a solid RIGHT-pointing one in the right border,
+-- both level with the name, on every move-mode shot and on neither of the last
+-- two.  Getting them the wrong way round is the failure this exists to catch.
+--
+-- The run ends with the MOVE screen open so a human takes the controls there.
+local U = require("tests.drivers.util")
+
+local Boxes = require("src.core.gen2.Boxes")
+local Mon = require("src.battle.gen2.Mon")
+local Screens = require("src.ui.Screens")
+
+return function(game)
+  local out = os.getenv("POKEPORT_SHOT_DIR") or "/tmp/gold-bug1672-arrows"
+
+  local function tap(button, frames)
+    game.input.pressQueue[#game.input.pressQueue + 1] = button
+    game.input.state[button] = true
+    U.wait(2)
+    game.input.state[button] = false
+    U.wait(frames or 6)
+  end
+
+  U.wait(45)
+  assert(game.world and game.world.map, "gold world did not boot")
+  local save, data = game.save, game.data
+
+  local function mon(species, level) return Mon.new(data, species, level) end
+
+  -- IsAnyMonHoldingMail refuses the whole screen (src/ui/gen2/PcMenu.lua:303),
+  -- so the seeded party carries no mail.
+  save.party = {}
+  for _, species in ipairs({ "CYNDAQUIL", "PIDGEY", "SENTRET" }) do
+    save.party[#save.party + 1] = mon(species, 12)
+  end
+  local stored = Boxes.box(save, 1)
+  for i = #stored, 1, -1 do stored[i] = nil end
+  for i, species in ipairs({ "GEODUDE", "ZUBAT", "RATTATA" }) do
+    stored[i] = mon(species, 10 + i)
+  end
+  Boxes.rename(save, 1, "GRASS")
+  save.currentBox = 1
+
+  local function openBox(mode)
+    Screens.push(game, "Gen2BoxMenu", {
+      save = save, mode = mode,
+      onClose = function() game.stack:pop() end,
+    })
+    U.wait(8)
+    return game.stack:top()
+  end
+
+  local function close()
+    while game.stack:top() and game.stack:top().submenuRows do
+      game.stack:pop()
+    end
+    U.wait(4)
+  end
+
+  -- ---- 1. the move list on a renamed box -----------------------------------
+  local menu = openBox("move")
+  U.log("01 move, box GRASS:", "want both arrows flanking GRASS on row 1")
+  U.shot(game, out .. "/01-move-box.png")
+
+  -- ---- 2. LEFT onto the PARTY ----------------------------------------------
+  -- BillsPC_BoxName's `.party` arm; only the move screen ever loads box 0.
+  tap("left")
+  U.log("02 move, PARTY:", "boxIndex " .. tostring(menu.boxIndex) ..
+    ", want 0 and both arrows still up")
+  U.shot(game, out .. "/02-move-party.png")
+  tap("right")
+
+  -- ---- 3. the MOVE / STATS / CANCEL submenu --------------------------------
+  tap("a")
+  U.log("03 submenu:", "phase " .. tostring(menu.phase) ..
+    ", want submenu and both arrows still up")
+  U.shot(game, out .. "/03-move-submenu.png")
+
+  -- ---- 4. the insert cursor (.PrepInsertCursor rewrites them) --------------
+  tap("a", 10)
+  U.log("04 insert:", "phase " .. tostring(menu.phase) ..
+    ", want insert and both arrows still up")
+  U.shot(game, out .. "/04-move-insert.png")
+  close()
+
+  -- ---- 5/6. the negative controls ------------------------------------------
+  openBox("withdraw")
+  U.log("05 withdraw:", "want plain border tiles, NO arrows")
+  U.shot(game, out .. "/05-withdraw-none.png")
+  close()
+
+  openBox("deposit")
+  U.log("06 deposit:", "want plain border tiles, NO arrows")
+  U.shot(game, out .. "/06-deposit-none.png")
+  close()
+
+  openBox("move")
+  U.log("done -- the MOVE screen is open; the controls are yours")
+end