chore(ios): update app-repo.json [skip ci]

bugs and slugs

.github/workflows/release.yml

@@ -1,8 +1,9 @@
 name: Release
 
 # Builds the macOS, Windows, and Linux desktop apps, an Android APK, an iOS
-# IPA, a Nintendo Switch SD-ready zip (experimental), Xbox UWP, and the Anbernic
-# RG34XXSP (Stock OS 64-bit MOD / PortMaster) port, then publishes them as a
+# IPA, a Nintendo Switch SD-ready zip (experimental), Xbox UWP, the Anbernic
+# RG34XXSP (Stock OS 64-bit MOD / PortMaster) and Linux ARM SBC PortMaster
+# handheld ports on the self-hosted Mac runner, and publishes them as a
 # GitHub Release.
 #
 # Versioning:
@@ -355,6 +356,20 @@ jobs:
           # runtime from PortMaster-GUI, so it needs no signing/notarization.
           ./build-rg34xxsp.sh --version "${{ needs.version.outputs.version }}"
 
+      - name: Build Linux ARM SBC PortMaster port
+        env:
+          # The release workflow must package the commit being released. The
+          # script defaults to the latest published release for standalone
+          # builds, while this explicit local override keeps CI source-aligned.
+          GEN1RECOMP_SOURCE_DIR: ${{ github.workspace }}
+          GEN1RECOMP_RELEASE_TAG: v${{ needs.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          # Same aarch64 PortMaster-style pack for Linux ARM SBC PortMaster. The build
+          # keeps its own cache because the two scripts use different staging
+          # layouts and runtime package paths.
+          ./build-linux-arm-sbc.sh --version "${{ needs.version.outputs.version }}"
+
       - name: Notarize & staple macOS app
         if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
@@ -449,6 +464,11 @@ jobs:
           [ -f "$rg34" ] || { echo "::error::$rg34 not found (expected from ./build-rg34xxsp.sh)"; exit 1; }
           cp "$rg34" "$outdir/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip"
 
+          # Linux ARM SBC PortMaster handheld port.
+          sbc="dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip"
+          [ -f "$sbc" ] || { echo "::error::$sbc not found (expected from ./build-linux-arm-sbc.sh)"; exit 1; }
+          cp "$sbc" "$outdir/gen1recomp-${v}-sbc-portmaster.zip"
+
           # Platform-independent update payload, built alongside the desktop
           # apps above (same game.love that gets fused into each of them).
           love_file=".bazinga/work/game.love"
@@ -564,6 +584,7 @@ jobs:
             "dist/release/gen1recomp-${v}-switch.zip"
             "dist/release/gen1recomp-${v}-xbox-uwp.zip"
             "dist/release/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip"
+            "dist/release/gen1recomp-${v}-sbc-portmaster.zip"
             "dist/release/gen1recomp-${v}.love"
             "dist/release/sha256sums.txt"
           )

CONTRIBUTING-mods.md

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

KANTO-CONTINUE.md

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

build-linux-arm-sbc.sh

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

build-rg34xxsp.sh

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

docs/linux-arm-sbc.md

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

docs/modding.md

@@ -340,6 +340,18 @@ failure as a failed first checkpoint rather than claiming restart safety.
 See RFC 0003, RFC 0004, RFC 0005, and RFC 0006 for exact contracts and error
 codes.
 
+At that same settled supported wild/trainer decision boundary, a tool may claim
+START through `battle.menu_auxiliary`. It receives `(next, game, context)`, where
+`context` is the data-only `{ kind = "wild" }` or `{ kind = "trainer" }`; it
+never receives the live battle controller. Return `true` to consume START after
+opening source-owned UI, or call `next(game, context)` to allow lower-priority
+handlers. With no handler, START remains inert. Ordinary encounters and the
+validated built-in scripted battle origins described by RFC 0005 are eligible;
+opaque scripts, link/Safari/ghost/demo battles, action queues,
+animation/messages, forced choices, and every phase that cannot safely be
+checkpointed remain excluded. Exceptions are contained by normal hook isolation
+and fall through without advancing a turn.
+
 ## Developer console
 
 Boot with developer mode on to unlock the in-game console and hot-reload
@@ -442,9 +454,12 @@ identifiers: `pc_box_withdraw`, `pc_box_deposit`, `pc_box_release`,
 `battle.bottom_ui_visible` and `battle.status_hud_visible` independently
 control the battle text/menu layer and the HP/status panels. Both receive
 `(next, state)` and default to `true`, so vanilla rendering is unchanged.
-Pushed text boxes also pass through `battle.bottom_ui_visible`; a wrapper that
-only owns battle presentation should return `false` only for its active battle
-or text-box state.
+Text boxes and YES/NO prompts pushed above a battle inherit a `false` result
+for that battle, so hiding the bottom layer cannot leave their white backing
+behind under another overlay. Text boxes also pass through the hook as their
+own state, preserving selective control outside a battle; a wrapper that only
+owns battle presentation should return `false` only for its active battle or
+text-box state.
 
 `core.logic_speed` receives `(next, game)` once per `Game:logicSpeed()` call
 (once per frame). Vanilla behavior resolves the per-category GAME SPEED
@@ -495,6 +510,21 @@ Neither hook needs a `Runtime.wantsHook` guard before calling it: `Hooks:call`
 already falls straight through to the vanilla function when no mod has
 wrapped the name, at negligible cost.
 
+## Detached Pokémon icon presentation
+
+`mod.ui.PokemonIcon.draw(game, summary, x, y, opts)` draws the same party icon
+the native Party menu would resolve without exposing a live Pokémon record or
+the private Party menu. `summary` is the detached data-only shape
+`{ species = string, hp = integer, maxHp = integer }`; `opts.selected` and
+`opts.counter` optionally request the native selected-icon animation phase.
+
+The engine retains icon ownership. Content registered through
+`mod.content.icons`, species `icon` definitions, asset overrides, and the
+public `pokemon.icon` hook therefore continue to compose. Invalid summaries
+return `false, code, message` and draw nothing. The helper is presentation
+only: it does not expose moves, status, checkpoint payloads, or mutable party
+state.
+
 ## Shared date and time presentation
 
 The global Options menu owns `DATE FORMAT` (`DEVICE`, `DD-MM-YYYY`,
@@ -514,17 +544,3 @@ local both = mod.datetime:dateTime(game, createdAt)
 The live `game` supplies only the current option context. Formatting never
 mutates the save, options, or timestamp, and invalid timestamps return
 `"----"`.
-
-## Device power information
-
-Sandboxed mods can read the host's battery state without receiving the rest
-of `love.system`:
-
-```lua
-local state, percent = mod.device:powerInfo()
-```
-
-`state` follows LÖVE's values: `"unknown"`, `"battery"`, `"nobattery"`,
-`"charging"`, or `"charged"`. `percent` is `0` through `100`, or `nil` when
-the platform cannot report it. The facade is read-only and does not expose
-URL launching, clipboard access, or other system operations.

docs/new-features.md

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

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

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

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

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

install-linux-arm-sbc.sh

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

mobile/ios/app-repo.json

@@ -12,6 +12,20 @@
       "tintColor": "3b5ca8",
       "category": "games",
       "versions": [
+        {
+          "version": "0.1.80",
+          "date": "2026-08-12",
+          "size": 10964568,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.80/gen1recomp-0.1.80-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1100 Allow for control edit and vibration toggle on gold\n- #1107 [Gold] When playing without a save slot in the launcher, no save will be created at all when saving ingame\n- #1112 [Gold] In the shop when buying items and pressing \"down\", it should not default to x99\n- #1121 [Gold] NPC trading (probably player too?) animation broken / missing things\n- #1126 [Gold] Jumping off ledge animation missing\n- #1130 A separate program for Gen2 (Gen2 Recomp)\n- #1145 Gen1recomp internal update - Mod didn't filter for Gen1 and Gen2 when click on individual tab\n- #1150 Control in Gold freeze when change\n- #1151 [Gold] Following up of #1127\n- #1152 [Gold] You cannot try to run away from wild battle after one of your Pokemon gets fainted.\n- #1161 window/borderless & resolution selection for gen2\n- #1162 [gold] learning TM/HM doesn't show if possible or not\n- #1164 Goldenrod Tower Softlock\n- #1165 [Gold] NPC trading behavior and ledge jumping missing still there despite fix\n- #1166 [Gold] nickname screen grey\n- #1167 [Gold] items in ilex forest missing\n- #1168 [Gold] multi-hit attacks only hits twice\n- #1169 [Gold] the sales lady in goldenrod underground\n- #1172 [Gold] {last item u found/got} used ROCK SMASH\n- #1173 [Gold] ROCK SMASH rocks keep slide left\n- #1177 [Gold] Touch controls position\n- #1178 No Vibration Setting for Gold\n- #1180 [Gold] something feels off with the DV calculation\n- #1184 [Gold] Kurt is in the wrong spot, blocking you from progressing\n- #1185 [Gold] Text messages is in the wrong order when a Pokemon learns a new skill after a trainer fight\n- #1188 GoldenRod tower softlock\n- #1190 POKEMON GOLD GEN1RECOMP++\n- #1192 cant import gold on RGXX build\n\n## Contributors\n\n- @anxiousintrovert\n- @AverageConsumer\n- @bryanthaboi\n- @MaxTomahawk\n- @ShaneMcGovernIE\n- @thibautbus"
+        },
+        {
+          "version": "0.1.79",
+          "date": "2026-08-12",
+          "size": 10956333,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.79/gen1recomp-0.1.79-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1090 With TILT Option enabled, screen does not correctly render beyond what would be visible with TILT Disabled.\n- #1093 Gen 2 Gold Beta: jingle doesn't play when receiving Elm's phone number\n- #1094 Gen 2 Gold Beta: no battle SFX when animations are Off\n- #1095 Gen 2 Gold Beta: player sprite has white box outline that cuts off Pokémon sprites\n- #1098 [Gold] Can't change controls (no menu for it and it doesn't use the one set in RBY)\n- #1102 [Gold] Shop ui off because of a border\n- #1105 [Gold] Game speed doesn't apply to the intro\n- #1106 [Gold] Games slots don't respect portable.txt\n- #1108 [Gold] Launcher doesn't show any information about the save slot(s)\n- #1109 [Options] text speed doesn't work at all.\n- #1110 [Gold] When catching a Pokemon, the ball disappears  and the text doesn't wait for you to progress\n- #1111 [Gold] nurse joy doesn't look left for healing\n- #1113 [Gold] Poke center -> Bills PC -> Deposit Pokemon, screen off\n- #1114 [Gold] Can't release Pokemon, menu doesn't appear\n- #1117 [Gold/Options] sound doesn't change\n- #1118 [Gold] Berrys animation missing and speedup.\n- #1121 [Gold] NPC trading (probably player too?) animation broken / missing things\n- #1122 [Gold] Level up UI.\n- #1123 [Gold] Character stops \"inside door\" when leaving buildings instead of moving one tile down\n- #1124 [Gold] When \"turning\", no animation is played\n- #1126 [Gold] Jumping off ledge animation missing\n- #1127 [Gold] Very minor Pokegear issues.\n- #1128 [Gold] When calling mom, the yes/no dialogue background color doesn't fit\n- #1131 [Gold] Pokegear map bug(s)\n- #1132 [gold] pokedex bugs\n- #1134 Unable to Validate/Pack mod calling Gold's overworld sprite\n- #1137 64x64 sprite support broken for mods on Gen 2\n- #1141 Teleport doesn't end wild battle\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi\n- @dburton95\n- @dlloa\n- @MaxTomahawk\n- @swuff-star\n- @TheRealSolidusSnake\n- @thibautbus"
+        },
         {
           "version": "0.1.78",
           "date": "2026-08-11",

mods/timekeepers_hut

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

scripts/build_android.sh

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

scripts/linux-arm64/build_appimage.sh

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

scripts/linux-arm64/selftest_build_linux_arm64.sh

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

src/battle/BattleSafety.lua

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

src/battle/BattleState.lua

@@ -21,12 +21,14 @@ local MoveEffects = require("src.battle.MoveEffects")
 local Party = require("src.pokemon.Party")
 local Pokemon = require("src.pokemon.Pokemon")
 local Runtime = require("src.mods.Runtime")
+local BattleSafety = require("src.battle.BattleSafety")
 local Screens = require("src.ui.Screens")
 local Status = require("src.battle.Status")
 local Timing = require("src.core.Timing")
 local TrainerAI = require("src.battle.TrainerAI")
 local TurnOrder = require("src.battle.TurnOrder")
 local TypeChart = require("src.battle.TypeChart")
+local UIVisibility = require("src.battle.UIVisibility")
 local RomText = require("src.core.RomText")
 local Strings = require("src.core.Strings")
 local WideBattle = require("src.battle.WideBattle")
@@ -134,9 +136,7 @@ function BattleState:sgbPalettes()
 end
 
 function BattleState:bottomUIVisible()
-  if not Runtime.wantsHook("battle.bottom_ui_visible") then return true end
-  return Runtime.call("battle.bottom_ui_visible", function() return true end,
-                      self) ~= false
+  return UIVisibility.bottomVisible(self, true)
 end
 
 function BattleState:statusHUDVisible()
@@ -1962,6 +1962,17 @@ function BattleState:update(dt)
       self:resolveTurn(locked)
       return
     end
+    -- START has no vanilla action at a settled supported player-decision
+    -- boundary.  A tool mod may claim this semantic auxiliary action through
+    -- the public hook, receiving only game plus a data-only kind.  The shared
+    -- safety predicate keeps every unsupported/forced/animated phase inert.
+    if input:wasPressed("start") and Runtime.wantsHook("battle.menu_auxiliary") then
+      local safe = BattleSafety.inspect(self.game, self)
+      if safe and Runtime.call("battle.menu_auxiliary", function() return false end,
+          self.game, { kind = self.kind }) == true then
+        return
+      end
+    end
     local col = (self.menuIndex - 1) % 2
     local row = math.floor((self.menuIndex - 1) / 2)
     if input:wasPressed("left") then

src/battle/UIVisibility.lua

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

src/battle/gen2/Battle.lua

@@ -217,7 +217,7 @@ function Battle.new(opts)
   opts = opts or {}
   local self = setmetatable({}, Battle)
   self.data = opts.data or {}
-  self.random = opts.random
+  self.random = opts.random or function(n) return rand(nil, n) end
   self.party = opts.party or {}
   self.trainer = opts.trainer
   self.save = opts.save
@@ -271,6 +271,13 @@ function Battle.new(opts)
     self.enemy = self.enemyParty[self.enemyIndex]
   end
 
+  for _, mon in ipairs(self.party) do
+    Mon.refreshStats(mon, self.data)
+  end
+  for _, mon in ipairs(self.enemyParty or {}) do
+    Mon.refreshStats(mon, self.data)
+  end
+
   -- Battle RAM opens empty on both sides: NewBattleMonStatus and
   -- NewEnemyMonStatus run at the first send-out of every battle.
   self:clearAllVolatiles()
@@ -1655,7 +1662,7 @@ function Battle:useMove(attacker, defender, moveId)
       state.rolloutLock = nil
     end
 
-    local hits = Effects.hitCount(def.effect, self.random)
+    local hits = Effects.hitCount(def.effect, self:roller())
     local landed = 0
     for hit = 1, hits do
       if (defender.hp or 0) <= 0 then break end
@@ -3178,7 +3185,8 @@ function Battle:giveExperiencePass(loser, def, recipients, count, halved)
         -- ChangeHappiness is outside the level loop.
         Happiness.change(mon, "GAINLEVEL")
         self:emit({ kind = "level", index = index, level = mon.level,
-          text = self:monName(mon) .. " grew to level " .. mon.level .. "!" })
+          text = self:monName(mon) .. " grew to level " .. mon.level .. "!",
+          sfx = "Sfx_DexFanfare5079", waitSfx = true })
         for _, moveId in ipairs(result.learned) do
           local ok, reason, entry = Mon.learnMove(mon, moveId, self.data)
           local moveDef = self:moveDef(moveId)
@@ -3644,7 +3652,7 @@ end
 -- Running: Gen 2's odds (engine/battle/core.asm TryToRunAwayFromBattle) are
 -- based on the speed ratio and how many times you have tried this battle.
 -- Trainers never let you run.
-function Battle:tryRun()
+function Battle:tryRun(pSpd)
   -- .cant_escape and .cant_run_from_trainer leave wBattlePlayerAction alone,
   -- which is what BattleMenu_Run reads to decide whether the turn was spent
   -- (engine/battle/core.asm:5035); only .cant_escape_2, the failed roll at the
@@ -3676,7 +3684,8 @@ function Battle:tryRun()
     return false
   end
   self.runAttempts = (self.runAttempts or 0) + 1
-  if self:runRoll(self:effectiveSpeed(self.player),
+  -- engine/battle/core.asm:2614
+  if self:runRoll(pSpd or self:effectiveSpeed(self.player),
       self:effectiveSpeed(self.enemy)) then
     self:emit({ kind = "run", text = "Got away safely!" })
     self:endBattle("run")

src/battle/gen2/Effects.lua

@@ -100,21 +100,28 @@ end
 -- are 1/8 each, which is what the `and 3` on a 0-3 roll plus the two-step
 -- fallthrough in .DetermineNumberOfHits produces.
 function Effects.multiHitCount(random)
-  local roll = random and random(4) or 0
-  if roll < 2 then return roll + 2 end
-  -- Hits 4 and 5 take a second roll, so each ends up half as likely.
-  local second = random and random(2) or 0
-  return second + 4
+  local function roll(n)
+    if random then return random(n) end
+    if love and love.math and love.math.random then
+      return love.math.random(n) - 1
+    end
+    return math.random(n) - 1
+  end
+  -- engine/battle/effect_commands.asm:5228
+  local first = roll(4)
+  if first < 2 then return first + 2 end
+  return roll(4) + 2
 end
 
 Effects.HIT_COUNTS = {
   EFFECT_DOUBLE_HIT = 2,
+  EFFECT_POISON_MULTI_HIT = 2,
   -- Triple Kick stops early if a hit misses; Battle rolls that per hit.
   EFFECT_TRIPLE_KICK = 3,
 }
 
 function Effects.hitCount(effect, random)
-  if effect == "EFFECT_MULTI_HIT" or effect == "EFFECT_POISON_MULTI_HIT" then
+  if effect == "EFFECT_MULTI_HIT" then
     return Effects.multiHitCount(random)
   end
   return Effects.HIT_COUNTS[effect] or 1

src/battle/gen2/Mon.lua

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

src/core/Checkpoint.lua

@@ -7,6 +7,7 @@ local Version = require("src.core.Version")
 local BattleState = require("src.battle.BattleState")
 local BattleCheckpoint = require("src.core.BattleCheckpoint")
 local ModRuntime = require("src.mods.Runtime")
+local BattleSafety = require("src.battle.BattleSafety")
 
 local Checkpoint = {}
 
@@ -36,72 +37,9 @@ local function scriptsBusy(ow)
     or nonempty(ow.scriptMoves)
 end
 
-local BATTLE_BUSY_FIELDS = {
-  "current", "afterQueue", "nextInsert", "pendingHit", "waitingUI",
-  "waitingSound", "waitFrames", "draining", "animPlaying", "growIn",
-  "introSlide", "ghostReveal", "mimicCtx", "mimicMoves", "result",
-}
-
-local function inspectBattle(ow, battle)
-  if battle.kind == "link" then
-    return refusal("battle", "link_battle_unsupported",
-      "Network battles cannot be checkpointed.")
-  end
-  if battle.safari or battle.ghost or battle.scopeReveal or battle.demo
-      or battle.noCatch then
-    return refusal("battle", "battle_variant_unsupported",
-      "This battle variant does not have a checkpoint contract.")
-  end
-  if battle.kind ~= "wild" and battle.kind ~= "trainer" then
-    return refusal("battle", "battle_variant_unsupported",
-      "This battle kind does not have a checkpoint contract.")
-  end
-  local origin = battle.checkpointOrigin
-  local ordinaryOrigin = battle.kind == "wild" and "wild_encounter"
-    or "trainer_encounter"
-  local scriptedOrigin = type(origin) == "table"
-    and origin.kind == "script_battle"
-  if type(origin) ~= "table"
-      or (origin.kind ~= ordinaryOrigin and not scriptedOrigin) then
-    return refusal("battle", "battle_origin_unsupported",
-      "The battle completion path cannot be reconstructed safely.")
-  end
-  local scriptedRunner = scriptedOrigin and (battle.checkpointScriptContinuation
-    or (ow.runner
-    and ow.runner.isCheckpointBattle
-    and ow.runner:isCheckpointBattle(battle)))
-  local otherScriptWork = nonempty(ow.parallelRunners)
-    or nonempty(ow.pendingScripts) or nonempty(ow.parallelQueue)
-    or nonempty(ow.scriptMoves)
-  if (scriptedOrigin and (not scriptedRunner or otherScriptWork))
-      or (not scriptedOrigin and scriptsBusy(ow)) then
-    return refusal("battle", "script_busy",
-      "A suspended or queued script cannot be checkpointed.")
-  end
-  if battle.phase ~= "menu" or nonempty(battle.queue) then
-    return refusal("battle", "battle_phase_busy",
-      "Wait for the player command menu before creating a checkpoint.")
-  end
-  for _, field in ipairs(BATTLE_BUSY_FIELDS) do
-    if battle[field] ~= nil and battle[field] ~= false then
-      return refusal("battle", "battle_phase_busy",
-        "Wait for the current battle action to finish.")
-    end
-  end
-  if not battle.player or not battle.enemy or battle.player.mon.hp <= 0
-      or (battle.menuLockedAction and battle:menuLockedAction(battle.player)) then
-    return refusal("battle", "battle_phase_busy",
-      "Wait for an ordinary player decision before creating a checkpoint.")
-  end
-  for _, battler in ipairs({ battle.player, battle.enemy }) do
-    if battler.shownHP ~= battler.mon.hp
-        or battler.shownStatus ~= battler.mon.status
-        or battler.drainFloor ~= nil or battler.drainHold ~= nil
-        or battler.faintQueued then
-      return refusal("battle", "battle_phase_busy",
-        "Wait for battle status and HP presentation to settle.")
-    end
-  end
+local function inspectBattle(game, battle)
+  local allowed, reason, message = BattleSafety.inspect(game, battle)
+  if not allowed then return refusal("battle", reason, message) end
   return { canCapture = true, canRestore = true, kind = "battle" }
 end
 
@@ -120,7 +58,7 @@ function Checkpoint.inspect(game)
   end
   local top = game.stack and game.stack.top and game.stack:top()
   if getmetatable(top) == BattleState then
-    return inspectBattle(ow, top)
+    return inspectBattle(game, top)
   end
   if top ~= ow then
     return refusal("overworld", "screen_busy",

src/core/Game.lua

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

src/core/Game2.lua

@@ -109,6 +109,12 @@ local function makeStack()
   return StateStack
 end
 
+local function visibleBaseState(stack)
+  if not stack then return nil end
+  local state = stack.states[stack:visibleBase()]
+  return stack:renderVisible(state) and state or nil
+end
+
 local function loadGenerated(path)
   local chunk = love.filesystem.load(path)
   if not chunk then return nil end
@@ -1441,8 +1447,7 @@ end
 -- them but the Pokegear, whose paper is RGB 28,31,20.  Nil means white, which
 -- is what Font.drawBox does by default.
 function Game2:textboxPaper()
-  local base = self.stack and self.stack.states
-    and self.stack.states[self.stack:visibleBase()]
+  local base = visibleBaseState(self.stack)
   if base and base.paperColor then return base:paperColor() end
   return nil
 end
@@ -1455,10 +1460,11 @@ function Game2:drawScene(w, h)
 
   if self:inFillBoot() then
     local top = self.stack:top()
-    local base = self.stack.states[self.stack:visibleBase()]
+    local base = visibleBaseState(self.stack)
     -- Title (and friends) paint sky/clouds edge-to-edge; Oak speech and
     -- name pick paint a paper-white surround via drawWidescreen.
-    local wide = (top and top.drawsWidescreen and top:drawsWidescreen()
+    local wide = (self.stack:renderVisible(top)
+      and top.drawsWidescreen and top:drawsWidescreen()
       and top.drawWidescreen) and top
       or (base and base.drawsWidescreen and base:drawsWidescreen()
         and base.drawWidescreen and base)
@@ -1507,8 +1513,9 @@ function Game2:drawScene(w, h)
     -- PARTY, PACK, #DEX, PC, DAY-CARE, MAILBOX and TRADE screens whenever a
     -- TextBox goes up over them.
     local top = self.stack:top()
-    local base = self.stack.states[self.stack:visibleBase()]
-    local wide = (top and top.drawsWidescreen and top:drawsWidescreen()
+    local base = visibleBaseState(self.stack)
+    local wide = (self.stack:renderVisible(top)
+      and top.drawsWidescreen and top:drawsWidescreen()
       and top.drawWidescreen) and top
       or (base and base.drawsWidescreen and base:drawsWidescreen()
         and base.drawWidescreen and base)
@@ -1906,11 +1913,10 @@ function Game2:applyOptions()
   require("src.render.Pipelines").applyOptions(options)
   -- src/core/Game.lua:1121 mirrors this call for Gen 1
   Input:applyBindings(options.bindings)
-  -- options.touchControls (the launcher editor's per-orientation layouts) and
-  -- options.haptics, the same two keys Gen 1 hands over here
-  -- (src/core/Game.lua:1073).  One options.lua serves both games, so the pad a
-  -- player laid out for Red is already the pad Gold draws.
-  TouchControls:applyOptions(options)
+  TouchControls:applyOptions({
+    touchControls = options.touchControls,
+    haptics = options.haptics,
+  })
   local GBCFX = require("src.render.GBCFX")
   if GBCFX.applyOptions(options) and self.save then
     -- applyOptions returns true when it had to clear an unsupported level.

src/core/Input.lua

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

src/core/TouchControls.lua

@@ -211,6 +211,10 @@ function TouchControls.defaultLayout(ww, wh, ox, oy, scale)
   local abW = dpadW * 0.46
   local ssW = dpadW * 0.30
   local margin = dpadW * 0.12
+  local ok, GameVersion = pcall(require, "src.core.GameVersion")
+  if ok and GameVersion.isGold and GameVersion.isGold() then
+    margin = math.max(margin, math.min(ww * 0.10, 72))
+  end
   return {
     dpad = { cx = ox + margin + dpadW / 2, cy = oy + wh - margin - dpadW / 2, w = dpadW },
     a = { cx = ox + ww - margin - abW * 0.55, cy = oy + wh - margin - abW * 1.75, w = abW },

src/core/gen2/Save.lua

@@ -275,6 +275,8 @@ Save.DEFAULT_OPTIONS = {
   musicVol = 7,             -- 0-7, like the GB's NR50 master volume
   sfxVol = 7,               -- 0-7
   musicFilter = 0,          -- low-pass steps, 0 = off
+  haptics = "light",
+  touchControls = { enabled = true },
 }
 
 function Save.defaultOptions()
@@ -719,6 +721,13 @@ end
 -- copy is the witness that survives a crash mid-replace.
 function Save.save(save)
   if type(save) ~= "table" then return false, "no save" end
+  if (save.version or "gold") == "gold" then
+    local ok, SaveData = pcall(require, "src.core.SaveData")
+    if ok and SaveData.activeSlot and not SaveData.activeSlot("gold") then
+      local id = SaveData.createSlot and SaveData.createSlot("gold")
+      if id and SaveData.setActiveSlot then SaveData.setActiveSlot("gold", id) end
+    end
+  end
   local main, backup, tmp = saveNames(save.version)
   local f = fs()
   if not f then return false, "no filesystem" end

src/import/RomImporter.lua

@@ -1370,6 +1370,10 @@ function RomImporter.new(onComplete, opts)
     end
   end
 
+  if GameVersion.VERSIONS[self.tab] then
+    self.modScope = self.tab
+  end
+
   return self
 end
 
@@ -2627,6 +2631,9 @@ function RomImporter:_switchTab(id)
   self.tab = id
   self._findSearchFocus = false
   self:_disarmTextInput()
+  if GameVersion.VERSIONS[id] then
+    self:_setModScope(id)
+  end
 end
 
 function RomImporter:_toggleFindSearchFocus()
@@ -2937,6 +2944,13 @@ function RomImporter:_refreshMods()
     end
   end
   self.mods = LauncherMods.list(self.modScope) or {}
+  if self.modScope then
+    local kept = {}
+    for _, m in ipairs(self.mods) do
+      if m.targetsHere ~= false then kept[#kept + 1] = m end
+    end
+    self.mods = kept
+  end
   self:_syncModUpdateInfo(false)
 end
 
@@ -3586,7 +3600,7 @@ function RomImporter:_findRows()
   -- index, query, or category actually changed.
   local c = self._findRowsCache
   if c and c.src == all and c.query == self.findQuery
-      and c.category == self.findCategory then
+      and c.category == self.findCategory and c.scope == self.modScope then
     return c.rows
   end
   local ModIndex = require("src.mods.ModIndex")
@@ -3594,8 +3608,33 @@ function RomImporter:_findRows()
     query = self.findQuery,
     category = self.findCategory,
   })
+  if self.modScope then
+    local gen = GameVersion.generation(self.modScope)
+    local kept = {}
+    for _, entry in ipairs(rows) do
+      local has1, has2 = false, false
+      local function note(s)
+        s = tostring(s or ""):lower()
+        if s == "gen1" or s == "gen 1" or s == "red" or s == "blue"
+            or s == "yellow" then
+          has1 = true
+        end
+        if s == "gen2" or s == "gen 2" or s == "gold" then
+          has2 = true
+        end
+      end
+      for _, cat in ipairs(entry.categories or {}) do note(cat) end
+      for _, tag in ipairs(entry.tags or {}) do note(tag) end
+      if (not has1 and not has2)
+          or (gen == 2 and has2)
+          or (gen ~= 2 and has1) then
+        kept[#kept + 1] = entry
+      end
+    end
+    rows = kept
+  end
   self._findRowsCache = { src = all, query = self.findQuery,
-    category = self.findCategory, rows = rows }
+    category = self.findCategory, scope = self.modScope, rows = rows }
   return rows
 end
 

src/mods/AssetTransform.lua

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

src/mods/Loader.lua

@@ -12,8 +12,6 @@ local Manifest = require("src.mods.Manifest")
 local Merge = require("src.mods.Merge")
 local ModTargets = require("src.mods.ModTargets")
 local Registry = require("src.mods.Registry")
-local SafePath = require("src.mods.SafePath")
-local Sandbox = require("src.mods.Sandbox")
 local Schemas = require("src.mods.Schemas")
 local Semver = require("src.mods.Semver")
 local Events = require("src.mods.Events")
@@ -74,12 +72,10 @@ local function orderedIds(mods, filter)
   return ids
 end
 
--- ------- the require gate
--- Two jobs in one interposition.  The engine_internals/network scan is
--- attribution only and stays dev-mode: it warns and delegates.  The
--- Sandbox.moduleDenial check is not -- require("io") would hand back
--- package.loaded.io and undo the whole mod environment -- so it is installed
--- in player builds too, for any boot that has mods on it.
+-- ------- dev-mode permissions tripwire
+-- Attribution only: the shim delegates unconditionally and blocks nothing.
+-- Installed once per process and only when the loader runs in dev mode, so a
+-- player build has zero interposition.
 
 local devShim = { installed = false, permissions = {}, warned = {}, depth = 0 }
 
@@ -139,8 +135,7 @@ end
 
 local function scanRequire(name)
   local modId = Runtime.currentMod
-  if type(modId) ~= "string" then modId = Runtime.modRequire end
-  if type(modId) ~= "string" or type(name) ~= "string" then return end
+  if not modId or type(name) ~= "string" then return end
   local granted = devShim.permissions[modId] or {}
   local function warnOnce(permission)
     local key = modId .. "|" .. permission .. "|" .. name
@@ -193,7 +188,6 @@ function Loader:_installDevShim()
   for id, mod in pairs(self.mods) do
     devShim.permissions[id] = mod.manifest.permissionSet
   end
-  devShim.dev = self.dev
   if devShim.installed then return end
   devShim.installed = true
   local delegate = require
@@ -201,22 +195,12 @@ function Loader:_installDevShim()
     -- only the mod's own call is the mod's doing; whatever that module
     -- requires in turn is the engine wiring itself up
     if devShim.depth == 0 then
-      -- Backstop for the deny list Sandbox.envFor's require already applies:
-      -- an engine module requiring io is the engine wiring itself up, a mod
-      -- doing it is the hole this closes, and any future path that runs mod
-      -- code without a sandbox env still lands here.
-      local owner = Runtime.currentMod or Runtime.modRequire
-      if owner or callerIsMod(3) then
-        local id = type(owner) == "string" and owner or nil
-        local denial = Sandbox.moduleDenial(name, devShim.permissions[id])
-        if denial then error(("[%s] %s"):format(id or "mod", denial), 0) end
-      end
-      if devShim.dev or devShim.generation ~= 1 then scanRequire(name) end
+      scanRequire(name)
       -- The Gen 1 name a mod asked for, answered by the Gen 2 arm behind it.
       -- Engine code keeps the real module: src/render/PaletteFX.lua:776
       -- requires src.core.Game on both generations and means it.
       if devShim.generation ~= 1 and Gen2Compat.serves(name)
-          and (owner or callerIsMod(3)) then
+          and callerIsMod(3) then
         local adapter = Gen2Compat.resolve(name, Runtime.currentMod)
         if adapter then
           local key = "adapter|" .. name
@@ -251,7 +235,7 @@ function Loader.new(opts)
     events = Events.new(), hooks = Hooks.new(), content = {}, assets = {},
     exports = {}, migrations = {}, order = {},
     modSave = {}, modOptions = {}, optionSchemas = {}, imageCache = {},
-    modInput = {}, modEnv = {},
+    modInput = {},
     fs = (opts and opts.fs) or (love and love.filesystem),
     dev = dev,
     -- Which generation this boot is (1 or 2).  Fixed at construction: the
@@ -374,13 +358,11 @@ function Loader:_writeOptionSchemas()
       -- demand; using it here means older mods do not need to migrate to
       -- mod.options:define just to appear in a launcher settings screen.
       if schema == nil and mod.manifest.options_schema and self.fs.load then
-        local ok, rows = pcall(function()
-          local path = SafePath.join(mod.path, mod.manifest.options_schema,
-            "options_schema")
-          local chunk = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
-          return chunk and chunk()
-        end)
-        if ok and type(rows) == "table" then schema = rows end
+        local chunk = self.fs.load(mod.path .. "/" .. mod.manifest.options_schema)
+        if chunk then
+          local ok, rows = pcall(chunk)
+          if ok and type(rows) == "table" then schema = rows end
+        end
       end
       if schema ~= nil then
         mods[id] = schema
@@ -999,16 +981,6 @@ function Loader:_api(mod)
         return DateTime.dateTime(game, timestamp)
       end,
     },
-    -- The read-only part of love.system that device UIs legitimately need.
-    -- Do not expose the module: openURL and clipboard access stay sandboxed.
-    device = {
-      powerInfo = function()
-        local getPowerInfo = love and love.system and love.system.getPowerInfo
-        if not getPowerInfo then return "unknown", nil end
-        local state, percent = getPowerInfo()
-        return state, percent
-      end,
-    },
     -- namespaced per mod; M11 backs these with save.modData /
     -- options.modOptions, the shape mods compile against is already final
     save = {
@@ -1119,11 +1091,9 @@ function Loader:_api(mod)
   -- assets keeps the v1 alias to the content accessors and adds the file
   -- helpers on top, so mod.assets.pokemon and mod.assets:image both resolve
   api.assets = setmetatable({
-    path = function(_, relative)
-      return SafePath.join(mod.path, relative, "mod.assets:path")
-    end,
+    path = function(_, relative) return mod.path .. "/" .. relative end,
     image = function(_, relative)
-      local full = SafePath.join(mod.path, relative, "mod.assets:image")
+      local full = mod.path .. "/" .. relative
       local cached = loader.imageCache[full]
       if cached then return cached end
       assert(love and love.graphics,
@@ -1133,10 +1103,9 @@ function Loader:_api(mod)
       return image
     end,
   }, { __index = api.content })
-  -- the mod's own directory and nothing above it: PhysFS already refuses a
-  -- climb, but loader.fs is injectable and has no such floor
   function api:read(relative)
-    return loader.fs.read(SafePath.join(self.path, relative, "mod:read"))
+    local path = self.path .. "/" .. relative
+    return loader.fs.read(path)
   end
   -- mod.world materializes on first touch, like the image helper above: a
   -- headless load must not drag the world stack in, and the Game the facade
@@ -1180,21 +1149,9 @@ function Loader:_game()
   return engineRequire("src.core.Game")
 end
 
--- The environment every chunk this mod authors runs in, built once per mod so
--- its entry file and its options_schema share one globals table.
-function Loader:_modEnv(mod)
-  local id = mod.manifest.id
-  local env = self.modEnv[id]
-  if not env then
-    env = Sandbox.envFor({ modId = id, permissions = mod.manifest.permissionSet })
-    self.modEnv[id] = env
-  end
-  return env
-end
-
 function Loader:_loadMod(mod)
-  local path = SafePath.join(mod.path, mod.manifest.entry, "manifest entry")
-  local chunk, err = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
+  local path = mod.path .. "/" .. mod.manifest.entry
+  local chunk, err = self.fs.load(path)
   if not chunk then error(err or ("unable to load " .. path)) end
   local api = self:_api(mod)
   local result = chunk(api)
@@ -1392,12 +1349,10 @@ function Loader:load(data)
   -- every touch: a mod captures the facade at file scope, before Game2 has a
   -- save or a world (src/mods/Gen2Compat.lua).
   Gen2Compat.bind(function() return self:_game() end)
-  -- Any boot with mods on it needs the gate, because require("io") is how a
-  -- mod would walk out of Sandbox.envFor.  Dev mode adds the permissions
-  -- tripwire on top, and a Gold boot the Gen 1-only require report -- the
-  -- difference between "the mod does nothing" and knowing why.  A boot with no
-  -- mods pays nothing.
-  if self.dev or next(self.mods) ~= nil then
+  -- Dev mode wants the permissions tripwire; a Gold boot with mods on it wants
+  -- the Gen 1-only require report, which is the difference between "the mod
+  -- does nothing" and knowing why.  A Gold boot with no mods pays nothing.
+  if self.dev or (self.generation ~= 1 and next(self.mods) ~= nil) then
     self:_installDevShim()
   end
   for _, mod in ipairs(ordered) do

src/mods/ManagerState.lua

@@ -8,8 +8,6 @@ local Font = require("src.render.Font")
 local GameVersion = require("src.core.GameVersion")
 local ModTargets = require("src.mods.ModTargets")
 local Runtime = require("src.mods.Runtime")
-local SafePath = require("src.mods.SafePath")
-local Sandbox = require("src.mods.Sandbox")
 local SaveData = require("src.core.SaveData")
 local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
@@ -938,18 +936,13 @@ function ManagerState:schemaFor(m)
   local schema = loader.optionSchemas and loader.optionSchemas[m.id]
   if schema == nil and m.options_schema and m.path
       and loader.fs and loader.fs.load then
-    -- mod-authored code, so it runs in the same sandbox the entry chunk does
-    local ok, rows = pcall(function()
-      local path = SafePath.join(m.path, m.options_schema, "options_schema")
-      local mod = loader.mods and loader.mods[m.id]
-      local env = mod and loader._modEnv and loader:_modEnv(mod)
-        or Sandbox.envFor()
-      local chunk = Sandbox.loadFile(loader.fs, path, env)
-      return chunk and chunk()
-    end)
-    if ok and type(rows) == "table" then
-      schema = rows
-      if loader.optionSchemas then loader.optionSchemas[m.id] = schema end
+    local chunk = loader.fs.load(m.path .. "/" .. m.options_schema)
+    if chunk then
+      local ok, rows = pcall(chunk)
+      if ok and type(rows) == "table" then
+        schema = rows
+        if loader.optionSchemas then loader.optionSchemas[m.id] = schema end
+      end
     end
   end
   return schema

src/mods/Manifest.lua

@@ -3,7 +3,6 @@
 -- that need to stat a file, this owns shape, vocabulary and range grammar.
 local Logger = require("src.core.Logger")
 local ModTargets = require("src.mods.ModTargets")
-local SafePath = require("src.mods.SafePath")
 local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
 
@@ -145,9 +144,6 @@ function Manifest.validate(raw, path)
   assert(type(raw.name) == "string" and raw.name ~= "", "manifest name is required")
   assert(type(raw.version) == "string" and raw.version ~= "", "manifest version is required")
   assert(type(raw.entry) == "string" and raw.entry ~= "", "manifest entry is required")
-  -- every manifest path is joined to the mod's own directory, so none of them
-  -- may climb out of it (src/mods/SafePath.lua)
-  local entry = SafePath.require(raw.entry, "manifest entry")
 
   -- absent means 1: full v1 compat, schema violations downgrade to warnings
   assert(raw.api == nil or tonumber(raw.api) ~= nil, "manifest api must be a number")
@@ -233,24 +229,19 @@ function Manifest.validate(raw, path)
   local affectsLink = profile ~= "content" and not language
   if type(raw.affects_link) == "boolean" then affectsLink = raw.affects_link end
 
-  local function optionalString(value, field)
+  local function optionalFile(value, field)
     if value == nil then return nil end
     assert(type(value) == "string" and value ~= "", field .. " must be a file path")
     return value
   end
 
-  local function optionalFile(value, field)
-    local text = optionalString(value, field)
-    return text and SafePath.require(text, field)
-  end
-
   local conflicts = mergeConflictLists(raw.conflicts, raw.incompatible)
 
   return {
     id = raw.id,
     name = raw.name,
     version = raw.version,
-    entry = entry,
+    entry = raw.entry,
     api = api,
     priority = tonumber(raw.priority) or 0,
     dependencies = array(raw.dependencies),
@@ -274,8 +265,7 @@ function Manifest.validate(raw, path)
     permissionSet = permissionSet,
     options_schema = optionalFile(raw.options_schema, "options_schema"),
     assets_transforms = optionalFile(raw.assets_transforms, "assets_transforms"),
-    -- an env var name, not a path, so it keeps the plain string check
-    force_enable_env = optionalString(raw.force_enable_env, "force_enable_env"),
+    force_enable_env = optionalFile(raw.force_enable_env, "force_enable_env"),
     path = path,
     raw = raw,
   }

src/mods/Runtime.lua

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

src/mods/SafePath.lua

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

src/mods/Sandbox.lua

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

src/render/TextBox.lua

@@ -7,7 +7,7 @@
 -- the text is exhausted and A is pressed, then calls onDone.
 
 local Font = require("src.render.Font")
-local Runtime = require("src.mods.Runtime")
+local UIVisibility = require("src.battle.UIVisibility")
 local Theme = require("src.ui.Theme")
 local Timing = require("src.core.Timing")
 
@@ -393,11 +393,7 @@ function TextBox:update(dt)
 end
 
 function TextBox:draw()
-  if Runtime.wantsHook("battle.bottom_ui_visible")
-      and Runtime.call("battle.bottom_ui_visible", function() return true end,
-                       self) == false then
-    return
-  end
+  if not UIVisibility.bottomVisible(self, true) then return end
   -- The dialogue box belongs against the bottom of the screen, not floating
   -- in the middle of a zoomed-out letterbox.  Declared per frame; the
   -- renderer blits this region to the screen edge and the rest of the UI

src/script/gen2/CallAsm.lua

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

src/ui/BindingsMenu.lua

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

src/ui/ChoiceBox.lua

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

src/ui/ModUI.lua

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

src/ui/PokemonIcon.lua

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

src/ui/TouchControlsEditor.lua

@@ -49,17 +49,29 @@ end
 function Editor.load(opts)
   opts = opts or {}
   Editor.onClose = opts.onClose
+  Editor.version = opts.version
+  Editor.hostPoll = opts.hostPoll == true
   Editor.drag = nil
   Editor.rects = {}
+  Editor._hostMouse = false
+  Editor._hostTouches = nil
   Editor.fonts = {
     title = love.graphics.newFont(28),
     body = love.graphics.newFont(16),
     btn = love.graphics.newFont(18),
   }
   local optsTbl = SaveData.loadOptions()
+  local applied = optsTbl
+  if opts.version == "gold" then
+    local gold = type(optsTbl.gold) == "table" and optsTbl.gold or {}
+    applied = {
+      touchControls = gold.touchControls,
+      haptics = gold.haptics or optsTbl.haptics,
+    }
+  end
   TouchControls:init()
   TouchControls:ensureImages()
-  TouchControls:applyOptions(optsTbl)
+  TouchControls:applyOptions(applied)
   TouchControls:setPreview(true)
   Editor.enabled = TouchControls.enabled ~= false
   PadCursor.reset()
@@ -71,17 +83,24 @@ function Editor.unload()
   PadCursor.reset()
   Editor.drag = nil
   Editor.onClose = nil
+  Editor.version = nil
+  Editor._hostMouse = false
+  Editor._hostTouches = nil
 end
 
 local function persist()
   local opts = SaveData.loadOptions()
   local cfg = TouchControls:config()
-  -- replaces the whole table, so a pre-#633 top-level positions key is
-  -- dropped once the player saves under the new shape
-  opts.touchControls = {
+  local block = {
     enabled = cfg.enabled,
     layouts = cfg.layouts,
   }
+  if Editor.version == "gold" then
+    opts.gold = type(opts.gold) == "table" and opts.gold or {}
+    opts.gold.touchControls = block
+  else
+    opts.touchControls = block
+  end
   SaveData.saveOptions(opts)
 end
 
@@ -104,9 +123,7 @@ end
 
 function Editor.update(dt)
   PadCursor.update(dt or 0)
-  -- drag follows the live pointer when love.touch / mouse / pad is available;
-  -- touchmoved / mousemoved also update, so this is a belt-and-suspenders
-  -- path for Android where move events can be thin
+  if Editor.hostPoll then Editor.pollHostPointers() end
   if not Editor.drag then return end
   local x, y
   if Editor.drag.touchId == "pad" then
@@ -297,6 +314,45 @@ local function endDrag(id)
   Editor.drag = nil
 end
 
+function Editor.pollHostPointers()
+  local down = love.mouse and love.mouse.isDown and love.mouse.isDown(1)
+  if down then
+    local x, y = love.mouse.getPosition()
+    if not Editor._hostMouse then
+      Editor._hostMouse = true
+      beginDrag("mouse", x, y)
+    else
+      moveDrag("mouse", x, y)
+    end
+  elseif Editor._hostMouse then
+    Editor._hostMouse = false
+    endDrag("mouse")
+  end
+  if not (love.touch and love.touch.getTouches and love.touch.getPosition) then
+    return
+  end
+  Editor._hostTouches = Editor._hostTouches or {}
+  local seen = {}
+  for _, id in ipairs(love.touch.getTouches()) do
+    seen[id] = true
+    local ok, tx, ty = pcall(love.touch.getPosition, id)
+    if ok and tx then
+      if not Editor._hostTouches[id] then
+        Editor._hostTouches[id] = true
+        beginDrag(id, tx, ty)
+      else
+        moveDrag(id, tx, ty)
+      end
+    end
+  end
+  for id in pairs(Editor._hostTouches) do
+    if not seen[id] then
+      Editor._hostTouches[id] = nil
+      endDrag(id)
+    end
+  end
+end
+
 function Editor.mousepressed(x, y, button)
   if button ~= 1 then return end
   -- Finger / mouse tap yields the Joy-Con pointer so the click lands where
@@ -391,4 +447,35 @@ function Editor.keypressed(key)
   end
 end
 
+function Editor.new(game)
+  local state = { game = game, isOpaque = true }
+  Editor.hostPoll = true
+  Editor.load({
+    version = "gold",
+    hostPoll = true,
+    onClose = function()
+      Editor.hostPoll = false
+      if game.options then
+        game.options.touchControls = TouchControls:config()
+      end
+      if game.stack and game.stack:top() == state then
+        game.stack:pop()
+      end
+      if game.applyOptions then game:applyOptions() end
+    end,
+  })
+  function state:wantsFillScale() return true end
+  function state:drawsWidescreen() return true end
+  function state:update(dt)
+    Editor.update(dt)
+    local input = self.game and self.game.input
+    if input and input:wasPressed("b") then close() end
+  end
+  function state:draw() end
+  function state:drawWidescreen(_w, _h)
+    Editor.draw()
+  end
+  return state
+end
+
 return Editor

src/ui/gen2/BattleState.lua

@@ -92,6 +92,8 @@ local FAINT_SLIDE_FRAMES_PER_ROW = 2
 -- (engine/battle/core.asm:3439-3466, data/text/battle.asm:241-249).
 local TEXT_NO_WILL_TO_FIGHT = "There's no will to battle!"
 local TEXT_EGG_CANT_BATTLE = "An EGG can't battle!"
+-- data/text/battle.asm:207
+local TEXT_USE_NEXT_MON = "Use next POKéMON?"
 
 -- BattleText_TheMoveIsDisabled / BattleText_TheresNoPPLeftForThisMove
 -- (data/text/battle.asm:315-322).
@@ -1146,11 +1148,11 @@ function BattleState:advanceQueue()
     -- pokegold engine/battle/core.asm:7057-7069: every mon that leveled
     -- gets the stats box, not just the mon currently on the field.
     self.pendingStatsMon = mon
-    -- BattleText_StringBuffer1GrewToLevel ends in text_end (battle.asm:336-343),
-    -- and the active mon never even prints it (core.asm:7044-7056 jumps to the
-    -- stats box).  Either way there is no PromptButton before the stats box.
+    -- engine/battle/core.asm:7044
     if mon and mon == battle.player then
       event.text = nil
+      event.sfx = nil
+      event.waitSfx = nil
       if self.shownHp then
         self.shownHp.player = mon.hp or 0
         if self.hpAnim and self.hpAnim.side == "player" then
@@ -1270,6 +1272,14 @@ function BattleState:advanceQueue()
     return self:askNickname(event.mon)
   end
   if event.kind == "choose-switch" then
+    -- engine/battle/core.asm:2590
+    if self.battle and self.battle.wild then
+      self.nextMonIndex = 1
+      self.phase = "ask-next-mon"
+      self.message = TEXT_USE_NEXT_MON
+      self.messageTimer = 0
+      return
+    end
     -- A fainted lead: force a switch before anything else runs.
     self.phase = "forced-switch"
     self.message = "Choose a POKéMON."
@@ -1876,6 +1886,36 @@ function BattleState:update(_dt)
     return
   end
 
+  -- engine/battle/core.asm:2590
+  if self.phase == "ask-next-mon" then
+    if self.messageTimer > 0 then
+      if input:wasPressed("a") or input:wasPressed("b") then
+        self.messageTimer = 0
+      end
+      return
+    end
+    if input:wasPressed("up") or input:wasPressed("down") then
+      self.nextMonIndex = self.nextMonIndex == 1 and 2 or 1
+    elseif input:wasPressed("b") then
+      return self:answerUseNextMon(false)
+    elseif input:wasPressed("a") then
+      return self:answerUseNextMon(self.nextMonIndex == 1)
+    end
+    return
+  end
+
+  if self.phase == "cant-escape-then-switch" then
+    if self.messageTimer > 0 then
+      if input:wasPressed("a") or input:wasPressed("b") then
+        self.messageTimer = 0
+      end
+      return
+    end
+    self.message = "Choose a POKéMON."
+    self.phase = "forced-switch"
+    return
+  end
+
   if self.phase == "refuse-shift" then
     if self.messageTimer > 0 then
       if input:wasPressed("a") or input:wasPressed("b") then
@@ -2433,6 +2473,31 @@ function BattleState:offerShiftSwitch(mon)
   self.messageTimer = MESSAGE_FRAMES
 end
 
+function BattleState:answerUseNextMon(yes)
+  if yes then
+    self.phase = "forced-switch"
+    self.message = "Choose a POKéMON."
+    return
+  end
+  local battle = self.battle
+  if not battle then
+    self.phase = "forced-switch"
+    return
+  end
+  local lead = battle.party and battle.party[1]
+  local pSpd = (lead and lead.stats and lead.stats.speed) or 0
+  -- engine/battle/core.asm:2614
+  if battle:tryRun(pSpd) then
+    self:pushAll(battle:takeEvents())
+    self.phase = "resolving"
+    return self:advanceQueue()
+  end
+  battle:takeEvents()
+  self.message = "Can't escape!"
+  self.messageTimer = MESSAGE_FRAMES
+  self.phase = "cant-escape-then-switch"
+end
+
 -- SetUpBattlePartyMenu + PickSwitchMonInBattle (core.asm:3307-3308), which is
 -- PARTYMENUACTION_SWITCH and carries no submenu; a cancel is `.canceled_switch`
 -- and answers exactly like NO (:3327).
@@ -3173,15 +3238,18 @@ function BattleState:drawPanel()
     -- stands.
     local asking = self.phase == "ask-nickname" or self.phase == "ask-forget"
       or self.phase == "stop-learning" or self.phase == "ask-shift"
+      or self.phase == "ask-next-mon"
     if asking and (self.messageTimer or 0) <= 0 then
       -- OfferSwitch calls PlaceYesNoBox with `lb bc, 1, 7`, so its box is at
       -- (1,7) instead (engine/battle/core.asm:3303, home/menu.asm:392-410).
-      local left = self.phase == "ask-shift" and 1 or 14
+      local left = (self.phase == "ask-shift" or self.phase == "ask-next-mon")
+        and 1 or 14
       Chrome.box(left, 7, 6, 5)
       Chrome.print("YES", left + 2, 8)
       Chrome.print("NO", left + 2, 10)
       local index = self.phase == "ask-nickname" and self.nicknameIndex
         or self.phase == "ask-shift" and self.shiftIndex
+        or self.phase == "ask-next-mon" and self.nextMonIndex
         or self.forgetChoice
       Chrome.cursor(left + 1, index == 1 and 8 or 10)
     end
@@ -3201,7 +3269,13 @@ local STATS_BOX_ROWS = {
 
 -- pokegold engine/battle/core.asm:7060-7066 (box at hlcoord 9,0, stats at 11,y).
 function BattleState:drawStatsBox(mon)
-  local stats = mon and mon.stats
+  if not mon then return end
+  local stats = mon.stats
+  local data = self.game and self.game.data
+  local def = data and data.pokemon and data.pokemon[mon.species]
+  if def and def.baseStats then
+    stats = Mon.stats(def.baseStats, mon.dvs, mon.level, mon.statExp)
+  end
   if not stats then return end
   Chrome.textbox(9, 0, 9, 10)
   for i, row in ipairs(STATS_BOX_ROWS) do

src/ui/gen2/MartMenu.lua

@@ -75,7 +75,8 @@ local SFX_TRANSACTION = "Sfx_Transaction"
 
 local MartMenu = {}
 MartMenu.__index = MartMenu
-MartMenu.isOpaque = true
+-- engine/items/mart.asm:54
+MartMenu.isOpaque = false
 
 -- constants/mart_constants.asm.  The `pokemart` macro emits this as one byte
 -- ahead of the word mart id, and MartTypeDialogs is indexed by it.
@@ -330,9 +331,6 @@ local function extractedText(text, base, labels)
   return out
 end
 
-function MartMenu:wantsFillScale() return true end
-function MartMenu:drawsWidescreen() return true end
-
 -- data/generated/marts.lua is what the ROM extractor will write out of `Marts`
 -- (data/items/marts.asm): `lists` is a 1-based array in MART_* order, each
 -- entry an array of item ids, and `bargain` is BargainShopData's own
@@ -896,7 +894,8 @@ local function printPriceOpaque(amount, ty)
 end
 
 function MartMenu:drawBuyList()
-  -- pokegold engine/menus/scrolling_menu.asm _InitScrollingMenu: no border for the buy list
+  -- engine/items/mart.asm:542
+  Chrome.box(LIST_BOX_X, LIST_BOX_Y, LIST_BOX_W, LIST_BOX_H)
   for row = 1, VISIBLE_ROWS do
     local i = row + self.scroll
     local ty = LIST_Y + (row - 1) * LIST_SPACING
@@ -953,18 +952,14 @@ end
 function MartMenu:drawUnder()
   local phase = self.phase
   if phase == "top" then
-    Chrome.clear()
     self:drawTopMenu()
     self:drawTextBox(self.topLines)
   elseif phase == "buy" or phase == "buyQuantity" then
-    Chrome.clear()
     self:drawMoneyBox()
     self:drawBuyList()
     self:drawDescription()
   elseif phase == "sell" or phase == "sellQuantity" then
     if self.pack then self.pack:drawPanel() end
-  else
-    Chrome.clear()
   end
 end
 
@@ -1003,17 +998,4 @@ function MartMenu:draw()
   self:drawPanel()
 end
 
-function MartMenu:drawWidescreen(winW, winH)
-  local G = love.graphics
-  G.setColor(1, 1, 1, 1)
-  G.rectangle("fill", 0, 0, winW, winH)
-  local scale = Chrome.fitScale(winW, winH)
-  G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
-  G.scale(scale, scale)
-  self:drawPanel()
-  G.pop()
-end
-
 return MartMenu

src/ui/gen2/NamingScreen.lua

@@ -119,7 +119,13 @@ function NamingScreen.new(game, opts)
   -- The header icon is an OBJ on the cart, so it wears a real palette; without
   -- one it would draw in raw DMG shades next to a colored world.
   self.iconColors = opts.iconColors
-  self.gfx = opts.menuGfx
+  local data = game and game.data or {}
+  self.gfx = opts.menuGfx or data.gen2MenuGfx
+  if self.gfx and self.gfx.naming then self.gfx = self.gfx.naming end
+  -- engine/menus/naming_screen.asm:47
+  -- engine/gfx/cgb_layouts.asm:488
+  local diploma = data.gen2Diploma
+  self.palette = diploma and diploma.palettes and diploma.palettes[1]
   self.tiles = {}
   if self.gfx then
     for _, key in ipairs({ "border", "middleLine", "underLine", "cursor" }) do
@@ -315,6 +321,10 @@ function NamingScreen:update(_dt)
   end
 end
 
+function NamingScreen:paperColor()
+  return GbcPalette.color(self.palette, 1)
+end
+
 -- The backdrop: one patterned tile repeated over the whole screen.  Without
 -- menu_gfx.lua (older cache) fall back to a flat mid gray, which keeps the
 -- cleared panels readable.
@@ -322,17 +332,25 @@ function NamingScreen:drawBackdrop()
   local G = love.graphics
   local tile = self.tiles.border
   if not tile then
-    G.setColor(0.62, 0.62, 0.62, 1)
+    local paper = self:paperColor()
+    G.setColor(paper[1] / 255, paper[2] / 255, paper[3] / 255, 1)
     G.rectangle("fill", 0, 0, 160, 144)
     G.setColor(1, 1, 1, 1)
     return
   end
-  G.setColor(1, 1, 1, 1)
-  for ty = 0, Chrome.SCREEN_H - 1 do
-    for tx = 0, Chrome.SCREEN_W - 1 do
-      G.draw(tile, tx * 8, ty * 8)
+  local function blit()
+    G.setColor(1, 1, 1, 1)
+    for ty = 0, Chrome.SCREEN_H - 1 do
+      for tx = 0, Chrome.SCREEN_W - 1 do
+        G.draw(tile, tx * 8, ty * 8)
+      end
     end
   end
+  if self.palette and GbcPalette.available() then
+    GbcPalette.with(self.palette, blit)
+  else
+    blit()
+  end
 end
 
 -- The cursor (data/sprite_anims/oam.asm .OAMData_TextEntryCursor and
@@ -410,7 +428,8 @@ end
 
 function NamingScreen:clearPanel(tx, ty, tw, th)
   local G = love.graphics
-  G.setColor(1, 1, 1, 1)
+  local paper = self:paperColor()
+  G.setColor(paper[1] / 255, paper[2] / 255, paper[3] / 255, 1)
   G.rectangle("fill", tx * 8, ty * 8, tw * 8, th * 8)
   G.setColor(0, 0, 0, 1)
 end
@@ -472,12 +491,13 @@ function NamingScreen:drawPanel()
       G.draw(self.iconImage, quad, 16, 16)
     end
   end
+  local pal = self.palette
   if self.monName then
     -- Nickname header is two lines: "<MON>'S" then "NICKNAME?".
-    Chrome.print(self.monName .. "'S", 5, 2)
-    Chrome.print("NICKNAME?", 5, 4)
+    Chrome.printThrough(self.monName .. "'S", 5, 2, pal)
+    Chrome.printThrough("NICKNAME?", 5, 4, pal)
   else
-    Chrome.print(self.prompt, 5, 2)
+    Chrome.printThrough(self.prompt, 5, 2, pal)
   end
   self:drawEntry(5, self.isBox and 4 or 6)
 
@@ -489,17 +509,22 @@ function NamingScreen:drawPanel()
     for col = 0, 8 do
       local ch = line[col + 1]
       if ch and ch ~= " " and ch ~= "" then
-        Chrome.print(ch, 2 + col * 2, keyboardTop + row * 2)
+        Chrome.printThrough(ch, 2 + col * 2, keyboardTop + row * 2, pal)
       end
     end
   end
   local labels = self.lower and BOTTOM_LOWER_LABELS or BOTTOM_UPPER_LABELS
   local bottomY = keyboardTop + bottom * 2
   for i, label in ipairs(labels) do
-    Chrome.print(label, BOTTOM_LABEL_TX[i], bottomY)
+    Chrome.printThrough(label, BOTTOM_LABEL_TX[i], bottomY, pal)
   end
 
-  self:drawCursorBox(self:cursorTile())
+  local function cursor() self:drawCursorBox(self:cursorTile()) end
+  if pal and GbcPalette.available() then
+    GbcPalette.with(pal, cursor)
+  else
+    cursor()
+  end
   G.setColor(1, 1, 1, 1)
 end
 
@@ -511,23 +536,32 @@ function NamingScreen:drawWidescreen(winW, winH)
   local G = love.graphics
   -- The naming screen's own patterned backdrop is the surround: extend it to
   -- the window edges so a widescreen boot has no black pillarbox.
-  self:drawBackdrop()
   local scale = Chrome.fitScale(winW, winH)
   local ox, oy = Chrome.fitOrigin(winW, winH, scale)
-  G.setColor(0.62, 0.62, 0.62, 1)
+  local paper = self:paperColor()
+  G.setColor(paper[1] / 255, paper[2] / 255, paper[3] / 255, 1)
   G.rectangle("fill", 0, 0, winW, winH)
   G.setColor(1, 1, 1, 1)
   if self.tiles.border then
     local tilesX = math.ceil(winW / (8 * scale))
     local tilesY = math.ceil(winH / (8 * scale))
-    G.push()
-    G.scale(scale, scale)
-    for ty = 0, tilesY do
-      for tx = 0, tilesX do
-        G.draw(self.tiles.border, tx * 8, ty * 8)
+    local tile = self.tiles.border
+    local function blit()
+      G.setColor(1, 1, 1, 1)
+      G.push()
+      G.scale(scale, scale)
+      for ty = 0, tilesY do
+        for tx = 0, tilesX do
+          G.draw(tile, tx * 8, ty * 8)
+        end
       end
+      G.pop()
+    end
+    if self.palette and GbcPalette.available() then
+      GbcPalette.with(self.palette, blit)
+    else
+      blit()
     end
-    G.pop()
   end
   G.push()
   G.translate(ox, oy)

src/ui/gen2/OptionsMenu.lua

@@ -172,6 +172,34 @@ local ROWS = {
     text = function(options)
       return require("src.render.GBCFX").levelLabel(options.gbcfx or 0)
     end },
+  { id = "touchControls", label = "TOUCH PAD", port = true,
+    text = function(options)
+      local tc = options.touchControls
+      local on = not (type(tc) == "table" and tc.enabled == false)
+      return on and "ON" or "OFF"
+    end,
+    cycle = function(options, _delta, game)
+      local tc = type(options.touchControls) == "table" and options.touchControls or {}
+      tc.enabled = tc.enabled == false
+      options.touchControls = tc
+      require("src.core.TouchControls"):applyOptions(options)
+      if game and game.persistOptions then game:persistOptions() end
+    end },
+  { id = "touchLayout", label = "TOUCH LAYOUT", port = true,
+    activate = function(game)
+      game.stack:push(require("src.ui.TouchControlsEditor").new(game))
+    end },
+  { id = "haptics", label = "VIBRATION", port = true,
+    text = function(options)
+      return require("src.core.TouchControls").hapticLabel(options.haptics)
+    end,
+    cycle = function(options, delta, game)
+      local TC = require("src.core.TouchControls")
+      options.haptics = TC.cycleHaptics(options.haptics, delta)
+      TC:applyOptions(options)
+      TC.buzz(options.haptics)
+      if game and game.persistOptions then game:persistOptions() end
+    end },
   { label = "CANCEL", cancel = true },
 }
 
@@ -196,11 +224,18 @@ local function sameRows(_, rows) return rows end
 -- COLOR) simply appear in the list the hook receives.
 local function buildRows()
   local rows = {}
+  local env = os.getenv("POKEPORT_TOUCH")
+  local osName = love.system and love.system.getOS and love.system.getOS()
+  local showTouch = env == "1"
+    or (env ~= "0" and (osName == "Android" or osName == "iOS"))
   for i, row in ipairs(ROWS) do
-    local copy = {}
-    for key, value in pairs(row) do copy[key] = value end
-    copy.id = copy.id or copy.key or (copy.cancel and "cancel") or nil
-    rows[i] = copy
+    if showTouch or (row.id ~= "touchControls" and row.id ~= "touchLayout"
+        and row.id ~= "haptics") then
+      local copy = {}
+      for key, value in pairs(row) do copy[key] = value end
+      copy.id = copy.id or copy.key or (copy.cancel and "cancel") or nil
+      rows[#rows + 1] = copy
+    end
   end
   return rows
 end
@@ -291,6 +326,9 @@ end
 
 function OptionsMenu:leave_()
   if self.onDone then self.onDone(self.options) end
+  if self.game and self.game.stack and self.game.stack:top() == self then
+    self.game.stack:pop()
+  end
 end
 
 function OptionsMenu:update(_dt)

src/ui/gen2/PackMenu.lua

@@ -354,6 +354,12 @@ function PackMenu:useSelected()
     end
     return
   end
+  -- engine/items/tmhm.asm:73
+  local def = self.items and self.items[row.id]
+  if def and def.teaches then
+    self:openTeachParty(row)
+    return
+  end
   -- UseItem's jumptable runs off ITEMATTR's field-menu nibble, and the first
   -- four entries are all .Oak -- an X ATTACK or a POKé DOLL used from the
   -- field PACK prints OakThisIsntTheTimeText and goes nowhere.  Only the
@@ -586,6 +592,66 @@ function PackMenu:giveToSlot(slot, row)
   held:giveItem(row.id)
 end
 
+-- engine/items/tmhm.asm:73
+function PackMenu:openTeachParty(row)
+  local game = self.game
+  local party = (self.save and self.save.party) or {}
+  if #party == 0 then
+    self.message = NO_POKEMON
+    return
+  end
+  if not (game and game.stack) then return end
+  if not pcall(Screens.get, game, "Gen2PartyMenu") then return end
+  local def = self.items and self.items[row.id]
+  local moveId = def and def.teaches
+  local moves = game.data and game.data.moves
+  local moveDef = moves and moves[moveId]
+  local moveName = (moveDef and moveDef.name) or moveId
+  self.staleRows = true
+  Screens.push(game, "Gen2PartyMenu", {
+    save = self.save,
+    prompt = "teach",
+    tmhm = { move = moveId },
+    onCancel = function()
+      game.stack:pop()
+      self:rebuild()
+    end,
+    onChoose = function(_slot, mon)
+      game.stack:pop()
+      local species = game.data and game.data.pokemon
+        and game.data.pokemon[mon.species]
+      local allowed = false
+      for _, id in ipairs((species and species.tmhm) or {}) do
+        if id == moveId then allowed = true end
+      end
+      if not allowed then
+        if game.say then
+          game:say(("%s can't learn %s!"):format(
+            mon.nickname or mon.species or "?", moveName))
+        end
+        return
+      end
+      for _, move in ipairs(mon.moves or {}) do
+        if move.id == moveId then
+          if game.say then
+            game:say(("%s already knows %s!"):format(
+              mon.nickname or mon.species or "?", moveName))
+          end
+          return
+        end
+      end
+      if not game.learnMoveOn then return end
+      game:learnMoveOn(mon, moveId, function(learned)
+        if not learned then return end
+        if tostring(row.id):sub(1, 3) == "HM_" then return end
+        require("src.core.gen2.Happiness").change(mon, "LEARNMOVE")
+        if game.consumeItem then game:consumeItem(row.id) end
+        self:rebuild()
+      end)
+    end,
+  })
+end
+
 function PackMenu:update(_dt)
   local input = self.game and self.game.input
   if not input then return end

src/ui/gen2/PartyMenu.lua

@@ -22,6 +22,7 @@ local GbcPalette = require("src.render.GbcPalette")
 local HpBar = require("src.battle.gen2.HpBar")
 local Logger = require("src.core.Logger")
 local Mail = require("src.core.gen2.Mail")
+local Mon = require("src.battle.gen2.Mon")
 local Runtime = require("src.mods.Runtime")
 local Screens = require("src.ui.Screens")
 
@@ -90,11 +91,20 @@ function PartyMenu.new(game, opts)
   self.save = save
   self.party = opts.party or (save and save.party) or {}
   local data = game and game.data or {}
+  -- engine/pokemon/move_mon.asm:1402
+  for i = 1, #self.party do
+    Mon.refreshStats(self.party[i], data)
+  end
   self.icons = opts.icons or data.gen2Icons
   self.palettes = opts.palettes or data.gen2Palettes
   self.pokemon = opts.pokemon or data.pokemon
   self.prompt = PartyMenu.PROMPTS[opts.prompt or "choose"] or opts.prompt
     or PartyMenu.PROMPTS.choose
+  -- engine/pokemon/party_menu.asm:297
+  self.tmhm = opts.tmhm
+  if self.tmhm and (opts.prompt == nil or opts.prompt == "teach") then
+    self.prompt = PartyMenu.PROMPTS.teach
+  end
   self.onChoose = opts.onChoose
   self.onCancel = opts.onCancel
   self.moves = opts.moves or data.moves
@@ -469,7 +479,14 @@ function PartyMenu:update(_dt)
     elseif self.wantsSubmenu or self.wantsBattleSubmenu then
       self:openSubmenu()
     elseif self.onChoose then
-      self.onChoose(self.index, self.party[self.index])
+      local mon = self.party[self.index]
+      if self.tmhm and mon and mon.isEgg then
+        -- engine/items/tmhm.asm:104
+        local world = self.game and self.game.world
+        if world and world.playSfxNamed then world:playSfxNamed("Sfx_Wrong") end
+        return
+      end
+      self.onChoose(self.index, mon)
     end
   elseif input:wasPressed("b") then
     self:storeCursor()
@@ -674,6 +691,18 @@ function PartyMenu.rowFor(mon)
   }
 end
 
+-- engine/pokemon/party_menu.asm:331
+function PartyMenu:tmhmAble(mon)
+  if not mon or mon.isEgg then return nil end
+  local move = self.tmhm and self.tmhm.move
+  if not move then return nil end
+  local species = self.pokemon and self.pokemon[mon.species]
+  for _, id in ipairs((species and species.tmhm) or {}) do
+    if id == move then return "ABLE" end
+  end
+  return "NOT ABLE"
+end
+
 -- WritePartyMenuTilemap, jumptable entry by jumptable entry.  Every coordinate
 -- below is the hlcoord the matching PARTYMENUQUALITY_* routine uses, and each
 -- steps 2 * SCREEN_WIDTH per mon:
@@ -712,10 +741,15 @@ function PartyMenu:drawPanel()
     self:drawIcon(mon, self:iconX(i), 4 + (i - 1) * 16 + self:iconBob(i))
     local row = PartyMenu.rowFor(mon)
     Chrome.print(row.name, 3, nameY)
-    if row.hp then Chrome.print(row.hp, 13, nameY) end
+    if self.tmhm then
+      local able = self:tmhmAble(mon)
+      if able then Chrome.print(able, 12, dataY) end
+    else
+      if row.hp then Chrome.print(row.hp, 13, nameY) end
+      if row.hp then self:drawHpBar(mon, 11, dataY) end
+    end
     if row.status then Chrome.print(row.status, 5, dataY) end
     if row.level then Chrome.print(row.level, 8, dataY) end
-    if row.hp then self:drawHpBar(mon, 11, dataY) end
   end
 
   -- .end does `dec hl` twice from the row past the last nickname, so CANCEL

src/ui/gen2/Pokegear.lua

@@ -1084,16 +1084,20 @@ function Pokegear:update(_dt)
   -- answers -1 rather than backing out to the strip.
   if self.fly then return self:updateFlyMap(input) end
   if self.mode == "strip" then
-    if input:wasPressed("left") then
-      self.cardIndex = self.cardIndex > 1 and self.cardIndex - 1 or #self.cards
-    elseif input:wasPressed("right") then
-      self.cardIndex = self.cardIndex < #self.cards and self.cardIndex + 1 or 1
-    elseif input:wasPressed("a") then
-      self.mode = "card"
-    elseif input:wasPressed("b") then
-      if self.onClose then self.onClose() end
+    local stripCard = self:card()
+    if not (stripCard and stripCard.id == "phone") then
+      if input:wasPressed("left") then
+        self.cardIndex = self.cardIndex > 1 and self.cardIndex - 1 or #self.cards
+      elseif input:wasPressed("right") then
+        self.cardIndex = self.cardIndex < #self.cards and self.cardIndex + 1 or 1
+      elseif input:wasPressed("a") then
+        self.mode = "card"
+      elseif input:wasPressed("b") then
+        if self.onClose then self.onClose() end
+      end
+      return
     end
-    return
+    self.mode = "card"
   end
   -- Inside a card.
   local card = self:card()
@@ -1105,6 +1109,19 @@ function Pokegear:update(_dt)
   -- submenu is waiting for.
   local phoneBusy = card and card.id == "phone"
     and (self.call ~= nil or self.phoneSubmenu ~= nil)
+  -- engine/pokegear/pokegear.asm:799
+  if card and card.id == "phone" and not phoneBusy then
+    if input:wasPressed("b") then
+      if self.onClose then self.onClose() end
+      return
+    elseif input:wasPressed("left") then
+      self:switchCard("map", "clock")
+      return
+    elseif input:wasPressed("right") then
+      self:switchCard("radio")
+      return
+    end
+  end
   if not phoneBusy and input:wasPressed("b") then
     self.mode = "strip"
     self:stopRadio()
@@ -2057,6 +2074,7 @@ function Pokegear:drawPlayerIcon(x, y)
   local beat = math.floor((self.iconTimer or 0) / 8)
   -- .OAMData_RedWalk (data/sprite_anims/oam.asm:314-319) hangs its four tiles
   -- at -8,-8; camY of -4 undoes the world's sprite lift.
+  love.graphics.setColor(1, 1, 1, 1)
   self.playerIcon:draw(x - 8, y - 8, 0, -4, "down",
     beat % 2, beat == 3)
   return true

src/ui/gen2/SummaryMenu.lua

@@ -261,6 +261,8 @@ function SummaryMenu.new(game, opts)
       math.min(opts.index or 1, math.max(1, #self.party)))
     self.mon = self.party[self.index]
   end
+  -- engine/pokemon/move_mon.asm:1402
+  Mon.refreshStats(self.mon, data)
   self.page = opts.page or PINK_PAGE
   -- ManagePokemonMoves opens straight onto MoveScreenLoop's screen; SELECT off
   -- the green page reaches the same view with the stats pages still behind it.
@@ -678,6 +680,8 @@ function SummaryMenu:switchMon(delta)
   if next_ < 1 or next_ > #self.party then return false end
   self.index = next_
   self.mon = self.party[next_]
+  -- engine/pokemon/move_mon.asm:1402
+  Mon.refreshStats(self.mon, self.game and self.game.data)
   self.moveIndex = 1
   self:playCry()
   return true
@@ -694,6 +698,8 @@ function SummaryMenu:switchMonPastEggs(delta)
   if next_ < 1 or next_ > #self.party then return false end
   self.index = next_
   self.mon = self.party[next_]
+  -- engine/pokemon/move_mon.asm:1402
+  Mon.refreshStats(self.mon, self.game and self.game.data)
   self.moveIndex = 1
   self:playCry()
   return true

src/ui/gen2/TradeAnim.lua

@@ -45,6 +45,7 @@
 local Anim = require("src.core.gen2.TradeAnim")
 local Assets = require("src.render.Assets")
 local Chrome = require("src.ui.gen2.Chrome")
+local Font = require("src.render.Font")
 local GbcPalette = require("src.render.GbcPalette")
 local Music = require("src.core.Music")
 local Palettes = require("src.world.gen2.Palettes")
@@ -202,6 +203,15 @@ local TEMPLATE_ROWS = {
   { row = 6, text = "<ID>№." },
 }
 
+-- gfx/sgb/predef.pal:29
+local function scale5(value) return math.floor(value * 255 / 31 + 0.5) end
+local TRADE_TUBE_PAL = {
+  { scale5(31), scale5(31), scale5(31) },
+  { scale5(18), scale5(20), scale5(27) },
+  { scale5(11), scale5(15), scale5(23) },
+  { 0, 0, 0 },
+}
+
 --------------------------------------------------------------------------
 -- Construction
 --------------------------------------------------------------------------
@@ -367,8 +377,22 @@ end
 -- reading through.
 -- `index` is a GB shade, 0 (white) to 3 (black); GbcPalette.color counts from
 -- 1, as the palettes themselves do.
+function TradeAnimView:bgColors()
+  local id = (self.beat or {}).id or ""
+  local pan = id:find("_pan_", 1, true)
+  if not pan then
+    return Palettes.textColors(self.palettes)
+  end
+  local colors = TRADE_TUBE_PAL
+  -- engine/movie/trade_animation.asm:1271
+  if math.floor((self.frame or 0) / 8) % 2 == 1 then
+    colors = { colors[1], colors[3], colors[2], colors[4] }
+  end
+  return colors
+end
+
 function TradeAnimView:shade(index)
-  local colors = Palettes.textColors(self.palettes)
+  local colors = self:bgColors()
   local rgb = GbcPalette.color(colors, index + 1)
     or ({ { 255, 255, 255 }, { 168, 168, 168 }, { 96, 96, 96 },
           { 0, 0, 0 } })[index + 1]
@@ -384,7 +408,7 @@ end
 -- and GbcPalette maps them.  A driver with no shader draws the greys, which
 -- is the DMG ramp and not a black frame.
 function TradeAnimView:through(body)
-  local colors = Palettes.textColors(self.palettes)
+  local colors = self:bgColors()
   love.graphics.setColor(1, 1, 1, 1)
   if colors and GbcPalette.available() then
     GbcPalette.with(colors, body)
@@ -543,7 +567,7 @@ function TradeAnimView:drawStats(record, offset)
   G.setColor(1, 1, 1, 1)
   G.rectangle("fill", (PANEL_X + 1) * 8, PANEL_Y * 8, 9 * 8, 8)
   for _, row in ipairs(TEMPLATE_ROWS) do
-    Chrome.print(row.text, PANEL_X + 1, row.row)
+    Chrome.print(Strings(row.text), PANEL_X + 1, row.row)
   end
   Chrome.print(Chrome.number(record.dex or 0, 3, true), PANEL_X + 7, 0)
   Chrome.print(record.name, PANEL_X + 1, 2)
@@ -767,6 +791,8 @@ end
 function TradeAnimView:drawPanel()
   local id = (self.beat or {}).id
   local t = self.offset or 0
+  -- engine/movie/trade_animation.asm:151
+  local wasBattle = Font.useBattleExtra(true)
   Chrome.clear()
 
   if GIVE_BEATS[id] then
@@ -794,6 +820,7 @@ function TradeAnimView:drawPanel()
     end
   end
   love.graphics.setColor(1, 1, 1, 1)
+  Font.useBattleExtra(wasBattle)
 end
 
 function TradeAnimView:drawTubeBeat(id, t)

src/world/OverworldController.lua

@@ -462,8 +462,18 @@ function OverworldState:setMap(mapId, x, y, facing, opts)
   if not keepMusic then
     -- ..(home/overworld.asm ln 2346)
     local Music = require("src.core.Music")
+    -- opts.freshBoot: switch instantly instead of cross-fading, like every
+    -- other map's PlayDefaultMusic on real hardware -- set only by
+    -- Game.lua's hard state teleports (onContinue, New Game, F2,
+    -- restoreCheckpointSave). Deliberately separate from opts.via ==
+    -- "boot" itself: dev tooling (src/dev/Console.lua's warp verb,
+    -- src/dev/HotReload.lua's reloadMap) reuses that same default for the
+    -- surf-restore/fresh-npc-pool branches above and must keep the
+    -- ordinary crossfade.
+    local fade = Music.MAP_FADE
+    if opts and opts.freshBoot then fade = nil end
     Music.playMap(Game.data, mapId, Game.save.onBike, self.player.surfing,
-                  Music.MAP_FADE)
+                  fade)
   end
 
   -- forced bike/surf tiles fire the moment the player is placed on the

src/world/gen2/Npc.lua

@@ -442,6 +442,27 @@ function NPC:updateTreeShake()
   return true
 end
 
+function NPC:scriptRockSmash(frames)
+  -- engine/overworld/map_objects.asm:1462
+  self.rockSmash = {
+    frame = 0,
+    frames = frames or 10,
+  }
+  self.frozen = true
+  return true
+end
+
+function NPC:updateRockSmash()
+  local st = self.rockSmash
+  if not st then return false end
+  st.frame = st.frame + 1
+  if st.frame >= st.frames then
+    self.rockSmash = nil
+    return false
+  end
+  return true
+end
+
 -- `passable` is the follower's escape (src/world/gen2/Follower.lua), the same
 -- name and meaning src/world/Collision.lua:20 gives it under Gen 1.
 local function occupied(entities, tx, ty, self)
@@ -514,6 +535,10 @@ function NPC:update(map, entities)
     self:updateTreeShake()
     return
   end
+  if self.rockSmash then
+    self:updateRockSmash()
+    return
+  end
   -- NPC_CHANGE_FACING (src/world/NPC.lua:71): one walk cycle in place, no
   -- translation.  Above the moving arm because it has no targetX to reach,
   -- and the arm below would assign cellX = nil a frame later.
@@ -726,6 +751,15 @@ function NPC:draw(ox, oy, scale)
     self.sprite:draw(
       self.px, self.py + yOffset, 0, 0,
       facing, 0, false, false, q == 3)
+  elseif self.rockSmash then
+    -- engine/overworld/map_objects.asm:1462
+    if (self.rockSmash.frame % 2) == 0 then
+      G.pop()
+      return
+    end
+    self.sprite:draw(
+      self.px, self.py + yOffset, 0, 0,
+      self.facing, self:walkPhase(), self.stepFlip)
   else
     self.sprite:draw(
       self.px, self.py + yOffset, 0, 0,

src/world/gen2/Player.lua

@@ -17,6 +17,12 @@ local TURN_FRAMES = 4
 -- at the walking rate, which is what stops a bike step flickering the legs.
 Player.STEP_FRAMES = STEP_FRAMES
 
+-- engine/overworld/map_objects.asm:1815
+local JUMP_Y = {
+  -4, -6, -8, -10, -11, -12, -12, -12,
+  -11, -10, -9, -8, -6, -4, 0, 0,
+}
+
 function Player.new(cx, cy, facing, spriteDef)
   local self = setmetatable({
     cellX = cx, cellY = cy,
@@ -170,9 +176,11 @@ function Player:update()
   self.px = self.cellX * 16 + dx * adv
   self.py = self.cellY * 16 + dy * adv
   if self.jumping then
-    -- pokegold engine/overworld/map_objects.asm: UpdateJumpPosition's
-    -- y_offsets table peaks at -12.
-    self.py = self.py - math.floor(12 * math.sin(math.pi * self.progress / frames))
+    -- engine/overworld/map_objects.asm:1815
+    local idx = math.floor((self.progress - 1) / 2) + 1
+    if idx < 1 then idx = 1 end
+    if idx > #JUMP_Y then idx = #JUMP_Y end
+    self.spriteYOffset = JUMP_Y[idx]
   end
   if self.progress >= frames then
     self.cellX, self.cellY = self.targetX, self.targetY
@@ -180,6 +188,7 @@ function Player:update()
     self.px, self.py = self.cellX * 16, self.cellY * 16
     self.moving = false
     self.jumping = nil
+    self.spriteYOffset = 0
     self.stepFlip = not self.stepFlip
     return true
   end
@@ -193,6 +202,15 @@ function Player:draw(ox, oy, scale)
   -- standing on.  StepFunction_GotBite's `xor 1` rod bob and the fly take-off
   -- lift both ride this one byte.
   local yOffset = self.spriteYOffset or 0
+  if self.jumping then
+    -- engine/overworld/map_objects.asm:1995
+    local gx = ox + self.px * scale
+    local gy = oy + self.py * scale
+    local s = 16 * scale
+    G.setColor(0, 0, 0, 0.4)
+    G.ellipse("fill", gx + s * 0.5, gy + s * 0.85, s * 0.35, s * 0.12)
+    G.setColor(1, 1, 1, 1)
+  end
   if self.sprite then
     G.push()
     G.translate(ox, oy)

src/world/gen2/World.lua

@@ -621,6 +621,8 @@ function World.new(game)
     -- which is why a cut tree is back the next time you walk in.  Restoring
     -- these at the top of setMap is that refill.
     blockEdits = {},
+    -- engine/overworld/map_setup.asm:78
+    objectSpawns = {},
     -- A field move that is mid-flow (the used-X text, then its effect).
     fieldMove = nil,
     -- ---- state the script VM owns ------------------------------------------
@@ -1819,6 +1821,15 @@ function World:moveObject(objectId, cellX, cellY)
   local def = self.map and self.map.def
   local obj = def and def.objects and def.objects[index]
   if not (obj and cellX and cellY) then return end
+  local mapId = self.map and self.map.id
+  local key = obj.index or index
+  if mapId then
+    self.objectSpawns = self.objectSpawns or {}
+    self.objectSpawns[mapId] = self.objectSpawns[mapId] or {}
+    if not self.objectSpawns[mapId][key] then
+      self.objectSpawns[mapId][key] = { obj.x, obj.y }
+    end
+  end
   obj.x, obj.y = cellX, cellY
   local npc = self:objectEntity(objectId)
   if npc and npc ~= self.player then
@@ -3715,6 +3726,16 @@ function World:updateMovement()
   while st.i <= #st.bytes do
     local b = st.bytes[st.i]
     st.i = st.i + 1
+    -- engine/overworld/movement.asm:163
+    if b == 0x57 then
+      local duration = st.bytes[st.i] or 0
+      st.i = st.i + 1
+      if ent.scriptRockSmash then
+        ent:scriptRockSmash(duration)
+      end
+      st.sleep = duration
+      return
+    end
     local act = Movement.decodeByte(b)
     if act.kind == "end" then
       -- SLIDING_F is an object flag, not a stream one, so a stream that never
@@ -5237,6 +5258,38 @@ function World:restoreBlocks()
   return any
 end
 
+function World:restoreObjectSpawns()
+  -- engine/overworld/map_setup.asm:78
+  local spawns = self.objectSpawns
+  if not spawns then return end
+  for mapId, byIndex in pairs(spawns) do
+    local def = self.maps and self.maps[mapId]
+    local objects = def and def.objects
+    if objects then
+      for key, xy in pairs(byIndex) do
+        local obj
+        for _, row in ipairs(objects) do
+          if (row.index or 0) == key then obj = row break end
+        end
+        if obj then
+          obj.x, obj.y = xy[1], xy[2]
+        end
+        local npc = self.npcPool
+          and self.npcPool[string.format("%s_obj_%d", mapId, key)]
+        if npc then
+          npc.cellX, npc.cellY = xy[1], xy[2]
+          npc.px, npc.py = xy[1] * 16, xy[2] * 16
+          npc.homeX, npc.homeY = xy[1], xy[2]
+          npc.moving = false
+          npc.progress = 0
+          npc.targetX, npc.targetY = nil, nil
+        end
+      end
+    end
+    spawns[mapId] = nil
+  end
+end
+
 -- Drop the loaded map's baked canvases and bake again.  Same shape as what
 -- pollTimeOfDay does when the clock rolls the palette over; a block edit
 -- invalidates the bake for the same reason a palette change does.  A world with
@@ -5360,8 +5413,10 @@ end
 -- picked, and TextBox reads it back off game.stringBuffer.
 function World:setNickname(mon)
   if not self.game then return end
-  self.game.stringBuffer =
-    (mon and (mon.nickname or mon.name or mon.species)) or ""
+  local name = (mon and (mon.nickname or mon.name or mon.species)) or ""
+  self.game.stringBuffer = name
+  -- engine/events/overworld.asm:1339
+  if self.vm then self.vm.stringBuffer = name end
 end
 
 function World:playMonCry(mon)
@@ -8304,6 +8359,7 @@ function World:setMap(mapId, cx, cy, facing, opts)
   -- and WHIRLPOOL swapped out goes back: a cut tree is standing again the next
   -- time the map is loaded, and this has to happen before Map.new reads them.
   self:restoreBlocks()
+  self:restoreObjectSpawns()
   -- HandleNewMap (home/map.asm:216-228) runs ResetMapBufferEventFlags before
   -- anything else that touches state: event flags 0-7
   -- (EVENT_TEMPORARY_UNTIL_MAP_RELOAD) die on every map load, which is what
@@ -8784,7 +8840,8 @@ function World:tryLedgeJump(dir)
   -- ShakeGrass (engine/overworld/movement.asm:741-770).
   p.inGrass, p.grassShake = false, nil
   p.progress = 0
-  p.stepFrames = Player.STEP_FRAMES
+  -- engine/overworld/map_objects.asm:1163
+  p.stepFrames = Player.STEP_FRAMES * 2
   self:playSfxNamed("Sfx_JumpOverLedge", SFX_JUMP_OVER_LEDGE)
   return true
 end

tests/drivers/gold_save_slot_bug1107_test.lua

@@ -0,0 +1,49 @@
+-- In-game Gold SAVE with no launcher slot must leave a file CONTINUE can see.
+--
+--   POKEPORT_GAME=gold POKEPORT_IDENTITY=gold-bug1107 \
+--     POKEPORT_DRIVER=tests/drivers/gold_save_slot_bug1107_test.lua love .
+
+local U = require("tests.drivers.util")
+local SaveData = require("src.core.SaveData")
+
+return function(game)
+  U.wait(45)
+  assert(game.world and game.world.map, "gold world did not boot")
+
+  local before = SaveData.listSlots("gold")
+  local hadFile = false
+  for _, slot in ipairs(before) do
+    if slot.exists then hadFile = true break end
+  end
+  if not hadFile then
+    local opts = SaveData.loadOptions()
+    opts.saveSlots = opts.saveSlots or {}
+    opts.saveSlots.gold = nil
+    SaveData.saveOptions(opts)
+    SaveData.resetSlotState()
+  end
+
+  local ok, err = game:writeSave()
+  if not ok then
+    U.log("FAIL gold writeSave:", tostring(err))
+  else
+    local after = SaveData.listSlots("gold")
+    local found, path
+    for _, slot in ipairs(after) do
+      if slot.exists then
+        found = slot.id
+        path = SaveData.slotDiskPath("gold", slot.id)
+        break
+      end
+    end
+    if found then
+      U.log("PASS gold save is launcher-visible:", found, path or "")
+    else
+      U.log("FAIL gold save wrote but listSlots has no file")
+    end
+  end
+
+  while true do
+    coroutine.yield()
+  end
+end

tests/drivers/herbshop_bug1169_test.lua

@@ -0,0 +1,49 @@
+-- Herb shop intro over the Goldenrod Underground map (#1169).
+-- pokegold engine/items/mart.asm:54 HerbShop, maps/GoldenrodUnderground.asm:158
+--
+--   POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/herbshop_bug1169_test.lua love .
+
+local U = require("tests.drivers.util")
+
+return function(game)
+  local out = os.getenv("SHOT_DIR") or os.getenv("POKEPORT_SHOT_DIR")
+    or "/tmp/bug1169"
+  U.wait(45)
+  local world = game.world
+  assert(world and world.map, "gold world did not boot")
+
+  -- maps/GoldenrodUnderground.asm:52
+  world.clockDay = 0
+  world.mapScenes = world.mapScenes or {}
+  -- maps/GoldenrodUnderground.asm:679
+  assert(world:setMap("GOLDENROD_UNDERGROUND", 6, 21, "right"),
+    "setMap GOLDENROD_UNDERGROUND failed")
+  U.wait(8)
+
+  local granny
+  for _, npc in ipairs(world.npcs or {}) do
+    if npc.def and npc.def.sprite == "SPRITE_GRANNY" then granny = npc break end
+  end
+  if not granny then
+    U.log("FAIL granny not on the map (need Sunday)")
+  end
+
+  local MartMenu = require("src.ui.gen2.MartMenu")
+  U.tap(game, "a")
+  U.wait(6)
+  for _ = 1, 90 do
+    if getmetatable(game.stack:top()) == MartMenu then break end
+    U.tap(game, "a")
+    U.wait(4)
+  end
+  local top = game.stack:top()
+  if getmetatable(top) ~= MartMenu then
+    U.log("FAIL mart did not open")
+  elseif top.isOpaque then
+    U.log("FAIL mart is opaque")
+  else
+    U.log("herb shop intro over the map")
+  end
+  U.shot(game, out .. "/herbshop_intro.png")
+  while true do U.wait(60) end
+end

tests/drivers/kurt_well_bug1184_test.lua

@@ -0,0 +1,88 @@
+-- Kurt stays at moveobject (11, 6) for the visit, then ROM spawn (16, 14)
+-- on the next load.
+-- #1184
+-- maps/SlowpokeWellB1F.asm:48 / engine/overworld/map_setup.asm:78
+-- POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/kurt_well_bug1184_test.lua love .
+
+local U = require("tests.drivers.util")
+
+local KURT_ID = 8
+local ROM_X, ROM_Y = 16, 14
+local MOVE_X, MOVE_Y = 11, 6
+local FLAG_KURT = 1856
+local FLAG_ROCKETS = 1788
+
+local function findKurt(world)
+  for _, npc in ipairs(world.npcs or {}) do
+    if npc.def and npc.def.sprite == "SPRITE_KURT" then return npc end
+  end
+  return nil
+end
+
+local function kurtDef(world)
+  local objects = world.map and world.map.def and world.map.def.objects
+  return objects and objects[KURT_ID - 1]
+end
+
+return function(game)
+  U.wait(45)
+  local world = game.world
+  assert(world and world.map, "gold world did not boot")
+
+  world.mapScenes = world.mapScenes or {}
+  world.mapScenes.PLAYERS_HOUSE_1F = 1
+  world.mapScenes.NEW_BARK_TOWN = 1
+  world.events:set(FLAG_KURT, false)
+  world.events:set(FLAG_ROCKETS, true)
+
+  assert(world:setMap("SLOWPOKE_WELL_B1F", 15, 14, "right"),
+    "SLOWPOKE_WELL_B1F did not load")
+  U.wait(4)
+
+  local pass, fail = 0, 0
+  local function claim(ok, text)
+    if ok then pass = pass + 1 else fail = fail + 1 end
+    U.log(ok and "PASS" or "FAIL", text)
+  end
+
+  local kurt = findKurt(world)
+  claim(kurt ~= nil, "Kurt is on the well map")
+  claim(kurt and kurt.cellX == ROM_X and kurt.cellY == ROM_Y,
+    ("Kurt ROM spawn is (%d, %d), saw (%s, %s)")
+      :format(ROM_X, ROM_Y,
+        tostring(kurt and kurt.cellX), tostring(kurt and kurt.cellY)))
+
+  world:moveObject(KURT_ID, MOVE_X, MOVE_Y)
+  world:appearObject(KURT_ID)
+  U.wait(4)
+
+  kurt = findKurt(world)
+  claim(kurt and kurt.cellX == MOVE_X and kurt.cellY == MOVE_Y,
+    ("after moveobject Kurt is at (%d, %d), saw (%s, %s)")
+      :format(MOVE_X, MOVE_Y,
+        tostring(kurt and kurt.cellX), tostring(kurt and kurt.cellY)))
+
+  assert(world:setMap("PLAYERS_HOUSE_1F", 3, 3, "down"),
+    "PLAYERS_HOUSE_1F did not load")
+  U.wait(2)
+  world.events:set(FLAG_KURT, false)
+  assert(world:setMap("SLOWPOKE_WELL_B1F", 15, 14, "right"),
+    "SLOWPOKE_WELL_B1F did not reload")
+  U.wait(4)
+
+  local def = kurtDef(world)
+  kurt = findKurt(world)
+  claim(def and def.x == ROM_X and def.y == ROM_Y,
+    ("reload restored Kurt def to (%d, %d), saw (%s, %s)")
+      :format(ROM_X, ROM_Y,
+        tostring(def and def.x), tostring(def and def.y)))
+  claim(kurt and kurt.cellX == ROM_X and kurt.cellY == ROM_Y,
+    ("reload put Kurt at (%d, %d), not the blocking cell (%d, %d); saw (%s, %s)")
+      :format(ROM_X, ROM_Y, MOVE_X, MOVE_Y,
+        tostring(kurt and kurt.cellX), tostring(kurt and kurt.cellY)))
+
+  U.log(("machine checks: %d passed, %d failed"):format(pass, fail))
+  U.log("Kurt should be at the well entrance, not on the inner path.")
+
+  while true do U.wait(60) end
+end

tests/drivers/multihit_bug1168_test.lua

@@ -0,0 +1,143 @@
+-- Fury Attack / Barrage hit 2-5 times, Twineedle stays at 2. Issue #1168.
+-- pokegold engine/battle/effect_commands.asm:5228 (BattleCommand_EndLoop).
+--   POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/multihit_bug1168_test.lua love .
+-- Do not add POKEPORT_SPEED: the per-strike HP steps are what you are judging.
+
+local U = require("tests.drivers.util")
+local Battle = require("src.battle.gen2.Battle")
+local Effects = require("src.battle.gen2.Effects")
+local Mon = require("src.battle.gen2.Mon")
+
+return function(game)
+  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
+
+  local function claim(ok, text)
+    print((ok and "[multihit] PASS " or "[multihit] FAIL ") .. text)
+  end
+
+  U.wait(45)
+  local world = game.world
+  if not (world and world.map) then
+    print("[multihit] FAIL gold world did not boot")
+    while true do U.wait(60) end
+  end
+
+  local fury = game.data.moves and game.data.moves.FURY_ATTACK
+  local twine = game.data.moves and game.data.moves.TWINEEDLE
+  claim(fury ~= nil, "FURY_ATTACK is in the move table")
+  claim(fury and fury.effect == "EFFECT_MULTI_HIT",
+    "FURY_ATTACK is EFFECT_MULTI_HIT")
+  claim(twine ~= nil, "TWINEEDLE is in the move table")
+  claim(twine and twine.effect == "EFFECT_POISON_MULTI_HIT",
+    "TWINEEDLE is EFFECT_POISON_MULTI_HIT")
+  claim(Effects.hitCount("EFFECT_DOUBLE_HIT") == 2, "DOUBLE_HIT is 2")
+  claim(Effects.hitCount("EFFECT_POISON_MULTI_HIT") == 2,
+    "POISON_MULTI_HIT (Twineedle) is 2")
+
+  local seq, si = { 0, 1, 2, 0, 3, 3 }, 0
+  local function scripted()
+    si = si + 1
+    return seq[si] or 0
+  end
+  claim(Effects.hitCount("EFFECT_MULTI_HIT", scripted) == 2, "roll 0 -> 2 hits")
+  claim(Effects.hitCount("EFFECT_MULTI_HIT", scripted) == 3, "roll 1 -> 3 hits")
+  claim(Effects.hitCount("EFFECT_MULTI_HIT", scripted) == 2,
+    "roll 2 then 0 -> 2 hits")
+  claim(Effects.hitCount("EFFECT_MULTI_HIT", scripted) == 5,
+    "roll 3 then 3 -> 5 hits")
+
+  local function fiveHitRandom(n)
+    if n == 4 then return 3 end
+    return 0
+  end
+
+  local headP = Mon.new(game.data, "CYNDAQUIL", 20)
+  local headW = Mon.new(game.data, "SNORLAX", 20)
+  if headP and headW then
+    headP.moves = { { id = "FURY_ATTACK", pp = 20, maxPp = 20 } }
+    local b = Battle.new({
+      data = game.data, party = { headP }, wild = headW,
+      random = fiveHitRandom,
+    })
+    local landed, hitLine = 0, nil
+    for _, ev in ipairs(b:takeTurn({ kind = "move", move = "FURY_ATTACK" })) do
+      if ev.kind == "damage" and ev.side == "enemy" then
+        landed = landed + 1
+      end
+      if ev.kind == "message" and ev.text then
+        local n = ev.text:match("Hit (%d+) time")
+        if n then hitLine, landed = ev.text, tonumber(n) end
+      end
+    end
+    claim(landed == 5,
+      ("scripted Fury Attack hit %d times (want 5, not 2)"):format(landed))
+    if hitLine then print("[multihit] " .. hitLine) end
+  else
+    claim(false, "could not build a headless Fury Attack pair")
+  end
+
+  local player = Mon.new(game.data, "CYNDAQUIL", 20)
+  if not player then
+    print("[multihit] FAIL could not build CYNDAQUIL")
+    while true do U.wait(60) end
+  end
+  player.moves = { { id = "FURY_ATTACK", pp = 20, maxPp = 20 } }
+  game.save.party = { player }
+
+  local wild = Mon.new(game.data, "SNORLAX", 20)
+  if not wild then
+    print("[multihit] FAIL could not build SNORLAX")
+    while true do U.wait(60) end
+  end
+  if not world:startBattle({ wild = wild }) then
+    print("[multihit] FAIL startBattle failed")
+    while true do U.wait(60) end
+  end
+
+  local screen
+  for _ = 1, 600 do
+    local top = game.stack:top()
+    if top and top.battle then screen = top break end
+    U.wait(1)
+  end
+  if not (screen and screen.battle) then
+    print("[multihit] FAIL battle screen never came up")
+    while true do U.wait(60) end
+  end
+
+  local left = 2
+  screen.battle.random = function(n)
+    if n == 4 and left > 0 then
+      left = left - 1
+      return 3
+    end
+    if left > 0 then return 0 end
+    if love and love.math and love.math.random then
+      return love.math.random(n) - 1
+    end
+    return math.random(n) - 1
+  end
+
+  for _ = 1, 200 do
+    if screen.phase == "menu" then break end
+    tap("a", 3)
+  end
+  if screen.phase ~= "menu" then
+    print("[multihit] FAIL never reached the battle menu")
+    while true do U.wait(60) end
+  end
+
+  tap("a")
+  U.wait(6)
+  tap("a")
+  print("[multihit] Fury Attack should strike five times on this turn.")
+  print("[multihit] later turns are 2-5. Twineedle would stay at 2.")
+
+  while true do U.wait(60) end
+end

tests/drivers/radiotower_softlock_bug1164_test.lua

@@ -0,0 +1,92 @@
+-- Radio Tower 5F director returns to the office after a downstairs/upstairs
+-- reload, not on the stair warp at (12, 0).
+-- #1164 / #1188
+-- maps/RadioTower5F.asm:115 / engine/overworld/map_setup.asm:78
+-- POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/radiotower_softlock_bug1164_test.lua love .
+
+local U = require("tests.drivers.util")
+
+local DIRECTOR_ID = 2
+local OFFICE_X, OFFICE_Y = 3, 6
+local STAIR_X, STAIR_Y = 12, 0
+local FLAG_ROCKETS = 1742
+local FLAG_CIVILIANS = 1744
+
+local function findDirector(world)
+  for _, npc in ipairs(world.npcs or {}) do
+    if npc.def and npc.def.sprite == "SPRITE_GENTLEMAN" then return npc end
+  end
+  return nil
+end
+
+local function directorDef(world)
+  local objects = world.map and world.map.def and world.map.def.objects
+  return objects and objects[DIRECTOR_ID - 1]
+end
+
+return function(game)
+  U.wait(45)
+  local world = game.world
+  assert(world and world.map, "gold world did not boot")
+
+  world.mapScenes = world.mapScenes or {}
+  world.mapScenes.RADIO_TOWER_5F = 2
+  world.mapScenes.RADIO_TOWER_4F = 0
+  world.events:set(FLAG_ROCKETS, true)
+  world.events:set(FLAG_CIVILIANS, false)
+
+  assert(world:setMap("RADIO_TOWER_5F", 10, 4, "down"),
+    "RADIO_TOWER_5F did not load")
+  U.wait(4)
+
+  local pass, fail = 0, 0
+  local function claim(ok, text)
+    if ok then pass = pass + 1 else fail = fail + 1 end
+    U.log(ok and "PASS" or "FAIL", text)
+  end
+
+  local director = findDirector(world)
+  claim(director ~= nil, "director is on 5F")
+  claim(director and director.cellX == OFFICE_X and director.cellY == OFFICE_Y,
+    ("director office spawn is (%d, %d), saw (%s, %s)")
+      :format(OFFICE_X, OFFICE_Y,
+        tostring(director and director.cellX),
+        tostring(director and director.cellY)))
+
+  world:moveObject(DIRECTOR_ID, STAIR_X, STAIR_Y)
+  world:appearObject(DIRECTOR_ID)
+  U.wait(4)
+
+  director = findDirector(world)
+  claim(director and director.cellX == STAIR_X and director.cellY == STAIR_Y,
+    ("after moveobject director is at the stairs (%d, %d), saw (%s, %s)")
+      :format(STAIR_X, STAIR_Y,
+        tostring(director and director.cellX),
+        tostring(director and director.cellY)))
+
+  assert(world:setMap("RADIO_TOWER_4F", 12, 4, "down"),
+    "RADIO_TOWER_4F did not load")
+  U.wait(2)
+  assert(world:setMap("RADIO_TOWER_5F", 10, 4, "down"),
+    "RADIO_TOWER_5F did not reload")
+  U.wait(4)
+
+  local def = directorDef(world)
+  director = findDirector(world)
+  claim(def and def.x == OFFICE_X and def.y == OFFICE_Y,
+    ("reload restored director def to (%d, %d), saw (%s, %s)")
+      :format(OFFICE_X, OFFICE_Y,
+        tostring(def and def.x), tostring(def and def.y)))
+  claim(not (director and director.cellX == STAIR_X and director.cellY == STAIR_Y),
+    "director is not standing on the stair warp")
+  claim(director and director.cellX == OFFICE_X and director.cellY == OFFICE_Y,
+    ("reload put director in the office (%d, %d); saw (%s, %s)")
+      :format(OFFICE_X, OFFICE_Y,
+        tostring(director and director.cellX),
+        tostring(director and director.cellY)))
+
+  U.log(("machine checks: %d passed, %d failed"):format(pass, fail))
+  U.log("The gentleman should be in the office. The stairs must be clear.")
+
+  while true do U.wait(60) end
+end

tests/drivers/rocksmash_shift_bug1173_test.lua

@@ -0,0 +1,85 @@
+-- Route 40 smashable rocks stay on their cell through rock_smash, then a
+-- seamless Olivine round trip.
+-- #1173
+-- engine/overworld/movement.asm:163 / maps/Route40.asm:291
+-- POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/rocksmash_shift_bug1173_test.lua love .
+
+local U = require("tests.drivers.util")
+
+local ROCK_ID = 6
+local ROCK_X, ROCK_Y = 12, 8
+local SMASH = { 0x57, 10, 0x47 }
+
+local function findRock(world, x, y)
+  for _, npc in ipairs(world.npcs or {}) do
+    if npc.def and npc.def.sprite == "SPRITE_ROCK"
+        and npc.cellX == x and npc.cellY == y then
+      return npc
+    end
+  end
+  return nil
+end
+
+local function rockAt(world, x, y)
+  for _, npc in ipairs(world.npcs or {}) do
+    if npc.def and npc.def.sprite == "SPRITE_ROCK"
+        and npc.cellX == x and npc.cellY == y then
+      return true
+    end
+  end
+  return false
+end
+
+return function(game)
+  U.wait(45)
+  local world = game.world
+  assert(world and world.map, "gold world did not boot")
+
+  world.mapScenes = world.mapScenes or {}
+  world.mapScenes.ROUTE_40 = 0
+  world.mapScenes.OLIVINE_CITY = 0
+
+  assert(world:setMap("ROUTE_40", 12, 9, "up"), "ROUTE_40 did not load")
+  U.wait(4)
+
+  local pass, fail = 0, 0
+  local function claim(ok, text)
+    if ok then pass = pass + 1 else fail = fail + 1 end
+    U.log(ok and "PASS" or "FAIL", text)
+  end
+
+  local rock = findRock(world, ROCK_X, ROCK_Y)
+  claim(rock ~= nil, ("rock is at (%d, %d)"):format(ROCK_X, ROCK_Y))
+
+  world:beginMovement(ROCK_ID, SMASH)
+  for _ = 1, 40 do
+    if not world.moveState then break end
+    U.wait(1)
+  end
+  claim(world.moveState == nil, "rock_smash stream finished")
+
+  rock = findRock(world, ROCK_X, ROCK_Y)
+  claim(rock ~= nil,
+    ("after rock_smash the rock is still at (%d, %d), not one cell left")
+      :format(ROCK_X, ROCK_Y))
+  claim(not rockAt(world, ROCK_X - 1, ROCK_Y),
+    "no smashable rock slid one cell left")
+
+  assert(world:setMap("OLIVINE_CITY", 18, 15, "down", { seamless = true }),
+    "OLIVINE_CITY did not load")
+  U.wait(2)
+  assert(world:setMap("ROUTE_40", 12, 9, "up", { seamless = true }),
+    "ROUTE_40 did not reload")
+  U.wait(4)
+
+  claim(rockAt(world, ROCK_X, ROCK_Y),
+    ("after Olivine round trip the rock is still at (%d, %d)")
+      :format(ROCK_X, ROCK_Y))
+  claim(not rockAt(world, ROCK_X - 1, ROCK_Y),
+    "seamless reload did not shift the rock left")
+
+  U.log(("machine checks: %d passed, %d failed"):format(pass, fail))
+  U.log("The three rocks should sit on (12, 8), (11, 7), (13, 6).")
+
+  while true do U.wait(60) end
+end

tests/drivers/use_next_mon_bug1152_test.lua

@@ -0,0 +1,94 @@
+-- After a wild faint, "Use next POKéMON?" yes/no; NO tries to run. Issue #1152.
+-- pokegold engine/battle/core.asm:2590 (AskUseNextPokemon).
+--   POKEPORT_GAME=gold POKEPORT_DRIVER=tests/drivers/use_next_mon_bug1152_test.lua love .
+-- Do not add POKEPORT_SPEED: you need the yes/no box to sit there.
+
+local U = require("tests.drivers.util")
+local Mon = require("src.battle.gen2.Mon")
+
+return function(game)
+  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
+
+  local function claim(ok, text)
+    print((ok and "[use-next] PASS " or "[use-next] FAIL ") .. text)
+    return ok
+  end
+
+  U.wait(45)
+  local world = game.world
+  if not (world and world.map) then
+    print("[use-next] FAIL gold world did not boot")
+    while true do U.wait(60) end
+  end
+
+  local lead = Mon.new(game.data, "SENTRET", 5)
+  local backup = Mon.new(game.data, "CYNDAQUIL", 12)
+  if not (lead and backup) then
+    print("[use-next] FAIL could not build the party")
+    while true do U.wait(60) end
+  end
+  lead.hp = 1
+  lead.moves = { { id = "TACKLE", pp = 35, maxPp = 35 } }
+  backup.moves = { { id = "TACKLE", pp = 35, maxPp = 35 } }
+  game.save.party = { lead, backup }
+
+  local wild = Mon.new(game.data, "PIDGEY", 20)
+  if not wild then
+    print("[use-next] FAIL could not build a wild PIDGEY")
+    while true do U.wait(60) end
+  end
+  if not world:startBattle({ wild = wild }) then
+    print("[use-next] FAIL startBattle failed")
+    while true do U.wait(60) end
+  end
+
+  local screen
+  for _ = 1, 600 do
+    local top = game.stack:top()
+    if top and top.battle then screen = top break end
+    U.wait(1)
+  end
+  if not (screen and screen.battle) then
+    print("[use-next] FAIL battle screen never came up")
+    while true do U.wait(60) end
+  end
+
+  for _ = 1, 200 do
+    if screen.phase == "menu" then break end
+    tap("a", 3)
+  end
+  if screen.phase ~= "menu" then
+    print("[use-next] FAIL never reached the battle menu")
+    while true do U.wait(60) end
+  end
+
+  tap("a")
+  U.wait(6)
+  tap("a")
+
+  local sawAsk, sawForced = false, false
+  for _ = 1, 400 do
+    if screen.phase == "ask-next-mon" then sawAsk = true break end
+    if screen.phase == "forced-switch" or screen.phase == "submenu" then
+      sawForced = true
+      break
+    end
+    if screen.battle.over then break end
+    tap("a", 3)
+  end
+
+  claim(sawAsk, "wild faint opened Use next POKéMON?")
+  claim(not sawForced, "wild faint did not skip to the party list")
+  claim(screen.phase == "ask-next-mon",
+    "phase is ask-next-mon (YES switches, NO/B tries to run)")
+  print("[use-next] YES sends you to the party. NO or B tries to run.")
+  print("[use-next] a failed run still opens the party. trainers skip this.")
+
+  while true do U.wait(60) end
+end

tests/engine/battle_menu_auxiliary.lua

@@ -0,0 +1,108 @@
+-- Public battle auxiliary actions are a narrow semantic entry point for tool
+-- mods.  They run only at the same settled ordinary decision boundary as a
+-- battle checkpoint, consume no FIGHT/PKMN/ITEM/RUN action, and receive no
+-- live BattleState object.
+
+package.path = "./?.lua;./?/init.lua;" .. package.path
+love = love or require("tests.love_stub")
+
+local T = require("tests.harness").suite("battle menu auxiliary action")
+local Fixtures = require("tests.modkit").fixtures
+local BattleState = require("src.battle.BattleState")
+local Hooks = require("src.mods.Hooks")
+local Runtime = require("src.mods.Runtime")
+local Pokemon = require("src.pokemon.Pokemon")
+local SaveData = require("src.core.SaveData")
+local StateStack = require("src.core.StateStack")
+
+local Data = Fixtures.fresh()
+
+local function makeGame(kind)
+  local save = SaveData.newGame()
+  save.meta.playthroughId = "battle-menu-playthrough"
+  save.party = { Pokemon.new(Data, "FIXMON_A", 20) }
+  local stack = setmetatable({ states = {} }, { __index = StateStack })
+  local overworld = {
+    map = { id = save.player.map },
+    player = { cellX = save.player.x, cellY = save.player.y, facing = save.player.facing },
+    runner = { isRunning = function() return false end },
+    parallelRunners = {}, pendingScripts = {}, parallelQueue = {}, scriptMoves = {},
+  }
+  local game = { data = Data, save = save, stack = stack }
+  game.input = { wasPressed = function(_, button) return button == "start" end }
+  game.overworld = overworld
+  stack.states[1] = overworld
+  local battle = kind == "trainer"
+    and BattleState.newTrainer(game, "OPP_FIX_YOUNGSTER", 1)
+    or BattleState.newWild(game, "FIXMON_B", 12)
+  battle.phase, battle.queue = "menu", {}
+  battle.checkpointOrigin = kind == "trainer"
+    and { kind = "trainer_encounter", map = save.player.map, npcId = "TRAINER_1",
+      trainerClass = "OPP_FIX_YOUNGSTER", partyIndex = 1, event = "EVENT_BEAT_TRAINER_1" }
+    or { kind = "wild_encounter", map = save.player.map }
+  battle.onFinish = function() end
+  stack.states[2] = battle
+  return game, battle
+end
+
+local oldHooks = Runtime.hooks
+local hooks = Hooks.new()
+Runtime.hooks = hooks
+
+local game, battle = makeGame("wild")
+local calls = 0
+hooks:wrap("battle.menu_auxiliary", function(nextFn, liveGame, context)
+  calls = calls + 1
+  T.check(liveGame == game, "auxiliary action receives the live game")
+  T.same(context, { kind = "wild" }, "auxiliary action receives only data-only battle context")
+  return true
+end, 0, "tool_fixture")
+
+local originalIndex = battle.menuIndex
+battle:update(1 / 60)
+T.eq(calls, 1, "START reaches the public auxiliary action at a wild decision")
+T.eq(battle.phase, "menu", "handled auxiliary action does not advance the battle")
+T.eq(battle.menuIndex, originalIndex, "handled auxiliary action preserves cursor")
+T.eq(#battle.queue, 0, "handled auxiliary action does not enqueue a turn")
+
+hooks:removeOwner("tool_fixture")
+local trainerGame, trainer = makeGame("trainer")
+local trainerCalls = 0
+hooks:wrap("battle.menu_auxiliary", function(_, liveGame, context)
+  trainerCalls = trainerCalls + 1
+  T.check(liveGame == trainerGame, "trainer action receives its live game")
+  T.same(context, { kind = "trainer" }, "trainer context remains data-only")
+  return true
+end, 0, "trainer_fixture")
+trainer:update(1 / 60)
+T.eq(trainerCalls, 1, "START reaches the public auxiliary action at a trainer decision")
+hooks:removeOwner("trainer_fixture")
+
+local scriptedGame, scripted = makeGame("trainer")
+scripted.checkpointOrigin = { kind = "script_battle", scriptId = "STORY_TEST", pc = 4 }
+scripted.checkpointScriptContinuation = { kind = "script_battle" }
+local scriptedCalls = 0
+hooks:wrap("battle.menu_auxiliary", function(_, liveGame, context)
+  scriptedCalls = scriptedCalls + 1
+  T.check(liveGame == scriptedGame,
+    "scripted action receives the live game without its runner")
+  T.same(context, { kind = "trainer" },
+    "supported scripted trainer context remains data-only")
+  return true
+end, 0, "scripted_fixture")
+scripted:update(1 / 60)
+T.eq(scriptedCalls, 1,
+  "START reaches the public auxiliary action at a supported scripted decision")
+hooks:removeOwner("scripted_fixture")
+
+local unsafeGame, unsafe = makeGame("wild")
+unsafe.phase = "messages"
+local unsafeCalls = 0
+hooks:wrap("battle.menu_auxiliary", function() unsafeCalls = unsafeCalls + 1 return true end,
+  0, "unsafe_fixture")
+unsafe:update(1 / 60)
+T.eq(unsafeCalls, 0, "messages never expose the auxiliary action")
+hooks:removeOwner("unsafe_fixture")
+
+Runtime.hooks = oldHooks
+T.finish()

tests/engine/resume_boot_music_no_fade.lua

@@ -0,0 +1,208 @@
+-- Regression test for the title-music-bleeds-into-the-map bug: Continue,
+-- F2 quickload, and checkpoint-resume used to drop the player into the
+-- overworld while the old song (the title screen's, or F2's previous
+-- location) was still cross-fading in over Music.MAP_FADE's ~1.2s,
+-- audibly wrong since the player already had control. See
+-- OverworldState:setMap (src/world/OverworldController.lua) for the
+-- opts.freshBoot mechanism this exercises, and Game.lua for where it's
+-- set (onContinue, New Game, F2, restoreCheckpointSave) and where it's
+-- deliberately not (dev tooling's reuse of opts.via == "boot").
+--
+-- (A)-(A4) and (C) call the real Game:restoreSave, Game:keypressed("f2"),
+-- Game:restoreCheckpointSave and Console:exec("warp ...") -- SaveData.load
+-- stubbed to skip the slot/persistence format -- so a dropped freshBoot at
+-- any real call site fails this test, not just a hand-built opts table.
+-- (D) simulates HotReload's { via = "boot" } shape instead of calling
+-- through its local, unexported reloadMap.
+--
+-- ROM-free (fixture dataset -- FIX_TOWN/FIX_ROUTE, tests/fixture_data),
+-- like tests/engine/warp_sprite_hidden_bug916.lua, so the CI headless
+-- tier (no data/generated/) runs it.
+--   luajit tests/engine/resume_boot_music_no_fade.lua
+
+package.path = "./?.lua;./?/init.lua;" .. package.path
+if not _G.love then _G.love = require("tests.love_stub") end
+
+local T = require("tests.modkit")
+local check = T.check
+local eq = T.eq
+
+local Source = {}
+Source.__index = Source
+function Source:play() self.playing = true end
+function Source:stop() self.playing = false end
+function Source:pause() self.playing = false end
+function Source:isPlaying() return self.playing end
+function Source:setLooping() end
+function Source:setVolume(v) self.volume = v end
+function Source:setPitch() end
+function Source:setFilter() end
+function Source:getDuration() return 1 end
+
+local made = {} -- file -> the last source built for it
+love.audio = {
+  newSource = function(file, mode)
+    made[file] = setmetatable({ file = file, mode = mode }, Source)
+    return made[file]
+  end,
+}
+
+local Data = T.fixtures.fresh()
+-- fixture patches that let the overworld boot and run headlessly (same
+-- set tests/engine/warp_sprite_hidden_bug916.lua needs for the same reason)
+Data.tilesets.FIX_OUT.tilesPerRow = 16
+Data.field.flyWarps = Data.field.flyWarps or {}
+Data.field.playerSprites = { walk = "SPRITE_FIX_PLAYER" }
+Data.field.waterTilesets = {}
+Data.field.forcedMovement = { tiles = {} }
+-- no data.audio in the fixture dataset either; synthesize just enough for
+-- real Music.lua playback to run against the real FIX_TOWN/FIX_ROUTE maps
+Data.audio = Data.audio or {}
+Data.audio.songs = Data.audio.songs or {}
+Data.audio.songs.Music_TitleScreen = { file = "title.wav" }
+Data.audio.mapSongs = Data.audio.mapSongs or {}
+Data.audio.mapSongs.FIX_TOWN = "Music_FixTown"
+Data.audio.songs.Music_FixTown = { file = "town.wav" }
+Data.audio.mapSongs.FIX_ROUTE = "Music_FixRoute"
+Data.audio.songs.Music_FixRoute = { file = "route.wav" }
+
+local Music = require("src.core.Music")
+local SaveData = require("src.core.SaveData")
+local Game = require("src.core.Game")
+local StateStack = require("src.core.StateStack")
+local OverworldState = require("src.world.OverworldController")
+local Console = require("src.dev.Console")
+
+Game.data = Data
+Game.save = SaveData.newGame()
+Game.save.player.name = "RED"
+Game.save.player.map = "FIX_TOWN"
+StateStack:init()
+Game.stack = StateStack
+Game.overworld = OverworldState -- set once at boot in the real game (Game.lua)
+Game.input = {
+  isDown = function() return false end,
+  wasPressed = function() return false end,
+  step = function() end, state = {}, pressQueue = {},
+}
+Game.renderer = {
+  beginWorldPass = function() end, endWorldPass = function() end,
+  beginUIPass = function() end, endUIPass = function() end,
+  worldViewSize = function() return 160, 144 end,
+  setSGBZones = function() end,
+}
+
+local function playing()
+  for file, src in pairs(made) do
+    if src.playing then return file end
+  end
+  return "(silence)"
+end
+
+local function finishFade()
+  for _ = 1, 7 * Music.MAP_FADE do Music.update(Data) end
+end
+
+-- ===========================================================================
+-- (A) The real Game:restoreSave, called the way onContinue calls it.
+-- ===========================================================================
+Music.play(Data, "Music_TitleScreen")
+eq(playing(), "title.wav", "title screen music is playing before Continue")
+
+local loaded = SaveData.newGame()
+loaded.player.map = "FIX_TOWN"
+Game:restoreSave(loaded, false, { freshBoot = true })
+
+eq(playing(), "town.wav",
+  "Continue's real restoreSave(..., {freshBoot=true}) swaps at once")
+
+-- ===========================================================================
+-- (A2) The same real Game:restoreSave with no opts at all -- its own
+-- default (e.g. for any future caller that doesn't ask for freshBoot) is
+-- the safe, ordinary crossfade, not a silent hard-cut.
+-- ===========================================================================
+Music.play(Data, "Music_TitleScreen") -- stand-in for whatever was playing
+local loaded2 = SaveData.newGame()
+loaded2.player.map = "FIX_TOWN"
+Game:restoreSave(loaded2, false)
+
+eq(playing(), "title.wav",
+  "restoreSave(...) with no opts still fades, not an instant swap")
+finishFade()
+eq(playing(), "town.wav", "...landing on the loaded save's map song")
+
+-- ===========================================================================
+-- (A3) The real Game:keypressed("f2") handler, both ways it's reachable:
+-- at the title screen and mid-session. SaveData.load is stubbed rather
+-- than round-tripped through the in-memory love.filesystem, to isolate
+-- this test from the slot/persistence format.
+-- ===========================================================================
+local realLoad = SaveData.load
+local loaded3 = SaveData.newGame()
+loaded3.player.map = "FIX_TOWN"
+SaveData.load = function() return loaded3, false end
+
+StateStack:init() -- no overworld on the stack: "at the title screen"
+Music.play(Data, "Music_TitleScreen")
+Game:keypressed("f2")
+eq(playing(), "town.wav",
+  "F2 from the title screen (overworld not on the stack) swaps at once")
+
+StateStack:init()
+StateStack.states[1] = OverworldState -- overworld already active: mid-session
+Music.play(Data, "Music_TitleScreen") -- stand-in for the session's own song
+Game:keypressed("f2")
+eq(playing(), "town.wav",
+  "F2 mid-session (a live overworld already on the stack) also swaps at once")
+
+SaveData.load = realLoad
+StateStack:init()
+
+-- ===========================================================================
+-- (A4) The real Game:restoreCheckpointSave, called the way Checkpoint.resume
+-- (RFC 0006's mod.checkpoint:resume) calls it.
+-- ===========================================================================
+Music.play(Data, "Music_TitleScreen")
+local checkpointSave = SaveData.newGame()
+checkpointSave.player.map = "FIX_TOWN"
+Game:restoreCheckpointSave(checkpointSave)
+eq(playing(), "town.wav",
+  "a title-session checkpoint resume swaps at once, no lingering title music")
+
+StateStack:init()
+
+-- ===========================================================================
+-- (B) An ordinary warp (e.g. walking into a house) is unaffected: it still
+-- cross-fades like any other map-to-map transition.
+-- ===========================================================================
+OverworldState:setMap("FIX_ROUTE", 3, 3, "up", {})
+eq(playing(), "town.wav",
+  "an ordinary warp still fades: the old song is still playing right after setMap")
+finishFade()
+eq(playing(), "route.wav",
+  "...and lands on the new map's song once the fade completes")
+
+-- ===========================================================================
+-- (C) The real dev console `warp` verb (src/dev/Console.lua VERBS.warp).
+-- ===========================================================================
+Music.play(Data, "Music_TitleScreen") -- re-arm a "stale" song to prove intent
+Console.new(Game):exec("warp FIX_TOWN 5 5")
+
+eq(playing(), "title.wav",
+  "Console's real `warp` verb still fades, like an ordinary warp")
+finishFade()
+eq(playing(), "town.wav", "...landing on the target map's song")
+
+-- ===========================================================================
+-- (D) src/dev/HotReload.lua's reloadMap opts shape, simulated (see header)
+-- rather than called through: reloadMap is local/unexported, and
+-- HotReload.run's full loader teardown is out of scope for this fix.
+-- ===========================================================================
+Music.play(Data, "Music_TitleScreen")
+OverworldState:setMap("FIX_ROUTE", 3, 3, "up", { via = "boot" })
+eq(playing(), "title.wav",
+  "HotReload's { via = \"boot\" } setMap still fades, not an instant swap")
+finishFade()
+eq(playing(), "route.wav", "...landing on the reloaded map's song")
+
+T.finish("resume_boot_music_no_fade")

tests/integration/title_checkpoint_cold_start.lua

@@ -72,11 +72,10 @@ local function writeProbe()
   fs.write("mods/cold_start_probe/manifest.json",
     '{"id":"cold_start_probe","name":"cold start probe","version":"1.0.0",'
       .. '"entry":"main.lua","api":2,"profile":"content"}')
-  -- mod.exports, not _G: a mod's globals are its own (src/mods/Sandbox.lua)
   fs.write("mods/cold_start_probe/main.lua", [[
 return function(mod)
-  mod.exports.storage = mod.storage
-  mod.exports.checkpoints = mod.checkpoints
+  _G.COLD_STORAGE = mod.storage
+  _G.COLD_CHECKPOINTS = mod.checkpoints
 end
 ]])
 end
@@ -126,12 +125,11 @@ if phase == "capture" then
   local game = runtime(SaveData.newGame({ version = "red" }), false)
   loader.game = game
   assert(loader:load({}) == true)
-  local probe = assert(loader.exports.cold_start_probe)
-  assert(probe.storage:write(game, "history/index", { newest = "q0001" }))
-  local checkpoint = assert(probe.checkpoints:capture(game))
-  assert(probe.storage:write(game, "history/q0001", checkpoint))
+  assert(_G.COLD_STORAGE:write(game, "history/index", { newest = "q0001" }))
+  local checkpoint = assert(_G.COLD_CHECKPOINTS:capture(game))
+  assert(_G.COLD_STORAGE:write(game, "history/q0001", checkpoint))
   local id = assert(game.save.meta.playthroughId)
-  assert(probe.checkpoints:ensureNormalSave(game, checkpoint))
+  assert(_G.COLD_CHECKPOINTS:ensureNormalSave(game, checkpoint))
   local normal = assert(SaveData.load("red"))
   assert(normal.meta.playthroughId == id)
   fs.write("cold-start-witness.lua", SaveSerializer.encode({ playthroughId = id }))
@@ -141,16 +139,15 @@ else
   title.save.options = { volume = 7, bindings = {} }
   loader.game = title
   assert(loader:load({}) == true)
-  local probe = assert(loader.exports.cold_start_probe)
-  local selected = assert(probe.storage:selected(title))
+  local selected = assert(_G.COLD_STORAGE:selected(title))
   local witness = assert(SaveSerializer.decode(assert(fs.read("cold-start-witness.lua"))))
   assert(selected:context().playthroughId == witness.playthroughId)
   assert(selected:read("history/index").newest == "q0001")
   local checkpoint = assert(selected:read("history/q0001"))
-  assert(probe.checkpoints:resume(title, checkpoint))
+  assert(_G.COLD_CHECKPOINTS:resume(title, checkpoint))
   assert(title.save.meta.playthroughId == witness.playthroughId)
   assert(title.save.options.volume == 7)
-  assert(SaveSerializer.encode(probe.checkpoints:capture(title))
+  assert(SaveSerializer.encode(_G.COLD_CHECKPOINTS:capture(title))
     == SaveSerializer.encode(checkpoint))
   local normal = assert(SaveData.load("red"))
   assert(normal.meta.playthroughId == witness.playthroughId)

tests/mod_loader_tests.lua

@@ -102,19 +102,20 @@ if not headlessOk then error(headlessErr) end
 love = love or require("tests.love_stub")
 
 -- ------- discovery, dependency order, merge
--- "addon" sorts before "base" so only the dependency edge can order them.
--- loader.order is the engine's own record of what ran when; a mod cannot
--- append to a shared global any more (src/mods/Sandbox.lua).
+-- "addon" sorts before "base" so only the dependency edge can order them
+_G.MOD_TEST_ORDER = {}
 local files = {
   ["mods/addon/manifest.json"] = manifestJson("addon", '["base"]'),
   ["mods/addon/main.lua"] = [[
 return function(mod)
+  _G.MOD_TEST_ORDER[#_G.MOD_TEST_ORDER + 1] = "addon"
   mod.content.pokemon:override("MODMON", { name = "ADDONMON" })
 end
 ]],
   ["mods/base/manifest.json"] = manifestJson("base"),
   ["mods/base/main.lua"] = [[
 return function(mod)
+  _G.MOD_TEST_ORDER[#_G.MOD_TEST_ORDER + 1] = "base"
   mod.content.pokemon:register("MODMON", { name = "BASEMON" })
   mod.content.music:register("MOD_SONG", { file = "song.ogg" })
 end
@@ -125,7 +126,7 @@ local loader = Loader.new({ fs = memfs(files) })
 check(loader:load(data) == true, "headless load succeeds with injected fs")
 check(loader.mods.addon ~= nil and loader.mods.base ~= nil,
   "discovery finds both mods")
-check(loader.order[1] == "base" and loader.order[2] == "addon",
+check(_G.MOD_TEST_ORDER[1] == "base" and _G.MOD_TEST_ORDER[2] == "addon",
   "topo-sort runs the dependency before its dependent")
 check(data.pokemon.MODMON ~= nil and data.pokemon.MODMON.name == "ADDONMON",
   "registered content merges into data")
@@ -410,5 +411,6 @@ local StateStack = require("src.core.StateStack")
 while StateStack:top() do StateStack:pop() end
 require("src.core.Music").stop()
 Runtime.install(savedEvents, savedHooks)
+_G.MOD_TEST_ORDER = nil
 
 S.finish()

tests/mod_manifest_tests.lua

@@ -341,8 +341,7 @@ check(cycleStatus.innocent.state == "loaded" and cycleData.items.FINE ~= nil,
   "a mod beside the cycle loads normally")
 
 -- ------- inter-mod exports and find
--- probes report through mod.exports: a mod's globals are its own
--- (src/mods/Sandbox.lua)
+_G.MOD_FIND_RESULTS = {}
 local exportLoader = Loader.new({ fs = memfs({
   ["mods/colorlib/manifest.json"] = manifestJson("colorlib"),
   ["mods/colorlib/main.lua"] = [[
@@ -357,7 +356,7 @@ end
   }),
   ["mods/daynight/main.lua"] = [[
 return function(mod)
-  local results = mod.exports
+  local results = _G.MOD_FIND_RESULTS
   local color = mod.find("colorlib")
   results.depVersion = color.version
   results.tint = color.exports.tint("dusk")
@@ -372,7 +371,7 @@ end
   ["options.lua"] = "return { mods = { shelved = false } }",
 }) })
 check(exportLoader:load({}) == true, "the export fixture loads clean")
-local found = exportLoader.exports.daynight
+local found = _G.MOD_FIND_RESULTS
 check(found.tint == "tinted:dusk", "find returns the other mod's live export table")
 check(found.depVersion == "1.0.0", "the handle carries the other mod's version")
 check(found.optional == true, "an enabled optional dependency is findable")
@@ -381,8 +380,10 @@ check(found.disabled == nil, "find returns nil for a disabled mod")
 check(found.method == true, "mod:find is tolerated alongside mod.find")
 check(exportLoader.order[1] == "colorlib",
   "a hard dependency executes before its dependent")
+_G.MOD_FIND_RESULTS = nil
 
 -- ------- the rest of the v2 mod object
+_G.MOD_OBJECT_PROBE = {}
 local objectLoader = Loader.new({ fs = memfs({
   ["mods/probe/manifest.json"] = manifestJson("probe", {
     api = "2", description = '"probing"', priority = "3",
@@ -390,7 +391,7 @@ local objectLoader = Loader.new({ fs = memfs({
   ["mods/probe/data.txt"] = "hello from the mod dir",
   ["mods/probe/main.lua"] = [[
 return function(mod)
-  local probe = mod.exports
+  local probe = _G.MOD_OBJECT_PROBE
   probe.id, probe.version, probe.path = mod.id, mod.version, mod.path
   probe.manifestApi = mod.manifest.api
   mod.manifest.api = 99
@@ -422,7 +423,7 @@ end
   ["options.lua"] = "return { modOptions = { probe = { volume = 4 } } }",
 }) })
 check(objectLoader:load({ pokemon = {} }) == true, "the mod object fixture loads clean")
-local probe = objectLoader.exports.probe
+local probe = _G.MOD_OBJECT_PROBE
 check(probe.id == "probe" and probe.version == "1.0.0" and probe.path == "mods/probe",
   "identity fields are present")
 check(probe.manifestApi == 2 and objectLoader.mods.probe.manifest.api == 2,
@@ -448,6 +449,7 @@ check(probe.onceCount == 1 and probe.stillHeard == true,
   "events:once fires once and does not skip the listener behind it")
 check(tostring(probe.forgery):find("may only emit", 1, true) ~= nil,
   "a mod cannot emit outside its own event namespace")
+_G.MOD_OBJECT_PROBE = nil
 
 -- a failing entry chunk takes its exports, commands and migrations with it
 local residueLoader = Loader.new({ fs = memfs({

tests/mod_qol_hooks_tests.lua

@@ -12,6 +12,7 @@ local Zoom = require("src.render.Zoom")
 local ListMenu = require("src.ui.ListMenu")
 local NamingScreen = require("src.ui.NamingScreen")
 local TextBox = require("src.render.TextBox")
+local ChoiceBox = require("src.ui.ChoiceBox")
 local PartyMenu = require("src.ui.PartyMenu")
 local Player = require("src.world.Player")
 local Music = require("src.core.Music")
@@ -180,6 +181,23 @@ do
   text:draw()
   check(seen == text, "pushed text boxes use the same visibility hook")
   unsub()
+
+  local battle = setmetatable({ isBattle = true }, BattleState)
+  local game = { stack = { states = {} } }
+  text = setmetatable({ game = game }, TextBox)
+  local choice = setmetatable({ game = game }, ChoiceBox)
+  game.stack.states = { battle, text, choice }
+  local queried = {}
+  unsub = wrap("battle.bottom_ui_visible", function(_, state)
+    queried[#queried + 1] = state
+    return state ~= battle
+  end)
+  text:draw()
+  choice:draw()
+  check(queried[1] == battle and queried[2] == battle and #queried == 2,
+    "battle overlays inherit a hidden bottom layer without drawing backings")
+  unsub()
+
   check(BattleState.bottomUIVisible({ phase = "moveSelect" }),
     "battle bottom UI returns when the hook is removed")
 

tests/mod_render_tests.lua

@@ -87,19 +87,13 @@ end
 
 -- ------- a mod registers two pipelines and the engine dispatches them
 
--- The probe table is the mod's, published through mod.exports: a mod's
--- globals are its own now (src/mods/Sandbox.lua).  The world/present folds
--- accept only a real Canvas, so the mod makes concrete ones to return and the
--- test pins identity through the dispatch.
+local trace = {}
+
 local FILES = {
   ["mods/painter/manifest.json"] = manifest("painter", ',"priority":10'),
   ["mods/painter/main.lua"] = [[
     local mod = ...
-    local T = mod.exports
-    T.trace, T.available = {}, true
-    T.worldOut = love.graphics.newCanvas(2, 2)
-    T.blurOut = love.graphics.newCanvas(2, 2)
-    T.gradeOut = love.graphics.newCanvas(2, 2)
+    local T = _G.__RENDER_TEST
     mod.content.render_pipelines:register("diorama", {
       label = "DIORAMA",
       levels = { "OFF", "LOW", "HIGH" },
@@ -107,6 +101,8 @@ local FILES = {
       priority = 20,
       available = function() return T.available end,
       update = function(dt, level) T.trace[#T.trace + 1] = "update:" .. level end,
+      -- the folds composite only a real Canvas, so the mod hands back the
+      -- canvases the test pre-created (see T.worldOut / T.blurOut / T.gradeOut)
       drawWorld = function(ctx)
         T.trace[#T.trace + 1] = "world:" .. tostring(ctx.tag)
         return T.worldOut
@@ -127,12 +123,17 @@ local FILES = {
   ]],
 }
 
+_G.__RENDER_TEST = { trace = trace, available = true }
+-- the world/present folds accept only a real Canvas, so give the mod concrete
+-- ones to return and pin identity through the dispatch
+_G.__RENDER_TEST.worldOut = love.graphics.newCanvas(2, 2)
+_G.__RENDER_TEST.blurOut = love.graphics.newCanvas(2, 2)
+_G.__RENDER_TEST.gradeOut = love.graphics.newCanvas(2, 2)
+
 local data = {}
 local loader = Loader.new({ fs = memfs(FILES) })
 local okLoad = loader:load(data)
 check(okLoad, "the pipeline mod loads clean: " .. table.concat(loader.errors, "; "))
-local RT = loader.exports.painter
-local trace = RT.trace
 Pipelines.install(data)
 
 check(type(data.render_pipelines) == "table",
@@ -168,24 +169,24 @@ Pipelines.setLevel("grade", 1)
 
 eq(Pipelines.worldPipeline(), "diorama",
   "the eligible world pipeline claims the world pass")
-eq(Pipelines.drawWorld("diorama", { tag = "ctx" }), RT.worldOut,
+eq(Pipelines.drawWorld("diorama", { tag = "ctx" }), _G.__RENDER_TEST.worldOut,
   "drawWorld returns the mod's canvas")
 eq(trace[#trace], "world:ctx", "drawWorld received the frame context")
 
-eq(Pipelines.worldPresent(RT.worldOut), RT.blurOut,
+eq(Pipelines.worldPresent(_G.__RENDER_TEST.worldOut), _G.__RENDER_TEST.blurOut,
   "worldPresent folds its canvas over the world image")
 eq(Pipelines.wantsPresent(), true, "a live present pass asks for the canvas")
-eq(Pipelines.present(RT.gradeOut), RT.gradeOut,
+eq(Pipelines.present(_G.__RENDER_TEST.gradeOut), _G.__RENDER_TEST.gradeOut,
   "present folds its canvas over the finished composite")
 
 -- ------- the hardware gate
 
-RT.available = false
+_G.__RENDER_TEST.available = false
 eq(Pipelines.worldPipeline(), nil,
   "an unavailable pipeline never takes the world pass")
 eq(Pipelines.worldPresent("world-canvas"), "world-canvas",
   "an unavailable pipeline's worldPresent is skipped")
-RT.available = true
+_G.__RENDER_TEST.available = true
 eq(Pipelines.worldPipeline(), "diorama", "availability is re-read each frame")
 
 -- ------- the gate governs input, never the draw
@@ -281,8 +282,7 @@ local SLOPPY = {
   ["mods/sloppy/manifest.json"] = manifest("sloppy"),
   ["mods/sloppy/main.lua"] = [[
     local mod = ...
-    local T = mod.exports
-    T.ran = 0
+    local T = _G.__SLOPPY
     mod.content.render_pipelines:register("sloppy", {
       label = "SLOPPY",
       present = function(canvas)
@@ -302,20 +302,20 @@ local SLOPPY = {
     })
   ]],
 }
+_G.__SLOPPY = { ran = 0 }
 local sloppyData = {}
 local sloppyLoader = Loader.new({ fs = memfs(SLOPPY) })
 sloppyLoader:load(sloppyData)
-local SL = sloppyLoader.exports.sloppy
 Pipelines.install(sloppyData)
 
 local composite = love.graphics.newCanvas(4, 4)
 Pipelines.setLevel("sloppy", 1)
 for _, bad in ipairs({ "just-a-string", true, 42 }) do
-  SL.ret = bad
+  _G.__SLOPPY.ret = bad
   eq(Pipelines.present(composite), composite,
     "a present returning a " .. type(bad) .. " leaves the composite untouched")
 end
-check(SL.ran == 3, "the present callback still ran each frame")
+check(_G.__SLOPPY.ran == 3, "the present callback still ran each frame")
 check(Pipelines.eligible("sloppy") == true,
   "a non-canvas return does not retire the pipeline as broken")
 Pipelines.setLevel("sloppy", 0)
@@ -334,9 +334,11 @@ eq(love.graphics.getCanvas(), "engine-canvas",
 eq(love.graphics.getBlendMode(), "alpha",
   "a present that changed blend mode cannot leak it past the fold")
 Pipelines.setLevel("dirty", 0)
+_G.__SLOPPY = nil
 
 Pipelines.reset()
 Pipelines.install(nil)
+_G.__RENDER_TEST = nil
 
 -- ------- and with no mods at all, the whole subsystem is inert
 

tests/modkit/cases/checkpoints.lua

@@ -139,20 +139,23 @@ local files = {
   ["mods/probe/manifest.json"] =
     '{"id":"probe","name":"probe","version":"1.0.0",'
       .. '"entry":"main.lua","api":2,"profile":"content"}',
-  -- mod.exports, not _G: a mod's globals are its own (src/mods/Sandbox.lua)
   ["mods/probe/main.lua"] = [[
-return function(mod) mod.exports.checkpoints = mod.checkpoints end
+return function(mod)
+  _G.MOD_CHECKPOINTS = mod.checkpoints
+  _G.MOD_HOOKS = mod.hooks
+end
 ]],
 }
 local game, ow = makeGame()
 local loader = Loader.new({ fs = memfs(files) })
 loader.game = game
 T.check(loader:load({}) == true, "checkpoint fixture mod loads")
-local checkpoints = (loader.exports.probe or {}).checkpoints
+local checkpoints = _G.MOD_CHECKPOINTS
 T.check(type(checkpoints) == "table",
   "Loader exposes mod.checkpoints through the public mod object")
 if type(checkpoints) ~= "table" then
   Runtime.events, Runtime.hooks = savedEvents, savedHooks
+  _G.MOD_CHECKPOINTS = nil
   T.finish()
 end
 
@@ -433,8 +436,28 @@ if battleSnapshot then
     "public battle capture/restore/capture is a normalized differential roundtrip")
 end
 
+-- The mod receives the normal public hook facade, never BattleState. START
+-- at the restored safe decision reaches its semantic auxiliary action without
+-- selecting a native command.
+local auxiliaryCalls = 0
+_G.MOD_HOOKS:wrap("battle.menu_auxiliary", function(nextFn, liveGame, context)
+  auxiliaryCalls = auxiliaryCalls + 1
+  T.check(liveGame == battleGame, "public battle auxiliary action receives the game")
+  T.same(context, { kind = "wild" }, "public auxiliary context is data-only")
+  return true
+end)
+battleGame.input = { wasPressed = function(_, button) return button == "start" end }
+local boundary = battleGame.stack:top()
+local originalMenuIndex = boundary.menuIndex
+boundary:update(1 / 60)
+T.eq(auxiliaryCalls, 1, "public mod hook receives START at the checkpoint boundary")
+T.eq(boundary.phase, "menu", "public auxiliary hook does not advance the turn")
+T.eq(boundary.menuIndex, originalMenuIndex, "public auxiliary hook preserves cursor")
+
 Runtime.events, Runtime.hooks = savedEvents, savedHooks
 Runtime.currentMod = nil
+_G.MOD_CHECKPOINTS = nil
+_G.MOD_HOOKS = nil
 love.math.getRandomState = oldGetRandomState
 love.math.setRandomState = oldSetRandomState
 

tests/modkit/cases/device_power_info.lua

@@ -1,52 +0,0 @@
--- A sandboxed mod may read battery state without receiving love.system and
--- its process-launching surface.
-
-package.path = "./?.lua;./?/init.lua;" .. package.path
-
-local T = require("tests.modkit")
-
-local FIXTURE = {
-  ["mods/power_probe/manifest.json"] = [[{
-    "id": "power_probe",
-    "name": "Power Probe",
-    "version": "1.0.0",
-    "entry": "main.lua",
-    "api": 2
-  }]],
-  ["mods/power_probe/main.lua"] = [[
-    local mod = ...
-    mod.exports.state, mod.exports.percent = mod.device:powerInfo()
-  ]],
-}
-
-local saved = T.love.system.getPowerInfo
-local calls = 0
-T.love.system.getPowerInfo = function()
-  calls = calls + 1
-  return "charging", 42, 900
-end
-
-local vanilla = T.sdk.loadNone({})
-T.eq(calls, 0, "no mod leaves the device power backend cold")
-vanilla.release()
-
-local run = T.sdk.loadMods({ "mods/power_probe" },
-  { fs = T.sdk.memfs(FIXTURE) })
-T.eq(#run.errors, 0,
-  "the sandboxed power probe loads clean (" .. tostring(run.errors[1]) .. ")")
-local out = run.loader.exports.power_probe or {}
-T.eq(out.state, "charging", "the public facade reports battery state")
-T.eq(out.percent, 42, "the public facade reports battery percentage")
-T.eq(calls, 1, "one facade read makes one platform call")
-run.release()
-
-T.love.system.getPowerInfo = nil
-local unavailable = T.sdk.loadMods({ "mods/power_probe" },
-  { fs = T.sdk.memfs(FIXTURE) })
-out = unavailable.loader.exports.power_probe or {}
-T.eq(out.state, "unknown", "a missing platform backend has a stable state")
-T.eq(out.percent, nil, "a missing platform backend has no invented percentage")
-unavailable.release()
-
-T.love.system.getPowerInfo = saved
-T.finish("device_power_info")

tests/modkit/cases/platform_lifecycle_hooks.lua

@@ -23,16 +23,16 @@ local FIXTURE = {
       extraPolls = extraPolls + 1
       if not paused then nextFn(game, dt) end
     end)
-    local vetoQuit = false
     mod.hooks:wrap("core.quit_to_launcher", function(nextFn)
-      if vetoQuit then return false end
+      if os.getenv("FIXTURE_VETO_QUIT") == "1" then return false end
       return nextFn()
     end)
-    -- test-only knobs on mod.exports: a sandboxed mod has no shared _G to
-    -- smuggle them through (src/mods/Sandbox.lua)
-    mod.exports.setPaused = function(v) paused = v end
-    mod.exports.extraPolls = function() return extraPolls end
-    mod.exports.setVetoQuit = function(v) vetoQuit = v end
+    -- test-only knobs, read back through mod.storage-free globals since
+    -- this fixture never leaves the process
+    _G.__fixturePlatformBridge = {
+      setPaused = function(v) paused = v end,
+      extraPolls = function() return extraPolls end,
+    }
   ]],
 }
 
@@ -43,23 +43,23 @@ do
   T.eq(#run.errors, 0,
     "the fixture mod loads clean (" .. tostring(run.errors[1]) .. ")")
 
-  local bridge = run.loader.exports.fix_platform_bridge
   local calls = 0
   local fakeGame = { update = function(self, dt) calls = calls + 1 end }
 
-  bridge.setPaused(false)
+  _G.__fixturePlatformBridge.setPaused(false)
   PlatformHooks.update(fakeGame, 1 / 60)
   T.eq(calls, 1, "unpaused: vanilla Game:update runs")
-  T.eq(bridge.extraPolls(), 1,
+  T.eq(_G.__fixturePlatformBridge.extraPolls(), 1,
     "the subscriber's wrapper runs every frame")
 
-  bridge.setPaused(true)
+  _G.__fixturePlatformBridge.setPaused(true)
   PlatformHooks.update(fakeGame, 1 / 60)
   T.eq(calls, 1, "paused: vanilla Game:update is skipped")
-  T.eq(bridge.extraPolls(), 2,
+  T.eq(_G.__fixturePlatformBridge.extraPolls(), 2,
     "the subscriber keeps polling every frame while paused")
 
   run.release()
+  _G.__fixturePlatformBridge = nil
 end
 
 -- core.quit_to_launcher: a subscriber can veto without the vanilla
@@ -70,8 +70,11 @@ do
   T.eq(#run.errors, 0,
     "the fixture mod loads clean (" .. tostring(run.errors[1]) .. ")")
 
-  local bridge = run.loader.exports.fix_platform_bridge
-  bridge.setVetoQuit(true)
+  local realGetenv = os.getenv
+  os.getenv = function(name)
+    if name == "FIXTURE_VETO_QUIT" then return "1" end
+    return realGetenv(name)
+  end
   local vanillaCalls = 0
   local vetoed = PlatformHooks.quitToLauncher(function()
     vanillaCalls = vanillaCalls + 1
@@ -79,7 +82,7 @@ do
   end)
   T.eq(vetoed, false, "a subscriber can veto the return-to-launcher decision")
   T.eq(vanillaCalls, 0, "a veto never evaluates the vanilla condition")
-  bridge.setVetoQuit(false)
+  os.getenv = realGetenv
 
   local passed = PlatformHooks.quitToLauncher(function() return true end)
   T.eq(passed, true, "with no veto, the vanilla decision passes through unchanged")

tests/modkit/cases/pokemon_icon.lua

@@ -0,0 +1,60 @@
+-- Public read-only Pokemon icon presentation delegates to the same resolver
+-- PartyMenu uses, so content registrations and pokemon.icon hooks compose.
+
+package.path = "./?.lua;./?/init.lua;" .. package.path
+
+local T = require("tests.modkit")
+local PartyMenu = require("src.ui.PartyMenu")
+
+local FIXTURE = {
+  ["mods/icon_probe/manifest.json"] = [[{
+    "id": "icon_probe",
+    "name": "Icon Probe",
+    "version": "1.0.0",
+    "entry": "main.lua",
+    "api": 2
+  }]],
+  ["mods/icon_probe/main.lua"] = [[
+    local mod = ...
+    mod.exports.icon = mod.ui.PokemonIcon
+  ]],
+}
+
+local run = T.sdk.loadMods({ "mods/icon_probe" }, { fs = T.sdk.memfs(FIXTURE) })
+T.eq(#run.errors, 0, "fixture mod loads cleanly")
+local icon = run.loader.exports.icon_probe.icon
+T.eq(type(icon), "table", "mod.ui exposes the PokemonIcon helper")
+T.eq(type(icon.draw), "function", "PokemonIcon exposes a draw operation")
+
+local original = PartyMenu.drawIcon
+local call
+PartyMenu.drawIcon = function(game, mon, x, y, selected, counter)
+  call = { game = game, mon = mon, x = x, y = y,
+    selected = selected, counter = counter }
+end
+
+local game = { data = {} }
+local drawn, code = icon.draw(game, {
+  species = "PIKACHU", hp = 4, maxHp = 10,
+}, 8, 16, { selected = true, counter = 7 })
+T.eq(drawn, true, "valid detached Pokemon summary is drawable")
+T.eq(code, nil, "valid summary has no rejection code")
+T.check(call and call.game == game, "helper delegates with the live game")
+T.eq(call.mon.species, "PIKACHU", "species reaches the shared party resolver")
+T.eq(call.mon.hp, 4, "captured current HP reaches icon animation semantics")
+T.eq(call.mon.stats.hp, 10, "captured maximum HP reaches icon animation semantics")
+T.eq(call.selected, true, "selection state is presentation-only")
+T.eq(call.counter, 7, "animation counter is presentation-only")
+
+call = nil
+local bad, badCode = icon.draw(game, {
+  species = "PIKACHU", hp = 11, maxHp = 10,
+}, 0, 0)
+T.eq(bad, false, "invalid detached summary fails closed")
+T.eq(badCode, "invalid_pokemon_preview", "invalid summary has a stable error")
+T.eq(call, nil, "invalid summary never reaches renderer internals")
+
+PartyMenu.drawIcon = original
+run.release()
+
+T.finish("pokemon_icon")

tests/modkit/cases/sandbox.lua

@@ -1,208 +0,0 @@
--- T4: the mod sandbox (src/mods/Sandbox.lua).  A mod's own chunks run against
--- an environment with no io, no os beyond the clock, and no way to name a path
--- outside its own directory, so a mod cannot reach the player's filesystem.
--- Every case here is an escape a mod would actually try.
-
-package.path = "./?.lua;./?/init.lua;" .. package.path
-
-local T = require("tests.modkit")
-local Manifest = require("src.mods.Manifest")
-local Sandbox = require("src.mods.Sandbox")
-local SafePath = require("src.mods.SafePath")
-
-local function manifest(id, extra)
-  return ('{"id":"%s","name":"%s","version":"1.0.0","entry":"main.lua",'
-    .. '"api":2%s}'):format(id, id, extra or "")
-end
-
--- what a probe reports back; pcall'd so one broken assumption does not take
--- the whole entry chunk down and hide the rest
-local PROBE = [[
-  local mod = ...
-  local out = mod.exports
-  out.io = io
-  out.package = package
-  out.dofile = dofile
-  out.loadfile = loadfile
-  out.setfenv = setfenv
-  out.getfenv = getfenv
-  out.debug = debug
-  out.osGetenv = os.getenv
-  out.osExecute = os.execute
-  out.osRemove = os.remove
-  out.osTime = type(os.time)
-  out.stringOk = ("a"):rep(3)
-
-  local function attempt(fn, ...)
-    local ok, err = pcall(fn, ...)
-    if ok then return false end
-    return tostring(err)
-  end
-  out.requireIo = attempt(require, "io")
-  out.requireOs = attempt(require, "os")
-  out.requireDebug = attempt(require, "debug")
-  out.requirePackage = attempt(require, "package")
-  out.requireFfi = attempt(require, "ffi")
-  out.requireLoveFs = attempt(require, "love.filesystem")
-  out.requireSocket = attempt(require, "socket")
-  -- called from a nested Lua frame rather than straight off pcall, which is
-  -- the shape a stack-walking gate reads differently
-  out.requireIoNested = attempt(function() return require("io") end)
-  out.requireSemver = select(2, pcall(require, "src.mods.Semver"))
-
-  out.loveFilesystem = attempt(function() return love.filesystem end)
-  out.loveThread = attempt(function() return love.thread end)
-  out.loveSystem = attempt(function() return love.system end)
-  out.loveGraphics = type(love.graphics)
-  out.loveAssign = attempt(function() love.filesystem = {} end)
-
-  -- the multi-file pattern mods/timekeepers_hut uses: a chunk loaded from the
-  -- mod's own source must inherit the sandbox, not the real globals
-  local child = load("return io, os.getenv, _G")
-  local childIo, childGetenv, childG = child()
-  out.childIo = childIo
-  out.childGetenv = childGetenv
-  out.childSharesEnv = childG == _G
-
-  out.readEscape = attempt(function() return mod:read("../../secret.txt") end)
-  out.readAbsolute = attempt(function() return mod:read("/etc/hosts") end)
-  out.readBackslash = attempt(function() return mod:read("..\\secret.txt") end)
-  out.assetsEscape = attempt(function() return mod.assets:path("../../x.png") end)
-  out.readOwn = mod:read("data/note.txt")
-
-  _G.SANDBOX_LEAK = "escaped"
-  out.globalsAreOwn = _G ~= nil and _G.SANDBOX_LEAK == "escaped"
-  -- a mod stomping the standard library must not reach the engine
-  table.insert = function() error("stomped") end
-  string.format = function() error("stomped") end
-]]
-
-local FILES = {
-  ["mods/fix_sandbox/manifest.json"] = manifest("fix_sandbox"),
-  ["mods/fix_sandbox/main.lua"] = PROBE,
-  ["mods/fix_sandbox/data/note.txt"] = "own file",
-}
-
-local run = T.sdk.loadMods({ "mods/fix_sandbox" }, { fs = T.sdk.memfs(FILES) })
-T.eq(#run.errors, 0,
-  "the probe mod loads clean (" .. tostring(run.errors[1]) .. ")")
-local out = run.loader.exports.fix_sandbox or {}
-
--- ------- the standard library a mod does not get
-
-T.eq(out.io, nil, "io is absent from the mod environment")
-T.eq(out.package, nil, "package is absent, so package.loaded is unreachable")
-T.eq(out.dofile, nil, "dofile is absent")
-T.eq(out.loadfile, nil, "loadfile is absent")
-T.eq(out.setfenv, nil, "setfenv is absent, so a mod cannot swap its own env")
-T.eq(out.getfenv, nil, "getfenv is absent, so a mod cannot read the real _G out")
-T.eq(out.debug, nil, "the debug library is absent")
-T.eq(out.osGetenv, nil, "os.getenv is absent -- it is how the report's exploit "
-  .. "found the user's home directory")
-T.eq(out.osExecute, nil, "os.execute is absent")
-T.eq(out.osRemove, nil, "os.remove is absent")
-T.eq(out.osTime, "function", "os.time still works: the clock is not the hole")
-T.eq(out.stringOk, "aaa", "the safe standard library is intact")
-
--- ------- require, the one call that would undo all of the above
-
-T.check(out.requireIo and out.requireIo:find("not available to mods", 1, true),
-  "require(\"io\") is refused: " .. tostring(out.requireIo))
-T.check(out.requireOs ~= false, "require(\"os\") is refused")
-T.check(out.requireDebug ~= false, "require(\"debug\") is refused")
-T.check(out.requirePackage ~= false, "require(\"package\") is refused")
-T.check(out.requireFfi ~= false, "require(\"ffi\") is refused: it is arbitrary C")
-T.check(out.requireLoveFs ~= false, "require(\"love.filesystem\") is refused")
-T.check(out.requireIoNested ~= false,
-  "require(\"io\") from a nested frame is refused the same way")
-T.check(out.requireSocket and out.requireSocket:find("network", 1, true),
-  "a network module names the permission it needs: " .. tostring(out.requireSocket))
-T.eq(type(out.requireSemver), "table",
-  "the supported engine requires still resolve")
-
--- ------- the love facade
-
-T.check(out.loveFilesystem and out.loveFilesystem:find("mod.storage", 1, true),
-  "love.filesystem is refused and names the replacement")
-T.check(out.loveThread ~= false, "love.thread is refused: it opens a full Lua state")
-T.check(out.loveSystem and out.loveSystem:find("mod.device:powerInfo()", 1, true),
-  "love.system is refused and names the scoped power replacement")
-T.eq(out.loveGraphics, "table", "the rest of love passes through")
-T.check(out.loveAssign ~= false, "a mod cannot assign into the love facade")
-
--- ------- env propagation and isolation
-
-T.eq(out.childIo, nil,
-  "a chunk a mod load()s inherits the sandbox (5.1 would hand it the real _G)")
-T.eq(out.childGetenv, nil, "the child chunk gets the same reduced os")
-T.check(out.childSharesEnv, "the child chunk shares the mod's own globals table")
-T.check(out.globalsAreOwn, "a mod's globals write to its own table")
-T.eq(_G.SANDBOX_LEAK, nil, "and never reach the engine's _G")
-T.eq(("%d"):format(1), "1",
-  "a mod stomping string.format cannot reach the engine's copy")
-do
-  local probe = {}
-  table.insert(probe, "still works")
-  T.eq(probe[1], "still works",
-    "nor table.insert -- each mod gets its own standard-library namespace")
-end
-
--- ------- paths
-
-T.check(out.readEscape and out.readEscape:find("must stay inside", 1, true),
-  "mod:read cannot climb out of the mod directory: " .. tostring(out.readEscape))
-T.check(out.readAbsolute ~= false, "mod:read refuses an absolute path")
-T.check(out.readBackslash ~= false, "mod:read refuses a backslash climb")
-T.check(out.assetsEscape ~= false, "mod.assets:path refuses a climb")
-T.eq(out.readOwn, "own file", "and the mod's own files still read")
-run.release()
-
--- ------- the grammar itself
-
-for _, bad in ipairs({ "../x", "a/../../x", "/etc/hosts", "C:/Windows/x",
-                       "..\\x", "a\\b", "..", ".", "" }) do
-  T.eq(SafePath.safe(bad), nil, ("SafePath rejects %q"):format(bad))
-end
-T.eq(SafePath.safe("maps/NEW_BARK_TOWN.lua"), "maps/NEW_BARK_TOWN.lua",
-  "an ordinary relative path passes")
-T.eq(SafePath.safe("./main.lua"), "main.lua",
-  "a leading ./ is normalized rather than rejected, so older manifests load")
-
--- ------- manifest paths are untrusted input too
-
-T.check(not pcall(Manifest.validate,
-  { id = "evil", name = "evil", version = "1.0.0", entry = "../../../evil.lua" }),
-  "a manifest cannot point entry outside the mod directory")
-T.check(not pcall(Manifest.validate,
-  { id = "evil", name = "evil", version = "1.0.0", entry = "main.lua",
-    options_schema = "../../options.lua" }),
-  "nor options_schema")
-T.check(pcall(Manifest.validate,
-  { id = "fine", name = "fine", version = "1.0.0", entry = "main.lua" }),
-  "an ordinary manifest still validates")
-
--- ------- bytecode
-
-do
-  local bad = {
-    ["mods/fix_bytecode/manifest.json"] = manifest("fix_bytecode"),
-    ["mods/fix_bytecode/main.lua"] = string.dump(function() end),
-  }
-  local bytecodeRun = T.sdk.loadMods({ "mods/fix_bytecode" },
-    { fs = T.sdk.memfs(bad) })
-  T.eq(#bytecodeRun.errors, 1, "a mod that ships bytecode fails to load")
-  T.check(tostring(bytecodeRun.errors[1]):find("bytecode", 1, true),
-    "and says why: " .. tostring(bytecodeRun.errors[1]))
-  bytecodeRun.release()
-end
-
--- ------- the sandbox is not opt-in
-
-do
-  local env = Sandbox.envFor({ modId = "probe" })
-  T.eq(env.io, nil, "a bare Sandbox.envFor is already closed")
-  T.eq(env._G, env, "_G points at the sandbox, not the real globals")
-  T.check(not pcall(env.require, "io"), "and its require refuses io")
-end
-
-T.finish("sandbox")

tests/modkit/cases/screen_render_visible.lua

@@ -5,6 +5,7 @@ package.path = "./?.lua;./?/init.lua;" .. package.path
 
 local T = require("tests.modkit")
 local Game = require("src.core.Game")
+local Game2 = require("src.core.Game2")
 local Runtime = require("src.mods.Runtime")
 local StateStack = require("src.core.StateStack")
 local Renderer = require("src.render.Renderer")
@@ -92,6 +93,43 @@ do
     "the hidden menu remains the active top state")
   game.stack:update(1 / 60)
   T.eq(menu.updates, 1, "the hidden menu keeps its update ownership")
+
+  -- Gold keeps the overworld outside its state stack. A companion-opened
+  -- screen can therefore be the stack's only state; visibleBase() still
+  -- returns index 1, but that hidden state must not become the direct base.
+  for _, boot in ipairs({ false, true }) do
+    local stack = setmetatable({}, { __index = StateStack })
+    stack:init()
+    local hidden = {
+      screenId = "BagMenu",
+      isOpaque = true,
+      draws = 0,
+      wideDraws = 0,
+      draw = function(self) self.draws = self.draws + 1 end,
+      drawsWidescreen = function() return true end,
+      drawWidescreen = function(self)
+        self.wideDraws = self.wideDraws + 1
+      end,
+    }
+    stack:push(hidden)
+    local world = {
+      map = {}, draws = 0,
+      draw = function(self) self.draws = self.draws + 1 end,
+      fitScale = function() return 1 end,
+    }
+    game = { stack = stack, world = world }
+    game.inFillBoot = function() return boot end
+    game.letterbox = function() end
+    setmetatable(game, { __index = Game2 })
+
+    game:drawScene(1280, 720)
+    T.eq(hidden.wideDraws, 0,
+      "Gold omits a hidden widescreen top (boot=" .. tostring(boot) .. ")")
+    T.eq(hidden.draws, 0,
+      "Gold omits its hidden GB canvas (boot=" .. tostring(boot) .. ")")
+    T.eq(world.draws, boot and 0 or 1,
+      "Gold reveals its external world (boot=" .. tostring(boot) .. ")")
+  end
   run.release()
 end
 

tests/modkit/cases/storage.lua

@@ -66,13 +66,12 @@ end
 
 local files = {
   ["mods/alpha/manifest.json"] = manifest("alpha"),
-  -- mod.exports, not _G: a mod's globals are its own (src/mods/Sandbox.lua)
   ["mods/alpha/main.lua"] = [[
-return function(mod) mod.exports.storage = mod.storage end
+return function(mod) _G.MOD_STORAGE_ALPHA = mod.storage end
 ]],
   ["mods/beta/manifest.json"] = manifest("beta"),
   ["mods/beta/main.lua"] = [[
-return function(mod) mod.exports.storage = mod.storage end
+return function(mod) _G.MOD_STORAGE_BETA = mod.storage end
 ]],
 }
 local fs = memfs(files)
@@ -81,12 +80,12 @@ local current = game("red", "play-a")
 loader.game = current
 T.check(loader:load({}) == true, "storage fixture mods load")
 
-local alpha = (loader.exports.alpha or {}).storage
-local beta = (loader.exports.beta or {}).storage
+local alpha, beta = _G.MOD_STORAGE_ALPHA, _G.MOD_STORAGE_BETA
 T.check(type(alpha) == "table" and type(beta) == "table",
   "Loader exposes mod.storage through the public mod object")
 if type(alpha) ~= "table" or type(beta) ~= "table" then
   Runtime.events, Runtime.hooks = savedEvents, savedHooks
+  _G.MOD_STORAGE_ALPHA, _G.MOD_STORAGE_BETA = nil, nil
   T.finish()
 end
 
@@ -177,5 +176,6 @@ T.eq(next(emptyFiles), nil, "no-mod boot creates no storage paths or files")
 
 Runtime.events, Runtime.hooks = savedEvents, savedHooks
 Runtime.currentMod = nil
+_G.MOD_STORAGE_ALPHA, _G.MOD_STORAGE_BETA = nil, nil
 
 T.finish()

tests/modkit/cases/title_playthrough_context.lua

@@ -57,16 +57,13 @@ local files = {
   ["mods/probe/manifest.json"] =
     '{"id":"probe","name":"probe","version":"1.0.0",'
       .. '"entry":"main.lua","api":2,"profile":"content"}',
-  -- mod.exports, not _G: a mod's globals are its own (src/mods/Sandbox.lua)
   ["mods/probe/main.lua"] = [[
 return function(mod)
-  local out = mod.exports
-  out.storage = mod.storage
-  out.checkpoints = mod.checkpoints
-  out.restoreCount = 0
+  _G.MOD_TITLE_STORAGE = mod.storage
+  _G.MOD_TITLE_CHECKPOINTS = mod.checkpoints
   mod.events:on("checkpoint.restored", function(ev)
-    out.restoreCount = out.restoreCount + 1
-    out.restoreKind = ev.kind
+    _G.MOD_TITLE_RESTORE_COUNT = (_G.MOD_TITLE_RESTORE_COUNT or 0) + 1
+    _G.MOD_TITLE_RESTORE_KIND = ev.kind
   end)
 end
 ]],
@@ -85,8 +82,7 @@ local loader = Loader.new({ fs = fs })
 loader.game = active
 T.check(loader:load({}) == true, "title-context fixture mod loads")
 
-local probe = loader.exports.probe or {}
-local storage = probe.storage
+local storage = _G.MOD_TITLE_STORAGE
 T.check(type(storage) == "table", "loader exposes the public storage facade")
 if type(storage) == "table" then
   local written, writeCode, writeMessage = storage:write(active, "history/index", {
@@ -182,7 +178,7 @@ if type(storage) == "table" then
   end
 
   local runtime = makeRuntime(active.save, false)
-  local checkpoints = probe.checkpoints
+  local checkpoints = _G.MOD_TITLE_CHECKPOINTS
   T.check(type(checkpoints) == "table", "loader exposes the public checkpoint facade")
   local checkpoint = checkpoints and checkpoints:capture(runtime)
   T.check(type(checkpoint) == "table",
@@ -230,9 +226,9 @@ if type(storage) == "table" then
       "title bootstrap never rewrites the first normal save")
     T.same(checkpoints:capture(titleRuntime), checkpoint,
       "bootstrapped overworld differentially recaptures the selected checkpoint")
-    T.eq(probe.restoreCount, 1,
+    T.eq(_G.MOD_TITLE_RESTORE_COUNT, 1,
       "a successfully verified title resume emits checkpoint.restored exactly once")
-    T.eq(probe.restoreKind, "overworld",
+    T.eq(_G.MOD_TITLE_RESTORE_KIND, "overworld",
       "title resume lifecycle reports the reconstructed checkpoint kind")
 
     -- Force a failure after restoreCheckpointSave has already installed the
@@ -259,7 +255,7 @@ if type(storage) == "table" then
       version = "red", meta = { playthroughId = originalId },
     }, fs).savedAt, anchoredAt,
       "failed title reconstruction never rewrites the normal Pokémon save")
-    T.eq(probe.restoreCount, 1,
+    T.eq(_G.MOD_TITLE_RESTORE_COUNT, 1,
       "failed title reconstruction emits no additional restored lifecycle event")
   end
 
@@ -294,6 +290,10 @@ end
 
 Runtime.events, Runtime.hooks = savedEvents, savedHooks
 Runtime.currentMod = nil
+_G.MOD_TITLE_STORAGE = nil
+_G.MOD_TITLE_CHECKPOINTS = nil
+_G.MOD_TITLE_RESTORE_COUNT = nil
+_G.MOD_TITLE_RESTORE_KIND = nil
 SaveData.resetSlotState()
 SaveData.loadOptions = originalLoadOptions
 love.filesystem = realFs

tests/modkit_tests.lua

@@ -125,11 +125,8 @@ local hotFiles = {
   ["mods/hot_mod/main.lua"] = [[
 return function(mod)
   mod.content.pokemon:patch("FIXMON_A", { baseStats = { speed = 99 } })
-  -- counted on mod.exports, not _G: a mod's globals are its own
-  -- (src/mods/Sandbox.lua), and a reload gives it a fresh table
-  local out = mod.exports
   mod.events:on("game.ready", function()
-    out.ready = (out.ready or 0) + 1
+    _G.MODKIT_TEST_READY = (_G.MODKIT_TEST_READY or 0) + 1
   end)
 end
 ]],
@@ -151,6 +148,7 @@ local function freshHotData()
   return d
 end
 
+_G.MODKIT_TEST_READY = 0
 local hotData = freshHotData()
 local game = { data = hotData, save = { modData = {} } }
 local bootLoader = Loader.new({ fs = hotFs })
@@ -211,8 +209,7 @@ check(deepEqual(hotData.pokemon.FIXMON_B, fixture.load().pokemon.FIXMON_B),
   "untouched base record is byte-identical after reload")
 check(flushed >= 1, "reload flushed the registered caches")
 check(summary:find("reloaded 1 mods", 1, true) ~= nil, "reload summary counts")
-check((game.mods.exports.hot_mod or {}).ready >= 1,
-  "game.ready re-reaches re-subscribed mods")
+check(_G.MODKIT_TEST_READY >= 1, "game.ready re-reaches re-subscribed mods")
 ChipAudio.stopMusic = savedStopMusic
 check(musicStops >= 1, "reload stops chip music through the cache bus")
 Sound.play(beepData, "Fix_Beep")
@@ -231,6 +228,7 @@ local broken = HotReload.run(game, { fs = hotFs })
 check(#broken.errors > 0, "broken edit lands in the error feed")
 check(hotData.pokemon.FIXMON_A.baseStats.speed == 45,
   "broken mod rolls back to pristine base")
+_G.MODKIT_TEST_READY = nil
 
 -- ------- dev console: repl, verbs, tracer, input isolation