Merge branch 'main' into bugsquashingjuly26

* new launcher and save converts and pipeline

* fixing bugs

.github/workflows/release.yml

@@ -214,8 +214,21 @@ jobs:
           apk="$(find dist/android/debug -name '*.apk' | head -1)"
           [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
           cp "$apk" "$outdir/gen1recomp-${v}-android.apk"
+
+          # 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"
+          [ -f "$love_file" ] || { echo "::error::$love_file not found (expected from scripts/build.sh)"; exit 1; }
+          cp "$love_file" "$outdir/gen1recomp-${v}.love"
+
           ls -lh "$outdir"
 
+          # Checksums for every staged release asset (sums file itself is
+          # written after this and named outside the gen1recomp-* glob, so it
+          # never lists itself).
+          (cd "$outdir" && shasum -a 256 gen1recomp-* > sha256sums.txt)
+          cat "$outdir/sha256sums.txt"
+
       - name: Publish GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
@@ -266,7 +279,9 @@ jobs:
             "dist/release/gen1recomp-${v}-macos.zip" \
             "dist/release/gen1recomp-${v}-windows.zip" \
             "dist/release/gen1recomp-${v}-linux.zip" \
-            "dist/release/gen1recomp-${v}-android.apk"
+            "dist/release/gen1recomp-${v}-android.apk" \
+            "dist/release/gen1recomp-${v}.love" \
+            "dist/release/sha256sums.txt"
 
           echo "Published release $tag"
 

assets/touch/README.md

@@ -0,0 +1,9 @@
+# On-screen touch control art
+
+From Xelu's "Free Controller & Keyboard Prompts" pack (Nicolae Berbece /
+Those Awesome Guys), public domain under CC0:
+https://thoseawesomeguys.com/prompts/
+
+256px Nintendo Switch set, renamed for src/core/TouchControls.lua:
+d-pad (neutral + per-direction highlight), A, B, plus (START) and
+minus (SELECT).

conf.lua

@@ -47,8 +47,9 @@ function love.conf(t)
     -- freely to portrait or landscape), otherwise locked to the window's w/h
     -- aspect.  So a non-resizable tall window forced portrait; resizable lets
     -- the game follow the device.  The renderer letterboxes the 160x144
-    -- viewport into whatever size results, and touch input is gesture-based,
-    -- so both orientations just work.  iOS follows the Info.plist orientations
+    -- viewport into whatever size results, and the on-screen touch controls
+    -- re-lay themselves out from the new window size, so both orientations
+    -- just work.  iOS follows the Info.plist orientations
     -- (see mobile/ios/overlays/love-ios.plist, now portrait + landscape).
     t.window.resizable = true
     -- Starting size is a tall portrait hint; the OS resizes to the real

data/scripts/flavor/copycats_house_2f.lua

@@ -1,9 +1,8 @@
 -- Flavor talk scripts for CopycatsHouse2F (registry id COPYCATS_HOUSE_2F).
 -- Source: pokered/scripts/CopycatsHouse2F.asm, pokered/text/CopycatsHouse2F.asm
 --
--- TEXT_COPYCATSHOUSE2F_COPYCAT is already ported (with the POKE DOLL /
--- TM31 MIMIC trade) in data/scripts/story4.lua, so it is intentionally
--- omitted here.
+-- TEXT_COPYCATSHOUSE2F_COPYCAT (POKE DOLL -> TM31 MIMIC) lives in
+-- data/scripts/story4.lua.
 
 return {
   COPYCATS_HOUSE_2F = {

data/scripts/oaks_lab.lua

@@ -6,7 +6,8 @@
 --   takes it ("I'll take this one, then!") and both balls disappear.
 --   Source: scripts/OaksLab.asm OaksLabCharmanderPokeBallText /
 --   OaksLabRivalTakePokeBallScript.
--- * Rival (object 1): before starter -> "gramps isn't around"; with
+-- * Rival (object 1): before starter -> "go ahead and choose" once Oak
+--   has walked you in, else "gramps isn't around" (#218); with
 --   starter -> taunt + battle OPP_RIVAL1 with the counter-pick party
 --   (player Bulbasaur -> rival Charmander etc., parties 1/2/3 =
 --   Squirtle/Bulbasaur/Charmander in data/trainers/parties.asm);
@@ -59,52 +60,97 @@ end
 
 return {
   talk = {
-    -- Oak: accepts the parcel and hands over the Pokédex, then (once the
-    -- player has beaten the Route 22 rival) hands over the real POKé
-    -- BALLs (scripts/OaksLab.asm OaksLabOak1Text, simplified: no rival
-    -- recall / dex-rating / "pokemon can fight" / "around the world"
-    -- branches -- see docs/known-differences.md)
+    -- Oak: OaksLabOak1Text.  Parcel delivery kicks SCRIPT_OAKSLAB_RIVAL_
+    -- ARRIVES_AT_OAKS_REQUEST + OaksLabOakGivesPokedexScript (rival walk-
+    -- in, full Pokédex speech, rival exit, Route 22 arm).  Dex-rating
+    -- (DisplayDexRating) is still skipped.
     TEXT_OAKSLAB_OAK1 = {
-      { "face_player" },                                          -- 1
-      { "check_flag", "EVENT_GOT_OAKS_PARCEL" },                  -- 2
-      { "jump_if_false", 16 },                                    -- 3
-      { "check_flag", "EVENT_OAK_GOT_PARCEL" },                   -- 4
-      { "jump_if_true", 16 },                                     -- 5
-      { "show_text", "_OaksLabOak1DeliverParcelText" },           -- 6
-      { "take_item", "OAKS_PARCEL", 1 },                          -- 7
-      { "set_flag", "EVENT_OAK_GOT_PARCEL" },                     -- 8
-      { "show_text", "_OaksLabOak1PokemonAroundTheWorldText" },   -- 9
-      { "set_flag", "EVENT_GOT_POKEDEX" },                        -- 10
-      -- OaksLab.asm OakGivesPokedex: HideObject TOGGLE_POKEDEX_1/2
-      -- so the table sprites leave with the gift (#106).
-      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },          -- 11
-      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },          -- 12
-      -- the Pokédex swaps Viridian's two old men (OaksLab.asm:602-606:
-      -- HideObject TOGGLE_LYING_OLD_MAN / ShowObject TOGGLE_OLD_MAN).
-      -- Until this ran, the walking man at (17,5) -- who owns the coffee
-      -- ask and the catch tutorial -- stayed OFF for the whole game
-      -- (toggleable_objects.asm seeds him OFF, the sleeper ON).
-      { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" }, -- 13
-      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN" },  -- 14
-      { "jump", "end" },                                          -- 15
-      { "check_flag", "EVENT_GOT_STARTER" },                      -- 16
-      { "jump_if_false", 31 },                                    -- 17
-      { "check_item", "POKE_BALL" },                              -- 18
-      { "jump_if_true", 29 },                                     -- 19
-      { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },    -- 20
-      { "jump_if_false", 33 },                                    -- 21
-      { "check_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },           -- 22
-      { "jump_if_true", 29 },                                     -- 23
-      { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },             -- 24
-      { "give_item", "POKE_BALL", 5, false },                     -- 25
-      { "show_text", "_OaksLabOak1ReceivedPokeballsText" },       -- 26
-      { "show_text", "_OaksLabGivePokeballsExplanationText" },    -- 27
-      { "jump", "end" },                                          -- 28
-      { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },      -- 29
-      { "jump", "end" },                                          -- 30
-      { "show_text", "_OaksLabOak1WhichPokemonDoYouWantText" },   -- 31
-      { "jump", "end" },                                          -- 32
-      { "show_text", "_OaksLabOak1RaiseYourYoungPokemonText" },   -- 33
+      { "face_player" },
+      { "check_item", "POKE_BALL" },
+      { "jump_if_true", "come_see" },
+      { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },
+      { "jump_if_true", "give_balls" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_true", "around_world" },
+      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },
+      { "jump_if_false", "pre_lab_battle" },
+      { "check_item", "OAKS_PARCEL" },
+      { "jump_if_false", "raise_young" },
+      -- OaksLabOak1Text.got_parcel → RivalArrives + OakGivesPokedex
+      { "show_text", "_OaksLabOak1DeliverParcelText" },
+      { "play_sound", "Get_Key_Item" },
+      { "show_text", "_OaksLabOak1ParcelThanksText" },
+      { "take_item", "OAKS_PARCEL", 1 },
+      { "stop_music" },
+      { "play_music", "Music_MeetRival" },
+      { "show_text", "_OaksLabRivalGrampsText" },
+      { "show_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
+      -- OaksLabCalcRivalMovementScript: sprite map (8,11) → cell (4,7)
+      -- when the player stands below Oak (the usual desk talk).
+      { "place_npc", 1, 4, 7, "up" },
+      { "move_npc_to", 1, 4, 3 },
+      { "play_music", "Music_OaksLab" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabRivalWhatDidYouCallMeForText" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakIHaveARequestText" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "show_text", "_OaksLabOakGotPokedexText" },
+      { "play_sound", "Get_Key_Item" },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
+      { "face_object", 1, "up" },
+      { "face_object", 5, "down" },
+      { "show_text", "_OaksLabOakThatWasMyDreamText" },
+      { "face_object", 1, "right" },
+      { "show_text", "_OaksLabRivalLeaveItAllToMeText" },
+      { "set_flag", "EVENT_GOT_POKEDEX" },
+      { "set_flag", "EVENT_OAK_GOT_PARCEL" },
+      { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" },
+      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN" },
+      { "stop_music" },
+      { "play_music", "Music_MeetRival" },
+      { "move_npc_to", 1, 4, 7 },
+      { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
+      { "play_music", "Music_OaksLab" },
+      { "set_flag", "EVENT_1ST_ROUTE22_RIVAL_BATTLE" },
+      { "clear_flag", "EVENT_2ND_ROUTE22_RIVAL_BATTLE" },
+      { "set_flag", "EVENT_ROUTE22_RIVAL_WANTS_BATTLE" },
+      { "show_object", "ROUTE_22", "ROUTE22_RIVAL1" },
+      { "jump", "end" },
+
+      { "label", "raise_young" },
+      { "show_text", "_OaksLabOak1RaiseYourYoungPokemonText" },
+      { "jump", "end" },
+
+      { "label", "pre_lab_battle" },
+      { "check_flag", "EVENT_GOT_STARTER" },
+      { "jump_if_true", "can_fight" },
+      { "show_text", "_OaksLabOak1WhichPokemonDoYouWantText" },
+      { "jump", "end" },
+      { "label", "can_fight" },
+      { "show_text", "_OaksLabOak1YourPokemonCanFightText" },
+      { "jump", "end" },
+
+      { "label", "around_world" },
+      { "show_text", "_OaksLabOak1PokemonAroundTheWorldText" },
+      { "jump", "end" },
+
+      { "label", "give_balls" },
+      { "check_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
+      { "jump_if_true", "come_see" },
+      { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
+      { "give_item", "POKE_BALL", 5, false },
+      { "show_text", "_OaksLabOak1ReceivedPokeballsText" },
+      { "show_text", "_OaksLabGivePokeballsExplanationText" },
+      { "jump", "end" },
+
+      { "label", "come_see" },
+      { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },
     },
 
     TEXT_OAKSLAB_CHARMANDER_POKE_BALL =
@@ -117,36 +163,45 @@ return {
       starterBall("_OaksLabYouWantBulbasaurText", "BULBASAUR", "EVENT_CHOSE_BULBASAUR",
                   "OAKSLAB_BULBASAUR_POKE_BALL", 6, "OAKSLAB_CHARMANDER_POKE_BALL"),
 
+    -- Talking to the rival only ever prints a line: the lab battle is a
+    -- coordinate trigger (OaksLabRivalChallengesPlayerScript, wYCoord == 6;
+    -- see onStep below), never a talk action.  The handler used to fall
+    -- through from the "looks stronger" taunt straight into start_battle,
+    -- so talking to Blue at the table launched the rival fight before the
+    -- player ever stepped onto the trigger (#219).  scripts/OaksLab.asm
+    -- OaksLabText8 branches text only:
+    --   * got starter, not yet battled -> _OaksLabRivalMyPokemonLooksStronger
+    --   * already battled -> _OaksLabRivalFedUpWithWaitingText (a Route 22
+    --     line; normally unreachable since the rival is hidden after the
+    --     lab battle in OaksLabRivalEndBattleScript)
+    --   * no starter yet -> the FOLLOWED_OAK pre-starter fork (#218)
     TEXT_OAKSLAB_RIVAL = {
-      { "face_player" },                                          -- 1
-      { "check_flag", "EVENT_GOT_STARTER" },                      -- 2
-      { "jump_if_false", 21 },                                    -- 3
-      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },        -- 4
-      { "jump_if_true", 19 },                                     -- 5
-      { "show_text", "_OaksLabRivalMyPokemonLooksStrongerText" }, -- 6
-      { "check_flag", "EVENT_CHOSE_BULBASAUR" },                  -- 7
-      { "jump_if_false", 11 },                                    -- 8
-      { "start_battle", "trainer", "OPP_RIVAL1", 3 },             -- 9  Charmander
-      { "jump", 16 },                                             -- 10
-      { "check_flag", "EVENT_CHOSE_SQUIRTLE" },                   -- 11
-      { "jump_if_false", 15 },                                    -- 12
-      { "start_battle", "trainer", "OPP_RIVAL1", 2 },             -- 13 Bulbasaur
-      { "jump", 16 },                                             -- 14
-      { "start_battle", "trainer", "OPP_RIVAL1", 1 },             -- 15 Squirtle
-      -- OaksLabRivalEndBattleScript: HealParty + flag, then exit either way
-      { "heal_party" },                                           -- 16
-      { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },          -- 17
-      { "jump", 23 },                                             -- 18
-      { "show_text", "_OaksLabRivalFedUpWithWaitingText" },       -- 19
-      { "jump", "end" },                                          -- 20
-      { "show_text", "_OaksLabRivalGrampsIsntAroundText" },       -- 21
-      { "jump", "end" },                                          -- 22
-      -- win: sulk text then exit; loss: Rival1WinText already played in
-      -- battle (HandlePlayerBlackOut), so skip straight to the walk-out
-      { "jump_if_false", 25 },                                    -- 23
-      { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" }, -- 24
-      { "move_npc_to", 1, 4, 11 },                                -- 25
-      { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" },             -- 26
+      { "face_player" },
+      { "check_flag", "EVENT_GOT_STARTER" },
+      { "jump_if_false", "pre_starter" },
+      { "check_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" },
+      { "jump_if_true", "after_battle" },
+      -- has a starter, has not fought yet: just the taunt.  The battle is
+      -- the coordinate trigger in onStep, not this talk (#219)
+      { "show_text", "_OaksLabRivalMyPokemonLooksStrongerText" },
+      { "jump", "end" },
+
+      { "label", "after_battle" },
+      { "show_text", "_OaksLabRivalFedUpWithWaitingText" },
+      { "jump", "end" },
+
+      -- pre-starter fork (scripts/OaksLab.asm OaksLabText8 rival handler):
+      -- Oak has already escorted you in (three balls on the table) -> he
+      -- waves you on to choose; not yet escorted (very early game) -> the
+      -- "Gramps isn't around" line.  #218
+      { "label", "pre_starter" },
+      { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB" },
+      { "jump_if_false", "gramps_gone" },
+      { "show_text", "_OaksLabRivalGoAheadAndChooseText" },
+      { "jump", "end" },
+
+      { "label", "gramps_gone" },
+      { "show_text", "_OaksLabRivalGrampsIsntAroundText" },
     },
   },
 
@@ -168,9 +223,16 @@ return {
   -- OaksLabScript8 / OaksLabRivalChallenge)
   onStep = function(game, ow, x, y)
     local flags = game.save.flags
-    -- Oak blocks the exit mats (4,11)/(5,11) until you take a starter
+    -- Oak stops you leaving without a starter at the bookshelf row (cell
+    -- y == 6): this is the same wYCoord == 6 coordinate script the rival
+    -- challenge just below uses (scripts/OaksLab.asm, both gated on
+    -- EVENT_GOT_STARTER), so Oak halts you level with the shelves, not one
+    -- corridor length later on the exit mat.  At y>=6 only the x=4,5
+    -- corridor is walkable and the up-push keeps the player above y=7, so
+    -- this only ever fires at y=6 in the corridor -- matching the rival
+    -- trigger's shape. (#232)
     if flags.EVENT_FOLLOWED_OAK_INTO_LAB and not flags.EVENT_GOT_STARTER
-       and y == 11 and (x == 4 or x == 5) then
+       and y >= 6 then
       ow.runner:run({
         { "show_text", "_OaksLabOakDontGoAwayYetText" },
         { "move_player", "up", 1 },
@@ -209,10 +271,18 @@ return {
       -- OaksLabRivalEndBattleScript: heal + flag on win or loss; no blackout
       table.insert(rows, { "heal_party" })
       table.insert(rows, { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" })
-      -- win: sulk text then exit; loss jumps to the walk-out (taunt was
-      -- already shown in-battle via Rival1WinText)
+      -- OaksLabRivalEndBattleScript: on WIN, print the "picked the wrong
+      -- POKéMON!" gloat, then BOTH win and loss print the shared exit line
+      -- _OaksLabRivalSmellYouLaterText ("OK! I'll make my POKéMON fight to
+      -- toughen it up!\012<PLAYER>! Gramps! Smell you later!") before Blue
+      -- marches out.  A loss skips only the gloat (that taunt was already
+      -- shown in-battle via Rival1WinText), never the exit line (#231).  The
+      -- jump_if_false convergence point is the exit line: base+6 indexes the
+      -- SmellYouLater row below, so WIN falls IPicked -> SmellYouLater and
+      -- LOSS jumps straight to SmellYouLater (both then walk-out + hide).
       table.insert(rows, { "jump_if_false", base + 6 })
       table.insert(rows, { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
+      table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
       table.insert(rows, { "move_npc_to", 1, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
       ow.runner:run(rows, { npc = rival })

data/scripts/story.lua

@@ -395,7 +395,93 @@ M.SS_ANNE_CAPTAINS_ROOM = {
 -- MrFujisHouse.asm; the teleport back to his house is a warp)
 -- -------------------------------------------------------------------
 
+-- scripts/PokemonTower7F.asm: after each Rocket loses,
+-- PokemonTower7FEndBattleScript shows its EndBattle text (EndTrainerBattle),
+-- prints its AfterBattle text (DisplayTextID), then
+-- PokemonTower7FRocketLeaveMovementScript walks the grunt off toward the
+-- (9,16) stairs (MoveSprite) and PokemonTower7FHideNPCScript despawns it
+-- (HideObject).  Without this the beaten grunts stood in the corridor
+-- forever (#200).
+local POKEMON_TOWER_7F_ROCKETS = {
+  { index = 1, name = "POKEMONTOWER7F_ROCKET1",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_0",
+    after = "_PokemonTower7FRocket1AfterBattleText" },
+  { index = 2, name = "POKEMONTOWER7F_ROCKET2",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_1",
+    after = "_PokemonTower7FRocket2AfterBattleText" },
+  { index = 3, name = "POKEMONTOWER7F_ROCKET3",
+    beat = "EVENT_BEAT_POKEMONTOWER_7_TRAINER_2",
+    after = "_PokemonTower7FRocket3AfterBattleText" },
+}
+
+-- PokemonTower7FNPCCoordMovementTable, keyed by the PLAYER's tile ("x,y")
+-- at the engagement (both the talk and the sight walk-up leave the player on
+-- the tile the vanilla table indexes).  Each list is that entry's
+-- NPC_MOVEMENT_* exit, applied from the grunt's current tile.  The exact
+-- tables are one per grunt (dbmapcoord bytes decoded back to x,y).
+local POKEMON_TOWER_7F_EXITS = {
+  [1] = { -- ROCKET1 @ (9,11), faces RIGHT
+    ["9,12"]  = { "right", "down", "down", "down", "down", "down", "left" },
+    ["10,11"] = { "down", "right", "down", "down", "down", "down" },
+    ["11,11"] = { "down", "down", "down", "down", "down" },
+    ["12,11"] = { "down", "down", "down", "down", "down" },
+  },
+  [2] = { -- ROCKET2 @ (12,9), faces LEFT
+    ["12,10"] = { "left", "down", "down", "down", "down", "down", "down" },
+    ["11,9"]  = { "down", "down", "down", "left", "down", "down" },
+    ["10,9"]  = { "down", "down", "down", "down", "down" },
+    ["9,9"]   = { "down", "down", "down", "down", "down" },
+  },
+  [3] = { -- ROCKET3 @ (9,7), faces RIGHT
+    ["9,8"]  = { "right", "down", "down", "down", "down", "down", "down" },
+    ["10,7"] = { "down", "down", "down", "down", "down" },
+    ["11,7"] = { "down", "down", "down", "down", "down" },
+    ["12,7"] = { "down", "down", "down", "down", "down" },
+  },
+}
+-- The vanilla table only lists the sight/talk tiles the map geometry allows;
+-- a plain down-walk keeps any other engagement tile (e.g. talking from the
+-- side) safe -- it still clears the corridor and despawns the grunt.
+local POKEMON_TOWER_7F_EXIT_FALLBACK =
+  { "down", "down", "down", "down", "down" }
+
 M.POKEMON_TOWER_7F = {
+  -- Repair saves that beat a grunt before the exit walk was ported: in
+  -- vanilla HideObject persists (wMissableObjectFlags), so a beaten grunt is
+  -- still gone on re-entry.  hide_object below writes objectToggles for new
+  -- wins; this hides any grunt whose BEAT flag is already set.
+  onEnter = function(game, ow)
+    local Commands = require("src.script.Commands")
+    local ctx = { game = game, save = game.save, overworld = ow }
+    for _, r in ipairs(POKEMON_TOWER_7F_ROCKETS) do
+      if game.save.flags[r.beat] then
+        Commands.hide_object(ctx, "POKEMON_TOWER_7F", r.name)
+      end
+    end
+  end,
+  -- runVictoryHook fires after every trainer win on the map (both the sight
+  -- and talk paths route through engageTrainer -> checkVictoryRewards), so
+  -- this walks off whichever grunt was just beaten but is still standing.
+  -- The AfterBattle text + walk queue UNDER the EndBattle box engageTrainer
+  -- pushes right after, giving the vanilla order: EndBattle, AfterBattle,
+  -- walk, despawn.
+  onVictory = function(game, ow)
+    if ow.runner:isRunning() then return end
+    for _, r in ipairs(POKEMON_TOWER_7F_ROCKETS) do
+      local npc = ow:npcByIndex(r.index)
+      if npc and game.save.flags[r.beat] then
+        local key = ow.player.cellX .. "," .. ow.player.cellY
+        local dirs = (POKEMON_TOWER_7F_EXITS[r.index] or {})[key]
+                     or POKEMON_TOWER_7F_EXIT_FALLBACK
+        ow.runner:run({
+          { "show_text", r.after },                       -- DisplayTextID
+          { "walk_npc", r.index, dirs },                  -- MoveSprite
+          { "hide_object", "POKEMON_TOWER_7F", r.name },  -- HideObject
+        }, { npc = npc })
+        return
+      end
+    end
+  end,
   talk = {
     TEXT_POKEMONTOWER7F_MR_FUJI = {
       { "face_player" },                                  -- 1
@@ -878,16 +964,23 @@ M.HALL_OF_FAME = {
 
 M.CERULEAN_CITY = {
   talk = {
+    -- CeruleanCityRivalText: Bill line once beaten; pre-battle otherwise.
+    -- Post-fight walk matches CeruleanCityMovement4 (right then into town).
     TEXT_CERULEANCITY_RIVAL = {
-      { "face_player" },                                    -- 1
-      { "check_flag", "EVENT_BEAT_CERULEAN_RIVAL" },        -- 2
-      { "jump_if_true", 9 },                                -- 3
-      { "show_text", "_CeruleanCityRivalPreBattleText" },   -- 4
-      { "rival_battle", "OPP_RIVAL1", 7 },                  -- 5
-      { "jump_if_false", 10 },                              -- 6
-      { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },          -- 7
-      { "show_text", "_CeruleanCityRivalDefeatedText" },    -- 8
-      { "jump", 10 },                                       -- 9
+      { "face_player" },                                         -- 1
+      { "check_flag", "EVENT_BEAT_CERULEAN_RIVAL" },             -- 2
+      { "jump_if_true", 13 },                                    -- 3
+      { "show_text", "_CeruleanCityRivalPreBattleText" },        -- 4
+      { "rival_battle", "OPP_RIVAL1", 7 },                       -- 5
+      { "jump_if_false", "end" },                                -- 6
+      { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },               -- 7
+      { "show_text", "_CeruleanCityRivalDefeatedText" },         -- 8
+      { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 9
+      { "walk_npc", 1, { "right", "down", "down", "down",
+                         "down", "down", "down" } },             -- 10
+      { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 11
+      { "jump", "end" },                                         -- 12
+      { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 13
     },
   },
 }

data/scripts/story2.lua

@@ -445,33 +445,67 @@ local function engageSuperNerd(game, ow, onDone)
   ow:engageTrainer(nerd, onDone)
 end
 
-local function mtMoonFossil(itemId, otherName)
+-- MtMoonB2FMoveSuperNerdScript: player-near-dome coords walk RIGHT then
+-- UP (MoveRight falls through into MoveUp); near-helix walks UP only.
+local function mtMoonNerdWalk(px, py, itemId)
+  if (px == 12 and py == 7) or (px == 11 and py == 6) or (px == 12 and py == 5) then
+    return { "right", "up" }
+  end
+  if (px == 13 and py == 7) or (px == 14 and py == 6) or (px == 14 and py == 5) then
+    return { "up" }
+  end
+  return (itemId == "DOME_FOSSIL") and { "right", "up" } or { "up" }
+end
+
+-- scripts/MtMoonB2F.asm Dome/Helix fossil text_asm + MoveSuperNerd +
+-- SuperNerdTakesOtherFossil: pick one, hide it, walk the nerd to the
+-- other, "All right. Then this is mine!", hide the other.
+local function mtMoonFossil(itemId, otherName, gotFlag)
   return function(game, ow, npc, done)
     local TextBox = require("src.render.TextBox")
-    local ChoiceBox = require("src.ui.ChoiceBox")
-    if game.save.flags.EVENT_GOT_A_FOSSIL then
-      game.stack:push(TextBox.new(game, "You already took\na fossil.", done))
+    local t = game.data.text
+    local flags = game.save.flags
+    if flags.EVENT_GOT_DOME_FOSSIL or flags.EVENT_GOT_HELIX_FOSSIL then
+      done()
       return
     end
-    -- can't grab a fossil until the Super Nerd is beaten -- he intercepts
     if not superNerdBeaten(ow) then
       engageSuperNerd(game, ow, done)
       return
     end
-    local name = game.data.items[itemId].name
-    game.stack:push(TextBox.new(game, ("You want the\n%s?"):format(name), function()
-      game.stack:push(ChoiceBox.new(game, function(yes)
-        if not yes then done() return end
-        game.save.inventory[itemId] = 1
-        game.save.flags.EVENT_GOT_A_FOSSIL = true
-        local Commands = require("src.script.Commands")
-        local ctx = { save = game.save, overworld = ow, game = game }
-        Commands.hide_object(ctx, "MT_MOON_B2F", npc.def.name)
-        Commands.hide_object(ctx, "MT_MOON_B2F", otherName)
+    local want = (itemId == "DOME_FOSSIL")
+      and (t._MtMoonB2FDomeFossilYouWantText or "You want the\nDOME FOSSIL?")
+      or (t._MtMoonB2FHelixFossilYouWantText or "You want the\nHELIX FOSSIL?")
+    game.stack:push(TextBox.new(game, want, nil, { choice = function(yes)
+      if not yes then done() return end
+      if not require("src.inventory.Bag").add(game.save, itemId, 1) then
         game.stack:push(TextBox.new(game,
-          ("%s got the\n%s!"):format(game.save.player.name, name), done))
-      end))
-    end))
+          t._MtMoonB2FYouHaveNoRoomText or "Look, you've got\nno room for this.",
+          done))
+        return
+      end
+      local idef = game.data.items[itemId]
+      game.stringBuffer = idef and idef.name or itemId
+      require("src.core.Sound").play(game.data, "Get_Key_Item")
+      local dirs = mtMoonNerdWalk(ow.player.cellX, ow.player.cellY, itemId)
+      game.stack:push(TextBox.new(game,
+        t._MtMoonB2FReceivedFossilText
+          or ("{PLAYER} got the\n" .. game.stringBuffer .. "!"),
+        function()
+          local Commands = require("src.script.Commands")
+          Commands.hide_object(
+            { save = game.save, overworld = ow, game = game },
+            "MT_MOON_B2F", npc.def.name)
+          flags[gotFlag] = true
+          ow.runner:run({
+            { "walk_npc", 1, dirs },
+            { "text_opts", { auto = true } },
+            { "show_text", "_MtMoonB2FSuperNerdThenThisIsMineText" },
+            { "play_sound", "Get_Key_Item" },
+            { "hide_object", "MT_MOON_B2F", otherName },
+          }, { onDone = done })
+        end))
+    end }))
   end
 end
 
@@ -486,13 +520,17 @@ M.MT_MOON_B2F = {
     return false
   end,
   talk = {
-    TEXT_MTMOONB2F_DOME_FOSSIL = mtMoonFossil("DOME_FOSSIL", "MTMOONB2F_HELIX_FOSSIL"),
-    TEXT_MTMOONB2F_HELIX_FOSSIL = mtMoonFossil("HELIX_FOSSIL", "MTMOONB2F_DOME_FOSSIL"),
+    TEXT_MTMOONB2F_DOME_FOSSIL = mtMoonFossil(
+      "DOME_FOSSIL", "MTMOONB2F_HELIX_FOSSIL", "EVENT_GOT_DOME_FOSSIL"),
+    TEXT_MTMOONB2F_HELIX_FOSSIL = mtMoonFossil(
+      "HELIX_FOSSIL", "MTMOONB2F_DOME_FOSSIL", "EVENT_GOT_HELIX_FOSSIL"),
   },
 }
 
 -- The ticket clerk (scripts/Museum1F.asm Museum1FScientist1Text):
--- Y50, once; declining at the rope walks you back out.
+-- Y50, once.  Declining at the rope shoves the player one tile SOUTH back off
+-- the exhibit rope they crossed heading north (#151); the museum floor has no
+-- ledges, so a plain scriptMove("down",1) is the correct primitive.
 local function museumClerk(game, ow, done, onDecline)
   local TextBox = require("src.render.TextBox")
   local ChoiceBox = require("src.ui.ChoiceBox")
@@ -527,7 +565,7 @@ M.MUSEUM_1F = {
     if y == 4 and (x == 9 or x == 10)
        and not game.save.flags.EVENT_BOUGHT_MUSEUM_TICKET then
       museumClerk(game, ow, nil, function()
-        ow:scriptMove(ow.player, "right", 1)
+        ow:scriptMove(ow.player, "down", 1)
       end)
       return true
     end
@@ -822,6 +860,10 @@ M.DAYCARE = {
               if def then
                 mon.stats = Stats.calc(def, mon.level, mon.dvs, mon.statExp)
                 mon.hp = mon.stats.hp
+                -- Daycare.asm: WriteMonMoves with wLearningMovesFromDayCare
+                local Pokemon = require("src.pokemon.Pokemon")
+                Pokemon.learnMovesFromDayCare(
+                  game.data, mon, def, startLevel, newLevel)
               end
               table.insert(game.save.party, mon)
               game.save.daycare = nil

data/scripts/story3.lua

@@ -524,8 +524,17 @@ M.GAME_CORNER = {
           game.data.text._GameCornerRocketAfterBattleText
           or "Our hideout might\nbe discovered! I\nbetter tell BOSS!",
           function()
-            hideRocket()
-            done()
+            -- #198: GameCornerRocketExitScript (scripts/GameCorner.asm)
+            -- ApplyMovementData walks the grunt one tile UP into the poster
+            -- (the hideout's secret entrance at 9,4) before HideObject, so
+            -- he leaves the floor rather than popping out of existence on
+            -- (9,5).  scriptMove locks player input (#scriptMoves>0) and
+            -- ignores collision, so we despawn + unfreeze (done) only once
+            -- the step lands.
+            ow:scriptMove(npc, "up", 1, function()
+              hideRocket()
+              done()
+            end)
           end))
       end)
     end,
@@ -606,40 +615,62 @@ local function activePrizes()
   return require("src.core.GameVersion").isBlue() and BLUE_PRIZES or RED_PRIZES
 end
 
+-- Prize counters (engine/menus/prize_menu.asm CeladonPrizeMenu; the prize
+-- list itself is data/events/prizes.asm, prize_mon_levels.asm).  Gen1 gates
+-- the prize window on the COIN CASE: it does IsItemInBag COIN_CASE first, and
+-- with no case prints RequireCoinCaseText and returns without ever opening a
+-- window; only with the case does it print ExchangeCoinsForPrizesText and then
+-- show the prizes.  #194: the port used to open the window unconditionally and
+-- skip both text boxes.
 local function prizeCounter(game, ow, npc, done)
   local ListMenu = require("src.ui.ListMenu")
   local Commands = require("src.script.Commands")
-  local items = {}
-  for _, p in ipairs(activePrizes()) do
-    local label
-    if p.kind == "mon" then
-      label = ("%s L%d"):format(game.data.pokemon[p.species].name, p.level)
-    else
-      label = game.data.items[p.item].name
-    end
-    table.insert(items, { label = label, right = tostring(p.cost), value = p })
+  local TextBox = require("src.render.TextBox")
+  local t = game.data.text
+  -- IsItemInBag COIN_CASE: without the case, deny and open no window
+  -- (COIN_CASE is a numeric count in save.inventory, nil when absent).
+  if not game.save.inventory.COIN_CASE then
+    game.stack:push(TextBox.new(game,
+      t._RequireCoinCaseText or "A COIN CASE is\nrequired!", done))
+    return
   end
-  local list
-  list = ListMenu.new(game, "PRIZES (COINS)", items, {
-    footer = ("COINS %d"):format(game.save.coins or 0),
-    onChoose = function(item)
-      local p = item.value
-      if (game.save.coins or 0) < p.cost then
-        list.footer = "Not enough coins!"
-        return
+  -- ExchangeCoinsForPrizesText plays before the prize window opens.
+  game.stack:push(TextBox.new(game,
+    t._ExchangeCoinsForPrizesText or "We exchange your\ncoins for prizes.",
+    function()
+      local items = {}
+      for _, p in ipairs(activePrizes()) do
+        local label
+        if p.kind == "mon" then
+          label = ("%s L%d"):format(game.data.pokemon[p.species].name, p.level)
+        else
+          label = game.data.items[p.item].name
+        end
+        table.insert(items,
+          { label = label, right = tostring(p.cost), value = p })
       end
-      game.save.coins = game.save.coins - p.cost
-      if p.kind == "mon" then
-        Commands.give_pokemon({ save = game.save, game = game },
-                              p.species, p.level)
-      else
-        game.save.inventory[p.item] = (game.save.inventory[p.item] or 0) + 1
-      end
-      list.footer = ("Got it! COINS %d"):format(game.save.coins)
-    end,
-    onCancel = done,
-  })
-  game.stack:push(list)
+      local list
+      list = ListMenu.new(game, "PRIZES (COINS)", items, {
+        footer = ("COINS %d"):format(game.save.coins or 0),
+        onChoose = function(item)
+          local p = item.value
+          if (game.save.coins or 0) < p.cost then
+            list.footer = "Not enough coins!"
+            return
+          end
+          game.save.coins = game.save.coins - p.cost
+          if p.kind == "mon" then
+            Commands.give_pokemon({ save = game.save, game = game },
+                                  p.species, p.level)
+          else
+            game.save.inventory[p.item] = (game.save.inventory[p.item] or 0) + 1
+          end
+          list.footer = ("Got it! COINS %d"):format(game.save.coins)
+        end,
+        onCancel = done,
+      })
+      game.stack:push(list)
+    end))
 end
 
 M.GAME_CORNER_PRIZE_ROOM = {

data/scripts/story4.lua

@@ -134,12 +134,19 @@ M.MT_MOON_POKECENTER = {
 -- Karate Master, take HITMONLEE or HITMONCHAN (the other disappears)
 -- -------------------------------------------------------------------
 
+-- ownBall/otherBall keep their spots for signature symmetry; only ownBall
+-- is ever hidden (Gen1 removes just the chosen ball).
 local function dojoBall(species, ownBall, otherBall, askKey)
   return function(game, ow, npc, done)
     local t = text(game)
     local flags = game.save.flags
+    -- Already took one prize: the OTHER ball is still on the mat, so
+    -- talking to it now gives the "Better not get greedy..." refusal
+    -- (FightingDojo.asm .gotThePokemon / _FightingDojoBetterNotGetGreedyText),
+    -- not a silent no-op (#197).
     if flags.EVENT_GOT_HITMONLEE or flags.EVENT_GOT_HITMONCHAN then
-      done()
+      push(game, t._FightingDojoBetterNotGetGreedyText
+        or "Better not get\ngreedy...", done)
       return
     end
     if not flags.EVENT_BEAT_KARATE_MASTER then
@@ -153,8 +160,10 @@ local function dojoBall(species, ownBall, otherBall, askKey)
       local Commands = require("src.script.Commands")
       local ctx = { save = game.save, game = game, overworld = ow }
       Commands.give_pokemon(ctx, species, 30)
+      -- Hide ONLY the chosen ball; the other stays (FightingDojo.asm hides
+      -- just the picked object's index) and routes to the greedy line above
+      -- when talked to (#197).
       Commands.hide_object(ctx, "FIGHTING_DOJO", ownBall)
-      Commands.hide_object(ctx, "FIGHTING_DOJO", otherBall)
       push(game, ("%s got\n%s!"):format(game.save.player.name, species), done)
     end)
   end
@@ -171,6 +180,21 @@ M.FIGHTING_DOJO = {
                "FIGHTINGDOJO_HITMONLEE_POKE_BALL",
                "_FightingDojoHitmonchanPokeBallText"),
   },
+  -- The two dojo posters on the north wall (FightingDojo.asm bg_events at
+  -- the top of the room, cells (4,0)/(5,0) directly above the prize balls)
+  -- print _EnemiesOnEverySideText.  The map extractor dropped the dojo
+  -- bg_events (signs = {}), so wire the poster read here, the same
+  -- facing-up + coord shape the mansion switches use.  Reachable only once
+  -- a claimed prize frees the ball cell below the poster (#197).
+  onInteract = function(game, ow, fx, fy)
+    if ow.player.facing ~= "up" then return false end
+    if fy == 0 and (fx == 4 or fx == 5) then
+      push(game, text(game)._EnemiesOnEverySideText
+        or "Enemies on every\nside!")
+      return true
+    end
+    return false
+  end,
 }
 
 -- -------------------------------------------------------------------
@@ -212,30 +236,31 @@ M.COPYCATS_HOUSE_2F = {
   talk = {
     TEXT_COPYCATSHOUSE2F_COPYCAT = function(game, ow, npc, done)
       local t = text(game)
+      local Bag = require("src.inventory.Bag")
       if game.save.flags.EVENT_GOT_TM31 then
-        push(game, t._CopycatsHouse2FCopycatWhirlingText
-          or "Huh? Huh? Huh?", done)
+        push(game, t._CopycatsHouse2FCopycatTM31Explanation2Text, done)
         return
       end
-      if (game.save.inventory.POKE_DOLL or 0) > 0 then
-        ask(game, t._CopycatsHouse2FCopycatPokeDollText
-          or "Oh wow!\nA POKé DOLL!\fFor me?\nCan I have it?", function(yes)
-          if not yes then done() return end
-          game.save.inventory.POKE_DOLL = game.save.inventory.POKE_DOLL - 1
-          if game.save.inventory.POKE_DOLL == 0 then
-            game.save.inventory.POKE_DOLL = nil
-          end
-          if not require("src.inventory.Bag").add(game.save, "TM_MIMIC", 1) then
-            push(game, "You don't have\nroom for TM31!", done)
+      -- Mimic line first; auto-trade POKE DOLL for TM31 (no YES/NO).
+      push(game, t._CopycatsHouse2FCopycatDoYouLikePokemonText, function()
+        if (game.save.inventory.POKE_DOLL or 0) <= 0 then
+          done()
+          return
+        end
+        push(game, t._CopycatsHouse2FCopycatTM31PreReceiveText, function()
+          if not Bag.add(game.save, "TM_MIMIC", 1) then
+            push(game, t._CopycatsHouse2FCopycatTM31NoRoomText, done)
             return
           end
+          game.stringBuffer = game.data.items.TM_MIMIC.name
+          require("src.core.Sound").play(game.data, "Get_Item1")
+          Bag.remove(game.save, "POKE_DOLL", 1)
           game.save.flags.EVENT_GOT_TM31 = true
-          push(game, ("%s got\nTM31!"):format(game.save.player.name), done)
+          push(game, t._CopycatsHouse2FCopycatReceivedTM31Text, function()
+            push(game, t._CopycatsHouse2FCopycatTM31Explanation1Text, done)
+          end)
         end)
-        return
-      end
-      push(game, t._CopycatsHouse2FCopycatText
-        or "I like to mimic\npeople!", done)
+      end)
     end,
   },
 }

data/scripts/story5.lua

@@ -196,14 +196,24 @@ local function inCoords(coords, x, y)
   return false
 end
 
--- coordinate block: show a line and push the player back one step
+-- coordinate block: show a line and shove the player back one step.  pokered
+-- shoves with a SIMULATED JOYPAD press (scripts/ViridianCity.asm ViridianCity-
+-- CheckGymOpenScript), which runs the normal overworld step pipeline including
+-- HandleLedges (engine/overworld/ledges.asm), so the shove must HOP a ledge
+-- when one sits in front: the tile below the Viridian Gym door is a down-ledge
+-- (#151).  Gates with no ledge in front (Cinnabar gym lock at (18,4)) get
+-- checkLedgeHop == false and fall back to the plain forced step, unchanged.
 local function stepGate(opts)
   return function(game, ow, x, y)
     if not inCoords(opts.coords, x, y) then return false end
     if not opts.blocked(game) then return false end
     require("src.core.Sound").play(game.data, "Denied")
-    push(game, text(game)[opts.text] or opts.fallback,
-         function() ow:scriptMove(ow.player, opts.push, 1) end)
+    push(game, text(game)[opts.text] or opts.fallback, function()
+      ow.player.facing = opts.push
+      if not ow:checkLedgeHop(opts.push) then
+        ow:scriptMove(ow.player, opts.push, 1)
+      end
+    end)
     return true
   end
 end
@@ -457,6 +467,19 @@ end
 -- EVENT_ROUTE22_RIVAL_WANTS_BATTLE in Oak's lab (expired by Pewter
 -- Gym) and again in Viridian Gym; we derive the same windows from the
 -- surrounding story flags so old saves work too.
+-- Rival1Exit → Viridian (right/down); Rival2Exit → League (left).
+local function route22ExitDirs(n, py)
+  if n == 2 then
+    if py == 5 then return { "left", "left", "left", "left" } end
+    return { "left", "left", "left" }
+  end
+  if py == 5 then
+    return { "right", "right", "down", "down", "down", "down", "down" }
+  end
+  return { "up", "right", "right", "right",
+           "down", "down", "down", "down", "down", "down" }
+end
+
 local function route22Scene(n, objIndex, objName, oppClass, baseParty, beatFlag, py)
   return {
     { "show_object", "ROUTE_22", objName },                    -- 1
@@ -468,7 +491,7 @@ local function route22Scene(n, objIndex, objName, oppClass, baseParty, beatFlag,
     { "set_flag", beatFlag },                                  -- 7
     { "show_text", "_Route22Rival" .. n .. "DefeatedText" },   -- 8
     { "show_text", "_Route22RivalAfterBattleText" .. n },      -- 9
-    { "move_npc_to", objIndex, 25, 5 },                        -- 10
+    { "walk_npc", objIndex, route22ExitDirs(n, py) },          -- 10
     { "hide_object", "ROUTE_22", objName },                    -- 11
   }
 end
@@ -495,6 +518,14 @@ M.ROUTE_22 = {
 -- Cerulean City: the Nugget Bridge rival ambush (CeruleanCityCoords2),
 -- the TM28 rocket thief with his forced-fight cells (Coords1), and the
 -- cave guard who steps aside once you are Champion.
+-- Post-battle: Bill text then CeruleanCityMovement3/4 into town.
+local function ceruleanRivalExitDirs(px)
+  if px == 20 then
+    return { "right", "down", "down", "down", "down", "down", "down" }
+  end
+  return { "left", "down", "down", "down", "down", "down", "down" }
+end
+
 local function ceruleanRivalScene(px, py)
   return {
     { "show_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 1
@@ -502,41 +533,43 @@ local function ceruleanRivalScene(px, py)
     { "face_object", 1, "down" },                              -- 3
     { "show_text", "_CeruleanCityRivalPreBattleText" },        -- 4
     { "rival_battle", "OPP_RIVAL1", 7 },                       -- 5
-    { "jump_if_false", 10 },                                   -- 6
+    { "jump_if_false", 11 },                                   -- 6
     { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },               -- 7
     { "show_text", "_CeruleanCityRivalDefeatedText" },         -- 8
-    { "move_npc_to", 1, 20, 2 },                               -- 9
-    { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 10
+    { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 9
+    { "walk_npc", 1, ceruleanRivalExitDirs(px) },              -- 10
+    { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 11
   }
 end
 
 -- scripts/CeruleanCity.asm CeruleanCityRocketText: fight the thief,
--- then he returns TM28 (DIG) and hurries off
+-- then he returns TM28 (DIG) and hurries off.  CeruleanHideRocket
+-- (CeruleanCity_2.asm) is GBFadeOutToBlack → Show GUARD1 / Hide GUARD2 /
+-- Hide ROCKET → GBFadeInFromBlack — not a bare hide_object.
 local rocketRows = {
   { "face_player" },                                           -- 1
   { "check_flag", "EVENT_GOT_TM28" },                          -- 2
-  { "jump_if_true", 15 },                                      -- 3
+  { "jump_if_true", 15 },                                      -- 3 → CeruleanHideRocket
   { "check_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },        -- 4
   { "jump_if_true", 9 },                                       -- 5
   { "show_text", "_CeruleanCityRocketText" },                  -- 6
   { "start_battle", "trainer", "OPP_ROCKET", 5 },              -- 7
-  { "jump_if_false", 18 },                                     -- 8
+  { "jump_if_false", "end" },                                  -- 8
   { "show_text", "_CeruleanCityRocketIllReturnTheTMText" },    -- 9
   { "set_flag", "EVENT_BEAT_CERULEAN_ROCKET_THIEF" },          -- 10
   { "give_item", "TM_DIG", 1, false },                         -- 11 (row 13 prints)
   { "set_flag", "EVENT_GOT_TM28" },                            -- 12
   { "show_text", "_CeruleanCityRocketReceivedTM28Text" },      -- 13
   { "show_text", "_CeruleanCityRocketIBetterGetMovingText" },  -- 14
-  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_ROCKET" },   -- 15
-  -- CeruleanHideRocket (scripts/CeruleanCity_2.asm) does all three behind
-  -- one fade: the ROCKET goes, GUARD1 (28,12) appears and GUARD2 (27,12)
-  -- disappears.  GUARD2 stands on the only walkable neighbour of the
-  -- trashed house's south door, which is one of the two ways through the
-  -- fence dividing Cerulean, so this swap is what reconnects the city.
-  -- Bill's ticket performs the same swap (data/scripts/story.lua), and
-  -- both are idempotent, so whichever the player reaches first opens it.
+  { "fade", "out" },                                           -- 15 GBFadeOutToBlack
+  -- CeruleanHideRocket while black: GUARD1 (28,12) appears, GUARD2
+  -- (27,12) and the ROCKET go.  GUARD2 blocks the trashed-house south
+  -- door neighbour — the swap reconnects the city (Bill's ticket does
+  -- the same in story.lua; either route is enough).
   { "show_object", "CERULEAN_CITY", "CERULEANCITY_GUARD1" },   -- 16
   { "hide_object", "CERULEAN_CITY", "CERULEANCITY_GUARD2" },   -- 17
+  { "hide_object", "CERULEAN_CITY", "CERULEANCITY_ROCKET" },   -- 18
+  { "fade", "in" },                                            -- 19 GBFadeInFromBlack
 }
 
 M.CERULEAN_CITY = {

data/scripts/victories.lua

@@ -12,6 +12,12 @@
 -- "; deactivate gym trainers" / SetEventRange in the other gyms, and
 -- FightingDojo.asm SetEventRange EVENT_BEAT_KARATE_MASTER ..
 -- EVENT_BEAT_FIGHTING_DOJO_TRAINER_3).
+--
+-- `dialogue` is the end-battle + post-battle text chain each gym leader
+-- runs (SaveEndBattleTextPointers then the map's *PostBattle / ReceiveTM
+-- script).  Leaders are not def_trainers entries, so engageTrainer has
+-- no header.won — checkVictoryRewards shows this chain instead of a
+-- synthetic "received badge/TM" stub.
 
 local function range(prefix, first, last)
   local t = {}
@@ -31,28 +37,76 @@ return {
                       hide = {
                         { "PEWTER_CITY", "PEWTERCITY_YOUNGSTER" },
                         { "ROUTE_22", "ROUTE22_RIVAL1" },
+                      },
+                      dialogue = {
+                        "_PewterGymBrockReceivedBoulderBadgeText",
+                        "_PewterGymBrockBoulderBadgeInfoText",
+                        "_PewterGymBrockWaitTakeThisText",
+                        "_PewterGymReceivedTM34Text",
+                        "_TM34ExplanationText",
                       } },
   ["OPP_MISTY#1"] = { badge = "CASCADEBADGE", flag = "EVENT_BEAT_MISTY",
                       item = "TM_BUBBLEBEAM",
-                      deactivate = range("EVENT_BEAT_CERULEAN_GYM_TRAINER_", 0, 1) },
+                      deactivate = range("EVENT_BEAT_CERULEAN_GYM_TRAINER_", 0, 1),
+                      dialogue = {
+                        "_CeruleanGymMistyReceivedCascadeBadgeText",
+                        "_CeruleanGymMistyCascadeBadgeInfoText",
+                        "_CeruleanGymMistyReceivedTM11Text",
+                      } },
   ["OPP_LT_SURGE#1"] = { badge = "THUNDERBADGE", flag = "EVENT_BEAT_LT_SURGE",
                          item = "TM_THUNDERBOLT",
-                         deactivate = range("EVENT_BEAT_VERMILION_GYM_TRAINER_", 0, 2) },
+                         deactivate = range("EVENT_BEAT_VERMILION_GYM_TRAINER_", 0, 2),
+                         dialogue = {
+                           "_VermilionGymLTSurgeReceivedThunderBadgeText",
+                           "_VermilionGymLTSurgeThunderBadgeInfoText",
+                           "_VermilionGymLTSurgeReceivedTM24Text",
+                           "_TM24ExplanationText",
+                         } },
   ["OPP_ERIKA#1"] = { badge = "RAINBOWBADGE", flag = "EVENT_BEAT_ERIKA",
                       item = "TM_MEGA_DRAIN",
-                      deactivate = range("EVENT_BEAT_CELADON_GYM_TRAINER_", 0, 6) },
+                      deactivate = range("EVENT_BEAT_CELADON_GYM_TRAINER_", 0, 6),
+                      dialogue = {
+                        "_CeladonGymErikaReceivedRainbowBadgeText",
+                        "_CeladonGymRainbowBadgeInfoText",
+                        "_CeladonGymReceivedTM21Text",
+                        "_TM21ExplanationText",
+                      } },
   ["OPP_KOGA#1"] = { badge = "SOULBADGE", flag = "EVENT_BEAT_KOGA",
                      item = "TM_TOXIC",
-                     deactivate = range("EVENT_BEAT_FUCHSIA_GYM_TRAINER_", 0, 5) },
+                     deactivate = range("EVENT_BEAT_FUCHSIA_GYM_TRAINER_", 0, 5),
+                     dialogue = {
+                       "_FuchsiaGymKogaReceivedSoulBadgeText",
+                       "_FuchsiaGymKogaSoulBadgeInfoText",
+                       "_FuchsiaGymKogaReceivedTM06Text",
+                       "_FuchsiaGymKogaTM06ExplanationText",
+                     } },
   ["OPP_SABRINA#1"] = { badge = "MARSHBADGE", flag = "EVENT_BEAT_SABRINA",
                         item = "TM_PSYWAVE",
-                        deactivate = range("EVENT_BEAT_SAFFRON_GYM_TRAINER_", 0, 6) },
+                        deactivate = range("EVENT_BEAT_SAFFRON_GYM_TRAINER_", 0, 6),
+                        dialogue = {
+                          "_SaffronGymSabrinaReceivedMarshBadgeText",
+                          "_SaffronGymSabrinaMarshBadgeInfoText",
+                          "_SaffronGymSabrinaReceivedTM46Text",
+                          "_TM46ExplanationText",
+                        } },
   ["OPP_BLAINE#1"] = { badge = "VOLCANOBADGE", flag = "EVENT_BEAT_BLAINE",
                        item = "TM_FIRE_BLAST",
-                       deactivate = range("EVENT_BEAT_CINNABAR_GYM_TRAINER_", 0, 6) },
+                       deactivate = range("EVENT_BEAT_CINNABAR_GYM_TRAINER_", 0, 6),
+                       dialogue = {
+                         "_CinnabarGymBlaineReceivedVolcanoBadgeText",
+                         "_CinnabarGymBlaineVolcanoBadgeInfoText",
+                         "_CinnabarGymBlaineReceivedTM38Text",
+                         "_CinnabarGymBlaineTM38ExplanationText",
+                       } },
   ["OPP_GIOVANNI#3"] = { badge = "EARTHBADGE", flag = "EVENT_BEAT_GIOVANNI",
                          item = "TM_FISSURE",
-                         deactivate = range("EVENT_BEAT_VIRIDIAN_GYM_TRAINER_", 0, 7) },
+                         deactivate = range("EVENT_BEAT_VIRIDIAN_GYM_TRAINER_", 0, 7),
+                         dialogue = {
+                           "_ViridianGymGiovanniReceivedEarthBadgeText",
+                           "_ViridianGymGiovanniEarthBadgeInfoText",
+                           "_ViridianGymGiovanniReceivedTM27Text",
+                           "_ViridianGymGiovanniTM27ExplanationText",
+                         } },
 
   -- Silph Co. Giovanni: unlocks the president's Master Ball gift
   ["OPP_GIOVANNI#2"] = { flag = "EVENT_BEAT_SILPH_CO_GIOVANNI" },
@@ -60,9 +114,12 @@ return {
   -- Fighting Dojo Karate Master (scripts/FightingDojo.asm
   -- FightingDojoKarateMasterPostBattleScript sets EVENT_BEAT_KARATE_MASTER,
   -- which gates the HITMONLEE/HITMONCHAN gift).  OPP_BLACKBELT party 1 is
-  -- only him (data/maps/objects/FightingDojo.asm).
+  -- only him (data/maps/objects/FightingDojo.asm).  `dialogue` is the
+  -- concede + prize offer he speaks after the win (his header supplies the
+  -- "Hwa! Arrgh! Beaten!" won line first; #197).
   ["OPP_BLACKBELT#1"] = { flag = "EVENT_BEAT_KARATE_MASTER",
-                          deactivate = range("EVENT_BEAT_FIGHTING_DOJO_TRAINER_", 0, 3) },
+                          deactivate = range("EVENT_BEAT_FIGHTING_DOJO_TRAINER_", 0, 3),
+                          dialogue = { "_FightingDojoKarateMasterIWillGiveYouAPokemonText" } },
 
   -- Elite Four progress flags (their rooms' door logic isn't ported, but
   -- the flags make the Hall of Fame checkable)

docs/launcher.md

@@ -0,0 +1,163 @@
+# Launcher
+
+The launcher is `src/import/RomImporter.lua`, the first-run / title screen
+that runs before `Game:load`. Besides ROM import (see the file's own header)
+it hosts a tabbed shell covering per-game save slots and a mod manager. This
+file documents the runtime model; the visual spec lives separately.
+
+## Android multi-ROM import
+
+On Android, `love.system.pickFile()` opens the Storage Access Framework
+picker (`GameActivity.showRomFilePicker`); the chosen file is copied to
+`picked_rom.gb` in the app save directory. `RomImporter` then imports on
+refocus / Choose via `findPendingRom`: only a 1 MiB `.gb` whose SHA-1 maps
+to a version that is **not** yet ready counts as pending. A leftover
+`picked_rom.gb` from Red therefore cannot block Blue's Choose (issue #167).
+After a successful import the consumed save-dir `.gb` is removed.
+
+**Manual check (device/emulator):** import Red → switch to Blue → Choose →
+system file picker must appear (not a silent Red re-extract) → pick Blue →
+Blue becomes ready beside Red.
+
+## Tab structure
+
+`self.tab` is one of `"red"`, `"blue"`, `"yellow"`, `"mods"`. The tab bar
+draws one chip per game plus a MODS chip and rebuilds `self.tabRects` every
+frame so `mousepressed` can dispatch clicks; switching tabs mid-import is
+allowed (a dropped ROM still routes by SHA-1 regardless of which tab shows).
+
+- A game tab (`_drawGamePanel`) shows the ROM card, the SAVE FILES card, the
+  Play button, and the SAVE SLOT card in a responsive two-column grid (see
+  Responsiveness). The MODS tab (`_drawModsPanel`) shows the mod list instead.
+- The self-updater banner (`self.Check`, see `docs/updater.md`) draws as a
+  centered pill in a reserved band just above the footer, on every tab. That
+  position is unchanged by this redesign, so `docs/updater.md` needed no edits.
+
+## Save slot model
+
+All slot I/O lives in `src/core/SaveData.lua` and goes through the same fs
+abstraction (`persistFs`) every other save/options call uses, so portable
+mode (an `io.*` filesystem used when `portable.txt` marks the install)
+keeps working unchanged.
+
+- **Files.** A version's playthroughs live under `saves/<version>/`, one file
+  per slot: `saves/<version>/slot1.lua` plus a rolling `.bak` and staged
+  `.tmp` witness (`slotNames`), mirroring the write/recovery discipline
+  `SaveData.save`/`load` already use for the flat legacy file. Slot ids match
+  `slot%d+`; `createSlot` allocates one past the highest existing number so a
+  reused id can never collide with a lingering file.
+- **Registry.** The ordered slot list and which one is active persist in
+  `options.lua` (via the existing `SaveData.loadOptions`/`saveOptions`):
+  `options.saveSlots = { [version] = { list = {"slot1", ...}, active = "slot1" } }`.
+- **Active slot resolution.** `saveNames(version)`, the function every
+  existing caller (`TitleState` hasSave/load/save, recovery order) already
+  goes through, now resolves the *active* slot instead of a fixed flat name.
+  Resolved once per version per process (`ensureVersionSlots`, cached in
+  `activeSlotCache`/`slotsChecked`): a registry entry wins; otherwise a lazy
+  legacy migration may create one; otherwise the flat legacy path is used
+  (`save.lua` / `save_blue.lua`), so a pre-slots install keeps working as before.
+- **Legacy migration.** One-time per version, lazy on first
+  `listSlots`/`load`/`saveNames` call (`tryMigrateLegacy`): if a flat legacy
+  file exists and no `saves/<version>/` registry does, its main + `.bak` are
+  copied into `saves/<version>/slot1.lua(.bak)`, verified readable
+  (`decodeSlot`: main, then `.tmp`, then `.bak`), and only then are the
+  originals removed and `slot1` registered as active. A copy that fails to
+  verify leaves the originals in place; migration never loses data.
+
+The launcher-facing API:
+- `SaveData.listSlots(version)` -> array of `{id, exists, name, meta}` for
+  every registered slot. `name` is the save's player name, or `nil` for an
+  empty slot; `meta` is `{badges, timeText, dexCount}` (the same fields the
+  title screen's `ContinueInfo` shows) or `nil`. The pure part,
+  `SaveData.slotSummary(save)`, is unit-testable with no filesystem.
+- `SaveData.setActiveSlot(version, slotId)` registers the id if new, persists
+  it as active, and updates the process cache so the very next save/load
+  lands there. The launcher calls this the moment a slot row is clicked
+  (`RomImporter:_selectSlot`); pressing Play needs no signature change, since
+  `Game.lua`/`main.lua` still just call `SaveData.load()`/`save()`.
+- `SaveData.createSlot(version)` -> new slot id, registered but with **no
+  save file written**. An empty slot means the title screen offers NEW GAME
+  only, which needs no further changes.
+
+## Launcher mod manager
+
+`src/mods/LauncherMods.lua` is a launcher-only read of the mod set. It runs
+before `Game:load`, so **it never loads a mod's entry chunk**; only
+`manifest.json` is read and validated (`src/mods/Manifest.validate`), the way
+`Loader:_discover` finds mods without running them. The real loader
+(`src/mods/Loader.lua`) still owns the actual load at boot.
+
+- `LauncherMods.list()` scans `mods/` one level deep (first id wins on a
+  duplicate) and returns one row per mod:
+  `{id, name, version, badge, description, enabled, status, statusDetail}`.
+  `badge` is the manifest's `category`, falling back to `profile`, then
+  `"MOD"`, uppercased. `enabled` reads `options.mods[id]` (missing means
+  enabled, matching the loader's own default).
+- `status` is `"ok"`, `"warn"`, or `"conflict"`, computed by the pure
+  `LauncherMods.deriveList`/`statusFor` against `ManagerState.resolveToggle`
+  and the validated manifests: `conflict` when enabling this mod collides
+  with another enabled one; `warn` for an out-of-range `game_version` or an
+  absent/disabled/wrong-version hard dependency; `ok` otherwise. Having no
+  `love.*` calls, this half is table-driven by the test suite on its own.
+- `LauncherMods.setEnabled(id, bool)` persists `options.mods[id]` as a plain
+  boolean, the exact shape `Loader:_saveState` writes, so the running game
+  and the in-game `ManagerState` see the change on next boot. The mods panel
+  calls this on every toggle and re-derives the list right away
+  (`RomImporter:_refreshMods`) so a status change (e.g. a new conflict)
+  shows without waiting for a reload.
+- `LauncherMods.installZip(path)` mounts the archive with
+  `love.filesystem.mount`, locates the mod root via `locateRoot` (manifest at
+  the zip root, or inside one top-level folder), validates its manifest, and
+  copies the tree into the save-dir `mods/<id>/` before unmounting. Rejects a
+  duplicate of an already-installed mod id, and accepts either an external
+  path string or a LOVE `DroppedFile`, staging a dropped file into a save-dir
+  temp first (mount only reaches save-dir-relative paths), the same way
+  `RomImporter` handles a dropped ROM. A failed copy rolls its partial tree
+  back, and every path unmounts and clears the staged temp file.
+
+## Import / Export save
+
+The SAVE FILES card wires a raw Gen1 `.sav` battery image to the save slots
+through `src/import/SaveFileIO.lua`, which sits on top of
+`src/save_convert/SaveConvert.lua` and the slot API in `SaveData`.
+
+- **Import save** is live once the game's ROM is imported (playable). It opens
+  a native `.sav` picker (`chooseSav`, the per-OS dialogs mirror `chooseZip`;
+  Android has no picker and shows a drop hint). `SaveFileIO.importToSlot`
+  reads the bytes (an absolute path, a dropped LOVE file, or raw bytes),
+  guards the 32768-byte size, runs `SaveConvert.importSav` (which also rejects
+  a bad main-data checksum), then registers a fresh slot (`SaveData.createSlot`),
+  writes it (`SaveData.writeSlot`), and makes it active (`SaveData.setActiveSlot`).
+  The meta stamp is re-stamped off `gen1_import` to the current numeric format
+  so `SaveData.load`'s migration pass accepts the slot. On success the SAVE SLOT
+  panel is refreshed with the new slot selected.
+- **Export save** is live only when the active slot actually holds a save
+  (checked against `listSlots`). `SaveFileIO.exportActiveSlot` loads the active
+  slot, encodes it back with `SaveConvert.exportSav` (a slot never keeps
+  `rawImport`, so this is a zero-filled template export, which is valid), and
+  writes `exports/gen1recomp-<version>-<slotId>.sav` in the save directory
+  (`love.filesystem.createDirectory("exports")`). It returns the absolute path
+  (`love.filesystem.getSaveDirectory()`), which the notice line shows with a
+  desktop "Open folder" affordance (`love.system.openURL("file://" .. dir)`).
+- **Drag-drop.** `filedropped` routes a `.sav` to the import path for the
+  currently active game tab; when a non-game tab (mods, or the locked yellow
+  placeholder) is showing it defaults to red, the always-present first game
+  (`_savedropTarget`). `.gb` (ROM) and `.zip` (mod) routing is unchanged.
+- **Failure UX.** Every error path (wrong size, bad checksum, write failure,
+  nothing to export, ROM not imported yet) surfaces as a red notice line on the
+  card. Nothing raises and nothing silently no-ops.
+
+`SaveFileIO` is love-free enough to unit-test through the same in-memory
+filesystem stub the slot backend uses (`tests/engine/save_file_io_tests.lua`).
+
+## Responsiveness
+
+Every measurement derives from `love.graphics.getDimensions()` each frame
+plus the existing global scale `s = clamp(height / 768, 0.7, 1.6)`; nothing
+assumes a fixed window size. The game panel's two-column grid (ROM/SAVE
+FILES/Play on the left, SAVE SLOT on the right) collapses to one stacked
+column, slot card below Play, when the window is too narrow for both
+`~300 * s`-wide columns. The save-slot list and the mod list both scroll
+(wheel, or drag on touch/desktop) clamped to their own content extent,
+recomputed every draw. The tab bar labels only the active chip so it stays
+narrow-safe, and content caps out at `~1440 * s` wide, centered.

docs/modding.md

@@ -18,6 +18,111 @@ Regenerate the reference straight into a wiki checkout:
 luajit tools/gen_registry_docs.lua ../pokemon-gen1-recomp-project.wiki
 ```
 
+## Rendering pipelines
+
+Most registries hand the engine *content*. `render_pipelines` hands it
+*drawing*: a pipeline is a display mode a mod owns, which may replace the
+overworld's world pass with geometry of its own and/or post-process the
+finished image. `mods/voxel_world` is the worked example — a 3D diorama
+overworld plus a tilt-shift miniature pass, in about 120 lines of glue over
+its renderer.
+
+A record declares what the mode *is*; the engine
+(`src/render/Pipelines.lua`) supplies everything about *being a display
+mode*: the OFF/1/2/3 ladder, an options row next to TILT, a hotkey,
+persistence in `save.options.pipelines`, and the rule that a world pipeline
+and the engine's own TILT are mutually exclusive.
+
+```lua
+mod.content.render_pipelines:register("diorama", {
+  label = "DIORAMA",                    -- options row label
+  levels = { "OFF", "15", "35", "50" }, -- ladder; defaults to OFF/ON
+  hotkey = "6",                         -- checked after the engine's keys
+  priority = 20,                        -- highest eligible wins the world
+  available = function() return Renderer3D.ok() end,
+  update = function(dt, level) Camera.ease(dt, level) end,
+  drawWorld = function(ctx) return renderScene(ctx) end,
+})
+```
+
+Three draw stages, each optional; a record needs at least one:
+
+| stage | signature | runs |
+| --- | --- | --- |
+| `drawWorld` | `(ctx) -> canvas \| nil` | instead of the flat/tilt world pass |
+| `worldPresent` | `(canvas, ctx) -> canvas` | over the world, **before** the UI composites |
+| `present` | `(canvas, ctx) -> canvas` | over the whole frame, world and UI alike |
+
+`worldPresent` is the one to reach for when an effect must leave dialog
+boxes and menus crisp — a depth-of-field or colour grade on the world only.
+`present` is for effects that genuinely own the screen, like a CRT curve.
+
+`ctx` carries the frame: `state`, `cam`, `vw`/`vh` (world-pixel view),
+`width`/`height` (window pixels), `scale`, `level`, `paletteFor(map)` and
+`spriteColors(map)`. It also carries `ctx.drawFx(project, scale)` — call it
+with your own projection and the engine draws every active field effect
+(the "!" bubble, the Poké Center heal machine, the Fly bird, the fishing
+rod, Rock Tunnel darkness) at its correct anchor under your camera. There
+is exactly one copy of each effect, so a new engine effect works in your
+pipeline without you touching anything.
+
+Three rules worth knowing:
+
+- **`gate` governs input, never the draw.** It decides whether the player
+  may *change* the mode (default: free-roam overworld only). A mode that
+  stopped rendering during a warp would flash the flat 2D world every time
+  the player walked through a door.
+- **`available` is re-read every frame** and is the only thing that decides
+  whether the mode can render at all. Answer `false` on a headless run or a
+  driver with no depth canvas and the engine silently keeps the vanilla 2D
+  path — which is why shipping a pipeline enabled is safe.
+- **A callback that throws retires its pipeline**, attributed to your mod in
+  the manager's error feed, and the frame falls back to 2D. A broken
+  renderer costs the player a display mode, never the game.
+
+Returning `nil` from `drawWorld` is a normal answer meaning "not this
+frame"; the engine draws the vanilla world instead.
+
+## Battle sprite scaling
+
+The enemy's front pic draws at 1x and the player's back pic at 2x, the way
+the Game Boy did. A mod can override either, per species or per image.
+
+Per species, on the `pokemon` record:
+
+```lua
+-- MEW's back pic renders 1.5x; its front pic is untouched
+mod.content.pokemon:patch("MEW", { battleScaleBack = 1.5 })
+```
+
+`battleScaleFront` scales the enemy pic, `battleScaleBack` the player pic;
+both take a number in `0.25 .. 4.0`.
+
+Per image, on the `battle_sprite_scales` registry, keyed by the asset path
+exactly as the data references it:
+
+```lua
+mod.content.battle_sprite_scales:register("abra_back", {
+  path = "assets/generated/battle/back/abrab.png",
+  scale = 1.5,
+})
+```
+
+An image-level entry beats the species scale for that one pic, and it is
+the only way to scale a pic that is not species-keyed — the player's
+trainer back sprite, held on screen until "Go!", is a bare image path.
+
+The resolution order at draw time is **image-level → species-level →
+default** (1x front, 2x back).
+
+- **The pic stays grounded at every scale.** The player pic keeps its feet
+  flush on the text-box top (`y = 96`); the enemy pic keeps its bottom edge
+  and horizontal centre pinned in its 7×7 slot. A larger pic grows upward
+  and outward from that anchor, never off the shelf.
+- **Scaling composes with the send-out grow.** The `AnimateSendingOutMon`
+  ball-to-pic grow multiplies your scale through each stage, so a rescaled
+  mon still grows into place from the ball, grounded the whole way.
+
 ## Developer console
 
 Boot with developer mode on to unlock the in-game console and hot-reload

docs/new-features.md

@@ -179,4 +179,18 @@ Into-battle wipes still run the original eight styles inside the classic
 blocks cascade outward from that square into the surrounding world so the
 void outside the OG wipe fills in lockstep. Once the battle state is up,
 letterbox voids around the battle canvas fill **white** instead of black
-so the whole window reads as one continuous battle screen.
+so the whole window reads as one continuous battle screen.
+
+## On-screen touch controls (mobile)
+
+On Android/iOS the game draws a translucent d-pad (bottom-left), A/B
+buttons (bottom-right, Game Boy diagonal), and +/- START/SELECT (bottom
+center) over the frame, using Xelu's CC0 controller prompts
+(`assets/touch/`). Real buttons, not gestures: press lands the frame the
+finger does, sliding on the d-pad changes direction without lifting, and
+multi-touch chords (e.g. hold a direction + tap B) work. The overlay only
+appears while no controller is being used: the first gamepad button or
+stick push hides it, the next screen touch brings it back, and unplugging
+the last controller restores it immediately. Layout re-derives from the
+window size on rotation. Desktop testing: `POKEPORT_TOUCH=1 love .` forces
+the overlay on and lets the mouse act as a finger (`=0` forces it off).

docs/updater.md

@@ -0,0 +1,126 @@
+# Updater
+
+A fused build (`love.filesystem.isFused()` true) ships a bundled `game.love`
+baked into the executable, but that bundled copy is only ever the *fallback*.
+On every launch, before anything else runs, `Boot.run` (`src/update/Boot.lua`)
+looks in the save directory's `updates/` folder for a downloaded
+`gen1recomp-X.Y.Z.love` payload that is both strictly newer than the bundled
+engine version and runnable on this shell. If one qualifies, it is mounted
+over `/` (so its files win over the fused source for every subsequent
+`require`) and chainloaded in place: the payload's `main.lua` and `love.load`
+run as if they had shipped in the executable. A dev/source checkout is never
+fused, so `Boot.run` no-ops there and the working tree always runs itself.
+
+The pieces are deliberately layered so the risky part is small. `Boot.select`
+is a pure function (no `love.*` calls) that, given probed candidates and the
+bundled `engine`/`shell`, decides what to run and what stale payloads to
+delete. `Boot.probePayload` mounts one archive at an isolated mountpoint and
+reads its `src/core/Version.lua` with `loadstring` (never `require`, so it is
+never cached as a module) to learn its `engine` and `minShell`. `Boot.run`
+orchestrates the crash guard, enumeration, selection, and the mount +
+chainload, with full rollback on any failure. Checking for and fetching a
+new payload is a separate, slower path: `src/update/Check.lua` is a thin
+main-thread state machine the launcher screen polls, while the curl calls,
+JSON parsing, and sha256 verification run on a background `love.thread`
+(`src/update/check_worker.lua`) so a hung network call never blocks a frame.
+
+## Version.lua fields
+
+`src/core/Version.lua` carries three fields the updater reads directly (the
+existing `modApi`, `linkProtocol`, `saveFormat`, and `cache` fields are
+untouched):
+
+- `engine` - the semver release, e.g. `"1.4.0"`. The repo default is the
+  `"0.0.0-dev"` placeholder; CI stamps the real `X.Y.Z` into the packed
+  `game.love` only, never the working tree. A `"0.0.0-dev"` engine always
+  reports itself up to date (it never chases a release, and it never counts
+  as a valid payload to chainload).
+- `shell` - the native-shell contract this build's fused executable
+  implements.
+- `minShell` - the lowest shell contract required to *run* this payload.
+
+Bump `minShell` only when a payload needs something the currently-shipped
+native shell cannot provide, for example a LOVE version bump, a new required
+system binary, or a change to `love.run` itself (see Known limitations
+below). An older shell refuses to chainload a payload whose `minShell`
+exceeds the shell it provides; `Boot.select` keeps that payload in `updates/`
+rather than deleting it, in case a future shell upgrade can run it, and
+`Check`'s worker reports `needs_full` so the player is pointed at a full
+installer instead. Do not bump `minShell` for an ordinary Lua/data release;
+that is exactly the case the updater exists to avoid a reinstall for.
+
+## Release assets
+
+Each tagged release `vX.Y.Z` carries the existing per-platform archives
+(`gen1recomp-X.Y.Z-macos.zip`, `-windows.zip`, `-linux.zip`,
+`-android.apk`) plus two assets the updater itself consumes:
+
+- `gen1recomp-X.Y.Z.love` - the payload, matched by the exact pattern
+  `gen1recomp-<version>.love` (see `isPayloadName` in `Boot.lua` and
+  `Check.parseRelease`).
+- `sha256sums.txt` - `shasum -a 256` output (`<hex>  <filename>`, bare
+  filenames) covering at least the `.love` payload. `Check.parseSums`
+  tolerates a leading `*` binary marker and a `./` prefix but expects the
+  filename otherwise to match the asset name exactly.
+
+A release missing either asset is treated as "no in-place update available":
+`Check` reports `needs_full` and sends the player to `Check.releaseUrl()`
+(`https://github.com/bryanthaboi/pokemon-gen1-recomp-project/releases/latest`).
+
+## Save-directory layout
+
+Under the save directory (identity `pokemon-love2d`):
+
+```
+updates/gen1recomp-<X.Y.Z>.love   downloaded payload(s)
+updates/pending.txt                crash-guard marker
+```
+
+`pending.txt` holds the filename of the payload currently being chainloaded.
+`Boot.run`'s `chainload` writes it immediately before mounting, and removes it
+on both a successful handoff and a clean rollback. If it is still present the
+*next* time `Boot.run` starts, the previous boot died mid-handoff, so that
+named payload is distrusted: it and the marker are deleted before candidates
+are enumerated. Boot may still fall back to an older valid payload, or to the
+bundled game, in that case.
+
+## Update flow
+
+1. **Boot** (every launch, fused builds only): crash-guard check, enumerate
+   and probe every `updates/*.love`, pick the highest engine that is
+   strictly newer than the bundled one and whose `minShell` this shell
+   satisfies, delete stale payloads, chainload the winner (or run the
+   bundled game if none qualifies).
+2. **Check** (launcher screen): `Check.start()` kicks off an async check
+   against the GitHub releases API; safe to call every frame, it is a no-op
+   once a check is in flight or has reached a terminal state. `Check.state()`
+   reports `idle | checking | uptodate | available | downloading | ready |
+   needs_full | error` plus the latest version and download progress.
+3. **Download + verify**: on `available`, `Check.download()` tells the
+   worker to fetch the payload, polling the growing `.part` file for
+   progress. On completion the worker re-fetches `sha256sums.txt`, verifies
+   the payload's sha256, and probes it with `Boot.probePayload` to gate its
+   `minShell` against this shell's `shell`. A verified, runnable payload is
+   renamed into place and reported as `ready`; anything else reports
+   `error` or `needs_full` and leaves `updates/` clean.
+4. **Restart to apply**: a `ready` payload just sits in `updates/` until the
+   player relaunches; the next launch's Boot step (1) is what actually
+   mounts and runs it. There is no in-session hot-swap.
+
+## Known limitations
+
+- **`love.run` persists across handoff.** By the time `chainload` runs, the
+  bundled `love.run` has already returned its stepper to LOVE; redefining the
+  global `love.run` from the payload's `main.lua` does not affect the loop
+  already driving the frame. A payload that must change `love.run` itself
+  needs a `minShell` bump so an older shell refuses to chainload it rather
+  than running with half its intended behavior.
+- **Android has no in-app download transport yet.** `check_worker.lua`
+  shells out to curl for both the release check and the download; curl is
+  absent on Android, so `Check` degrades to `status = "error"` there (the
+  launcher UI hides on that status) and the player is directed to the
+  releases page via `Check.releaseUrl()` instead.
+- **Dev/source runs never self-update.** `Boot.run` returns immediately when
+  `love.filesystem.isFused()` is false, and a working tree's `engine` is the
+  `"0.0.0-dev"` placeholder that always reports up to date, so a source
+  checkout is always "the game" itself; updating it means pulling the repo.

main.lua

@@ -18,6 +18,11 @@ local driverCo  -- optional frame-driver (POKEPORT_DRIVER=file.lua): a
 -- bot or screenshot run is not at the mercy of the player's last choice.
 local speedOverride = tonumber(os.getenv("POKEPORT_SPEED"))
 
+-- POKEPORT_TOUCH=1 forces the mobile on-screen controls on and lets the
+-- mouse stand in for a finger, so the overlay can be exercised on desktop
+-- (see src/core/TouchControls.lua).
+local mouseTouch = os.getenv("POKEPORT_TOUCH") == "1"
+
 -- How many times to run a scripted act+step loop per rendered frame.  Only
 -- scripted runs use this; interactive play fast-forwards through
 -- Game.speedOverride / the GAME SPEED option instead.
@@ -56,6 +61,12 @@ local function bootGame(version)
 end
 
 function love.load(args)
+  -- Self-updater boot shell: a fused build may mount and chainload a newer
+  -- downloaded payload here.  True means it took over, so we must stop.  A
+  -- dev / source checkout no-ops (see src/update/Boot.lua).
+  local Boot = require("src.update.Boot")
+  if Boot.run(args) then return end
+
   local savePath
   for i, a in ipairs(args or {}) do
     if a == "--editor" then
@@ -268,6 +279,9 @@ function love.mousepressed(x, y, button)
   if editorMode and EditorApp.mousepressed then
     return EditorApp.mousepressed(x, y, button)
   end
+  if mouseTouch and Game and button == 1 then
+    Game:touchpressed("mouse", x, y)
+  end
 end
 
 function love.mousereleased(x, y, button)
@@ -275,6 +289,16 @@ function love.mousereleased(x, y, button)
   if editorMode and EditorApp.mousereleased then
     return EditorApp.mousereleased(x, y, button)
   end
+  if mouseTouch and Game and button == 1 then
+    Game:touchreleased("mouse", x, y)
+  end
+end
+
+function love.mousemoved(x, y)
+  if editorMode or Importer then return end
+  if mouseTouch and Game and love.mouse.isDown(1) then
+    Game:touchmoved("mouse", x, y)
+  end
 end
 
 function love.textinput(text)

mobile/ANDROID.md

@@ -43,9 +43,12 @@ The embedded `game.love` deliberately excludes `data/generated/`,
 `assets/generated/`, and any ROM. It contains the first-boot Lua importer and
 `tools/rom_manifest.json`.
 
-The current importer has desktop file pickers only. A production Android
-release still needs a Storage Access Framework handoff that passes the chosen
-ROM to LÖVE; the APK packaging itself is data-free.
+ROM import on Android uses `love.system.pickFile()` →
+`GameActivity.showRomFilePicker` (Storage Access Framework), which copies the
+chosen file to `picked_rom.gb` under the app save directory. `RomImporter`
+imports pending (not-yet-ready) `.gb` files from that folder on Choose /
+refocus; see `docs/launcher.md` (Android multi-ROM import). The APK payload
+itself remains data-free (no embedded ROM or generated cache).
 
 ### SDK / NDK
 

mods/examples/example_balance_tweaks/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "BALANCE",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "dependencies": [],
   "optional_dependencies": [],

mods/examples/example_dexnav/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "TOOL",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "dependencies": [],
   "optional_dependencies": [],

mods/examples/example_jukebox/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "AUDIO",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "permissions": ["engine_internals"],
   "dependencies": [],

mods/examples/example_lost_parcel/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "QUEST",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "permissions": ["engine_internals"],
   "dependencies": [],

mods/examples/example_mini_conversion/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "total_conversion",
   "category": "TOTAL_CONVERSION",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 900,
   "dependencies": [],
   "optional_dependencies": [],

mods/examples/example_shiny_palette/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "content",
   "category": "GRAPHICS",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "assets_transforms": "transforms.lua",
   "dependencies": [],

mods/examples/example_weather/manifest.json

@@ -6,7 +6,7 @@
   "entry": "main.lua",
   "profile": "overhaul",
   "category": "MECHANIC",
-  "game_version": ">=1.0.0 <2.0.0",
+  "game_version": ">=0.0.0-0 <2.0.0",
   "priority": 100,
   "dependencies": [],
   "optional_dependencies": [],

scripts/build.sh

@@ -68,6 +68,31 @@ if unzip -Z1 "$LOVE_FILE" \
 fi
 say "game.love: $(du -h "$LOVE_FILE" | cut -f1)"
 
+# ------------------------------------------------------- stamp release version
+# The working tree ships Version.lua with engine "0.0.0-dev"; the real release
+# number only ever lives inside the packed archive. When --version is a strict
+# X.Y.Z, patch a copy of Version.lua (engine set to that number) under a staging
+# dir and replace the entry inside game.love in place -- never the source tree.
+# Short-hash / "dev" builds are left with the "-dev" default so they cannot be
+# mistaken for a release. The stamp is then read back out of the archive and the
+# build fails if it did not take.
+if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  say "stamping engine version $VERSION into game.love"
+  stamp_dir="$WORK/stamp"
+  rm -rf "$stamp_dir"
+  mkdir -p "$stamp_dir/src/core"
+  sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+    "$ROOT/src/core/Version.lua" > "$stamp_dir/src/core/Version.lua"
+  (cd "$stamp_dir" && zip -q "$LOVE_FILE" src/core/Version.lua)
+  version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+  unzip -p "$LOVE_FILE" src/core/Version.lua \
+    | grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+    || fail "version stamp failed: game.love does not report engine $VERSION"
+  say "stamped engine version: $VERSION"
+else
+  say "version '$VERSION' is not X.Y.Z,  shipping default engine (no stamp)"
+fi
+
 # --------------------------------------------------------------- macOS
 build_mac() {
   say "building macOS app"

scripts/build_android.sh

@@ -145,6 +145,32 @@ pack_game_love() {
     fail "game.love unexpectedly contains generated ROM data"
   fi
   say "game.love: $(du -h "$LOVE_FILE" | cut -f1) -> $LOVE_FILE"
+
+  # This script packs its own game.love (it does not reuse build.sh's), so it
+  # stamps the release version the same way: patch a copy of Version.lua
+  # (engine set to $VERSION) under a throwaway staging dir and replace the
+  # entry inside the archive in place -- never the source tree. VERSION is
+  # already validated as X.Y.Z above; when it is empty the packaged game keeps
+  # the "0.0.0-dev" default. The stamp is read back out and the build fails if
+  # it did not take.
+  if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    say "stamping engine version $VERSION into game.love"
+    local stamp_dir
+    stamp_dir="$(mktemp -d)"
+    mkdir -p "$stamp_dir/src/core"
+    sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+      "$ROOT/src/core/Version.lua" > "$stamp_dir/src/core/Version.lua"
+    (cd "$stamp_dir" && zip -q "$LOVE_FILE" src/core/Version.lua)
+    local version_re
+    version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+    unzip -p "$LOVE_FILE" src/core/Version.lua \
+      | grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+      || fail "version stamp failed: game.love does not report engine $VERSION"
+    rm -rf "$stamp_dir"
+    say "stamped engine version: $VERSION"
+  else
+    say "no X.Y.Z --version,  shipping default engine (no stamp)"
+  fi
 }
 
 # --------------------------------------------------------------- SDK check

src/battle/BattleState.lua

@@ -173,9 +173,32 @@ local function grayImage(img)
   return getImage(meta.path) or img
 end
 
+-- the asset path a loaded battle image came from (nil for the headless
+-- stub images), so the battle_sprite_scales registry can be looked up by
+-- the same path data references
+local function imagePathOf(img)
+  local m = imageMeta[img]
+  return m and m.path
+end
+
 -- the image a battler pic actually draws with this frame
 function BattleState:picImage(img)
-  if self.grayPics then return grayImage(img) end
+  local PaletteFX = require("src.render.PaletteFX")
+  -- #207: OG / OG INV / CLASSIC are forced-mono display modes.  A battle that
+  -- exposes no SGB zones (sgbPalettes() == nil) has a whole-screen GRAYS zone
+  -- invented by PaletteFX.ensureZones, so Renderer:endFrame re-thresholds the
+  -- WHOLE finished frame through the shade shader a second time (keyed on the
+  -- red channel).  A pic baked with the species' SGB color is then remapped
+  -- again and loses its warm mid shades -- REDMON's reds 1.0/0.839 both land in
+  -- the c0 bucket, collapsing CHARMANDER's body into the white paper and
+  -- leaving only the outline.  Emit the raw DMG-gray build instead (exactly
+  -- what the SE_WAVY_SCREEN grayPics path already does) so the downstream remap
+  -- recolors 255->c0/170->c1/85->c2/0->c3 and all four shades survive; cool
+  -- palettes (CYANMON reds 0.678/0.451) already rendered correctly.  This mode
+  -- set mirrors PaletteFX.ensureZones / effectiveColors -- keep them in sync.
+  local mono = PaletteFX.mode == "og" or PaletteFX.mode == "og_inv"
+               or PaletteFX.mode == "classic"
+  if self.grayPics or mono then return grayImage(img) end
   return fadeImage(img, self:activeBgp())
 end
 
@@ -267,6 +290,10 @@ local function makeBattler(data, mon, isPlayer, save)
     badgeBoosts = badgeBoosts,
     statuses = data.statuses,
     shownHP = mon.hp, -- the HP the bar displays (UpdateHPBar drain)
+    -- HUD status label (DrawHUDsAndHPBars); mon.status can land mid-move
+    -- while the tilemap still shows the prior condition until the next
+    -- post-action HUD refresh (core.asm after Execute*Move)
+    shownStatus = mon.status,
     stages = {},
     -- volatile state; Transform/Conversion/Mimic override the cur* fields
     curStats = mon.stats,
@@ -548,6 +575,12 @@ function BattleState:say(text)
   table.insert(self.queue, { text = text })
 end
 
+-- Message that opens YES/NO once typed out, keeping the text visible
+-- underneath (pokered `done` + TWO_OPTION_MENU / TextBox opts.choice).
+function BattleState:sayChoice(text, onChoose)
+  table.insert(self.queue, { text = text, choice = onChoose })
+end
+
 function BattleState:act(fn)
   table.insert(self.queue, { fn = fn })
 end
@@ -648,16 +681,53 @@ local function shownHP(b)
   return math.floor(shown)
 end
 
+-- Parse a battle message into its rendered lines.  The extractor marks
+-- \n = next line and \v = CONT (home/text.asm ContText: draw the blinking
+-- ▼, WaitForTextScrollButtonPress, then ScrollTextUpOneLine); the boosted /
+-- EXP.ALL exp lines end in the CONT code in the ROM (data/generated/text.lua
+-- _BoostedText/_WithExpAllText = "...\011").  Each entry is { codes, cont },
+-- cont true when the line was preceded by \v.  Splitting before Font.encode
+-- keeps the control chars out of the glyph stream.  The box then types into
+-- a rolling 2-line window (self.shown) that scrolls when a 3rd line arrives
+-- instead of drawing it off-screen at y=144 (#216).
 function BattleState:startMessage(item)
   self.current = item
   self.lines = {}
   self.total = 0
-  for chunk in (item.text .. "\n"):gmatch("(.-)\n") do
+  local text = item.text or ""
+  local pos, cont = 1, false
+  while true do
+    local npos = text:find("[\n\v]", pos)
+    local chunk = npos and text:sub(pos, npos - 1) or text:sub(pos)
     local codes = Font.encode(chunk)
-    table.insert(self.lines, codes)
+    self.lines[#self.lines + 1] = { codes = codes, cont = cont }
     self.total = self.total + #codes
+    if not npos then break end
+    cont = text:sub(npos, npos) == "\v"
+    pos = npos + 1
   end
+  self.shown = {}        -- up to two visible lines of revealed glyph codes
+  self.lineIndex = 0
+  -- self.charIndex counts glyphs typed across the WHOLE message (drivers read
+  -- it against self.total); the current line's revealed count is #shown[last]
   self.charIndex = 0
+  self.msgWaiting = nil
+  self.scrollPx = nil
+  self:beginMsgLine()
+end
+
+-- Start typing the next line into the rolling window.  When the box already
+-- shows two lines, drop the top one and set the pixel scroll-up
+-- (ScrollTextUpOneLine), mirroring TextBox:beginLine.
+function BattleState:beginMsgLine()
+  self.lineIndex = self.lineIndex + 1
+  local ln = self.lines[self.lineIndex]
+  self.codes = ln and ln.codes or {}
+  if #self.shown >= 2 then
+    table.remove(self.shown, 1)
+    self.scrollPx = 8
+  end
+  self.shown[#self.shown + 1] = {}
 end
 
 function BattleState:updateQueue()
@@ -805,11 +875,50 @@ function BattleState:updateQueue()
     end
     self:startMessage(item)
   end
-  if self.charIndex < self.total then
-    self.charIndex = math.min(self.total, self.charIndex + 2)
-  else
-    local input = self.game.input
+  local input = self.game.input
+  -- a \v CONT wait holds the box until A/B, then scrolls the next line in
+  -- (home/text.asm ContText); this keeps a 3rd line on-screen (#216)
+  if self.msgWaiting then
     if input:wasPressed("a") or input:wasPressed("b") then
+      self.msgWaiting = nil
+      self:beginMsgLine()
+    end
+    return true
+  end
+  local cur = self.shown[#self.shown]
+  if #cur < #self.codes then
+    -- battle typewriter cadence: two glyphs per fixed step (as before)
+    for _ = 1, 2 do
+      if #cur >= #self.codes then break end
+      cur[#cur + 1] = self.codes[#cur + 1]
+      self.charIndex = self.charIndex + 1
+    end
+  elseif self.lineIndex < #self.lines then
+    -- current line finished, more lines remain: \v waits for A/B + ▼ before
+    -- scrolling, \n advances now (beginMsgLine scrolls if the box is full)
+    if self.lines[self.lineIndex + 1].cont then
+      self.msgWaiting = true
+    else
+      self:beginMsgLine()
+    end
+  else
+    local item = self.current
+    -- TrainerAboutToUseText ends in `done` then DisplayTextBoxID: YES/NO
+    -- overlays the still-visible "Will … change POKéMON?" page.
+    if item and item.choice and not item.choiceOpen then
+      item.choiceOpen = true
+      self.waitingUI = true
+      local ChoiceBox = require("src.ui.ChoiceBox")
+      local battle = self
+      self.game.stack:push(ChoiceBox.new(self.game, function(yes)
+        local fn = item.choice
+        battle.current = nil
+        fn(yes)
+      end))
+      return true
+    end
+    if not (item and item.choice)
+       and (input:wasPressed("a") or input:wasPressed("b")) then
       self.current = nil
     end
   end
@@ -1060,11 +1169,14 @@ function BattleState:update(dt)
   self:updateFx()
   local input = self.game.input
 
-  -- safety net: HP changed outside a queued drain (level-up heals,
-  -- field effects) snaps once the queue is idle
+  -- safety net: HP/status changed outside a queued drain (level-up heals,
+  -- field effects, bag cures) snaps once the queue is idle
   if self.phase == "menu" then
     for _, b in ipairs({ self.player, self.enemy }) do
-      if b and b.shownHP then b.shownHP = b.mon.hp end
+      if b then
+        if b.shownHP then b.shownHP = b.mon.hp end
+        b.shownStatus = b.mon.status
+      end
     end
   end
 
@@ -2145,90 +2257,105 @@ end
 -- move execution pipeline
 -- ---------------------------------------------------------------------
 
+-- Mirror DrawHUDsAndHPBars: reveal mon.status on the HUD only after the
+-- current action's queued anim/text have played (PoisonEffect sets the
+-- bit before PlayCurrentMoveAnimation2 + PrintText, but the HUD redraw
+-- waits until after Execute*Move returns).
+function BattleState:syncShownStatus()
+  for _, b in ipairs({ self.player, self.enemy }) do
+    if b then b.shownStatus = b.mon.status end
+  end
+end
+
 function BattleState:executeAction(user, target, action)
   if user.mon.hp <= 0 or target.mon.hp <= 0 then return end
   if not action then return end
 
-  -- ghost battles: the ghost never attacks; its whole turn is the
-  -- GetOutText (ExecuteEnemyMove -> PrintGhostText, core.asm:5462-5463)
-  if self.ghost and not user.isPlayer then
-    self:sayNext(self.data.text._GetOutText or "GHOST: Get out...\nGet out...")
-    return
-  end
-
-  -- refresh the held-in-place mirror before the status checks (see
-  -- lockedAction): the victim is held exactly while the opponent's
-  -- trapping bit is set -- including a counter sitting at 0 until the
-  -- end-of-turn CheckNumAttacksLeft clear
-  user.boundTurns = target.trappingTurns
-                    and math.max(1, target.trappingTurns) or nil
-
-  -- trainer class AI actions (engine/battle/trainer_ai.asm)
-  if action.special == "aiItem" then
-    self.aiUses = (self.aiUses or 1) - 1
-    for _, m in ipairs(TrainerAI.useItem(self, action.item)) do
-      self:sayNext(prefixEnemy(m, self.enemy))
-    end
-    self:drainNext()
-    require("src.core.Sound").play(self.data, "Heal_Ailment")
-    return
-  end
-  if action.special == "aiSwitch" then
-    self.aiUses = (self.aiUses or 1) - 1
-    local previous = self.enemy
-    local oldName = self.enemy.name
-    self.enemyIndex = action.index
-    self.enemy = makeBattler(self.data, self.enemyParty[action.index], false)
-    -- EnemySendOutFirstMon (core.asm:1314-1315): clears player's trap
-    clearTrapping(self.player)
-    self:syncSides()
-    Runtime.emit("battle.battler_switched", {
-      battle = self, side = self.sides[2], battler = self.enemy,
-      previous = previous,
-    })
-    self.aiUses = self:aiUsesFor()
-    markSeen(self.game, self.enemy.mon.species)
-    -- _AIBattleWithdrawText: "X with-/drew Y!"
-    self:sayNext(("%s with-\ndrew %s!"):format(self.trainer.name, oldName))
-    self:sayNext(("%s sent\nout %s!"):format(self.trainer.name, self.enemy.name))
-    return
-  end
-
-  -- special locked actions.  All of them still run the status gauntlet:
-  -- CheckPlayerStatusConditions (core.asm:3328-3583) evaluates sleep ->
-  -- freeze -> held-in-place -> flinch -> recharge -> disable tick ->
-  -- confusion -> paralysis BEFORE the bide/thrash/trapping handling.
-  if action.special == "recharge" then
-    -- only reaching .HyperBeamCheck consumes the flag (core.asm:3384-
-    -- 3392): sleep/freeze/held/flinch keep the mon recharging next turn
-    if self:preRechargeChecks(user, target) then return end
-    user.mustRecharge = nil
-    self:sayNext(("%s\nmust recharge!"):format(displayName(user)))
-    return
-  end
-  if action.special == "bound" then
-    if not target.trappingTurns then
-      -- the trap ended earlier this turn: the CANNOT_MOVE selection is
-      -- simply lost (ExecutePlayerMove returns immediately on $ff)
+  local function run()
+    -- ghost battles: the ghost never attacks; its whole turn is the
+    -- GetOutText (ExecuteEnemyMove -> PrintGhostText, core.asm:5462-5463)
+    if self.ghost and not user.isPlayer then
+      self:sayNext(self.data.text._GetOutText or "GHOST: Get out...\nGet out...")
       return
     end
-    -- sleep/freeze take precedence over the held-in-place message
-    if self:statusInterrupt(user, target) then return end
-    return
-  end
-  if action.special == "trapping" then
-    if self:statusInterrupt(user, target) then return end
-    self:continueTrapping(user, target)
-    return
-  end
-  if action.special == "bide" then
-    if self:statusInterrupt(user, target) then return end
-    self:continueBide(user, target)
-    return
-  end
 
-  if self:statusInterrupt(user, target) then return end
-  self:performMove(user, target, action, false)
+    -- refresh the held-in-place mirror before the status checks (see
+    -- lockedAction): the victim is held exactly while the opponent's
+    -- trapping bit is set -- including a counter sitting at 0 until the
+    -- end-of-turn CheckNumAttacksLeft clear
+    user.boundTurns = target.trappingTurns
+                      and math.max(1, target.trappingTurns) or nil
+
+    -- trainer class AI actions (engine/battle/trainer_ai.asm)
+    if action.special == "aiItem" then
+      self.aiUses = (self.aiUses or 1) - 1
+      for _, m in ipairs(TrainerAI.useItem(self, action.item)) do
+        self:sayNext(prefixEnemy(m, self.enemy))
+      end
+      self:drainNext()
+      require("src.core.Sound").play(self.data, "Heal_Ailment")
+      return
+    end
+    if action.special == "aiSwitch" then
+      self.aiUses = (self.aiUses or 1) - 1
+      local previous = self.enemy
+      local oldName = self.enemy.name
+      self.enemyIndex = action.index
+      self.enemy = makeBattler(self.data, self.enemyParty[action.index], false)
+      -- EnemySendOutFirstMon (core.asm:1314-1315): clears player's trap
+      clearTrapping(self.player)
+      self:syncSides()
+      Runtime.emit("battle.battler_switched", {
+        battle = self, side = self.sides[2], battler = self.enemy,
+        previous = previous,
+      })
+      self.aiUses = self:aiUsesFor()
+      markSeen(self.game, self.enemy.mon.species)
+      -- _AIBattleWithdrawText: "X with-/drew Y!"
+      self:sayNext(("%s with-\ndrew %s!"):format(self.trainer.name, oldName))
+      self:sayNext(("%s sent\nout %s!"):format(self.trainer.name, self.enemy.name))
+      return
+    end
+
+    -- special locked actions.  All of them still run the status gauntlet:
+    -- CheckPlayerStatusConditions (core.asm:3328-3583) evaluates sleep ->
+    -- freeze -> held-in-place -> flinch -> recharge -> disable tick ->
+    -- confusion -> paralysis BEFORE the bide/thrash/trapping handling.
+    if action.special == "recharge" then
+      -- only reaching .HyperBeamCheck consumes the flag (core.asm:3384-
+      -- 3392): sleep/freeze/held/flinch keep the mon recharging next turn
+      if self:preRechargeChecks(user, target) then return end
+      user.mustRecharge = nil
+      self:sayNext(("%s\nmust recharge!"):format(displayName(user)))
+      return
+    end
+    if action.special == "bound" then
+      if not target.trappingTurns then
+        -- the trap ended earlier this turn: the CANNOT_MOVE selection is
+        -- simply lost (ExecutePlayerMove returns immediately on $ff)
+        return
+      end
+      -- sleep/freeze take precedence over the held-in-place message
+      if self:statusInterrupt(user, target) then return end
+      return
+    end
+    if action.special == "trapping" then
+      if self:statusInterrupt(user, target) then return end
+      self:continueTrapping(user, target)
+      return
+    end
+    if action.special == "bide" then
+      if self:statusInterrupt(user, target) then return end
+      self:continueBide(user, target)
+      return
+    end
+
+    if self:statusInterrupt(user, target) then return end
+    self:performMove(user, target, action, false)
+  end
+  run()
+  -- after announce/anim/effect text (pokered DrawHUDsAndHPBars)
+  self:actNext(function() self:syncShownStatus() end)
 end
 
 -- Sleep / confusion onomatopoeia from Check*StatusConditions
@@ -2654,6 +2781,13 @@ function BattleState:enemyMonFainted()
     local levels, gained = Experience.apply(self.data, mon, self.enemy.def,
                                             self.enemy.mon.level, self.kind == "trainer",
                                             split, mon.traded)
+    -- Track level-ups for EvolveAfterBattle (OverworldState:afterBattle ->
+    -- Evolution.checkParty).  B-cancel leaves the mon at/above threshold;
+    -- without this gate it re-triggers after every later fight (#213).
+    if #levels > 0 then
+      self.leveledUp = self.leveledUp or {}
+      self.leveledUp[mon] = true
+    end
     Runtime.emit("battle.exp_gained", {
       battle = self, mon = mon, gained = gained, levels = levels,
     })
@@ -2663,12 +2797,15 @@ function BattleState:enemyMonFainted()
       -- _WithExpAllText / _BoostedText / _ExpPointsText; the EXP.ALL
       -- pass beats the traded boost (wBoostExpByExpAll checks first),
       -- and _ExpPointsText prints wExpAmountGained -- the raw share,
-      -- captured before the max-level cap (experience.asm:92-100)
+      -- captured before the max-level cap (experience.asm:92-100).
+      -- _BoostedText / _WithExpAllText end in the CONT code (\v, "...\011"
+      -- in data/generated/text.lua): the box waits for A/B + ▼ then scrolls
+      -- the amount line in, so it stays on-screen instead of at y=144 (#216).
       local tail = "%d EXP. Points!"
       if announce == "expAll" then
-        tail = "with EXP.ALL,\n" .. tail
+        tail = "with EXP.ALL,\v" .. tail
       elseif mon.traded then
-        tail = "a boosted\n" .. tail
+        tail = "a boosted\v" .. tail
       end
       self:sayNext(("%s gained\n" .. tail):format(name, gained))
     end
@@ -2681,6 +2818,17 @@ function BattleState:enemyMonFainted()
         require("src.core.Sound").play(game.data, "Level_Up")
         return StatBox.new(game, mon)
       end)
+      -- After PrintStatsBox, experience.asm reloads the active battler's
+      -- wBattleMon and runs DrawHUDsAndHPBars, so its HP bar reflects the
+      -- higher current HP.  Experience.lua:84 already raised mon.hp by
+      -- (newMaxHP - oldMaxHP); the party mon and the battler share one table
+      -- (makeBattler), so mon.stats.hp (the bar's denominator) jumps to the
+      -- new max instantly while the battler's shownHP numerator lags at the
+      -- old current HP -- the bar SHRINKS (#224).  Animate shownHP up to the
+      -- new current HP (house convention: potions drain the bar too, see
+      -- itemUsed) so the bar grows instead.  Only the active player battler
+      -- shares its table with the HUD; other party mons (EXP.ALL) have no bar.
+      if mon == self.player.mon then self:drainNext() end
       for _, moveId in ipairs(Experience.movesLearnedAt(
           self.data.pokemon[mon.species], lv)) do
         self:learnMove(mon, moveId)
@@ -2724,51 +2872,37 @@ function BattleState:enemyMonFainted()
     end
     if nextIndex then
       self.enemyIndex = nextIndex
-      -- SHIFT battle style (the default): announce the next mon and
-      -- offer a free switch (SET skips the prompt)
+      -- EnemySendOutFirstMon (core.asm:1366-1443): SHIFT offers a free
+      -- switch when party count > 1, the active mon is alive, and the
+      -- battle-style bit is clear.  pokered counts party slots (not
+      -- remaining HP); SET / single-mon / fainted active skip the prompt.
       local nextMon = self.enemyParty[self.enemyIndex]
       local nextName = nextMon.nickname or self.data.pokemon[nextMon.species].name
-      local style = (self.game.save.options or {}).battleStyle or "shift"
-      local healthy = 0
-      for _, mon in ipairs(self.game.save.party) do
-        if mon.hp > 0 then healthy = healthy + 1 end
-      end
-      if style ~= "set" and healthy > 1 and self.player.mon.hp > 0 then
-        self:say(("%s is\nabout to use\n%s!"):format(self.trainer.name, nextName))
-        self:say(("Will %s\nchange POKéMON?"):format(self.game.save.player.name))
-        local game = self.game
-        self:ui(function()
-          local ChoiceBox = require("src.ui.ChoiceBox")
-          return ChoiceBox.new(game, function(yes)
+      local style = tostring((self.game.save.options or {}).battleStyle or "shift")
+        :lower()
+      local partyCount = #self.game.save.party
+      -- SwitchPlayerMon runs AFTER TrainerSentOutText (core.asm:1436-1443)
+      local shiftSwitchMon = nil
+      if style ~= "set" and partyCount > 1 and self.player.mon.hp > 0 then
+        -- _TrainerAboutToUseText: "X is" / "about to use" then cont nick,
+        -- then para "Will PLAYER" / "change POKéMON?" with YES/NO.
+        self:say(("%s is\nabout to use"):format(self.trainer.name))
+        self:say(("%s!"):format(nextName))
+        self:sayChoice(
+          ("Will %s\nchange POKéMON?"):format(self.game.save.player.name),
+          function(yes)
             if not yes then return end
+            local game = self.game
             Screens.push(game, "PartyMenu", {
               battle = self,
+              forceSwitch = true,
               onSwitch = function(mon)
                 if mon ~= self.player.mon and mon.hp > 0 then
-                  local previous = self.player
-                  self.player = makeBattler(self.data, mon, true, game.save)
-                  clearTrapping(self.enemy) -- SendOutMon clears foe trap
-                  self:syncSides()
-                  Runtime.emit("battle.battler_switched", {
-                    battle = self, side = self.sides[1],
-                    battler = self.player, previous = previous,
-                  })
-                  self:markParticipant()
-                  self.nextInsert = 0
-                  self.sendingOut = true
-                  self:sayNext(self:sendOutText(self.player.name))
-                  self:animNext("POOF_ANIM", false)
-                  self:actNext(function()
-                    self.sendingOut = false
-                    -- SendOutMon (core.asm:1757-1762): poof, then the grow-in
-                    self:startGrowIn(self.player)
-                    require("src.core.Sound").playCry(self.data, self.player.mon.species)
-                  end)
+                  shiftSwitchMon = mon
                 end
               end,
             })
           end)
-        end)
       end
       self:act(function()
         local previous = self.enemy
@@ -2797,6 +2931,29 @@ function BattleState:enemyMonFainted()
           end)
         end)
       end)
+      -- SwitchPlayerMon after the enemy is out (core.asm:1436-1443)
+      self:act(function()
+        local mon = shiftSwitchMon
+        if not mon then return end
+        local previous = self.player
+        self.player = makeBattler(self.data, mon, true, self.game.save)
+        clearTrapping(self.enemy)
+        self:syncSides()
+        Runtime.emit("battle.battler_switched", {
+          battle = self, side = self.sides[1],
+          battler = self.player, previous = previous,
+        })
+        self:markParticipant()
+        self.nextInsert = 0
+        self.sendingOut = true
+        self:sayNext(self:sendOutText(self.player.name))
+        self:animNext("POOF_ANIM", false)
+        self:actNext(function()
+          self.sendingOut = false
+          self:startGrowIn(self.player)
+          require("src.core.Sound").playCry(self.data, self.player.mon.species)
+        end)
+      end)
       return
     end
     local prize = (self.trainer.baseMoney or 0) * self.enemy.mon.level
@@ -2920,6 +3077,8 @@ function BattleState:openReplacementMenu()
   self:ui(function()
     return self:buildScreen("PartyMenu", {
       battle = self,
+      -- ChooseNextMon: pick immediately (no SWITCH/STATS/CANCEL)
+      forceSwitch = true,
       onSwitch = function(mon)
         if mon.hp <= 0 then
           self:say("There's no will\nto fight!")
@@ -3130,6 +3289,9 @@ end
 
 -- called by BagMenu after an item is used in battle (consumes the turn)
 function BattleState:itemUsed(messages)
+  -- bag cures clear mon.status before the message UI; refresh the HUD
+  -- once control returns (pokered DrawHUDsAndHPBars after item use)
+  self:syncShownStatus()
   for _, m in ipairs(messages or {}) do self:say(m) end
   table.insert(self.queue, { drain = true }) -- potions animate the bar
   self:act(function()
@@ -3151,10 +3313,39 @@ function BattleState:ballMissMessage(shakes)
   return t._ItemUseBallText04 or "Shoot! It was so\nclose too!"
 end
 
+-- AskName (engine/menus/naming_screen.asm): ClearSprites, wild field blank,
+-- PrintText, YES/NO while text stays (TextBox opts.choice). Shared by party
+-- AddPartyMon and SendNewMonToBox (#172).
+function BattleState:askNicknameUI(mon, displayName)
+  local game = self.game
+  self.lockedBall = nil
+  self.blankForAskName = true
+  local TextBox = require("src.render.TextBox")
+  local text = ("Do you want to\ngive a nickname\nto %s?"):format(displayName)
+  local label = game.data.text and game.data.text._DoYouWantToNicknameText
+  if label then
+    -- extractor CONT is \t; TextBox scrolls on \n/\v
+    text = label:gsub("\t", "\n"):gsub("{RAM:?[%w_]*}", displayName)
+  end
+  return TextBox.new(game, text, nil, {
+    choice = function(yes)
+      self.blankForAskName = false
+      if not yes then return end
+      pcall(Screens.push, game, "NamingScreen", {
+        title = "NICKNAME?", maxLen = 10,
+        onDone = function(name)
+          if name and #name > 0 then mon.nickname = name end
+        end,
+      })
+    end,
+  })
+end
+
 -- The caught mon joins the party or a PC box (ItemUseBall .captured,
 -- item_effects.asm:518-566): the caught text, then for a NEW species
--- "New POKéDEX data will be added" + the dex entry page, then the
--- party add (with the nickname ask) or the PC transfer text.
+-- "New POKéDEX data will be added" + the dex entry page, then
+-- AddPartyMon or SendNewMonToBox (both call AskName), then the PC
+-- transfer text when the party was full.
 function BattleState:storeCaughtMon()
   -- ItemUseBall reloads the caught mon via LoadEnemyMonData
   -- (item_effects.asm:472-501), regenerating its move list from the
@@ -3174,31 +3365,20 @@ function BattleState:storeCaughtMon()
       return self:buildScreen("DexEntryMenu", species)
     end)
   end
-  if Party.add(game.save.party, self.enemy.mon) then
-    -- nickname prompt (AskName runs inside AddPartyMon; box mons are
-    -- never offered a nickname)
+  local function askCaughtNickname()
     local caught = self.enemy.mon
     local enemyName = self.enemy.name
     self:uiNext(function()
-      local ChoiceBox = require("src.ui.ChoiceBox")
-      local TextBox = require("src.render.TextBox")
-      return TextBox.new(game, ("Do you want to\ngive a nickname\nto %s?")
-          :format(enemyName), function()
-        game.stack:push(ChoiceBox.new(game, function(yes)
-          if not yes then return end
-          pcall(Screens.push, game, "NamingScreen", {
-            title = "NICKNAME?", maxLen = 10,
-            onDone = function(name)
-              if name and #name > 0 then caught.nickname = name end
-            end,
-          })
-        end))
-      end)
+      return self:askNicknameUI(caught, enemyName)
     end)
+  end
+  if Party.add(game.save.party, self.enemy.mon) then
+    askCaughtNickname()
   else
     destination = "box"
     local boxNum = require("src.pokemon.Boxes").deposit(game.save, self.enemy.mon)
     if boxNum then
+      askCaughtNickname()
       -- _ItemUseBallText07/08 keyed on EVENT_MET_BILL
       local pc = (game.save.flags and game.save.flags.EVENT_MET_BILL)
                  and "BILL's PC" or "someone's PC"
@@ -3449,12 +3629,15 @@ function BattleState:fxFaintActive(battler)
          and fx.faint.frames > 0 or false
 end
 
--- vertical slide offset for a fainting battler (the player's pic is
--- drawn 2x, so it slides 2x as fast to sink at the same visual rate)
-function BattleState:fxFaintOffset(battler)
+-- vertical slide offset for a fainting battler.  The offset is in screen
+-- pixels, so it scales with the pic's draw scale (the player's default 2x
+-- sinks 2x as fast to sink at the same visual rate); a mod scale composes
+-- the same way.  scale defaults to the vanilla side scale when unknown.
+function BattleState:fxFaintOffset(battler, scale)
   local fx = self.fx
   if self:fxFaintActive(battler) then
-    return (30 - fx.faint.frames) * 2 * (battler.isPlayer and 2 or 1)
+    scale = scale or (battler.isPlayer and 2 or 1)
+    return (30 - fx.faint.frames) * 2 * scale
   end
   return 0
 end
@@ -3550,7 +3733,7 @@ function BattleState:drawBattlerPic(battler, x, y, scale)
     return
   end
   if self:fxFaintActive(battler) then
-    local off = self:fxFaintOffset(battler)
+    local off = self:fxFaintOffset(battler, scale)
     local visible = img:getHeight() - math.floor(off / scale)
     if visible > 0 then
       local quad = love.graphics.newQuad(0, 0, img:getWidth(), visible,
@@ -3847,6 +4030,63 @@ function BattleState:drawAnimLayer(colorized)
   end
 end
 
+-- ------------------------------------------------------------------
+-- Mod-facing battle sprite scaling.  The enemy front pic draws at 1x and
+-- the player back pic at 2x on the GB; a mod can override either per
+-- species (pokemon.battleScaleFront / battleScaleBack) or per image path
+-- (the battle_sprite_scales registry, which is the only handle on the
+-- non-species pics like the trainer back).  These resolvers and the
+-- placement math are pure (no love.*) so the grounding contract -- feet
+-- pinned at any scale -- is unit-tested directly.
+-- ------------------------------------------------------------------
+
+-- the vanilla scale for a side: enemy front 1x, player back 2x
+BattleState.BATTLE_SCALE_DEFAULT = { front = 1, back = 2 }
+
+-- image-level override for an asset path, or nil.  scales is the merged
+-- data.battle_sprite_scales table (record id -> { path, scale }).
+function BattleState.imageBattleScale(scales, path)
+  if not scales or not path then return nil end
+  for id, rec in pairs(scales) do
+    if id ~= "_owners" and type(rec) == "table" and rec.path == path then
+      return rec.scale
+    end
+  end
+  return nil
+end
+
+-- effective battle scale for a pic: image-level override, else the
+-- species-level override for the side, else the side default.  side is
+-- "front" (enemy) or "back" (player); species may be nil (a non-species
+-- pic like the trainer back, which only image-level scaling reaches).
+function BattleState.resolveBattleScale(data, side, path, species)
+  local img = data and BattleState.imageBattleScale(data.battle_sprite_scales, path)
+  if img then return img end
+  local def = species and data and data.pokemon and data.pokemon[species]
+  local field = side == "back" and "battleScaleBack" or "battleScaleFront"
+  local override = def and def[field]
+  if override then return override end
+  return BattleState.BATTLE_SCALE_DEFAULT[side] or 1
+end
+
+-- Player (back) placement: feet flush on the text-box top (y=96) at any
+-- scale, with the left transparent columns pulled back so opaque pixels
+-- land where hardware's white-on-white columns left them.  Returns the
+-- top-left x, y and the scale (slide/shake offsets are added by the
+-- caller).  Feet stay at 96 for every scale: y + (h - pad) * scale == 96.
+function BattleState.backPlacement(w, h, pad, padL, scale)
+  return 8 - padL * scale, 96 - (h - pad) * scale, scale
+end
+
+-- Enemy (front) placement: given the s=1 slot origin (ex, ey) from the
+-- 7x7 tile layout, keep the bottom edge and horizontal centre pinned as
+-- the pic scales -- the same compensation AnimateSendingOutMon's grow
+-- uses.  Returns top-left x, y and the scale.  The bottom edge stays put
+-- for every scale: y + h * scale == ey + h.
+function BattleState.frontPlacement(ex, ey, w, h, scale)
+  return ex + w * (1 - scale) / 2, ey + h * (1 - scale), scale
+end
+
 -- Front/trainer pics: LoadUncompressedSpriteData centers the sprite in
 -- a 7x7 tile buffer, then CopyUncompressedPicToTilemap places that
 -- buffer at hlcoord 12,0.  Horizontal pad is floor((8-w)/2) tiles;
@@ -3890,16 +4130,23 @@ function BattleState:drawPicsLayer(slide, sx, sy)
     local img = self:picImage(self.enemy.sprite)
     love.graphics.setColor(1, 1, 1, 1)
     local ex, ey = enemyPicXY(img, slide, sx, sy)
+    local s = BattleState.resolveBattleScale(self.data, "front",
+      imagePathOf(img), self.enemy.mon and self.enemy.mon.species)
     local gs = self:growInScale(self.enemy)
     if gs then
       -- AnimateSendingOutMon: the downscaled pic keeps its bottom edge
-      -- and horizontal center pinned to the mon's slot while it grows
-      if gs > 0 then
-        love.graphics.draw(img, ex + img:getWidth() * (1 - gs) / 2,
-                           ey + img:getHeight() * (1 - gs), 0, gs, gs)
+      -- and horizontal center pinned to the mon's slot while it grows --
+      -- the mod scale composes multiplicatively with the grow stage
+      local eff = s * gs
+      if eff > 0 then
+        local dx, dy = BattleState.frontPlacement(ex, ey,
+          img:getWidth(), img:getHeight(), eff)
+        love.graphics.draw(img, dx, dy, 0, eff, eff)
       end
     else
-      self:drawBattlerPic(self.enemy, ex, ey, 1)
+      local dx, dy = BattleState.frontPlacement(ex, ey,
+        img:getWidth(), img:getHeight(), s)
+      self:drawBattlerPic(self.enemy, dx, dy, s)
     end
   end
 
@@ -3913,9 +4160,14 @@ function BattleState:drawPicsLayer(slide, sx, sy)
     local img = self:picImage(self.playerBackPic)
     local pad = imagePadBottom[self.playerBackPic] or 0
     local padL = imagePadLeft[self.playerBackPic] or 0
+    -- the trainer back is a bare pic, not species-keyed, so only an
+    -- image-level battle_sprite_scales entry can rescale it
+    local s = BattleState.resolveBattleScale(self.data, "back",
+      imagePathOf(self.playerBackPic), nil)
     love.graphics.setColor(1, 1, 1, 1)
-    love.graphics.draw(img, 8 - padL * 2 + slide + sx,
-                       96 - (img:getHeight() - pad) * 2 + sy, 0, 2, 2)
+    local dx, dy = BattleState.backPlacement(img:getWidth(), img:getHeight(),
+      pad, padL, s)
+    love.graphics.draw(img, dx + slide + sx, dy + sy, 0, s, s)
   elseif self.player and self.player.sprite and not hidePlayer
      and not self.sendingOut and not self:fxHidden(self.player) then
     local img = self:picImage(self.player.sprite)
@@ -3923,19 +4175,24 @@ function BattleState:drawPicsLayer(slide, sx, sy)
     -- feet flush on the text box top (y=96), ignoring baked-in padding
     local pad = imagePadBottom[self.player.sprite] or 0
     local padL = imagePadLeft[self.player.sprite] or 0
-    local px = 8 - padL * 2 + sx
+    local s = BattleState.resolveBattleScale(self.data, "back",
+      imagePathOf(self.player.sprite),
+      self.player.mon and self.player.mon.species)
     local gs = self:growInScale(self.player)
     if gs then
       -- the player-side AnimateSendingOutMon grow (after the poof,
-      -- core.asm:1757-1762): feet pinned at y=96, center at x=8+w
-      if gs > 0 then
-        love.graphics.draw(img, px + img:getWidth() * (1 - gs),
-                           96 - (img:getHeight() - pad) * 2 * gs + sy,
-                           0, 2 * gs, 2 * gs)
+      -- core.asm:1757-1762): feet pinned at y=96, horizontal centre
+      -- pinned, mod scale composed with the grow stage
+      local eff = s * gs
+      if eff > 0 then
+        love.graphics.draw(img,
+          8 - padL * s + img:getWidth() * s * (1 - gs) / 2 + sx,
+          96 - (img:getHeight() - pad) * eff + sy, 0, eff, eff)
       end
     else
-      self:drawBattlerPic(self.player, px,
-                          96 - (img:getHeight() - pad) * 2 + sy, 2)
+      local dx, dy = BattleState.backPlacement(img:getWidth(),
+        img:getHeight(), pad, padL, s)
+      self:drawBattlerPic(self.player, dx + sx, dy + sy, s)
     end
   end
   if clipped then
@@ -3953,11 +4210,19 @@ function BattleState:drawHUDs(slide)
   -- the HUD clears with the send-out text (ClearScreenArea,
   -- core.asm:1414-1417) and DrawEnemyHUDAndHPBar (1435) only redraws
   -- it after the grow-in + cry
-  local barData = self:colorMode() and {} or self.data -- gray fill when zoned
+  -- In colorized modes the zone pass (drawZonePass over BATTLE_ZONES pal 0/1)
+  -- recolors the bar's DMG gray fill by region, so drawHPBar must skip its
+  -- per-pixel tint (grayFill) -- otherwise GREENBAR's red-channel-0 fill
+  -- double-applies and the zone shade shader maps the whole bar to black (#229).
+  local grayFill = self:colorMode()
+  local barData = self.data
   local fx = self.fx
   local hudShake = (fx and fx.hudShakeX) or 0
+  -- FaintEnemyPokemon clears the enemy HUD area; it stays blank through
+  -- TrainerAboutToUseText until DrawEnemyHUDAndHPBar after the next send-out
   if self.enemy and not self.showEnemyTrainer and not self.enemySendingOut
-     and not self:growInScale(self.enemy) and slide == 0 then
+     and not self:growInScale(self.enemy) and slide == 0
+     and not self.enemy.fainted then
     -- enemy HUD (DrawEnemyHUDAndHPBar): name row 0, <LV>+level (4,1),
     -- HP bar (2,2) with the vertical tick at (1,2), underline row 3;
     -- AnimationShakeEnemyHUD nudges just this block via SCX
@@ -3967,15 +4232,16 @@ function BattleState:drawHUDs(slide)
     end
     love.graphics.setColor(0, 0, 0, 1)
     Font.draw(self.enemy.name, nameX(1, self.enemy.name), 0)
-    if self.enemy.mon.status then
-      Font.draw(self:statusLabel(self.enemy.mon), 40, 8)
+    if self.enemy.shownStatus then
+      Font.draw(self:statusLabel({ status = self.enemy.shownStatus }), 40, 8)
     else
       hudTile(0x6E, 32, 8) -- <LV>
       Font.draw(tostring(self.enemy.mon.level), 40, 8)
     end
     hudTile(0x73, 8, 16)
     drawHPBar(barData, 2, 2,
-              { hp = shownHP(self.enemy), stats = self.enemy.mon.stats })
+              { hp = shownHP(self.enemy), stats = self.enemy.mon.stats },
+              nil, grayFill)
     hudTile(0x74, 8, 24)
     for i = 2, 9 do hudTile(0x76, i * 8, 24) end
     hudTile(0x78, 80, 24)
@@ -4015,15 +4281,15 @@ function BattleState:drawHUDs(slide)
     -- the tick at (18,10) and the triangle at (9,11)
     love.graphics.setColor(0, 0, 0, 1)
     Font.draw(self.player.name, nameX(10, self.player.name), 56)
-    if self.player.mon.status then
-      Font.draw(self:statusLabel(self.player.mon), 120, 64)
+    if self.player.shownStatus then
+      Font.draw(self:statusLabel({ status = self.player.shownStatus }), 120, 64)
     else
       hudTile(0x6E, 112, 64) -- <LV>
       Font.draw(tostring(self.player.mon.level), 120, 64)
     end
     drawHPBar(barData, 10, 9,
               { hp = shownHP(self.player), stats = self.player.mon.stats },
-              1) -- wHPBarType 1: the $6D cap
+              1, grayFill) -- wHPBarType 1: the $6D cap
     Font.draw(("%3d/%3d"):format(shownHP(self.player), self.player.mon.stats.hp), 88, 80)
     hudTile(0x73, 144, 80)
     hudTile(0x77, 144, 88)
@@ -4036,16 +4302,27 @@ function BattleState:drawTextArea()
   Font.drawBox(0, 12, 20, 6)
   love.graphics.setColor(0, 0, 0, 1)
   if self.phase == "messages" and self.current then
-    local shown = 0
-    for li, codes in ipairs(self.lines) do
-      -- battle text uses every other tile row (hlcoord *,14 / *,16)
-      local y = 112 + (li - 1) * 16
-      for i = 1, #codes do
-        if shown >= self.charIndex then break end
-        Font.drawCode(codes[i], 8 + (i - 1) * 8, y)
-        shown = shown + 1
+    -- rolling 2-line window: shown[1] at row y=112, shown[2] at y=128 (battle
+    -- text uses every other tile row, hlcoord *,14 / *,16).  scrollPx animates
+    -- the lines up one row (ScrollTextUpOneLine) so a 3rd line scrolls into
+    -- view instead of drawing off-screen at y=144 (#216).
+    if self.scrollPx and self.scrollPx > 0 then
+      self.scrollPx = self.scrollPx - 2
+      if self.scrollPx <= 0 then self.scrollPx = nil end
+    end
+    local off = self.scrollPx or 0
+    local ys = { 112, 128 }
+    for li, line in ipairs(self.shown or {}) do
+      local y = (ys[li] or 128) + off
+      for i = 1, #line do
+        Font.drawCode(line[i], 8 + (i - 1) * 8, y)
       end
     end
+    -- the blinking down arrow ('▼', glyph $EE) while a \v CONT wait holds the
+    -- box, bottom-right of the box like TextBox / home/text.asm
+    if self.msgWaiting and self.frame % 60 < 30 then
+      Font.drawCode(0xEE, (0 + 20 - 2) * 8, (12 + 6 - 1) * 8 - 4)
+    end
   elseif self.phase == "menu" and self.demo then
     -- the old-man script (DisplayBattleMenu, core.asm:2038-2049): the
     -- standard menu, with the '▶' hand drawn by the scripted keystrokes
@@ -4122,6 +4399,13 @@ function BattleState:drawTextArea()
 end
 
 function BattleState:draw()
+  -- AskName: ClearSprites + wild ClearScreenArea — white field under the
+  -- nickname TextBox / YES/NO (naming_screen.asm); overlays draw on top.
+  if self.blankForAskName then
+    love.graphics.setColor(1, 1, 1, 1)
+    love.graphics.rectangle("fill", 0, 0, 160, 144)
+    return
+  end
   local fx = self.fx
   -- window shakes (SE_SHAKE_SCREEN / the enemy-hit vertical shake);
   -- the animations-off fallback keeps the old +-2 alternation

src/core/Data.lua

@@ -102,6 +102,39 @@ function Data:seedDefaults()
   -- after-battle rows so Blaine's SetEventRange deactivation and talk
   -- after-text work like the other gyms (scripts/CinnabarGym.asm).
   self:seedCinnabarGymTrainerHeaders()
+  -- #197: the Fighting Dojo Karate Master is text_asm, so the extractor
+  -- writes no header for him -- seed one so he engages on sight and has
+  -- his defeat / re-talk lines (same idea as the Cinnabar seed above).
+  self:seedFightingDojoKarateMaster()
+  -- #189: 1F cabin door order vs rooms map (survey zoom)
+  require("src.world.SsAnneLayout").apply(self.maps)
+end
+
+-- The Karate Master (FightingDojo.asm) is a text_asm object: his object has
+-- no def_trainers row (DisplayTextID routes to his ASM script), so the
+-- extractor emits headers only for the four blackbelts ([2]..[5]).  Seed
+-- object index [1] so he behaves like the real leader:
+--   * range 4 (matches the strongest blackbelt) -> CheckFightingMapTrainers
+--     spots the player in his DOWN line and he challenges on sight (#197),
+--   * battle = his pre-battle challenge, won = "Hwa! Arrgh! Beaten!",
+--   * after = the "Stay and train at Karate with us!" re-talk line.
+-- Deliberately NO `event`: EVENT_BEAT_KARATE_MASTER is owned by
+-- victories.lua (OPP_BLACKBELT#1) exactly like the gym leaders, and
+-- engageTrainer sets header.event *before* checkVictoryRewards runs -- if
+-- this header also set it, the reward's flag guard would early-return and
+-- swallow the prize dialogue.  trainerDefeated tracks him via
+-- defeatedTrainers[npc.id] like the leaders.
+function Data:seedFightingDojoKarateMaster()
+  local headers = self.trainer_headers
+  if not headers then return end
+  headers.FightingDojo = headers.FightingDojo or {}
+  if headers.FightingDojo[1] then return end
+  headers.FightingDojo[1] = {
+    range = 4,
+    battle = "_FightingDojoKarateMasterText",
+    won = "_FightingDojoKarateMasterDefeatedText",
+    after = "_FightingDojoKarateMasterStayAndTrainWithUsText",
+  }
 end
 
 function Data:seedCinnabarGymTrainerHeaders()

src/core/DiscordPresence.lua

@@ -38,8 +38,18 @@ local state = {
   unsubs = {},
   pid = nil,
   loggedAbsent = false, -- one quiet note when Discord isn't running
+  game = nil,          -- kept for the "friend clicked join" -> push a screen path
+  joinCode = nil,       -- the online-match/tournament code to advertise as a join secret, if any
+  joinKind = "match",   -- "match" (LinkState online) or "tournament"
+  partySize = 1,        -- current headcount for the party.size Discord shows
+  partyMax = 2,
+  subscribedJoin = false, -- SUBSCRIBE ACTIVITY_JOIN sent on this connection?
 }
 
+-- MSG_DONTWAIT differs by OS (Darwin 0x80, Linux 0x40); only used for the
+-- ongoing per-frame inbound poll, never for the one-time connect/handshake
+local MSG_DONTWAIT_BY_OS = { ["OS X"] = 0x80, Linux = 0x40 }
+
 local function disabledByEnv()
   return os.getenv("POKEPORT_NO_DISCORD") == "1"
       or os.getenv("POKEPORT_AUTOPILOT") ~= nil
@@ -378,6 +388,15 @@ local function connect()
     state.dirty = true
     state.lastSentKey = nil
     state.loggedAbsent = false
+    state.subscribedJoin = false
+    -- ask for "friend clicked join" dispatches; a plain outbound write, so
+    -- it's harmless to send even on Windows, where the inbound poll below
+    -- isn't implemented yet (see pollJoinRequest)
+    if sendFrame(OP_FRAME, Json.encode({
+      cmd = "SUBSCRIBE", evt = "ACTIVITY_JOIN", nonce = nonce(),
+    })) then
+      state.subscribedJoin = true
+    end
     Logger.info("discord: rich presence connected")
     return true
   end)
@@ -427,7 +446,7 @@ local function buildActivity()
     activityState = "At the title screen"
   end
 
-  return {
+  local activity = {
     details = details,
     state = activityState,
     timestamps = { start = state.startedAt },
@@ -436,10 +455,25 @@ local function buildActivity()
       large_text = "Pokemon Gen1Recomp",
     },
   }
+  -- a party/join-secret pair is what makes Discord show "Ask to Join" on
+  -- the profile card; the secret carries our own room/tournament code plus
+  -- a one-letter kind tag ("m"/"t") so the click handler on the other end
+  -- knows which screen to jump into -- Discord only echoes the string
+  -- back, so the kind has to ride inside it
+  if state.joinCode then
+    local kindTag = state.joinKind == "tournament" and "t" or "m"
+    activity.party = { id = "pokeport-" .. state.joinCode,
+                       size = { state.partySize, state.partyMax } }
+    activity.secrets = { join = "join:" .. kindTag .. ":" .. state.joinCode }
+  end
+  return activity
 end
 
 local function activityKey(activity)
-  return (activity.details or "") .. "|" .. (activity.state or "")
+  local partyKey = activity.party
+    and (activity.party.size[1] .. "/" .. activity.party.size[2]) or ""
+  return (activity.details or "") .. "|" .. (activity.state or "") .. "|"
+    .. (activity.secrets and activity.secrets.join or "") .. "|" .. partyKey
 end
 
 local function flush(force)
@@ -567,6 +601,96 @@ local function subscribe(game)
   end)
 end
 
+-- Advertise (or clear, with code=nil) an online-match/tournament code as a
+-- Discord join secret. LinkState/Tournament call this once they have a
+-- real code from the relay, and clear it again once paired/started or the
+-- hosting screen exits (an invite that's already full or gone is worse
+-- than no invite). kind is "match" (default) or "tournament"; size/max are
+-- the party.size Discord shows (default 1/2, a plain 1v1 room) -- a
+-- tournament passes its live roster count and a generous cap instead, and
+-- should call this again whenever the roster changes, not just once.
+function DiscordPresence.setJoinCode(code, kind, size, max)
+  pcall(function()
+    state.joinCode = code
+    state.joinKind = kind or "match"
+    state.partySize = size or 1
+    state.partyMax = max or 2
+    state.dirty = true
+    flush(false)
+  end)
+end
+
+-- A friend clicked "Ask to Join" on our profile and Discord delivered the
+-- secret back over this same connection. Only act from a safe spot (never
+-- yank the player out of a battle or an already-running link session) --
+-- "exploring"/"menu" are the coarse buckets subscribe() above already
+-- tracks; anything more specific (a shop, a dialogue box) is a rarer miss
+-- worth accepting rather than adding a second, finer-grained state tracker
+-- just for this.
+local function handleJoinRequest(secret)
+  if not secret or secret == "" then return end
+  if state.activity == "battle" then return end
+  local game = state.game
+  if not game or not game.stack then return end
+  local top = game.stack:top()
+  if top and top.stage and top.net then return end -- already in a link session
+  local kindTag, code = secret:match("^(%a):(.+)$")
+  if not kindTag then kindTag, code = "m", secret end -- older/plain secret: assume match
+  Runtime.emit("discord.join_requested", { code = code, kind = kindTag })
+  if kindTag == "t" then
+    local ok, Tournament = pcall(require, "src.link.Tournament")
+    if ok and Tournament.newJoinOnline then
+      game.stack:push(Tournament.newJoinOnline(game, code))
+    end
+  else
+    local ok, LinkState = pcall(require, "src.link.LinkState")
+    if ok and LinkState.newJoinOnline then
+      game.stack:push(LinkState.newJoinOnline(game, code))
+    end
+  end
+end
+
+-- non-blocking peek for an incoming ACTIVITY_JOIN dispatch. Unix (FFI)
+-- only for now: reading a Windows named pipe without risking a stall needs
+-- a HANDLE-level PeekNamedPipe that the plain io.open() connection below
+-- doesn't give us, so a Windows player's presence/party/join-secret still
+-- all work (they can still be seen and clicked), the click just isn't
+-- delivered back to their own game session yet.
+local function pollJoinRequest()
+  if state.isWindows or not state.ffi or not state.socket or not state.subscribedJoin then
+    return
+  end
+  pcall(function()
+    local ffi = state.ffi
+    local dontwait = MSG_DONTWAIT_BY_OS[love.system.getOS()] or 0
+    local hbuf = ffi.new("char[8]")
+    local n = ffi.C.recv(state.socket, hbuf, 8, dontwait)
+    if not n or tonumber(n) <= 0 then return end -- nothing waiting right now
+    local header = ffi.string(hbuf, 8)
+    local opcode = unpackU32(header:sub(1, 4))
+    local length = unpackU32(header:sub(5, 8))
+    if not opcode or not length or length < 0 or length > 65536 then return end
+    -- the body may lag the header by a packet; the connection's normal
+    -- (short-timeout) blocking read is fine here since it has already
+    -- announced its exact length
+    local body = length > 0 and readExact(length) or ""
+    if body == nil then return end
+    if opcode == 3 then -- PING -> PONG, keeps Discord from closing on us
+      sendFrame(4, body)
+      return
+    end
+    if opcode ~= 1 then return end
+    local decoded = Json.decode(body)
+    if decoded and decoded.evt == "ACTIVITY_JOIN" then
+      local secret = decoded.data and decoded.data.secret
+      if type(secret) == "string" and secret ~= "" then
+        if secret:sub(1, 5) == "join:" then secret = secret:sub(6) end
+        handleJoinRequest(secret)
+      end
+    end
+  end)
+end
+
 function DiscordPresence.init(game)
   local ok, err = pcall(function()
     DiscordPresence.shutdown()
@@ -579,6 +703,8 @@ function DiscordPresence.init(game)
     state.location = "Title screen"
     state.mapId = nil
     state.battleLabel = nil
+    state.joinCode = nil
+    state.game = game
     state.dirty = true
     state.nextReconnectAt = 0
     state.loggedAbsent = false
@@ -621,6 +747,7 @@ function DiscordPresence.update(_dt)
       end
       return
     end
+    pollJoinRequest()
     if state.dirty then flush(false) end
   end)
 end
@@ -649,10 +776,13 @@ function DiscordPresence.shutdown()
   state.lastSentKey = nil
   state.connected = false
   state.socket = nil
+  state.subscribedJoin = false
+  state.joinCode = nil
 end
 
 -- test / debug helpers
 DiscordPresence._state = state
 DiscordPresence.locationName = locationName
+DiscordPresence.handleJoinRequest = handleJoinRequest
 
 return DiscordPresence

src/core/Game.lua

@@ -8,7 +8,7 @@ local Logger = require("src.core.Logger")
 local Renderer = require("src.render.Renderer")
 local SaveData = require("src.core.SaveData")
 local StateStack = require("src.core.StateStack")
-local TouchInput = require("src.core.TouchInput")
+local TouchControls = require("src.core.TouchControls")
 local ModLoader = require("src.mods.Loader")
 local ModRuntime = require("src.mods.Runtime")
 local Screens = require("src.ui.Screens")
@@ -37,12 +37,15 @@ function Game:load()
   self.mods = ModLoader.new()
   self.mods:load(Data)
   self.modStatus = self.mods:status()
+  -- render pipelines dispatch off the merged dataset; point them at the
+  -- one the mods just merged into before anything can draw a frame
+  require("src.render.Pipelines").install(Data)
 
   self.input = Input
   Input:init()
 
-  self.touchInput = TouchInput
-  TouchInput:init()
+  self.touchControls = TouchControls
+  TouchControls:init()
 
   self.renderer = Renderer
   Renderer:init()
@@ -177,9 +180,6 @@ function Game:logicSpeed()
 end
 
 function Game:update(dt)
-  -- Touch timers / prior-frame auto-releases before the fixed step so
-  -- deferred A and edge pulses land in Input's press queue for this step.
-  TouchInput:update(dt)
   -- Fast-forward scales only the logic clock (see src/core/GameSpeed.lua).
   -- Give the accumulator room for one full frame at the current speed,
   -- or the anti-spiral clamp quietly caps every level above ~15X.
@@ -198,6 +198,9 @@ function Game:update(dt)
   -- Overworld tilt toggle tween: presentational, so it runs on the real
   -- frame dt (not the fixed logic step) for a smooth ~0.25s glide.
   require("src.render.Tilt").update(dt)
+  -- mod render pipelines tween on the same real-frame clock, for the same
+  -- reason: they are presentational, so fast-forward must not speed them up
+  require("src.render.Pipelines").update(dt)
   pcall(function() require("src.core.DiscordPresence").update(dt) end)
   -- Steady-state memory backstop: advance the incremental collector one
   -- small step every rendered frame.  The heavy GPU objects are now freed
@@ -240,6 +243,8 @@ function Game:draw()
     worldZones = self.overworld:sgbWorldZones()
   end
   Renderer:endFrame(zones, worldZones)
+  -- on-screen mobile controls: pure screen-space, over the finished frame
+  TouchControls:draw()
 end
 
 -- overworld survey zoom: wheel up / '=' zooms in, wheel down / '-' out
@@ -341,6 +346,17 @@ function Game:keypressed(key)
     self:writeOptions()
     return
   end
+  -- Mod render pipelines claim their hotkeys last, so one can never shadow
+  -- an engine display key however a mod declares it (12 §rendering
+  -- pipelines).  syncOptions writes the whole ladder back, including the
+  -- tilt exclusion a world pipeline forces.
+  local Pipelines = require("src.render.Pipelines")
+  if Pipelines.hotkey(key, self.stack:top(), self.overworld) then
+    Pipelines.syncOptions(self.save.options)
+    require("src.render.Tilt").setLevel(self.save.options.tilt or 0)
+    self:writeOptions()
+    return
+  end
   Input:keypressed(key)
 end
 
@@ -358,6 +374,9 @@ function Game:keyreleased(key)
 end
 
 function Game:gamepadpressed(joystick, button)
+  -- a controller is being used: the touch overlay steps aside until the
+  -- next screen touch (mobile only; a no-op elsewhere)
+  TouchControls:noteGamepad()
   -- BindingsMenu's pad capture rides the same top-state routing as keys
   local top = self.stack and self.stack:top()
   if top and top.onGamepadPressed then
@@ -372,6 +391,8 @@ function Game:gamepadreleased(joystick, button)
 end
 
 function Game:gamepadaxis(joystick, axis, value)
+  -- past-deadzone only, so resting-stick drift can't hide the overlay
+  if math.abs(value) > 0.5 then TouchControls:noteGamepad() end
   Input:gamepadaxis(joystick, axis, value)
 end
 
@@ -381,12 +402,12 @@ end
 -- state is worse than asking the player to re-press.
 function Game:focus(f)
   Input:reset()
-  TouchInput:reset()
+  TouchControls:reset()
 end
 
 function Game:visible(v)
   Input:reset()
-  TouchInput:reset()
+  TouchControls:reset()
 end
 
 -- A disconnected/dropped controller can't send the button-up for whatever
@@ -394,19 +415,19 @@ end
 -- flags it owned.
 function Game:joystickremoved(joystick)
   Input:reset()
-  TouchInput:reset()
+  TouchControls:joystickremoved()
 end
 
 function Game:touchpressed(id, x, y)
-  TouchInput:touchpressed(id, x, y)
+  TouchControls:touchpressed(id, x, y)
 end
 
 function Game:touchmoved(id, x, y)
-  TouchInput:touchmoved(id, x, y)
+  TouchControls:touchmoved(id, x, y)
 end
 
 function Game:touchreleased(id, x, y)
-  TouchInput:touchreleased(id, x, y)
+  TouchControls:touchreleased(id, x, y)
 end
 
 -- Point the loader's mod.save backing at this save's modData so per-mod
@@ -457,6 +478,9 @@ function Game:applyOptions(opts)
   if Sound.applyOptions then Sound.applyOptions(opts) end
   require("src.render.PaletteFX").applyOptions(opts)
   require("src.render.Tilt").applyOptions(opts)
+  -- after Tilt, so a persisted world pipeline can switch the tilt level it
+  -- just restored back off (the two are mutually exclusive)
+  require("src.render.Pipelines").applyOptions(opts)
   require("src.render.Zoom").applyOptions(opts)
   require("src.render.TileRenderer").applyOptions(opts)
   -- returns true when a persisted GBC FX level was cleared on mobile

src/core/Input.lua

@@ -154,6 +154,17 @@ function Input:step()
   self.pressQueue = {}
 end
 
+-- The on-screen touch overlay (src/core/TouchControls.lua) presses GB
+-- buttons directly by name -- not through a keyboard alias -- so a player
+-- rebind can never detach or shadow the overlay.
+function Input:overlayPressed(btn)
+  press(self, btn, "touch:" .. btn)
+end
+
+function Input:overlayReleased(btn)
+  release(self, btn, "touch:" .. btn)
+end
+
 function Input:gamepadpressed(joystick, button)
   local btn = self.padBindings[button]
   if btn then

src/core/SaveData.lua

@@ -17,6 +17,7 @@ local Runtime = require("src.mods.Runtime")
 local Semver = require("src.mods.Semver")
 local Boxes = require("src.pokemon.Boxes")
 local Bag = require("src.inventory.Bag")
+local Badges = require("src.inventory.Badges")
 
 local GameVersion = require("src.core.GameVersion")
 
@@ -31,10 +32,11 @@ local OPTIONS_FILENAME = "options.lua"
 -- Main / backup / staged-witness names for a version (defaults to the active
 -- one).  The backup is a rolling copy and .tmp is the staged-write witness;
 -- load promotes either when the main file is missing or fails to parse.
-local function saveNames(version)
-  local main = "save" .. GameVersion.saveSuffix(version) .. ".lua"
-  return main, main .. ".bak", main .. ".tmp"
-end
+-- Forward-declared here so saveFilename (just below) and every save/load
+-- caller share the one upvalue; the body is filled in under "save slots"
+-- once the options IO it depends on exists, because it now resolves the
+-- ACTIVE slot for a version rather than the fixed flat name.
+local saveNames
 
 -- The main save filename for a version -- used by the title screen's
 -- CONTINUE gate so it looks for the right game's save.
@@ -91,6 +93,18 @@ local function makePortableFs(dir)
       os.remove(full(name))
       return true
     end,
+    createDirectory = function(name)
+      -- portable mode writes real files through io.*, which will not
+      -- create missing parent directories; mkdir the tree so a slot path
+      -- like "saves/red" exists before a write lands inside it
+      local osPath = full(name):gsub("/", SEP)
+      if SEP == "\\" then
+        os.execute('mkdir "' .. osPath .. '" 2>nul')
+      else
+        os.execute('mkdir -p "' .. osPath .. '" 2>/dev/null')
+      end
+      return true
+    end,
   }
 end
 
@@ -198,6 +212,11 @@ function SaveData.defaultOptions()
     videoMode = "windowed",
     -- hard render frame-rate cap; render-only pacing (issue #88, FrameCap.lua)
     fpsCap = 60,
+    -- Per-pipeline display levels, keyed by render_pipelines id (see
+    -- src/render/Pipelines.lua).  A level for a mod that is not installed
+    -- is kept rather than pruned, so re-enabling the mod restores the mode
+    -- the player left it in.
+    pipelines = {},
     -- Native mod enablement is an installation option, not save-slot data.
     -- Missing entries mean enabled so newly installed mods work by default.
     mods = {},
@@ -283,6 +302,264 @@ function SaveData.loadOptions(fs)
   return SaveData.mergeOptions(data)
 end
 
+-- ------- save slots
+
+-- A version's playthroughs live in numbered slots under saves/<version>/;
+-- the active slot is where in-game SAVE and CONTINUE land.  The registry
+-- (the ordered slot list plus which one is active) persists in options.lua
+-- under options.saveSlots[version]; the active slot is also cached
+-- process-wide (like GameVersion.current) so the hot saveNames path does
+-- not re-read options every call.  A false cache entry means "no slot in
+-- use" and the flat legacy path (save.lua / save_blue.lua) is used, which
+-- keeps a brand-new install and every pre-slots caller working unchanged.
+local activeSlotCache = {}   -- version -> slotId in use, or false when none
+local slotsChecked = {}      -- version -> true once resolved this process
+
+local function slotDir(version) return "saves/" .. version end
+
+local function slotNames(version, id)
+  local main = slotDir(version) .. "/" .. id .. ".lua"
+  return main, main .. ".bak", main .. ".tmp"
+end
+
+-- the pre-slots flat names a version always used (save.lua for Red,
+-- save_blue.lua for Blue); still the destination before any slot exists
+local function legacyNames(version)
+  local main = "save" .. GameVersion.saveSuffix(version) .. ".lua"
+  return main, main .. ".bak", main .. ".tmp"
+end
+
+-- Slot resolution is only meaningful for versions GameVersion actually knows
+-- (red/blue).  The launcher also renders a locked placeholder tab ("yellow")
+-- that has no info entry and therefore no saveSuffix; resolving its legacy
+-- names would index a nil info table and crash.  Treat any unknown version as
+-- having no slots so the slot APIs degrade to empty/no-op instead.
+local function knownVersion(version)
+  return GameVersion.info(version) ~= nil
+end
+
+-- Create the parent directory of a slot path when the fs supports it.
+-- love.filesystem.createDirectory makes the whole tree; the injected memfs
+-- stub keys files by full path and exposes no such method, so this is a
+-- no-op there.
+local function ensureParentDir(fs, name)
+  local dir = name:match("^(.*)/[^/]+$")
+  if dir and fs.createDirectory then fs.createDirectory(dir) end
+end
+
+-- Decode a slot's save using the same recovery order load() uses -- main,
+-- then the .tmp write-witness, then the .bak -- so a slot mid-crash still
+-- summarizes.  nil when nothing readable is present.
+local function decodeSlot(fs, version, id)
+  local main, bak, tmp = slotNames(version, id)
+  local data = fs.getInfo(main) and SaveSerializer.decode(fs.read(main) or "")
+  if data then return data end
+  data = fs.getInfo(tmp) and SaveSerializer.decode(fs.read(tmp) or "")
+  if data then return data end
+  data = fs.getInfo(bak) and SaveSerializer.decode(fs.read(bak) or "")
+  return data or nil
+end
+
+-- One-time legacy consolidation: a pre-slots install has a flat save file
+-- (+ .bak) and no saves/<version>/ registry.  Copy both into slot1, verify
+-- the copy reads back, then remove the originals and register slot1 as the
+-- active slot.  Returns the new slot id, or nil when there is nothing to
+-- migrate or the copy could not be verified (originals left in place so no
+-- data is ever lost to a failed move).
+local function tryMigrateLegacy(version, fs)
+  local lmain, lbak, ltmp = legacyNames(version)
+  local mainBody = fs.getInfo(lmain) and fs.read(lmain)
+  local bakBody = fs.getInfo(lbak) and fs.read(lbak)
+  if not (mainBody or bakBody) then return nil end
+  local id = "slot1"
+  local dmain, dbak = slotNames(version, id)
+  ensureParentDir(fs, dmain)
+  if mainBody then fs.write(dmain, mainBody) end
+  if bakBody then fs.write(dbak, bakBody) end
+  -- refuse to delete the originals unless the new slot is loadable (from
+  -- the main copy or, failing that, the backup)
+  if not decodeSlot(fs, version, id) then return nil end
+  remove(fs, lmain)
+  remove(fs, lbak)
+  remove(fs, ltmp)
+  local opts = SaveData.loadOptions(fs)
+  opts.saveSlots = opts.saveSlots or {}
+  opts.saveSlots[version] = { list = { id }, active = id }
+  SaveData.saveOptions(opts, fs)
+  return id
+end
+
+-- Resolve (once per version per process) which slot in-game saves use: an
+-- existing registry wins; otherwise a lazy legacy migration may create
+-- slot1; otherwise false, meaning the flat legacy path.
+local function ensureVersionSlots(version, fs)
+  if slotsChecked[version] then return end
+  slotsChecked[version] = true
+  if not knownVersion(version) then
+    activeSlotCache[version] = false
+    return
+  end
+  local opts = SaveData.loadOptions(fs)
+  local reg = opts.saveSlots and opts.saveSlots[version]
+  if reg and type(reg.list) == "table" and #reg.list > 0 then
+    activeSlotCache[version] = reg.active or reg.list[1]
+    return
+  end
+  activeSlotCache[version] = tryMigrateLegacy(version, fs) or false
+end
+
+-- (body for the forward-declared saveNames.)  Resolves the ACTIVE slot for
+-- the version, falling back to the flat legacy names when no slot is in use.
+function saveNames(version)
+  version = version or GameVersion.get()
+  local fs = persistFs(nil)
+  ensureVersionSlots(version, fs)
+  local slot = activeSlotCache[version]
+  if slot then return slotNames(version, slot) end
+  return legacyNames(version)
+end
+
+-- Pure extraction of the launcher's per-slot summary from a decoded save,
+-- factored out so it is unit-testable with no filesystem: the player name
+-- (nil for an empty slot) and { badges, timeText, dexCount } -- the same
+-- fields the title screen's ContinueInfo derives.  Badges resolve against
+-- the vanilla gym list (launcher has no loaded Data), which is what the
+-- flat launcher meta line needs.
+function SaveData.slotSummary(save)
+  if type(save) ~= "table" then return nil, nil end
+  local name = save.player and save.player.name or nil
+  local dexCount = 0
+  for _ in pairs((save.pokedex and save.pokedex.owned) or {}) do
+    dexCount = dexCount + 1
+  end
+  local t = math.floor(save.playTime or 0)
+  local timeText = ("%d:%02d"):format(math.floor(t / 3600),
+                                      math.floor(t / 60) % 60)
+  return name, {
+    badges = Badges.count(nil, save),
+    timeText = timeText,
+    dexCount = dexCount,
+  }
+end
+
+-- Slots visible to the launcher: every registered slot for a version, each
+-- with whether it holds a save and the cheap summary above.  A fresh
+-- install with nothing registered returns an empty array; a legacy install
+-- is migrated to slot1 first.
+function SaveData.listSlots(version)
+  version = version or GameVersion.get()
+  if not knownVersion(version) then return {} end
+  local fs = persistFs(nil)
+  ensureVersionSlots(version, fs)
+  local opts = SaveData.loadOptions(fs)
+  local reg = opts.saveSlots and opts.saveSlots[version]
+  local list = (reg and reg.list) or {}
+  local out = {}
+  for _, id in ipairs(list) do
+    local save = decodeSlot(fs, version, id)
+    local name, meta = SaveData.slotSummary(save)
+    out[#out + 1] = { id = id, exists = save ~= nil, name = name, meta = meta }
+  end
+  return out
+end
+
+-- Point the active slot at slotId (registering it if new) and persist the
+-- choice to options.lua; also update the process-global cache so the very
+-- next save/load lands in the chosen slot.
+function SaveData.setActiveSlot(version, slotId)
+  version = version or GameVersion.get()
+  if not knownVersion(version) then return nil end
+  local fs = persistFs(nil)
+  local opts = SaveData.loadOptions(fs)
+  opts.saveSlots = opts.saveSlots or {}
+  local reg = opts.saveSlots[version] or { list = {}, active = nil }
+  local found = false
+  for _, id in ipairs(reg.list) do
+    if id == slotId then found = true break end
+  end
+  if not found then reg.list[#reg.list + 1] = slotId end
+  reg.active = slotId
+  opts.saveSlots[version] = reg
+  SaveData.saveOptions(opts, fs)
+  slotsChecked[version] = true
+  activeSlotCache[version] = slotId
+  return slotId
+end
+
+-- Register a new empty slot for the version and return its id.  Does NOT
+-- write a save file and does NOT change the active slot: an empty slot
+-- means the title screen offers NEW GAME only.  Ids are "slot%d+",
+-- allocated one past the highest existing number so a reused id can never
+-- collide with a lingering file.
+function SaveData.createSlot(version)
+  version = version or GameVersion.get()
+  if not knownVersion(version) then return nil end
+  local fs = persistFs(nil)
+  ensureVersionSlots(version, fs)
+  local opts = SaveData.loadOptions(fs)
+  opts.saveSlots = opts.saveSlots or {}
+  local reg = opts.saveSlots[version] or { list = {}, active = nil }
+  local maxN = 0
+  for _, id in ipairs(reg.list) do
+    local n = tonumber(tostring(id):match("^slot(%d+)$"))
+    if n and n > maxN then maxN = n end
+  end
+  local id = "slot" .. (maxN + 1)
+  reg.list[#reg.list + 1] = id
+  opts.saveSlots[version] = reg
+  SaveData.saveOptions(opts, fs)
+  return id
+end
+
+-- The active slot id in use for a version (resolved once per process like
+-- saveNames does), or nil when none is registered and the flat legacy path is
+-- in use.  Public so the launcher's save Import/Export glue can name an export
+-- after the slot it came from without reaching into the private cache.
+function SaveData.activeSlot(version)
+  version = version or GameVersion.get()
+  if not knownVersion(version) then return nil end
+  local fs = persistFs(nil)
+  ensureVersionSlots(version, fs)
+  return activeSlotCache[version] or nil
+end
+
+-- Write saveTable into an existing slot's file (SaveSerializer.encode), through
+-- the same fs seam every other save/load call uses (so portable mode keeps
+-- working) and the same .tmp-witness / .bak recovery discipline SaveData.save
+-- uses for the flat path.  Used by the launcher's save-import glue, which has
+-- already registered the slot via createSlot but written no bytes yet; unlike
+-- SaveData.save this targets a specific slot and never rebuilds meta or touches
+-- options.  Returns true, or false + an error string on a failed write.
+function SaveData.writeSlot(version, slotId, saveTable)
+  version = version or GameVersion.get()
+  if not knownVersion(version) then return false, "unknown version" end
+  if type(slotId) ~= "string" then return false, "missing slot id" end
+  if type(saveTable) ~= "table" then return false, "missing save table" end
+  local main, bak, tmp = slotNames(version, slotId)
+  local encoded = SaveSerializer.encode(saveTable)
+  local fs = persistFs(nil)
+  ensureParentDir(fs, main)
+  if fs.getInfo(main) then
+    local prev = fs.read(main)
+    if prev then fs.write(bak, prev) end
+  end
+  local ok, err = fs.write(tmp, encoded)
+  if not ok then return false, err end
+  remove(fs, main)
+  ok, err = fs.write(main, encoded)
+  if not ok then return false, err end
+  remove(fs, tmp)
+  return true
+end
+
+-- Test seam: drop the process-global slot cache so a suite can exercise
+-- migration/resolution against a freshly injected filesystem.  Unused by
+-- the game, which resolves each version exactly once per boot.
+function SaveData.resetSlotState()
+  for k in pairs(activeSlotCache) do activeSlotCache[k] = nil end
+  for k in pairs(slotsChecked) do slotsChecked[k] = nil end
+end
+
 -- ------- meta
 
 -- the version/engine/mod-set stamp every v2 save carries; mods is the
@@ -525,6 +802,9 @@ function SaveData.save(data, mods)
   end
   local encoded = SaveSerializer.encode(gameOnly)
   local fs = persistFs(nil)
+  -- the active slot may live in saves/<version>/, which must exist before
+  -- the .tmp/.bak/main writes land (a no-op for the flat legacy path)
+  ensureParentDir(fs, FILENAME)
   if fs.getInfo(FILENAME) then
     local prev = fs.read(FILENAME)
     if prev then fs.write(BACKUP_FILENAME, prev) end

src/core/TouchControls.lua

@@ -0,0 +1,287 @@
+-- On-screen touch controls: a visible d-pad, A, B, START and SELECT drawn
+-- over the finished frame (art: Xelu's CC0 controller prompts, see
+-- assets/touch/README.md).  Replaces the old touch gesture recognizer:
+-- every control is a real button under the thumb, so there is no
+-- tap-vs-swipe classification, no deferred-A double-tap window, and no
+-- added latency.
+--
+-- Mobile only, and only while no controller is being used: the overlay
+-- shows on Android/iOS, disappears the moment a gamepad button or stick
+-- is used, and comes back on the next screen touch (Game routes both
+-- events here).  POKEPORT_TOUCH=1 forces it on for desktop testing
+-- (main.lua then drives it with the mouse); POKEPORT_TOUCH=0 forces it
+-- off everywhere.
+--
+-- Controls press GB buttons through Input:overlayPressed/Released -- their
+-- own input source, not a keyboard alias -- so a held overlay direction
+-- merges cleanly with a keyboard key or stick holding the same button,
+-- and a player rebind can never detach the overlay.
+
+local Input = require("src.core.Input")
+
+local TouchControls = {}
+
+-- idle vs pressed overlay opacity
+local ALPHA = 0.65
+local ALPHA_PRESSED = 0.95
+-- translucent backing disc behind each control: the prompt art is dark
+-- gray, so without it the controls melt into dark map areas
+local BACK = 0.24
+local BACK_PRESSED = 0.38
+
+-- neutral zone at the d-pad center, as a fraction of the d-pad width;
+-- inside it no direction is held (keeps a resting thumb from jittering)
+local DPAD_DEAD = 0.16
+
+-- hit slop: how far past the visible edge a press still counts, as a
+-- multiplier on the control's half-width.  START/SELECT get more because
+-- the glyphs are small.
+local SLOP = { a = 1.3, b = 1.3, start = 1.4, select = 1.4 }
+
+local BUTTONS = { "a", "b", "start", "select" }
+
+local IMAGES = {
+  dpad = "assets/touch/dpad.png",
+  dpad_up = "assets/touch/dpad_up.png",
+  dpad_down = "assets/touch/dpad_down.png",
+  dpad_left = "assets/touch/dpad_left.png",
+  dpad_right = "assets/touch/dpad_right.png",
+  a = "assets/touch/a.png",
+  b = "assets/touch/b.png",
+  start = "assets/touch/start.png",
+  select = "assets/touch/select.png",
+}
+
+local function wantsOverlay()
+  local env = os.getenv("POKEPORT_TOUCH")
+  if env == "1" then return true end
+  if env == "0" then return false end
+  local osName = love.system and love.system.getOS and love.system.getOS()
+  return osName == "Android" or osName == "iOS"
+end
+
+function TouchControls:init()
+  self.active = wantsOverlay()
+  self.controllerHidden = false
+  self.touches = {}
+  -- per-GB-button owner count: two fingers on A must not double-press it,
+  -- and lifting one of them must not release the other's hold
+  self.held = {}
+  self.dpadTouch = nil
+  self.layoutW, self.layoutH = nil, nil
+  self.img = nil
+  if not self.active then return end
+  -- soft-fail: a missing/corrupt PNG must never block boot; the overlay
+  -- stays off and keyboard/controller play still works
+  local img = {}
+  for name, path in pairs(IMAGES) do
+    local ok, im = pcall(love.graphics.newImage, path)
+    if not ok then
+      img = nil
+      break
+    end
+    -- smooth UI icons; the global default filter is nearest for GB pixels
+    im:setFilter("linear", "linear")
+    img[name] = im
+  end
+  self.img = img
+end
+
+function TouchControls:visible()
+  return self.active and self.img ~= nil and not self.controllerHidden
+end
+
+-- Layout in LOVE units (density-independent on mobile), recomputed when
+-- the window size changes (rotation, resize).  D-pad bottom-left, B/A
+-- bottom-right with A above B (the Game Boy diagonal), START/SELECT
+-- flanking the bottom center.
+function TouchControls:layout()
+  local ww, wh = love.graphics.getDimensions()
+  if self.layoutW == ww and self.layoutH == wh then return self.L end
+  self.layoutW, self.layoutH = ww, wh
+  local short = math.min(ww, wh)
+  -- ~a third of the short edge, capped so tablets don't get a dinner plate
+  local dpadW = math.min(180, short * 0.34)
+  local abW = dpadW * 0.46
+  local ssW = dpadW * 0.30
+  local margin = dpadW * 0.12
+  -- START/SELECT hug the bottom center: on a narrow portrait phone the
+  -- d-pad and B leave little room, so a tight pair is what keeps them off
+  -- the neighboring controls
+  self.L = {
+    dpad = { cx = margin + dpadW / 2, cy = wh - margin - dpadW / 2, w = dpadW },
+    a = { cx = ww - margin - abW * 0.55, cy = wh - margin - abW * 1.75, w = abW },
+    b = { cx = ww - margin - abW * 1.60, cy = wh - margin - abW * 0.55, w = abW },
+    start = { cx = ww / 2 + ssW * 0.60, cy = wh - margin - ssW * 0.95, w = ssW },
+    select = { cx = ww / 2 - ssW * 0.60, cy = wh - margin - ssW * 0.95, w = ssW },
+  }
+  local fontSize = math.max(8, math.floor(ssW * 0.26))
+  if not self.labelFont or self.fontSize ~= fontSize then
+    self.fontSize = fontSize
+    self.labelFont = love.graphics.newFont(fontSize)
+  end
+  return self.L
+end
+
+local function inCircle(zone, x, y, slop)
+  local r = zone.w * 0.5 * slop
+  local dx, dy = x - zone.cx, y - zone.cy
+  return dx * dx + dy * dy <= r * r
+end
+
+local function dpadDir(zone, x, y)
+  local dx, dy = x - zone.cx, y - zone.cy
+  local dead = zone.w * DPAD_DEAD
+  if math.abs(dx) < dead and math.abs(dy) < dead then return nil end
+  if math.abs(dx) >= math.abs(dy) then
+    return dx > 0 and "right" or "left"
+  end
+  return dy > 0 and "down" or "up"
+end
+
+local function pressBtn(self, btn)
+  local n = (self.held[btn] or 0) + 1
+  self.held[btn] = n
+  if n == 1 then Input:overlayPressed(btn) end
+end
+
+local function releaseBtn(self, btn)
+  local n = self.held[btn]
+  if not n then return end
+  if n > 1 then
+    self.held[btn] = n - 1
+  else
+    self.held[btn] = nil
+    Input:overlayReleased(btn)
+  end
+end
+
+-- the d-pad touch's held direction changed (or ended): swap the GB hold
+local function setDpad(self, touch, dir)
+  if touch.dir == dir then return end
+  if touch.dir then releaseBtn(self, touch.dir) end
+  touch.dir = dir
+  if dir then pressBtn(self, dir) end
+end
+
+function TouchControls:touchpressed(id, x, y)
+  if not (self.active and self.img) then return end
+  -- a controller hid the overlay; the first touch only brings it back
+  if self.controllerHidden then
+    self.controllerHidden = false
+    return
+  end
+  local L = self:layout()
+  for _, btn in ipairs(BUTTONS) do
+    if inCircle(L[btn], x, y, SLOP[btn]) then
+      self.touches[id] = { control = btn }
+      pressBtn(self, btn)
+      return
+    end
+  end
+  -- square hit zone a bit past the cross art; one owning finger at a time
+  local dz = L.dpad
+  local half = dz.w * 0.65
+  if not self.dpadTouch
+     and math.abs(x - dz.cx) <= half and math.abs(y - dz.cy) <= half then
+    self.dpadTouch = id
+    local touch = { control = "dpad", dir = nil }
+    self.touches[id] = touch
+    setDpad(self, touch, dpadDir(dz, x, y))
+  end
+end
+
+function TouchControls:touchmoved(id, x, y)
+  local touch = self.touches[id]
+  -- only the d-pad tracks movement (slide between directions without
+  -- lifting); buttons hold until release wherever the finger wanders
+  if not touch or touch.control ~= "dpad" then return end
+  setDpad(self, touch, dpadDir(self:layout().dpad, x, y))
+end
+
+function TouchControls:touchreleased(id, x, y)
+  local touch = self.touches[id]
+  if not touch then return end
+  self.touches[id] = nil
+  if touch.control == "dpad" then
+    setDpad(self, touch, nil)
+    self.dpadTouch = nil
+  else
+    releaseBtn(self, touch.control)
+  end
+end
+
+-- LÖVE has no touchcancelled: a touch interrupted by the OS (app
+-- backgrounded, a system gesture stealing the finger) never fires
+-- touchreleased and would strand its button held forever.  Called from
+-- Game alongside Input:reset() on focus/visibility loss.
+function TouchControls:reset()
+  for btn in pairs(self.held) do
+    Input:overlayReleased(btn)
+  end
+  self.held = {}
+  self.touches = {}
+  self.dpadTouch = nil
+end
+
+-- a gamepad is being used: hide the overlay (dropping anything it held)
+-- until the next screen touch asks for it back
+function TouchControls:noteGamepad()
+  if not self.active or self.controllerHidden then return end
+  self.controllerHidden = true
+  self:reset()
+end
+
+-- last controller unplugged: show the overlay again immediately instead
+-- of requiring a blind first tap
+function TouchControls:joystickremoved()
+  self:reset()
+  if love.joystick and love.joystick.getJoystickCount
+     and love.joystick.getJoystickCount() == 0 then
+    self.controllerHidden = false
+  end
+end
+
+local function drawIcon(img, zone, pressed)
+  love.graphics.setColor(1, 1, 1, pressed and BACK_PRESSED or BACK)
+  love.graphics.circle("fill", zone.cx, zone.cy, zone.w * 0.58)
+  local scale = zone.w / img:getWidth()
+  love.graphics.setColor(1, 1, 1, pressed and ALPHA_PRESSED or ALPHA)
+  love.graphics.draw(img, zone.cx - zone.w / 2,
+                     zone.cy - img:getHeight() * scale / 2, 0, scale, scale)
+end
+
+-- Screen-space, called by Game:draw after Renderer:endFrame so the
+-- overlay rides on top of everything (world, UI, CRT/GBC FX included).
+function TouchControls:draw()
+  if not self:visible() then return end
+  local L = self:layout()
+  love.graphics.push("all")
+  love.graphics.origin()
+
+  local dpadTouch = self.dpadTouch and self.touches[self.dpadTouch]
+  local dir = dpadTouch and dpadTouch.dir
+  drawIcon(dir and self.img["dpad_" .. dir] or self.img.dpad, L.dpad,
+           dir ~= nil)
+  for _, btn in ipairs(BUTTONS) do
+    drawIcon(self.img[btn], L[btn], self.held[btn] ~= nil)
+  end
+
+  -- the +/- glyphs alone don't say which is which; shadowed so the text
+  -- reads on both the black letterbox and battle's white one
+  love.graphics.setFont(self.labelFont)
+  local ly = L.start.cy + L.start.w * 0.66
+  local function label(text, zone)
+    local w = self.labelFont:getWidth(text)
+    love.graphics.setColor(0, 0, 0, 0.6)
+    love.graphics.print(text, zone.cx - w / 2 + 1, ly + 1)
+    love.graphics.setColor(1, 1, 1, ALPHA + 0.2)
+    love.graphics.print(text, zone.cx - w / 2, ly)
+  end
+  label("START", L.start)
+  label("SELECT", L.select)
+
+  love.graphics.pop()
+end
+
+return TouchControls

src/core/TouchInput.lua

@@ -1,297 +0,0 @@
--- Touch gesture recognizer → virtual keyboard keys for Input.lua.
---
--- Deferred-tap tradeoff: A fires only after DOUBLE_TAP_MS with no second
--- tap. That adds ~280ms latency to every A press so a double-tap can be
--- remapped to START instead of A-then-START. Gen 1 has no frame-perfect
--- input needs, so the latency is acceptable.
---
--- Select = two-finger tap (open Q1 in docs/mobile-plan.md): when a second distinct
--- touch ID lands while another short, low-movement touch is active, fire
--- SELECT (press + one-frame auto-release).
-
-local Input = require("src.core.Input")
-
-local TouchInput = {}
-
-local function dpiScale()
-  if love and love.window then
-    if love.window.getDPIScale then
-      return love.window.getDPIScale()
-    end
-    if love.window.toPixels then
-      return love.window.toPixels(1)
-    end
-  end
-  return 1
-end
-
--- Tunables (device-DPI-scaled where noted). Adjust after on-device testing.
-local SWIPE_THRESHOLD_PX = 14
-local EDGE_PX = 24
-local EDGE_SWIPE_PX = 24
-local DOUBLE_TAP_MS = 280
-local TAP_MAX_MS = 320
-local TAP_MAX_MOVE_PX = 12
-
-local function scaled(px)
-  return px * dpiScale()
-end
-
-local DIRS = { up = true, down = true, left = true, right = true }
-
--- Virtual keys Input:keypressed looks up in KEYBOARD bindings (not button names).
-local KEY = {
-  up = "up",
-  down = "down",
-  left = "left",
-  right = "right",
-  a = "z",
-  b = "x",
-  start = "escape",
-  select = "tab",
-}
-
-local function nowMs()
-  return love.timer.getTime() * 1000
-end
-
-local function dominantDir(dx, dy)
-  if math.abs(dx) >= math.abs(dy) then
-    return dx > 0 and "right" or "left"
-  end
-  return dy > 0 and "down" or "up"
-end
-
-function TouchInput:init()
-  self.touches = {}
-  self.pendingA = nil          -- { deadlineMs = number }
-  -- Edge pulses (B / START / SELECT / deferred-A): press now, release on a
-  -- later update so FixedStep can consume wasPressed first.
-  -- `armed` = pressed during events since last update; promoted to
-  -- `autoRelease` at the start of update (released on the *following* update).
-  -- Deferred-A fired inside update goes straight into `autoRelease`.
-  self.armed = {}
-  self.autoRelease = {}
-  self.selectFired = false     -- one SELECT per two-finger gesture cluster
-end
-
--- LÖVE has no touchcancelled event, so a touch interrupted by the OS (app
--- backgrounded mid-touch, a system gesture stealing the finger) never fires
--- touchreleased and would otherwise strand its direction held forever.
--- Called from Game alongside Input:reset() on focus/visibility loss.
-function TouchInput:reset()
-  for _, touch in pairs(self.touches) do
-    releaseDir(self, touch)
-  end
-  self.touches = {}
-  self.pendingA = nil
-  self.armed = {}
-  self.autoRelease = {}
-  self.selectFired = false
-end
-
-local function pulse(self, key)
-  Input:keypressed(key)
-  self.armed[#self.armed + 1] = key
-end
-
-local function pulseInUpdate(self, key)
-  Input:keypressed(key)
-  self.autoRelease[#self.autoRelease + 1] = key
-end
-
-local function releaseDir(self, touch)
-  if touch.dir and DIRS[touch.dir] then
-    Input:keyreleased(KEY[touch.dir])
-    touch.dir = nil
-  end
-end
-
-local function pressDir(self, touch, dir)
-  if touch.dir == dir then return end
-  releaseDir(self, touch)
-  touch.dir = dir
-  Input:keypressed(KEY[dir])
-end
-
-local function totalMove(touch, x, y)
-  local dx = x - touch.x0
-  local dy = y - touch.y0
-  return math.abs(dx), math.abs(dy), dx, dy
-end
-
-local function isTapLike(touch, x, y, tMs)
-  local ax, ay = totalMove(touch, x, y)
-  local elapsed = tMs - touch.t0
-  return elapsed <= TAP_MAX_MS
-     and ax <= scaled(TAP_MAX_MOVE_PX)
-     and ay <= scaled(TAP_MAX_MOVE_PX)
-     and not touch.classified
-end
-
-local function countActive(self)
-  local n = 0
-  for _ in pairs(self.touches) do n = n + 1 end
-  return n
-end
-
-local function tryTwoFingerSelect(self, tMs)
-  if self.selectFired then return false end
-  local ids = {}
-  for id, touch in pairs(self.touches) do
-    if isTapLike(touch, touch.x, touch.y, tMs) then
-      ids[#ids + 1] = id
-    end
-  end
-  if #ids < 2 then return false end
-
-  self.selectFired = true
-  self.pendingA = nil
-  for _, id in ipairs(ids) do
-    local touch = self.touches[id]
-    touch.classified = true
-    touch.consumed = true
-    releaseDir(self, touch)
-  end
-  pulse(self, KEY.select)
-  return true
-end
-
-function TouchInput:update(dt)
-  -- Releases armed on a prior update (FixedStep already saw wasPressed).
-  for i = 1, #self.autoRelease do
-    Input:keyreleased(self.autoRelease[i])
-  end
-  -- Promote event-phase pulses from since the last update; they release next time.
-  self.autoRelease = self.armed
-  self.armed = {}
-
-  local tMs = nowMs()
-
-  -- Deferred A: fire once the double-tap window closes with no second tap.
-  -- Queued into autoRelease so the next update clears hold after this FixedStep.
-  if self.pendingA and tMs >= self.pendingA.deadlineMs then
-    self.pendingA = nil
-    pulseInUpdate(self, KEY.a)
-  end
-
-  -- Keep two-finger SELECT detection live while both fingers stay down.
-  if countActive(self) >= 2 then
-    tryTwoFingerSelect(self, tMs)
-  elseif countActive(self) == 0 then
-    self.selectFired = false
-  end
-end
-
-function TouchInput:touchpressed(id, x, y)
-  local tMs = nowMs()
-
-  -- Second tap inside the deferred-A window → START instead of A.
-  if self.pendingA and tMs < self.pendingA.deadlineMs then
-    self.pendingA = nil
-    pulse(self, KEY.start)
-    -- Still record this touch so a lingering finger doesn't become a stray swipe.
-    self.touches[id] = {
-      x0 = x, y0 = y, x = x, y = y, t0 = tMs,
-      edge = x < scaled(EDGE_PX),
-      classified = true,
-      consumed = true,
-      dir = nil,
-    }
-    return
-  end
-
-  self.touches[id] = {
-    x0 = x, y0 = y, x = x, y = y, t0 = tMs,
-    edge = x < scaled(EDGE_PX),
-    classified = false,
-    consumed = false,
-    dir = nil,
-  }
-
-  if countActive(self) >= 2 then
-    tryTwoFingerSelect(self, tMs)
-  end
-end
-
-function TouchInput:touchmoved(id, x, y)
-  local touch = self.touches[id]
-  if not touch or touch.consumed then return end
-
-  touch.x, touch.y = x, y
-  local ax, ay, dx, dy = totalMove(touch, x, y)
-  local swipeTh = scaled(SWIPE_THRESHOLD_PX)
-
-  -- Edge-origin swipes become B on release; never promote to d-pad.
-  if touch.edge then
-    if ax >= scaled(EDGE_SWIPE_PX) or ay >= scaled(EDGE_SWIPE_PX) then
-      touch.classified = true
-    end
-    return
-  end
-
-  if not touch.classified then
-    if ax < swipeTh and ay < swipeTh then return end
-    touch.classified = true
-    pressDir(self, touch, dominantDir(dx, dy))
-    return
-  end
-
-  -- Mid-hold direction change: release old, press new (dominant axis).
-  if touch.dir then
-    local fromLastX = x - touch.x0
-    local fromLastY = y - touch.y0
-    -- Re-evaluate from origin so small jitter doesn't flip; require threshold
-    -- distance from origin along the new dominant axis.
-    if math.abs(fromLastX) >= swipeTh or math.abs(fromLastY) >= swipeTh then
-      local newDir = dominantDir(fromLastX, fromLastY)
-      if newDir ~= touch.dir then
-        pressDir(self, touch, newDir)
-      end
-    end
-  end
-end
-
-function TouchInput:touchreleased(id, x, y)
-  local touch = self.touches[id]
-  if not touch then return end
-
-  local tMs = nowMs()
-  touch.x, touch.y = x, y
-  local ax, ay = totalMove(touch, x, y)
-
-  if touch.dir then
-    releaseDir(self, touch)
-    self.touches[id] = nil
-    if countActive(self) == 0 then self.selectFired = false end
-    return
-  end
-
-  if touch.consumed then
-    self.touches[id] = nil
-    if countActive(self) == 0 then self.selectFired = false end
-    return
-  end
-
-  -- Left-edge B: origin in EDGE_PX strip and movement past EDGE_SWIPE_PX
-  -- (or already marked classified while moving). Prefer over d-pad / tap.
-  if touch.edge then
-    local edgeTh = scaled(EDGE_SWIPE_PX)
-    if touch.classified or ax >= edgeTh or ay >= edgeTh then
-      pulse(self, KEY.b)
-      self.touches[id] = nil
-      if countActive(self) == 0 then self.selectFired = false end
-      return
-    end
-  end
-
-  -- Plain tap → defer A (or it was already classified as swipe without dir, ignore).
-  if isTapLike(touch, x, y, tMs) then
-    self.pendingA = { deadlineMs = tMs + DOUBLE_TAP_MS }
-  end
-
-  self.touches[id] = nil
-  if countActive(self) == 0 then self.selectFired = false end
-end
-
-return TouchInput

src/core/Version.lua

@@ -4,14 +4,22 @@
 -- tests.
 
 local Version = {
-  engine = "1.0.0",       -- game/engine release (semver triple)
+  engine = "0.0.0-dev",   -- game/engine release (semver).  Repo default is the
+                          -- "-dev" placeholder; CI stamps the real X.Y.Z into
+                          -- the packed game.love only, never the working tree.
+  shell = 1,              -- native-shell contract this build implements
+  minShell = 1,           -- lowest shell contract that can RUN this payload.
+                          -- Bump only when a payload needs a newer native
+                          -- binary (e.g. a LOVE version bump); an older shell
+                          -- refuses to chainload a payload whose minShell
+                          -- exceeds the shell it provides.
   modApi = 2,             -- mod API major (manifest `api`)
   linkProtocol = 2,       -- link handshake wire version (Handshake.PROTOCOL)
   saveFormat = 4,         -- save.meta.format
   cache = "rom-cache-v5", -- ROM import cache generation (RomImporter marker)
 }
 
--- "gen1recomp v1.0.0"
+-- "gen1recomp v0.0.0-dev" (or the stamped release version in shipped builds)
 function Version.title(base)
   return (base or "gen1recomp")
     .. " v" .. Version.engine

src/import/RomExtractor.lua

@@ -375,6 +375,8 @@ function RomExtractor:extractMaps()
     }
     self:tick("Maps", mapIndex, #keys)
   end
+  -- keep the extract ROM-faithful; Data:seedDefaults applies the #189
+  -- S.S. Anne 1F cabin reorder at load time
   self:write("maps", out)
   return out
 end

src/import/SaveFileIO.lua

@@ -0,0 +1,112 @@
+-- SaveFileIO -- the launcher's glue between a raw Gen1 .sav battery image and
+-- this project's save slots.  Keeps RomImporter lean: the SAVE FILES card just
+-- calls importToSlot / exportActiveSlot and renders the {ok, result} outcome.
+--
+-- Import reads bytes (an absolute picker path, a dropped LOVE file, or raw
+-- bytes), runs them through SaveConvert.importSav (32768-byte + checksum
+-- validated), then registers a fresh slot, writes it, and makes it active.
+-- Export loads the active slot, encodes it back to a 32768-byte SRAM image, and
+-- drops it in the save directory's exports/ folder, returning the absolute path
+-- so the launcher can offer an "open folder" affordance.
+--
+-- Every failure returns false + a friendly one-line message (never raises), so
+-- the card can surface it as a red notice line rather than crashing.
+
+local SaveConvert = require("src.save_convert.SaveConvert")
+local SaveData = require("src.core.SaveData")
+local GameVersion = require("src.core.GameVersion")
+
+local SaveFileIO = {}
+
+local SAVE_SIZE = SaveConvert.SAVE_SIZE
+
+-- Resolve raw save bytes from whatever the launcher hands us:
+--   * a LOVE DroppedFile (a table/userdata with :open/:read/:getSize), read the
+--     way RomImporter reads a dropped ROM;
+--   * a raw 32768-byte string (the tests and the in-memory path) used as-is;
+--   * any other string treated as an absolute picker path opened with io.open.
+-- A picker path is never 32768 bytes long, so the length test disambiguates it
+-- from a raw image cleanly.  Returns bytes, or nil + an error string.
+local function readSource(source)
+  local t = type(source)
+  if t == "table" or t == "userdata" then
+    if type(source.read) ~= "function" then
+      return nil, "that file could not be read"
+    end
+    local ok, openErr = source:open("r")
+    if not ok then return nil, "could not open the dropped file: " .. tostring(openErr) end
+    local data, readErr = source:read(source:getSize())
+    source:close()
+    if not data then return nil, "could not read the dropped file: " .. tostring(readErr) end
+    return data
+  end
+  if t ~= "string" then
+    return nil, "no save file was provided"
+  end
+  if #source == SAVE_SIZE then
+    return source
+  end
+  local f, openErr = io.open(source, "rb")
+  if not f then return nil, "could not read the save file: " .. tostring(openErr) end
+  local data = f:read("*a")
+  f:close()
+  if type(data) ~= "string" then return nil, "the save file was empty" end
+  return data
+end
+
+-- importToSlot(source, version) -> ok, slotIdOrErr
+-- source: an absolute path, a LOVE DroppedFile, or raw 32768 bytes.  On success
+-- registers a new slot for the version, writes the imported save into it, makes
+-- it the active slot, and returns true + the new slot id.  On any failure
+-- returns false + a friendly message.
+function SaveFileIO.importToSlot(source, version)
+  version = version or GameVersion.get()
+  local bytes, readErr = readSource(source)
+  if not bytes then return false, readErr end
+  if #bytes ~= SAVE_SIZE then
+    return false, ("A save file must be %d bytes (32 KB); this one is %d.")
+      :format(SAVE_SIZE, #bytes)
+  end
+  local save, convertErr = SaveConvert.importSav(bytes, version)
+  if not save then return false, convertErr end
+  -- Tag the game version and normalize the meta stamp: SaveConvert leaves
+  -- meta.format = "gen1_import", but SaveData.load's migration pass compares
+  -- the format numerically, so re-stamp it to the current format (the imported
+  -- table is already current-shaped, so no migration is skipped by doing so).
+  save.version = version
+  save.meta = SaveData.buildMeta(nil, save.meta)
+  local slotId = SaveData.createSlot(version)
+  if not slotId then return false, "this game has no save slots to import into" end
+  local ok, writeErr = SaveData.writeSlot(version, slotId, save)
+  if not ok then
+    return false, "could not write the imported save: " .. tostring(writeErr)
+  end
+  SaveData.setActiveSlot(version, slotId)
+  return true, slotId
+end
+
+-- exportActiveSlot(version) -> ok, pathOrErr
+-- Loads the version's active slot save (SaveData.load semantics), encodes it
+-- back to a 32768-byte SRAM image, and writes it to
+-- exports/gen1recomp-<version>-<slotId>.sav in the save directory (created if
+-- absent).  Returns true + the absolute path on success, false + a friendly
+-- message otherwise.
+function SaveFileIO.exportActiveSlot(version)
+  version = version or GameVersion.get()
+  local save = SaveData.load(version)
+  if not save then return false, "this game has no save to export yet" end
+  local bytes, exportErr = SaveConvert.exportSav(save)
+  if not bytes then return false, exportErr end
+  local slotId = SaveData.activeSlot(version) or "save"
+  local fs = love and love.filesystem
+  if not (fs and fs.write) then return false, "no filesystem available to export to" end
+  if fs.createDirectory then fs.createDirectory("exports") end
+  local rel = ("exports/gen1recomp-%s-%s.sav"):format(version, slotId)
+  local ok, writeErr = fs.write(rel, bytes)
+  if not ok then return false, "could not write the export: " .. tostring(writeErr) end
+  local base = fs.getSaveDirectory and fs.getSaveDirectory() or ""
+  if base ~= "" then return true, base .. "/" .. rel end
+  return true, rel
+end
+
+return SaveFileIO

src/inventory/ItemEffects.lua

@@ -114,10 +114,11 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
   local itemDef = data.items[itemId]
   local name = itemDef and itemDef.name or itemId
 
-  -- ItemUseVitamin / ItemUsePPUp / ItemUseEvoStone / ItemUseCoinCase
-  -- all refuse mid-battle (jp nz, ItemUseNotTime)
+  -- ItemUseVitamin / ItemUsePPUp / ItemUseEvoStone / ItemUseCoinCase /
+  -- ItemUseTMHM all refuse mid-battle (jp nz, ItemUseNotTime)
   if battle and (VITAMINS[itemId] or STONES[itemId] or itemId == "PP_UP"
-                 or itemId == "RARE_CANDY" or itemId == "COIN_CASE") then
+                 or itemId == "RARE_CANDY" or itemId == "COIN_CASE"
+                 or (itemDef and itemDef.machine)) then
     return "failed", { "OAK: " .. save.player.name
       .. "!\nThis isn't the\ntime to use that!" }
   end

src/link/LinkBattle.lua

@@ -182,7 +182,7 @@ function LinkBattle.new(game, net, opts)
 
   -- both parties pass through the same pack->unpack clamp on both
   -- machines, so the copies are identical everywhere
-  local unpackOpts = { strict = opts.strict or false }
+  local unpackOpts = { strict = opts.strict or false, forceLevel = opts.forceLevel }
   local myParty, myErr = unpackParty(game, opts.myParty, unpackOpts, function(p)
     return ("Your %s can't\nbattle on the\nother game."):format(tostring(p.species))
   end)
@@ -646,7 +646,7 @@ function LinkBattle.newSpectator(game, net, opts)
     return nil, "Link battle needs\nthe same mods on\nboth games."
   end
 
-  local unpackOpts = { strict = opts.strict or false }
+  local unpackOpts = { strict = opts.strict or false, forceLevel = opts.forceLevel }
   local hostParty, hostErr = unpackParty(game, opts.hostParty, unpackOpts, function(p)
     return ("%s's %s can't\nbattle on this\ngame."):format(hostName, tostring(p.species))
   end)

src/link/LinkState.lua

@@ -3,6 +3,7 @@
 -- lua-enet (bundled with LÖVE),  no relay server.
 
 local CodeEntry = require("src.link.CodeEntry")
+local DiscordPresence = require("src.core.DiscordPresence")
 local Font = require("src.render.Font")
 local Handshake = require("src.link.Handshake")
 local Net = require("src.link.Net")
@@ -16,6 +17,31 @@ LinkState.__index = LinkState
 LinkState.isOpaque = true
 
 local CURSOR = 0xED
+local ANY = "ANY" -- sentinel: a leading nil array entry breaks ipairs under
+                  -- LuaJIT even though # still reports the full size, so
+                  -- the level picker cycles this string instead of nil,
+                  -- converted to nil only on the wire (see levelForWire)
+local FORCE_LEVEL_STEPS = { ANY, 50, 100 }
+
+local function indexOf(list, value)
+  for i, v in ipairs(list) do
+    if v == value then return i end
+  end
+  return 1
+end
+
+local function levelForWire(v)
+  -- ANY ("use each mon's real level") goes on the wire as nil (no forced
+  -- level).  An explicit guard, not `v == ANY and nil or v`: that idiom's
+  -- true branch is nil, so it falls through to `or v` and returned the
+  -- literal "ANY" string, which then crashed math.floor in unpackMon (#204).
+  if v == ANY then return nil end
+  return v
+end
+
+local function forceLevelLabel(v)
+  return (v == ANY or v == nil) and "ANY" or ("AUTO " .. tostring(v))
+end
 
 -- stages before any Net object is meaningfully "this session's link" --
 -- .net can still be a leftover failed attempt sitting on self, so error/
@@ -54,7 +80,23 @@ function LinkState.new(game)
   return self
 end
 
+-- entry point for a Discord "Ask to Join" click (see DiscordPresence.lua):
+-- skips the whole LAN/ONLINE/TOURNAMENT menu and jumps straight to
+-- "connecting with this code", same as if the player had typed it in
+function LinkState.newJoinOnline(game, code)
+  local self = LinkState.new(game)
+  self.net = Net.new()
+  if self.net:joinOnline(nil, code) then
+    self.stage = "onlineJoining"
+  else
+    self.stage = "menu" -- exitWith below needs a real stage to unwind from
+    self:exitWith("Link error:\n" .. (self.net.error or "?"))
+  end
+  return self
+end
+
 function LinkState:exitWith(message, reason)
+  DiscordPresence.setJoinCode(nil)
   Runtime.emit("link.ended", { reason = reason or (message and "error" or "bye") })
   if self.net then self.net:close() end
   self.game.stack:pop()
@@ -108,7 +150,12 @@ function LinkState:decideCompat(mode, isHost)
                mods = peer and peer.mods, fingerprint = peer and peer.fingerprint },
   })
   if self.verdict == "full" or self.verdict == "vanilla_peer" then
-    self:startMode(mode, isHost)
+    if isHost and mode == "battle" then
+      -- host picks the level rule now, before the parties are exchanged
+      self.stage = "battleOptions"
+    else
+      self:startMode(mode, isHost)
+    end
     return
   end
   -- naming the difference up front is the whole point: the old behaviour
@@ -208,8 +255,13 @@ function LinkState:update(dt)
     end
 
   elseif self.stage == "onlineHosting" then
+    if not self.discordCodeSet and self.net.code then
+      DiscordPresence.setJoinCode(self.net.code)
+      self.discordCodeSet = true
+    end
     if input:wasPressed("b") then self:exitWith(nil) return end
     if self.net.paired then
+      DiscordPresence.setJoinCode(nil) -- someone's here now; stop advertising
       self.stage = "modeSelect"
       self.index = 1
     end
@@ -300,6 +352,23 @@ function LinkState:update(dt)
       self:exitWith(nil)
     end
 
+  elseif self.stage == "battleOptions" then -- host picks the level rule,
+                                             -- once compat is confirmed and
+                                             -- before parties are exchanged
+    self.levelChoice = self.levelChoice or ANY
+    if input:wasPressed("b") then
+      self:exitWith(nil)
+    elseif input:wasPressed("up") or input:wasPressed("down")
+        or input:wasPressed("left") or input:wasPressed("right") then
+      local delta = (input:wasPressed("down") or input:wasPressed("left")) and -1 or 1
+      local i = indexOf(FORCE_LEVEL_STEPS, self.levelChoice)
+      i = ((i - 1 + delta) % #FORCE_LEVEL_STEPS) + 1
+      self.levelChoice = FORCE_LEVEL_STEPS[i]
+    elseif input:wasPressed("a") then
+      self.forceLevel = levelForWire(self.levelChoice)
+      self:startMode(self.pendingMode, true)
+    end
+
   elseif self.stage == "waitHello" then -- host waits for the peer's hello
     if input:wasPressed("b") then self:exitWith(nil) return end
     local got, other = self:pollHello()
@@ -343,6 +412,9 @@ function LinkState:update(dt)
     local msgs = self.net:poll()
     for i, msg in ipairs(msgs) do
       if msg.type == "party" then
+        -- the host owns this rule (same as mode); the guest only learns
+        -- it here, off the host's own party message
+        if not self.isHost then self.forceLevel = msg.forceLevel end
         local LinkBattle = require("src.link.LinkBattle")
         local opts = {
           myParty = Protocol.packParty(self.game.save.party),
@@ -351,6 +423,7 @@ function LinkState:update(dt)
           seed = self.isHost and self.linkSeed or msg.seed,
           verdict = self.verdict,
           strict = Handshake.strict(self.verdict),
+          forceLevel = self.forceLevel,
         }
         local battle, why
         if self.isHost then
@@ -401,7 +474,8 @@ function LinkState:startMode(mode, isHost)
     end
     self.net:send({ type = "party",
                     mons = Protocol.packParty(self.game.save.party),
-                    seed = self.linkSeed })
+                    seed = self.linkSeed,
+                    forceLevel = isHost and self.forceLevel or nil })
   end
 end
 
@@ -424,6 +498,14 @@ function LinkState:updateTrade(input)
   if t.stage == "done" then
     local sent = t.party[t.myPick]
     local received, evoTo = t:apply(self.game)
+    -- Autosave the instant the swap commits into game.save.party, matching the
+    -- Cable Club: pokered engine/link/cable_club.asm calls SaveSAVtoSRAM
+    -- (engine/menus/save.asm) right after every trade so the trade is on the
+    -- cartridge before the animation runs.  Without this the received mon
+    -- lives only in memory until a manual START-menu save, so a force-quit
+    -- would lose it and a reset would clone the sent mon (#222).  Guarded so
+    -- headless LinkBattle-style fake games with no writeSave are unaffected.
+    if self.game.writeSave then self.game:writeSave() end
     local name = received.nickname or self.game.data.pokemon[received.species].name
     Runtime.emit("link.ended", { reason = "done" })
     self.net:close()
@@ -432,12 +514,22 @@ function LinkState:updateTrade(input)
     require("src.core.Sound").play(game.data, "Trade_Machine")
     Screens.push(game, "TradeAnim", {
       sent = sent, received = received,
+      enemyName = (self.peerName or "TRAINER"),
+      playerOt = game.save.player.name,
+      playerOtId = sent.otId or game.save.player.id,
+      enemyOtId = received.otId,
       onDone = function()
         game.stack:push(TextBox.new(game,
           ("Trade completed!\f%s received\n%s!"):format(game.save.player.name, name),
           function()
             if evoTo then
-              require("src.pokemon.Evolution").evolve(game, received, evoTo)
+              -- via="TRADE": a trade evolution cannot be B-cancelled
+              -- (pokered LINK_STATE_TRADING skips the flash B-poll) (#213).
+              -- Re-save once the evolution movie finishes so the evolved
+              -- species (not the pre-evo landed by t:apply) is what persists,
+              -- keeping disk in step with the autosave above (#222).
+              require("src.pokemon.Evolution").evolve(game, received, evoTo,
+                function() if game.writeSave then game:writeSave() end end, "TRADE")
             end
           end))
       end,
@@ -557,6 +649,12 @@ function LinkState:draw()
     Font.draw("BATTLE", 32, 68)
     Font.drawCode(CURSOR, 24, self.index == 1 and 48 or 68)
 
+  elseif self.stage == "battleOptions" then
+    drawTitle("BATTLE OPTIONS")
+    Font.draw("LEVELS:", 16, 56)
+    Font.draw(forceLevelLabel(self.levelChoice or ANY), 88, 56)
+    Font.draw("A: continue  B: back", 8, 128)
+
   elseif self.stage == "waitMode" or self.stage == "waitHello" then
     drawTitle("CONNECTED!")
     if self.stage == "waitHello" then

src/link/Protocol.lua

@@ -43,7 +43,12 @@ Protocol.plainCopy = plainCopy
 
 -- serialize a mon instance for the wire (plain data only).  ppUps rides
 -- along because the real cable transmitted it and its absence silently
--- capped a PP-Upped move at base PP on the receiving side.
+-- capped a PP-Upped move at base PP on the receiving side.  ot/otId ride
+-- along too: pokered's trade sends the whole party block including each
+-- mon's OT ID (party_struct MON_OTID) and the OT-names block (wPartyMonOT),
+-- and the receiver keeps them verbatim -- a differing OT/ID is what marks a
+-- mon as traded (boosted EXP, high-level disobedience).  Omitting them made
+-- a received mon show the receiver as its OT (#215).
 function Protocol.packMon(mon)
   local moves = {}
   for _, mv in ipairs(mon.moves) do
@@ -59,6 +64,8 @@ function Protocol.packMon(mon)
     dvs = mon.dvs,
     statExp = mon.statExp,
     moves = moves,
+    ot = mon.ot,
+    otId = mon.otId,
     extra = plainCopy(mon.extra),
   }
 end
@@ -71,12 +78,27 @@ function Protocol.unpackMon(data, packed, opts)
   local Stats = require("src.pokemon.Stats")
   local Growth = require("src.pokemon.Growth")
   local strict = opts and opts.strict
+  -- forceLevel comes from an "auto-level" ruling.  The picker's ANY choice
+  -- ("use each mon's real level", Gen1's only mode) is a string sentinel on
+  -- the LinkState/Tournament side (see levelForWire) that must mean "no
+  -- forced level" here.  Coerce once so a non-numeric level string -- the ANY
+  -- sentinel, an old peer, or a mod (#204) -- can never reach math.floor
+  -- below: tonumber("ANY") == nil, i.e. keep the packed real level, while
+  -- tonumber(50)/tonumber("50") both give 50.
+  local forceLevel = opts and tonumber(opts.forceLevel) or nil
   local def = data.pokemon[packed.species]
   if not def then
     if strict then return nil, "unknown POKéMON" end
     return nil
   end
   local level = math.max(2, math.min(100, math.floor(packed.level or 5)))
+  -- "auto-level" tournaments/matches: every participant's real level is
+  -- ignored and everyone rebuilds at the same fixed level instead, so a
+  -- Lv12 and a Lv100 party can battle on equal footing. Both sides pass
+  -- the identical forceLevel for a given match, so this stays symmetric.
+  if forceLevel then
+    level = math.max(2, math.min(100, math.floor(forceLevel)))
+  end
   local dvs = {}
   for _, k in ipairs({ "hp", "attack", "defense", "speed", "special" }) do
     dvs[k] = math.max(0, math.min(15, math.floor((packed.dvs or {})[k] or 0)))
@@ -104,6 +126,23 @@ function Protocol.unpackMon(data, packed, opts)
     if strict then return nil, "no shared moves" end
     moves = { { id = "TACKLE", pp = 35 } }
   end
+  -- a forced level scales every stat including max HP, so the real party's
+  -- current HP/status (a different level's numbers, possibly mid-fight)
+  -- isn't meaningful anymore -- auto-level starts everyone full and fresh,
+  -- same as a standardized tournament format would
+  local forced = forceLevel
+  local hp = forced and stats.hp
+    or math.max(0, math.min(stats.hp, math.floor(packed.hp or stats.hp)))
+  local status = forced and nil or packed.status
+  -- preserve the sender's original-trainer identity (party_struct MON_OTID +
+  -- wPartyMonOT on a real cable), clamped/typed like every other field so a
+  -- tampered packet can't inject a bad ID or a huge name.  Left nil when the
+  -- packet omits them (a v1/old peer) -- no worse than before for that legacy
+  -- path, and once ot is set the load-time stampOT backfill (mon.ot or ...)
+  -- becomes a no-op so the sender's identity survives save/reload (#215).
+  local otId = packed.otId
+    and math.max(0, math.min(65535, math.floor(packed.otId))) or nil
+  local ot = type(packed.ot) == "string" and packed.ot:sub(1, 10) or nil
   return {
     species = packed.species,
     level = level,
@@ -111,9 +150,11 @@ function Protocol.unpackMon(data, packed, opts)
     dvs = dvs,
     statExp = statExp,
     stats = stats,
-    hp = math.max(0, math.min(stats.hp, math.floor(packed.hp or stats.hp))),
-    status = packed.status,
+    hp = hp,
+    status = status,
     nickname = packed.nickname,
+    ot = ot,
+    otId = otId,
     moves = moves,
     -- a namespace whose mod this install lacks survives untouched, so the
     -- mon keeps it for the trip home

src/link/Tournament.lua

@@ -9,6 +9,7 @@
 -- time, uninterrupted by individual matches.
 
 local CodeEntry = require("src.link.CodeEntry")
+local DiscordPresence = require("src.core.DiscordPresence")
 local Font = require("src.render.Font")
 local Handshake = require("src.link.Handshake")
 local LinkBattle = require("src.link.LinkBattle")
@@ -33,7 +34,14 @@ local ANY = "ANY" -- sentinel: a leading *nil* array entry breaks ipairs
                   -- to nil only on the wire
 local LEVEL_STEPS = { ANY, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65,
                        70, 75, 80, 85, 90, 95, 100 }
-local SETTINGS_ROWS = 5 -- POKEMON, MIN LV, MAX LV, TIMER, PLAYING
+local SETTINGS_ROWS = 6 -- POKEMON, MIN LV, MAX LV, TIMER, LEVELS, PLAYING
+-- LEVELS cycles through this: ANY (real levels) or a fixed level every
+-- match normalizes to, regardless of each side's real party
+local FORCE_LEVEL_STEPS = { ANY, 50, 100 }
+-- tournaments have no real participant cap (any number can join before
+-- start); this is just generous headroom so Discord's party.size never
+-- reads as "full" and blocks a real invite click
+local TOURNAMENT_PARTY_MAX = 16
 
 local function indexOf(list, value)
   for i, v in ipairs(list) do
@@ -49,7 +57,16 @@ local function levelLabel(v)
 end
 
 local function levelForWire(v)
-  return v == ANY and nil or v
+  -- ANY ("use each mon's real level") goes on the wire as nil (no forced
+  -- level).  An explicit guard, not `v == ANY and nil or v`: that idiom's
+  -- true branch is nil, so it falls through to `or v` and returned the
+  -- literal "ANY" string, which then crashed math.floor in unpackMon (#204).
+  if v == ANY then return nil end
+  return v
+end
+
+local function forceLevelLabel(v)
+  return (v == ANY or v == nil) and "ANY" or ("AUTO " .. tostring(v))
 end
 
 local function partyStats(party)
@@ -69,7 +86,7 @@ function Tournament.new(game)
   self.stage = "menu"
   self.index = 1
   self.settings = { turnLimit = 6, requiredPartySize = 3, minLevel = ANY, maxLevel = ANY,
-                    participating = true }
+                    forceLevel = ANY, participating = true }
   self.settingsIndex = 1
   self.roster = {}
   self.spectatorRoster = {}
@@ -77,7 +94,24 @@ function Tournament.new(game)
   return self
 end
 
+-- entry point for a Discord "Ask to Join" click on a tournament invite
+-- (see DiscordPresence.lua): skips the HOST/JOIN menu and code entry,
+-- straight to "connecting with this code"
+function Tournament.newJoinOnline(game, code)
+  local self = Tournament.new(game)
+  self:startJoining(code)
+  return self
+end
+
+-- headcount for Discord's party.size: the roster only ever lists
+-- competing players, so a non-participating (organizer-only) host isn't
+-- in it even though they're right here running the thing
+function Tournament:discordPartySize()
+  return #self.roster + (self.participating == false and 1 or 0)
+end
+
 function Tournament:exitWith(message)
+  DiscordPresence.setJoinCode(nil)
   Sound.stopLoop(MUSIC)
   Runtime.emit("link.ended", { reason = message and "error" or "bye" })
   if self.net then self.net:close() end
@@ -106,6 +140,7 @@ function Tournament:startHosting()
     requiredPartySize = self.settings.requiredPartySize,
     minLevel = levelForWire(self.settings.minLevel),
     maxLevel = levelForWire(self.settings.maxLevel),
+    forceLevel = levelForWire(self.settings.forceLevel),
     participating = self.settings.participating,
     name = self.game.save.player.name,
     partySize = size, partyMinLevel = minL, partyMaxLevel = maxL,
@@ -145,8 +180,22 @@ function Tournament:handleMessage(msg)
   if msg.type == "tournament_hosted" then
     self.code = msg.code
     self.settings.turnLimit = msg.turnLimit
+    self.settings.forceLevel = msg.forceLevel == nil and ANY or msg.forceLevel
     self.participating = msg.participating
     self.stage = "bracket"
+    -- the server already seeded t.players/spectators with the creator at
+    -- creation time; mirror that here so the Discord party size (and the
+    -- "waiting for players" list) show the host from the very first frame,
+    -- not just once someone else joins and a real roster broadcast arrives
+    if self.participating then
+      self.roster = { self.game.save.player.name }
+    else
+      self.spectatorRoster = { self.game.save.player.name }
+    end
+    if self.isCreator then
+      DiscordPresence.setJoinCode(self.code, "tournament",
+        self:discordPartySize(), TOURNAMENT_PARTY_MAX)
+    end
   elseif msg.type == "tournament_host_error" then
     if msg.reason == "party_ineligible" then
       self:exitWith(("Can't host:\nneed %d Pokemon\nLv %s-%s."):format(
@@ -168,7 +217,12 @@ function Tournament:handleMessage(msg)
     self.settings.requiredPartySize = msg.requiredPartySize
     self.settings.minLevel = msg.minLevel == nil and ANY or msg.minLevel
     self.settings.maxLevel = msg.maxLevel == nil and ANY or msg.maxLevel
+    self.settings.forceLevel = msg.forceLevel == nil and ANY or msg.forceLevel
     self.stage = "bracket"
+    if self.isCreator and self.code then
+      DiscordPresence.setJoinCode(self.code, "tournament",
+        self:discordPartySize(), TOURNAMENT_PARTY_MAX)
+    end
   elseif msg.type == "bracket_update" then
     self.bracket = msg.tournament
     self.code = self.bracket.code
@@ -238,6 +292,7 @@ function Tournament:beginMatchBattle()
     verdict = verdict,
     strict = Handshake.strict(verdict),
     turnLimit = self.matchTurnLimit,
+    forceLevel = levelForWire(self.settings.forceLevel),
     keepNetOpen = true, -- this is the tournament's own connection, not a
                         -- dedicated match socket -- don't let finish() close it
   }
@@ -360,6 +415,7 @@ function Tournament:update(dt)
             hostParty = self.spectate.hostParty, guestParty = self.spectate.guestParty,
             hostName = self.spectate.hostName, guestName = self.spectate.guestName,
             seed = self.spectate.seed,
+            forceLevel = levelForWire(self.settings.forceLevel),
           })
           if not battle then
             self:exitWith(why or "Can't watch this\nmatch.")
@@ -426,6 +482,10 @@ function Tournament:update(dt)
         i = ((i - 1 + delta) % #TURN_LIMITS) + 1
         self.settings.turnLimit = TURN_LIMITS[i]
       elseif self.settingsIndex == 5 then
+        local i = indexOf(FORCE_LEVEL_STEPS, self.settings.forceLevel)
+        i = ((i - 1 + delta) % #FORCE_LEVEL_STEPS) + 1
+        self.settings.forceLevel = FORCE_LEVEL_STEPS[i]
+      elseif self.settingsIndex == 6 then
         self.settings.participating = not self.settings.participating
       end
     elseif input:wasPressed("a") or input:wasPressed("start") then
@@ -454,6 +514,7 @@ function Tournament:update(dt)
   elseif self.stage == "bracket" then
     if input:wasPressed("b") then self:exitWith(nil) return end
     if input:wasPressed("a") and self.isCreator and #self.roster >= 2 then
+      DiscordPresence.setJoinCode(nil) -- roster's locking in; stop advertising
       self.net:send({ type = "start_tournament" })
     end
 
@@ -475,7 +536,7 @@ local function drawTitle(text)
   Font.draw(text, 8, 6)
 end
 
-local SETTINGS_LABELS = { "POKEMON", "MIN LV", "MAX LV", "TIMER", "PLAYING" }
+local SETTINGS_LABELS = { "POKEMON", "MIN LV", "MAX LV", "TIMER", "LEVELS", "PLAYING" }
 
 function Tournament:draw()
   if self.stage == "menu" then
@@ -491,6 +552,7 @@ function Tournament:draw()
       levelLabel(self.settings.minLevel),
       levelLabel(self.settings.maxLevel),
       self.settings.turnLimit .. "s",
+      forceLevelLabel(self.settings.forceLevel),
       self.settings.participating and "YES" or "NO",
     }
     for i, label in ipairs(SETTINGS_LABELS) do

src/mods/LauncherMods.lua

@@ -0,0 +1,335 @@
+-- Launcher-side mod surface (18/launcher redesign): the mods panel runs
+-- BEFORE Game:load, so this NEVER loads a mod entry chunk -- it scans
+-- manifests only.  The full loader (src/mods/Loader.lua) still owns the real
+-- load at boot; this reads the same options.mods enable-state the loader
+-- writes, derives per-mod status with the pure ManagerState.resolveToggle,
+-- and installs a dropped/chosen .zip into the save-dir "mods/<id>/" tree.
+--
+-- Split in two: the pure derivation (deriveList, locateRoot) has no love and
+-- no filesystem, so the engine tier can table-drive it; the discovery and
+-- install paths reach for love.filesystem and SaveData.
+
+local Manifest = require("src.mods.Manifest")
+local ManagerState = require("src.mods.ManagerState")
+local Semver = require("src.mods.Semver")
+local Version = require("src.core.Version")
+local SaveData = require("src.core.SaveData")
+
+local LauncherMods = {}
+
+-- ------- pure status derivation
+
+-- A hard-dependency / conflict / version verdict for one manifest.  mods is
+-- the id -> validated-manifest map resolveToggle reads (its dependencySpecs,
+-- conflictSpecs, version and game_version are exactly the fields the loader's
+-- Manifest.validate produced); enabledSet is the current desired enable-set.
+local function statusFor(mods, id, enabledSet, enabled)
+  local m = mods[id]
+  -- conflict only bites an enabled mod: resolveToggle's conflict list is
+  -- bidirectional (this mod's conflicts spec vs an enabled other, and an
+  -- enabled other's spec vs this mod), which is exactly the launcher chip.
+  if enabled then
+    local r = ManagerState.resolveToggle(mods, id, true, enabledSet)
+    if #r.conflicts > 0 then
+      local otherId = r.conflicts[1]
+      local other = mods[otherId]
+      return "conflict",
+        "Conflicts with " .. ((other and other.name) or otherId)
+    end
+  end
+  -- warn: the engine is outside the mod's game_version range
+  if m.game_version
+      and not Semver.satisfies(Version.engine, m.game_version) then
+    return "warn", "Needs engine " .. m.game_version
+      .. " (have " .. Version.engine .. ")"
+  end
+  -- warn: a hard dependency is absent, switched off, or the wrong version.
+  -- resolveToggle would cascade-enable a merely-disabled dep rather than flag
+  -- it, so the disabled case is judged straight off the manifest here.
+  for _, spec in ipairs(m.dependencySpecs or {}) do
+    local dep = mods[spec.id]
+    if not dep then
+      return "warn", "Needs " .. spec.id .. " (not installed)"
+    elseif not enabledSet[spec.id] then
+      return "warn", "Needs " .. spec.id .. " (disabled)"
+    elseif spec.range
+        and not Semver.satisfies(dep.version, spec.range) then
+      return "warn", "Needs " .. spec.id .. " " .. spec.range
+    end
+  end
+  return "ok", "Ready"
+end
+
+-- deriveList(manifests, options) -> the panel row list, pure.
+-- manifests is an array of validated manifests (Manifest.validate output);
+-- options is the options table (only options.mods is read).  Rows come back
+-- sorted by id so the panel order is stable.
+function LauncherMods.deriveList(manifests, options)
+  local mods = options and options.mods or {}
+  local ordered = {}
+  for _, m in ipairs(manifests) do ordered[#ordered + 1] = m end
+  table.sort(ordered, function(a, b) return a.id < b.id end)
+
+  local byId, enabledSet = {}, {}
+  for _, m in ipairs(ordered) do
+    byId[m.id] = m
+    -- missing entry means enabled, matching the loader's default
+    if mods[m.id] ~= false then enabledSet[m.id] = true end
+  end
+
+  local out = {}
+  for _, m in ipairs(ordered) do
+    local enabled = enabledSet[m.id] == true
+    local status, detail = statusFor(byId, m.id, enabledSet, enabled)
+    local raw = m.raw or {}
+    out[#out + 1] = {
+      id = m.id,
+      name = m.name or m.id,
+      version = m.version,
+      -- category, then profile, then a generic fallback -- uppercased
+      badge = tostring(raw.category or m.profile or "MOD"):upper(),
+      description = m.description or "",
+      enabled = enabled,
+      status = status,
+      statusDetail = detail,
+    }
+  end
+  return out
+end
+
+-- locateRoot(paths) -> the mod-root prefix inside a mounted archive, pure.
+-- paths is a shallow listing: top-level file names as-is, and for a top-level
+-- directory a "<dir>/manifest.json" entry when it holds one.  Returns "" when
+-- the manifest sits at the archive root, "<dir>" when a single top-level
+-- folder holds it, or nil + a user-presentable reason.
+function LauncherMods.locateRoot(paths)
+  for _, p in ipairs(paths) do
+    if p == "manifest.json" then return "" end
+  end
+  local topDirs, seen, hasManifest = {}, {}, {}
+  for _, p in ipairs(paths) do
+    local top, rest = p:match("^([^/]+)/(.+)$")
+    if top then
+      if not seen[top] then
+        seen[top] = true
+        topDirs[#topDirs + 1] = top
+      end
+      if rest == "manifest.json" then hasManifest[top] = true end
+    end
+  end
+  if #topDirs == 1 and hasManifest[topDirs[1]] then return topDirs[1] end
+  if #topDirs > 1 then
+    return nil, "the .zip must contain a single mod folder"
+  end
+  return nil, "no manifest.json found in the .zip"
+end
+
+-- ------- discovery (love.filesystem)
+
+local function decodeManifest(raw, path)
+  local Json = require("src.link.Json")
+  local data, decodeErr = Json.decode(raw)
+  if not data then return nil, decodeErr end
+  local ok, manifest = pcall(Manifest.validate, data, path)
+  if not ok then return nil, manifest end
+  return manifest
+end
+
+-- Scan "mods/" one level deep for valid manifests (mirrors Loader:_discover,
+-- but validates only -- no entry chunk is ever loaded).  First id wins on a
+-- duplicate.  Returns an array of validated manifests.
+local function discover()
+  local fs = love and love.filesystem
+  local out = {}
+  if not (fs and fs.getInfo and fs.getDirectoryItems) then return out end
+  if not fs.getInfo("mods") then return out end
+  local seen = {}
+  for _, name in ipairs(fs.getDirectoryItems("mods")) do
+    local path = "mods/" .. name
+    local info = fs.getInfo(path)
+    if info and info.type == "directory" then
+      local raw = fs.read(path .. "/manifest.json")
+      if raw then
+        local manifest = decodeManifest(raw, path)
+        if manifest and not seen[manifest.id] then
+          seen[manifest.id] = true
+          out[#out + 1] = manifest
+        end
+      end
+    end
+  end
+  return out
+end
+
+-- list() -> the mods-panel rows for the current install.  Reads the same
+-- options.mods enable-state the loader persists, so a toggle here is what the
+-- game sees on its next boot.
+function LauncherMods.list()
+  local options = SaveData.loadOptions()
+  return LauncherMods.deriveList(discover(), options)
+end
+
+-- setEnabled(id, enabled): persist options.mods[id] in the exact shape
+-- Loader:_saveState writes (a plain boolean), so the running game and the
+-- in-game ManagerState pick it up unchanged.
+function LauncherMods.setEnabled(id, enabled)
+  local options = SaveData.loadOptions()
+  options.mods = options.mods or {}
+  options.mods[id] = enabled and true or false
+  SaveData.saveOptions(options)
+  return true
+end
+
+-- ------- install (love.filesystem)
+
+-- Read a .zip source into bytes.  A string is an external absolute path (like
+-- a chosen ROM) read with io.*, falling back to a save-dir-relative
+-- love.filesystem read; a love DroppedFile is opened the way RomImporter
+-- ingests dropped ROMs.
+local function readArchive(source)
+  local t = type(source)
+  if (t == "userdata" or t == "table") and type(source.open) == "function" then
+    local ok = source:open("r")
+    if not ok then return nil, "could not open the dropped file" end
+    local data = source:read(source:getSize())
+    source:close()
+    if not data then return nil, "the dropped file could not be read" end
+    return data
+  end
+  if t == "string" then
+    local f = io.open(source, "rb")
+    if f then
+      local data = f:read("*a")
+      f:close()
+      if not data then return nil, "could not read " .. source end
+      return data
+    end
+    if love and love.filesystem then
+      local data = love.filesystem.read(source)
+      if data then return data end
+    end
+    return nil, "could not open " .. source
+  end
+  return nil, "unsupported archive source"
+end
+
+-- Shallow listing of a mounted archive shaped for locateRoot: files by name,
+-- and for each top-level directory a "<dir>/manifest.json" marker only when it
+-- actually holds one (so a lone folder with no manifest still reads as empty).
+local function topLevelPaths(mount)
+  local fs = love.filesystem
+  local paths = {}
+  for _, name in ipairs(fs.getDirectoryItems(mount)) do
+    local info = fs.getInfo(mount .. "/" .. name)
+    if info and info.type == "directory" then
+      if fs.getInfo(mount .. "/" .. name .. "/manifest.json", "file") then
+        paths[#paths + 1] = name .. "/manifest.json"
+      end
+    else
+      paths[#paths + 1] = name
+    end
+  end
+  return paths
+end
+
+local function copyTree(src, dst)
+  local fs = love.filesystem
+  if not fs.createDirectory(dst) then
+    return nil, "could not create " .. dst
+  end
+  for _, name in ipairs(fs.getDirectoryItems(src)) do
+    local s = src .. "/" .. name
+    local d = dst .. "/" .. name
+    local info = fs.getInfo(s)
+    if info and info.type == "directory" then
+      local ok, err = copyTree(s, d)
+      if not ok then return nil, err end
+    else
+      local data = fs.read(s)
+      if data == nil then return nil, "could not read " .. name end
+      local ok, err = fs.write(d, data)
+      if not ok then return nil, "could not write " .. name .. ": " .. tostring(err) end
+    end
+  end
+  return true
+end
+
+local function removeTree(path)
+  local fs = love.filesystem
+  local info = fs.getInfo(path)
+  if not info then return end
+  if info.type == "directory" then
+    for _, child in ipairs(fs.getDirectoryItems(path)) do
+      removeTree(path .. "/" .. child)
+    end
+  end
+  fs.remove(path)
+end
+
+-- installZip(source) -> true, id  |  nil, errString
+-- source is an external path or a love DroppedFile.  The archive is validated
+-- BEFORE anything is copied; every path unmounts and clears the staged temp
+-- file, and a failed copy rolls its partial tree back.  A dropped file outside
+-- the save dir is staged into a save-dir temp first, because
+-- love.filesystem.mount only reaches a save-directory-relative path.
+function LauncherMods.installZip(source)
+  if not (love and love.filesystem) then
+    return nil, "mod install needs LOVE"
+  end
+  local fs = love.filesystem
+  local data, readErr = readArchive(source)
+  if not data then return nil, readErr end
+
+  -- stage into a save-dir temp so mount can reach it
+  local tmp = ("mod_import_%d_%d.zip"):format(os.time(), math.random(0, 999999))
+  local ok, writeErr = fs.write(tmp, data)
+  if not ok then
+    return nil, "could not stage the .zip: " .. tostring(writeErr)
+  end
+  local mount = "mod_import_mount"
+  if not fs.mount(tmp, mount) then
+    fs.remove(tmp)
+    return nil, "that .zip could not be opened"
+  end
+  local function cleanup()
+    pcall(fs.unmount, tmp)
+    fs.remove(tmp)
+  end
+
+  local prefix, rootErr = LauncherMods.locateRoot(topLevelPaths(mount))
+  if not prefix then
+    cleanup()
+    return nil, rootErr
+  end
+  local root = prefix == "" and mount or (mount .. "/" .. prefix)
+
+  local raw = fs.read(root .. "/manifest.json")
+  if not raw then
+    cleanup()
+    return nil, "the .zip has no readable manifest.json"
+  end
+  local manifest, manifestErr = decodeManifest(raw, root)
+  if not manifest then
+    cleanup()
+    return nil, "invalid mod manifest: " .. tostring(manifestErr)
+  end
+
+  -- reject a duplicate before touching the mods tree
+  local dest = "mods/" .. manifest.id
+  if fs.getInfo(dest) then
+    cleanup()
+    return nil, "a mod named '" .. manifest.id .. "' is already installed"
+  end
+
+  fs.createDirectory("mods")
+  local copied, copyErr = copyTree(root, dest)
+  if not copied then
+    removeTree(dest)
+    cleanup()
+    return nil, copyErr or "could not copy the mod files"
+  end
+  cleanup()
+  return true, manifest.id
+end
+
+return LauncherMods

src/mods/Schemas.lua

@@ -40,6 +40,19 @@ function f.int(min, max)
     end }
 end
 
+-- a bounded float; like f.int but keeps the fractional part (scales,
+-- gains).  Rejects out-of-range with the "expected number a..b" message.
+function f.numRange(min, max)
+  local desc = "number"
+  if min and max then desc = ("number %s..%s"):format(min, max)
+  elseif min then desc = ("number >= %s"):format(min) end
+  return { kind = "num", min = min, max = max, desc = desc,
+    check = function(v)
+      return type(v) == "number"
+        and (min == nil or v >= min) and (max == nil or v <= max)
+    end }
+end
+
 function f.enum(values)
   local set = {}
   for _, value in ipairs(values) do set[value] = true end
@@ -420,6 +433,12 @@ R.pokemon = {
                                         frames = f.opt(f.int(1)) } }),
     cry = f.opt(f.id("cries")), palette = f.opt(f.id("palettes")),
     trueColor = f.opt(f.bool),
+    -- battle-pic scale overrides for this species' own pics: front is the
+    -- enemy pic (default 1x), back is the player pic (default 2x).  An
+    -- image-level battle_sprite_scales entry for the same path beats these.
+    -- The pic stays grounded (feet pinned) at any scale; see docs/modding.md.
+    battleScaleFront = f.opt(f.numRange(0.25, 4.0)),
+    battleScaleBack = f.opt(f.numRange(0.25, 4.0)),
   },
   example = 'mod.content.pokemon:patch("MEW", { baseStats = { attack = 120 } })',
 }
@@ -791,6 +810,118 @@ R.transitions = {
   example = 'mod.content.transitions:register("dissolve", { frames = 30, draw = fn })',
 }
 
+-- ------- rendering pipelines
+--
+-- A pipeline is a display mode that owns part of the frame: it may replace
+-- the overworld's world pass with geometry of its own (drawWorld) and/or
+-- post-process the finished composite (present).  Everything around that --
+-- the OFF/1/2/3 ladder, its options row, its hotkey, persistence in
+-- save.options.pipelines and the gating that keeps it out of battles and
+-- menus -- is engine plumbing driven from this record, so a renderer mod
+-- declares what it is and writes only the two draw functions.
+--
+-- Both callbacks are optional and independent: a present-only pipeline is a
+-- post-process (bloom, tilt-shift, a CRT curve) that leaves whatever
+-- rendered the frame alone, and a drawWorld-only pipeline is a world
+-- renderer that composites straight.  See src/render/Pipelines.lua for the
+-- ctx each receives and docs/modding.md for the worked example.
+R.render_pipelines = {
+  semantics = "record", target = "render_pipelines",
+  fields = {
+    -- shown in the options menu; the ladder labels default to OFF/ON
+    label = f.str,
+    levels = f.opt(f.list(f.str)),
+    -- keyboard key that cycles the ladder, checked after the engine's own
+    -- display hotkeys so a pipeline can never shadow one
+    hotkey = f.opt(f.str),
+    -- higher wins when two world pipelines are somehow active at once;
+    -- also the options-row order, so a mode and its post-process sort
+    -- together instead of by id
+    priority = f.opt(f.num),
+    -- hardware/driver gate, checked every frame: false keeps the vanilla
+    -- 2D path, which is what a headless run and a driver with no depth
+    -- canvas both get
+    available = f.opt(f.fn),
+    -- (top, overworld) -> boolean: whether the player may CHANGE the mode
+    -- right now.  Defaults to the survey-zoom gate (free-roam overworld
+    -- only), which keeps a hotkey press from switching modes mid-warp or
+    -- mid-cutscene.  It has no say over whether an already-on mode draws:
+    -- a mode that stopped rendering during a warp would flash the flat 2D
+    -- world every time the player walked through a door.
+    gate = f.opt(f.fn),
+    -- (dt, level): presentational tweens, ticked on real frame time
+    update = f.opt(f.fn),
+    -- (ctx) -> canvas | nil: render the world.  nil falls back to the
+    -- vanilla flat/tilt draw for this frame.
+    drawWorld = f.opt(f.fn),
+    -- (canvas, ctx) -> canvas: post-process the WORLD image, before the UI
+    -- composites over it -- a depth-of-field or colour grade that must not
+    -- touch the dialog boxes and menus sitting on top.  Only runs when some
+    -- pipeline rendered the world, since the vanilla world pass has no
+    -- single finished image to hand over.
+    worldPresent = f.opt(f.fn),
+    -- (canvas, ctx) -> canvas: post-process the whole finished composite,
+    -- world and UI alike (a CRT curve, a full-screen grade).  Must return a
+    -- canvas; the input unchanged is the correct answer when the effect is
+    -- off.
+    present = f.opt(f.fn),
+    -- drop GPU objects (window resize, hot reload, mode switch)
+    invalidate = f.opt(f.fn),
+  },
+  -- a pipeline that does neither half is dead weight and would silently
+  -- occupy an options row and a hotkey
+  extra = function(_, value)
+    if value.drawWorld == nil and value.present == nil
+        and value.worldPresent == nil then
+      return "a render pipeline needs drawWorld, worldPresent or present"
+    end
+  end,
+  -- A pipeline callback fails at play time, long after the load phase has
+  -- handed its report to the mod manager, so the merge leaves behind who
+  -- wrote each record for Pipelines to name in the failure -- the same
+  -- provenance trick the audio registries use (Loader.stampAudioOwners).
+  -- Placement is otherwise the default record merge.
+  write = function(target, registry)
+    local owners, tombstones = {}, {}
+    for id in pairs(registry.ops) do
+      local value = registry:get(id)
+      if value == nil then
+        tombstones[#tombstones + 1] = id
+      else
+        target[id] = value
+        local owner = registry.owners[id]
+        if owner and owner ~= Schemas.ENGINE then owners[id] = owner end
+      end
+    end
+    for _, id in ipairs(tombstones) do target[id] = nil end
+    target._owners = owners
+  end,
+  example = 'mod.content.render_pipelines:register("voxel", ' ..
+    '{ label = "VOXEL", levels = { "OFF", "15", "35", "50" }, drawWorld = fn })',
+}
+
+-- ------- battle sprite scales
+--
+-- Per-image battle-pic scale overrides, keyed by record id and consulted
+-- by asset path at draw time.  Where a species' battleScaleFront /
+-- battleScaleBack scales its own front/back pic, this scales ANY battle
+-- pic by the path it is drawn from -- the only handle on the non-species
+-- pics like the player's trainer back sprite.  Image-level beats
+-- species-level; both compose with the send-out grow and keep the sprite
+-- grounded (feet pinned) at whatever scale.  See docs/modding.md.
+R.battle_sprite_scales = {
+  semantics = "record", target = "battle_sprite_scales",
+  fields = {
+    -- the asset path exactly as data references it, e.g.
+    -- "assets/generated/battle/back/abrab.png"
+    path = f.path,
+    -- 1 = native pixels; the drawn size relative to the pic's own pixels
+    scale = f.numRange(0.25, 4.0),
+  },
+  example = 'mod.content.battle_sprite_scales:register("abra_back", ' ..
+    '{ path = "assets/generated/battle/back/abrab.png", scale = 1.5 })',
+}
+
 -- ------- progression
 
 R.evolution_methods = {

src/pokemon/Evolution.lua

@@ -106,11 +106,55 @@ function Evolution.apply(game, mon, newSpecies, via)
   })
 end
 
+-- After the "evolved into" text, Gen1 re-runs the level-up learn check on
+-- the EVOLVED species (engine/pokemon/evos_moves.asm EvolveMon calls the
+-- LearnMoveFromLevelUp predef, engine/pokemon/learn_move.asm) -- a mon
+-- evolving at exactly a learnset level gains that move (GYARADOS learns
+-- BITE at 20, so MAGIKARP->GYARADOS @20 learns BITE, @21 does not) (#12).
+-- Mirrors the rare-candy learn loop in src/ui/BagMenu.lua so a full move
+-- list opens the forget prompt.  mon.species is already the new species
+-- (Evolution.apply ran before the congrats text).  onDone runs once the
+-- learn list is exhausted, replacing the caller's direct onDone.
+function Evolution.learnEvolutionMoves(game, mon, onDone)
+  local Experience = require("src.battle.Experience")
+  local def = game.data.pokemon[mon.species]
+  -- movesLearnedAt uses entry.level == level (exact Gen1 rule); do NOT use
+  -- Pokemon.movesAtLevel (<= level), which would over-grant older moves.
+  local moves = Experience.movesLearnedAt(def, mon.level)
+  local i = 0
+  local function nextStep()
+    i = i + 1
+    local moveId = moves[i]
+    if not moveId then
+      if onDone then onDone() end
+      return
+    end
+    for _, mv in ipairs(mon.moves) do
+      if mv.id == moveId then return nextStep() end
+    end
+    local mdef = game.data.moves[moveId]
+    if not mdef then return nextStep() end
+    local name = mon.nickname or def.name
+    if #mon.moves < 4 then
+      table.insert(mon.moves, { id = moveId, pp = mdef.pp })
+      Runtime.emit("pokemon.move_learned", { mon = mon, moveId = moveId })
+      game.stack:push(TextBox.new(game,
+        ("%s learned\n%s!"):format(name, mdef.name), nextStep))
+    else
+      -- LearnMoveFromLevelUp with a full moveset: the forget UI
+      Screens.push(game, "MoveLearnMenu", mon, moveId, nextStep)
+    end
+  end
+  nextStep()
+end
+
 -- Play the evolution movie (flashing forms), then apply + text.
 -- Headless (no real graphics) falls back to the plain text flow.
 function Evolution.evolve(game, mon, newSpecies, onDone, via)
   if love.image and love.image.newImageData then
-    Screens.push(game, "EvolutionState", mon, newSpecies, onDone)
+    -- forward `via` so EvolutionState can keep trade evolutions
+    -- non-cancelable (LINK_STATE_TRADING) while others accept B (#213)
+    Screens.push(game, "EvolutionState", mon, newSpecies, onDone, via)
     return
   end
   Music.play(game.data, Music.special(game.data, "evolution"))
@@ -120,7 +164,9 @@ function Evolution.evolve(game, mon, newSpecies, onDone, via)
               :format(oldName, oldName, game.data.pokemon[newSpecies].name)
   game.stack:push(TextBox.new(game, msg, function()
     Music.restoreMap(game.data)
-    if onDone then onDone() end
+    -- re-run the evolved species' level-up learn check before onDone
+    -- (evos_moves.asm EvolveMon -> learn_move.asm LearnMoveFromLevelUp, #12)
+    Evolution.learnEvolutionMoves(game, mon, onDone)
   end))
 end
 
@@ -138,13 +184,22 @@ function Evolution.request(game, mon, trigger, onDone)
   return species
 end
 
--- After-battle hook: evolve everyone who qualifies (queued one at a time).
-function Evolution.checkParty(game, onDone)
+-- After-battle hook: evolve mons that leveled this battle and still
+-- qualify (queued one at a time, party order).  Gen1 EvolveAfterBattle
+-- only considers mons that gained a level during the fight — a B-cancel
+-- means "not this time", and the next offer waits for the next level-up
+-- (or Rare Candy / stone, which call Evolution.evolve directly).
+-- leveledUp is a set of party mon tables; nil/empty yields no evolutions.
+function Evolution.checkParty(game, onDone, leveledUp)
   local pending = {}
-  for _, mon in ipairs(game.save.party) do
-    local target, evo = Evolution.pendingFor(game, mon, { kind = "levelup" })
-    if target then
-      table.insert(pending, { mon = mon, to = target, via = evo and evo.method })
+  if leveledUp then
+    for _, mon in ipairs(game.save.party) do
+      if leveledUp[mon] then
+        local target, evo = Evolution.pendingFor(game, mon, { kind = "levelup" })
+        if target then
+          table.insert(pending, { mon = mon, to = target, via = evo and evo.method })
+        end
+      end
     end
   end
   local i = 0

src/pokemon/Pokemon.lua

@@ -29,6 +29,34 @@ function Pokemon.movesAtLevel(speciesDef, level)
   return moves
 end
 
+-- Day Care retrieve (pokered WriteMonMoves + wLearningMovesFromDayCare):
+-- grant learnset moves with startLevel < moveLevel <= newLevel, shifting
+-- the oldest slot out when full. Silent — no LearnMove prompts.
+function Pokemon.learnMovesFromDayCare(data, mon, speciesDef, startLevel, newLevel)
+  if not (speciesDef and speciesDef.learnset and mon) then return end
+  mon.moves = mon.moves or {}
+  for _, entry in ipairs(speciesDef.learnset) do
+    local moveLevel = entry.level
+    if moveLevel > newLevel then break end
+    if moveLevel > startLevel then
+      local known = false
+      for _, mv in ipairs(mon.moves) do
+        if mv.id == entry.move then known = true break end
+      end
+      if not known then
+        local mdef = data.moves[entry.move]
+        local slot = { id = entry.move, pp = mdef and mdef.pp or 0 }
+        if #mon.moves < 4 then
+          mon.moves[#mon.moves + 1] = slot
+        else
+          table.remove(mon.moves, 1)
+          mon.moves[#mon.moves + 1] = slot
+        end
+      end
+    end
+  end
+end
+
 function Pokemon.new(data, species, level, rng)
   local def = data.pokemon[species]
   assert(def, "unknown species " .. tostring(species))

src/render/HudTiles.lua

@@ -77,7 +77,17 @@ end
 -- one-pixel sliver.  The fill is tinted with the SGB bar palettes at
 -- GetHealthBarColor's thresholds (>= 27 px green, >= 10 yellow, else
 -- red).
-function HudTiles.drawHPBar(data, tx, ty, mon, barType)
+--
+-- grayFill (#229): when the caller will colorize this bar with an SGB
+-- region palette (BattleState's zone pass, BATTLE_ZONES pal 0/1 =
+-- GetHealthBarColor), leave the fill as its raw DMG shade-2 gray and skip
+-- the per-pixel tint -- the DMG hardware bar is ONE gray shade recolored by
+-- the region palette (engine/gfx/palettes.asm SetPal_Battle,
+-- data/sgb/sgb_packets.asm BlkPacket_Battle), never a per-pixel repaint.
+-- Tinting first would double-apply the color: GREENBAR's fill {0,189,0} has
+-- red channel 0, so the tint zeroes the whole bar's red and the zone's
+-- red-channel-keyed shade shader then maps every pixel to color 3 = black.
+function HudTiles.drawHPBar(data, tx, ty, mon, barType, grayFill)
   local x, y = tx * 8, ty * 8
   HudTiles.tile(0x71, x, y)
   HudTiles.tile(0x62, x + 8, y)
@@ -86,15 +96,17 @@ function HudTiles.drawHPBar(data, tx, ty, mon, barType)
     px = math.max(1, math.floor(mon.hp * 48 / mon.stats.hp))
   end
   local tint
-  local PaletteFX = require("src.render.PaletteFX")
-  local name = px >= 27 and "GREENBAR" or px >= 10 and "YELLOWBAR" or "REDBAR"
-  local colors = PaletteFX.pal(data, name)
-  if colors then
-    local c = colors[3] -- GB color 2 is the fill shade
-    -- the fill pixels are the 2/3-gray shade; divide so they land on
-    -- the palette color exactly (the black outline stays black)
-    tint = { math.min(1, c[1] / 170), math.min(1, c[2] / 170),
-             math.min(1, c[3] / 170), 1 }
+  if not grayFill then
+    local PaletteFX = require("src.render.PaletteFX")
+    local name = px >= 27 and "GREENBAR" or px >= 10 and "YELLOWBAR" or "REDBAR"
+    local colors = PaletteFX.pal(data, name)
+    if colors then
+      local c = colors[3] -- GB color 2 is the fill shade
+      -- the fill pixels are the 2/3-gray shade; divide so they land on
+      -- the palette color exactly (the black outline stays black)
+      tint = { math.min(1, c[1] / 170), math.min(1, c[2] / 170),
+               math.min(1, c[3] / 170), 1 }
+    end
   end
   for i = 0, 5 do
     local seg = math.min(8, math.max(0, px - i * 8))

src/render/PaletteFX.lua

@@ -50,14 +50,23 @@ PaletteFX.GBC_OBJ = {
 }
 
 -- OG BLUE: Pokemon Blue's Game Boy Color boot-ROM auto-palette.  Same
--- one-global-pair scheme as OG RED (Blue also ships no CGB code), but the
--- boot ROM colorizes the background blue instead of red -- so "OG RED" for a
--- Blue playthrough is white -> light blue -> dark blue -> black, mirroring
--- GBC_BG channel-for-channel so the blue reads at the same brightness.  The
--- OBJ (sprite) palette stays the same green, matching how Red and Blue share
--- the green-character look on a Game Boy Color.
+-- one-global-pair scheme as OG RED (Blue also ships no CGB code), but the boot
+-- ROM gives Blue its OWN entry rather than a recolored Red: a light-blue/blue
+-- BACKGROUND and -- unlike Red -- a PINK object palette (OBP0).  Values from
+-- Bulbapedia's "List of color palettes ... Generation I" GBC boot-ROM table
+-- (BG 0x63A5FF/0x0000FF, OBJ 0xFF8484/0x943A3A), confirmed against a Gambatte
+-- hardware capture.  The earlier code mirrored GBC_BG channel-for-channel
+-- (0x8484FF/0x3A3A94) and reused Red's green sprites for both versions on the
+-- premise that Red and Blue "share the green-character look"; both premises
+-- are wrong -- Blue's background is a genuinely different blue and its
+-- characters are pink (#155).  Lightest shade first, like GBC_BG.
 PaletteFX.GBC_BG_BLUE = {
-  { 255, 255, 255 }, { 132, 132, 255 }, { 58, 58, 148 }, { 0, 0, 0 },
+  { 255, 255, 255 }, { 99, 165, 255 }, { 0, 0, 255 }, { 0, 0, 0 },
+}
+-- Blue's OBJ palette (OBP0) is the red/pink ramp -- the very same colors OG
+-- RED uses for its BACKGROUND (GBC_BG), just applied to objects instead.
+PaletteFX.GBC_OBJ_BLUE = {
+  { 255, 255, 255 }, { 255, 132, 132 }, { 148, 58, 58 }, { 0, 0, 0 },
 }
 
 -- The active game's OG boot-ROM background palette: blue for a Blue
@@ -69,6 +78,16 @@ function PaletteFX.ogBg()
   return PaletteFX.GBC_BG
 end
 
+-- The active game's OG boot-ROM object palette (OBP0): Blue's pink ramp for a
+-- Blue playthrough, Red's green otherwise.  Returns the colors AND a
+-- version-distinct cache-group string, because SpriteRenderer.getObpImage keys
+-- its baked-image cache by (image path, group): a shared group would collide a
+-- Red bake with a Blue one and one version would show the other's colors.
+function PaletteFX.ogObj()
+  if GameVersion.isBlue() then return PaletteFX.GBC_OBJ_BLUE, "gbcobj_blue" end
+  return PaletteFX.GBC_OBJ, "gbcobj"
+end
+
 local INV_MAP = { [0] = 3, [1] = 2, [2] = 1, [3] = 0 }
 
 function PaletteFX.shader()
@@ -183,17 +202,25 @@ function PaletteFX.usesGbcPack(mode)
 end
 
 -- Whether the active mode bakes a per-OBJ palette onto overworld sprites
--- (the OBP bake + post-zone redraw path).  ONLY OG RED does: it wears the
--- GBC boot-ROM green object palette (PaletteFX.GBC_OBJ) so the player and
--- NPCs stay green over the red background, exactly like Pokemon Red on a
--- Game Boy Color.  SGB mode deliberately does NOT: an SGB OBJ carries no
--- palette of its own, so the characters tint with the whole-map region
--- palette along with the terrain (the Super Game Boy never colored Pokemon
--- Red's sprites separately -- baking a per-sprite palette there was the
--- "reds coloring on the player/NPCs" bug).  RED++ colors sprites through
--- the usesGbcPack() path in SpriteRenderer instead.
+-- (the OBP bake + post-zone redraw path).  OG RED and SGB both do: characters
+-- wear the GBC boot-ROM object palette (PaletteFX.ogObj -- green over Red's red
+-- background, pink over Blue's blue background), so the player and NPCs carry a
+-- fixed object color instead of tinting with whatever region palette their
+-- feet stand over.  On real hardware a sprite is an OBJ colored by an OBJ
+-- palette (color/sprites.asm ColorOverworldSprite), distinct from the BG it
+-- overlaps -- so Red's cap must stay green in tall grass, not turn the ROUTE
+-- palette's light-blue (issue #150: SGB region-tinting sent the cap to shade-2
+-- = light-blue and the character clashed with the grass it should blend into).
+-- Terrain is unaffected -- pal() below still hands SGB its per-map BG palette;
+-- only OG RED short-circuits BG to the one global red palette.  An EARLIER
+-- attempt at per-sprite SGB color baked GBC_BG (the RED background ramp) onto
+-- characters -- that was the "reds coloring on the player/NPCs" bug; the object
+-- palette is GBC_OBJ (green), so baking it here is the fix, not that
+-- regression.  RED++ colors sprites through the usesGbcPack() path in
+-- SpriteRenderer instead.
 function PaletteFX.usesSpriteObp(mode)
-  return (mode or PaletteFX.mode) == "ogred"
+  mode = mode or PaletteFX.mode
+  return mode == "ogred" or mode == "gbc"
 end
 
 -- ------- post-zone sprite redraw (GBC mode)

src/render/Pipelines.lua

@@ -0,0 +1,423 @@
+-- Rendering pipelines: the engine side of the render_pipelines registry.
+--
+-- A pipeline is a display mode a mod owns.  It may replace the overworld's
+-- world pass with geometry of its own (drawWorld) and/or post-process the
+-- finished composite (present).  Everything else about being a display mode
+-- -- the OFF/1/2/3 ladder, the options row, the hotkey, persistence, the
+-- free-roam gate, and never letting a mod's error take the frame down -- is
+-- engine plumbing and lives here, so a renderer mod writes the two draw
+-- functions and declares the rest.
+--
+-- The two halves compose independently and in priority order: the highest
+-- priority eligible drawWorld renders the world, then every eligible
+-- present folds over whatever came out (the world pipeline's canvas, or the
+-- vanilla flat/tilt composite when none ran).  A present that is switched
+-- off returns its input, so a full ladder of them costs nothing at level 0.
+--
+-- Nothing here reaches collision, movement, triggers or scripts: like
+-- survey zoom and tilt, a pipeline is purely presentational, which is why
+-- its level rides in save.options rather than the save proper.
+--
+-- Spec: docs/modding.md (rendering pipelines)
+
+local Data = require("src.core.Data")
+local Logger = require("src.core.Logger")
+local Runtime = require("src.mods.Runtime")
+local Zoom = require("src.render.Zoom")
+
+local Pipelines = {}
+
+-- id -> level.  Levels live here rather than on the records because the
+-- records are merged content: frozen after load, and shared with whatever
+-- else reads Data.
+local levels = {}
+
+-- ids whose callbacks have already thrown, so a pipeline that fails every
+-- frame reports once instead of filling the log at 60Hz
+local broken = {}
+
+Pipelines.DEFAULT_LEVELS = { "OFF", "ON" }
+
+-- The merged dataset the records live in.  The boot singleton is the
+-- default -- Game.data is that very table -- and install() lets a headless
+-- caller (the SDK harness, a tool) point this at a dataset of its own.
+local source = Data
+
+function Pipelines.install(data)
+  source = data or Data
+  Pipelines.reset()
+end
+
+-- ------- catalog
+
+-- Every registered pipeline as { id = ..., def = ... }, ordered by priority
+-- (descending, ties by id) so selection, the options rows and the present
+-- fold all walk the same sequence.
+--
+-- Memoized on the namespace table's identity.  Content freezes at the merge
+-- boundary, so the answer cannot change for a given table -- and this is
+-- read several times per frame by update(), worldPipeline() and the
+-- endFrame present check, which is no place to allocate and sort.  An empty
+-- list is cached too, so a mod-free boot pays one table for the process.
+local listCache, listSource = nil, nil
+
+function Pipelines.list()
+  local defs = source and source.render_pipelines
+  if defs == listSource and listCache then return listCache end
+  local out = {}
+  if type(defs) == "table" then
+    for id, def in pairs(defs) do
+      -- the merge writes provenance under _owners; skip the bookkeeping
+      -- keys rather than treating them as pipelines
+      if type(id) == "string" and id:sub(1, 1) ~= "_" and type(def) == "table" then
+        out[#out + 1] = { id = id, def = def }
+      end
+    end
+    table.sort(out, function(a, b)
+      local pa, pb = a.def.priority or 0, b.def.priority or 0
+      if pa ~= pb then return pa > pb end
+      return a.id < b.id
+    end)
+  end
+  listCache, listSource = out, defs
+  return out
+end
+
+function Pipelines.get(id)
+  local defs = source and source.render_pipelines
+  local def = type(defs) == "table" and defs[id] or nil
+  return type(def) == "table" and def or nil
+end
+
+-- the mod that registered a pipeline, so a runtime failure lands in the
+-- feed the mod manager shows instead of only in the console
+local function ownerOf(id)
+  local defs = source and source.render_pipelines
+  local owners = type(defs) == "table" and defs._owners or nil
+  return owners and owners[id] or nil
+end
+
+-- Run one of a pipeline's callbacks under pcall.  A mod that throws mid-
+-- frame must not take the frame with it: the pipeline is marked broken,
+-- attributed once, and treated as absent from then on -- which degrades to
+-- the vanilla 2D path rather than a black screen.
+local function guard(id, fn, ...)
+  if broken[id] then return nil end
+  local ok, result = pcall(fn, ...)
+  if ok then return result end
+  broken[id] = true
+  Logger.error("render pipeline %s failed: %s -- disabled for this session",
+               id, tostring(result))
+  Runtime.reportError(ownerOf(id), "render pipeline failed: " .. tostring(result))
+  return nil
+end
+
+-- Whether a callback's return is a real Canvas we can composite.  A mod that
+-- forgets a return, or hands back a shade string / flag / number, must be
+-- ignored rather than trusted -- draw() on a non-canvas takes the frame down.
+-- Real LOVE canvases are userdata answering typeOf("Canvas"); the headless
+-- test stub (tests/love_stub) fakes them as tables carrying the Canvas method
+-- shape (love.graphics.newCanvas), so accept either and nothing else.
+local function isCanvas(v)
+  if type(v) == "userdata" then
+    return type(v.typeOf) == "function" and v:typeOf("Canvas") == true
+  end
+  if type(v) == "table" then
+    return type(v.getWidth) == "function" and type(v.getHeight) == "function"
+  end
+  return false
+end
+
+-- Dispatch a mod render callback with its GPU state fenced off: push("all")
+-- before and pop() after, so a callback that returns cleanly but leaves a
+-- shader bound, the canvas redirected, or blend/colour changed cannot corrupt
+-- the engine composite that follows.  guard() catches a callback that throws;
+-- this catches one that dirties state.  A pipeline already retired skips the
+-- push/pop entirely, so the stack stays balanced.
+local function guardRender(id, fn, ...)
+  if broken[id] then return nil end
+  love.graphics.push("all")
+  local out = guard(id, fn, ...)
+  love.graphics.pop()
+  return out
+end
+
+-- ------- levels
+
+function Pipelines.levelLabels(id)
+  local def = Pipelines.get(id)
+  local labels = def and def.levels
+  if type(labels) ~= "table" or labels[1] == nil then
+    return Pipelines.DEFAULT_LEVELS
+  end
+  return labels
+end
+
+-- highest selectable level: one less than the label count, so a two-label
+-- ladder is a plain OFF/ON toggle
+function Pipelines.maxLevel(id)
+  return #Pipelines.levelLabels(id) - 1
+end
+
+function Pipelines.level(id)
+  return levels[id] or 0
+end
+
+function Pipelines.levelLabel(id, level)
+  local labels = Pipelines.levelLabels(id)
+  return labels[(level or Pipelines.level(id)) + 1] or labels[1] or "OFF"
+end
+
+-- A world pipeline and the engine's own tilt mode are two answers to the
+-- same question, so switching one on switches the other off -- the rule
+-- tilt and survey zoom already follow between themselves.  Present-only
+-- pipelines (post-processes) compose with tilt and are left alone.
+local function excludeTilt(id, level)
+  local def = Pipelines.get(id)
+  if not (def and def.drawWorld) or level <= 0 then return end
+  local Tilt = require("src.render.Tilt")
+  if Tilt.level > 0 then Tilt.setLevel(0) end
+  -- one world pipeline at a time, for the same reason
+  for _, entry in ipairs(Pipelines.list()) do
+    if entry.id ~= id and entry.def.drawWorld and Pipelines.level(entry.id) > 0 then
+      levels[entry.id] = 0
+    end
+  end
+end
+
+function Pipelines.setLevel(id, level)
+  if not Pipelines.get(id) then return 0 end
+  level = math.floor(tonumber(level) or 0)
+  if level < 0 then level = 0 end
+  local max = Pipelines.maxLevel(id)
+  if level > max then level = max end
+  levels[id] = level
+  excludeTilt(id, level)
+  return level
+end
+
+-- Advance the ladder and wrap to OFF, the shape every display hotkey walks.
+function Pipelines.cycle(id, dir)
+  local max = Pipelines.maxLevel(id)
+  if max < 1 then return 0 end
+  local span = max + 1
+  local target = (Pipelines.level(id) + (dir or 1)) % span
+  if target < 0 then target = target + span end
+  return Pipelines.setLevel(id, target)
+end
+
+-- Turning a world pipeline on must switch tilt off in the save too, not
+-- just in the live module, or the next boot restores both.  Call sites hand
+-- over the options table so this stays the one place that rule lives.
+function Pipelines.syncOptions(opts)
+  if type(opts) ~= "table" then return end
+  local bucket = opts.pipelines
+  if type(bucket) ~= "table" then
+    bucket = {}
+    opts.pipelines = bucket
+  end
+  for _, entry in ipairs(Pipelines.list()) do
+    bucket[entry.id] = Pipelines.level(entry.id)
+    if entry.def.drawWorld and Pipelines.level(entry.id) > 0 then
+      opts.tilt = 0
+    end
+  end
+end
+
+-- Restore levels from a loaded options table.  A pipeline whose mod is gone
+-- keeps its stored level untouched in the bucket (so re-enabling the mod
+-- restores the mode) but contributes nothing while absent.
+function Pipelines.applyOptions(opts)
+  local bucket = type(opts) == "table" and opts.pipelines or nil
+  levels = {}
+  broken = {}
+  local world = nil
+  for _, entry in ipairs(Pipelines.list()) do
+    local stored = type(bucket) == "table" and bucket[entry.id] or 0
+    local level = math.floor(tonumber(stored) or 0)
+    if level < 0 then level = 0 end
+    local max = Pipelines.maxLevel(entry.id)
+    if level > max then level = max end
+    -- list() is priority order, so the first world pipeline with a stored
+    -- level is the one that wins; the rest restore to OFF rather than
+    -- sitting on a level that can never render
+    if entry.def.drawWorld and level > 0 then
+      if world then level = 0 else world = entry.id end
+    end
+    levels[entry.id] = level
+  end
+  -- a restored world pipeline and tilt are two answers to the same
+  -- question; the pipeline wins, as it does at every place that sets one
+  if world then require("src.render.Tilt").setLevel(0) end
+end
+
+function Pipelines.reset()
+  levels = {}
+  broken = {}
+end
+
+-- ------- per-frame
+
+-- Presentational tweens run on real frame time, like Tilt's.  Every
+-- pipeline ticks, not just the active ones: a mode easing back OUT still
+-- has an angle to retire.
+function Pipelines.update(dt)
+  for _, entry in ipairs(Pipelines.list()) do
+    if entry.def.update then
+      guardRender(entry.id, entry.def.update, dt, Pipelines.level(entry.id))
+    end
+  end
+end
+
+-- A pipeline may run this frame when it is switched on, has not thrown, and
+-- its hardware gate says yes.  `available` is consulted every frame rather
+-- than cached: a driver that loses its depth canvas on a resize has to be
+-- able to change its mind.
+--
+-- Deliberately NOT gated on the state stack.  `gate` governs whether the
+-- player may CHANGE the mode, never whether it draws -- a display mode that
+-- stopped rendering during a warp, a scripted cutscene or an open menu
+-- would flash the flat 2D world for those frames every time the player
+-- walked through a door.  Once a mode is on it renders until it is off.
+function Pipelines.eligible(id)
+  local def = Pipelines.get(id)
+  if not def or broken[id] then return false end
+  if Pipelines.level(id) <= 0 then return false end
+  if def.available and guard(id, def.available) ~= true then return false end
+  return true
+end
+
+-- Whether the player may cycle this mode right now: the free-roam gate,
+-- which keeps a hotkey press from switching modes mid-warp or mid-cutscene.
+-- Input only -- see eligible() for why the draw path does not consult it.
+function Pipelines.canToggle(id, top, overworld)
+  local def = Pipelines.get(id)
+  if not def then return false end
+  local gate = def.gate or Zoom.gateOK
+  return guard(id, gate, top, overworld) == true
+end
+
+-- The pipeline that owns the world pass right now, or nil for the vanilla
+-- flat/tilt draw.  Highest priority wins; the exclusion rules above mean
+-- there is normally only one candidate anyway.
+function Pipelines.worldPipeline()
+  for _, entry in ipairs(Pipelines.list()) do
+    if entry.def.drawWorld and Pipelines.eligible(entry.id) then
+      return entry.id, entry.def
+    end
+  end
+  return nil
+end
+
+-- Render the world through `id`.  Returns the canvas to composite, or nil
+-- when the pipeline declined this frame (nothing to draw, a transient
+-- failure), which the caller treats as "fall back to the 2D path".
+function Pipelines.drawWorld(id, ctx)
+  local def = Pipelines.get(id)
+  if not (def and def.drawWorld) then return nil end
+  return guardRender(id, def.drawWorld, ctx)
+end
+
+-- Fold every eligible world post-process over a pipeline's world image,
+-- before the UI composites on top.  This is where a depth-of-field or a
+-- colour grade belongs when it must leave the dialog boxes and menus crisp;
+-- `present` below is the whole-frame counterpart.  Only reachable once some
+-- pipeline rendered the world, so it is gated on the overworld state the
+-- same way drawWorld is.
+function Pipelines.worldPresent(canvas, ctx)
+  if canvas == nil then return nil end
+  for _, entry in ipairs(Pipelines.list()) do
+    if entry.def.worldPresent and Pipelines.eligible(entry.id) then
+      local out = guardRender(entry.id, entry.def.worldPresent, canvas, ctx)
+      -- accept only a real Canvas: a pass that returns a non-canvas (a
+      -- forgotten return, a shade string) is ignored, not folded in
+      if isCanvas(out) then canvas = out end
+    end
+  end
+  return canvas
+end
+
+-- Fold every eligible post-process over the finished frame.  Present
+-- pipelines are not gated on the overworld state -- a CRT curve or a colour
+-- grade applies to menus and battles too -- so eligibility here is just
+-- "switched on and available".  A pass that returns a non-canvas is
+-- ignored rather than trusted, so a mod cannot blank the screen by
+-- forgetting a return.
+function Pipelines.present(canvas, ctx)
+  if canvas == nil then return nil end
+  for _, entry in ipairs(Pipelines.list()) do
+    if entry.def.present and Pipelines.eligible(entry.id) then
+      local out = guardRender(entry.id, entry.def.present, canvas, ctx)
+      -- accept only a real Canvas: a pass that returns a non-canvas is
+      -- ignored (docstring above), so a mod cannot blank or crash the frame
+      -- by forgetting a return or handing back a truthy non-canvas
+      if isCanvas(out) then canvas = out end
+    end
+  end
+  return canvas
+end
+
+-- true when any present-only pass wants to run, so the composite path can
+-- skip allocating a target it would not use
+function Pipelines.wantsPresent()
+  for _, entry in ipairs(Pipelines.list()) do
+    if entry.def.present and Pipelines.eligible(entry.id) then return true end
+  end
+  return false
+end
+
+-- ------- input and UI
+
+-- Cycle whichever pipeline claims `key`.  Returns the id when one did, so
+-- the caller knows the key was consumed.  Checked after the engine's own
+-- display hotkeys, so a mod can never shadow one.
+function Pipelines.hotkey(key, top, overworld)
+  for _, entry in ipairs(Pipelines.list()) do
+    if entry.def.hotkey == key then
+      -- the gate belongs here and nowhere else: it stops the player
+      -- flipping modes mid-warp or mid-cutscene, and has no say over
+      -- whether an already-on mode draws
+      if Pipelines.canToggle(entry.id, top, overworld) then
+        Pipelines.cycle(entry.id)
+        return entry.id
+      end
+      return nil
+    end
+  end
+  return nil
+end
+
+-- Options rows for every registered pipeline, in the same priority order,
+-- in the descriptor shape src/ui/OptionRows.lua renders.
+function Pipelines.rows(game)
+  local rows = {}
+  for _, entry in ipairs(Pipelines.list()) do
+    local id = entry.id
+    rows[#rows + 1] = {
+      id = "pipeline:" .. id,
+      label = entry.def.label or id:upper(),
+      value = function() return Pipelines.levelLabel(id) end,
+      step = function(g, dir)
+        Pipelines.cycle(id, dir)
+        local opts = g and g.save and g.save.options
+        if opts then
+          Pipelines.syncOptions(opts)
+          -- the exclusion above may have switched tilt off; keep the live
+          -- module in step with the option it just wrote
+          require("src.render.Tilt").setLevel(opts.tilt or 0)
+        end
+        return true
+      end,
+    }
+  end
+  return rows
+end
+
+-- Drop every pipeline's GPU objects (window resize, hot reload).
+function Pipelines.invalidate()
+  for _, entry in ipairs(Pipelines.list()) do
+    if entry.def.invalidate then guardRender(entry.id, entry.def.invalidate) end
+  end
+end
+
+return Pipelines

src/render/Renderer.lua

@@ -9,12 +9,28 @@
 local Zoom = require("src.render.Zoom")
 local Tilt = require("src.render.Tilt")
 local PaletteFX = require("src.render.PaletteFX")
+local Pipelines = require("src.render.Pipelines")
 
 local Renderer = {}
 
 Renderer.WIDTH = 160
 Renderer.HEIGHT = 144
 
+-- Whether a value is a real Canvas we can composite.  Real LOVE canvases are
+-- userdata answering typeOf("Canvas"); the headless test stub fakes them as
+-- tables carrying the Canvas method shape.  A mod pipeline handing back a
+-- non-canvas must be rejected before it reaches love.graphics.draw, which
+-- would otherwise take the frame down with it.
+local function isCanvas(v)
+  if type(v) == "userdata" then
+    return type(v.typeOf) == "function" and v:typeOf("Canvas") == true
+  end
+  if type(v) == "table" then
+    return type(v.getWidth) == "function" and type(v.getHeight) == "function"
+  end
+  return false
+end
+
 -- Tilt mode: the upright billboard canvas is grown by this many world
 -- pixels on every side beyond the ground world view, so a structure or
 -- sprite standing near a view edge still draws in full instead of being
@@ -23,27 +39,42 @@ Renderer.HEIGHT = 144
 -- endFrame composites the padded canvas back with a matching offset.
 Renderer.UPRIGHT_MARGIN = 160
 
--- LOVE units + framebuffer pixels + the live unit→pixel ratio.
--- Android's DisplayMetrics.density (love.graphics.getDPIScale) is often
--- non-integer (1.5, 2.75, …).  Integer scaling in units then maps each GB
--- pixel to a fractional number of framebuffer pixels → shimmer, uneven /
--- non-square "pixels", and movement judder (issue #87).  Always derive the
--- crisp integer scale from the drawable pixel size; draw with (pixels/dpi)
--- so the GPU lands on whole framebuffer pixels.  Desktop dpi=1 is unchanged.
+-- LOVE units + framebuffer pixels + per-axis unit→pixel ratios.
+-- Android's DisplayMetrics.density is often non-integer (1.5, 2.75, …).
+-- Integer scaling in units then maps each GB pixel to a fractional number of
+-- framebuffer pixels → shimmer, uneven / non-square "pixels", and movement
+-- judder (issue #87).  Always derive the crisp integer scale from the
+-- *drawable* pixel size (the window framebuffer we present into -- not a
+-- combined multi-display metric), then draw with (pixels / axisDpi) so the
+-- GPU lands on whole framebuffer pixels.  Desktop dpi=1 is unchanged.
+--
+-- LOVE's projection is anisotropic: 1 unit in X covers pw/ww framebuffer
+-- pixels and 1 unit in Y covers ph/wh.  Those ratios match on a normal
+-- highdpi surface, but diverge when unit sizes are truncated independently
+-- (`(int)(pixels/density)`) or when a dual-screen / forced-rotation device
+-- reports mismatched unit vs drawable aspects (AYN Thor, issue #208).
+-- love.graphics.getDPIScale() is only ph/wh, so using it (or pw/ww alone)
+-- for both axes makes the other axis land on a fractional, stretched count.
+-- Keep separate dpiX/dpiY so each GB pixel covers fitScale() physical pixels
+-- on BOTH axes (square).
 local function displayMetrics()
   local ww, wh = love.graphics.getDimensions()
   local pw, ph = ww, wh
   if love.graphics.getPixelDimensions then
     pw, ph = love.graphics.getPixelDimensions()
   end
-  local dpi = 1
-  if ww > 0 and pw > 0 then
-    dpi = pw / ww
-  elseif love.graphics.getDPIScale then
-    dpi = love.graphics.getDPIScale()
+  local dpiX, dpiY = 1, 1
+  if ww > 0 and pw > 0 then dpiX = pw / ww end
+  if wh > 0 and ph > 0 then dpiY = ph / wh end
+  -- No pixel API (headless / old stub): fall back to getDPIScale, else 1.
+  if (dpiX == 1 and dpiY == 1) and not love.graphics.getPixelDimensions
+     and love.graphics.getDPIScale then
+    local d = love.graphics.getDPIScale()
+    if d and d > 1e-6 then dpiX, dpiY = d, d end
   end
-  if not dpi or dpi < 1e-6 then dpi = 1 end
-  return ww, wh, pw, ph, dpi
+  if dpiX < 1e-6 then dpiX = 1 end
+  if dpiY < 1e-6 then dpiY = 1 end
+  return ww, wh, pw, ph, dpiX, dpiY
 end
 
 function Renderer:init()
@@ -57,25 +88,63 @@ function Renderer:init()
   -- the projected ground in endFrame; never touched while tilt is off.
   self.uprightCanvas = nil
   self.uprightActive = false
+  -- a render pipeline's finished world image, already at window resolution
+  -- (see src/render/Pipelines.lua).  nil is "no pipeline rendered this
+  -- frame", which is every vanilla frame.
+  self.worldOverride = nil
+end
+
+-- Hand endFrame a pipeline's world image to composite instead of the world
+-- canvas.  Cleared every frame, so a pipeline that declines one frame falls
+-- straight back to the 2D path rather than showing a stale image.
+function Renderer:setWorldOverride(canvas)
+  -- Defensive: a pipeline that hands back a non-canvas (forgotten return, a
+  -- truthy sentinel) must not reach the worldOverride blit in endFrame, where
+  -- love.graphics.draw on it would crash the frame.  Reject it and fall back
+  -- to the 2D path rather than trust it.
+  if canvas ~= nil and not isCanvas(canvas) then canvas = nil end
+  self.worldOverride = canvas
 end
 
 -- Integer framebuffer pixels per GB pixel that fit the window.  Zoom /
 -- GBCFX / callers treat this as the crisp scale; endFrame converts to LOVE
--- units via / dpi when drawing.
+-- units via / dpiX and / dpiY when drawing.
 function Renderer:fitScale()
   local _, _, pw, ph = displayMetrics()
   return math.max(1, math.floor(math.min(pw / self.WIDTH, ph / self.HEIGHT)))
 end
 
--- world-pass canvas size in world pixels: enough to fill the window at s'.
--- In tilt mode the canvas grows (both dimensions, by Tilt.viewGrowth) so
--- the projected ground plane still covers the whole window with no
--- background peeking at the receded top/bottom corners; flat mode returns
--- exactly today's size (growth factor is 1 when tilt is inactive).
+-- LOVE-unit draw scales endFrame uses for the UI blit: integer framebuffer
+-- scale (fitScale) divided by each axis's unit→pixel factor, so a GB pixel
+-- lands on fitScale() whole PHYSICAL pixels on both axes once LOVE applies
+-- its projection (fitScale() == drawScaleX() * dpiX == drawScaleY() * dpiY).
+-- Exposed for #208's regression (square pixels when dpiX ≠ dpiY).
+function Renderer:drawScaleX()
+  local _, _, _, _, dpiX = displayMetrics()
+  return self:fitScale() / dpiX
+end
+
+function Renderer:drawScaleY()
+  local _, _, _, _, _, dpiY = displayMetrics()
+  return self:fitScale() / dpiY
+end
+
+-- Back-compat alias: uniform surfaces have drawScaleX == drawScaleY.
+function Renderer:drawScale()
+  return self:drawScaleX()
+end
+
+-- world-pass canvas size in world pixels: enough to fill the drawable at s'.
+-- Sized from framebuffer pixels (not unit dims) so anisotropic dpiX/dpiY
+-- cannot over/under-cover the window.  In tilt mode the canvas grows (both
+-- dimensions, by Tilt.viewGrowth) so the projected ground plane still covers
+-- the whole window with no background peeking at the receded top/bottom
+-- corners; flat mode returns exactly today's size (growth factor is 1 when
+-- tilt is inactive).
 function Renderer:worldViewSize()
-  local ww, wh, _, _, dpi = displayMetrics()
-  local s = Zoom.scale(self:fitScale()) / dpi
-  local vw, vh = Zoom.fillViewSize(s, ww, wh)
+  local _, _, pw, ph = displayMetrics()
+  local sp = Zoom.scale(self:fitScale())
+  local vw, vh = math.ceil(pw / sp), math.ceil(ph / sp)
   -- Even sizes keep Camera:follow on integer pixels (viewW/2 is integral),
   -- so unfloored FX/sprite math cannot phase-shimmer against the tile layer.
   if vw % 2 ~= 0 then vw = vw + 1 end
@@ -91,6 +160,7 @@ end
 function Renderer:beginFrame(transparent)
   self.worldActive = false
   self.uprightActive = false
+  self.worldOverride = nil
   -- warp-fade overlay from Transition (issue #121); cleared each frame so
   -- a popped transition cannot leave a sticky black veil
   self.worldFadeAlpha = nil
@@ -112,21 +182,24 @@ end
 -- Black 8x8 (scaled) blocks cascading outward from the classic GB letterbox
 -- into the surrounding window, matching BattleTransition wipe progress.
 -- Tiles that sit entirely inside the 160x144 square are left to the OG wipe.
-function Renderer:drawBattleCascade(prog, ww, wh, ox, oy, vpw, vph, S)
+-- Sx/Sy are LOVE-unit scales (Sy defaults to Sx on uniform surfaces).
+function Renderer:drawBattleCascade(prog, ww, wh, ox, oy, vpw, vph, Sx, Sy)
   if not prog or prog <= 0 then return end
-  local TILE = 8 * S
-  if TILE < 1 then TILE = 1 end
-  local cols = math.ceil(ww / TILE)
-  local rows = math.ceil(wh / TILE)
+  Sy = Sy or Sx
+  local TILE_W, TILE_H = 8 * Sx, 8 * Sy
+  if TILE_W < 1 then TILE_W = 1 end
+  if TILE_H < 1 then TILE_H = 1 end
+  local cols = math.ceil(ww / TILE_W)
+  local rows = math.ceil(wh / TILE_H)
   local cx, cy = ox + vpw / 2, oy + vph / 2
   local order = {}
   for row = 0, rows - 1 do
     for col = 0, cols - 1 do
-      local x, y = col * TILE, row * TILE
+      local x, y = col * TILE_W, row * TILE_H
       -- any tile with area outside the letterbox participates
-      if x < ox or y < oy or x + TILE > ox + vpw or y + TILE > oy + vph then
-        local dist = math.max(math.abs(x + TILE / 2 - cx),
-                              math.abs(y + TILE / 2 - cy))
+      if x < ox or y < oy or x + TILE_W > ox + vpw or y + TILE_H > oy + vph then
+        local dist = math.max(math.abs(x + TILE_W / 2 - cx),
+                              math.abs(y + TILE_H / 2 - cy))
         order[#order + 1] = { x, y, dist }
       end
     end
@@ -143,7 +216,7 @@ function Renderer:drawBattleCascade(prog, ww, wh, ox, oy, vpw, vph, S)
   love.graphics.setScissor(0, 0, ww, wh)
   for i = 1, n do
     local t = order[i]
-    love.graphics.rectangle("fill", t[1], t[2], TILE, TILE)
+    love.graphics.rectangle("fill", t[1], t[2], TILE_W, TILE_H)
   end
   love.graphics.setScissor()
   love.graphics.setColor(1, 1, 1, 1)
@@ -266,10 +339,11 @@ end
 -- into (nil = default framebuffer; presentCanvas when CRT is on).
 -- Returns true on success; false (no shader/mesh) tells endFrame to fall
 -- back to the flat blit unchanged.
-function Renderer:drawTiltedWorld(zoneList, s, wox, woy, target)
+function Renderer:drawTiltedWorld(zoneList, sx, sy, wox, woy, target)
   local shader = self:tiltShader()
   local mesh = self:tiltMesh()
   if not (shader and mesh) then return false end
+  sy = sy or sx
   local wvw = self.worldCanvas:getWidth()
   local wvh = self.worldCanvas:getHeight()
 
@@ -318,7 +392,7 @@ function Renderer:drawTiltedWorld(zoneList, s, wox, woy, target)
   mesh:setVertices(Tilt.meshCorners(wvw, wvh))
   love.graphics.push()
   love.graphics.translate(wox, woy)
-  love.graphics.scale(s, s)
+  love.graphics.scale(sx, sy)
   love.graphics.setColor(1, 1, 1, 1)
   love.graphics.setShader(shader)
   love.graphics.draw(mesh)
@@ -360,14 +434,15 @@ end
 -- presented through the GBC FX shader as a final pass.
 function Renderer:endFrame(zones, worldZones)
   love.graphics.setCanvas()
-  local ww, wh, pw, ph, dpi = displayMetrics()
-  -- Sp = integer framebuffer pixels per GB pixel; S = LOVE-unit draw scale.
+  local ww, wh, pw, ph, dpiX, dpiY = displayMetrics()
+  -- Sp = integer framebuffer pixels per GB pixel;
+  -- Sx/Sy = LOVE-unit draw scales (may differ when dpiX ≠ dpiY).
   local Sp = self:fitScale()
-  local S = Sp / dpi
-  local vpw, vph = self.WIDTH * S, self.HEIGHT * S
+  local Sx, Sy = Sp / dpiX, Sp / dpiY
+  local vpw, vph = self.WIDTH * Sx, self.HEIGHT * Sy
   -- Snap the letterbox origin to a framebuffer pixel, then convert to units.
-  local ox = math.floor((pw - self.WIDTH * Sp) / 2) / dpi
-  local oy = math.floor((ph - self.HEIGHT * Sp) / 2) / dpi
+  local ox = math.floor((pw - self.WIDTH * Sp) / 2) / dpiX
+  local oy = math.floor((ph - self.HEIGHT * Sp) / 2) / dpiY
   local GBCFX = require("src.render.GBCFX")
   -- Forced mono/Classic modes still need a whole-screen zone when a state
   -- exposes no SGB packets (raw DMG canvas), so sendColors can remap.
@@ -380,7 +455,11 @@ function Renderer:endFrame(zones, worldZones)
   zones = withTrueColor(zones, "ui")
   worldZones = withTrueColor(worldZones, "world")
 
-  local needPresent = GBCFX.active()
+  -- A post-process pipeline needs the whole composite in a canvas for the
+  -- same reason GBC FX does, so either one alone is enough to take the
+  -- present path; with neither, the frame draws straight to the screen
+  -- exactly as it always did.
+  local needPresent = GBCFX.active() or Pipelines.wantsPresent()
   local present = nil
   if needPresent then
     if not self.presentCanvas or self.presentCanvas:getWidth() ~= ww
@@ -408,14 +487,15 @@ function Renderer:endFrame(zones, worldZones)
   love.graphics.rectangle("fill", 0, 0, ww, wh)
   love.graphics.setColor(1, 1, 1, 1)
 
-  -- blit `canvas` at `scale` (LOVE units) into origin (bx, by), scissored to
-  -- the (boxX, boxY, boxW, boxH) screen rect.  zoneScale converts zone
-  -- coords (canvas-space) into screen units.
-  local function blit(canvas, scale, zoneList, zoneScale, bx, by, boxX, boxY, boxW, boxH)
+  -- blit `canvas` at (sx, sy) LOVE-unit scales into origin (bx, by),
+  -- scissored to the (boxX, boxY, boxW, boxH) screen rect.  zoneSx/zoneSy
+  -- convert zone coords (canvas-space) into screen units.
+  local function blit(canvas, sx, sy, zoneList, zoneSx, zoneSy,
+                      bx, by, boxX, boxY, boxW, boxH)
     local shader = zoneList and zoneList[1] and PaletteFX.shader() or nil
     if not shader then
       love.graphics.setScissor(boxX, boxY, boxW, boxH)
-      love.graphics.draw(canvas, bx, by, 0, scale, scale)
+      love.graphics.draw(canvas, bx, by, 0, sx, sy)
       love.graphics.setScissor()
       return
     end
@@ -431,23 +511,43 @@ function Renderer:endFrame(zones, worldZones)
         love.graphics.setShader(not plain and shader or nil)
       end
       if not plain then PaletteFX.sendColors(shader, z.colors) end
-      if scissorClamped(bx + z.x * zoneScale, by + z.y * zoneScale,
-                        z.w * zoneScale, z.h * zoneScale,
+      if scissorClamped(bx + z.x * zoneSx, by + z.y * zoneSy,
+                        z.w * zoneSx, z.h * zoneSy,
                         boxX, boxY, boxW, boxH) then
-        love.graphics.draw(canvas, bx, by, 0, scale, scale)
+        love.graphics.draw(canvas, bx, by, 0, sx, sy)
       end
     end
     love.graphics.setScissor()
     love.graphics.setShader()
   end
 
-  if self.worldActive then
+  if self.worldOverride then
+    -- A render pipeline already produced the whole world -- terrain,
+    -- characters and its own FX overlay -- as one window-resolution image,
+    -- so it composites with a straight 1:1 blit and the world canvas is
+    -- skipped entirely (nothing drew into it).  The UI blit below still
+    -- runs, so dialogs, menus and the HUD sit on top as usual.
+    love.graphics.setColor(1, 1, 1, 1)
+    love.graphics.setScissor(0, 0, ww, wh)
+    love.graphics.draw(self.worldOverride, 0, 0, 0, 1 / dpiX, 1 / dpiY)
+    love.graphics.setScissor()
+    -- the screen-space overlays the flat path draws over its composite
+    local fade = self.worldFadeAlpha
+    if fade and fade > 0 then
+      love.graphics.setColor(0, 0, 0, fade)
+      love.graphics.rectangle("fill", 0, 0, ww, wh)
+      love.graphics.setColor(1, 1, 1, 1)
+    end
+    if self.battleCascadeProg then
+      self:drawBattleCascade(self.battleCascadeProg, ww, wh, ox, oy, vpw, vph, Sx, Sy)
+    end
+  elseif self.worldActive then
     local sp = Zoom.scale(Sp)
-    local s = sp / dpi
+    local sx, sy = sp / dpiX, sp / dpiY
     local wvw = self.worldCanvas:getWidth()
     local wvh = self.worldCanvas:getHeight()
-    local wox = math.floor((pw - wvw * sp) / 2) / dpi
-    local woy = math.floor((ph - wvh * sp) / 2) / dpi
+    local wox = math.floor((pw - wvw * sp) / 2) / dpiX
+    local woy = math.floor((ph - wvh * sp) / 2) / dpiY
     -- Tilt mode projects the ground world pass through the perspective mesh
     -- (SGB zones baked in beforehand -- see drawTiltedWorld -- so no zone
     -- scissoring here).  drawTiltedWorld returns false when tilt is off or
@@ -455,12 +555,12 @@ function Renderer:endFrame(zones, worldZones)
     -- falls through to the flat blit, keeping the flat frame byte-for-byte
     -- identical to today.
     local projected =
-      Tilt.active() and self:drawTiltedWorld(worldZones or zones, s, wox, woy, present)
+      Tilt.active() and self:drawTiltedWorld(worldZones or zones, sx, sy, wox, woy, present)
     if not projected then
       if worldZones then
-        blit(self.worldCanvas, s, worldZones, s, wox, woy, 0, 0, ww, wh)
+        blit(self.worldCanvas, sx, sy, worldZones, sx, sy, wox, woy, 0, 0, ww, wh)
       else
-        blit(self.worldCanvas, s, zones, S, wox, woy, 0, 0, ww, wh)
+        blit(self.worldCanvas, sx, sy, zones, Sx, Sy, wox, woy, 0, 0, ww, wh)
       end
       -- OBP-baked overworld sprites replay on top of the zone pass (GBC
       -- mode per-object coloring; see PaletteFX.markSpriteRedraw).  Grass
@@ -481,11 +581,11 @@ function Renderer:endFrame(zones, worldZones)
           end
           if wanted then PaletteFX.sendColors(wanted, r.colors) end
           if r.quad then
-            love.graphics.draw(r.image, r.quad, wox + r.x * s, woy + r.y * s,
-                               0, s * r.sx, s)
+            love.graphics.draw(r.image, r.quad, wox + r.x * sx, woy + r.y * sy,
+                               0, sx * r.sx, sy)
           else
-            love.graphics.draw(r.image, wox + r.x * s, woy + r.y * s,
-                               0, s * r.sx, s)
+            love.graphics.draw(r.image, wox + r.x * sx, woy + r.y * sy,
+                               0, sx * r.sx, sy)
           end
         end
         if activeShader then love.graphics.setShader() end
@@ -502,7 +602,7 @@ function Renderer:endFrame(zones, worldZones)
       local M = self.UPRIGHT_MARGIN
       love.graphics.setColor(1, 1, 1, 1)
       love.graphics.setScissor(0, 0, ww, wh)
-      love.graphics.draw(self.uprightCanvas, wox - M * s, woy - M * s, 0, s, s)
+      love.graphics.draw(self.uprightCanvas, wox - M * sx, woy - M * sy, 0, sx, sy)
       love.graphics.setScissor()
     end
     -- Screen-space warp fade (Transition) over the full world composite so
@@ -518,19 +618,34 @@ function Renderer:endFrame(zones, worldZones)
     -- Battle transition: cascade black blocks into the area outside the
     -- classic 160x144 wipe square (world still shows through until filled).
     if self.battleCascadeProg then
-      self:drawBattleCascade(self.battleCascadeProg, ww, wh, ox, oy, vpw, vph, S)
+      self:drawBattleCascade(self.battleCascadeProg, ww, wh, ox, oy, vpw, vph, Sx, Sy)
     end
   end
   -- UI stays in the classic centered GB letterbox
-  blit(self.canvas, S, zones, S, ox, oy, ox, oy, vpw, vph)
+  blit(self.canvas, Sx, Sy, zones, Sx, Sy, ox, oy, ox, oy, vpw, vph)
 
   if present then
     love.graphics.setCanvas()
-    -- shader grid/shadow math is in framebuffer pixels
-    GBCFX.present(present, Sp)
+    -- Post-process pipelines run over the finished composite -- world, UI
+    -- and all -- and before GBC FX, so a blur or colour grade is what the
+    -- LCD grid is then drawn over rather than something that smears the
+    -- grid itself.  Each pass hands back a canvas; with none registered
+    -- this returns `present` unchanged and the frame is byte-identical.
+    local composed = Pipelines.present(present,
+      { width = ww, height = wh, scale = Sp, dpi = dpiY, dpiX = dpiX, dpiY = dpiY }) or present
+    if GBCFX.active() then
+      -- shader grid/shadow math is in framebuffer pixels
+      GBCFX.present(composed, Sp)
+    else
+      -- the present canvas only existed for the post-process, so put the
+      -- result on the screen at the same 1:1 unit mapping it was built at
+      love.graphics.setColor(1, 1, 1, 1)
+      love.graphics.draw(composed, 0, 0)
+    end
   end
   self.worldActive = false
   self.uprightActive = false
+  self.worldOverride = nil
   PaletteFX.setPass(nil)
 end
 

src/render/SpriteRenderer.lua

@@ -65,8 +65,12 @@ end
 
 Assets.register(SpriteRenderer.invalidate)
 
+-- exported: a render pipeline's own sprite geometry picks frames by the
+-- same tables, so a 3D pose can never drift from the 2D one
 local STAND = { down = 0, up = 1, left = 2, right = 2 }
 local WALK = { down = 3, up = 4, left = 5, right = 5 }
+SpriteRenderer.STAND = STAND
+SpriteRenderer.WALK = WALK
 
 -- seed: any stable per-instance value (e.g. an NPC's `id`) used to resolve
 -- RED++'s per-instance "random" OBP sentinel (PaletteFX.spriteObp)
@@ -83,6 +87,32 @@ function SpriteRenderer.new(spriteDef, seed)
   return self
 end
 
+-- The image this sprite would draw from right now: the plain sheet, or the
+-- OBP-recolored bake of it.  Exposed so a render pipeline can texture its
+-- own geometry from the very same image -- the geometry carries sheet pixel
+-- coordinates rather than baked colors, so sharing this one resolver is
+-- what makes palette modes and sprite-replacing mods apply to 2D and 3D
+-- alike.
+--
+-- Deliberately free of draw's bookkeeping: markTrueColor and
+-- markSpriteRedraw exist to patch up the screen-space zone shader, and a
+-- pipeline that renders into its own canvas never runs through it.  For the
+-- same reason the OG-RED bake is returned unconditionally here rather than
+-- only during a redraw pass -- there is no later pass to restore it.
+function SpriteRenderer:resolveImage()
+  if self.def.trueColor then return self.image end
+  if PaletteFX.usesGbcPack() then
+    local colors, group = PaletteFX.spriteObp(self.def, self.seed)
+    if colors then return getObpImage(self.def.image, colors, group) end
+  elseif PaletteFX.usesSpriteObp() then
+    -- OG boot-ROM OBJ palette: green on Red, pink on Blue (PaletteFX.ogObj
+    -- returns colors + a version-distinct cache group so the two never
+    -- collide in obpCache) -- see issue #155
+    return getObpImage(self.def.image, PaletteFX.ogObj())
+  end
+  return self.image
+end
+
 -- facing: down/up/left/right; walkPhase: 0 stand, 1 walk; flip: alternate
 -- steps mirror the walk frame for up/down (GB uses OAM flip for this).
 local function blitFrame(image, quad, x, y, flip, redraw)
@@ -114,11 +144,13 @@ function SpriteRenderer:draw(px, py, camX, camY, facing, walkPhase, stepFlip)
       image = getObpImage(self.def.image, colors, group)
     end
   elseif PaletteFX.usesSpriteObp() and PaletteFX.spriteRedrawPassActive() then
-    -- OG RED (GBC boot-ROM look): every OBJ wears the one global green
-    -- object palette.  The red BG zone shader still runs over the world
-    -- canvas, so the baked sprite is queued for a post-zone redraw
-    -- (PaletteFX.markSpriteRedraw) that restores its green pixels on top.
-    image = getObpImage(self.def.image, PaletteFX.GBC_OBJ, "gbcobj")
+    -- OG RED (GBC boot-ROM look): every OBJ wears the one global object
+    -- palette -- green over Red's red background, pink over Blue's blue
+    -- background (PaletteFX.ogObj, #155).  The BG zone shader still runs over
+    -- the world canvas, so the baked sprite is queued for a post-zone redraw
+    -- (PaletteFX.markSpriteRedraw) that restores its object-colored pixels on
+    -- top.
+    image = getObpImage(self.def.image, PaletteFX.ogObj())
     redraw = true
   end
   -- single-frame sprites (item balls, fossils...) have one fixed pose;

src/render/TextBox.lua

@@ -50,6 +50,7 @@ function TextBox.new(game, text, onDone, opts)
   self.charIndex = 0
   self.shown = {} -- visible lines (max 2), each a list of glyph codes
   self.waiting = false
+  self.contAdvance = false
   self.done = false
   self.blink = 0
   self:beginLine()
@@ -65,7 +66,11 @@ TextBox.TOKENS = {
   PLAYER = function(game) return game.save.player.name or "RED" end,
   RIVAL = function(game) return game.save.player.rival or "BLUE" end,
   RAM = function(game, arg)
-    return arg == "wStringBuffer" and game.stringBuffer or nil
+    if arg == "wStringBuffer" then return game.stringBuffer end
+    if arg == "wBoxNumString" then return game.boxNumString end
+    -- SendNewMonToBox / _SentToBoxText reads the deposited nick here
+    if arg == "wBoxMonNicks" then return game.boxMonNicks end
+    return nil
   end,
 }
 
@@ -83,31 +88,55 @@ end
 
 -- Split marked-up text into pages of lines.  \v-scrolled lines become
 -- additional lines on the same page (the box scrolls them).
+-- pages.contBefore[p][i] is true when line i was preceded by \v (cont):
+-- pokered ContText waits for A/B + ▼ before scrolling that line in.
 function TextBox.paginate(text, maxCols)
   maxCols = maxCols or (Theme.textBox and Theme.textBox.maxCols) or MAX_COLS
   local pages = {}
+  local contBefore = {}
+  local function pushLine(lines, conts, line, wait)
+    while #line > maxCols do
+      local cut = maxCols
+      for i = maxCols, 1, -1 do
+        if line:sub(i, i) == " " then cut = i break end
+      end
+      table.insert(lines, line:sub(1, cut))
+      table.insert(conts, wait)
+      wait = false
+      line = line:sub(cut + 1)
+    end
+    table.insert(lines, line)
+    table.insert(conts, wait)
+  end
   for pageText in (text .. "\f"):gmatch("(.-)\f") do
     if pageText ~= "" then
-      local lines = {}
-      for chunk in (pageText .. "\n"):gmatch("(.-)[\n\v]") do
-        local line = chunk
-        -- wrap long lines defensively (the source rarely needs it)
-        while #line > maxCols do
-          local cut = maxCols
-          for i = maxCols, 1, -1 do
-            if line:sub(i, i) == " " then cut = i break end
-          end
-          table.insert(lines, line:sub(1, cut))
-          line = line:sub(cut + 1)
+      local lines, conts = {}, {}
+      local pos, waitNext = 1, false
+      while true do
+        local npos = pageText:find("[\n\v]", pos)
+        if not npos then
+          pushLine(lines, conts, pageText:sub(pos), waitNext)
+          break
         end
-        table.insert(lines, line)
+        pushLine(lines, conts, pageText:sub(pos, npos - 1), waitNext)
+        waitNext = pageText:sub(npos, npos) == "\v"
+        pos = npos + 1
+      end
+      if lines[#lines] == "" then
+        table.remove(lines)
+        table.remove(conts)
+      end
+      if #lines > 0 then
+        table.insert(pages, lines)
+        table.insert(contBefore, conts)
       end
-      -- drop trailing empty line from the final gmatch round
-      if lines[#lines] == "" then table.remove(lines) end
-      if #lines > 0 then table.insert(pages, lines) end
     end
   end
-  if #pages == 0 then pages = { { "" } } end
+  if #pages == 0 then
+    pages = { { "" } }
+    contBefore = { { false } }
+  end
+  pages.contBefore = contBefore
   return pages
 end
 
@@ -179,10 +208,17 @@ function TextBox:update(dt)
     if input:wasPressed("a") or input:wasPressed("b") then
       require("src.core.Sound").play(self.game.data, "Press_AB")
       self.waiting = false
-      self.shown = {}
-      self.pageIndex = self.pageIndex + 1
-      self.lineIndex = 1
-      self:beginLine()
+      if self.contAdvance then
+        -- ContText / ManualTextScroll: keep the box, scroll one line
+        self.contAdvance = false
+        self.lineIndex = self.lineIndex + 1
+        self:beginLine()
+      else
+        self.shown = {}
+        self.pageIndex = self.pageIndex + 1
+        self.lineIndex = 1
+        self:beginLine()
+      end
     end
     return
   end
@@ -203,10 +239,19 @@ function TextBox:update(dt)
       -- line finished
       local page = self.pages[self.pageIndex]
       if self.lineIndex < #page then
-        self.lineIndex = self.lineIndex + 1
-        self:beginLine()
+        local nextIdx = self.lineIndex + 1
+        local conts = self.pages.contBefore and self.pages.contBefore[self.pageIndex]
+        if conts and conts[nextIdx] then
+          -- pokered <CONT>: ▼ + WaitForTextScrollButtonPress before scroll
+          self.waiting = true
+          self.contAdvance = true
+        else
+          self.lineIndex = nextIdx
+          self:beginLine()
+        end
       elseif self.pageIndex < #self.pages then
         self.waiting = true
+        self.contAdvance = false
       else
         self.done = true
       end

src/render/TileRenderer.lua

@@ -179,6 +179,11 @@ local function recolorSample(r, g, b, a, colors)
   return col[1] / 255, col[2] / 255, col[3] / 255, a
 end
 
+-- exported: a render pipeline bakes a map's palette into its own texture
+-- atlas the same way, and has to land on the identical colors as the 2D
+-- tiles it is standing in for
+TileRenderer.recolorSample = recolorSample
+
 -- the 8 shifted variants of one tile (built once per sheet + tile id [+
 -- gbcKey, when `colors` recolors it for RED++ -- see buildAnim])
 local shiftVariants = {}

src/save_convert/GenSave.lua

@@ -0,0 +1,813 @@
+-- Vanilla Gen1 (Red/Blue, international) raw SRAM save (32768 bytes) <->
+-- this project's save.lua shape (src/core/SaveData.lua / SaveData.newGame).
+--
+-- Pure Lua, no love.* dependency -- runs under plain luajit for the CLI
+-- (tools/save_convert/convert.lua) and headless tests alike.
+--
+-- Every offset below was derived mechanically from the authoritative
+-- source (../pokered/ram/wram.asm, ram/sram.asm, macros/ram.asm) and
+-- cross-checked against three independently well-known Gen1 save
+-- addresses: money @ 0x25F3, badges @ 0x2602, party data @ 0x2F2C --
+-- all three fall out exactly right from the single sPlayerName anchor
+-- below, strong triangulated confirmation the whole chain (SRAM bank 1
+-- layout, wMainData field order, party_struct/box_struct sizes) is right.
+--
+-- SRAM layout (32768 bytes = 4 banks x 8192): bank 0 is sprite buffers +
+-- Hall of Fame (not modeled -- see "explicitly out of scope" in the
+-- save-converter plan); bank 1 is "Save Data" (sPlayerName through
+-- sMainDataCheckSum); banks 2/3 are the 12 PC boxes (6 each) + checksums.
+--
+-- Fields with no equivalent in save.lua (current sprite/animation state,
+-- connection-header cache, Day Care, Safari Zone, HOF roster) are
+-- intentionally not modeled: on export, encode() starts from the
+-- ORIGINAL imported bytes as a template when available (GenSave.decode
+-- stashes them) so that scratch state round-trips untouched instead of
+-- being invented; with no template (a save that originated in this
+-- project) those bytes stay zero-filled, which is safe because the real
+-- game regenerates all of it from wCurMap on the next map load anyway.
+
+local bit = require("bit")
+
+local GenSave = {}
+
+-- ------------------------------------------------------------------
+-- Absolute byte offsets (0-based, matching a raw 32768-byte .sav file)
+-- ------------------------------------------------------------------
+
+local NAME_LENGTH = 11
+local PARTY_LENGTH = 6
+local MONS_PER_BOX = 20
+local NUM_BADGES = 8
+local BOX_STRUCT_SIZE = 33   -- Species,HP,Level,Status,Type1,Type2,CatchRate,
+                              -- Moves x4,OTID,Exp x3,HPExp,AtkExp,DefExp,
+                              -- SpdExp,SpcExp,DVs,PP x4 (macros/ram.asm box_struct)
+local PARTY_STRUCT_SIZE = 44 -- box_struct + Level + Stats x5 (party_struct)
+local BOX_REGION_SIZE = 1 + (MONS_PER_BOX + 1) + MONS_PER_BOX * BOX_STRUCT_SIZE
+                       + MONS_PER_BOX * NAME_LENGTH + MONS_PER_BOX * NAME_LENGTH -- 1122
+
+local O = {}
+O.playerName = 9624                                    -- sPlayerName (11B)  = 0x2598
+O.mainData = O.playerName + NAME_LENGTH                 -- sMainData (wMainDataStart mirror)
+O.pokedexOwned = O.mainData + 0                         -- 19B (flag_array 151)
+O.pokedexSeen = O.mainData + 19                         -- 19B
+O.numBagItems = O.mainData + 38                         -- 1B
+O.bagItems = O.mainData + 39                             -- 41B (20 x (id,qty) + $FF term)
+O.money = O.mainData + 80                                -- 3B BCD             = 0x25F3
+O.rivalName = O.mainData + 83                            -- 11B
+O.options = O.mainData + 94                              -- 1B
+O.badges = O.mainData + 95                                -- 1B                = 0x2602
+O.playerId = O.mainData + 98                              -- 2B (big-endian)
+O.curMap = O.mainData + 103                               -- 1B
+O.yCoord = O.mainData + 106                               -- 1B
+O.xCoord = O.mainData + 107                               -- 1B
+O.lastMap = O.mainData + 110                              -- 1B
+O.numPcItems = O.mainData + 579                           -- 1B
+O.pcItems = O.mainData + 580                              -- 101B (50 x (id,qty) + $FF term)
+O.currentBoxNum = O.mainData + 681                        -- 1B (bits 0-6: box 0-11, bit 7: unused here)
+O.coins = O.mainData + 685                                -- 2B BCD
+O.eventFlags = O.mainData + 1104                          -- 320B (flag_array NUM_EVENTS = 2560 bits)
+-- Play time (wPlayTimeHours/Maxed/Minutes/Seconds/Frames) lives INSIDE the
+-- sMainData window (wMainDataStart..wMainDataEnd is copied verbatim into
+-- SRAM), 1866 bytes past wMainDataStart -- reached from the checksum-verified
+-- wEventFlags anchor: 320 (event flag_array) + 293 (the wGrassRate/enemy-party
+-- battle UNION) + 66 + 66 (wEnemyMonOT/Nicks, 6 x NAME_LENGTH each; the
+-- rgbds FOR n,1,PARTY_LENGTH+1 loop is end-exclusive => 6 mons, not 7) + 2
+-- (wTrainerHeaderPtr) + 6 (ds) + 1 (wOpponentAfterWrongAnswer) + 1
+-- (wCurMapScript) + 7 (ds) = 762. Confirmed on the real fixture: those five
+-- bytes read 201h 30m 07s, a sane completed-save clock.
+O.playTimeHours = O.mainData + 1866                       -- 1B
+O.playTimeMaxed = O.mainData + 1867                       -- 1B (set once past 255h)
+O.playTimeMinutes = O.mainData + 1868                     -- 1B (0-59)
+O.playTimeSeconds = O.mainData + 1869                     -- 1B (0-59)
+O.playTimeFrames = O.mainData + 1870                      -- 1B (0-59, 1/60s ticks)
+O.mainDataSize = 1929                                     -- wMainDataEnd - wMainDataStart
+
+O.spriteData = O.mainData + O.mainDataSize
+O.spriteDataSize = 512                                    -- 2 x 16 sprites x 16B
+
+O.partyData = O.spriteData + O.spriteDataSize             -- = 0x2F2C
+O.partyCount = O.partyData
+O.partySpecies = O.partyData + 1                          -- 7B (PARTY_LENGTH+1)
+O.partyMons = O.partyData + 8                             -- 6 x 44B
+O.partyMonOT = O.partyData + 8 + PARTY_LENGTH * PARTY_STRUCT_SIZE
+O.partyMonNicks = O.partyMonOT + PARTY_LENGTH * NAME_LENGTH
+O.partyDataSize = 1 + (PARTY_LENGTH + 1) + PARTY_LENGTH * PARTY_STRUCT_SIZE
+                 + PARTY_LENGTH * NAME_LENGTH + PARTY_LENGTH * NAME_LENGTH -- 404
+
+O.curBoxData = O.partyData + O.partyDataSize
+O.boxCount = O.curBoxData
+O.boxSpecies = O.curBoxData + 1                           -- 21B
+O.boxMons = O.curBoxData + 22                             -- 20 x 33B
+O.boxMonOT = O.curBoxData + 22 + MONS_PER_BOX * BOX_STRUCT_SIZE
+O.boxMonNicks = O.boxMonOT + MONS_PER_BOX * NAME_LENGTH
+
+O.checksumStart = O.playerName
+O.checksumEnd = O.curBoxData + BOX_REGION_SIZE + 1        -- + sTileAnimations (1B)
+O.mainChecksum = O.checksumEnd                            -- 1B
+
+O.box1 = 16384                                             -- bank 2 start
+O.boxBank2Checksum = O.box1 + 6 * BOX_REGION_SIZE
+O.boxBank2IndividualChecksums = O.boxBank2Checksum + 1     -- 6B
+O.box7 = 24576                                              -- bank 3 start
+O.boxBank3Checksum = O.box7 + 6 * BOX_REGION_SIZE
+O.boxBank3IndividualChecksums = O.boxBank3Checksum + 1      -- 6B
+
+GenSave.OFFSETS = O
+GenSave.BOX_REGION_SIZE = BOX_REGION_SIZE
+GenSave.SAVE_SIZE = 32768
+
+-- ------------------------------------------------------------------
+-- Byte-level helpers.  `bytes` is a 32768-byte Lua string (1-based
+-- indexing, so byte offset N is string position N+1); `buf` for writing
+-- is a 32768-entry array of 1-char strings, joined at the end.
+-- ------------------------------------------------------------------
+
+local function u8(bytes, off) return bytes:byte(off + 1) end
+local function u16be(bytes, off) return u8(bytes, off) * 256 + u8(bytes, off + 1) end
+local function u24be(bytes, off)
+  return u8(bytes, off) * 65536 + u8(bytes, off + 1) * 256 + u8(bytes, off + 2)
+end
+
+local function setByte(buf, off, v)
+  buf[off + 1] = string.char(bit.band(v, 0xFF))
+end
+local function setU16be(buf, off, v)
+  setByte(buf, off, bit.band(bit.rshift(v, 8), 0xFF))
+  setByte(buf, off + 1, bit.band(v, 0xFF))
+end
+local function setU24be(buf, off, v)
+  setByte(buf, off, bit.band(bit.rshift(v, 16), 0xFF))
+  setByte(buf, off + 1, bit.band(bit.rshift(v, 8), 0xFF))
+  setByte(buf, off + 2, bit.band(v, 0xFF))
+end
+local function setBcd(buf, off, nbytes, v)
+  for i = nbytes - 1, 0, -1 do
+    local d = v % 100
+    v = math.floor(v / 100)
+    setByte(buf, off + i, math.floor(d / 10) * 16 + (d % 10))
+  end
+end
+local function readBcd(bytes, off, nbytes)
+  local n = 0
+  for i = 0, nbytes - 1 do
+    local b = u8(bytes, off + i)
+    n = n * 100 + math.floor(b / 16) * 10 + (b % 16)
+  end
+  return n
+end
+
+-- CalcCheckSum (engine/menus/save.asm): complement of the additive sum
+local function checksum(bytes, from, to)
+  local sum = 0
+  for i = from, to - 1 do sum = bit.band(sum + u8(bytes, i), 0xFF) end
+  return bit.band(bit.bnot(sum), 0xFF)
+end
+
+-- flag_array packs LSB-first within each byte (bit 0 of byte 0 = index 0).
+-- This is pokered's runtime FlagAction convention (home/predef macros): it
+-- takes flag number N, addresses byte N/8, and builds the mask by rotating
+-- a 1 left N%8 times starting from bit 0 -- i.e. flag N%8==0 is the LSB.
+-- Same convention PKHeX uses for Gen1 dex/event flags (FlagUtil.GetFlag:
+-- data[ofs + bit/8] >> (bit%8) & 1). Cross-validated against the real save:
+-- ZAPDOS (dex 145) is physically boxed there, so its owned/seen flag must be
+-- set; only the LSB reading returns it set (MSB-first spuriously drops
+-- exactly that one bit at the byte-18 boundary), yielding a complete 151/151
+-- dex. The prior MSB-first code round-tripped self-consistently but decoded
+-- every flag_array (pokedex AND event flags) to the wrong bit.
+local function bitGet(bytes, base, index)
+  local byteOff = base + math.floor(index / 8)
+  local b = u8(bytes, byteOff)
+  return bit.band(bit.rshift(b, index % 8), 1) == 1
+end
+
+-- Set one bit directly in `buf` (0-based flag index into a flag_array
+-- starting at `base`), preserving every other bit already in that byte --
+-- template bytes (see encode()'s header note) survive for bits this pass
+-- never explicitly touches, e.g. event-flag bits with no known name
+-- sharing a byte with ones that do.
+local function bitSet(buf, base, index, value)
+  local byteOff = base + math.floor(index / 8)
+  local bitIdx = index % 8
+  local cur = buf[byteOff + 1] and buf[byteOff + 1]:byte() or 0
+  local mask = bit.lshift(1, bitIdx)
+  setByte(buf, byteOff, value and bit.bor(cur, mask) or bit.band(cur, bit.bnot(mask)))
+end
+
+-- ------------------------------------------------------------------
+-- Text (fixed-length name fields: charmap-encoded, "@" ($50) terminated,
+-- $50-padded after the terminator). setCharmap(cm) must be called once
+-- before decode/encode (src/save_convert/data/charmap.lua's shape).
+-- ------------------------------------------------------------------
+
+local charmap
+
+function GenSave.setCharmap(cm) charmap = cm end
+
+local function decodeName(bytes, off, len)
+  local out = {}
+  for i = 0, len - 1 do
+    local b = u8(bytes, off + i)
+    if b == 0x50 then break end
+    out[#out + 1] = charmap.byByte[b] or "?"
+  end
+  return table.concat(out)
+end
+
+local function encodeName(buf, off, len, text)
+  local i, pos = 0, 1
+  while i < len - 1 and pos <= #text do
+    -- a bracketed control token (e.g. "<DOT>", from decodeName reading a
+    -- byte with no plain-glyph mapping) is ONE game character despite
+    -- being several text bytes here; match it as a whole unit first, or
+    -- it would fall through to per-byte matching and turn into "?" x5
+    local bracket = text:match("^(<[^<>]*>)", pos)
+    local ch, clen
+    if bracket and charmap.byToken[bracket] then
+      ch, clen = bracket, #bracket
+    else
+      local b0 = text:byte(pos)
+      clen = (b0 < 0x80 and 1) or (b0 < 0xE0 and 2) or (b0 < 0xF0 and 3) or 4
+      ch = text:sub(pos, pos + clen - 1)
+    end
+    setByte(buf, off + i, charmap.byToken[ch] or charmap.byToken["?"] or 0x50)
+    i, pos = i + 1, pos + clen
+  end
+  -- Write exactly ONE $50 terminator and then STOP. The bytes after it are
+  -- left untouched: when encoding over a template they stay as the original
+  -- save's post-terminator padding (so an unchanged name round-trips
+  -- byte-identical), and on a templateless export they stay zero-filled. The
+  -- game reads a name only up to the first $50, so whatever follows is inert.
+  if i < len then setByte(buf, off + i, 0x50) end
+end
+
+-- ------------------------------------------------------------------
+-- DV / PP packing (box_struct DVs, PP)
+-- ------------------------------------------------------------------
+
+-- DVs:: dw, packed as byte0=(Attack<<4)|Defense, byte1=(Speed<<4)|Special;
+-- HP DV is derived, not stored, from each stat DV's low bit.
+local function decodeDVs(bytes, off)
+  local b0, b1 = u8(bytes, off), u8(bytes, off + 1)
+  local atk, def = bit.rshift(b0, 4), bit.band(b0, 0xF)
+  local spe, spc = bit.rshift(b1, 4), bit.band(b1, 0xF)
+  local hp = bit.bor(bit.lshift(bit.band(atk, 1), 3), bit.lshift(bit.band(def, 1), 2),
+                     bit.lshift(bit.band(spe, 1), 1), bit.band(spc, 1))
+  return { hp = hp, attack = atk, defense = def, speed = spe, special = spc }
+end
+
+local function encodeDVs(buf, off, dvs)
+  setByte(buf, off, bit.bor(bit.lshift(bit.band(dvs.attack or 0, 0xF), 4), bit.band(dvs.defense or 0, 0xF)))
+  setByte(buf, off + 1, bit.bor(bit.lshift(bit.band(dvs.speed or 0, 0xF), 4), bit.band(dvs.special or 0, 0xF)))
+end
+
+-- PP byte: top 2 bits = PP Up count (0-3), bottom 6 bits = current PP
+local function decodePPByte(b) return bit.band(b, 0x3F), bit.rshift(b, 6) end
+local function encodePPByte(pp, ppUps) return bit.bor(bit.lshift(bit.band(ppUps or 0, 3), 6), bit.band(pp or 0, 0x3F)) end
+
+-- ------------------------------------------------------------------
+-- Crosswalks (built once from `data` = {pokemon=,moves=,items=,maps=})
+-- ------------------------------------------------------------------
+
+-- pokered constants/type_constants.asm PHYSICAL/SPECIAL block; stable,
+-- not worth a dedicated extractor for 15 names.
+local TYPE_BY_INDEX = {
+  [0] = "NORMAL", [1] = "FIGHTING", [2] = "FLYING", [3] = "POISON",
+  [4] = "GROUND", [5] = "ROCK", [6] = "BIRD", [7] = "BUG", [8] = "GHOST",
+  [20] = "FIRE", [21] = "WATER", [22] = "GRASS", [23] = "ELECTRIC",
+  [24] = "PSYCHIC_TYPE", [25] = "ICE", [26] = "DRAGON",
+}
+local TYPE_INDEX = {}
+for i, name in pairs(TYPE_BY_INDEX) do TYPE_INDEX[name] = i end
+
+-- Badge bit order (constants/ram_constants.asm BIT_BOULDERBADGE=0 ..
+-- BIT_EARTHBADGE=7); this project stores badges as truthy
+-- save.inventory[id] entries, not a flag or a separate bitmask
+-- (src/inventory/Badges.lua Badges.list's VANILLA order matches exactly).
+local BADGE_BY_BIT = {
+  [0] = "BOULDERBADGE", [1] = "CASCADEBADGE", [2] = "THUNDERBADGE",
+  [3] = "RAINBOWBADGE", [4] = "SOULBADGE", [5] = "MARSHBADGE",
+  [6] = "VOLCANOBADGE", [7] = "EARTHBADGE",
+}
+local BADGE_BY_BIT_SET = {}
+for _, name in pairs(BADGE_BY_BIT) do BADGE_BY_BIT_SET[name] = true end
+
+-- STATUS_* bits (constants/battle_constants.asm): 0-2 sleep-turns-left,
+-- 3 PSN, 4 BRN, 5 FRZ, 6 PAR
+local STATUS_BIT = { PSN = 3, BRN = 4, FRZ = 5, PAR = 6 }
+local function decodeStatus(b)
+  if bit.band(b, 7) > 0 then return "SLP" end
+  for name, bitIdx in pairs(STATUS_BIT) do
+    if bit.band(b, bit.lshift(1, bitIdx)) ~= 0 then return name end
+  end
+  return nil
+end
+local function encodeStatus(status)
+  if status == "SLP" then return 7 end
+  if status and STATUS_BIT[status] then return bit.lshift(1, STATUS_BIT[status]) end
+  return 0
+end
+
+local function buildIndexCrosswalk(defs)
+  local byIndex, byId = {}, {}
+  for id, def in pairs(defs or {}) do
+    if def.index ~= nil then
+      byIndex[def.index] = id
+      byId[id] = def.index
+    end
+  end
+  return byIndex, byId
+end
+
+-- Pokedex bit position: NATIONAL DEX NUMBER (1-151), NOT the internal ROM
+-- species byte (`def.index`, used for party/box mon structs) -- these are
+-- two completely different Gen1 numbering schemes (the whole "MissingNo"
+-- phenomenon is dex-number vs internal-index mismatches). This project's
+-- generated data has no dedicated dex-number field, but every pokemon.lua
+-- entry's `source` documents its extraction origin as "ROM:BaseStats[N]",
+-- and BaseStats is declared in dex order in the disassembly -- verified
+-- directly against 5 species (BULBASAUR->[1], CHARMANDER->[4],
+-- SQUIRTLE->[7], PIKACHU->[25], MEWTWO->[150], all exactly their real
+-- national dex numbers) before relying on it here.
+local function buildDexCrosswalk(defs)
+  local byDex, dexOf = {}, {}
+  for id, def in pairs(defs or {}) do
+    local n = def.source and tonumber(def.source:match("BaseStats%[(%d+)%]"))
+    if n then
+      byDex[n] = id
+      dexOf[id] = n
+    end
+  end
+  return byDex, dexOf
+end
+
+-- TM/HM item entries carry no `index` (data/generated/items.lua extracts
+-- them by move/slot, not by their place in the raw item-constant table),
+-- so buildIndexCrosswalk alone would silently drop every TM/HM from the
+-- bag/PC on encode. Their real item ids ARE derivable: pokered's
+-- constants/item_constants.asm declares "HM_\1: the item id, starting at
+-- $C4" and "TM_\1: the item id, starting at $C9" for slot 1, incrementing
+-- per slot -- i.e. HM01=196+.. , TM01=201+(number-1).
+local function addMachineIndices(defs, byIndex, byId)
+  for id, def in pairs(defs or {}) do
+    if byId[id] == nil and def.machine and def.machine.number then
+      local base = def.machine.kind == "HM" and 195 or 200
+      local idx = base + def.machine.number
+      byIndex[idx] = id
+      byId[id] = idx
+    end
+  end
+end
+
+function GenSave.crosswalks(data)
+  local pokemonByIndex, pokemonIndex = buildIndexCrosswalk(data.pokemon)
+  local movesByIndex, movesIndex = buildIndexCrosswalk(data.moves)
+  local itemsByIndex, itemsIndex = buildIndexCrosswalk(data.items)
+  addMachineIndices(data.items, itemsByIndex, itemsIndex)
+  local mapsByIndex, mapsIndex = buildIndexCrosswalk(data.maps)
+  local pokemonByDex, pokemonDex = buildDexCrosswalk(data.pokemon)
+  return {
+    pokemonByIndex = pokemonByIndex, pokemonIndex = pokemonIndex,
+    pokemonByDex = pokemonByDex, pokemonDex = pokemonDex,
+    movesByIndex = movesByIndex, movesIndex = movesIndex,
+    itemsByIndex = itemsByIndex, itemsIndex = itemsIndex,
+    mapsByIndex = mapsByIndex, mapsIndex = mapsIndex,
+    speciesDefs = data.pokemon or {},
+  }
+end
+
+-- ------------------------------------------------------------------
+-- Mon struct (box_struct is a byte-for-byte prefix of party_struct;
+-- decodeMon reads the box_struct fields, then Level+Stats if isParty).
+-- Type1/Type2 are read for nothing (this project derives type from
+-- species) but re-derived from data.pokemon[species].types on encode.
+-- ------------------------------------------------------------------
+
+local function decodeMon(bytes, off, isParty, cw)
+  local speciesIdx = u8(bytes, off)
+  if speciesIdx == 0 then return nil end -- empty slot
+  local species = cw.pokemonByIndex[speciesIdx]
+  local hp = u16be(bytes, off + 1)
+  local boxLevel = u8(bytes, off + 3)
+  local status = decodeStatus(u8(bytes, off + 4))
+  local catchRate = u8(bytes, off + 7)
+  local moves = {}
+  for i = 0, 3 do
+    local moveIdx = u8(bytes, off + 8 + i)
+    if moveIdx > 0 then
+      local pp, ppUps = decodePPByte(u8(bytes, off + 29 + i))
+      moves[#moves + 1] = { id = cw.movesByIndex[moveIdx], pp = pp, ppUps = ppUps }
+    end
+  end
+  local otId = u16be(bytes, off + 12)
+  local exp = u24be(bytes, off + 14)
+  local statExp = {
+    hp = u16be(bytes, off + 17), attack = u16be(bytes, off + 19),
+    defense = u16be(bytes, off + 21), speed = u16be(bytes, off + 23),
+    special = u16be(bytes, off + 25),
+  }
+  local dvs = decodeDVs(bytes, off + 27)
+  local mon = {
+    species = species, exp = exp, dvs = dvs, statExp = statExp,
+    hp = hp, status = status, moves = moves, otId = otId,
+    catchRate = catchRate, level = boxLevel,
+    -- Type1/Type2 as physically stored. This project derives type from species
+    -- for gameplay, but the raw bytes are captured so encode() can reproduce
+    -- them verbatim: some real saves (traded/tampered mons) carry type values
+    -- that do not match the ROM base stats, and re-deriving would corrupt them.
+    typeBytes = { u8(bytes, off + 5), u8(bytes, off + 6) },
+  }
+  if isParty then
+    mon.level = u8(bytes, off + 33)
+    mon.stats = {
+      hp = u16be(bytes, off + 34), attack = u16be(bytes, off + 36),
+      defense = u16be(bytes, off + 38), speed = u16be(bytes, off + 40),
+      special = u16be(bytes, off + 42),
+    }
+  end
+  return mon
+end
+
+local function encodeMon(buf, off, mon, isParty, cw)
+  if not mon then
+    setByte(buf, off, 0)
+    return
+  end
+  setByte(buf, off, cw.pokemonIndex[mon.species] or 0)
+  setU16be(buf, off + 1, mon.hp or 0)
+  setByte(buf, off + 3, mon.level or 1)
+  setByte(buf, off + 4, encodeStatus(mon.status))
+  local def = cw.speciesDefs[mon.species]
+  if mon.typeBytes then
+    -- reproduce the exact stored type bytes captured on decode (faithful
+    -- byte round-trip); fresh, engine-built mons have none and derive below.
+    setByte(buf, off + 5, mon.typeBytes[1] or 0)
+    setByte(buf, off + 6, mon.typeBytes[2] or 0)
+  else
+    local t = (def and def.types) or {}
+    setByte(buf, off + 5, TYPE_INDEX[t[1]] or 0)
+    setByte(buf, off + 6, TYPE_INDEX[t[2] or t[1]] or 0)
+  end
+  setByte(buf, off + 7, mon.catchRate or (def and def.catchRate) or 0)
+  for i = 0, 3 do
+    local mv = mon.moves and mon.moves[i + 1]
+    setByte(buf, off + 8 + i, mv and (cw.movesIndex[mv.id] or 0) or 0)
+    setByte(buf, off + 29 + i, mv and encodePPByte(mv.pp, mv.ppUps) or 0)
+  end
+  setU16be(buf, off + 12, mon.otId or 0)
+  setU24be(buf, off + 14, mon.exp or 0)
+  local se = mon.statExp or {}
+  setU16be(buf, off + 17, se.hp or 0)
+  setU16be(buf, off + 19, se.attack or 0)
+  setU16be(buf, off + 21, se.defense or 0)
+  setU16be(buf, off + 23, se.speed or 0)
+  setU16be(buf, off + 25, se.special or 0)
+  encodeDVs(buf, off + 27, mon.dvs or {})
+  if isParty then
+    setByte(buf, off + 33, mon.level or 1)
+    local st = mon.stats or {}
+    setU16be(buf, off + 34, st.hp or 0)
+    setU16be(buf, off + 36, st.attack or 0)
+    setU16be(buf, off + 38, st.defense or 0)
+    setU16be(buf, off + 40, st.speed or 0)
+    setU16be(buf, off + 42, st.special or 0)
+  end
+end
+
+-- ------------------------------------------------------------------
+-- Bag / PC items: (id, qty) byte pairs, $FF-terminated
+-- ------------------------------------------------------------------
+
+local function decodeItemList(bytes, off, capacity, cw)
+  local inventory, order = {}, {}
+  for i = 0, capacity - 1 do
+    local idByte = u8(bytes, off + i * 2)
+    if idByte == 0xFF then break end
+    local qty = u8(bytes, off + i * 2 + 1)
+    local id = cw.itemsByIndex[idByte]
+    if id then
+      inventory[id] = qty
+      order[#order + 1] = id
+    end
+  end
+  return inventory, order
+end
+
+local function encodeItemList(buf, off, capacity, inventory, order, cw)
+  local i = 0
+  local seen = {}
+  local function put(id, qty)
+    if i >= capacity or not qty or qty <= 0 then return end
+    local idByte = cw.itemsIndex[id]
+    if not idByte then return end
+    setByte(buf, off + i * 2, idByte)
+    setByte(buf, off + i * 2 + 1, math.min(qty, 99))
+    i = i + 1
+    seen[id] = true
+  end
+  for _, id in ipairs(order or {}) do
+    if inventory[id] and not seen[id] then put(id, inventory[id]) end
+  end
+  for id, qty in pairs(inventory or {}) do
+    if not seen[id] then put(id, qty) end
+  end
+  setByte(buf, off + i * 2, 0xFF)
+  return i -- count actually written (badges etc. in `inventory` that
+           -- aren't real items are silently skipped by put(), so this
+           -- can be less than #inventory -- see the wNumBagItems caller)
+end
+
+-- ------------------------------------------------------------------
+-- decode: raw 32768-byte SRAM string -> save.lua-shaped table
+-- ------------------------------------------------------------------
+
+function GenSave.decode(bytes, data, opts)
+  assert(#bytes == GenSave.SAVE_SIZE, "expected a 32768-byte save")
+  local cw = GenSave.crosswalks(data)
+  local warnings = {}
+  local function warn(msg) warnings[#warnings + 1] = msg end
+
+  if checksum(bytes, O.checksumStart, O.checksumEnd) ~= u8(bytes, O.mainChecksum) then
+    warn("main data checksum mismatch (importing anyway)")
+  end
+
+  local save = {
+    meta = { format = "gen1_import" },
+    player = {
+      name = decodeName(bytes, O.playerName, NAME_LENGTH),
+      rival = decodeName(bytes, O.rivalName, NAME_LENGTH),
+      id = u16be(bytes, O.playerId),
+    },
+    money = readBcd(bytes, O.money, 3),
+    coins = readBcd(bytes, O.coins, 2),
+    inventory = {},
+    pcItems = {},
+    pokedex = { seen = {}, owned = {} },
+    flags = {},
+    party = {},
+    boxes = {},
+    currentBox = 1,
+  }
+
+  -- pokedex (own/seen, flag_array NUM_POKEMON: bit 0 = dex #1)
+  for dex, species in pairs(cw.pokemonByDex) do
+    local bitIdx = dex - 1
+    if bitGet(bytes, O.pokedexOwned, bitIdx) then save.pokedex.owned[species] = true end
+    if bitGet(bytes, O.pokedexSeen, bitIdx) then save.pokedex.seen[species] = true end
+  end
+
+  save.inventory, save.bagOrder = decodeItemList(bytes, O.bagItems, 20, cw)
+  save.pcItems, save.pcOrder = decodeItemList(bytes, O.pcItems, 50, cw)
+
+  -- badges: truthy save.inventory[id] entries (src/inventory/Badges.lua),
+  -- set AFTER decodeItemList since that call replaces save.inventory
+  local badgesByte = u8(bytes, O.badges)
+  for i = 0, NUM_BADGES - 1 do
+    if bit.band(badgesByte, bit.lshift(1, i)) ~= 0 then
+      save.inventory[BADGE_BY_BIT[i]] = 1
+    end
+  end
+
+  -- party
+  local partyCount = u8(bytes, O.partyCount)
+  for i = 0, math.min(partyCount, PARTY_LENGTH) - 1 do
+    local mon = decodeMon(bytes, O.partyMons + i * PARTY_STRUCT_SIZE, true, cw)
+    if mon then
+      mon.ot = decodeName(bytes, O.partyMonOT + i * NAME_LENGTH, NAME_LENGTH)
+      mon.nickname = decodeName(bytes, O.partyMonNicks + i * NAME_LENGTH, NAME_LENGTH)
+      save.party[#save.party + 1] = mon
+    end
+  end
+
+  -- current box (bank 1) + the 11 stored boxes (banks 2/3)
+  for i = 1, 12 do save.boxes[i] = {} end
+  local function decodeBoxRegion(base, boxNum)
+    local count = u8(bytes, base)
+    for i = 0, math.min(count, MONS_PER_BOX) - 1 do
+      local mon = decodeMon(bytes, base + 22 + i * BOX_STRUCT_SIZE, false, cw)
+      if mon then
+        mon.ot = decodeName(bytes, base + 22 + MONS_PER_BOX * BOX_STRUCT_SIZE + i * NAME_LENGTH, NAME_LENGTH)
+        mon.nickname = decodeName(bytes, base + 22 + MONS_PER_BOX * (BOX_STRUCT_SIZE + NAME_LENGTH) + i * NAME_LENGTH, NAME_LENGTH)
+        table.insert(save.boxes[boxNum], mon)
+      end
+    end
+  end
+  local curBoxNum = bit.band(u8(bytes, O.currentBoxNum), 0x7F) -- 0-based box index
+  curBoxNum = math.max(1, math.min(12, curBoxNum + 1))
+  decodeBoxRegion(O.curBoxData, curBoxNum)
+  for b = 1, 6 do
+    if b + 0 ~= curBoxNum then decodeBoxRegion(O.box1 + (b - 1) * BOX_REGION_SIZE, b) end
+  end
+  for b = 7, 12 do
+    if b ~= curBoxNum then decodeBoxRegion(O.box7 + (b - 7) * BOX_REGION_SIZE, b) end
+  end
+  save.currentBox = curBoxNum
+
+  -- event flags (only bits with a known name are decoded)
+  local events = data.eventFlags
+  if events then
+    for bitIdx, name in pairs(events.byBit) do
+      if bitGet(bytes, O.eventFlags, bitIdx) then save.flags[name] = true end
+    end
+  end
+
+  -- map + position
+  local mapIdx = u8(bytes, O.curMap)
+  local mapId = cw.mapsByIndex[mapIdx]
+  local y, x = u8(bytes, O.yCoord), u8(bytes, O.xCoord)
+  if mapId then
+    save.player.map, save.player.x, save.player.y = mapId, x, y
+  else
+    warn(("unknown map index %d, defaulting spawn"):format(mapIdx))
+  end
+  local lastMapIdx = u8(bytes, O.lastMap)
+  local lastMapId = cw.mapsByIndex[lastMapIdx]
+  if lastMapId then save.lastOutdoor = { id = lastMapId } end
+
+  -- play time: this project stores save.playTime as a single float of
+  -- SECONDS (src/core/Game.lua accumulates dt each frame; StartMenu /
+  -- TrainerCard / TitleState render it H:MM via t/3600 and (t/60)%60).
+  -- Fold the Gen1 H/M/S/F fields into that one number; frames are 1/60s
+  -- sub-second ticks, kept as a fraction so an export recovers them exactly.
+  save.playTime = u8(bytes, O.playTimeHours) * 3600
+                + u8(bytes, O.playTimeMinutes) * 60
+                + u8(bytes, O.playTimeSeconds)
+                + u8(bytes, O.playTimeFrames) / 60
+
+  save.warnings = warnings
+  save.rawImport = bytes -- template for a later encode(); see file header
+  return save
+end
+
+-- ------------------------------------------------------------------
+-- encode: save.lua-shaped table -> raw 32768-byte SRAM string
+-- ------------------------------------------------------------------
+
+function GenSave.encode(save, data, template)
+  local cw = GenSave.crosswalks(data)
+  local src = template or save.rawImport
+  local buf = {}
+  if src then
+    for i = 1, GenSave.SAVE_SIZE do buf[i] = src:sub(i, i) end
+  else
+    local zero = string.char(0)
+    for i = 1, GenSave.SAVE_SIZE do buf[i] = zero end
+  end
+
+  encodeName(buf, O.playerName, NAME_LENGTH, (save.player and save.player.name) or "RED")
+  encodeName(buf, O.rivalName, NAME_LENGTH, (save.player and save.player.rival) or "BLUE")
+  setU16be(buf, O.playerId, (save.player and save.player.id) or 0)
+  setBcd(buf, O.money, 3, math.min(save.money or 0, 999999))
+  setBcd(buf, O.coins, 2, math.min(save.coins or 0, 9999))
+
+  local badgesByte = 0
+  for bitIdx, name in pairs(BADGE_BY_BIT) do
+    if save.inventory and save.inventory[name] then
+      badgesByte = bit.bor(badgesByte, bit.lshift(1, bitIdx))
+    end
+  end
+  setByte(buf, O.badges, badgesByte)
+
+  for dex, species in pairs(cw.pokemonByDex) do
+    local bitIdx = dex - 1
+    bitSet(buf, O.pokedexOwned, bitIdx,
+          (save.pokedex and save.pokedex.owned and save.pokedex.owned[species]) and true or false)
+    bitSet(buf, O.pokedexSeen, bitIdx,
+          (save.pokedex and save.pokedex.seen and save.pokedex.seen[species]) and true or false)
+  end
+
+  -- Badges occupy real item IDs in data/generated/items.lua (Gen1's item
+  -- ID space includes them, $01-$08, for the "got the BOULDERBADGE!"
+  -- text display), but this project's save.lua stores them as truthy
+  -- save.inventory[id] entries alongside actual bag items (see the badge
+  -- block above and src/inventory/Badges.lua) -- a real save NEVER
+  -- writes them into wBagItems (they only ever live in wObtainedBadges,
+  -- already encoded above), so they must be filtered out here or they'd
+  -- corrupt the bag with bogus "badge items".
+  local bagInventory = {}
+  for id, qty in pairs(save.inventory or {}) do
+    if not BADGE_BY_BIT_SET[id] then bagInventory[id] = qty end
+  end
+  local bagN = encodeItemList(buf, O.bagItems, 20, bagInventory, save.bagOrder, cw)
+  setByte(buf, O.numBagItems, bagN)
+  local pcN = encodeItemList(buf, O.pcItems, 50, save.pcItems or {}, save.pcOrder, cw)
+  setByte(buf, O.numPcItems, pcN)
+
+  local events = data.eventFlags
+  if events and save.flags then
+    for name in pairs(save.flags) do
+      local bitIdx = events.byName[name]
+      if bitIdx then bitSet(buf, O.eventFlags, bitIdx, true) end
+    end
+  end
+
+  -- party
+  local party = save.party or {}
+  local partyN = math.min(#party, PARTY_LENGTH)
+  setByte(buf, O.partyCount, partyN)
+  for i = 0, partyN - 1 do
+    local mon = party[i + 1]
+    encodeMon(buf, O.partyMons + i * PARTY_STRUCT_SIZE, mon, true, cw)
+    setByte(buf, O.partySpecies + i, cw.pokemonIndex[mon.species] or 0)
+    encodeName(buf, O.partyMonOT + i * NAME_LENGTH, NAME_LENGTH,
+              mon.ot or (save.player and save.player.name) or "RED")
+    encodeName(buf, O.partyMonNicks + i * NAME_LENGTH, NAME_LENGTH,
+              mon.nickname or mon.species or "")
+  end
+  -- $FF-terminate the species index list right after the last real mon. The
+  -- struct, OT-name and nickname bytes of the empty slots past partyN are left
+  -- exactly as the template holds them (original stale data -> byte-identical
+  -- round-trip) or zero on a fresh export -- the game never reads past the
+  -- count, so this matches how it leaves those bytes itself.
+  setByte(buf, O.partySpecies + partyN, 0xFF)
+
+  -- boxes: current box mirrors save.currentBox into sCurBoxData; all 12
+  -- also get written into their bank-2/3 slot (sCurBoxData is a working
+  -- copy the real game keeps in sync on every PC visit, so keeping both
+  -- copies consistent here matches that invariant)
+  local function encodeBoxRegion(base, mons)
+    local n = math.min(#mons, MONS_PER_BOX)
+    setByte(buf, base, n)
+    for i = 0, n - 1 do
+      local mon = mons[i + 1]
+      encodeMon(buf, base + 22 + i * BOX_STRUCT_SIZE, mon, false, cw)
+      setByte(buf, base + 1 + i, cw.pokemonIndex[mon.species] or 0)
+      encodeName(buf, base + 22 + MONS_PER_BOX * BOX_STRUCT_SIZE + i * NAME_LENGTH, NAME_LENGTH,
+                mon.ot or (save.player and save.player.name) or "RED")
+      encodeName(buf, base + 22 + MONS_PER_BOX * (BOX_STRUCT_SIZE + NAME_LENGTH) + i * NAME_LENGTH, NAME_LENGTH,
+                mon.nickname or mon.species or "")
+    end
+    -- $FF-terminate the species list after the last real mon; empty slots past
+    -- n keep their template bytes (byte-identical round-trip) or zero (fresh
+    -- export), just as the game leaves stale box data untouched past the count.
+    setByte(buf, base + 1 + n, 0xFF)
+  end
+  local boxes = save.boxes or {}
+  local curBoxNum = math.max(1, math.min(12, save.currentBox or 1))
+  encodeBoxRegion(O.curBoxData, boxes[curBoxNum] or {})
+  -- bit 7 of wCurBoxNum is the "box system initialized" flag, not part of the
+  -- 0-11 index; preserve it from the template, or set it on a templateless
+  -- export (any save we emit has an initialized box system).
+  local prevBoxByte = buf[O.currentBoxNum + 1]
+  local boxHiBit = (src and prevBoxByte) and bit.band(prevBoxByte:byte(), 0x80) or 0x80
+  setByte(buf, O.currentBoxNum, bit.bor(bit.band(curBoxNum - 1, 0x7F), boxHiBit))
+  for b = 1, 6 do encodeBoxRegion(O.box1 + (b - 1) * BOX_REGION_SIZE, boxes[b] or {}) end
+  for b = 7, 12 do encodeBoxRegion(O.box7 + (b - 7) * BOX_REGION_SIZE, boxes[b] or {}) end
+
+  -- map + position
+  if save.player and save.player.map then
+    setByte(buf, O.curMap, cw.mapsIndex[save.player.map] or 0)
+    setByte(buf, O.yCoord, save.player.y or 0)
+    setByte(buf, O.xCoord, save.player.x or 0)
+  end
+  if save.lastOutdoor and save.lastOutdoor.id then
+    setByte(buf, O.lastMap, cw.mapsIndex[save.lastOutdoor.id] or 0)
+  end
+
+  -- play time: split save.playTime (seconds) back into H/M/S/F. The real
+  -- game freezes the clock at 255h and sets wPlayTimeMaxed once past it, so
+  -- mirror that cap rather than letting hours overflow a single byte.
+  local totalFrames = math.floor((save.playTime or 0) * 60 + 0.5)
+  local hours = math.floor(totalFrames / 216000) -- 3600s * 60 frames
+  if hours > 255 then
+    setByte(buf, O.playTimeHours, 255)
+    setByte(buf, O.playTimeMaxed, 1)
+    setByte(buf, O.playTimeMinutes, 59)
+    setByte(buf, O.playTimeSeconds, 59)
+    setByte(buf, O.playTimeFrames, 59)
+  else
+    local rem = totalFrames - hours * 216000
+    local mins = math.floor(rem / 3600); rem = rem - mins * 3600
+    local secs = math.floor(rem / 60)
+    setByte(buf, O.playTimeHours, hours)
+    setByte(buf, O.playTimeMaxed, 0)
+    setByte(buf, O.playTimeMinutes, mins)
+    setByte(buf, O.playTimeSeconds, secs)
+    setByte(buf, O.playTimeFrames, rem - secs * 60)
+  end
+
+  local out = table.concat(buf)
+  -- checksums, computed last over the now-final bytes
+  local outBuf = {}
+  for i = 1, #out do outBuf[i] = out:sub(i, i) end
+  setByte(outBuf, O.mainChecksum, checksum(out, O.checksumStart, O.checksumEnd))
+  -- Per pokered (engine/menus/save.asm SaveSAVtoSRAM / CalcCheckSum): each box
+  -- gets its own checksum, and the bank aggregate is CalcCheckSum over the
+  -- ENTIRE six-box region (6 x 1122 bytes), not a sum of the six box sums.
+  local function boxChecksum(base) return checksum(out, base, base + BOX_REGION_SIZE) end
+  for b = 0, 5 do
+    setByte(outBuf, O.boxBank2IndividualChecksums + b,
+            boxChecksum(O.box1 + b * BOX_REGION_SIZE))
+  end
+  setByte(outBuf, O.boxBank2Checksum,
+          checksum(out, O.box1, O.box1 + 6 * BOX_REGION_SIZE))
+  for b = 0, 5 do
+    setByte(outBuf, O.boxBank3IndividualChecksums + b,
+            boxChecksum(O.box7 + b * BOX_REGION_SIZE))
+  end
+  setByte(outBuf, O.boxBank3Checksum,
+          checksum(out, O.box7, O.box7 + 6 * BOX_REGION_SIZE))
+
+  return table.concat(outBuf)
+end
+
+return GenSave

src/save_convert/SaveConvert.lua

@@ -0,0 +1,189 @@
+-- SaveConvert -- the runtime-facing entry point the launcher UI calls to
+-- turn a vanilla Gen1 (Red/Blue, international) battery save into this
+-- project's in-memory save table, and back out to a raw .sav image.
+--
+-- This is the ONE place the engine, the tests and the CLI
+-- (tools/save_convert/convert.lua) share: the GenSave codec, the crosswalk
+-- data loading, the merge over new-game defaults, and the version tag all
+-- live here so every consumer behaves identically.
+--
+-- Pure Lua, no love.* dependency at require time: GenSave and the crosswalk
+-- tables load through `require`, exactly how src/core/Data.lua pulls the
+-- generated modules -- which resolves under both plain luajit (package.path
+-- "./?.lua") for the headless CLI/tests and love.filesystem for a fused
+-- build, with an OS-path fallback for odd working directories. The only
+-- place `love` is referenced is inside a guarded fallback, so running under
+-- stock Lua never touches it.
+
+local GenSave = require("src.save_convert.GenSave")
+
+local SaveConvert = {}
+
+SaveConvert.SAVE_SIZE = GenSave.SAVE_SIZE
+
+-- ------------------------------------------------------------------
+-- Crosswalk data loading (cached).  Mirrors src/core/Data.lua: prefer
+-- `require` (works headless via package.path and fused via love's package
+-- searcher); fall back to love.filesystem.load, then a plain dofile, for
+-- the rare case a host has an unusual cwd or module path.
+-- ------------------------------------------------------------------
+
+-- { require-module-path, os-relative-file-path } for each table the codec
+-- needs.  pokemon/moves/items/maps come from the shared generated data;
+-- charmap/event_flags are the save-convert-specific crosswalks.
+local DATA_MODULES = {
+  pokemon    = { "data.generated.pokemon",          "data/generated/pokemon.lua" },
+  moves      = { "data.generated.moves",            "data/generated/moves.lua" },
+  items      = { "data.generated.items",            "data/generated/items.lua" },
+  maps       = { "data.generated.maps",             "data/generated/maps.lua" },
+  charmap    = { "src.save_convert.data.charmap",   "src/save_convert/data/charmap.lua" },
+  eventFlags = { "src.save_convert.data.event_flags", "src/save_convert/data/event_flags.lua" },
+}
+
+local function loadTable(requirePath, filePath)
+  local ok, mod = pcall(require, requirePath)
+  if ok and type(mod) == "table" then return mod end
+  -- fused build with an unexpected module path: read straight off the
+  -- mounted filesystem (love is a global here, only ever touched when it
+  -- actually exists -- stock Lua never reaches this branch)
+  if love and love.filesystem and love.filesystem.getInfo
+     and love.filesystem.getInfo(filePath) then
+    local chunk = love.filesystem.load(filePath)
+    if chunk then
+      local m = chunk()
+      if type(m) == "table" then return m end
+    end
+  end
+  local chunk = loadfile(filePath)
+  if chunk then
+    local m = chunk()
+    if type(m) == "table" then return m end
+  end
+  return nil, ("cannot load save-convert data module %q (tried require %q and file %q)")
+    :format(requirePath, requirePath, filePath)
+end
+
+local crosswalk   -- { pokemon=, moves=, items=, maps=, eventFlags= }
+local charmapReady
+
+local function ensureData()
+  if not crosswalk then
+    local data = {}
+    for key, spec in pairs(DATA_MODULES) do
+      if key ~= "charmap" then
+        local mod, e = loadTable(spec[1], spec[2])
+        if not mod then return nil, e end
+        data[key] = mod
+      end
+    end
+    crosswalk = data
+  end
+  if not charmapReady then
+    local cm, err = loadTable(DATA_MODULES.charmap[1], DATA_MODULES.charmap[2])
+    if not cm then return nil, err end
+    GenSave.setCharmap(cm)
+    charmapReady = true
+  end
+  return crosswalk
+end
+
+-- Exposed for the CLI/tests so they can share the exact data set the codec
+-- uses (and so a caller can pre-warm the cache).  Returns data, err.
+function SaveConvert.loadData()
+  return ensureData()
+end
+
+-- ------------------------------------------------------------------
+-- new-game default skeleton the decoded fields merge on top of.  Carried
+-- verbatim from tools/save_convert/convert.lua so the CLI and the runtime
+-- produce a byte-identical save table for the same input.
+-- ------------------------------------------------------------------
+
+local function defaultsSave()
+  return {
+    meta = { format = "gen1_import", mods = {} },
+    defeatedTrainers = {},
+    repelSteps = 0,
+    modData = {},
+    options = {
+      textSpeed = 3, animations = true, battleStyle = "shift",
+      ruleset = "gen1_faithful", musicVol = 7, sfxVol = 7, musicFilter = 0,
+      speed = 1, colors = "gbc", tilt = 0, gbcfx = 0,
+      videoMode = "windowed", mods = {},
+    },
+  }
+end
+
+-- Merge a GenSave.decode() result over the new-game defaults, exactly the
+-- way convert.lua did, then stamp the requested version.  The 32768-byte
+-- import template GenSave stashes as `rawImport` and the decode `warnings`
+-- are dropped here: neither belongs in a serialized slot file (a fresh
+-- export always starts zero-filled -- see GenSave.lua's header).
+local function mergeDefaults(decoded, version)
+  decoded.warnings = nil
+  decoded.rawImport = nil
+  local save = defaultsSave()
+  for k, v in pairs(decoded) do save[k] = v end
+  save.lastHeal = { map = save.player.map, x = save.player.x, y = save.player.y }
+  save.lastOutdoor = save.lastOutdoor or { id = save.player.map }
+  if version ~= nil then
+    save.meta = save.meta or {}
+    save.meta.version = version
+  end
+  return save
+end
+SaveConvert.mergeDefaults = mergeDefaults
+
+-- ------------------------------------------------------------------
+-- Public API
+-- ------------------------------------------------------------------
+
+-- importSav(bytes, version) -> saveTable, err
+-- bytes: the raw 32768-byte SRAM string. Validates size and the main-data
+-- checksum, decodes through GenSave, and returns a save table fully merged
+-- over the new-game defaults and tagged with `version`, ready to hand to
+-- SaveSerializer.encode for a slot file. On any failure returns nil + a
+-- message (never raises).
+function SaveConvert.importSav(bytes, version)
+  if type(bytes) ~= "string" then
+    return nil, "expected raw save bytes as a string"
+  end
+  if #bytes ~= GenSave.SAVE_SIZE then
+    return nil, ("save must be %d bytes, got %d"):format(GenSave.SAVE_SIZE, #bytes)
+  end
+  local data, derr = ensureData()
+  if not data then return nil, derr end
+
+  local ok, decoded = pcall(GenSave.decode, bytes, data)
+  if not ok then return nil, "decode failed: " .. tostring(decoded) end
+
+  -- checksum validation: GenSave.decode records a warning rather than
+  -- throwing (so it can still read a foreign/corrupt save), but for the
+  -- runtime import path a bad main-data checksum means the file is not a
+  -- trustworthy save, so reject it.
+  for _, w in ipairs(decoded.warnings or {}) do
+    if tostring(w):find("checksum") then
+      return nil, "save data checksum invalid (" .. tostring(w) .. ")"
+    end
+  end
+
+  return mergeDefaults(decoded, version)
+end
+
+-- exportSav(saveTable) -> bytes, err
+-- Encodes a save table back to a raw 32768-byte SRAM image. Template-aware:
+-- if the table still carries the stashed import template (saveTable.rawImport)
+-- GenSave reproduces every unmodeled region from it; otherwise those regions
+-- are zero-filled. On failure returns nil + a message (never raises).
+function SaveConvert.exportSav(saveTable)
+  if type(saveTable) ~= "table" then
+    return nil, "expected a save table"
+  end
+  local data, derr = ensureData()
+  if not data then return nil, derr end
+  local ok, bytes = pcall(GenSave.encode, saveTable, data, nil)
+  if not ok then return nil, "encode failed: " .. tostring(bytes) end
+  return bytes
+end
+
+return SaveConvert

src/save_convert/data/charmap.lua

@@ -0,0 +1,579 @@
+-- Generated by tools/build_data.py. DO NOT EDIT.
+-- Gen1 text byte <-> glyph/token charmap (fixed-length name
+-- fields: player/rival/OT names, nicknames -- box/party mon
+-- names are NUL-free, '@' ($50) terminated, space-padded).
+-- byToken's key is the literal glyph for ordinary characters
+-- ("A", "é", ...) or a bracketed control token
+-- ("<PLAYER>", "@") for terminators/substitutions -- only
+-- the plain single-glyph entries are meaningful inside a name.
+return {
+  byByte = {
+    [0] = "<NULL>",
+    [5] = "ガ",
+    [6] = "ギ",
+    [7] = "グ",
+    [8] = "ゲ",
+    [9] = "ゴ",
+    [10] = "ザ",
+    [11] = "ジ",
+    [12] = "ズ",
+    [13] = "ゼ",
+    [14] = "ゾ",
+    [15] = "ダ",
+    [16] = "ヂ",
+    [17] = "ヅ",
+    [18] = "デ",
+    [19] = "ド",
+    [25] = "バ",
+    [26] = "ビ",
+    [27] = "ブ",
+    [28] = "ボ",
+    [38] = "が",
+    [39] = "ぎ",
+    [40] = "ぐ",
+    [41] = "げ",
+    [42] = "ご",
+    [43] = "ざ",
+    [44] = "じ",
+    [45] = "ず",
+    [46] = "ぜ",
+    [47] = "ぞ",
+    [48] = "だ",
+    [49] = "ぢ",
+    [50] = "づ",
+    [51] = "で",
+    [52] = "ど",
+    [58] = "ば",
+    [59] = "び",
+    [60] = "ぶ",
+    [61] = "べ",
+    [62] = "ぼ",
+    [64] = "パ",
+    [65] = "ピ",
+    [66] = "プ",
+    [67] = "ポ",
+    [68] = "ぱ",
+    [69] = "ぴ",
+    [70] = "ぷ",
+    [71] = "ぺ",
+    [72] = "ぽ",
+    [73] = "<PAGE>",
+    [74] = "<PKMN>",
+    [75] = "<_CONT>",
+    [76] = "<SCROLL>",
+    [78] = "<NEXT>",
+    [79] = "<LINE>",
+    [80] = "@",
+    [81] = "<PARA>",
+    [82] = "<PLAYER>",
+    [83] = "<RIVAL>",
+    [84] = "#",
+    [85] = "<CONT>",
+    [86] = "<……>",
+    [87] = "<DONE>",
+    [88] = "<PROMPT>",
+    [89] = "<TARGET>",
+    [90] = "<USER>",
+    [91] = "<PC>",
+    [92] = "<TM>",
+    [93] = "<TRAINER>",
+    [94] = "<ROCKET>",
+    [95] = "<DEXEND>",
+    [96] = "<BOLD_A>",
+    [97] = "<BOLD_B>",
+    [98] = "<BOLD_C>",
+    [99] = "<BOLD_D>",
+    [100] = "<BOLD_E>",
+    [101] = "<BOLD_F>",
+    [102] = "<BOLD_G>",
+    [103] = "<BOLD_H>",
+    [104] = "<BOLD_I>",
+    [105] = "<BOLD_V>",
+    [106] = "<BOLD_S>",
+    [107] = "<BOLD_L>",
+    [108] = "<BOLD_M>",
+    [109] = "<COLON>",
+    [110] = "ぃ",
+    [111] = "ぅ",
+    [112] = "‘",
+    [113] = "’",
+    [114] = "“",
+    [115] = "”",
+    [116] = "·",
+    [117] = "…",
+    [118] = "ぁ",
+    [119] = "ぇ",
+    [120] = "ぉ",
+    [121] = "┌",
+    [122] = "─",
+    [123] = "┐",
+    [124] = "│",
+    [125] = "└",
+    [126] = "┘",
+    [127] = " ",
+    [128] = "A",
+    [129] = "B",
+    [130] = "C",
+    [131] = "D",
+    [132] = "E",
+    [133] = "F",
+    [134] = "G",
+    [135] = "H",
+    [136] = "I",
+    [137] = "J",
+    [138] = "K",
+    [139] = "L",
+    [140] = "M",
+    [141] = "N",
+    [142] = "O",
+    [143] = "P",
+    [144] = "Q",
+    [145] = "R",
+    [146] = "S",
+    [147] = "T",
+    [148] = "U",
+    [149] = "V",
+    [150] = "W",
+    [151] = "X",
+    [152] = "Y",
+    [153] = "Z",
+    [154] = "(",
+    [155] = ")",
+    [156] = ":",
+    [157] = ";",
+    [158] = "[",
+    [159] = "]",
+    [160] = "a",
+    [161] = "b",
+    [162] = "c",
+    [163] = "d",
+    [164] = "e",
+    [165] = "f",
+    [166] = "g",
+    [167] = "h",
+    [168] = "i",
+    [169] = "j",
+    [170] = "k",
+    [171] = "l",
+    [172] = "m",
+    [173] = "n",
+    [174] = "o",
+    [175] = "p",
+    [176] = "q",
+    [177] = "r",
+    [178] = "s",
+    [179] = "t",
+    [180] = "u",
+    [181] = "v",
+    [182] = "w",
+    [183] = "x",
+    [184] = "y",
+    [185] = "z",
+    [186] = "é",
+    [187] = "'d",
+    [188] = "'l",
+    [189] = "'s",
+    [190] = "'t",
+    [191] = "'v",
+    [192] = "た",
+    [193] = "ち",
+    [194] = "つ",
+    [195] = "て",
+    [196] = "と",
+    [197] = "な",
+    [198] = "に",
+    [199] = "ぬ",
+    [200] = "ね",
+    [201] = "の",
+    [202] = "は",
+    [203] = "ひ",
+    [204] = "ふ",
+    [205] = "へ",
+    [206] = "ほ",
+    [207] = "ま",
+    [208] = "み",
+    [209] = "む",
+    [210] = "め",
+    [211] = "も",
+    [212] = "や",
+    [213] = "ゆ",
+    [214] = "よ",
+    [215] = "ら",
+    [216] = "り",
+    [217] = "る",
+    [218] = "れ",
+    [219] = "ろ",
+    [220] = "わ",
+    [221] = "を",
+    [222] = "ん",
+    [223] = "っ",
+    [224] = "'",
+    [225] = "<PK>",
+    [226] = "<MN>",
+    [227] = "-",
+    [228] = "'r",
+    [229] = "'m",
+    [230] = "?",
+    [231] = "!",
+    [232] = ".",
+    [233] = "ァ",
+    [234] = "ゥ",
+    [235] = "ェ",
+    [236] = "▷",
+    [237] = "▲",
+    [238] = "▼",
+    [239] = "♂",
+    [240] = "<ED>",
+    [241] = "×",
+    [242] = "<DOT>",
+    [243] = "/",
+    [244] = ",",
+    [245] = "♀",
+    [246] = "0",
+    [247] = "1",
+    [248] = "2",
+    [249] = "3",
+    [250] = "4",
+    [251] = "5",
+    [252] = "6",
+    [253] = "7",
+    [254] = "8",
+    [255] = "9",
+  },
+  byToken = {
+    [" "] = 127,
+    ["!"] = 231,
+    ["#"] = 84,
+    ["'"] = 224,
+    ["'d"] = 187,
+    ["'l"] = 188,
+    ["'m"] = 229,
+    ["'r"] = 228,
+    ["'s"] = 189,
+    ["'t"] = 190,
+    ["'v"] = 191,
+    ["("] = 154,
+    [")"] = 155,
+    [","] = 244,
+    ["-"] = 227,
+    ["."] = 232,
+    ["/"] = 243,
+    ["0"] = 246,
+    ["1"] = 247,
+    ["2"] = 248,
+    ["3"] = 249,
+    ["4"] = 250,
+    ["5"] = 251,
+    ["6"] = 252,
+    ["7"] = 253,
+    ["8"] = 254,
+    ["9"] = 255,
+    [":"] = 156,
+    [";"] = 157,
+    ["<BOLD_A>"] = 96,
+    ["<BOLD_B>"] = 97,
+    ["<BOLD_C>"] = 98,
+    ["<BOLD_D>"] = 99,
+    ["<BOLD_E>"] = 100,
+    ["<BOLD_F>"] = 101,
+    ["<BOLD_G>"] = 102,
+    ["<BOLD_H>"] = 103,
+    ["<BOLD_I>"] = 104,
+    ["<BOLD_L>"] = 107,
+    ["<BOLD_M>"] = 108,
+    ["<BOLD_P>"] = 114,
+    ["<BOLD_S>"] = 106,
+    ["<BOLD_V>"] = 105,
+    ["<COLON>"] = 109,
+    ["<CONT>"] = 85,
+    ["<DEXEND>"] = 95,
+    ["<DONE>"] = 87,
+    ["<DOT>"] = 242,
+    ["<ED>"] = 240,
+    ["<ID>"] = 115,
+    ["<LINE>"] = 79,
+    ["<LV>"] = 110,
+    ["<MN>"] = 226,
+    ["<NEXT>"] = 78,
+    ["<NULL>"] = 0,
+    ["<PAGE>"] = 73,
+    ["<PARA>"] = 81,
+    ["<PC>"] = 91,
+    ["<PK>"] = 225,
+    ["<PKMN>"] = 74,
+    ["<PLAYER>"] = 82,
+    ["<PROMPT>"] = 88,
+    ["<RIVAL>"] = 83,
+    ["<ROCKET>"] = 94,
+    ["<SCROLL>"] = 76,
+    ["<TARGET>"] = 89,
+    ["<TM>"] = 92,
+    ["<TRAINER>"] = 93,
+    ["<USER>"] = 90,
+    ["<_CONT>"] = 75,
+    ["<to>"] = 112,
+    ["<……>"] = 86,
+    ["?"] = 230,
+    ["@"] = 80,
+    A = 128,
+    B = 129,
+    C = 130,
+    D = 131,
+    E = 132,
+    F = 133,
+    G = 134,
+    H = 135,
+    I = 136,
+    J = 137,
+    K = 138,
+    L = 139,
+    M = 140,
+    N = 141,
+    O = 142,
+    P = 143,
+    Q = 144,
+    R = 145,
+    S = 146,
+    T = 147,
+    U = 148,
+    V = 149,
+    W = 150,
+    X = 151,
+    Y = 152,
+    Z = 153,
+    ["["] = 158,
+    ["]"] = 159,
+    a = 160,
+    b = 161,
+    c = 162,
+    d = 163,
+    e = 164,
+    f = 165,
+    g = 166,
+    h = 167,
+    i = 168,
+    j = 169,
+    k = 170,
+    l = 171,
+    m = 172,
+    n = 173,
+    o = 174,
+    p = 175,
+    q = 176,
+    r = 177,
+    s = 178,
+    t = 179,
+    u = 180,
+    v = 181,
+    w = 182,
+    x = 183,
+    y = 184,
+    z = 185,
+    ["¥"] = 240,
+    ["·"] = 116,
+    ["×"] = 241,
+    ["é"] = 186,
+    ["‘"] = 112,
+    ["’"] = 113,
+    ["“"] = 114,
+    ["”"] = 115,
+    ["…"] = 117,
+    ["′"] = 96,
+    ["″"] = 97,
+    ["№"] = 116,
+    ["⋯"] = 117,
+    ["─"] = 122,
+    ["│"] = 124,
+    ["┌"] = 121,
+    ["┐"] = 123,
+    ["└"] = 125,
+    ["┘"] = 126,
+    ["▲"] = 237,
+    ["▶"] = 237,
+    ["▷"] = 236,
+    ["▼"] = 238,
+    ["♀"] = 245,
+    ["♂"] = 239,
+    ["　"] = 127,
+    ["。"] = 232,
+    ["「"] = 112,
+    ["」"] = 113,
+    ["『"] = 114,
+    ["』"] = 115,
+    ["ぁ"] = 118,
+    ["あ"] = 177,
+    ["ぃ"] = 110,
+    ["い"] = 178,
+    ["ぅ"] = 111,
+    ["う"] = 179,
+    ["ぇ"] = 119,
+    ["え"] = 180,
+    ["ぉ"] = 120,
+    ["お"] = 181,
+    ["か"] = 182,
+    ["が"] = 38,
+    ["き"] = 183,
+    ["ぎ"] = 39,
+    ["く"] = 184,
+    ["ぐ"] = 40,
+    ["け"] = 185,
+    ["げ"] = 41,
+    ["こ"] = 186,
+    ["ご"] = 42,
+    ["さ"] = 187,
+    ["ざ"] = 43,
+    ["し"] = 188,
+    ["じ"] = 44,
+    ["す"] = 189,
+    ["ず"] = 45,
+    ["せ"] = 190,
+    ["ぜ"] = 46,
+    ["そ"] = 191,
+    ["ぞ"] = 47,
+    ["た"] = 192,
+    ["だ"] = 48,
+    ["ち"] = 193,
+    ["ぢ"] = 49,
+    ["っ"] = 223,
+    ["つ"] = 194,
+    ["づ"] = 50,
+    ["て"] = 195,
+    ["で"] = 51,
+    ["と"] = 196,
+    ["ど"] = 52,
+    ["な"] = 197,
+    ["に"] = 198,
+    ["ぬ"] = 199,
+    ["ね"] = 200,
+    ["の"] = 201,
+    ["は"] = 202,
+    ["ば"] = 58,
+    ["ぱ"] = 68,
+    ["ひ"] = 203,
+    ["び"] = 59,
+    ["ぴ"] = 69,
+    ["ふ"] = 204,
+    ["ぶ"] = 60,
+    ["ぷ"] = 70,
+    ["へ"] = 205,
+    ["べ"] = 61,
+    ["ぺ"] = 71,
+    ["ほ"] = 206,
+    ["ぼ"] = 62,
+    ["ぽ"] = 72,
+    ["ま"] = 207,
+    ["み"] = 208,
+    ["む"] = 209,
+    ["め"] = 210,
+    ["も"] = 211,
+    ["ゃ"] = 224,
+    ["や"] = 212,
+    ["ゅ"] = 225,
+    ["ゆ"] = 213,
+    ["ょ"] = 226,
+    ["よ"] = 214,
+    ["ら"] = 215,
+    ["り"] = 216,
+    ["る"] = 217,
+    ["れ"] = 218,
+    ["ろ"] = 219,
+    ["わ"] = 220,
+    ["を"] = 221,
+    ["ん"] = 222,
+    ["ァ"] = 233,
+    ["ア"] = 128,
+    ["ィ"] = 176,
+    ["イ"] = 129,
+    ["ゥ"] = 234,
+    ["ウ"] = 130,
+    ["ェ"] = 235,
+    ["エ"] = 131,
+    ["ォ"] = 244,
+    ["オ"] = 132,
+    ["カ"] = 133,
+    ["ガ"] = 5,
+    ["キ"] = 134,
+    ["ギ"] = 6,
+    ["ク"] = 135,
+    ["グ"] = 7,
+    ["ケ"] = 136,
+    ["ゲ"] = 8,
+    ["コ"] = 137,
+    ["ゴ"] = 9,
+    ["サ"] = 138,
+    ["ザ"] = 10,
+    ["シ"] = 139,
+    ["ジ"] = 11,
+    ["ス"] = 140,
+    ["ズ"] = 12,
+    ["セ"] = 141,
+    ["ゼ"] = 13,
+    ["ソ"] = 142,
+    ["ゾ"] = 14,
+    ["タ"] = 143,
+    ["ダ"] = 15,
+    ["チ"] = 144,
+    ["ヂ"] = 16,
+    ["ッ"] = 172,
+    ["ツ"] = 145,
+    ["ヅ"] = 17,
+    ["テ"] = 146,
+    ["デ"] = 18,
+    ["ト"] = 147,
+    ["ド"] = 19,
+    ["ナ"] = 148,
+    ["ニ"] = 149,
+    ["ヌ"] = 150,
+    ["ネ"] = 151,
+    ["ノ"] = 152,
+    ["ハ"] = 153,
+    ["バ"] = 25,
+    ["パ"] = 64,
+    ["ヒ"] = 154,
+    ["ビ"] = 26,
+    ["ピ"] = 65,
+    ["フ"] = 155,
+    ["ブ"] = 27,
+    ["プ"] = 66,
+    ["ホ"] = 156,
+    ["ボ"] = 28,
+    ["ポ"] = 67,
+    ["マ"] = 157,
+    ["ミ"] = 158,
+    ["ム"] = 159,
+    ["メ"] = 160,
+    ["モ"] = 161,
+    ["ャ"] = 173,
+    ["ヤ"] = 162,
+    ["ュ"] = 174,
+    ["ユ"] = 163,
+    ["ョ"] = 175,
+    ["ヨ"] = 164,
+    ["ラ"] = 165,
+    ["ル"] = 166,
+    ["レ"] = 167,
+    ["ロ"] = 168,
+    ["ワ"] = 169,
+    ["ヲ"] = 170,
+    ["ン"] = 171,
+    ["ー"] = 227,
+    ["円"] = 240,
+    ["！"] = 231,
+    ["．"] = 242,
+    ["／"] = 243,
+    ["０"] = 246,
+    ["１"] = 247,
+    ["２"] = 248,
+    ["３"] = 249,
+    ["４"] = 250,
+    ["５"] = 251,
+    ["６"] = 252,
+    ["７"] = 253,
+    ["８"] = 254,
+    ["９"] = 255,
+    ["？"] = 230,
+    ["ﾞ"] = 229,
+    ["ﾟ"] = 228,
+  },
+  source = "pokered constants/charmap.asm",
+}

src/script/Commands.lua

@@ -261,7 +261,9 @@ function Commands.move_player(ctx, dir, tiles)
 end
 
 function Commands.move_npc(ctx, objIndex, dir, tiles)
-  local npc = ctx.overworld:npcByIndex(objIndex)
+  local ow = ctx.overworld
+  if not ow then return end
+  local npc = ow:npcByIndex(objIndex)
   if npc then walkEntity(ctx, npc, dir, tiles) end
 end
 
@@ -308,6 +310,7 @@ end
 
 function Commands.move_npc_to(ctx, objIndex, tx, ty)
   local ow = ctx.overworld
+  if not ow then return end
   local npc = ow:npcByIndex(objIndex)
   if not npc then return end
   local path = bfsPath(ow.map, npc.cellX, npc.cellY, tx, ty, ow.entities, npc)
@@ -339,6 +342,20 @@ function Commands.face_object(ctx, objIndex, dir)
   if npc then npc.facing = dir end
 end
 
+-- Instantly relocate an NPC (OaksLabCalcRivalMovementScript / SetSpritePosition1).
+-- facing is optional.  Headless-safe no-op without an overworld.
+function Commands.place_npc(ctx, objIndex, x, y, facing)
+  local ow = ctx.overworld
+  if not ow then return end
+  local npc = ow:npcByIndex(objIndex)
+  if not npc then return end
+  npc.cellX, npc.cellY = x, y
+  npc.px, npc.py = x * 16, y * 16
+  npc.moving = false
+  npc.targetX, npc.targetY = nil, nil
+  if facing then npc.facing = facing end
+end
+
 function Commands.face_npc(ctx)
   -- make the player face the talking NPC
   if ctx.npc and ctx.overworld then
@@ -485,7 +502,7 @@ function Commands.heal_party(ctx)
 end
 
 -- AskName (engine/menus/naming_screen.asm): yes/no then NamingScreen.
--- AddPartyMon only offers this for party mons (box deposits skip it).
+-- AddPartyMon and SendNewMonToBox both offer this.
 -- Preserves ctx.lastCheck so GivePokemon's carry is not clobbered by the
 -- yes/no result (scripts jump_if_false on give failure afterwards).
 local function askNickname(ctx, mon)
@@ -527,8 +544,9 @@ end
 -- the asm's carry: true when the mon was given, false when both the
 -- party and every box are full (that .boxFull path leaves the giver's
 -- script able to offer again later, e.g. the Celadon Eevee ball).
--- Party adds run AskName (AddPartyMon) when a script runner is present;
--- mods that pre-set gift.nickname skip the prompt.
+-- AskName runs for party (AddPartyMon) and box (SendNewMonToBox) when a
+-- script runner is present; mods that pre-set gift.nickname skip it.
+-- Box deposits also print SentToBoxText (give_pokemon.asm:36-37).
 function Commands.give_pokemon(ctx, species, level)
   -- Native mods can transform a gift before the Pokémon object is created.
   -- This is intentionally an event rather than a special-case starter hook:
@@ -540,14 +558,17 @@ function Commands.give_pokemon(ctx, species, level)
   end
   local Pokemon = require("src.pokemon.Pokemon")
   local Party = require("src.pokemon.Party")
+  local Boxes = require("src.pokemon.Boxes")
   local mon = Pokemon.new(ctx.game.data, species, level)
   if gift.nickname then mon.nickname = gift.nickname end
   ctx.game.stringBuffer = ctx.game.data.pokemon[species].name or species
   ctx.pendingPokemonName = species
   require("src.battle.BattleState").stampOT(ctx.save, mon)
   local addedToParty = Party.add(ctx.save.party, mon)
+  local boxNum = nil
   if not addedToParty then
-    if not require("src.pokemon.Boxes").deposit(ctx.save, mon) then
+    boxNum = Boxes.deposit(ctx.save, mon)
+    if not boxNum then
       ctx.lastCheck = false
       return
     end
@@ -558,11 +579,30 @@ function Commands.give_pokemon(ctx, species, level)
     dex.owned[species] = true
   end
   ctx.lastCheck = true
-  -- AddPartyMon AskName: party only; skip box deposits, mod-set nicknames,
-  -- and callback-style callers that have no script runner to yield on.
-  if addedToParty and not gift.nickname and ctx.runner then
+  ctx.addedToParty = addedToParty
+  ctx.boxNum = boxNum
+  -- AskName: both AddPartyMon and SendNewMonToBox; skip mod-set nicks
+  -- and callback-style callers with no script runner to yield on.
+  if not gift.nickname and ctx.runner then
     askNickname(ctx, mon)
   end
+  if boxNum then
+    local name = mon.nickname
+      or (ctx.game.data.pokemon[species] and ctx.game.data.pokemon[species].name)
+      or species
+    ctx.game.boxMonNicks = name
+    ctx.game.stringBuffer = tostring(boxNum)
+    if ctx.runner then
+      Commands.show_text(ctx, "_SentToBoxText")
+    else
+      local TextBox = require("src.render.TextBox")
+      local raw = ctx.game.data.text and ctx.game.data.text._SentToBoxText
+      ctx.game.stack:push(TextBox.new(ctx.game, raw or (
+        "There's no more\nroom for POKéMON!\v" .. name
+        .. " was\vsent to POKéMON\vBOX " .. boxNum .. " on PC!"),
+        function() end))
+    end
+  end
 end
 
 function Commands.give_money(ctx, amount)
@@ -783,6 +823,8 @@ function Commands.trade(ctx, tradeIndex, doneFlag)
   local newMon = Pokemon.new(data, trade.get, sent.level)
   newMon.nickname = trade.nickname
   newMon.traded = true -- boosted exp + Name Rater refusal (different OT)
+  newMon.ot = "TRAINER" -- InGameTrade_TrainerString
+  newMon.otId = (love.math and love.math.random or math.random)(0, 65535)
   table.remove(party, slot)
   table.insert(party, newMon)
   local dex = ctx.save.pokedex
@@ -790,9 +832,13 @@ function Commands.trade(ctx, tradeIndex, doneFlag)
     dex.seen[trade.get] = true
     dex.owned[trade.get] = true
   end
-  -- the trade machine animation (engine/movie/trade.asm)
+  -- InternalClockTradeAnim (engine/movie/trade.asm)
   Screens.push(ctx.game, "TradeAnim", {
     sent = sent, received = newMon,
+    enemyName = "TRAINER",
+    playerOt = ctx.save.player.name,
+    playerOtId = sent.otId or ctx.save.player.id,
+    enemyOtId = newMon.otId,
     onDone = function() runner:resume() end,
   })
   runner:yield()

src/ui/BagMenu.lua

@@ -214,11 +214,10 @@ local function useOn(game, battle, id, target, list, moveIndex)
        and ow.map.id ~= "AGATHAS_ROOM" then
       list:close()
       consume(game, id)
-      require("src.core.Sound").play(game.data, "Teleport_Exit1")
-      ow.player.surfing = false
-      -- EnterMapAnim on arrival (BIT_ESCAPE_WARP / special warp path);
-      -- blackouts omit arrive="teleport" (HandleBlackOut has no LeaveMapAnim)
-      ow:warpToHealPoint(nil, { arrive = "teleport" })
+      -- LeaveMapAnim spin-up + SFX_TELEPORT_EXIT_1, a fade, then land OUTSIDE
+      -- the last Pokémon Center town door like Fly (#196), via the shared
+      -- departure helper -- the same path Dig/Teleport take from the party menu
+      ow:beginTeleportOut()
     else
       showMessages(game, { "OAK: " .. game.save.player.name
         .. "!\nThis isn't the\ntime to use that!" })
@@ -303,7 +302,8 @@ local function pickTargetAndUse(game, battle, id, list)
   -- the ETHERs and PP UP open the move menu after picking a mon
   -- (ItemUsePPRestore / ItemUsePPUp); the ELIXERs hit every move
   local wantsMove = id == "ETHER" or id == "MAX_ETHER" or id == "PP_UP"
-  require("src.ui.Screens").push(game, "PartyMenu", {
+  local def = game.data.items[id]
+  local opts = {
     pickOnly = true,
     onSwitch = function(mon)
       if not wantsMove then
@@ -326,11 +326,27 @@ local function pickTargetAndUse(game, battle, id, list)
         end,
       }))
     end,
-  })
+  }
+  -- TM/HM: open the party menu in Gen 1's TM/HM display mode so each mon
+  -- shows ABLE / NOT ABLE from its learnset and the prompt reads "Use TM on
+  -- which POKeMON?" (engine/items/item_effects.asm ItemUseTMHM ->
+  -- party_menu.asm TM/HM type). Stones and other pickOnly items keep the
+  -- plain HP layout (Gen 1 shows no ABLE/NOT ABLE for them), so gate
+  -- strictly on def.machine. #210
+  if def and def.machine then
+    opts.tmhm = { move = def.machine.move, kind = def.machine.kind }
+  end
+  require("src.ui.Screens").push(game, "PartyMenu", opts)
 end
 
 local function useItem(game, battle, id, list)
   local def = game.data.items[id]
+  -- ItemUseTMHM checks wIsInBattle before BootedUpTMText
+  if battle and def and def.machine then
+    local _, payload = ItemEffects.use(game.data, game.save, id, nil, battle)
+    showMessages(game, payload)
+    return
+  end
   if ItemEffects.needsTarget(id, def) and not ItemEffects.isBall(id) then
     -- TMs/HMs boot up and announce their move before the target picker
     -- (ItemUseTMHM: BootedUpTMText / BootedUpHMText + TeachMachineMoveText)

src/ui/BoxMenu.lua

@@ -3,9 +3,11 @@
 -- plus CHANGE BOX.
 
 local Boxes = require("src.pokemon.Boxes")
+local Font = require("src.render.Font")
 local ListMenu = require("src.ui.ListMenu")
 local Menu = require("src.ui.Menu")
 local Party = require("src.pokemon.Party")
+local TextBox = require("src.render.TextBox")
 
 local BoxMenu = {}
 
@@ -14,6 +16,11 @@ local function monLabel(game, mon)
   return ("%s :L%d"):format(mon.nickname or def.name, mon.level)
 end
 
+local function monName(game, mon)
+  local def = game.data.pokemon[mon.species]
+  return mon.nickname or def.name
+end
+
 -- Per-mon submenu (bills_pc.asm DisplayDepositWithdrawMenu): the chosen
 -- action + STATS + CANCEL.  STATS shows the status screen and returns
 -- here; CANCEL/B goes back to the list.
@@ -31,8 +38,26 @@ local function monSubmenu(game, action, mon, onAction)
   }, { tx = 9, ty = 10, tw = 11, th = 8, noSound = true }))
 end
 
+-- After a successful transfer: close the mon list (BoxMenu stays beneath
+-- via keepOpen) and show the taken-out / stored text (jp BillsPCMenu).
+local function afterTransfer(game, list, text)
+  list:close()
+  game.stack:push(TextBox.new(game, text))
+end
+
 local function withdraw(game)
   local box = Boxes.active(game.save)
+  local t = game.data.text
+  if #box == 0 then
+    game.stack:push(TextBox.new(game, t._NoMonText
+      or "What? There are\nno POKéMON here!"))
+    return
+  end
+  if #game.save.party >= Party.MAX then
+    game.stack:push(TextBox.new(game, t._CantTakeMonText
+      or "You can't take\nany more POKéMON.\fDeposit POKéMON\nfirst."))
+    return
+  end
   local items = {}
   for i, mon in ipairs(box) do
     table.insert(items, { label = monLabel(game, mon), value = i })
@@ -49,13 +74,29 @@ local function withdraw(game)
         end
         table.remove(box, item.value)
         table.insert(game.save.party, mon)
-        list:close()
+        local name = monName(game, mon)
+        game.stringBuffer = name
+        require("src.core.Sound").playCry(game.data, mon.species)
+        afterTransfer(game, list, t._MonIsTakenOutText
+          or (name .. " is\ntaken out.\vGot " .. name .. "."))
       end)
     end,
   }))
 end
 
 local function deposit(game)
+  local t = game.data.text
+  if #game.save.party <= 1 then
+    game.stack:push(TextBox.new(game, t._CantDepositLastMonText
+      or "You can't deposit\nthe last POKéMON!"))
+    return
+  end
+  local box = Boxes.active(game.save)
+  if #box >= Boxes.CAPACITY then
+    game.stack:push(TextBox.new(game, t._BoxFullText
+      or "Oops! This Box is\nfull of POKéMON."))
+    return
+  end
   local items = {}
   for i, mon in ipairs(game.save.party) do
     table.insert(items, { label = monLabel(game, mon), value = i })
@@ -69,40 +110,50 @@ local function deposit(game)
           list.footer = "You need at least\none POKéMON!"
           return
         end
-        local box = Boxes.active(game.save)
-        if #box >= Boxes.CAPACITY then
+        local active = Boxes.active(game.save)
+        if #active >= Boxes.CAPACITY then
           list.footer = ("BOX %d is full!"):format(game.save.currentBox)
           return
         end
         table.remove(game.save.party, item.value)
-        table.insert(box, mon)
-        list:close()
+        table.insert(active, mon)
+        local name = monName(game, mon)
+        game.stringBuffer = name
+        game.boxNumString = tostring(game.save.currentBox)
+        require("src.core.Sound").playCry(game.data, mon.species)
+        afterTransfer(game, list, t._MonWasStoredText
+          or (name .. " was\nstored in Box " .. game.boxNumString .. "."))
       end)
     end,
   }))
 end
 
--- RELEASE POKéMON (bills_pc.asm .release): confirm, then "Bye [MON]!"
+-- RELEASE POKéMON (bills_pc.asm BillsPCRelease): confirm, then "Bye [MON]!".
+-- Index by list.index (not stale item.value) after removeCurrent (#171).
 local function release(game)
   local box = Boxes.active(game.save)
+  local t = game.data.text
+  if #box == 0 then
+    game.stack:push(TextBox.new(game, t._NoMonText
+      or "What? There are\nno POKéMON here!"))
+    return
+  end
   local items = {}
   for i, mon in ipairs(box) do
     table.insert(items, { label = monLabel(game, mon), value = i })
   end
   game.stack:push(ListMenu.new(game,
     ("BOX %d (RELEASE)"):format(game.save.currentBox), items, {
-    onChoose = function(item, list)
-      local mon = box[item.value]
+    onChoose = function(_, list)
+      local mon = box[list.index]
       if not mon then return end
-      local def = game.data.pokemon[mon.species]
-      local name = mon.nickname or def.name
+      local name = monName(game, mon)
       local ChoiceBox = require("src.ui.ChoiceBox")
-      local TextBox = require("src.render.TextBox")
       game.stack:push(TextBox.new(game,
         "Once released,\n" .. name .. " is\ngone forever. OK?", function()
         game.stack:push(ChoiceBox.new(game, function(yes)
           if not yes then return end
-          table.remove(box, item.value)
+          table.remove(box, list.index)
           require("src.core.Sound").playCry(game.data, mon.species)
           game.stack:push(TextBox.new(game,
             ("%s was\nreleased outside.\fBye %s!"):format(name, name)))
@@ -129,7 +180,6 @@ local function changeBox(game)
       -- the original asks BEFORE switching ("When you change a #MON
       -- BOX, data will be saved. OK?"); declining aborts the change
       local ChoiceBox = require("src.ui.ChoiceBox")
-      local TextBox = require("src.render.TextBox")
       game.stack:push(TextBox.new(game,
         "When you change a\nPOKéMON BOX, data\nwill be saved. OK?", function()
         game.stack:push(ChoiceBox.new(game, function(yes)
@@ -143,21 +193,48 @@ local function changeBox(game)
   }))
 end
 
+-- bills_pc.asm BillsPCMenu chrome: What? text box + BOX No. overlay
+local function drawChrome(game)
+  Font.drawBox(0, 12, 20, 6)
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw("What?", 8, 112)
+  Font.drawBox(9, 14, 11, 4)
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw("BOX No.", 80, 128)
+  local n = game.save.currentBox or 1
+  if n >= 10 then
+    Font.draw(tostring(n), 136, 128)
+  else
+    Font.draw(tostring(n), 144, 128)
+  end
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
 function BoxMenu.new(game)
   Boxes.ensure(game.save)
   -- bills_pc.asm BillsPCMenu: TextBoxBorder at (0,0) with interior
-  -- 12x10 → total 14x12.  "CHANGE BOX" is 10 tiles and needs the
-  -- full interior (cursor col + label); the old tw=12 right-side box
-  -- drew the final glyph on the border.
-  return Menu.new(game, {
-    { label = "WITHDRAW", onSelect = function() withdraw(game) end },
-    { label = "DEPOSIT", onSelect = function() deposit(game) end },
-    { label = "RELEASE", onSelect = function() release(game) end },
-    { label = "CHANGE BOX", onSelect = function() changeBox(game) end },
+  -- 12x10 → total 14x12.  "CHANGE BOX" / "WITHDRAW <PK><MN>" need the
+  -- full interior (cursor col + label).  keepOpen so WITHDRAW/DEPOSIT/
+  -- RELEASE/CHANGE BOX leave this menu underneath (jp BillsPCMenu).
+  local menu = Menu.new(game, {
+    { label = "WITHDRAW <PK><MN>", keepOpen = true,
+      onSelect = function() withdraw(game) end },
+    { label = "DEPOSIT <PK><MN>", keepOpen = true,
+      onSelect = function() deposit(game) end },
+    { label = "RELEASE <PK><MN>", keepOpen = true,
+      onSelect = function() release(game) end },
+    { label = "CHANGE BOX", keepOpen = true,
+      onSelect = function() changeBox(game) end },
     { label = "SEE YA!" },
     -- Bill's PC runs silent end to end (BIT_NO_MENU_BUTTON_SOUND,
     -- engine/menus/pokemon_pc.asm)
   }, { tx = 0, ty = 0, tw = 14, th = 12, noSound = true })
+  local baseDraw = menu.draw
+  function menu:draw()
+    baseDraw(self)
+    drawChrome(game)
+  end
+  return menu
 end
 
 return BoxMenu

src/ui/ChoiceBox.lua

@@ -1,4 +1,4 @@
--- YES/NO choice box (top-left of the text box area, like the original).
+-- YES/NO choice box (InitYesNoTextBoxParameters: above the text box, right).
 
 local Font = require("src.render.Font")
 local Theme = require("src.ui.Theme")
@@ -14,6 +14,11 @@ function ChoiceBox.new(game, onChoose, opts)
   self.index = (opts and opts.defaultNo) and 2 or 1
   -- BIT_NO_MENU_BUTTON_SOUND: PC-session prompts stay silent
   self.noSound = (opts and opts.noSound) or false
+  local box = Theme.choiceBox
+  self.tx = (opts and opts.tx) or box.tx
+  self.ty = (opts and opts.ty) or box.ty
+  self.tw = (opts and opts.tw) or box.tw
+  self.th = (opts and opts.th) or box.th
   return self
 end
 
@@ -38,13 +43,13 @@ function ChoiceBox:update(dt)
 end
 
 function ChoiceBox:draw()
-  local box = Theme.choiceBox
-  Font.drawBox(box.tx, box.ty, box.tw, box.th)
+  local tx, ty, tw, th = self.tx, self.ty, self.tw, self.th
+  Font.drawBox(tx, ty, tw, th)
   love.graphics.setColor(0, 0, 0, 1)
-  Font.draw("YES", (box.tx + 2) * 8, (box.ty + 1) * 8)
-  Font.draw("NO", (box.tx + 2) * 8, (box.ty + 3) * 8)
-  Font.drawCode(Theme.cursor, (box.tx + 1) * 8,
-                (box.ty + (self.index == 1 and 1 or 3)) * 8)
+  Font.draw("YES", (tx + 2) * 8, (ty + 1) * 8)
+  Font.draw("NO", (tx + 2) * 8, (ty + 3) * 8)
+  Font.drawCode(Theme.cursor, (tx + 1) * 8,
+                (ty + (self.index == 1 and 1 or 3)) * 8)
   love.graphics.setColor(1, 1, 1, 1)
 end
 

src/ui/EvolutionState.lua

@@ -1,8 +1,11 @@
 -- The evolution movie (engine/movie/evolution.asm): the mon's pic
 -- flashes back and forth with the evolved form, speeding up, then the
 -- new form appears with its cry and the congratulations text.
--- B during the flash cancels ("Huh? ... stopped evolving!"? -- Gen 1
--- has no cancel; the flash always completes).
+-- pokered engine/pokemon/evos_moves.asm (EvolveMon) polls hJoyHeld during
+-- the flash: holding B aborts the evolution -- the mon keeps its species
+-- and _StoppedEvolvingText ("Huh? MON stopped evolving!") prints.  The
+-- lone exception is trade evolutions (wLinkState == LINK_STATE_TRADING),
+-- which skip that poll and cannot be cancelled (#213).
 
 local Font = require("src.render.Font")
 local Music = require("src.core.Music")
@@ -14,7 +17,10 @@ EvolutionState.isOpaque = true
 -- SGB: SetPal_PokemonWholeScreen for the mon on display
 function EvolutionState:sgbPalettes(game)
   local P = require("src.render.PaletteFX")
-  local species = self.done and self.newSpecies or self.mon.species
+  -- a cancelled evolution keeps the old species (never applied), so only
+  -- colorize with the new form once it has actually evolved
+  local species = (self.done and not self.canceled) and self.newSpecies
+    or self.mon.species
   local c = P.monPal(game.data, species)
   if c then return { P.whole(c) } end
   return P.wholeNamed(game.data, "MEWMON")
@@ -29,17 +35,22 @@ local function frontSprite(game, species)
   return ok and img or nil
 end
 
-function EvolutionState.new(game, mon, newSpecies, onDone)
+function EvolutionState.new(game, mon, newSpecies, onDone, via)
   local self = setmetatable({}, EvolutionState)
   self.game = game
   self.mon = mon
   self.newSpecies = newSpecies
   self.onDone = onDone
+  self.via = via
+  -- evos_moves.asm: only trade evolutions (LINK_STATE_TRADING) skip the
+  -- B-cancel poll; level-up, stone and rare-candy evos are all cancelable.
+  self.cancelable = (via ~= "TRADE")
   self.oldName = mon.nickname or game.data.pokemon[mon.species].name
   self.oldSprite = frontSprite(game, mon.species)
   self.newSprite = frontSprite(game, newSpecies)
   self.t = 0
   self.done = false
+  self.canceled = false
   Music.play(game.data, Music.special(game.data, "evolution"))
   return self
 end
@@ -47,11 +58,28 @@ end
 function EvolutionState:update(dt)
   self.t = self.t + 1
   if self.done then return end
+  local game = self.game
+  -- evos_moves.asm EvolveMon: each flash iteration polls hJoyHeld and, for
+  -- a cancelable evolution, aborts when B is held -- the mon keeps its
+  -- species (Evolution.apply never runs) and _StoppedEvolvingText prints.
+  if self.cancelable and game.input:isDown("b") then
+    self.done = true
+    self.canceled = true
+    local TextBox = require("src.render.TextBox")
+    -- mirrors data/generated/text.lua _StoppedEvolvingText
+    game.stack:push(TextBox.new(game,
+      ("Huh? %s\nstopped evolving!"):format(self.oldName),
+      function()
+        Music.restoreMap(game.data)
+        game.stack:pop() -- the evolution screen itself
+        if self.onDone then self.onDone() end
+      end))
+    return
+  end
   if self.t >= FLASH_FRAMES then
     self.done = true
-    local game = self.game
     local Evolution = require("src.pokemon.Evolution")
-    Evolution.apply(game, self.mon, self.newSpecies)
+    Evolution.apply(game, self.mon, self.newSpecies, self.via)
     require("src.core.Sound").playCry(game.data, self.newSpecies)
     local TextBox = require("src.render.TextBox")
     local newName = game.data.pokemon[self.newSpecies].name
@@ -61,7 +89,12 @@ function EvolutionState:update(dt)
       function()
         Music.restoreMap(game.data)
         game.stack:pop() -- the evolution screen itself
-        if self.onDone then self.onDone() end
+        -- Gen1 re-runs the level-up learn check on the evolved species
+        -- after the "evolved into" text (evos_moves.asm EvolveMon ->
+        -- learn_move.asm LearnMoveFromLevelUp, #12).  Pop the evo screen
+        -- first so the "learned MOVE!" text / forget prompt push onto the
+        -- overworld / battle-return, not this state.
+        Evolution.learnEvolutionMoves(game, self.mon, self.onDone)
       end))
   end
 end
@@ -73,7 +106,8 @@ function EvolutionState:draw()
   -- accelerating flash between the two forms
   local sprite
   if self.done then
-    sprite = self.newSprite
+    -- a cancelled evolution settles back on the original form
+    sprite = self.canceled and self.oldSprite or self.newSprite
   else
     local period = math.max(4, 28 - math.floor(self.t / 40) * 6)
     local showNew = math.floor(self.t / period) % 2 == 1

src/ui/FlyMenu.lua

@@ -11,9 +11,13 @@ function FlyMenu.new(game)
   local visited = game.save.visited or {}
   local seen = {}
   for _, mapId in ipairs(game.data.field.flyOrder or {}) do
-    -- towns only (dungeon escape spots share the table), each listed once
+    -- towns only (dungeon escape spots share the table), each listed once.
+    -- Indigo Plateau (tileset PLATEAU) is a valid Fly destination too, so allow
+    -- it past the OVERWORLD-only isOutdoor gate while the CAVERN/FACILITY escape
+    -- spots stay excluded (LoadTownMap_Fly cycles it like any town, #203).
     local def = game.data.maps[mapId]
-    if visited[mapId] and def and Map.isOutdoor(def) and not seen[mapId] then
+    if visited[mapId] and def and not seen[mapId]
+       and (Map.isOutdoor(def) or def.tileset == "PLATEAU") then
       seen[mapId] = true
       table.insert(items, {
         value = mapId,

src/ui/ListMenu.lua

@@ -37,8 +37,12 @@ function ListMenu.new(game, title, items, opts)
   -- text box, a money box sits top-right, and the list shortens to
   -- clear them (DisplayPokemartDialogue_'s screen)
   self.dialogue = opts.dialogue
+  -- PC item lists (players_pc.asm): PrintListMenuEntries shows 4 names
+  -- and PrintText footers ("How many?", stored/withdrew) use the standard
+  -- bottom text box — same row budget as the mart, without the money box.
+  self.messageBox = opts.messageBox
   self.money = opts.money          -- () -> current money for the box
-  self.rows = opts.dialogue and 4 or ROWS
+  self.rows = opts.rows or ((opts.dialogue or opts.messageBox) and 4 or ROWS)
   return self
 end
 
@@ -137,8 +141,10 @@ function ListMenu:draw()
     love.graphics.setColor(0, 0, 0, 1)
     local money = ("¥%d"):format(self.money and self.money() or 0)
     Font.draw(money, 152 - Font.width(money), 8)
-    -- the clerk's line in the standard bottom text box; long prompts
-    -- wrap and keep their last two lines, like the GB's scrolled box
+  end
+  if self.dialogue or (self.messageBox and self.footer) then
+    -- standard bottom text box (PrintText); long prompts wrap and keep
+    -- their last two lines, like the GB's scrolled box (#115/#174)
     Font.drawBox(0, 12, 20, 6)
     love.graphics.setColor(0, 0, 0, 1)
     if self.footer then
@@ -153,8 +159,7 @@ function ListMenu:draw()
       end
     end
   elseif self.footer then
-    -- PC deposit/withdraw footers use "\n"; draw the last two lines so
-    -- long item names are not clipped at the screen edge (#115).
+    -- bare footer (bag money line, etc.)
     local flat = {}
     for _, page in ipairs(require("src.render.TextBox").paginate(self.footer)) do
       for _, line in ipairs(page) do flat[#flat + 1] = line end

src/ui/MoveLearnMenu.lua

@@ -22,6 +22,8 @@ function MoveLearnMenu.new(game, mon, newMoveId, onDone)
   self.newMoveId = newMoveId
   self.onDone = onDone
   self.index = 1
+  -- forget-list UI only after TryingToLearn YES (learn_move.asm .loop)
+  self.selecting = false
   return self
 end
 
@@ -31,24 +33,32 @@ end
 
 -- TryingToLearnText + yes/no (learn_move.asm TryingToLearn): NO offers
 -- AbandonLearning, whose own NO loops back here (DontAbandonLearning).
+-- Use TextBox opts.choice so YES/NO overlays the still-visible prompt;
+-- pushing ChoiceBox from onDone pops the text first and leaves YES/NO
+-- on "Which move should be forgotten?" (#173).
 function MoveLearnMenu:enter()
   local TextBox = require("src.render.TextBox")
-  local ChoiceBox = require("src.ui.ChoiceBox")
   local game = self.game
   local mdef = game.data.moves[self.newMoveId]
   local name = self:monName()
+  self.selecting = false
   game.stack:push(TextBox.new(game,
     ("%s is\ntrying to learn\v%s!\fBut, %s\ncan't learn more\vthan 4 moves!\f")
       :format(name, mdef.name, name) ..
     ("Delete an older\nmove to make room\vfor %s?"):format(mdef.name),
-    function()
-      game.stack:push(ChoiceBox.new(game, function(yes)
-        if not yes then self:confirmAbandon() end
-      end))
-    end))
+    nil, {
+      choice = function(yes)
+        if yes then
+          self.selecting = true
+        else
+          self:confirmAbandon()
+        end
+      end,
+    }))
 end
 
 function MoveLearnMenu:update(dt)
+  if not self.selecting then return end
   local input = self.game.input
   local n = #self.mon.moves + 1 -- moves + CANCEL
   if input:wasPressed("up") then
@@ -82,15 +92,15 @@ end
 -- (DontAbandonLearning)
 function MoveLearnMenu:confirmAbandon()
   local TextBox = require("src.render.TextBox")
-  local ChoiceBox = require("src.ui.ChoiceBox")
   local game = self.game
   local mdef = game.data.moves[self.newMoveId]
+  self.selecting = false
   game.stack:push(TextBox.new(game,
-    ("Abandon learning\n%s?"):format(mdef.name), function()
-    game.stack:push(ChoiceBox.new(game, function(yes)
-      if yes then self:finish(false) else self:enter() end
-    end))
-  end))
+    ("Abandon learning\n%s?"):format(mdef.name), nil, {
+      choice = function(yes)
+        if yes then self:finish(false) else self:enter() end
+      end,
+    }))
 end
 
 function MoveLearnMenu:finish(learned)
@@ -98,6 +108,7 @@ function MoveLearnMenu:finish(learned)
   local game = self.game
   local name = self:monName()
   local mdef = game.data.moves[self.newMoveId]
+  self.selecting = false
   game.stack:pop()
   local msg
   if learned then
@@ -114,6 +125,7 @@ function MoveLearnMenu:finish(learned)
 end
 
 function MoveLearnMenu:draw()
+  if not self.selecting then return end
   -- single-spaced move list box (TryingToLearn: TextBoxBorder at 4,7)
   -- plus the port's extra CANCEL row
   Font.drawBox(4, 5, 16, 7)

src/ui/OptionsMenu.lua

@@ -10,6 +10,7 @@
 -- bottom line like pokered's.
 
 local PaletteFX = require("src.render.PaletteFX")
+local Pipelines = require("src.render.Pipelines")
 local Tilt = require("src.render.Tilt")
 local GBCFX = require("src.render.GBCFX")
 local Zoom = require("src.render.Zoom")
@@ -193,6 +194,15 @@ local function buildRows(game)
         local o = g.save.options
         o.tilt = wrapIndex((o.tilt or 0) + dir, 4)
         Tilt.setLevel(o.tilt)
+        -- tilt and a mod's world pipeline are two answers to the same
+        -- question; turning this on switches that off (Pipelines does the
+        -- same in the other direction)
+        if o.tilt > 0 then
+          for _, entry in ipairs(Pipelines.list()) do
+            if entry.def.drawWorld then Pipelines.setLevel(entry.id, 0) end
+          end
+          Pipelines.syncOptions(o)
+        end
         return true
       end },
     { id = "gbcfx", label = "GBC FX",
@@ -295,6 +305,26 @@ local function buildRows(game)
     end
     rows = filtered
   end
+  -- A mod's render pipelines are display modes like TILT, so their rows sit
+  -- with it rather than at the end of the list where a mod's own
+  -- ui.options.rows additions land.  Nothing registered means nothing
+  -- spliced, so a vanilla install sees the list it always had.
+  local pipelineRows = Pipelines.rows(game)
+  if pipelineRows[1] then
+    local merged = {}
+    for _, row in ipairs(rows) do
+      merged[#merged + 1] = row
+      if row.id == "tilt" then
+        for _, extra in ipairs(pipelineRows) do merged[#merged + 1] = extra end
+      end
+    end
+    -- no TILT row to anchor to (a future build could drop it): append
+    -- rather than silently lose the modes
+    if #merged == #rows then
+      for _, extra in ipairs(pipelineRows) do merged[#merged + 1] = extra end
+    end
+    rows = merged
+  end
   return rows
 end
 

src/ui/PartyMenu.lua

@@ -1,11 +1,15 @@
 -- Party menu: list the party, choose a member.
 -- Modes:
---   default: A -> submenu (STATS / SWITCH order / CANCEL)
---   opts.onSwitch: A -> hand the chosen mon to the callback (battle
---                  switch, item targeting via opts.pickOnly)
+--   default: A -> submenu (STATS / SWITCH / field moves)
+--   opts.onSwitch + opts.battle (voluntary PKMN): A -> SWITCH / STATS /
+--     CANCEL (core.asm PartyMenuOrRockOrRun), then onSwitch on SWITCH
+--   opts.onSwitch + opts.forceSwitch: A -> onSwitch immediately
+--     (ChooseNextMon / SHIFT free-switch)
+--   opts.pickOnly + opts.onSwitch: A -> onSwitch (item / script target)
 --   opts.onCancel: fired when the menu closes without a pick (B)
 -- Pops itself on B.
 
+local Assets = require("src.render.Assets")
 local Font = require("src.render.Font")
 local Logger = require("src.core.Logger")
 local Runtime = require("src.mods.Runtime")
@@ -93,7 +97,10 @@ local function drawIcon(game, mon, x, y, selected, counter)
   end
   if not path then return end
   if iconImages[path] == nil then
-    local ok, img = pcall(love.graphics.newImage, path)
+    -- resolve through Assets so an overrides/ or transform-derived icon
+    -- (e.g. a per-species image at assets/generated/icons/<name>.png) is
+    -- picked up the same way battle sprites are
+    local ok, img = pcall(love.graphics.newImage, Assets.resolve(path))
     iconImages[path] = ok and img or false
   end
   local img = iconImages[path]
@@ -125,6 +132,11 @@ function PartyMenu.new(game, opts)
   self.onSwitch = opts.onSwitch
   self.onCancel = opts.onCancel
   self.pickOnly = opts.pickOnly
+  -- TM/HM teaching: opts.tmhm = { move, kind } switches the list to Gen 1's
+  -- TM/HM display (ABLE / NOT ABLE per mon instead of the HP bar, and the
+  -- "Use TM on which POKeMON?" prompt). Set by BagMenu.pickTargetAndUse. #210
+  self.tmhm = opts.tmhm
+  self.forceSwitch = opts.forceSwitch
   self.battle = opts.battle
   self.party = opts.party -- link battles pass their clamped copies
   self.swapFrom = nil
@@ -156,12 +168,29 @@ function PartyMenu:update(dt)
         -- hook-injected entries carry a callback instead of an action id
         entry.onSelect(mon, self.game)
       elseif action == "stats" then
+        -- battle and field alike return to the party list afterwards
+        -- (core.asm .partyMenuWasSelected)
         Screens.push(self.game, "SummaryMenu", mon)
+      elseif action == "battle_switch" then
+        self.game.stack:pop()
+        self.onSwitch(mon)
+        return
+      elseif action == "cancel" then
+        self.game.stack:pop()
+        if self.onCancel then self.onCancel() end
+        return
       elseif action == "switch" then
         self.swapFrom = self.index
       elseif action == "fly" then
+        -- FLY opens the TOWN MAP with a cursor over the visited fly towns,
+        -- not a plain text list (engine/menus/town_map.asm LoadTownMap_Fly).
+        -- flyTo (OverworldController) validates the fly-warp + runs the
+        -- departure/warp, so we just hand it the chosen mapId (#195).
+        local ow = self.game.overworld
         self.game.stack:pop() -- close the party menu
-        Screens.push(self.game, "FlyMenu")
+        Screens.push(self.game, "TownMap", { fly = true, onFly = function(mapId)
+          if ow then ow:flyTo(mapId) end
+        end })
         return
       elseif action == "flash" then -- FLASH lights dark tunnels
         -- start_sub_menus.asm .flash: PrintText _FlashLightsAreaText, then
@@ -286,21 +315,15 @@ function PartyMenu:update(dt)
         -- 1/5 of the user's max HP to a chosen teammate
         self.softboiledFrom = self.index
       elseif action == "escape" then
-        -- DIG / TELEPORT both warp to the last Pokémon Center town
-        -- (wLastBlackoutMap, special_warps.asm escape warp); .dig/.teleport
-        -- end with GBPalWhiteOutWithDelay3 + jp .goBackToMap
+        -- DIG / TELEPORT warp to the last Pokémon Center TOWN (wLastBlackoutMap,
+        -- special_warps.asm escape warp).  pokered's .dig/.teleport spin the
+        -- player up (LeaveMapAnim), white/fade out, then land it; this port
+        -- lands OUTSIDE the town PC door like Fly (#196).  beginTeleportOut
+        -- centralizes the spin -> fade -> warp so BagMenu's ESCAPE ROPE shares
+        -- the exact departure; the fade + warp fire when the spin ends.
         local ow = self.game.overworld
-        local heal = self.game.save.lastHeal
-        local Transition = require("src.render.Transition")
         self.game.stack:pop()
-        if ow and heal then
-          self.game.stack:push(Transition.whiteFlash(self.game, nil, function()
-            require("src.core.Sound").play(self.game.data, "Teleport_Exit1")
-            -- EnterMapAnim on arrival (HandleFlyWarpOrDungeonWarp sets
-            -- BIT_FLY_WARP); blackouts must not pass arrive="teleport"
-            ow:warpToHealPoint(nil, { arrive = "teleport" })
-          end))
-        end
+        if ow then ow:beginTeleportOut() end
         return
       end
       self.submenu = nil
@@ -341,58 +364,66 @@ function PartyMenu:update(dt)
         require("src.core.Sound").play(self.game.data, "Swap")
       end
       self.swapFrom = nil
-    elseif self.onSwitch then
+    elseif self.onSwitch and (self.forceSwitch or self.pickOnly or not self.battle) then
       self.game.stack:pop()
       self.onSwitch(mon)
     else
       self.submenu = true
       self.subIndex = 1
-      -- STATS/SWITCH plus this mon's field moves (start_sub_menus.asm
-      -- builds the same dynamic list)
-      local items = { { label = "STATS", action = "stats" },
-                      { label = "SWITCH", action = "switch" } }
+      local items
       local ow = self.game.overworld
-      -- Field moves (HMs/TMs) are usable out of battle even when the mon
-      -- is fainted -- Gen 1 does not require HP for Cut/Fly/Surf/etc.
-      -- Battle still excludes this list via `not self.battle`. Softboiled
-      -- can appear for a fainted user; its heal transfer then no-ops.
-      if not self.battle and ow then
-        -- FLY/TELEPORT: CheckIfInOutsideMap (OVERWORLD + PLATEAU —
-        -- Route 23 / Indigo Plateau outdoor), not OVERWORLD alone (#83)
-        local outside = Map.isOutside(ow.map.def,
-          FieldDefaults.field(self.game.data, "outsideTilesets"))
-        for _, mv in ipairs(mon.moves) do
-          if mv.id == "FLY" and outside
-             and self.game.save.inventory.THUNDERBADGE then
-            table.insert(items, { label = "FLY", action = "fly" })
-          elseif mv.id == "FLASH" and ow.dark
-             and self.game.save.inventory.BOULDERBADGE then
-            table.insert(items, { label = "FLASH", action = "flash" })
-          elseif mv.id == "CUT" and self.game.save.inventory.CASCADEBADGE then
-            -- CUT/SURF/STRENGTH are party-menu field moves too
-            -- (start_sub_menus.asm .outOfBattleMovePointers); listed here
-            -- with the same list-time badge filter this file already uses
-            -- for FLY/FLASH.  The facing-tile/activation check happens on
-            -- selection (useCutFieldMove/useSurfFieldMove).
-            table.insert(items, { label = "CUT", action = "cut" })
-          elseif mv.id == "SURF" and self.game.save.inventory.SOULBADGE then
-            table.insert(items, { label = "SURF", action = "surf" })
-          elseif mv.id == "STRENGTH" and self.game.save.inventory.RAINBOWBADGE then
-            table.insert(items, { label = "STRENGTH", action = "strength" })
-          elseif mv.id == "SOFTBOILED" then
-            table.insert(items, { label = "SOFTBOILED", action = "softboiled" })
-          elseif mv.id == "TELEPORT" and outside then
-            -- TELEPORT works only OUTDOORS (start_sub_menus.asm
-            -- .teleport -> CheckIfInOutsideMap); dark maps don't
-            -- block it
-            table.insert(items, { label = "TELEPORT", action = "escape" })
-          elseif mv.id == "DIG" and DIG_TILESETS[ow.map.def.tileset]
-             and ow.map.id ~= "AGATHAS_ROOM" then
-            -- DIG runs ItemUseEscapeRope (.dig sets wCurItem =
-            -- ESCAPE_ROPE): usable in the dungeon tilesets of
-            -- escape_rope_tilesets.asm minus Agatha's room, even in
-            -- the dark (Rock Tunnel)
-            table.insert(items, { label = "DIG", action = "escape" })
+      if self.battle and self.onSwitch then
+        -- SwitchStatsCancelText (core.asm PartyMenuOrRockOrRun)
+        items = { { label = "SWITCH", action = "battle_switch" },
+                  { label = "STATS", action = "stats" },
+                  { label = "CANCEL", action = "cancel" } }
+      else
+        -- STATS/SWITCH plus this mon's field moves (start_sub_menus.asm
+        -- builds the same dynamic list)
+        items = { { label = "STATS", action = "stats" },
+                  { label = "SWITCH", action = "switch" } }
+        -- Field moves (HMs/TMs) are usable out of battle even when the mon
+        -- is fainted -- Gen 1 does not require HP for Cut/Fly/Surf/etc.
+        -- Battle still excludes this list via `not self.battle`. Softboiled
+        -- can appear for a fainted user; its heal transfer then no-ops.
+        if not self.battle and ow then
+          -- FLY/TELEPORT: CheckIfInOutsideMap (OVERWORLD + PLATEAU —
+          -- Route 23 / Indigo Plateau outdoor), not OVERWORLD alone (#83)
+          local outside = Map.isOutside(ow.map.def,
+            FieldDefaults.field(self.game.data, "outsideTilesets"))
+          for _, mv in ipairs(mon.moves) do
+            if mv.id == "FLY" and outside
+               and self.game.save.inventory.THUNDERBADGE then
+              table.insert(items, { label = "FLY", action = "fly" })
+            elseif mv.id == "FLASH" and ow.dark
+               and self.game.save.inventory.BOULDERBADGE then
+              table.insert(items, { label = "FLASH", action = "flash" })
+            elseif mv.id == "CUT" and self.game.save.inventory.CASCADEBADGE then
+              -- CUT/SURF/STRENGTH are party-menu field moves too
+              -- (start_sub_menus.asm .outOfBattleMovePointers); listed here
+              -- with the same list-time badge filter this file already uses
+              -- for FLY/FLASH.  The facing-tile/activation check happens on
+              -- selection (useCutFieldMove/useSurfFieldMove).
+              table.insert(items, { label = "CUT", action = "cut" })
+            elseif mv.id == "SURF" and self.game.save.inventory.SOULBADGE then
+              table.insert(items, { label = "SURF", action = "surf" })
+            elseif mv.id == "STRENGTH" and self.game.save.inventory.RAINBOWBADGE then
+              table.insert(items, { label = "STRENGTH", action = "strength" })
+            elseif mv.id == "SOFTBOILED" then
+              table.insert(items, { label = "SOFTBOILED", action = "softboiled" })
+            elseif mv.id == "TELEPORT" and outside then
+              -- TELEPORT works only OUTDOORS (start_sub_menus.asm
+              -- .teleport -> CheckIfInOutsideMap); dark maps don't
+              -- block it
+              table.insert(items, { label = "TELEPORT", action = "escape" })
+            elseif mv.id == "DIG" and DIG_TILESETS[ow.map.def.tileset]
+               and ow.map.id ~= "AGATHAS_ROOM" then
+              -- DIG runs ItemUseEscapeRope (.dig sets wCurItem =
+              -- ESCAPE_ROPE): usable in the dungeon tilesets of
+              -- escape_rope_tilesets.asm minus Agatha's room, even in
+              -- the dark (Rock Tunnel)
+              table.insert(items, { label = "DIG", action = "escape" })
+            end
           end
         end
       end
@@ -410,6 +441,38 @@ function PartyMenu:update(dt)
   end
 end
 
+-- The bottom-of-screen context message for the current menu state
+-- (pokered engine/menus/party_menu.asm PartyMenuMessage / RedrawPartyMenu_):
+-- the party menu always prints a message in the bottom text box.  With the
+-- normal message id that is PartyMenuBattleText ("Bring out which POKéMON?")
+-- when IsInBattle else PartyMenuNormalText ("Choose a POKéMON."); the swap /
+-- item / TM-HM ids print their own strings, which draw() handles inline.
+-- Pure (no side effects) so drivers can assert it. #147
+function PartyMenu:bottomMessage()
+  if self.swapFrom then
+    return "Move to where?"
+  elseif self.softboiledFrom or self.pickOnly then
+    return "Use on which one?"
+  elseif self.tmhm then
+    return self.game.data.text._PartyMenuUseTMText
+      or "Use TM on which\nPOKéMON?"
+  elseif self.battle then
+    return self.game.data.text._PartyMenuBattleText
+      or "Bring out which\nPOKéMON?"
+  else
+    return self.game.data.text._PartyMenuNormalText
+      or "Choose a POKéMON."
+  end
+end
+
+-- Name-row pixel Y for party slot i (1-based).
+-- pokered party_menu.asm RedrawPartyMenu_: hlcoord 3, 0, then each entry
+-- advances 2*SCREEN_WIDTH (16 px).  The bottom message box sits at tile
+-- row 12 (y=96); slot 6's HP row is therefore at y=88. #262
+function PartyMenu.entryY(i)
+  return (i - 1) * 16
+end
+
 function PartyMenu:draw()
   love.graphics.setColor(1, 1, 1, 1)
   love.graphics.rectangle("fill", 0, 0, 160, 144)
@@ -421,9 +484,9 @@ function PartyMenu:draw()
   local HudTiles = require("src.render.HudTiles")
   for i, mon in ipairs(party) do
     local def = self.game.data.pokemon[mon.species]
-    local y = (i - 1) * 16 + 12
+    local y = PartyMenu.entryY(i)
     love.graphics.setColor(1, 1, 1, 1)
-    drawIcon(self.game, mon, 8, y - 2, i == self.index, self.blink or 0)
+    drawIcon(self.game, mon, 8, y, i == self.index, self.blink or 0)
     love.graphics.setColor(0, 0, 0, 1)
     Font.draw(mon.nickname or def.name, 24, y)
     -- level at column 13 (<LV> tile + digits, PrintLevel) AND the
@@ -436,16 +499,34 @@ function PartyMenu:draw()
       -- PrintLevel overwrites the <LV> tile with the third digit
       Font.draw(tostring(mon.level), 104, y)
     end
-    if mon.hp <= 0 then
-      Font.draw("FNT", 136, y)
-    elseif mon.status then
-      Font.draw(mon.status, 136, y)
+    if self.tmhm then
+      -- TM/HM teaching menu (engine/menus/party_menu.asm PrintPartyMenu):
+      -- the second row shows the inline "ABLE" / "NOT ABLE" learnability
+      -- strings in place of the HP bar and status, decided by CanLearnTM.
+      -- The learnset scan mirrors ItemEffects.use so the display can never
+      -- disagree with the actual teach. #210
+      local can = false
+      for _, m in ipairs(def.tmhm or {}) do
+        if m == self.tmhm.move then can = true break end
+      end
+      -- right-aligned so the shorter "ABLE" shares "NOT ABLE"'s right edge
+      if can then
+        Font.draw("ABLE", 120, y + 8)
+      else
+        Font.draw("NOT ABLE", 88, y + 8)
+      end
+    else
+      if mon.hp <= 0 then
+        Font.draw("FNT", 136, y)
+      elseif mon.status then
+        Font.draw(mon.status, 136, y)
+      end
+      -- the colored tile HP bar (DrawHP2 + SetPartyMenuHPBarColor)
+      love.graphics.setColor(1, 1, 1, 1)
+      HudTiles.drawHPBar(self.game.data, 5, (y + 8) / 8, mon)
+      love.graphics.setColor(0, 0, 0, 1)
+      Font.draw(("%3d/%3d"):format(mon.hp, mon.stats.hp), 104, y + 8)
     end
-    -- the colored tile HP bar (DrawHP2 + SetPartyMenuHPBarColor)
-    love.graphics.setColor(1, 1, 1, 1)
-    HudTiles.drawHPBar(self.game.data, 5, (y + 8) / 8, mon)
-    love.graphics.setColor(0, 0, 0, 1)
-    Font.draw(("%3d/%3d"):format(mon.hp, mon.stats.hp), 104, y + 8)
     if i == self.index then
       Font.drawCode(Theme.cursor, 0, y)
     end
@@ -457,8 +538,34 @@ function PartyMenu:draw()
     Font.draw("Move to where?", 8, 136)
   elseif self.softboiledFrom then
     Font.draw("Use on which one?", 8, 136)
+  elseif self.tmhm then
+    -- "Use TM on which\nPOKeMON?" in the standard bottom text box
+    -- (party_menu.asm keeps the message box for the TM/HM menu); box + line
+    -- geometry match TextBox's default (rows 12-17, text on rows 14/16). #210
+    Font.drawBox(0, 12, 20, 6)
+    love.graphics.setColor(0, 0, 0, 1)
+    local prompt = self.game.data.text._PartyMenuUseTMText
+      or "Use TM on which\nPOKéMON?"
+    local ly = 112
+    for line in (prompt .. "\n"):gmatch("([^\n]*)\n") do
+      Font.draw(line, 8, ly)
+      ly = ly + 16
+    end
   elseif self.pickOnly then
     Font.draw("Use on which one?", 8, 136)
+  else
+    -- default field party menu (StartMenu) and the battle voluntary-switch
+    -- (BattleState:openParty): Gen1 prints PartyMenuNormalText / PartyMenuBattleText
+    -- in the standard bottom text box (party_menu.asm PartyMenuMessage), not
+    -- plain bottom-row text.  Box + line geometry match the #210 TM/HM case and
+    -- TextBox's default (rows 12-17, text on rows 14/16). #147
+    Font.drawBox(0, 12, 20, 6)
+    love.graphics.setColor(0, 0, 0, 1)
+    local ly = 112
+    for line in (self:bottomMessage() .. "\n"):gmatch("([^\n]*)\n") do
+      Font.draw(line, 8, ly)
+      ly = ly + 16
+    end
   end
   if self.submenu then
     local n = #self.subItems

src/ui/PlayerPC.lua

@@ -71,6 +71,7 @@ end
 local function withdraw(game)
   local pc = game.save.pcItems
   game.stack:push(ListMenu.new(game, "WITHDRAW ITEM", buildItems(game, pc), {
+    messageBox = true,
     onChoose = function(item, list)
       askQuantity(game, list, pc[item.value] or 1, item.value, function(qty)
         local Bag = require("src.inventory.Bag")
@@ -107,6 +108,7 @@ local function deposit(game)
     if not Bag.isBadge(id) then depositable[id] = count end
   end
   game.stack:push(ListMenu.new(game, "DEPOSIT ITEM", buildItems(game, depositable), {
+    messageBox = true,
     onChoose = function(item, list)
       askQuantity(game, list, inv[item.value] or 1, item.value, function(qty)
         if pcFull(game, pc, item.value) then
@@ -126,6 +128,7 @@ end
 local function toss(game)
   local pc = game.save.pcItems
   game.stack:push(ListMenu.new(game, "TOSS ITEM", buildItems(game, pc), {
+    messageBox = true,
     onChoose = function(item, list)
       local def = game.data.items[item.value]
       if (def and def.keyItem) or item.value:find("^HM_") then
@@ -161,9 +164,9 @@ function PlayerPC.new(game)
     { label = "DEPOSIT ITEM", onSelect = function() deposit(game) end },
     { label = "TOSS ITEM", onSelect = function() toss(game) end },
     { label = "LOG OFF" },
-    -- the whole PC session runs silent (BIT_NO_MENU_BUTTON_SOUND,
-    -- engine/menus/players_pc.asm PlayersPCMenu)
-  }, { tx = 3, ty = 0, tw = 17, th = 10, noSound = true })
+    -- silent PC session (BIT_NO_MENU_BUTTON_SOUND); players_pc.asm
+    -- PlayersPCMenu TextBoxBorder (0,0) b=8 c=14 → 16x10
+  }, { tx = 0, ty = 0, tw = 16, th = 10, noSound = true })
 end
 
 return PlayerPC

src/ui/QuantityBox.lua

@@ -40,15 +40,19 @@ function QuantityBox:update(dt)
 end
 
 function QuantityBox:draw()
-  local w = self.unitPrice and 11 or 7
-  local tx = 20 - w - 1
-  Font.drawBox(tx, 13, w, 3)
+  -- DisplayChooseQuantityMenu (home/list_menu.asm): non-priced box at
+  -- hlcoord 15,9 (interior 3x1); priced at hlcoord 7,9 (interior 11x1).
+  -- TextBoxBorder adds the frame, so outer size is +2 on each axis.
+  local tw = self.unitPrice and 13 or 5
+  local tx = self.unitPrice and 7 or 15
+  local ty = 9
+  Font.drawBox(tx, ty, tw, 3)
   love.graphics.setColor(0, 0, 0, 1)
   local s = ("×%02d"):format(self.qty) -- the multiply glyph tile
   if self.unitPrice then
     s = s .. (" ¥%d"):format(self.qty * self.unitPrice)
   end
-  Font.draw(s, (tx + 1) * 8, 14 * 8)
+  Font.draw(s, (tx + 1) * 8, (ty + 1) * 8)
   love.graphics.setColor(1, 1, 1, 1)
 end
 

src/ui/ShopMenu.lua

@@ -106,8 +106,11 @@ local function sell(game)
     onChoose = function(item)
       local def = game.data.items[item.value]
       -- only key items and HMs are unsellable (pokemart.asm IsKeyItem /
-      -- IsItemHM); zero-price items like ETHER sell for ¥0
-      if (def and def.keyItem) or item.value:find("^HM_") then
+      -- IsItemHM); zero-price items like ETHER sell for ¥0.  An unknown id
+      -- (nil def) has no price, so treat it as unsellable too rather than
+      -- indexing nil below -- guards saves that already picked up a bogus
+      -- ITEM_NONE "0" from Blue's House before that pickup was fixed (#11).
+      if not def or def.keyItem or item.value:find("^HM_") then
         list.footer = txt(game, "_PokemartUnsellableItemText",
                           "I can't put a\nprice on that.")
         return

src/ui/SummaryMenu.lua

@@ -5,6 +5,13 @@
 -- A on page 2) closes.
 
 local Font = require("src.render.Font")
+-- status_screen.asm PrintMonType prints the type's DISPLAY name from the
+-- TypeNames table, not the constant: species types are stored as pokered
+-- constants (RomExtractor:typesById) and PSYCHIC's is "PSYCHIC_TYPE" (so it
+-- won't collide with the PSYCHIC move), which would overflow the TYPE field.
+-- TypeChart.displayName maps it back to "PSYCHIC", like HallOfFame and the
+-- battle move-type box already do (#214).
+local TypeChart = require("src.battle.TypeChart")
 
 local SummaryMenu = {}
 SummaryMenu.__index = SummaryMenu
@@ -99,10 +106,10 @@ function SummaryMenu:draw()
     -- TYPE1/TYPE2/IDNo/OT column (10,9) with values indented (11,10)
     drawLineBox(19, 9, 8, 6)
     Font.draw("TYPE1/", 80, 72)
-    Font.draw(def.types[1] or "", 88, 80)
+    Font.draw(def.types[1] and TypeChart.displayName(def.types[1]) or "", 88, 80)
     if def.types[2] then
       Font.draw("TYPE2/", 80, 88)
-      Font.draw(def.types[2], 88, 96)
+      Font.draw(TypeChart.displayName(def.types[2]), 88, 96)
     end
     Font.draw("IDNo/", 80, 104)
     -- the trainer ID is rolled at new game (SaveData.newGame) and

src/ui/Theme.lua

@@ -15,7 +15,8 @@ local Theme = {
   cols = Renderer.WIDTH / 8,
   rows = Renderer.HEIGHT / 8,
   textBox = { tx = 0, ty = 12, tw = 20, th = 6, maxCols = 18 },
-  choiceBox = { tx = 0, ty = 7, tw = 6, th = 5 },
+  -- InitYesNoTextBoxParameters / AskName: hlcoord 14, 7 (YES_NO_MENU 4x3)
+  choiceBox = { tx = 14, ty = 7, tw = 6, th = 5 },
 }
 
 function Theme.load(data)

src/ui/TownMap.lua

@@ -7,6 +7,11 @@
 -- the selected name in a banner up top, and the player's current
 -- location blinking.  List mode (townMap data missing): up/down through
 -- an ordered list of fly towns instead.  B closes.
+--
+-- Fly mode (opts.fly + opts.onFly, LoadTownMap_Fly): the same Kanto map,
+-- but the cursor cycles ONLY the visited fly destinations (Up/Down, in fly
+-- order), the banner reads "To <NAME>", and A calls onFly(mapId) to depart.
+-- This is what the party-menu FLY field move opens (#195).
 
 local Font = require("src.render.Font")
 local Sound = require("src.core.Sound")
@@ -80,7 +85,10 @@ local function buildLocations(game)
   local seen = {}
   for _, mapId in ipairs(field.flyOrder or {}) do
     local def = game.data.maps and game.data.maps[mapId]
-    if not seen[mapId] and def and Map.isOutdoor(def) then
+    -- accept the PLATEAU tileset too so Indigo Plateau shows on the
+    -- stale-asset list fallback, matching the fly-list filter (#203)
+    if not seen[mapId] and def
+       and (Map.isOutdoor(def) or def.tileset == "PLATEAU") then
       seen[mapId] = true
       local loc = { name = mapId:gsub("_", " ") }
       table.insert(locs, loc)
@@ -119,6 +127,42 @@ local function markerXY(loc)
   return loc.x * 8 + 16, loc.y * 8 + 8
 end
 
+-- the row-0 name banner; fly mode prefixes "To " like LoadTownMap_Fly
+-- (engine/menus/town_map.asm prints the destination as "To <NAME>")
+function TownMap:bannerText(loc)
+  return (self.fly and "To " or "") .. loc.name
+end
+
+-- Fly mode selection set (engine/menus/town_map.asm LoadTownMap_Fly): the
+-- cursor cycles ONLY the visited fly destinations, in fly order, each landing
+-- on its town square.  Built from field.flyOrder filtered to visited outdoor
+-- towns that have a fly-warp spot, deduped, reusing the grid loc so the cursor
+-- lands on the town and its name shows in the banner.
+local function buildFlyList(game, byMap)
+  local field = game.data.field or {}
+  local visited = game.save.visited or {}
+  local flyWarps = field.flyWarps or {}
+  local Map = require("src.world.Map")
+  local flyLocs, flyMapIds, seen = {}, {}, {}
+  for _, mapId in ipairs(field.flyOrder or {}) do
+    local def = game.data.maps and game.data.maps[mapId]
+    -- INDIGO_PLATEAU is a normal Fly spot (engine/menus/town_map.asm
+    -- LoadTownMap_Fly cycles it like any town), but its map uses tileset
+    -- "PLATEAU" not OVERWORLD, so Map.isOutdoor() alone dropped it from the
+    -- cursor even though it is visited and has a fly warp.  Allow PLATEAU here
+    -- while the CAVERN/FACILITY dungeon escape spots that share flyOrder still
+    -- fail the gate and stay out (#203).
+    if not seen[mapId] and visited[mapId] and flyWarps[mapId]
+       and def and (Map.isOutdoor(def) or def.tileset == "PLATEAU") then
+      seen[mapId] = true
+      local loc = byMap[mapId] or { name = mapId:gsub("_", " ") }
+      table.insert(flyLocs, loc)
+      flyMapIds[#flyLocs] = mapId
+    end
+  end
+  return flyLocs, flyMapIds
+end
+
 -- opts.nestSpecies: the Pokédex AREA screen (LoadTownMap_Nest) --
 -- blink a nest icon on every map whose wild slots hold the species
 function TownMap.new(game, opts)
@@ -152,6 +196,26 @@ function TownMap.new(game, opts)
                           or "assets/generated/townmap/nest.png")
     self.nestIcon = ok and img or nil
   end
+  if opts.fly then
+    -- FLY picker (LoadTownMap_Fly): restrict the selectable set to the
+    -- visited fly towns so Up/Down cycle only those and A knows the mapId.
+    local flyLocs, flyMapIds = buildFlyList(game, self.byMap)
+    if #flyLocs > 0 then
+      self.fly = true
+      self.onFly = opts.onFly
+      self.locs = flyLocs
+      self.flyMapIds = flyMapIds
+      -- grid rendering needs coords on every entry; without them fall back to
+      -- the name list so the fly screen still works on stale asset builds
+      if self.mode == "grid" then
+        for _, loc in ipairs(flyLocs) do
+          if not (loc.x and loc.y) then self.mode = "list" break end
+        end
+      end
+    end
+    -- with nothing visited yet there is nowhere to fly: leave self.fly unset
+    -- so the screen degrades to a plain viewer (B closes)
+  end
   -- the player's current location (guard: overworld may not be running)
   local mapId = game.overworld and game.overworld.map and game.overworld.map.id
   self.playerLoc = mapId and self.byMap[mapId] or nil
@@ -199,7 +263,19 @@ function TownMap:update(dt)
     self.game.stack:pop()
     return
   end
-  if self.nestSpecies then
+  if self.fly then
+    -- LoadTownMap_Fly: Up/Down cycle the visited destinations, A flies there,
+    -- B cancels (handled above).  moveList walks self.locs, now the fly list.
+    if input:wasPressed("a") then
+      Sound.play(self.game.data, "Press_AB")
+      local mapId = self.flyMapIds[self.sel]
+      self.game.stack:pop()
+      if mapId and self.onFly then self.onFly(mapId) end
+      return
+    elseif input:wasPressed("up") then self:moveList(-1)
+    elseif input:wasPressed("down") then self:moveList(1)
+    end
+  elseif self.nestSpecies then
     if input:wasPressed("a") then
       Sound.play(self.game.data, "Press_AB")
       self.game.stack:pop()
@@ -260,18 +336,28 @@ function TownMap:draw()
       love.graphics.setColor(1, 1, 1, 1)
       return
     end
-    -- the player's current location blinks (slow phase)
+    -- the player's current location blinks (slow phase).  Paint it with a
+    -- palette-safe DARK shade (red 0), not red: this screen composites through
+    -- the TOWNMAP SGB shade-remap shader (PaletteFX.shader), which keys ONLY on
+    -- the red channel, and a red-0.75 dot lands in the c1 bucket = TOWNMAP
+    -- {165,214,255}, the exact light-blue used for the water and the town-square
+    -- fill, so the marker was drawn but recolored invisible (#152).  Red 0 -> c3
+    -- {25,16,16} = a solid dark "you are here" dot, visible on land and water.
     if self.playerLoc and self.blink < 20 then
       local x, y = markerXY(self.playerLoc)
-      love.graphics.setColor(0.75, 0.1, 0.1, 1)
+      love.graphics.setColor(0, 0, 0, 1)
       love.graphics.rectangle("fill", x + 2, y + 2, 4, 4)
       love.graphics.setColor(1, 1, 1, 1)
     end
-    -- blinking cursor on the selected location
+    -- blinking cursor on the selected location.  markerXY is the 8x8 cell's
+    -- top-left; the cursor asset is a 16x16 hollow frame centered on its own
+    -- (8,8), so draw it -4,-4 to enclose the cell (engine/menus/town_map.asm
+    -- draws the box cursor CENTERED on the selected location).  Drawing it at
+    -- the cell top-left put the square in the frame's top-left quadrant (#152).
     if selected and self.blink % 16 < 10 then
       local x, y = markerXY(selected)
       if self.bg.cursor then
-        love.graphics.draw(self.bg.cursor, x, y)
+        love.graphics.draw(self.bg.cursor, x - 4, y - 4)
       else
         love.graphics.setColor(0, 0, 0, 1)
         love.graphics.rectangle("line", x + 0.5, y + 0.5, 7, 7)
@@ -281,7 +367,7 @@ function TownMap:draw()
     -- the name strip on row 0 (DisplayTownMap: ClearScreenArea + name)
     love.graphics.rectangle("fill", 0, 0, 160, 8)
     love.graphics.setColor(0, 0, 0, 1)
-    if selected then Font.draw(selected.name, 8, 0) end
+    if selected then Font.draw(self:bannerText(selected), 8, 0) end
     love.graphics.setColor(1, 1, 1, 1)
     return
   end
@@ -294,7 +380,9 @@ function TownMap:draw()
       drawSquare(loc)
     end
     if self.playerLoc and self.blink < 20 then
-      love.graphics.setColor(0.75, 0.1, 0.1, 1)
+      -- palette-safe dark, same red-channel shade-remap reason as the primary
+      -- grid path above (#152); stale-asset builds hit this fallback square
+      love.graphics.setColor(0, 0, 0, 1)
       love.graphics.rectangle("fill", self.playerLoc.x * 8 + 2,
                               self.playerLoc.y * 8 + 2, 4, 4)
     end
@@ -317,7 +405,10 @@ function TownMap:draw()
         end
         Font.draw(loc.name, 24, y)
         if loc == self.playerLoc and self.blink < 20 then
-          -- blinking marker on the player's current town
+          -- blinking marker on the player's current town; force the palette-safe
+          -- dark shade explicitly so the red-channel shade-remap keeps it
+          -- visible regardless of Font.draw's leftover color (#152)
+          love.graphics.setColor(0, 0, 0, 1)
           love.graphics.rectangle("fill", 24 + #loc.name * 8 + 6, y + 2, 4, 4)
         end
       end
@@ -327,7 +418,7 @@ function TownMap:draw()
   -- name banner across the top
   Font.drawBox(0, 0, 20, 3)
   love.graphics.setColor(0, 0, 0, 1)
-  if selected then Font.draw(selected.name, 8, 8) end
+  if selected then Font.draw(self:bannerText(selected), 8, 8) end
   love.graphics.setColor(1, 1, 1, 1)
 end
 

src/ui/TradeAnim.lua

@@ -1,8 +1,7 @@
--- Link/in-game trade cinematic (engine/movie/trade.asm, trade2.asm):
--- the traded POKéMON rises away with its cry and a goodbye, then the
--- received one descends with its cry and "take good care" text.
--- A skips the slide animations ahead.  Calls onDone() after popping.
+-- InternalClockTradeAnim (engine/movie/trade.asm): cable-trade cinematic
+-- used by in-game NPC trades and internally-clocked link trades.
 
+local Font = require("src.render.Font")
 local Sound = require("src.core.Sound")
 local TextBox = require("src.render.TextBox")
 
@@ -10,13 +9,22 @@ local TradeAnim = {}
 TradeAnim.__index = TradeAnim
 TradeAnim.isOpaque = true
 
--- SGB: generic whole-screen palette (SET_PAL_GENERIC)
 function TradeAnim:sgbPalettes(game)
   return require("src.render.PaletteFX").wholeNamed(game.data, "MEWMON")
 end
 
-local SLIDE_FRAMES = 90
-local REST_Y = 44 -- resting top of the sprite, roughly screen centre
+local DEFAULT_ART = {
+  gameBoy = "assets/generated/trade/game_boy.png",
+  openCable = "assets/generated/trade/open_cable.png",
+  cableHoriz = "assets/generated/trade/cable_horiz.png",
+  cableConn = "assets/generated/trade/cable_conn.png",
+  cableVert = "assets/generated/trade/cable_vert.png",
+  cableCorner = "assets/generated/trade/cable_corner.png",
+  cableEnd = "assets/generated/trade/cable_end.png",
+  cableBall = "assets/generated/trade/cable_ball.png",
+  cableBallAlt = "assets/generated/trade/cable_ball_alt.png",
+  bubble = "assets/generated/trade/bubble.png",
+}
 
 local function tryImage(path)
   if not path then return nil end
@@ -29,11 +37,46 @@ local function nameOf(game, mon)
   return mon.nickname or (def and def.name) or mon.species
 end
 
+local function speciesName(game, mon)
+  local def = game.data.pokemon[mon.species]
+  return (def and def.name) or mon.species
+end
+
+local function dexOf(game, mon)
+  local def = game.data.pokemon[mon.species]
+  return def and def.dex or 0
+end
+
 local function spriteOf(game, mon)
   local def = game.data.pokemon[mon.species]
   return tryImage(def and def.spriteFront)
 end
 
+local function expand(game, key, subs)
+  local raw = game.data.text and game.data.text[key]
+  if not raw then return key end
+  for token, value in pairs(subs or {}) do
+    raw = raw:gsub("{" .. token .. "}", value)
+  end
+  return TextBox.substitute(game, raw)
+end
+
+-- InternalClockTradeFuncSequence
+local SEQ = {
+  "show_player",
+  "open_cable",
+  "ball_enter",
+  "transfer_lr",
+  "delay",
+  "went_to",
+  "for_sends",
+  "farewell",
+  "transfer_rl",
+  "open_cable2",
+  "show_enemy",
+  "done",
+}
+
 function TradeAnim.new(game, opts)
   opts = opts or {}
   local self = setmetatable({}, TradeAnim)
@@ -41,62 +84,401 @@ function TradeAnim.new(game, opts)
   self.sent = opts.sent
   self.received = opts.received
   self.onDone = opts.onDone
+  self.enemyName = opts.enemyName or (self.received and self.received.ot) or "TRAINER"
+  self.playerName = (game.save.player and game.save.player.name) or "RED"
+  self.playerOt = opts.playerOt or self.playerName
+  self.playerOtId = opts.playerOtId
+    or (self.sent and self.sent.otId)
+    or (game.save.player and game.save.player.id)
+    or 0
+  self.enemyOtId = opts.enemyOtId
+    or (self.received and self.received.otId)
+    or love.math.random(0, 65535)
+
+  local art = (game.data.field and game.data.field.tradeArt) or DEFAULT_ART
+  self.img = {
+    gameBoy = tryImage(art.gameBoy or DEFAULT_ART.gameBoy),
+    openCable = tryImage(art.openCable or DEFAULT_ART.openCable),
+    cableHoriz = tryImage(art.cableHoriz or DEFAULT_ART.cableHoriz),
+    cableConn = tryImage(art.cableConn or DEFAULT_ART.cableConn),
+    cableVert = tryImage(art.cableVert or DEFAULT_ART.cableVert),
+    cableCorner = tryImage(art.cableCorner or DEFAULT_ART.cableCorner),
+    cableEnd = tryImage(art.cableEnd or DEFAULT_ART.cableEnd),
+    cableBall = tryImage(art.cableBall or DEFAULT_ART.cableBall),
+    cableBallAlt = tryImage(art.cableBallAlt or DEFAULT_ART.cableBallAlt),
+    bubble = tryImage(art.bubble or DEFAULT_ART.bubble),
+  }
   self.sentSprite = spriteOf(game, self.sent)
-  self.receivedSprite = spriteOf(game, self.received)
-  self.phase = "out"
+  self.recvSprite = spriteOf(game, self.received)
+
+  self.seq = 1
+  self.phase = SEQ[1]
   self.t = 0
+  self.scx = 0
+  self.ballX = 0
+  self.ballY = 0
+  self.monX = 0
+  self.monY = 0
+  self.flash = false
+  self.monVisible = true
+  self.waitingText = false
+  self.cableFlash = false
   return self
 end
 
 function TradeAnim:enter()
-  Sound.playCry(self.game.data, self.sent.species)
+  Sound.play(self.game.data, "Trade_Machine")
+end
+
+function TradeAnim:advance()
+  self.seq = self.seq + 1
+  self.phase = SEQ[self.seq] or "done"
+  self.t = 0
+  self.scx = 0
+  self.sub = nil
+  self.flash = false
+  self.cableFlash = false
+  self.poof = nil
+  if self.phase == "done" then
+    self.game.stack:pop()
+    if self.onDone then self.onDone() end
+  elseif self.phase == "show_enemy" then
+    self.monVisible = false
+  elseif self.phase == "transfer_lr" then
+    -- wBaseCoord $54, $1c OAM -> screen (76, 12)
+    self.monX, self.monY = 76, 12
+  elseif self.phase == "transfer_rl" then
+    -- wBaseCoord $64, $44 OAM -> screen (92, 52), right GB on screen
+    self.monX, self.monY = 92, 52
+    self.scx = 160
+  elseif self.phase == "ball_enter" then
+    -- lb bc, $20, $60: b = Y, c = X (Trade_AnimateBallEnteringLinkCable)
+    self.ballX, self.ballY = 0x60, 0x20
+  elseif self.phase == "open_cable" or self.phase == "open_cable2" then
+    -- SCX $a0 -> $f0: cable slides in from the right, open end rests at x64
+    self.scx = 0x50
+    Sound.play(self.game.data, "Heal_HP")
+  end
+end
+
+function TradeAnim:say(text, delay, thenFn)
+  self.waitingText = true
+  self.game.stack:push(TextBox.new(self.game, text, function()
+    self.waitingText = false
+    if thenFn then thenFn() else self:advance() end
+  end, { auto = { delay = delay or 80 } }))
+end
+
+function TradeAnim:skipHeld()
+  return self.game.input:wasPressed("a") or self.game.input:isDown("a")
 end
 
 function TradeAnim:update(dt)
-  local input = self.game.input
-  if self.phase == "out" or self.phase == "in" then
-    self.t = self.t + 1
-    if input:wasPressed("a") then self.t = SLIDE_FRAMES end
-    if self.t < SLIDE_FRAMES then return end
-    if self.phase == "out" then
-      self.phase = "goodbye"
-      self.game.stack:push(TextBox.new(self.game,
-        ("Goodbye %s!"):format(nameOf(self.game, self.sent)),
-        function()
-          self.phase = "in"
-          self.t = 0
-          Sound.playCry(self.game.data, self.received.species)
-        end))
+  if self.waitingText or self.phase == "done" then return end
+  local skip = self.game.input:wasPressed("a")
+  self.t = self.t + 1
+  local p = self.phase
+
+  if p == "show_player" then
+    -- slide from SCX $86 -> 0, hold 80, poof, cry (Trade_ShowPlayerMon)
+    if not self.sub then self.sub = "slide" end
+    if self.sub == "slide" then
+      self.scx = math.max(0, 0x86 - self.t * 2)
+      if skip or self.scx <= 0 then
+        self.scx = 0
+        self.sub = "hold"
+        self.t = 0
+      end
+    elseif self.sub == "hold" then
+      if skip or self.t >= 80 then
+        self.sub = "poof"
+        self.t = 0
+        self.monVisible = false
+        Sound.play(self.game.data, "Ball_Poof")
+      end
+    elseif self.sub == "poof" then
+      self.poof = math.max(0, 16 - self.t)
+      if skip or self.t >= 16 then
+        Sound.playCry(self.game.data, self.sent.species)
+        self.sub = nil
+        self:advance()
+      end
+    end
+
+  elseif p == "open_cable" or p == "open_cable2" then
+    -- 20 steps of 4px, matching the SCX loop
+    self.scx = math.max(0, 0x50 - self.t * 4)
+    if skip or self.scx <= 0 then
+      self.scx = 0
+      self:advance()
+    end
+
+  elseif p == "ball_enter" then
+    -- TRADE_BALL_SHAKE then ball rides the cable; X from $60 toward $a0
+    if self.t < 20 then
+      if skip then self.t = 20 end
+      return
+    end
+    local step = self.t - 20
+    if step % 3 == 0 then
+      self.ballX = 0x60 + math.floor(step / 3) * 4
+      self.flash = not self.flash
+      if self.ballX < 0xA0 then Sound.play(self.game.data, "Tink") end
+    end
+    if skip then self.ballX = 0xA0 end
+    if self.ballX >= 0xA0 then self:advance() end
+
+  elseif p == "transfer_lr" then
+    -- scroll left GB off while the mon rides the cable, then the sprite
+    -- itself moves right and down into the right GB (Trade_AnimMonMoveVertical)
+    if self.t <= 80 then
+      self.scx = math.min(160, self.t * 2)
+      self.monX, self.monY = 76, 12
+    elseif self.t <= 80 + 32 then
+      self.monX = 76 + math.floor((self.t - 80) / 8) * 4
+    elseif self.t <= 80 + 64 then
+      self.monX = 92
+      self.monY = 12 + math.floor((self.t - 112) / 8) * 10
     else
-      self.phase = "takecare"
-      self.game.stack:push(TextBox.new(self.game,
-        ("Take good care\nof %s!"):format(nameOf(self.game, self.received)),
-        function()
-          self.game.stack:pop()
-          if self.onDone then self.onDone() end
-        end))
+      self:advance()
+      return
+    end
+    if self.t % 8 == 0 then self.cableFlash = not self.cableFlash end
+    if skip then self:advance() end
+
+  elseif p == "transfer_rl" then
+    -- mirror: sprite climbs out of the right GB, then the screen scrolls
+    -- back to the left GB
+    if self.t <= 32 then
+      self.scx = 160
+      self.monX, self.monY = 92, 52 - math.floor(self.t / 8) * 10
+    elseif self.t <= 64 then
+      self.monX = 92 - math.floor((self.t - 32) / 8) * 4
+      self.monY = 12
+    elseif self.t <= 64 + 80 then
+      self.scx = math.max(0, 160 - (self.t - 64) * 2)
+      self.monX, self.monY = 76, 12
+    else
+      self:advance()
+      return
+    end
+    if self.t % 8 == 0 then self.cableFlash = not self.cableFlash end
+    if skip then self:advance() end
+
+  elseif p == "delay" then
+    if skip or self.t >= 100 then self:advance() end
+
+  elseif p == "went_to" then
+    local text = expand(self.game, "_TradeWentToText", {
+      ["RAM:wStringBuffer"] = speciesName(self.game, self.sent),
+      ["RAM:wLinkEnemyTrainerName"] = self.enemyName,
+    })
+    self:say(text, 200)
+
+  elseif p == "for_sends" then
+    local a = expand(self.game, "_TradeForText", {
+      ["RAM:wStringBuffer"] = speciesName(self.game, self.sent),
+    })
+    local b = expand(self.game, "_TradeSendsText", {
+      ["RAM:wLinkEnemyTrainerName"] = self.enemyName,
+      ["RAM:wNameBuffer"] = nameOf(self.game, self.received),
+    })
+    self.waitingText = true
+    self.game.stack:push(TextBox.new(self.game, a, function()
+      self.game.stack:push(TextBox.new(self.game, b, function()
+        self.waitingText = false
+        self:advance()
+      end, { auto = { delay = 80 } }))
+    end, { auto = { delay = 80 } }))
+
+  elseif p == "farewell" then
+    local a = expand(self.game, "_TradeWavesFarewellText", {
+      ["RAM:wLinkEnemyTrainerName"] = self.enemyName,
+    })
+    local b = expand(self.game, "_TradeTransferredText", {
+      ["RAM:wNameBuffer"] = nameOf(self.game, self.received),
+    })
+    self.waitingText = true
+    self.game.stack:push(TextBox.new(self.game, a, function()
+      self.game.stack:push(TextBox.new(self.game, b, function()
+        self.waitingText = false
+        self:advance()
+      end, { auto = { delay = 80 } }))
+    end, { auto = { delay = 80 } }))
+
+  elseif p == "show_enemy" then
+    if self.t == 1 then
+      Sound.play(self.game.data, "Ball_Poof")
+      self.monVisible = true
+    elseif self.t == 20 then
+      Sound.playCry(self.game.data, self.received.species)
+    elseif self.t >= 120 or skip then
+      local text = expand(self.game, "_TradeTakeCareText", {
+        ["RAM:wNameBuffer"] = nameOf(self.game, self.received),
+      })
+      self:say(text, 80)
     end
   end
 end
 
+local function drawCableHoriz(self, y, x0, x1)
+  if self.img.cableHoriz then
+    love.graphics.draw(self.img.cableHoriz, x0 - (self.scx % 8), y)
+  else
+    love.graphics.setColor(0.2, 0.2, 0.2, 1)
+    love.graphics.rectangle("fill", x0, y + 1, math.max(0, x1 - x0), 6)
+    love.graphics.setColor(1, 1, 1, 1)
+  end
+end
+
+function TradeAnim:drawMonInfo(mon, ot, otId, boxTy)
+  -- Trade_PrintPlayerMonInfoText: rows +0/+2/+4/+6 from the box top; the
+  -- No. line replaces part of the top border (hlcoord 5, 0 in trade2.asm)
+  Font.drawBox(4, boxTy, 12, 8)
+  local y0 = boxTy * 8
+  local no = ("No.%03d"):format(dexOf(self.game, mon))
+  love.graphics.setColor(1, 1, 1, 1)
+  love.graphics.rectangle("fill", 56, y0, Font.width(no), 8)
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw(no, 56, y0)
+  Font.draw(speciesName(self.game, mon), 40, y0 + 16)
+  Font.draw("OT/" .. (ot or "????"), 40, y0 + 32)
+  Font.draw(("IDNo.%05d"):format(otId or 0), 40, y0 + 48)
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+function TradeAnim:drawIconInBubble(mon, x, y)
+  local spr = (mon.species == self.received.species) and self.recvSprite or self.sentSprite
+  if spr then
+    local sw, sh = spr:getDimensions()
+    local s = 16 / math.max(sw, sh)
+    love.graphics.draw(spr, x, y, 0, s, s)
+  else
+    love.graphics.setColor(0, 0, 0, 1)
+    love.graphics.rectangle("fill", x + 4, y + 4, 8, 8)
+    love.graphics.setColor(1, 1, 1, 1)
+  end
+  if self.img.bubble then
+    if not self.bubbleQuad then
+      local iw, ih = self.img.bubble:getDimensions()
+      self.bubbleQuad = love.graphics.newQuad(0, 0, 16, 16, iw, ih)
+      self.bubbleQuadAlt = ih >= 32
+        and love.graphics.newQuad(0, 16, 16, 16, iw, ih)
+        or self.bubbleQuad
+    end
+    local q = self.cableFlash and self.bubbleQuadAlt or self.bubbleQuad
+    love.graphics.draw(self.img.bubble, q, x - 8, y - 8)
+  end
+end
+
+function TradeAnim:drawGameBoy(x, y)
+  if self.img.gameBoy then
+    love.graphics.draw(self.img.gameBoy, x, y)
+  else
+    love.graphics.setColor(0, 0, 0, 1)
+    love.graphics.rectangle("line", x, y, 48, 64)
+    love.graphics.setColor(1, 1, 1, 1)
+  end
+end
+
+function TradeAnim:drawLeftGB()
+  -- cable from GB to the right edge
+  if self.img.cableConn then
+    love.graphics.draw(self.img.cableConn, 88, 32)
+  end
+  drawCableHoriz(self, 32, 96, 160)
+  self:drawGameBoy(40, 24)
+  Font.drawBox(4, 12, 9, 4)
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw(self.playerName, 40, 112)
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+function TradeAnim:drawRightGB()
+  drawCableHoriz(self, 32, 0, 112)
+  if self.img.cableCorner then love.graphics.draw(self.img.cableCorner, 112, 32) end
+  if self.img.cableVert then
+    for i = 1, 4 do
+      love.graphics.draw(self.img.cableVert, 120, 40 + (i - 1) * 8)
+    end
+  end
+  if self.img.cableEnd then love.graphics.draw(self.img.cableEnd, 112, 72) end
+  if self.img.cableConn then love.graphics.draw(self.img.cableConn, 104, 72) end
+  self:drawGameBoy(56, 64)
+  Font.drawBox(6, 0, 9, 4)
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw(self.enemyName, 56, 16)
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
 function TradeAnim:draw()
   love.graphics.setColor(1, 1, 1, 1)
   love.graphics.rectangle("fill", 0, 0, 160, 144)
-  local sprite, y
-  if self.phase == "out" then
-    -- the sent mon rises up and off the screen
-    sprite = self.sentSprite
-    y = REST_Y - math.floor((self.t / SLIDE_FRAMES) * (REST_Y + 60))
-  elseif self.phase == "in" or self.phase == "takecare" then
-    -- the received mon descends into place
-    sprite = self.receivedSprite
-    local t = self.phase == "in" and self.t or SLIDE_FRAMES
-    y = -60 + math.floor((t / SLIDE_FRAMES) * (REST_Y + 60))
-  end
-  if sprite and y then
-    local w = sprite:getWidth()
-    love.graphics.draw(sprite, math.floor((160 - w) / 2), y)
+  local p = self.phase
+
+  if p == "show_player" then
+    love.graphics.push()
+    love.graphics.translate(-self.scx, 0)
+    -- mon pic on the BG at hlcoord 7, 2; info box on the window at
+    -- hWY $50, so it sits in the bottom half of the screen
+    if self.monVisible and self.sentSprite then
+      love.graphics.draw(self.sentSprite, 56, 16)
+    end
+    self:drawMonInfo(self.sent, self.playerOt, self.playerOtId, 10)
+    love.graphics.pop()
+    if self.poof and self.poof > 0 then
+      love.graphics.setColor(0, 0, 0, self.poof / 16)
+      love.graphics.circle("fill", 80, 40, 20 - (self.poof or 0))
+      love.graphics.setColor(1, 1, 1, 1)
+    end
+
+  elseif p == "open_cable" or p == "open_cable2" then
+    love.graphics.push()
+    love.graphics.translate(self.scx, 0)
+    if self.img.openCable then
+      love.graphics.draw(self.img.openCable, 64, 16) -- open end at SCX $f0
+    end
+    love.graphics.pop()
+
+  elseif p == "ball_enter" then
+    if self.img.openCable then
+      love.graphics.draw(self.img.openCable, 64, 16)
+    end
+    -- OAM coords carry a (+8, +16) hardware offset
+    local ball = self.flash and (self.img.cableBallAlt or self.img.cableBall)
+                or self.img.cableBall
+    if ball then
+      love.graphics.draw(ball, self.ballX - 8, self.ballY - 16)
+    else
+      love.graphics.setColor(0, 0, 0, 1)
+      love.graphics.circle("fill", self.ballX, self.ballY - 8, 6)
+      love.graphics.setColor(1, 1, 1, 1)
+    end
+
+  elseif p == "transfer_lr" or p == "transfer_rl" then
+    -- two-screen world: left GB scene at x0, right GB scene at x160;
+    -- the mon icon stays in screen space like the OAM sprite it ports
+    love.graphics.push()
+    love.graphics.translate(-self.scx, 0)
+    self:drawLeftGB()
+    love.graphics.translate(160, 0)
+    self:drawRightGB()
+    love.graphics.pop()
+    local mon = (p == "transfer_lr") and self.sent or self.received
+    self:drawIconInBubble(mon, self.monX, self.monY)
+    if self.cableFlash then
+      love.graphics.setColor(1, 1, 1, 0.15)
+      love.graphics.rectangle("fill", 0, 32, 160, 8)
+      love.graphics.setColor(1, 1, 1, 1)
+    end
+
+  elseif p == "show_enemy" then
+    if self.monVisible and self.recvSprite then
+      love.graphics.draw(self.recvSprite, 56, 16)
+    end
+    self:drawMonInfo(self.received, self.enemyName, self.enemyOtId, 10)
   end
+  -- went_to / for_sends / farewell / delay: cleared window; TextBox draws
 end
 
 return TradeAnim

src/ui/TrainerCard.lua

@@ -34,7 +34,8 @@ function TrainerCard.new(game)
   local self = setmetatable({ game = game }, TrainerCard)
   local img = tryImage("assets/generated/trainer_card/badges.png")
   if img then
-    -- 8 pairs of [gym leader face, badge]
+    -- badges.2bpp is 8 stacked [face, badge] pairs (DrawBadges FaceBadgeTiles)
+    self.faces = { img = img, quads = quads16(img, 8, 32, 0, 0) }
     self.badges = { img = img, quads = quads16(img, 8, 32, 0, 16) }
   end
   local nums = tryImage("assets/generated/trainer_card/badge_numbers.png")
@@ -124,7 +125,7 @@ function TrainerCard:draw()
     love.graphics.setColor(0, 0, 0, 1)
   end
 
-  -- numbered badge grid (rows 11-17): earned solid, unearned dimmed
+  -- numbered badge grid (rows 11-17): face by default, badge when owned
   self:frameBox(0, 11, 20, 7)
   local badges = Badges.list(self.game.data)
   for i = 1, #badges do
@@ -136,12 +137,11 @@ function TrainerCard:draw()
       love.graphics.setColor(1, 1, 1, 1)
       love.graphics.draw(self.nums.img, self.nums.quads[i - 1], tx, ty)
     end
-    if self.badges and self.badges.quads[i - 1]
-        and save.inventory[Badges.itemFor(badges[i])] then
-      -- unearned badge slots stay blank (DrawBadges)
+    if self.faces and self.faces.quads[i - 1] then
       love.graphics.setColor(1, 1, 1, 1)
-      love.graphics.draw(self.badges.img, self.badges.quads[i - 1],
-                         tx + 4, ty + 6)
+      local owned = save.inventory[Badges.itemFor(badges[i])]
+      local sheet = owned and self.badges or self.faces
+      love.graphics.draw(sheet.img, sheet.quads[i - 1], tx + 4, ty + 6)
     end
   end
   love.graphics.setColor(1, 1, 1, 1)

src/update/Boot.lua

@@ -0,0 +1,263 @@
+-- The boot shell: the heart of the self-updater.  A fused build, before it
+-- runs the game bundled inside it, looks in its save directory for a newer
+-- payload (a downloaded gen1recomp-X.Y.Z.love), and if one is present and
+-- runnable, mounts it over the bundled source and chainloads it -- so the
+-- binary shipped once can keep updating the Lua it runs without a reinstall.
+--
+-- Only a fused build self-updates.  A dev / source checkout IS the game, so
+-- Boot.run is a no-op there.
+--
+-- Three pieces, deliberately layered so the risky part is small and the
+-- decision part is testable:
+--   * Boot.select     -- pure: given probed candidates + the bundled version,
+--                        decide what to run and what to delete.  No love.*.
+--   * Boot.probePayload-- read one archive's advertised version, isolated.
+--   * Boot.run        -- orchestrates: crash-guard, enumerate, select, and
+--                        (if a payload wins) mount + chainload with full
+--                        rollback on any failure so the bundled game always
+--                        boots.
+--
+-- Known limitation: the bundled love.run keeps driving the frame loop after a
+-- handoff (it has already returned its stepper to LÖVE; redefining the global
+-- love.run does nothing to the running one).  A payload that must change
+-- love.run itself therefore requires a minShell bump so an older shell refuses
+-- to chainload it.
+
+local Semver = require("src.update.Semver")
+
+local Boot = {}
+
+-- Save-directory layout (identity "pokemon-love2d"), per the shared contract.
+local PAYLOAD_DIR = "updates"
+local PENDING = "updates/pending.txt"
+
+-- Isolated mountpoint used only to peek at a candidate's Version.lua, so its
+-- copy never collides with the running source's copy at "/".
+local PROBE_MOUNT = "__pokeport_probe"
+
+-- Downloaded payloads are named gen1recomp-<X.Y.Z>.love.
+local function isPayloadName(name)
+  return name:match("^gen1recomp%-.+%.love$") ~= nil
+end
+
+-- The love callbacks the payload's main.lua chunk may redefine when it runs.
+-- We snapshot these before a handoff and restore them if the handoff fails, so
+-- the exact bundled closures (with their intact upvalues) drive the game
+-- again.  love.run is included: harmless to restore, and it is one of the
+-- globals a payload main.lua reassigns.
+local CALLBACK_NAMES = {
+  "load", "update", "draw", "quit", "run",
+  "keypressed", "keyreleased", "textinput",
+  "mousepressed", "mousereleased", "mousemoved", "wheelmoved",
+  "touchpressed", "touchmoved", "touchreleased",
+  "gamepadpressed", "gamepadreleased", "gamepadaxis", "joystickremoved",
+  "focus", "visible", "resize", "filedropped", "directorydropped",
+  "errorhandler", "threaderror", "lowmemory",
+}
+
+local function snapshotCallbacks()
+  local snap = {}
+  for _, k in ipairs(CALLBACK_NAMES) do snap[k] = love[k] end
+  return snap
+end
+
+local function restoreCallbacks(snap)
+  for _, k in ipairs(CALLBACK_NAMES) do love[k] = snap[k] end
+end
+
+-- Drop every bundled Lua module the payload must be allowed to re-resolve: all
+-- src.* modules plus the main/conf chunks.  conf.lua cached the bundled
+-- Version into package.loaded["src.core.Version"]; without this purge the next
+-- require would hand back the bundled copy instead of the payload's.  Setting
+-- existing fields to nil during a pairs traversal is explicitly permitted.
+local function purgeBundledModules()
+  for key in pairs(package.loaded) do
+    if key:match("^src%.") or key == "main" or key == "conf" then
+      package.loaded[key] = nil
+    end
+  end
+end
+
+-- Boot.probePayload(rel) -> { engine = string, minShell = number } | nil, err
+--
+-- Mount the archive at rel (a save-directory-relative path) on an isolated
+-- mountpoint, read its src/core/Version.lua by executing the source with
+-- loadstring (NEVER require -- we must not cache or run it as a module), then
+-- unmount.  Version.lua is zero-require, so running its chunk is safe.
+function Boot.probePayload(rel)
+  if not love.filesystem.mount(rel, PROBE_MOUNT) then
+    return nil, "could not mount " .. tostring(rel)
+  end
+  local chunkPath = PROBE_MOUNT .. "/src/core/Version.lua"
+  local ok, result = pcall(function()
+    local src = love.filesystem.read(chunkPath)
+    if not src then error("Version.lua missing", 0) end
+    local chunk = loadstring(src, "@" .. chunkPath)
+    if not chunk then error("Version.lua would not compile", 0) end
+    return chunk()
+  end)
+  love.filesystem.unmount(rel)
+  if not ok then return nil, tostring(result) end
+  local v = result
+  if type(v) ~= "table" or type(v.engine) ~= "string" then
+    return nil, "payload has no usable Version table"
+  end
+  return { engine = v.engine, minShell = tonumber(v.minShell) or 1 }
+end
+
+-- Boot.select(candidates, bundledEngine, bundledShell) -> chosen | nil, toDelete
+--
+-- Pure (no love.*): decide which payload to run and which to delete.
+-- candidates is a list of { name = , engine = , minShell = }.
+--   * chosen: the highest engine that is STRICTLY newer than bundledEngine and
+--     whose minShell <= bundledShell (a payload the running shell can host).
+--   * toDelete: stale payloads -- engine <= bundled (old or the same as what we
+--     already ship), or superseded by the chosen one (not newer than chosen).
+--     A payload newer than the chosen one but unrunnable here (minShell too
+--     high) is kept: a future shell upgrade may be able to run it.
+function Boot.select(candidates, bundledEngine, bundledShell)
+  local chosen
+  for _, c in ipairs(candidates) do
+    local newer = Semver.compare(c.engine, bundledEngine) > 0
+    local runnable = (c.minShell or 1) <= bundledShell
+    if newer and runnable then
+      if not chosen or Semver.compare(c.engine, chosen.engine) > 0 then
+        chosen = c
+      end
+    end
+  end
+
+  local toDelete = {}
+  for _, c in ipairs(candidates) do
+    if not (chosen and c.name == chosen.name) then
+      local stale = Semver.compare(c.engine, bundledEngine) <= 0
+      if chosen and Semver.compare(c.engine, chosen.engine) <= 0 then
+        stale = true
+      end
+      if stale then toDelete[#toDelete + 1] = c.name end
+    end
+  end
+
+  return chosen and chosen.name or nil, toDelete
+end
+
+-- Mount the chosen payload and hand control to it.  Returns true when the
+-- payload is live and has completed its own love.load; false (with full
+-- rollback) on any failure, so the caller runs the bundled game instead.
+local function chainload(name, args)
+  local rel = PAYLOAD_DIR .. "/" .. name
+
+  -- Crash marker: if we die between here and clearing it, the next boot's
+  -- crash guard distrusts this payload and deletes it.
+  love.filesystem.write(PENDING, name)
+
+  -- Prepend-mount the payload at "/" (appendToPath = false) so its files win
+  -- over the fused source for every subsequent require / love.filesystem read.
+  if not love.filesystem.mount(rel, "/", false) then
+    love.filesystem.remove(PENDING)
+    return false
+  end
+
+  local snapshot = snapshotCallbacks()
+  purgeBundledModules()
+  _G.POKEPORT_PAYLOAD_MOUNTED = true
+
+  -- Chainload: run the payload's main.lua (redefines the love callbacks from
+  -- the NEW code), then call its love.load.  The new love.load calls Boot.run
+  -- again, which no-ops via the flag set above.
+  local ok, err = pcall(function()
+    local chunk = assert(love.filesystem.load("main.lua"))
+    chunk()
+    love.load(args)
+  end)
+
+  if not ok then
+    -- Handoff failed after mounting.  Unwind everything so the bundled game
+    -- boots cleanly: clear the flag, unmount the payload, purge any payload
+    -- modules it cached (so bundled requires reload from source), restore the
+    -- bundled love callbacks with their intact upvalues, and drop the marker.
+    -- Delete the payload too: it failed deterministically once, so leaving it
+    -- would re-select and re-fail it on every boot forever.
+    print("update: payload handoff failed, reverting to bundled: " .. tostring(err))
+    _G.POKEPORT_PAYLOAD_MOUNTED = nil
+    pcall(love.filesystem.unmount, rel)
+    purgeBundledModules()
+    restoreCallbacks(snapshot)
+    love.filesystem.remove(rel)
+    love.filesystem.remove(PENDING)
+    return false
+  end
+
+  -- Success: the payload owns the game now.  Drop the marker and tell the
+  -- caller to stop so the bundled love.load does not run on top of it.
+  love.filesystem.remove(PENDING)
+  return true
+end
+
+-- Everything after the fused / flag guards, wrapped so an unexpected error in
+-- enumeration or selection can never crash the boot.
+local function runInner(args)
+  -- Crash guard first: a pending.txt naming a payload means a previous boot
+  -- crashed mid-handoff.  Distrust that payload -- delete it and the marker --
+  -- then continue (we may still pick an older valid payload, or fall through
+  -- to the bundled game).
+  local pending = love.filesystem.read(PENDING)
+  if pending then
+    pending = pending:gsub("%s+$", "")
+    if pending ~= "" then
+      love.filesystem.remove(PAYLOAD_DIR .. "/" .. pending)
+    end
+    love.filesystem.remove(PENDING)
+  end
+
+  -- Enumerate and probe every payload in updates/.
+  local candidates = {}
+  if love.filesystem.getInfo(PAYLOAD_DIR, "directory") then
+    for _, entry in ipairs(love.filesystem.getDirectoryItems(PAYLOAD_DIR)) do
+      if isPayloadName(entry) then
+        local info = Boot.probePayload(PAYLOAD_DIR .. "/" .. entry)
+        if info then
+          candidates[#candidates + 1] = {
+            name = entry,
+            engine = info.engine,
+            minShell = info.minShell,
+          }
+        end
+      end
+    end
+  end
+
+  local Version = require("src.core.Version")
+  local chosen, toDelete = Boot.select(candidates, Version.engine, Version.shell)
+
+  for _, victim in ipairs(toDelete) do
+    love.filesystem.remove(PAYLOAD_DIR .. "/" .. victim)
+  end
+
+  if not chosen then return false end
+  return chainload(chosen, args)
+end
+
+-- Boot.run(args) -> boolean
+--
+-- The first line of love.load.  True means a payload was mounted and
+-- chainloaded and the caller must return immediately; false means boot the
+-- bundled game as normal.
+function Boot.run(args)
+  -- Dev / source checkouts never self-update.
+  if not (love.filesystem.isFused and love.filesystem.isFused()) then
+    return false
+  end
+  -- The chainloaded love.load calls Boot.run again; the flag makes it a no-op.
+  if _G.POKEPORT_PAYLOAD_MOUNTED then return false end
+
+  local ok, result = pcall(runInner, args)
+  if not ok then
+    -- An error escaped before any handoff mount (chainload cleans up after
+    -- itself), so state is still clean.  Never crash the boot.
+    return false
+  end
+  return result
+end
+
+return Boot

src/update/Check.lua

@@ -0,0 +1,177 @@
+-- Async release-check and payload-download for the self-update flow.
+--
+-- The heavy lifting (curl calls, sha256 verification, the Boot gate) happens
+-- on a background love.thread worker (src/update/check_worker.lua); this module
+-- is only the thin main-thread state machine the UI polls.  Two channels carry
+-- the conversation:
+--   "update_check_cmd"   main -> worker: { cmd = "check" | "download" | "quit" }
+--   "update_check_state" worker -> main: { status, latest, progress, error }
+--
+-- Nothing here ever blocks or throws into the game loop: when love.thread is
+-- absent (the headless test stub) or the worker cannot run (no curl, Android),
+-- state() simply reports "error" and the UI hides itself.  See the shared
+-- contract in the task brief for the status vocabulary and the file layout.
+--
+-- The release-JSON extraction and the sums parsing are exported as pure
+-- functions (no love.* calls) so plain-Lua tests can cover them, and so the
+-- worker can reuse the exact same code path via love.filesystem.load.
+
+local Check = {}
+
+Check.REPO = "bryanthaboi/pokemon-gen1-recomp-project"
+
+local CMD = "update_check_cmd"
+local STATE = "update_check_state"
+
+-- ---------------------------------------------------------------------------
+-- pure helpers (no love.*) -- also used inside the worker
+-- ---------------------------------------------------------------------------
+
+-- Find the release asset named exactly `name`, returning its download URL and
+-- byte size (or nil when the release has no such asset).
+function Check.pickAsset(assets, name)
+  if type(assets) ~= "table" then return nil end
+  for _, a in ipairs(assets) do
+    if type(a) == "table" and a.name == name then
+      return { url = a.browser_download_url, size = tonumber(a.size) }
+    end
+  end
+  return nil
+end
+
+local function stripV(tag)
+  return (tostring(tag):gsub("^[vV]", ""))
+end
+
+-- Decode a GitHub "releases/latest" response into just the fields the updater
+-- needs.  Returns { version, payloadName, payload, sums } where payload/sums are
+-- { url, size } tables (or nil when that asset is missing), or nil, err when the
+-- document is not a release with a strict X.Y.Z tag.  Json is injected so the
+-- worker can pass a filesystem-loaded codec; on the main thread / in tests it
+-- falls back to require.
+function Check.parseRelease(jsonText, Json)
+  Json = Json or require("src.link.Json")
+  local doc = Json.decode(jsonText)
+  if type(doc) ~= "table" or not doc.tag_name then
+    return nil, "no tag_name in release json"
+  end
+  local version = stripV(doc.tag_name)
+  if not version:match("^%d+%.%d+%.%d+$") then
+    return nil, "release tag is not X.Y.Z: " .. tostring(doc.tag_name)
+  end
+  local payloadName = "gen1recomp-" .. version .. ".love"
+  return {
+    version = version,
+    payloadName = payloadName,
+    payload = Check.pickAsset(doc.assets, payloadName),
+    sums = Check.pickAsset(doc.assets, "sha256sums.txt"),
+  }
+end
+
+-- Parse a shasum -a 256 file ("<hex>  <filename>", bare filenames).  With a
+-- `target` argument returns just that file's hash (or nil); otherwise returns
+-- the whole name -> hash map.  Tolerates the "*" binary marker and "./" prefix.
+function Check.parseSums(text, target)
+  local map = {}
+  for line in tostring(text):gmatch("[^\r\n]+") do
+    local hash, file = line:match("^(%x+)%s+%*?(%S+)")
+    if hash and file then
+      map[(file:gsub("^%./", ""))] = hash:lower()
+    end
+  end
+  if target ~= nil then return map[target] end
+  return map
+end
+
+-- ---------------------------------------------------------------------------
+-- main-thread state machine
+-- ---------------------------------------------------------------------------
+
+function Check.releaseUrl()
+  return "https://github.com/" .. Check.REPO .. "/releases/latest"
+end
+
+local worker           -- the love.thread, once started
+local cmdCh, stateCh   -- the two channels
+local workerReady      -- nil = untried, true = running, false = unavailable
+local requested        -- a check has been asked for this session
+local cache = { status = "idle" } -- newest snapshot from the worker
+
+local function ensureWorker()
+  if workerReady ~= nil then return workerReady end
+  if not (love and love.thread and love.thread.newThread) then
+    workerReady = false
+    return false
+  end
+  local ok, th = pcall(love.thread.newThread, "src/update/check_worker.lua")
+  if not ok or not th then
+    workerReady = false
+    return false
+  end
+  cmdCh = love.thread.getChannel(CMD)
+  stateCh = love.thread.getChannel(STATE)
+  if not pcall(function() th:start() end) then
+    workerReady = false
+    return false
+  end
+  worker = th
+  workerReady = true
+  return true
+end
+
+-- Pull every pending snapshot off the state channel (keeping the newest) and
+-- surface a worker crash as a soft error the UI can hide on.
+local function drain()
+  if stateCh then
+    local msg = stateCh:pop()
+    while msg do
+      cache = msg
+      msg = stateCh:pop()
+    end
+  end
+  if worker then
+    local err = worker:getError()
+    if err then
+      cache = { status = "error", error = tostring(err) }
+    end
+  end
+end
+
+-- Begin (or, on a prior error, retry) an async check.  Safe to call every frame:
+-- once a check is in flight or has reached a terminal state it is a no-op.
+function Check.start()
+  drain()
+  if cache.status == "checking" or cache.status == "downloading" then return end
+  if requested and cache.status ~= "error" and cache.status ~= "idle" then return end
+  if not ensureWorker() then
+    cache = { status = "error", error = "background threads unavailable" }
+    return
+  end
+  requested = true
+  cache = { status = "checking" }
+  cmdCh:push({ cmd = "check" })
+end
+
+-- Current snapshot: { status, latest, progress, error }.  status is one of
+-- idle | checking | uptodate | available | downloading | ready | needs_full | error.
+function Check.state()
+  drain()
+  return {
+    status = cache.status or "idle",
+    latest = cache.latest,
+    progress = cache.progress,
+    error = cache.error,
+  }
+end
+
+-- Start downloading the payload announced by an "available" check.  A no-op in
+-- any other state (the worker still holds the release info from the check).
+function Check.download()
+  drain()
+  if not cmdCh then return end
+  if cache.status ~= "available" then return end
+  cache = { status = "downloading", latest = cache.latest, progress = 0 }
+  cmdCh:push({ cmd = "download" })
+end
+
+return Check

src/update/Semver.lua

@@ -0,0 +1,53 @@
+-- Strict X.Y.Z semantic-version parsing and comparison for the self-updater.
+-- Every part of the updater (Boot, Check, the release picker) agrees on this
+-- one notion of "newer".  Zero requires and no love.* calls, so plain-Lua
+-- tests can exercise it and Boot can use it during the earliest boot step.
+--
+-- We only need the numeric core (major.minor.patch): the engine field is a
+-- bare X.Y.Z in shipped builds and the "0.0.0-dev" placeholder in the working
+-- tree.  Pre-release / build metadata is intentionally not supported -- a
+-- "-dev" or any other suffix makes parse fail, which is the safe answer for
+-- the updater (a dev checkout never counts as a real release to chainload).
+
+local Semver = {}
+
+-- Parse a strict "X.Y.Z" string (an optional leading "v" is allowed) into
+-- { major = n, minor = n, patch = n }.  Returns nil for anything else --
+-- extra components, non-numeric parts, or a trailing suffix like "-dev".
+function Semver.parse(s)
+  if type(s) ~= "string" then return nil end
+  local body = s:match("^v?(.+)$")
+  if not body then return nil end
+  local maj, min, pat = body:match("^(%d+)%.(%d+)%.(%d+)$")
+  if not maj then return nil end
+  return {
+    major = tonumber(maj),
+    minor = tonumber(min),
+    patch = tonumber(pat),
+  }
+end
+
+-- Coerce an argument that is either an already-parsed table or a version
+-- string into a parsed table (or nil).
+local function coerce(v)
+  if type(v) == "table" then return v end
+  return Semver.parse(v)
+end
+
+-- Compare two versions, each a parsed table or an X.Y.Z string.
+-- Returns -1 when a < b, 0 when equal, 1 when a > b.  An unparseable side
+-- sorts as the lowest possible version so a bogus value never wins a "newer"
+-- test; two unparseable sides compare equal.
+function Semver.compare(a, b)
+  local pa, pb = coerce(a), coerce(b)
+  if not pa and not pb then return 0 end
+  if not pa then return -1 end
+  if not pb then return 1 end
+  for _, field in ipairs({ "major", "minor", "patch" }) do
+    if pa[field] < pb[field] then return -1 end
+    if pa[field] > pb[field] then return 1 end
+  end
+  return 0
+end
+
+return Semver

src/update/check_worker.lua

@@ -0,0 +1,343 @@
+-- Background worker for the self-update flow (driven by src/update/Check.lua).
+--
+-- Runs on a love.thread so no curl call, sha256 pass or archive probe ever
+-- touches the render thread.  Talks over two channels:
+--   "update_check_cmd"   in:  { cmd = "check" | "download" | "quit" }
+--   "update_check_state" out: { status, latest, progress, error }
+--
+-- Transport is curl shelled out via io.popen (curl ships on macOS, Windows 10+
+-- and desktop Linux).  Everything is wrapped so a missing curl, an HTTP error,
+-- or a hung download degrades to a "error"/"needs_full" state rather than
+-- blocking or crashing the game.  On Android curl is absent and the check
+-- soft-fails to "error", which the UI hides.
+--
+-- Fresh love threads do not carry the "src.*" package searcher, so sibling
+-- modules are pulled in with love.filesystem.load exactly like
+-- src/core/chip_worker.lua does.  Semver and Boot are authored in parallel; we
+-- load them defensively and degrade (a local semver fallback, a permissive
+-- gate) if they are not present yet.
+
+require("love.thread")
+require("love.filesystem")
+require("love.data")
+require("love.timer")
+require("love.system")
+
+local function loadModule(path)
+  local ok, chunk = pcall(love.filesystem.load, path)
+  if not ok or type(chunk) ~= "function" then return nil end
+  local ok2, mod = pcall(chunk)
+  if not ok2 then return nil end
+  return mod
+end
+
+local Json    = loadModule("src/link/Json.lua")
+local Check   = loadModule("src/update/Check.lua")
+local Version = loadModule("src/core/Version.lua")
+local Semver  = loadModule("src/update/Semver.lua")
+-- Boot's top-level require("src.update.Semver") cannot resolve in this thread
+-- (no src.* searcher), which would leave Boot nil and the minShell gate
+-- permanently permissive.  Seed the loaded table first so it resolves.
+if Semver then package.loaded["src.update.Semver"] = Semver end
+local Boot    = loadModule("src/update/Boot.lua")
+
+local cmdCh   = love.thread.getChannel("update_check_cmd")
+local stateCh = love.thread.getChannel("update_check_state")
+
+local function post(t) stateCh:push(t) end
+
+local osName    = (love.system and love.system.getOS and love.system.getOS()) or ""
+local isWindows = osName == "Windows"
+local saveDir   = love.filesystem.getSaveDirectory()
+
+local API_URL = "https://api.github.com/repos/bryanthaboi/pokemon-gen1-recomp-project/releases/latest"
+
+-- the release picked by the last "check"; kept between commands so "download"
+-- knows the payload url/size/name without re-fetching
+local pending = nil
+
+-- ---------------------------------------------------------------------------
+-- shell / curl
+-- ---------------------------------------------------------------------------
+
+local function shq(s)
+  s = tostring(s)
+  if isWindows then
+    return '"' .. s:gsub('"', '') .. '"'
+  end
+  return "'" .. s:gsub("'", "'\\''") .. "'"
+end
+
+-- run curl and return its response body (text), or nil on any failure.  Used
+-- for the small text resources (release JSON, sums file); -f makes curl exit
+-- non-zero and emit nothing on an HTTP error, so an empty read is a failure.
+local function curlCapture(url)
+  local cmd = "curl -fsSL --connect-timeout 10 --max-time 40 "
+    .. "-H " .. shq("User-Agent: gen1recomp-updater") .. " "
+    .. "-H " .. shq("Accept: application/vnd.github+json") .. " "
+    .. shq(url)
+  local ok, pipe = pcall(io.popen, cmd)
+  if not ok or not pipe then return nil end
+  local out = pipe:read("*a")
+  pipe:close()
+  if not out or out == "" then return nil end
+  return out
+end
+
+local function haveCurl()
+  local ok, pipe = pcall(io.popen, "curl --version")
+  if not ok or not pipe then return false end
+  local out = pipe:read("*a")
+  pipe:close()
+  return out ~= nil and out:find("curl", 1, true) ~= nil
+end
+
+-- ---------------------------------------------------------------------------
+-- version compare (Semver per contract item 5, with a local fallback)
+-- ---------------------------------------------------------------------------
+
+local function parseTriple(s)
+  s = (tostring(s):gsub("^[vV]", ""))
+  local a, b, c = s:match("^(%d+)%.(%d+)%.(%d+)")
+  if not a then return nil end
+  return { tonumber(a), tonumber(b), tonumber(c) }
+end
+
+-- -1 | 0 | 1 for a<b | a==b | a>b
+local function compareVersions(a, b)
+  if Semver and Semver.compare then
+    local ok, r = pcall(Semver.compare, a, b)
+    if ok and r ~= nil then return r end
+  end
+  local pa, pb = parseTriple(a), parseTriple(b)
+  if not pa or not pb then return 0 end
+  for i = 1, 3 do
+    if pa[i] ~= pb[i] then return pa[i] < pb[i] and -1 or 1 end
+  end
+  return 0
+end
+
+-- ---------------------------------------------------------------------------
+-- verification and the shell gate
+-- ---------------------------------------------------------------------------
+
+local function sha256hex(data)
+  local digest = love.data.hash("sha256", data)
+  if type(digest) == "userdata" and digest.getString then
+    digest = digest:getString()
+  end
+  return love.data.encode("string", "hex", digest)
+end
+
+-- Confirm the save-dir file `rel` hashes to the sum listed for `payloadName`.
+local function verifyPayload(rel, payloadName, sumsText)
+  local want = Check.parseSums(sumsText, payloadName)
+  if not want then return false, "no checksum for " .. payloadName end
+  local data = love.filesystem.read(rel)
+  if not data then return false, "cannot read downloaded payload" end
+  if sha256hex(data):lower() ~= want:lower() then
+    return false, "checksum mismatch"
+  end
+  return true
+end
+
+-- true = ok to run, false = payload needs a newer shell (needs_full).  When Boot
+-- cannot probe (module missing during parallel dev, or a probe failure) we allow
+-- it: Boot.run's crash-guard handles a payload that turns out unrunnable.
+local function gatePasses(rel)
+  if not (Boot and Boot.probePayload) then return true end
+  local info = Boot.probePayload(rel)
+  if not info then return true end
+  local shell = (Version and Version.shell) or 1
+  if info.minShell and info.minShell > shell then return false end
+  return true
+end
+
+-- ---------------------------------------------------------------------------
+-- check
+-- ---------------------------------------------------------------------------
+
+local function doCheck()
+  post({ status = "checking" })
+
+  if not haveCurl() then
+    post({ status = "error", error = "curl not available" })
+    return
+  end
+
+  local body = curlCapture(API_URL)
+  if not body then
+    post({ status = "error", error = "release check failed" })
+    return
+  end
+
+  local rel, perr = Check.parseRelease(body, Json)
+  if not rel then
+    post({ status = "error", error = perr or "bad release json" })
+    return
+  end
+  pending = rel
+
+  -- Unstamped dev build: the working tree always looks "newer", so never
+  -- pester the developer with an update (contract item, Check design).
+  local currentEngine = (Version and Version.engine) or "0.0.0-dev"
+  if currentEngine == "0.0.0-dev" then
+    post({ status = "uptodate", latest = rel.version })
+    return
+  end
+
+  if compareVersions(rel.version, currentEngine) <= 0 then
+    post({ status = "uptodate", latest = rel.version })
+    return
+  end
+
+  -- A newer release, but without the .love payload or its sums we cannot do an
+  -- in-place update: send the user to the full installers.
+  if not (rel.payload and rel.payload.url and rel.sums and rel.sums.url) then
+    post({ status = "needs_full", latest = rel.version })
+    return
+  end
+
+  -- Already downloaded on a previous run?  Verify and gate it rather than
+  -- pulling the bytes again.
+  local finalRel = "updates/" .. rel.payloadName
+  if love.filesystem.getInfo(finalRel) then
+    local sums = curlCapture(rel.sums.url)
+    if sums and verifyPayload(finalRel, rel.payloadName, sums) then
+      if gatePasses(finalRel) == false then
+        love.filesystem.remove(finalRel)
+        post({ status = "needs_full", latest = rel.version })
+        return
+      end
+      post({ status = "ready", latest = rel.version })
+      return
+    end
+    -- stale / corrupt: drop it and offer a fresh download
+    love.filesystem.remove(finalRel)
+  end
+
+  post({ status = "available", latest = rel.version })
+end
+
+-- ---------------------------------------------------------------------------
+-- download
+-- ---------------------------------------------------------------------------
+
+-- Launch curl in the background writing `partAbs`, touching `doneAbs` when it
+-- exits.  Returns without waiting so the caller can poll the growing file for
+-- progress.  We deliberately do not capture curl's exit code: an incomplete or
+-- failed transfer simply fails the checksum below, which is the real gate.
+local function launchDownload(url, partAbs, doneAbs)
+  if isWindows then
+    -- a tiny batch file sidesteps cmd.exe's nested-quote madness
+    local batRel = "updates/dl.bat"
+    love.filesystem.write(batRel,
+      "@echo off\r\n"
+      .. "curl -fsSL --connect-timeout 15 --max-time 900 -o \""
+      .. partAbs .. "\" \"" .. url .. "\"\r\n"
+      .. "type nul > \"" .. doneAbs .. "\"\r\n")
+    os.execute('start "" /b ' .. shq(saveDir .. "/" .. batRel))
+  else
+    -- ( ... ) & backgrounds the whole group so os.execute returns at once
+    os.execute("( curl -fsSL --connect-timeout 15 --max-time 900 -o "
+      .. shq(partAbs) .. " " .. shq(url)
+      .. " ; touch " .. shq(doneAbs) .. " ) >/dev/null 2>&1 &")
+  end
+end
+
+local function doDownload()
+  if not (pending and pending.payload and pending.payload.url) then
+    post({ status = "error", error = "nothing to download" })
+    return
+  end
+  local rel = pending
+  post({ status = "downloading", latest = rel.version, progress = 0 })
+
+  love.filesystem.createDirectory("updates")
+  local partRel  = "updates/" .. rel.payloadName .. ".part"
+  local doneRel  = "updates/" .. rel.payloadName .. ".done"
+  local finalRel = "updates/" .. rel.payloadName
+  love.filesystem.remove(partRel)
+  love.filesystem.remove(doneRel)
+
+  local partAbs = saveDir .. "/updates/" .. rel.payloadName .. ".part"
+  local doneAbs = saveDir .. "/updates/" .. rel.payloadName .. ".done"
+  local size    = rel.payload.size or 0
+
+  launchDownload(rel.payload.url, partAbs, doneAbs)
+
+  -- poll the .part size for progress until curl drops the done-marker; a
+  -- stalled or run-away transfer breaks out and lets verification fail cleanly
+  local waited, lastSize, lastChange = 0, -1, 0
+  while true do
+    if love.filesystem.getInfo(doneRel) then break end
+    local pinfo = love.filesystem.getInfo(partRel)
+    local cur = (pinfo and pinfo.size) or 0
+    if size > 0 then
+      local p = cur / size
+      if p > 0.999 then p = 0.999 end -- 1.0 is reserved for "ready"
+      post({ status = "downloading", latest = rel.version, progress = p })
+    else
+      post({ status = "downloading", latest = rel.version })
+    end
+    if cur ~= lastSize then lastSize, lastChange = cur, waited end
+    if waited - lastChange > 60 then break end -- 60s with no growth: give up
+    if waited > 960 then break end             -- absolute ceiling
+    love.timer.sleep(0.25)
+    waited = waited + 0.25
+  end
+  love.filesystem.remove(doneRel)
+
+  local sums = curlCapture(rel.sums and rel.sums.url or "")
+  if not sums then
+    love.filesystem.remove(partRel)
+    post({ status = "error", error = "checksum fetch failed" })
+    return
+  end
+
+  local ok, verr = verifyPayload(partRel, rel.payloadName, sums)
+  if not ok then
+    love.filesystem.remove(partRel)
+    post({ status = "error", error = verr or "verification failed" })
+    return
+  end
+
+  if gatePasses(partRel) == false then
+    love.filesystem.remove(partRel)
+    post({ status = "needs_full", latest = rel.version })
+    return
+  end
+
+  -- finalize: rename the verified .part to its real name (fall back to a
+  -- love.filesystem copy if os.rename is unavailable on this platform)
+  if not os.rename(partAbs, saveDir .. "/updates/" .. rel.payloadName) then
+    local data = love.filesystem.read(partRel)
+    if not data then
+      post({ status = "error", error = "finalize failed" })
+      return
+    end
+    love.filesystem.write(finalRel, data)
+    love.filesystem.remove(partRel)
+  end
+
+  post({ status = "ready", latest = rel.version })
+end
+
+-- ---------------------------------------------------------------------------
+-- command loop
+-- ---------------------------------------------------------------------------
+
+while true do
+  local cmd = cmdCh:demand() -- blocks until the main thread pushes work
+  if type(cmd) == "table" then
+    if cmd.cmd == "quit" then
+      break
+    elseif cmd.cmd == "check" then
+      local ok, err = pcall(doCheck)
+      if not ok then post({ status = "error", error = tostring(err) }) end
+    elseif cmd.cmd == "download" then
+      local ok, err = pcall(doDownload)
+      if not ok then post({ status = "error", error = tostring(err) }) end
+    end
+  end
+end

src/world/FieldDefaults.lua

@@ -116,6 +116,16 @@ FieldDefaults.FIELD = {
   badgeGates = { ROUTE_22_GATE = { passedFlag = "PASSED_ROUTE22_GATE" } },
   -- VermilionGymSetDoorTile opens the motorized door once both locks are hit
   hiddenExtras = {
+    -- PrintTrashText bins (#188); seeds stale caches missing the key
+    printTrash = {
+      SS_ANNE_KITCHEN = {
+        { x = 13, y = 5, facing = "down" },
+        { x = 13, y = 7, facing = "down" },
+      },
+      VERMILION_GYM = {
+        { x = 6, y = 1, facing = "down" },
+      },
+    },
     trashCans = { map = "VERMILION_GYM",
                   doorBlock = { bx = 2, by = 2, block = 5 } },
   },

src/world/Map.lua

@@ -204,6 +204,16 @@ function Map:isWalkableCell(cx, cy)
 end
 
 function Map:isGrassCell(cx, cy)
+  -- Off-map cells never count as tall grass (issue #217).  cellTile
+  -- border-extends out-of-bounds coordinates with the map's borderBlock,
+  -- and some border blocks (e.g. ROUTE_1's block 11) have the grass tile
+  -- ($52 = 82) in their bottom row -- filler scenery, never standable
+  -- grass.  During a map-connection seam step crossConnection parks the
+  -- player one cell before the entry point (cellY = -1 crossing Viridian
+  -- City -> Route 1), so without this guard the feet-overdraw painted an
+  -- animated grass tuft over the player's head for the whole step.  pokered
+  -- only ever reads $52 from loaded map tiles, not the border filler.
+  if not self:inBounds(cx, cy) then return false end
   local grass = self.tileset.grassTile
   return grass ~= nil and self:cellTile(cx, cy) == grass
 end
@@ -223,6 +233,12 @@ function Map:setBlock(bx, by, block)
   self.def.blocks[by * self.def.width + bx + 1] = block
 end
 
+-- true if the cell's collision tile is a door tile
+-- (pokered IsPlayerStandingOnDoorTile)
+function Map:isDoorTileCell(cx, cy)
+  return self.doorTiles[self:cellTile(cx, cy)] or false
+end
+
 -- true if the cell's collision tile is a door or warp-activating tile
 function Map:isWarpTileCell(cx, cy)
   local t = self:cellTile(cx, cy)

src/world/NPC.lua

@@ -101,9 +101,18 @@ function NPC:walkPhase()
   return (p >= 4 and p < 12) and 1 or 0
 end
 
+-- Same contract as Player:pose -- the sheet, position, facing and step
+-- phase this frame renders to -- so a render pipeline can pose an NPC
+-- without caring which kind of entity it is.  An NPC never hops, so the
+-- trailing hop flag is always false.
+function NPC:pose()
+  return self.sprite, self.px, self.py, self.facing,
+         self:walkPhase(), self.stepFlip, false
+end
+
 function NPC:draw(camX, camY)
-  self.sprite:draw(self.px, self.py, camX, camY, self.facing,
-                   self:walkPhase(), self.stepFlip)
+  local sprite, px, py, facing, phase, flip = self:pose()
+  sprite:draw(px, py, camX, camY, facing, phase, flip)
 end
 
 return NPC

src/world/OverworldController.lua

@@ -12,6 +12,7 @@ local Map = require("src.world.Map")
 local MapLoader = require("src.world.MapLoader")
 local NPC = require("src.world.NPC")
 local PaletteFX = require("src.render.PaletteFX")
+local Pipelines = require("src.render.Pipelines")
 local Player = require("src.world.Player")
 local Runtime = require("src.mods.Runtime")
 local Screens = require("src.ui.Screens")
@@ -20,6 +21,7 @@ local Tilt = require("src.render.Tilt")
 local TextBox = require("src.render.TextBox")
 local Transition = require("src.render.Transition")
 local Warp = require("src.world.Warp")
+local Zoom = require("src.render.Zoom")
 
 -- isOverworld marks the live world state for WorldAPI's stack scan
 local OverworldState = { isOpaque = true, isOverworld = true }
@@ -220,17 +222,31 @@ function OverworldState:setMap(mapId, x, y, facing, opts)
     self.map.renderer:rebuild()
     self.cutBlocks[mapId] = nil
   end
-  -- Silph Co card key doors: the .blk layouts ship with the doorways
-  -- open; each floor's map script stamps the closed door block on load
-  -- until its unlock event is set (scripts/SilphCo2F.asm
-  -- SilphCo2FGateCallbackScript et al., closed blocks $54/$5f/$20)
+  -- Silph Co card key doors + Rocket Hideout elevator gates: the .blk
+  -- layouts ship with the doorways open; each floor's map script stamps
+  -- the closed door block on load until its unlock event is set
+  -- (scripts/SilphCo2F.asm SilphCo2FGateCallbackScript et al., closed
+  -- blocks $54/$5f/$20; scripts/RocketHideoutB1F.asm +
+  -- RocketHideoutB4F.asm ...DoorCallbackScript, closed blocks $54/$2d over
+  -- the lift doorway).  A door opens on its single `event`, or on `events`
+  -- when every listed flag must be set (Rocket Hideout B4F's lift gate
+  -- needs both guard trainers beaten -- CheckBothEventsSet).
   local closedDoors = FieldDefaults.fieldValue(Game.data, "cardKeyDoors",
                                                "closedDoors")
   local floorDoors = closedDoors and closedDoors[mapId]
   if floorDoors then
     local stamped = false
     for _, door in ipairs(floorDoors) do
-      local want = Game.save.flags[door.event] and door.open or door.block
+      local open
+      if door.events then
+        open = true
+        for _, ev in ipairs(door.events) do
+          if not Game.save.flags[ev] then open = false break end
+        end
+      else
+        open = Game.save.flags[door.event]
+      end
+      local want = open and door.open or door.block
       if self.map:blockAt(door.bx, door.by) ~= want then
         self.map:setBlock(door.bx, door.by, want)
         stamped = true
@@ -716,16 +732,13 @@ function OverworldState:update(dt)
   end
   if self.healAnim then
     local ha = self.healAnim
-    local Music = require("src.core.Music")
-    if ha.jinglePlaying and not ha.jingleDone then
-      ha.jingleDone = not Music.oneShotPlaying()
-    end
     local ev = OverworldState.stepHealAnim(ha)
     if ev == "ball" then
       require("src.core.Sound").play(Game.data, "Healing_Machine")
     elseif ev == "jingle" then
-      ha.jinglePlaying = Music.playOnce(Game.data, "Music_PkmnHealed")
-      ha.jingleDone = not ha.jinglePlaying
+      -- playOnce restores the map theme when the jingle ends; we no longer
+      -- block the fighting-fit text on that (#157)
+      require("src.core.Music").playOnce(Game.data, "Music_PkmnHealed")
     elseif ev == "done" then
       local done = ha.onDone
       self.healAnim = nil
@@ -750,6 +763,27 @@ function OverworldState:update(dt)
     end
   end
 
+  -- Dig/Teleport/Escape-Rope departure spin (beginTeleportOut).  The sprite
+  -- spins UP out of the map before the fade (player_animations.asm
+  -- _LeaveMapAnim -> PlayerSpinWhileMovingUp + SFX_TELEPORT_EXIT_1), the
+  -- mirror of Fly's flyAnim lead-in above.  Only when the spin finishes does
+  -- warpToHealPoint push the fade + warp, so the arrival spin-down lands the
+  -- player OUTSIDE the last Pokemon Center door (#196).  player.spinFrames
+  -- decrements in lockstep in Player:update, so the rising spin ends here too.
+  if self.teleportOut then
+    self.teleportOut.frames = self.teleportOut.frames - 1
+    if self.teleportOut.frames <= 0 then
+      local onDone = self.teleportOut.onDone
+      self.teleportOut = nil
+      self.player.spinning = false
+      self.player.spinFrames = nil
+      self.player.spinRise = nil
+      self.player.inputLocked = false
+      self:warpToHealPoint(onDone, { arrive = "teleport" })
+      return
+    end
+  end
+
   -- delayed one-shot SFX (the teleport-in spin's second note)
   if self.delaySfx then
     self.delaySfx.frames = self.delaySfx.frames - 1
@@ -788,7 +822,7 @@ function OverworldState:update(dt)
   -- escort then walks an extra tile before PlayerEntryMovementRLE, and
   -- the player lands on desk Oak.
   local scripted = self.runner:isRunning() or #self.scriptMoves > 0
-                   or self.engaging or self.emote
+                   or self.engaging or self.emote or self.teleportOut
   if not scripted and not self.transitioning then
     self:checkTrainerSight()
     -- CheckFightingMapTrainers (home/trainers.asm) zeroes hJoyHeld and
@@ -796,7 +830,7 @@ function OverworldState:update(dt)
     -- direction handling (JoypadOverworld runs the map script first) --
     -- the player can never start another step after being spotted.
     scripted = self.runner:isRunning() or #self.scriptMoves > 0
-               or self.engaging or self.emote
+               or self.engaging or self.emote or self.teleportOut
   end
   if not scripted and not self.transitioning then
     self:handleInput()
@@ -855,6 +889,21 @@ function OverworldState:dirHeld()
       or input:isDown("left") or input:isDown("right")
 end
 
+-- The warp cell the player WARPED IN on is inert until they physically step
+-- off it: standing on it, or bonking a wall/edge from it, must not re-fire a
+-- warp (CheckWarpsNoCollision's arrival-disable; see setMap where
+-- warpEntryCell/justWarped are set and onStepComplete where they clear).
+-- Both stand-still warp triggers -- the map-edge exit (checkEdgeExit) and the
+-- blocked-step collision warp (handleInput) -- must consult this, or a corner
+-- staircase whose warp tile sits on the map edge (Red's-house (7,1)) bounces
+-- floors every input frame (issue #230).
+function OverworldState:onWarpArrivalCell()
+  if self.justWarped then return true end
+  local entry = self.warpEntryCell
+  return entry ~= nil and self.player.cellX == entry.x
+         and self.player.cellY == entry.y
+end
+
 function OverworldState:handleInput()
   local input = Game.input
 
@@ -876,10 +925,11 @@ function OverworldState:handleInput()
         if self:checkBoulderPush(dir) then return end
       end
       local result, why = self.player:tryMove(dir, self.map, self.entities)
-      if result == "blocked" then
-        -- a collision while standing on a warp square fires the warp
-        -- when the extra check passes (CheckWarpsCollision: route-gate
-        -- doorways, dock entrances, ...)
+      -- a collision while standing on a warp square fires the warp when the
+      -- extra check passes (CheckWarpsCollision: route-gate doorways, dock
+      -- entrances, ...) -- but never on the inert cell we just warped in on
+      -- (issue #230), which the completed-step path guards the same way.
+      if result == "blocked" and not self:onWarpArrivalCell() then
         local w = Warp.onCollision(self.map, Game.data.field.warpCarpets,
                                    self.player.cellX, self.player.cellY, dir)
         if w then
@@ -1010,6 +1060,11 @@ function OverworldState:checkEdgeExit(dir)
 
   local w = Warp.onEdge(self.map, p.cellX, p.cellY, dir)
   if w then
+    -- ...but not while still standing on the warp cell we just arrived on
+    -- (issue #230): fall through so pushing into the edge bonks (SFX +
+    -- walk-in-place) instead of instantly re-warping.  A real step onto an
+    -- exit-carpet edge cleared warpEntryCell first, so those still fire.
+    if self:onWarpArrivalCell() then return false end
     self:takeWarp(w.def)
     return true
   end
@@ -1257,6 +1312,37 @@ function OverworldState:flyTo(mapId)
   self.flyDest = { map = mapId, x = spot.x, y = spot.y }
 end
 
+-- Dig / Teleport / Escape Rope departure animation, then land OUTSIDE the
+-- last Pokemon Center door like Fly (#196).  pokered's _LeaveMapAnim
+-- (engine/overworld/player_animations.asm) plays SFX_TELEPORT_EXIT_1 and
+-- spins the player while it rises up off the map (PlayerSpinWhileMovingUp)
+-- before the palettes fade; Fly's bird lead-in (flyTo/flyAnim) is the
+-- analogous departure this mirrors.  When the spin finishes (the teleportOut
+-- countdown in OverworldState:update), warpToHealPoint pushes the fade + warp
+-- with arrive="teleport" so the sprite spins back DOWN in front of the town
+-- PC door.  Shared by the party-menu DIG/TELEPORT action and BagMenu's
+-- ESCAPE ROPE so all three animate identically.
+function OverworldState:beginTeleportOut(onDone)
+  if not Game.save.lastHeal then
+    -- a save that has never visited a Pokemon Center has no heal point to
+    -- warp to; skip the animation entirely (matches the old guard that did
+    -- nothing when lastHeal was absent) instead of spinning into a nil warp
+    if onDone then onDone() end
+    return
+  end
+  require("src.core.Sound").play(Game.data, "Teleport_Exit1")
+  self.player.surfing = false
+  self.player.inputLocked = true
+  -- rising spin: the mirror of the arrival spin-drop set in startWarpTo, so
+  -- spinRise lifts the sprite (Player:pose) while spinFrames counts down
+  self.player.spinning = true
+  self.player.spinTimer = 0
+  self.player.spinFrames = 48
+  self.player.spinTotal = 48
+  self.player.spinRise = true
+  self.teleportOut = { frames = 48, onDone = onDone }
+end
+
 function OverworldState:npcAtCell(cx, cy)
   for _, npc in ipairs(self.npcs) do
     if (npc.cellX == cx and npc.cellY == cy) or
@@ -1475,7 +1561,17 @@ function OverworldState:tryHiddenObject(fx, fy)
   -- Pokémon Center PCs and other PC tiles
   for _, h in ipairs(extras.pcTiles[self.map.id] or {}) do
     if h.x == fx and h.y == fy and (not h.facing or h.facing == facing) then
-      self:openPC()
+      if self.map.id == "REDS_HOUSE_2F" then
+        -- The player's bedroom PC is the one location in Red/Blue whose PC
+        -- callback is OpenRedsPC (engine/events/hidden_objects/players_pc.asm),
+        -- which runs the PlayerPC predef directly -- item storage, no
+        -- SOMEONE'S/BILL'S PC main menu (DisplayPCMainMenu).  Every other
+        -- pcTile is a Pokémon Center-style PC that shows the multi-PC menu. (#228)
+        require("src.core.Sound").play(Game.data, "Turn_On_PC")
+        Screens.push(Game, "PlayerPC")
+      else
+        self:openPC()
+      end
       return true
     end
   end
@@ -1509,6 +1605,15 @@ function OverworldState:tryHiddenObject(fx, fy)
     end
   end
 
+  -- PrintTrashText: SS Anne kitchen + Vermilion Gym non-puzzle can
+  for _, h in ipairs(extras.printTrash and extras.printTrash[self.map.id] or {}) do
+    if h.x == fx and h.y == fy then
+      Game.stack:push(TextBox.new(Game, txt._VermilionGymTrashText
+        or "Nope, there's\nonly trash here."))
+      return true
+    end
+  end
+
   -- the Vermilion Gym trash can lock puzzle
   if self.map.id == "VERMILION_GYM" then
     for _, h in ipairs(extras.trashCans.cans or {}) do
@@ -1999,8 +2104,12 @@ function OverworldState:talkTo(npc)
     return
   end
 
-  -- item balls (object_event item argument)
-  if d.item then
+  -- item balls (object_event item argument).  A payload id of "0" is
+  -- pokered's ITEM_NONE sentinel: the ROM object sets the 0x80 "has item"
+  -- bit but names item 0, so it is a plain text object, not an item ball
+  -- (e.g. Blue's House wall Town Map / walking Daisy, #11).  Lua treats
+  -- the string "0" as truthy, so screen it out and fall through to text.
+  if d.item and d.item ~= "0" and d.item ~= 0 then
     if not require("src.inventory.Bag").add(Game.save, d.item, 1) then
       Game.stack:push(TextBox.new(Game, "You can't carry\nany more items!"))
       return
@@ -2188,13 +2297,10 @@ function OverworldState:dexRating()
   Game.stack:push(TextBox.new(Game, completion .. "\f" .. rating))
 end
 
--- AnimateHealingMachine (engine/overworld/healing_machine.asm): the
--- monitor lights, then one ball per party mon appears every 30 frames
--- (SFX_HEALING_MACHINE each); the healed jingle plays while the machine
--- sprites flash 8 times (an OBP1 xor every 10 frames), then a 32-frame
--- beat once the jingle ends.  Pure per-frame step over the ha table
--- ({ balls, lit, timer, visible, jingleDone }); returns "ball"/"jingle"/
--- "done" when the caller must fire the matching side effect.
+-- AnimateHealingMachine (engine/overworld/healing_machine.asm): balls
+-- every 30 frames, then jingle + FlashSprite8Times (8 x 10).  #157: skip
+-- pokered's post-flash .waitLoop2 / DelayFrames 32 so fighting-fit is
+-- immediate; jingle still plays and restoreMap runs when it ends.
 function OverworldState.stepHealAnim(ha)
   ha.timer = ha.timer + 1
   ha.phase = ha.phase or "balls"
@@ -2217,17 +2323,11 @@ function OverworldState.stepHealAnim(ha)
       ha.visible = not ha.visible
       ha.flashes = ha.flashes + 1
       if ha.flashes >= 8 then
-        ha.phase = "wait"
         ha.visible = true
+        ha.phase = "done"
+        return "done"
       end
     end
-  elseif ha.phase == "wait" then
-    -- .waitLoop2: hold until the jingle ends, then 32 more frames
-    if not ha.jingleDone then
-      ha.timer = 0
-    elseif ha.timer >= 32 then
-      return "done"
-    end
   end
 end
 
@@ -2403,19 +2503,34 @@ function OverworldState:checkVictoryRewards(trainerClass, partyIndex)
       Commands.hide_object(ctx, entry[1], entry[2])
     end
   end
-  local lines = {}
   if reward.badge then
     Game.save.inventory[reward.badge] = 1
-    local name = Game.data.items[reward.badge] and Game.data.items[reward.badge].name
-                 or reward.badge
-    table.insert(lines, ("%s received\nthe %s!"):format(Game.save.player.name, name))
   end
   if reward.item then
     local inv = Game.save.inventory
     inv[reward.item] = (inv[reward.item] or 0) + 1
-    local name = Game.data.items[reward.item] and Game.data.items[reward.item].name
-                 or reward.item
-    table.insert(lines, ("%s received\n%s!"):format(Game.save.player.name, name))
+    local idef = Game.data.items[reward.item]
+    -- GiveItem -> CopyToStringBuffer for "{RAM:wStringBuffer}" received texts
+    Game.stringBuffer = idef and idef.name or reward.item
+  end
+  local lines = {}
+  if reward.dialogue then
+    local text = Game.data.text or {}
+    for _, label in ipairs(reward.dialogue) do
+      if text[label] and text[label] ~= "" then
+        table.insert(lines, text[label])
+      end
+    end
+  elseif reward.badge or reward.item then
+    if reward.badge then
+      local name = Game.data.items[reward.badge] and Game.data.items[reward.badge].name
+                   or reward.badge
+      table.insert(lines, ("%s received\nthe %s!"):format(Game.save.player.name, name))
+    end
+    if reward.item then
+      local name = Game.stringBuffer or reward.item
+      table.insert(lines, ("%s received\n%s!"):format(Game.save.player.name, name))
+    end
   end
   if #lines > 0 then
     Game.stack:push(TextBox.new(Game, table.concat(lines, "\f")))
@@ -2437,6 +2552,8 @@ end
 -- interposed NPCs / walls -- but unsigned 8-bit Y makes a sprite exactly 4
 -- tiles north of the player sit at Y=$fc, so |$3c-$fc|=$c0 and a range-4
 -- DOWN trainer does not engage that tile (Route 9 Bug Catcher / issue #76).
+-- Off-screen sprites (IMAGEINDEX=$ff) never engage: without that gate, the
+-- same 8-bit wrap makes far same-row trainers look in-range (#153/#183).
 local PLAYER_SCREEN_X, PLAYER_SCREEN_Y = 0x40, 0x3c
 local function u8(n) return n % 256 end
 local function calcDiff(a, b)
@@ -2452,6 +2569,14 @@ local function trainerSightPixelDist(npc, player, horizontal)
                   u8(PLAYER_SCREEN_Y + (npc.cellY - player.cellY) * 16))
 end
 
+-- CheckSpriteAvailability (movement.asm): wXCoord/wYCoord = player - 4;
+-- visible when sprite is in [wCoord, wCoord + SCREEN_*/2 - 1] (GB 10x9).
+local function trainerSpriteOnScreen(npc, player)
+  local dx = npc.cellX - player.cellX
+  local dy = npc.cellY - player.cellY
+  return dx >= -4 and dx <= 5 and dy >= -4 and dy <= 4
+end
+
 -- STAY trainers with a facing spot the player crossing their line of
 -- sight (range from the extracted trainer headers), walk up and battle.
 function OverworldState:checkTrainerSight()
@@ -2464,7 +2589,8 @@ function OverworldState:checkTrainerSight()
     -- walkers included (they sight between steps)
     if d.trainerClass and not npc.moving
        and not self:trainerDefeated(npc)
-       and not mapScripts.talkScript(self.map.id, d.text) then
+       and not mapScripts.talkScript(self.map.id, d.text)
+       and trainerSpriteOnScreen(npc, p) then
       local header = Game.data:trainerHeader(self.map.def.label, d.index)
       local range = header and header.range or 0
       local vec = DIRVEC[npc.facing]
@@ -3131,7 +3257,9 @@ function OverworldState:afterBattle(result, battle)
               lead and lead.stats.hp or 0)
   local Evolution = require("src.pokemon.Evolution")
   local function evolutions()
-    Evolution.checkParty(Game)
+    -- Only mons that gained a level this battle (EXP.ALL included).
+    -- Scanning the whole party re-offered B-cancelled evolutions forever (#213).
+    Evolution.checkParty(Game, nil, battle and battle.leveledUp)
   end
   if result == "lose" then
     local oaksLabRival = battle and battle.oppClass == "OPP_RIVAL1"
@@ -3208,7 +3336,7 @@ function OverworldState:takeWarp(warpDef)
     self:startWarpTo(destMap, x, y, facing)
     return
   end
-  self.doorWarp = true -- door SFX + outdoor walk-out step
+  self.doorWarp = true -- door SFX + PlayerStepOutFromDoor walk-out
   self:startWarpTo(destMap, x, y, facing)
 end
 
@@ -3232,11 +3360,32 @@ function OverworldState:warpToHealPoint(onDone, opts)
   -- HandleFlyWarpOrDungeonWarp + DisplayPlayerBlackedOutText both clear
   -- BIT_ALWAYS_ON_BIKE (home/overworld.asm / home/text_script.asm)
   Game.save.forcedBike = nil
-  if opts and opts.arrive == "teleport" then
+  local map, x, y = heal.map, heal.x, heal.y
+  local teleport = opts and opts.arrive == "teleport"
+  if teleport then
     self.arriveWarp = "teleport"
+    -- Dig/Teleport/Escape Rope land OUTSIDE at the last Pokemon Center TOWN
+    -- door, like Fly (#196) -- NOT the interior heal cell a blackout returns
+    -- to.  pret routes escape-warp and blackout both through wLastBlackoutMap
+    -- (both appear inside in front of the nurse), but this port has decided
+    -- the escape-warp destination is the town PC door.  Prefer the canonical
+    -- Fly landing (field.flyWarps, one tile south of the PC door warp), else
+    -- the remembered outdoor door cell; fall back to the interior heal cell
+    -- only for an old save with no recorded outdoor.
+    local out = heal.outdoor
+    if out then
+      local fw = (Game.data.field.flyWarps or {})[out.id]
+      map = out.id
+      x = fw and fw.x or out.x
+      y = fw and fw.y or out.y
+    end
   end
-  self:startWarpTo(heal.map, heal.x, heal.y, "down", onDone)
-  if heal.outdoor then
+  self:startWarpTo(map, x, y, "down", onDone)
+  -- Blackouts land at the interior heal cell, so re-point LAST_MAP exits at
+  -- the remembered town door.  The teleport branch already lands ON that
+  -- outdoor map, so startWarpTo remembers it on the next exit; re-pointing
+  -- here would wrongly steer exits away from where the player now stands.
+  if heal.outdoor and not teleport then
     self:rememberOutdoor(heal.outdoor.id, heal.outdoor.x, heal.outdoor.y)
   end
 end
@@ -3293,15 +3442,24 @@ function OverworldState:startWarpTo(mapId, x, y, facing, onDone, opts)
       local outdoor = Map.isOutdoor(self.map.def)
       require("src.core.Sound").play(Game.data,
                                      outdoor and "Go_Outside" or "Go_Inside")
-      -- stepping out of an outdoor door/cave entrance (the original's
-      -- walk-out). Auto-walk leaves the mat, so the arrival disable
+      -- PlayerStepOutFromDoor (engine/overworld/auto_movement.asm): any
+      -- warp that lands on a door tile auto-steps south once, indoor or
+      -- outdoor. Auto-walk leaves the mat, so the arrival disable
       -- (warpEntryCell / justWarped) is unnecessary -- and would let you
       -- stand on the door without re-entering if you hold back into it.
-      if outdoor and self.player.facing == "down"
-         and self.map:isWarpTileCell(self.player.cellX, self.player.cellY) then
-        self.warpEntryCell = nil
-        self.justWarped = false
-        self:scriptMove(self.player, "down", 1)
+      -- The walk-out is a simulated d-pad press (wSimulatedJoypadStates),
+      -- not a forced move, so it obeys collision: on a landing with a
+      -- solid cell south of the door (the mansion stair landings back
+      -- onto shelves) the step bumps and the player stays on the door,
+      -- arrival disable intact, instead of clipping into the wall.
+      if self.map:isDoorTileCell(self.player.cellX, self.player.cellY) then
+        if Collision.canMove(self.map, self.entities, self.player, "down") then
+          self.warpEntryCell = nil
+          self.justWarped = false
+          self:scriptMove(self.player, "down", 1)
+        else
+          self.player.facing = "down"
+        end
       end
     end
   end, function()
@@ -3539,11 +3697,22 @@ function OverworldState:drawWorld()
   -- tilt is active).  So the ground draw calls below never change with tilt;
   -- only the sprite/FX draw path below them branches.  The sorts below only
   -- reorder (no draws), so they run once for both paths.
-  local tilt = Tilt.active()
-  self.map.renderer:drawBorderFill(cam.x, bgY, vw, vh)
-  self.map.renderer:draw(cam.x, bgY, vw, vh)
-  for _, nb in ipairs(self.neighbors) do
-    nb.map.renderer:drawMapOnly(cam.x - nb.ox, bgY - nb.oy, vw, vh)
+  -- A render pipeline (src/render/Pipelines.lua) replaces the ground draw
+  -- entirely with geometry of its own, so it is decided before tilt and
+  -- wins over it.  It falls back to the tilt/flat path whenever it cannot
+  -- run this frame -- headless, a driver with no depth canvas, or a mod
+  -- that threw -- so no caller ever sees a blank frame.
+  local pipelineId = Pipelines.worldPipeline()
+  local tilt = (not pipelineId) and Tilt.active()
+  -- the pipeline's finished world image, once it has run; nil keeps every
+  -- path below on the vanilla flat/tilt draw
+  local override
+  if not pipelineId then
+    self.map.renderer:drawBorderFill(cam.x, bgY, vw, vh)
+    self.map.renderer:draw(cam.x, bgY, vw, vh)
+    for _, nb in ipairs(self.neighbors) do
+      nb.map.renderer:drawMapOnly(cam.x - nb.ox, bgY - nb.oy, vw, vh)
+    end
   end
   -- per-billboard SGB palette source; only needed (and only paid for) when
   -- tilting.  nil headless / on stale palettes -> billboards go uncolorized.
@@ -3774,7 +3943,114 @@ function OverworldState:drawWorld()
     end
   end
 
-  if not tilt then
+  if pipelineId then
+    -- === PIPELINE PATH: a mod owns the world pass. ======================
+    -- It renders terrain and characters however it likes and hands back one
+    -- window-resolution image; the field FX stay ordinary 2D draws
+    -- composited on top by ctx.drawFx, each anchored to where its ground
+    -- point projects under the pipeline's own camera.  That is the direct
+    -- analogue of what :billboard does for tilt, and it keeps exactly one
+    -- copy of every effect: the closures above are the ones that run.
+    local pw, ph = love.graphics.getDimensions()
+    local pscale = Zoom.scale(Game.renderer:fitScale())
+    local ctx = {
+      state = self, cam = cam, vw = vw, vh = vh, bgY = bgY,
+      width = pw, height = ph, scale = pscale,
+      level = Pipelines.level(pipelineId),
+      -- the SGB world palette a map draws under; nil in the true-colour
+      -- modes, whose art is already baked (and must not be re-mapped)
+      paletteFor = function(map)
+        return PaletteFX.pal(Game.data, self:paletteNameFor(map or self.map))
+      end,
+      spriteColors = function(map)
+        if PaletteFX.usesGbcPack() then return nil end
+        return PaletteFX.pal(Game.data, self:paletteNameFor(map or self.map))
+      end,
+      fx = { heal = fxHeal, dust = fxDust, cutTree = fxCutTree,
+             emote = fxEmote, dark = fxDark, bird = fxBird, rod = fxRod },
+    }
+    -- Draw every active field FX into the finished scene.  `project(wx, wy)`
+    -- maps a world point to canvas pixels (nil when it is behind the
+    -- camera) and `scale` is canvas pixels per world pixel; the pipeline
+    -- owns the camera, this owns where each effect belongs and how the
+    -- closures' flat coordinates are slid onto the projected anchor.
+    -- Deliberately unscaled by depth, like :billboard: an effect keeps its
+    -- crisp authored size and only its anchor moves.
+    ctx.drawFx = function(project, scale)
+      scale = scale or pscale
+      local colors = ctx.spriteColors()
+      local function at(drawFn, wx, wy)
+        if not drawFn then return end
+        local sx, sy = project(wx, wy)
+        if not sx then return end          -- behind the camera
+        local shader = colors and PaletteFX.shader() or nil
+        if shader then
+          PaletteFX.sendColors(shader, colors)
+          love.graphics.setShader(shader)
+        end
+        -- the closures draw relative to the flat foot; slide that onto the
+        -- projected anchor, in world-pixel units inside the scaled transform
+        local fx, fy = wx - cam.x, wy - cam.y
+        love.graphics.push()
+        love.graphics.scale(scale, scale)
+        love.graphics.translate(sx / scale - fx, sy / scale - fy)
+        drawFn()
+        love.graphics.pop()
+        if shader then love.graphics.setShader() end
+      end
+      -- ground-hugging effects sit on the cell they belong to
+      if self.dustAnim then
+        at(fxDust, self.dustAnim.x * 16 + 8, self.dustAnim.y * 16 + 8)
+      end
+      if self.cutAnim then
+        at(fxCutTree, self.cutAnim.x * 16 + 8, self.cutAnim.y * 16 + 16)
+      end
+      if self.healAnim then
+        at(fxHeal, self.healAnim.px + 8, self.healAnim.py + 16)
+      end
+      -- standing effects anchor at the foot of whoever they belong to
+      if self.emote and self.emote.npc then
+        at(fxEmote, self.emote.npc.px + 8, self.emote.npc.py + 16)
+      end
+      if self.flyAnim then
+        at(fxBird, self.player.px + 8, self.player.py + 16)
+      end
+      if self.fishing then
+        at(fxRod, self.player.px + 8, self.player.py + 16)
+      end
+      -- Rock Tunnel darkness is a screen-space light window, not a ground
+      -- object: draw it flat over the finished scene like the tilt path.
+      -- It fills the view in world-pixel units, so it only needs the scale.
+      if self.dark then
+        love.graphics.push()
+        love.graphics.scale(scale, scale)
+        fxDark()
+        love.graphics.pop()
+      end
+    end
+    override = Pipelines.drawWorld(pipelineId, ctx)
+    -- world post-processes (a miniature-diorama blur, a colour grade) fold
+    -- over the finished scene here, so they never touch the UI drawn on top
+    if override then
+      override = Pipelines.worldPresent(override, ctx)
+    end
+    Game.renderer:setWorldOverride(override)
+    if not override then
+      -- The pipeline declined this frame (nothing to draw, or it threw and
+      -- was retired).  The ground pass was skipped on its behalf above, so
+      -- draw it now and fall through to the flat path below rather than
+      -- compositing an empty canvas.
+      self.map.renderer:drawBorderFill(cam.x, bgY, vw, vh)
+      self.map.renderer:draw(cam.x, bgY, vw, vh)
+      for _, nb in ipairs(self.neighbors) do
+        nb.map.renderer:drawMapOnly(cam.x - nb.ox, bgY - nb.oy, vw, vh)
+      end
+    end
+  end
+
+  if override then
+    -- the pipeline owns the whole frame; nothing else draws into the world
+  elseif not tilt then
     -- === FLAT PATH: everything into the one world canvas, as before =====
     -- OBP-baked sprites replay after the zone pass in GBC mode, so their
     -- grass feet-overdraw must replay over them too, colorized with the

src/world/Player.lua

@@ -61,16 +61,26 @@ function Player:tryMove(dir, map, entities)
   if self.facing ~= dir then
     self.facing = dir
     self.turnTimer = self.turnFrames or TURN_FRAMES
+    self.bumpFrames = nil -- turning to a new facing ends any wall-bonk cycle
     return "turned"
   end
   if self.turnTimer > 0 then return nil end
   local ok, why = Collision.canMove(map, entities, self, dir)
   if not ok then
+    -- Gen1: a blocked step still animates the player walking in place --
+    -- the collision path spends the step's worth of frames running
+    -- UpdateSprites before returning control, so the legs cycle without
+    -- the cell changing (home/overworld.asm collision handling; issue
+    -- #230).  Re-armed every frame the direction is held into the wall;
+    -- Player:update ticks the walk clock while it counts down, so releasing
+    -- returns to the standing pose within a step's length.
+    self.bumpFrames = self.stepFrames or STEP_FRAMES
     return "blocked", why
   end
   local tx, ty = Collision.target(self.cellX, self.cellY, dir)
   self.targetX, self.targetY = tx, ty
   self.moving = true
+  self.bumpFrames = nil -- a real step supersedes any in-place bonk
   self.progress = 0
   -- the bicycle doubles walking speed (8 frames per step)
   local save = require("src.core.Game").save
@@ -97,9 +107,19 @@ function Player:update()
     if self.spinFrames <= 0 then
       self.spinFrames = nil
       self.spinDrop = nil
+      self.spinRise = nil -- teleport-out departure lift (#196)
       self.spinning = false
     end
   end
+  -- wall-bonk walk-in-place (issue #230): while pushing into a wall the
+  -- collision path keeps the walk clock running without moving the cell,
+  -- so the sprite animates against the wall.  Guarded on not-moving so a
+  -- real step (which clears bumpFrames and advances animClock itself
+  -- below) can never double-tick the leg cadence.
+  if not self.moving and self.bumpFrames and self.bumpFrames > 0 then
+    self.bumpFrames = self.bumpFrames - 1
+    self.animClock = (self.animClock or 0) + 1
+  end
   if not self.moving then return false end
   local stepLen = self.stepFramesCur or self.stepFrames or STEP_FRAMES
   self.progress = self.progress + 1
@@ -132,7 +152,12 @@ function Player:facingCell()
 end
 
 function Player:walkPhase()
-  if not self.moving and not self.stepLanded then return 0 end
+  -- moving, the land-frame after a completed step, or an active wall-bonk
+  -- (issue #230) animate; a standing sprite otherwise
+  if not self.moving and not self.stepLanded
+     and not (self.bumpFrames and self.bumpFrames > 0) then
+    return 0
+  end
   -- walk frame during the middle of each 16-frame animation cycle
   local p = (self.animClock or self.progress) % 16
   return (p >= 4 and p < 12) and 1 or 0
@@ -140,28 +165,29 @@ end
 
 local SPIN_ORDER = { "down", "left", "up", "right" }
 
-function Player:draw(camX, camY)
+-- What this frame renders to: the sheet, where it sits, which way it faces
+-- and how far through a step it is.  Shared by the 2D draw below and by a
+-- render pipeline's own geometry (src/render/Pipelines.lua), so the two can
+-- never disagree about which sprite or facing is current.
+--
+-- The last return says the player is mid-ledge-hop, which is what the 2D
+-- path draws the ground shadow from and a 3D path turns into vertical lift.
+--
+-- This ADVANCES the surf-bob and spinner timers, so exactly one of pose()
+-- and draw() may run per frame -- and draw() is written in terms of pose()
+-- to keep that true by construction.  (hopFrames counts down in
+-- Player:update, on the fixed step, so it is safe to read here.)
+function Player:pose()
   local py = self.py
-  -- ledge hops arc (set for 2 cells by the ledge handler); surfing bobs.
-  -- hopFrames counts down in Player:update (fixed step), never here.
+  local hopping = false
+  -- ledge hops arc (set for 2 cells by the ledge handler); surfing bobs
   if self.hopFrames and self.hopFrames > 0 then
     local total = self.hopTotal or 32
     -- update runs before draw, so remaining N means N steps already
     -- consumed this hop → t matches the old draw-side post-decrement phase
     local t = 1 - self.hopFrames / total
     py = py - math.floor(10 * math.sin(t * math.pi) + 0.5)
-    -- the shadow stays on the ground under the jumper: one 8x8 tile
-    -- mirrored into a 2x2 block (normal/XFLIP/YFLIP/both) whose top-left
-    -- is 8px below the sprite's standing top-left (LoadHoppingShadowOAM +
-    -- LedgeHoppingShadowOAMBlock, engine/overworld/ledges.asm)
-    if self.shadowImg then
-      local sx = math.floor(self.px - camX)
-      local sy = math.floor(self.py - camY) - 4 + 8
-      love.graphics.draw(self.shadowImg, sx, sy)
-      love.graphics.draw(self.shadowImg, sx + 16, sy, 0, -1, 1)
-      love.graphics.draw(self.shadowImg, sx, sy + 16, 0, 1, -1)
-      love.graphics.draw(self.shadowImg, sx + 16, sy + 16, 0, -1, -1)
-    end
+    hopping = true
   elseif self.surfing then
     self.bobTimer = ((self.bobTimer or 0) + 1) % 32
     py = py + (self.bobTimer < 16 and 0 or 1)
@@ -182,11 +208,35 @@ function Player:draw(camX, camY)
     -- (EnterMapAnim PlayerSpinWhileMovingDown)
     if self.spinFrames and self.spinDrop then
       py = py - math.floor(self.spinFrames * 24 / (self.spinTotal or 64))
+    elseif self.spinFrames and self.spinRise then
+      -- Dig/Teleport/Escape-Rope departures spin the sprite UP out of the
+      -- map before the fade (LeaveMapAnim PlayerSpinWhileMovingUp) -- the
+      -- mirror of the arrival spin-down: the lift grows from 0 as spinFrames
+      -- counts down to 0 (#196), opposite sign to spinDrop above.
+      local total = self.spinTotal or 64
+      py = py - math.floor((total - self.spinFrames) * 24 / total)
     end
   end
   local sprite = (self.surfing and self.surfSprite)
                  or (self.onBike and self.bikeSprite) or self.sprite
-  sprite:draw(self.px, py, camX, camY, facing, phase, flip)
+  return sprite, self.px, py, facing, phase, flip, hopping
+end
+
+function Player:draw(camX, camY)
+  local sprite, px, py, facing, phase, flip, hopping = self:pose()
+  -- the shadow stays on the ground under the jumper: one 8x8 tile
+  -- mirrored into a 2x2 block (normal/XFLIP/YFLIP/both) whose top-left
+  -- is 8px below the sprite's standing top-left (LoadHoppingShadowOAM +
+  -- LedgeHoppingShadowOAMBlock, engine/overworld/ledges.asm)
+  if hopping and self.shadowImg then
+    local sx = math.floor(self.px - camX)
+    local sy = math.floor(self.py - camY) - 4 + 8
+    love.graphics.draw(self.shadowImg, sx, sy)
+    love.graphics.draw(self.shadowImg, sx + 16, sy, 0, -1, 1)
+    love.graphics.draw(self.shadowImg, sx, sy + 16, 0, 1, -1)
+    love.graphics.draw(self.shadowImg, sx + 16, sy + 16, 0, -1, -1)
+  end
+  sprite:draw(px, py, camX, camY, facing, phase, flip)
 end
 
 return Player

src/world/SsAnneLayout.lua

@@ -0,0 +1,62 @@
+-- S.S. Anne 1F cabins: ROM packs rooms so hallway doors map right→left
+-- onto the 3×2 rooms map (warp 1 = top-left = rightmost door).  Survey
+-- zoom makes that look left/right flipped vs 2F/B1F.  Reorder door→cell
+-- and slide objects so each door keeps its OG occupants while L→R doors
+-- land in reading order on the rooms map.
+
+local SsAnneLayout = {}
+
+local function leftmostRoomDoor(hall)
+  local best
+  for _, w in ipairs(hall.warps or {}) do
+    if w.destMap == "SS_ANNE_1F_ROOMS" then
+      if not best or w.x < best.x then best = w end
+    end
+  end
+  return best
+end
+
+function SsAnneLayout.apply(maps)
+  if not maps then return false end
+  local hall = maps.SS_ANNE_1F
+  local rooms = maps.SS_ANNE_1F_ROOMS
+  if not hall or not rooms then return false end
+  local left = leftmostRoomDoor(hall)
+  -- already hallway-ordered (leftmost door → rooms warp 1)
+  if not left or left.destWarp == 1 then return false end
+
+  local doors = {}
+  for _, w in ipairs(hall.warps) do
+    if w.destMap == "SS_ANNE_1F_ROOMS" then doors[#doors + 1] = w end
+  end
+  table.sort(doors, function(a, b) return a.x < b.x end)
+  for i, w in ipairs(doors) do w.destWarp = i end
+
+  -- rooms warps 1..6 return through hall warps 8..3 (L→R cabin doors)
+  for i, w in ipairs(rooms.warps or {}) do
+    if w.destMap == "SS_ANNE_1F" then w.destWarp = 9 - i end
+  end
+
+  local warpPos = {}
+  for i, w in ipairs(rooms.warps or {}) do
+    warpPos[i] = { x = w.x, y = w.y }
+  end
+  for _, o in ipairs(rooms.objects or {}) do
+    local col, row = math.floor(o.x / 10), math.floor(o.y / 10)
+    local oldK
+    for k, p in ipairs(warpPos) do
+      if math.floor(p.x / 10) == col and math.floor(p.y / 10) == row then
+        oldK = k
+        break
+      end
+    end
+    if oldK then
+      local newK = 7 - oldK
+      o.x = o.x + (warpPos[newK].x - warpPos[oldK].x)
+      o.y = o.y + (warpPos[newK].y - warpPos[oldK].y)
+    end
+  end
+  return true
+end
+
+return SsAnneLayout

tests/drivers/anne_door_test.lua

@@ -0,0 +1,28 @@
+-- Driver: #187 S.S. Anne cabin door entry.  Entering a room from the
+-- corridor should land one tile south of the door (pokered
+-- PlayerStepOutFromDoor), not leave the player on the door tile.
+return function(game)
+  local U = dofile("tests/drivers/util.lua")
+  local DIR = os.getenv("SHOT_DIR") or "/tmp/shots"
+
+  -- SS_ANNE_1F warp at (31,8) -> SS_ANNE_1F_ROOMS (rightmost cabin)
+  U.teleport(game, "SS_ANNE_1F", 31, 9, "up")
+  U.shot(game, DIR .. "/anne_0_before_enter.png")
+  local ow = game.overworld
+  U.log("before map:", ow.map.id, "pos:", ow.player.cellX, ow.player.cellY,
+        "facing:", ow.player.facing)
+
+  U.hold(game, "up", 20)
+  for _ = 1, 90 do
+    U.wait(1)
+    if ow.map.id == "SS_ANNE_1F_ROOMS" and not ow.transitioning
+       and #ow.scriptMoves == 0 and not ow.player.moving then
+      break
+    end
+  end
+  U.wait(8)
+  U.shot(game, DIR .. "/anne_1_after_enter.png")
+  U.log("after map:", ow.map.id, "pos:", ow.player.cellX, ow.player.cellY,
+        "facing:", ow.player.facing,
+        "onDoor:", tostring(ow.map:isWarpTileCell(ow.player.cellX, ow.player.cellY)))
+end

tests/drivers/battle_boosted_exp_bug216_test.lua

@@ -0,0 +1,173 @@
+-- Driver: reproduce #216 - "Boosted EXP text cut off".
+--
+-- A traded mon's EXP gain prints a 3-line message:
+--   "<mon> gained\na boosted\v<N> EXP. Points!"
+-- (engine/battle/experience.asm _GainedText/_BoostedText/_ExpPointsText;
+-- _BoostedText ends in the CONT code \v = char 11, "a boosted\011" in the
+-- extracted data/generated/text.lua).  The in-battle message box only has
+-- room for two lines (rows y=112 and y=128), so before the fix the third
+-- line was drawn at y=144 -- one row past the 160x144 screen -- and was
+-- never seen: a single A press dismissed the whole message and the wild win
+-- popped straight back to the overworld, so the boosted amount was invisible.
+--
+-- Gen1-correct behavior (home/text.asm ContText): the box scrolls a 2-line
+-- window, waiting for A/B on the \v (drawing the blinking ▼ arrow), then
+-- scrolls "a boosted" up to the top row and types "<N> EXP. Points!" on the
+-- bottom row (y=128) -- a VISIBLE row.
+--
+-- The driver builds a deterministic traded RATTATA, KOs a weak wild PIDGEY
+-- with no level-up, then renders the battle into a clean offscreen canvas
+-- while capturing Font.drawCode, and asserts the encoded "EXP. Points!"
+-- glyph run lands on a visible row (y <= 130), not off-screen at y=144.
+-- Fails on the buggy build (amount only ever drawn at y=144); passes once
+-- the box scrolls.
+--
+-- Run:
+--   SHOT_DIR=/tmp/bug216 POKEPORT_IDENTITY=bug216 POKEPORT_TOUCH=0 \
+--     POKEPORT_DRIVER=tests/drivers/battle_boosted_exp_bug216_test.lua love .
+return function(game)
+  local U = dofile("tests/drivers/util.lua")
+  local DIR = os.getenv("SHOT_DIR") or "/tmp/shots"
+  local Pokemon = require("src.pokemon.Pokemon")
+  local Growth = require("src.pokemon.Growth")
+  local Font = require("src.render.Font")
+  local BattleState = require("src.battle.BattleState")
+
+  -- deterministic traded RATTATA :L8; exp pinned to the L8 floor so a single
+  -- weak wild KO (~22 boosted exp) stays below the L9 threshold (no level-up
+  -- to muddy the message).  DVs pinned to max so numbers are stable per run.
+  local rattata = Pokemon.new(game.data, "RATTATA", 8, function(_, b) return b end)
+  local def = game.data.pokemon.RATTATA
+  rattata.exp = Growth.expForLevel(def.growthRate, 8, game.data.growth_rates)
+  rattata.traded = true -- the flag real trades/link set (Commands.lua / Protocol.lua)
+  game.save.party = { rattata }
+
+  U.teleport(game, "ROUTE_1", 5, 5, "down")
+  local ow = game.overworld
+
+  -- weak enemy: 1 HP so the first move KOs, speed 1 so RATTATA always moves
+  -- first, rng pinned low so every accuracy roll hits (Damage.accuracyRoll:
+  -- rng(0,255) < acc)
+  local battle = BattleState.newWild(game, "PIDGEY", 2)
+  battle.onFinish = function() end
+  battle.rng = function(a, _) return a end
+  battle.enemy.mon.hp = 1
+  battle.enemy.mon.stats.speed = 1
+  ow:pushBattle(battle)
+
+  -- Render the battle into a clean offscreen 160x144 canvas while recording
+  -- every Font.drawCode(code, x, y).  Returns true iff `targetCodes` appear
+  -- as a contiguous left-to-right run on a row at y <= maxY.  The off-screen
+  -- amount row (y=144) is excluded, so the buggy build never counts as
+  -- "shown".  BattleState:draw runs its own canvas pipeline internally and
+  -- restores the caller's canvas (see battle_hpbar_gbc_bug229_test.lua).
+  local canvas = love.graphics.newCanvas(160, 144)
+  local function seqVisible(targetCodes, maxY)
+    local rec = {}
+    local orig = Font.drawCode
+    Font.drawCode = function(code, x, y)
+      rec[#rec + 1] = { code, x, y }
+      return orig(code, x, y)
+    end
+    love.graphics.setCanvas(canvas)
+    love.graphics.clear(0, 0, 0, 1)
+    love.graphics.setColor(1, 1, 1, 1)
+    local okDraw = pcall(function() battle:draw() end)
+    love.graphics.setCanvas()
+    Font.drawCode = orig
+    if not okDraw then return false end
+    -- group glyphs by row, sort left-to-right, join codes into a delimited
+    -- string, and search each visible row for the target subsequence
+    local byY = {}
+    for _, g in ipairs(rec) do
+      if g[3] <= maxY then
+        byY[g[3]] = byY[g[3]] or {}
+        table.insert(byY[g[3]], g)
+      end
+    end
+    local tparts = {}
+    for _, c in ipairs(targetCodes) do tparts[#tparts + 1] = tostring(c) end
+    local needle = "," .. table.concat(tparts, ",") .. ","
+    for _, list in pairs(byY) do
+      table.sort(list, function(a, b) return a[2] < b[2] end)
+      local cs = {}
+      for _, g in ipairs(list) do cs[#cs + 1] = tostring(g[1]) end
+      if ("," .. table.concat(cs, ",") .. ","):find(needle, 1, true) then
+        return true
+      end
+    end
+    return false
+  end
+
+  local amountCodes = Font.encode("EXP. Points!")
+
+  -- mash through the intro to the FIGHT menu, then FIGHT -> move slot 1
+  -- (TACKLE) -> KO (mirrors battle_levelup_hpbar_bug224_test.lua)
+  for _ = 1, 300 do
+    if battle.phase == "menu" then break end
+    U.tap(game, "a")
+    U.wait(3)
+  end
+  if battle.phase ~= "menu" then error("bug216: never reached the FIGHT menu") end
+  U.tap(game, "a") -- FIGHT
+  for _ = 1, 60 do
+    if battle.phase == "moveSelect" then break end
+    U.wait(1)
+  end
+  if battle.phase ~= "moveSelect" then error("bug216: never reached move select") end
+  U.tap(game, "a") -- TACKLE -> KO
+
+  -- Phase A: advance to the boosted-EXP message (contains both "boosted"
+  -- and "EXP. Points!").  Break the frame it becomes current, before any A
+  -- press could scroll past it.
+  local function isBoosted()
+    local c = battle.current
+    return c and c.text and c.text:find("EXP. Points!", 1, true)
+             and c.text:find("boosted", 1, true)
+  end
+  local reached = false
+  for _ = 1, 900 do
+    if isBoosted() then reached = true break end
+    if game.stack:top() ~= battle then break end
+    U.tap(game, "a")
+    U.wait(2)
+  end
+  if not reached then
+    error("bug216: never reached the boosted-EXP message (battle ended early)")
+  end
+  U.log("boosted message: " ..
+        (tostring(battle.current.text):gsub("[\n\v]", "|")))
+
+  -- let the first two lines type out, then capture the cut-off
+  -- "gained / a boosted" box (both builds show this; the buggy build has no
+  -- visible third row)
+  U.wait(40)
+  U.shot(game, DIR .. "/bug216_boosted.png")
+
+  -- Phase B: the amount must become visible on a real row.  Each iteration
+  -- renders offscreen and checks; then taps A -- which scrolls the CONT
+  -- window on the fixed build, and (once fully typed) dismisses the message
+  -- on the buggy build.
+  local shown = false
+  for _ = 1, 120 do
+    if seqVisible(amountCodes, 130) then shown = true break end
+    if game.stack:top() ~= battle then break end
+    U.tap(game, "a")
+    U.wait(4)
+  end
+
+  if not shown then
+    error("bug216: 'EXP. Points!' amount never shown on a visible row " ..
+          "(drawn off-screen at y=144); the box did not scroll to the amount")
+  end
+
+  U.shot(game, DIR .. "/bug216_amount.png")
+
+  -- no level-up muddied the message
+  if battle.player.mon.level ~= 8 then
+    error("bug216: expected level 8, got " .. tostring(battle.player.mon.level))
+  end
+
+  U.log("bug216 OK: boosted EXP amount shown on a visible row, level still 8")
+  U.wait(4)
+end

tests/drivers/battle_hpbar_gbc_bug229_test.lua

@@ -0,0 +1,104 @@
+-- Regression test for issue #229 ("GSC palette black full health").
+--
+-- In RED++ ("Gen 2 / GSC-style") COLORS mode the full-health (green-band)
+-- in-battle HP bar rendered as a solid black rectangle.  Root cause is in
+-- src/render/HudTiles.lua drawHPBar: it pre-tinted the fill with GREENBAR's
+-- fill color {0,189,0} (red channel 0), zeroing the red channel of every bar
+-- pixel; the battle zone shade-remap shader (PaletteFX.shader, keyed ONLY on
+-- the red channel) then mapped every zeroed-red pixel to color 3 = black.
+-- Red/orange bands survived because REDBAR {247,0,0} / YELLOWBAR {247,165,0}
+-- keep a nonzero red channel.  SGB ('gbc') mode was unaffected because
+-- PaletteFX.pack({}) returns nil there, so the fill was already drawn gray.
+--
+-- Gen1-correct behavior: the DMG hardware bar is one gray shade recolored by
+-- the SGB region palette (home/pokemon.asm DrawHPBar + engine/gfx/palettes.asm
+-- SetPal_Battle + data/sgb/sgb_packets.asm BlkPacket_Battle), never a per-pixel
+-- repaint.  This driver forces RED++, enters a full-HP wild battle, screenshots
+-- the intro + action menu, then renders the battle into a clean 160x144 canvas
+-- and asserts the player AND enemy HP-bar fill bands are green (not black).
+--
+-- Run:
+--   SHOT_DIR=/tmp/bug229 POKEPORT_IDENTITY=bug229 POKEPORT_TOUCH=0 \
+--     POKEPORT_DRIVER=tests/drivers/battle_hpbar_gbc_bug229_test.lua love .
+return function(game)
+  local U = dofile("tests/drivers/util.lua")
+  local DIR = os.getenv("SHOT_DIR") or "."
+  local PaletteFX = require("src.render.PaletteFX")
+
+  -- Set the SAVED option, not just the live mode: Game:applyOptions re-reads
+  -- save.options.colors, so a bare setMode would get reverted to the default.
+  game.save.options = game.save.options or {}
+  game.save.options.colors = "redpp"
+  PaletteFX.setMode("redpp")
+
+  -- BULBASAUR :L5 is 19/19 -> full HP -> green band (matches the issue shot).
+  local Pokemon = require("src.pokemon.Pokemon")
+  game.save.party = { Pokemon.new(game.data, "BULBASAUR", 5) }
+
+  U.teleport(game, "ROUTE_1", 5, 5, "down")
+  local ow = game.overworld
+
+  local BattleState = require("src.battle.BattleState")
+  local battle = BattleState.newWild(game, "RATTATA", 3) -- full HP -> green
+  battle.onFinish = function() end
+  ow:pushBattle(battle)
+
+  U.wait(220)
+  U.shot(game, DIR .. "/bug229_redpp_intro.png")
+
+  -- Advance the intro text to the action menu deterministically (phase flips
+  -- to "menu" at BattleState:1111/1243); stop before a menu tap enters FIGHT.
+  for _ = 1, 40 do
+    if battle.phase == "menu" then break end
+    U.tap(game, "a")
+    U.wait(6)
+  end
+  U.wait(4)
+  U.shot(game, DIR .. "/bug229_redpp_menu.png")
+
+  -- Programmatic assertion: render the battle into a clean offscreen 160x144
+  -- canvas -- BattleState:draw runs its own SGB zone pass internally, so this
+  -- is the real colorized output (verified pixel-identical to the on-screen
+  -- capture).  Sample the CENTER fill rows of each bar (an 8px bar tile is
+  -- white frame rows / fill rows / white frame rows, so the middle rows are
+  -- the fill).  Before the fix the fill is ~ (0,0,0); after the fix it is
+  -- ~ (0,0.74,0) (GREENBAR fill {0,189,0}/255).
+  if love and love.graphics and love.graphics.newCanvas and battle.phase == "menu" then
+    local canvas = love.graphics.newCanvas(160, 144)
+    love.graphics.setCanvas(canvas)
+    love.graphics.clear(0, 0, 0, 1)
+    love.graphics.setColor(1, 1, 1, 1)
+    battle:draw()
+    love.graphics.setCanvas()
+    local id = canvas:newImageData()
+    do local dbg = id:encode("png"); local f = io.open(DIR .. "/bug229_offscreen.png", "wb"); if f then f:write(dbg:getString()); f:close() end end
+
+    local function green(r, g, b) return g > 0.4 and g > r and g > b end
+    -- returns worst (lowest-green) fill pixel across the center rows sampled
+    local function worstFill(x, ys)
+      local wr, wg, wb = 1, 1, 1
+      for _, y in ipairs(ys) do
+        local r, g, b = id:getPixel(x, y)
+        if g < wg then wr, wg, wb = r, g, b end
+      end
+      return wr, wg, wb
+    end
+    -- player bar: drawHPBar tile (10,9) -> fill x 96..143; fill rows y 74..77
+    local pr, pg, pb = worstFill(120, { 75, 76 })
+    -- enemy bar: drawHPBar tile (2,2) -> fill x 32..79; fill rows y 18..21
+    local er, eg, eb = worstFill(56, { 19, 20 })
+    U.log(string.format("player fill rgb = %.2f %.2f %.2f", pr, pg, pb))
+    U.log(string.format("enemy  fill rgb = %.2f %.2f %.2f", er, eg, eb))
+
+    if not (green(pr, pg, pb) and green(er, eg, eb)) then
+      error(string.format(
+        "issue #229: RED++ HP bar fill not green (player %.2f/%.2f/%.2f enemy %.2f/%.2f/%.2f)",
+        pr, pg, pb, er, eg, eb))
+    end
+    U.log("issue #229 PASS: green HP bar fill in RED++")
+  else
+    error("issue #229 driver: never reached the battle action menu")
+  end
+
+  U.wait(4)
+end

tests/drivers/battle_levelup_hpbar_bug224_test.lua

@@ -0,0 +1,125 @@
+-- Driver: reproduce #224 - "Level up health bar inches down".
+--
+-- On a level-up during battle, Gen 1 (engine/battle/experience.asm) raises
+-- the mon's current HP by (newMaxHP - oldMaxHP) and redraws the active
+-- battler's HP bar UP to reflect the higher current HP.  Our data layer is
+-- correct (Experience.lua:84 applies the current-HP delta), but the on-screen
+-- numerator - the battler's shownHP (the value the HUD bar/number use) - was
+-- never advanced on level-up, while the denominator (mon.stats.hp) jumped
+-- instantly.  So the drawn fill FRACTION fell (e.g. 8/20 -> 8/22) instead of
+-- rising to 10/22.
+--
+-- Setup: a SQUIRTLE at L5 with 8/oldMax HP and exp one point below the level-6
+-- threshold; a single wild KO crosses it.  The driver asserts the player HP
+-- bar's shownHP rises to the new current HP DURING the level-up messages
+-- (before the menu-phase safety net at BattleState.lua:1099 would mask it).
+-- Fails on the buggy build (shownHP stuck at 8); passes once fixed.
+return function(game)
+  local U = dofile("tests/drivers/util.lua")
+  local DIR = os.getenv("SHOT_DIR") or "/tmp/shots"
+  local Pokemon = require("src.pokemon.Pokemon")
+  local Growth = require("src.pokemon.Growth")
+  local BattleState = require("src.battle.BattleState")
+
+  -- deterministic mon: pin DVs to the max so the HP numbers are identical
+  -- across the before/after runs (Stats.randomDVs consumes rng(0,15))
+  local squirtle = Pokemon.new(game.data, "SQUIRTLE", 5, function(_, b) return b end)
+  local def = game.data.pokemon.SQUIRTLE
+  local oldHP = 8
+  squirtle.hp = oldHP -- partly depleted so the bar is well under full
+  -- one point below the level-6 exp threshold: a single kill levels up once
+  squirtle.exp = Growth.expForLevel(def.growthRate, 6, game.data.growth_rates) - 1
+  game.save.party = { squirtle }
+  local oldMax = squirtle.stats.hp
+
+  U.teleport(game, "ROUTE_1", 5, 5, "down")
+  local ow = game.overworld
+
+  -- weak enemy: 1 HP so the first TACKLE KOs; speed pinned to 1 so SQUIRTLE
+  -- always moves first (no enemy turn to muddy the HP math); rng pinned to
+  -- the low end so every roll hits (Damage.accuracyRoll: rng(0,255) < acc)
+  local battle = BattleState.newWild(game, "SLOWPOKE", 2)
+  battle.onFinish = function() end
+  battle.rng = function(a, _) return a end
+  battle.enemy.mon.hp = 1
+  battle.enemy.mon.stats.speed = 1
+  ow:pushBattle(battle)
+
+  -- mash through the intro to the FIGHT menu
+  for _ = 1, 240 do
+    if battle.phase == "menu" then break end
+    U.tap(game, "a")
+    U.wait(3)
+  end
+  if battle.phase ~= "menu" then error("bug224: never reached the FIGHT menu") end
+
+  -- HP box at L5: the menu safety net snaps shownHP to mon.hp, so 8/oldMax
+  U.shot(game, DIR .. "/bug224_menu.png")
+
+  -- FIGHT -> first move (TACKLE, slot 1) -> KO
+  U.tap(game, "a") -- FIGHT
+  for _ = 1, 60 do
+    if battle.phase == "moveSelect" then break end
+    U.wait(1)
+  end
+  if battle.phase ~= "moveSelect" then error("bug224: never reached move select") end
+  U.tap(game, "a") -- TACKLE
+
+  -- Monitor the level-up messages.  The bar must animate from oldHP toward
+  -- the new current HP while phase == 'messages' (before finish/menu-snap).
+  local maxShown = oldHP
+  local caughtUp = false
+  local shotGrew, shotRisen = false, false
+  for _ = 1, 600 do
+    U.wait(1)
+    U.tap(game, "a") -- advance text / dismiss the stat box (never skips the
+                     -- time-based drain), so we reach the HP-bar redraw
+    if battle.phase == "messages" and battle.player.mon.level >= 6 then
+      local sh = battle.player.shownHP or battle.player.mon.hp
+      maxShown = math.max(maxShown, sh)
+      if not shotGrew then
+        -- first L6 messages frame: buggy build already shows the shrunk bar
+        -- (8/newMax) here, and it never recovers
+        U.shot(game, DIR .. "/bug224_grew.png")
+        shotGrew = true
+      end
+      if not shotRisen and sh >= oldHP + 1.0 then
+        -- the bar has climbed at least a full HP: capture it mid-rise
+        U.shot(game, DIR .. "/bug224_hpbar.png")
+        shotRisen = true
+      end
+      if sh >= squirtle.hp - 0.5 then
+        caughtUp = true
+        break
+      end
+    end
+    if game.stack:top() ~= battle then break end -- battle finished/popped
+  end
+
+  -- data-layer sanity (Experience.lua): one level gained, max HP grew, and
+  -- current HP rose by the max-HP delta
+  if battle.player.mon.level ~= 6 then
+    error("bug224: expected level 6, got " .. tostring(battle.player.mon.level))
+  end
+  local newMax = squirtle.stats.hp
+  if not (newMax > oldMax) then
+    error("bug224: max HP did not grow (oldMax=" .. tostring(oldMax) ..
+          ", newMax=" .. tostring(newMax) .. "); repro is meaningless")
+  end
+  local expectHP = math.min(newMax, oldHP + (newMax - oldMax))
+  if squirtle.hp ~= expectHP then
+    error("bug224: current HP wrong: got " .. tostring(squirtle.hp) ..
+          ", expected " .. tostring(expectHP))
+  end
+
+  -- THE BUG: the on-screen bar must have risen to the new current HP during
+  -- the messages phase.  On the buggy build shownHP stays stuck at oldHP.
+  if not caughtUp then
+    error("bug224: HP bar did not rise on level-up - shownHP stuck at " ..
+          tostring(maxShown) .. " (oldHP=" .. tostring(oldHP) ..
+          "), mon.hp=" .. tostring(squirtle.hp) .. "/" .. tostring(newMax))
+  end
+
+  U.log("bug224 OK: L6, HP " .. tostring(squirtle.hp) .. "/" .. tostring(newMax) ..
+        ", bar rose from " .. tostring(oldHP) .. " to " .. tostring(maxShown))
+end

tests/drivers/battle_mono_sprite_bug207_test.lua

@@ -0,0 +1,150 @@
+-- Regression test for issue #207 ("Back of sprite only showing outline").
+--
+-- In the forced-mono display modes (OG / OG INV / CLASSIC) a warm-palette
+-- mon's battle pic (e.g. CHARMANDER, SGB palette REDMON) rendered as a bare
+-- black outline on white, its two mid shades gone, while cool-palette mons
+-- (SQUIRTLE, CYANMON) kept full shading.  Root cause is a double shade-remap:
+-- BattleState bakes each pic ONCE with the species' SGB colors, then draws it
+-- onto the UI canvas; in these modes BattleState exposes no SGB zones, so
+-- Renderer:endFrame invents a whole-screen GRAYS zone (PaletteFX.ensureZones)
+-- and runs the ENTIRE colored battle frame through PaletteFX.shader() a SECOND
+-- time.  That shader keys the DMG shade off the red channel
+-- (r>0.83?c0:r>0.5?c1:r>0.17?c2:c3); REDMON's two mid shades have red 1.0 and
+-- 0.839 -- BOTH > 0.83 -- so they collapse into shade 0 (the white paper),
+-- leaving only the near-black outline as shade 3.  CYANMON's reds (0.678,
+-- 0.451) land in the c1/c2 buckets, which is why blue mons were unaffected.
+--
+-- Gen1-correct behavior: mon pics are 2bpp 4-shade tiles (gfx/pokemon/back,
+-- gfx/pokemon/front); all four shades must be visible, and the same grayscale
+-- palette that renders SQUIRTLE renders CHARMANDER.  The fix draws the pics as
+-- raw DMG grays in these modes so the whole-screen remap recolors 255->c0,
+-- 170->c1, 85->c2, 0->c3 -- all four shades survive.
+--
+-- This driver forces OG, gives the player a CHARMANDER (the failing warm
+-- palette), enters a wild SQUIRTLE battle, and screenshots the exact action
+-- menu the reporter shows.  The assertion replays the on-screen two-stage
+-- pipeline into a clean 160x144 canvas (BattleState:draw, then the whole-screen
+-- GRAYS remap) and asserts the player CHARMANDER back-pic interior contains
+-- mid-gray shades (not outline-only), with the enemy SQUIRTLE front interior as
+-- an always-passing control.
+--
+-- Run:
+--   SHOT_DIR=/tmp/bug207 POKEPORT_IDENTITY=bug207 POKEPORT_TOUCH=0 \
+--     POKEPORT_DRIVER=tests/drivers/battle_mono_sprite_bug207_test.lua love .
+return function(game)
+  local U = dofile("tests/drivers/util.lua")
+  local DIR = os.getenv("SHOT_DIR") or "."
+  local PaletteFX = require("src.render.PaletteFX")
+
+  -- Set the SAVED option, not just the live mode: Game:applyOptions re-reads
+  -- save.options.colors, so a bare setMode would get reverted to the default.
+  game.save.options = game.save.options or {}
+  game.save.options.colors = "og"
+  PaletteFX.setMode("og")
+
+  -- CHARMANDER :L5 -- SGB palette REDMON, the warm palette that collapsed.
+  local Pokemon = require("src.pokemon.Pokemon")
+  game.save.party = { Pokemon.new(game.data, "CHARMANDER", 5) }
+
+  U.teleport(game, "ROUTE_1", 5, 5, "down")
+  local ow = game.overworld
+
+  local BattleState = require("src.battle.BattleState")
+  local battle = BattleState.newWild(game, "SQUIRTLE", 5)
+  battle.onFinish = function() end
+  ow:pushBattle(battle)
+
+  U.wait(220)
+  U.shot(game, DIR .. "/bug207_og_intro.png")
+
+  -- Advance the intro text to the action menu deterministically (phase flips
+  -- to "menu" once "Go! CHARMANDER!" has swapped in the species back pic).
+  for _ = 1, 40 do
+    if battle.phase == "menu" then break end
+    U.tap(game, "a")
+    U.wait(6)
+  end
+  U.wait(4)
+  -- The reporter's exact screen: the FIGHT/PKMN/ITEM/RUN action menu with the
+  -- player's CHARMANDER back pic fully visible bottom-left.
+  U.shot(game, DIR .. "/bug207_og_menu.png")
+
+  if not (love and love.graphics and love.graphics.newCanvas
+          and battle.phase == "menu") then
+    error("issue #207 driver: never reached the battle action menu")
+  end
+
+  -- Replay the on-screen forced-mono pipeline into an offscreen 160x144 canvas.
+  -- Stage 1 is BattleState's own colorized frame (its internal SGB zone pass
+  -- plus the mon pics drawn via picImage).  Stage 2 is Renderer:endFrame's
+  -- whole-screen remap for a state with no SGB zones: ensureZones -> whole(GRAYS),
+  -- then blit sends GRAYS through the shade shader over the FULL frame.  This is
+  -- pixel-faithful to the presented window (the U.shot captures above), but in
+  -- clean 160x144 canvas space so the sample boxes are resolution-independent.
+  local g = love.graphics
+  local shader = PaletteFX.shader()
+  local prev = g.getCanvas()
+  local a = g.newCanvas(160, 144)
+  local b = g.newCanvas(160, 144)
+  g.setCanvas(a)
+  g.clear(1, 1, 1, 1)          -- battle letterbox is white (letterboxWhite)
+  g.setColor(1, 1, 1, 1)
+  battle:draw()
+  g.setCanvas(b)
+  g.clear(0, 0, 0, 1)
+  g.setShader(shader)
+  PaletteFX.sendColors(shader, PaletteFX.GRAYS)
+  g.setColor(1, 1, 1, 1)
+  g.draw(a, 0, 0)
+  g.setShader()
+  g.setCanvas(prev)
+  local id = b:newImageData()
+  do
+    local png = id:encode("png")
+    local f = io.open(DIR .. "/bug207_og_offscreen.png", "wb")
+    if f then f:write(png:getString()); f:close() end
+  end
+
+  -- Count mid-gray pixels in a box.  The forced-mono frame is neutral gray:
+  -- shade 0 = white (~1.0), shade 3 = black (~0.0), and the two MID shades are
+  -- ltgray (170/255 = 0.667) and dkgray (85/255 = 0.333).  A mid shade exists
+  -- only when all four DMG shades survived the remap; an outline-only pic has
+  -- pure white + pure black and zero mid pixels.
+  local function midCount(x0, y0, x1, y1)
+    local n = 0
+    for y = y0, y1 do
+      for x = x0, x1 do
+        local r = id:getPixel(x, y)
+        if r > 0.18 and r < 0.82 then n = n + 1 end
+      end
+    end
+    return n
+  end
+
+  -- Player CHARMANDER back pic: hlcoord 1,5 (x=8), feet at y=96 -- interior
+  -- box well inside the body, clear of the white matte and the near-black
+  -- outline, and clear of the bottom-right HUD/HP bar.
+  local backMid = midCount(12, 50, 52, 92)
+  -- Enemy SQUIRTLE front pic: 7x7 slot at hlcoord 12,0 (x~96) -- control that
+  -- always keeps its mid shades (CYANMON reds land in the c1/c2 buckets).
+  local enemyMid = midCount(104, 8, 148, 48)
+  U.log(string.format("player back mid-gray px = %d ; enemy front mid-gray px = %d",
+                      backMid, enemyMid))
+
+  if enemyMid <= 20 then
+    error(string.format(
+      "issue #207 driver: control failed -- enemy SQUIRTLE front has no "
+      .. "mid-gray (%d); sample box or pipeline is wrong", enemyMid))
+  end
+  if backMid <= 20 then
+    error(string.format(
+      "issue #207: OG-mode CHARMANDER back pic is outline-only -- interior "
+      .. "has %d mid-gray px (expected the full 4-shade grayscale, like the "
+      .. "enemy front's %d)", backMid, enemyMid))
+  end
+  U.log(string.format(
+    "issue #207 PASS: OG-mode CHARMANDER back keeps its mid shades "
+    .. "(%d mid-gray px, control enemy %d)", backMid, enemyMid))
+
+  U.wait(4)
+end