Merge pull request #312 from bryanthaboi/dev

Lots of bug fixes and additional API greatness

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -25,7 +25,9 @@ body:
       options:
         - macOS
         - Windows
-        - Both
+        - Linux
+        - Android
+        - Multiple platforms
     validations:
       required: true
 
@@ -38,6 +40,17 @@ body:
     validations:
       required: true
 
+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers can ping you on Discord if they need a quick follow-up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
   - type: input
     id: location
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,35 +1,53 @@
 name: Feature request
-description: Ask for something new, or a change to how something already works.
+description: Ask for something new in the engine, launcher, or platform — not a content/gameplay mod.
 labels: ["enhancement"]
 body:
   - type: markdown
     attributes:
       value: |
+        Use this for **engine / launcher / platform** work (ports, video options, save
+        tooling, networking, mod API seams, docs).
+
+        If what you want is a gameplay, cosmetic, audio, or QoL change that a Lua mod
+        could ship — running shoes, alternate sprites, day/night, shiny indicators,
+        Gen 2-like battle toggles, soundtrack packs — open a
+        **[Mod request](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/issues/new?template=mod_request.yml)**
+        instead.
+
         "Can we add X" on its own is hard to act on. Say what you want, why you want it,
-        and how you picture it working. A request with real detail is one someone can
-        actually build without guessing at what you meant.
+        and how you picture it working.
 
   - type: input
     id: summary
     attributes:
       label: One line summary
       description: What you want, in a sentence.
-      placeholder: Add a run toggle so you can move at bike speed without the bike
+      placeholder: Add Linux AppImage releases next to the macOS and Windows builds
     validations:
       required: true
 
+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers can ping you on Discord if they need a quick follow-up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
   - type: textarea
     id: what
     attributes:
       label: What do you want
       description: >
-        Describe it properly. What is it, where does it live in the game, what does the
-        player see or do. If it changes something that already exists, say what it does today
-        and what it should do instead.
+        Describe it properly. What is it, where does it live (launcher, options,
+        engine), what does the player see or do. If it changes something that already
+        exists, say what it does today and what it should do instead.
       placeholder: |
-        A hold-to-run button, the way later Pokemon games do it. Hold B while moving on
-        foot and the player moves at bike speed. Release and you go back to walking.
-        Doesn't work indoors where the bike doesn't work, doesn't work in battles or menus.
+        Ship a Linux AppImage on each release, same version as the macOS/Windows builds,
+        with the same save folder layout and mod discovery path.
     validations:
       required: true
 
@@ -41,9 +59,8 @@ body:
         What's annoying or missing right now. What does this fix. If it's just because you
         think it would be fun, say that, it's a real answer.
       placeholder: |
-        Backtracking across routes you've already cleared is slow, and the bike is a menu
-        dive away and doesn't work in a lot of places. Running would cut a lot of dead time
-        without making the game easier.
+        LÖVE already runs on Linux; without a packaged build, players have to assemble
+        it themselves and miss release notes / update checks.
     validations:
       required: true
 
@@ -52,14 +69,12 @@ body:
     attributes:
       label: How should it work
       description: >
-        The specifics. Which button, which menu, what happens in the edge cases. If you don't
+        The specifics. Which menu, what happens in the edge cases. If you don't
         know, say what you'd expect as a player and leave the rest open.
       placeholder: |
-        - Hold B on the overworld to run
-        - Same speed as the bike
-        - Disabled anywhere the bike is disabled
-        - Sprite should probably need a running animation, not sure what that takes
-        - No effect on encounter rates
+        - GitHub Releases asset next to the .dmg / .exe
+        - Same options.lua / mods/ layout as desktop
+        - Documented in the README install section
     validations:
       required: true
 

.github/ISSUE_TEMPLATE/mod_request.yml

@@ -0,0 +1,115 @@
+name: Mod request
+description: Ask for a gameplay, cosmetic, audio, or QoL change that belongs as a Lua mod.
+labels: ["mod request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This tracker is for ideas that should ship as **mods**, not as core engine
+        features — alternate sprites, running shoes, day/night, shiny indicators,
+        soundtrack packs, Gen 2-like battle toggles, map cosmetics, bag QoL, etc.
+
+        The engine already exposes a lot of this through registries and hooks
+        ([modding wiki](https://github.com/bryanthaboi/pokemon-gen1-recomp-project/wiki)).
+        Use a **Feature request** instead for launcher / ports / video options /
+        networking / save tooling / new API seams.
+
+  - type: input
+    id: summary
+    attributes:
+      label: One line summary
+      description: What the mod should do, in a sentence.
+      placeholder: Hold B to run at bike speed on the overworld
+    validations:
+      required: true
+
+  - type: input
+    id: discord
+    attributes:
+      label: Discord username (optional)
+      description: >
+        So maintainers or mod authors can ping you on Discord if they pick this up.
+        Leave blank if you'd rather keep everything on GitHub.
+      placeholder: yourname
+    validations:
+      required: false
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What should the mod do
+      description: >
+        Describe the player-facing behavior. What changes, where, what does the
+        player see or press. If it toggles from Options or a START-menu entry, say so.
+      placeholder: |
+        Hold B while walking outdoors to move at bike speed. Release to walk again.
+        Same places the bike is allowed; no effect in battles or menus.
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why is this worth doing as a mod
+      description: >
+        Why optional/modded rather than a core option. Who wants it on, who wants
+        vanilla left alone.
+      placeholder: |
+        Great for replaying and backtracking, but some people want a strict Gen 1
+        pace. A mod (or an opt-in mod option) keeps both camps happy.
+    validations:
+      required: true
+
+  - type: textarea
+    id: how
+    attributes:
+      label: How should it work
+      description: >
+        Buttons, menus, edge cases, whether it needs new art/audio. If you know a
+        hook or registry that fits (movement.speed, pokemon.sprite, rulesets, …),
+        mention it — otherwise leave it open.
+      placeholder: |
+        - Hold B on the overworld
+        - Same step timing as the bike
+        - Disabled where the bike is disabled
+        - Prefer hooks:wrap("movement.speed") if that still fits
+    validations:
+      required: true
+
+  - type: dropdown
+    id: vanilla
+    attributes:
+      label: With the mod off, is vanilla unchanged
+      options:
+        - Yes — parity when disabled
+        - No — it would replace something always-on
+        - Not sure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Best-fit mod category
+      description: Same taxonomy as example mods (BALANCE, GRAPHICS, AUDIO, …).
+      options:
+        - GAMEPLAY / QoL
+        - GRAPHICS
+        - AUDIO
+        - BALANCE / ruleset
+        - CONTENT (maps, encounters, trainers)
+        - UI / TOOL
+        - TOTAL_CONVERSION-ish
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: >
+        Reference screenshots, other games/hacks that do it, related issues, or
+        "I'd like to try writing this myself." Leave blank if nothing comes to mind.
+    validations:
+      required: false

.github/workflows/ci.yml

@@ -14,7 +14,9 @@ name: ci
 
 on:
   push:
-    branches: [main]
+    # Integration branch + release branch. PRs already run via pull_request
+    # (any base); this list is only for post-merge push runs.
+    branches: [dev, main]
   pull_request:
 
 # a force-push while CI is mid-run should cancel the stale run, not queue

.github/workflows/release.yml

@@ -10,6 +10,9 @@ name: Release
 #   - To force a specific version, either:
 #       * run this workflow manually (Actions tab) and type it into "version", or
 #       * put "[release X.Y.Z]" anywhere in the commit message.
+#
+# Branch model: day-to-day work merges to `dev`. Releases stay on `main` only
+# so promoting `dev` -> `main` is the ship gate that cuts a build.
 
 on:
   push:
@@ -214,8 +217,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 +282,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/flavor/pewter_nidoran_house.lua

@@ -1,13 +1,21 @@
 -- pokered/scripts/PewterNidoranHouse.asm
 -- PewterNidoranHouseNidoranText: text_far _PewterNidoranHouseNidoranText, then
 -- text_asm plays the NIDORAN_M cry (PlayCry/WaitForSoundToFinish) before ending.
--- No sound-effect command exists in Commands.lua, so we port the dialogue line
--- only; the cry SFX is cosmetic and has no gameplay effect.
+-- play_cry only stashes ctx.pendingCry for the very next show_text row, so it
+-- has to sit immediately before that row (src/script/Commands.lua); the cry
+-- then sounds once the box has typed out, matching the asm's print-then-cry
+-- order.  Its waitForButton form keeps DisplayTextID's trailing
+-- WaitForTextScrollButtonPress -- PewterNidoranHouse_Script is
+-- `jp EnableAutoTextBoxDrawing`, which zeroes
+-- wDoNotWaitForButtonPressAfterDisplayingText -- so the box still holds until
+-- A/B.  The cry row was missing, leaving the NIDORAN silent (#247).
 return {
   PEWTER_NIDORAN_HOUSE = {
     talk = {
       TEXT_PEWTERNIDORANHOUSE_NIDORAN = {
         { "face_player" },
+        -- text_asm: ld a, NIDORAN_M / call PlayCry
+        { "play_cry", "NIDORAN_M", true },
         { "show_text", "_PewterNidoranHouseNidoranText" },
       },
     },

data/scripts/flavor/viridian_city.lua

@@ -59,13 +59,17 @@ M.VIRIDIAN_CITY = {
     -- ViridianCityYoungster2CaterpieAndWeedleDescriptionText are
     -- defined without a leading underscore in pokered/text/ViridianCity.asm
     -- and aren't present in data/generated/text.lua, so we fall back to
-    -- the literal strings from pokered.
+    -- the literal strings from pokered.  Those fallbacks have to carry the
+    -- extractor's markers, not plain newlines: line -> \n, cont -> \v,
+    -- para -> \f.  Spelling cont/para as \n and \n\n put all six lines on
+    -- one page with nothing to wait on, so the whole speech scrolled past
+    -- without a button press (#250).
     TEXT_VIRIDIANCITY_YOUNGSTER2 = function(game, ow, npc, done)
       local t = text(game)
       ask(game, t._ViridianCityYoungster2YouWantToKnowAboutText
-        or "You want to know\nabout the 2 kinds\nof caterpillar\nPOKéMON?", function(yes)
+        or "You want to know\nabout the 2 kinds\vof caterpillar\vPOKéMON?", function(yes)
         if yes then
-          push(game, "CATERPIE has no\npoison, but\nWEEDLE does.\n\nWatch out for its\nPOISON STING!", done)
+          push(game, "CATERPIE has no\npoison, but\vWEEDLE does.\fWatch out for its\nPOISON STING!", done)
         else
           push(game, "Oh, OK then!", done)
         end

data/scripts/flavor/viridian_nickname_house.lua

@@ -3,12 +3,16 @@
 return {
   VIRIDIAN_NICKNAME_HOUSE = {
     talk = {
-      -- ViridianNicknameHouseSpearowText: text_asm that shows the text
-      -- then plays a SPEAROW cry (PlayCry/WaitForSoundToFinish). The
-      -- cry playback isn't in the talk-script command vocabulary, so
-      -- only the flavor line is ported here.
+      -- ViridianNicknameHouseSpearowText: text_asm that PrintTexts the
+      -- line, then plays the SPEAROW cry (PlayCry/WaitForSoundToFinish)
+      -- before TextScriptEnd.  play_cry only arms the show_text row that
+      -- follows it, so the cry sounds once the box has typed out; its
+      -- waitForButton form keeps DisplayTextID's trailing
+      -- WaitForTextScrollButtonPress, so the box then holds until A/B like
+      -- any other NPC line rather than popping itself (#251).
       TEXT_VIRIDIANNICKNAMEHOUSE_SPEAROW = {
-        { "show_text", "_ViridianNicknameHouseSpearowText" },
+        { "play_cry", "SPEAROW", true },                      -- 1 PlayCry
+        { "show_text", "_ViridianNicknameHouseSpearowText" }, -- 2 PrintText
       },
     },
   },

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

@@ -16,6 +16,14 @@ M.VIRIDIAN_MART = {
   -- StartSimulatingJoypadStates walks the player to the counter
   -- (.PlayerMovement: PAD_LEFT 1, PAD_UP 2, door (3,7) -> counter (2,5))
   -- and ViridianMartOaksParcelScript hands the parcel over.  The player
+  -- never presses A.
+  --
+  -- The RLE list is consumed back to front: DecodeRLEList fills forward
+  -- from wSimulatedJoypadStatesEnd, the script seeds wSimulatedJoypadStates-
+  -- Index with the count, and home/overworld.asm decrements that index
+  -- before each read.  So PAD_LEFT 1, PAD_UP 2 actually plays up, up, left,
+  -- and the walk ends facing the clerk.  Replaying the list front to back
+  -- put the player at the counter facing up instead (#235).  The player
   -- never presses A.  This matters beyond convenience: the parcel gates
   -- Oak's Pokedex and the old man clearing Route 2, so vanilla guarantees
   -- it on entry rather than letting you walk out without it.
@@ -28,8 +36,8 @@ M.VIRIDIAN_MART = {
     if not f.EVENT_GOT_STARTER then return end
     ow:queueScript({
       { "show_text", "_ViridianMartClerkYouCameFromPalletTownText" },
-      { "move_player", "left", 1 },
       { "move_player", "up", 2 },
+      { "move_player", "left", 1 },
       -- the quest text's last page is "{PLAYER} got\nOAK's PARCEL!"
       { "give_item", "OAKS_PARCEL", 1, "_ViridianMartClerkParcelQuestText" },
       { "set_flag", "EVENT_GOT_OAKS_PARCEL" },
@@ -395,7 +403,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 +972,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,195 @@
+# 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 / mod / save import
+
+On Android, `love.system.pickFile([kind])` opens the Storage Access Framework
+picker (`GameActivity.showFilePicker`); the chosen file is copied into the app
+save directory as:
+
+| `kind` | Destination |
+| --- | --- |
+| nil / `"rom"` | `picked_rom.gb` (open) |
+| `"mod"` | `picked_mod.zip` (open) |
+| `"sav"` / `"save"` | `picked_save.sav` (open) |
+
+Export uses a separate API: `love.system.createFile(suggestedName)` →
+`GameActivity.showCreateDocument` (`ACTION_CREATE_DOCUMENT`), which copies
+staged `pending_export.sav` to the user-chosen URI and writes `export_done.flag`
+for the launcher to acknowledge on refocus.
+
+`RomImporter` then imports on refocus / Choose:
+
+- **ROMs** 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).
+- **Mods** via `findPendingMod`: Prefer `picked_mod.zip`, or (on Choose) any
+  other `.zip` at the save-dir root (USB copy).
+- **Saves** via `findPendingSav`: Prefer `picked_save.sav`, or (on Choose) any
+  other `.sav` at the save-dir root.
+
+After a successful import the consumed save-dir file 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. On the MODS tab, Import mod .zip must open the
+same system picker and install the chosen archive on return.
+
+## 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.
+- `SaveData.deleteSlot(version, slotId)` removes the slot's
+  main/`.bak`/`.tmp` files, drops it from the registry, and if it was active
+  points active at another remaining slot (or clears active when the list is
+  empty). The launcher's SAVE SLOT panel Delete control calls this.
+
+## 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.
+- `LauncherMods.uninstall(id)` removes `mods/<id>/` and clears
+  `options.mods[id]` so a later reinstall starts from the loader's default
+  (enabled). The mods panel Delete control calls this and re-derives the list.
+
+## 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` on desktop; on Android,
+  `love.system.pickFile("sav")` → `picked_save.sav`, same SAF path as ROMs).
+  `SaveFileIO.importToSlot` reads the bytes (an absolute path, a save-dir
+  relative name, 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")`). On desktop it returns the
+  absolute path (`love.filesystem.getSaveDirectory()`), which the notice line
+  shows with an "Open folder" affordance (`love.system.openURL("file://" .. dir)`).
+  On Android the bytes are also staged as `pending_export.sav` and
+  `love.system.createFile(suggestedName)` opens `ACTION_CREATE_DOCUMENT` so the
+  player can save to Downloads / Drive / etc.; on return `export_done.flag`
+  makes focus show "Save exported."
+- **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,52 @@ 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).
+## Translation support
+
+Every string the player can read is now reachable from a mod, so a
+translation is an ordinary content mod rather than a fork.
+
+Two things had to change. Text layout stopped counting bytes: the dialogue
+box measures a line in glyphs (charmap sequences), so a 3-byte character
+costs one column, a cut never lands inside a character, and a page with a
+non-default `advance` re-measures instead of overflowing. That also fixed
+25 vanilla English lines that were wrapping early because `é` in POKéMON
+and POKéDEX costs two bytes ("I study POKéMON as" is 19 bytes and 18
+glyphs, and the box was breaking it).
+
+Second, the text the engine writes itself - battle messages, item results,
+menu labels, the link-play screens - moved behind `src/core/Strings.lua`
+and the new `strings` registry. Extracted script text was already
+overridable through `text`; this covers the other half. Entries are keyed
+by the English source, so a translation that has not reached a string yet
+keeps rendering in English and a half-finished translation stays playable.
+
+Authors generate the whole thing:
+
+```sh
+python3 tools/modkit.py translation francais --language "Francais"
+```
+
+That scaffolds a mod with every translatable string as an empty catalog,
+plus a glyph-page and charmap stub, a naming-grid stub, and a
+`francais-worksheet/` directory holding the English to translate from
+(deliberately outside the mod: extracted text is ROM content and must not
+be packed). `--refresh` re-harvests after an engine update, keeping
+existing translations and parking orphaned keys rather than dropping them.
+
+See the wiki's Translations guide.

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 / mod / save import on Android uses `love.system.pickFile([kind])` →
+`GameActivity.showFilePicker` (Storage Access Framework), which copies the
+chosen file under the app save directory as `picked_rom.gb`,
+`picked_mod.zip`, or `picked_save.sav`. `RomImporter` imports pending files
+from that folder on Choose / refocus; see `docs/launcher.md`. The APK payload
+itself remains data-free (no embedded ROM or generated cache).
 
 ### SDK / NDK
 

mobile/android/gradle.properties

@@ -18,4 +18,4 @@ android.useAndroidX=true
 android.defaults.buildfeatures.buildconfig=true
 android.nonTransitiveRClass=true
 android.nonFinalResIds=true
-app.name=Pokemon Red
+app.name=gen1recomp

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

@@ -183,13 +183,37 @@ void vibrate(double seconds)
 	env->DeleteLocalRef(activity);
 }
 
-bool showFilePicker()
+bool showFilePicker(const char *destFilename)
 {
+	if (destFilename == nullptr || destFilename[0] == '\0')
+		destFilename = "picked_rom.gb";
+
 	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
 	jclass activity = env->FindClass("org/love2d/android/GameActivity");
 
-	jmethodID method = env->GetStaticMethodID(activity, "showRomFilePicker", "()Z");
-	jboolean result = env->CallStaticBooleanMethod(activity, method);
+	jmethodID method = env->GetStaticMethodID(activity, "showFilePicker",
+		"(Ljava/lang/String;)Z");
+	jstring jname = env->NewStringUTF(destFilename);
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jname);
+	env->DeleteLocalRef(jname);
+
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
+bool showCreateDocument(const char *suggestedName)
+{
+	if (suggestedName == nullptr || suggestedName[0] == '\0')
+		suggestedName = "export.sav";
+
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+
+	jmethodID method = env->GetStaticMethodID(activity, "showCreateDocument",
+		"(Ljava/lang/String;)Z");
+	jstring jname = env->NewStringUTF(suggestedName);
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jname);
+	env->DeleteLocalRef(jname);
 
 	env->DeleteLocalRef(activity);
 	return result;

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

@@ -63,9 +63,16 @@ void vibrate(double seconds);
  * Shows the system's "pick a document" UI (Storage Access Framework).
  * Returns true if the picker was launched; the picked file (if any) is
  * copied asynchronously by GameActivity.onActivityResult into the app's
- * external save directory, not returned here -- see src/import/RomImporter.lua.
+ * external save directory under destFilename (default picked_rom.gb), not
+ * returned here -- see src/import/RomImporter.lua.
  **/
-bool showFilePicker();
+bool showFilePicker(const char *destFilename = nullptr);
+
+/**
+ * Shows ACTION_CREATE_DOCUMENT so Lua can export a staged pending_export.sav
+ * to a user-chosen location. suggestedName is the dialog default filename.
+ **/
+bool showCreateDocument(const char *suggestedName = nullptr);
 
 /*
  * Helper functions for the filesystem module

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

@@ -22,6 +22,8 @@
 #include "common/config.h"
 #include "System.h"
 
+#include <cstring>
+
 #if defined(LOVE_MACOSX)
 #include <CoreServices/CoreServices.h>
 #elif defined(LOVE_IOS)
@@ -180,11 +182,32 @@ void System::vibrate(double seconds) const
 #endif
 }
 
-bool System::pickFile() const
+bool System::pickFile(const char *kind) const
 {
 #ifdef LOVE_ANDROID
-	return love::android::showFilePicker();
+	const char *dest = "picked_rom.gb";
+	if (kind != nullptr)
+	{
+		if (strcmp(kind, "mod") == 0)
+			dest = "picked_mod.zip";
+		else if (strcmp(kind, "sav") == 0 || strcmp(kind, "save") == 0)
+			dest = "picked_save.sav";
+		else if (strcmp(kind, "rom") == 0)
+			dest = "picked_rom.gb";
+	}
+	return love::android::showFilePicker(dest);
 #else
+	LOVE_UNUSED(kind);
+	return false;
+#endif
+}
+
+bool System::createFile(const char *suggestedName) const
+{
+#ifdef LOVE_ANDROID
+	return love::android::showCreateDocument(suggestedName);
+#else
+	LOVE_UNUSED(suggestedName);
 	return false;
 #endif
 }

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

@@ -111,9 +111,21 @@ public:
 	 * Android only for now; the result (if any) is not returned here -- see
 	 * love::android::showFilePicker and src/import/RomImporter.lua.
 	 *
+	 * @param kind Optional pick kind: nullptr/"rom" -> picked_rom.gb,
+	 *             "mod" -> picked_mod.zip, "sav"/"save" -> picked_save.sav.
 	 * @return Whether the picker was shown.
 	 **/
-	virtual bool pickFile() const;
+	virtual bool pickFile(const char *kind = nullptr) const;
+
+	/**
+	 * Shows the platform's native "create / save a file" UI (Android SAF
+	 * ACTION_CREATE_DOCUMENT). Copies staged pending_export.sav from the app
+	 * save directory to the user-chosen URI. See GameActivity.showCreateDocument.
+	 *
+	 * @param suggestedName Default filename shown in the dialog.
+	 * @return Whether the create dialog was shown.
+	 **/
+	virtual bool createFile(const char *suggestedName = nullptr) const;
 
 	/**
 	 * Gets if the user is playing music on background.

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

@@ -97,7 +97,15 @@ int w_vibrate(lua_State *L)
 
 int w_pickFile(lua_State *L)
 {
-	luax_pushboolean(L, instance()->pickFile());
+	const char *kind = luaL_optstring(L, 1, nullptr);
+	luax_pushboolean(L, instance()->pickFile(kind));
+	return 1;
+}
+
+int w_createFile(lua_State *L)
+{
+	const char *suggested = luaL_optstring(L, 1, nullptr);
+	luax_pushboolean(L, instance()->createFile(suggested));
 	return 1;
 }
 
@@ -117,6 +125,7 @@ static const luaL_Reg functions[] =
 	{ "openURL", w_openURL },
 	{ "vibrate", w_vibrate },
 	{ "pickFile", w_pickFile },
+	{ "createFile", w_createFile },
 	{ "hasBackgroundMusic", w_hasBackgroundMusic },
 	{ 0, 0 }
 };

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

@@ -22,12 +22,15 @@ package org.love2d.android;
 
 import org.libsdl.app.SDLActivity;
 
+import java.io.BufferedInputStream;
 import java.io.BufferedOutputStream;
 import java.io.File;
+import java.io.FileInputStream;
 import java.io.FileNotFoundException;
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.OutputStream;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
@@ -61,13 +64,24 @@ public class GameActivity extends SDLActivity {
     protected final int[] recordAudioRequestDummy = new int[1];
     public static final int EXTERNAL_STORAGE_REQUEST_CODE = 2;
     public static final int RECORD_AUDIO_REQUEST_CODE = 3;
-    public static final int ROM_PICKER_REQUEST_CODE = 4;
-    // Mirrors conf.lua's t.identity ("pokemon-love2d"): where the picked ROM
+    public static final int FILE_PICKER_REQUEST_CODE = 4;
+    public static final int FILE_CREATE_REQUEST_CODE = 5;
+    /** @deprecated Prefer FILE_PICKER_REQUEST_CODE; kept for older call sites. */
+    public static final int ROM_PICKER_REQUEST_CODE = FILE_PICKER_REQUEST_CODE;
+    // Mirrors conf.lua's t.identity ("pokemon-love2d"): where the picked file
     // is dropped so RomImporter's existing folder scan finds it -- see
     // src/import/RomImporter.lua and Filesystem::setIdentity (sets Android's
     // save directory to getExternalFilesDir()/save/<identity>).
     private static final String ROM_SAVE_IDENTITY = "pokemon-love2d";
     private static final String PICKED_ROM_FILENAME = "picked_rom.gb";
+    private static final String PICKED_MOD_FILENAME = "picked_mod.zip";
+    private static final String PICKED_SAVE_FILENAME = "picked_save.sav";
+    private static final String PENDING_EXPORT_FILENAME = "pending_export.sav";
+    private static final String EXPORT_DONE_FILENAME = "export_done.flag";
+    // Destination basename for the in-flight SAF pick (set by showFilePicker).
+    private String pendingPickFilename = PICKED_ROM_FILENAME;
+    // Suggested download name for the in-flight SAF create (set by showCreateDocument).
+    private String pendingCreateSuggestedName = "export.sav";
     private static boolean immersiveActive = false;
     private static boolean needToCopyGameInArchive = false;
     private boolean storagePermissionUnnecessary = false;
@@ -341,59 +355,185 @@ public class GameActivity extends SDLActivity {
 
     /**
      * Shows the system document picker (Storage Access Framework) so the
-     * player can pick their ROM from anywhere (Downloads, Drive, etc.)
-     * without needing to know where the app's external files folder is.
-     * Requires API 19+ (ACTION_OPEN_DOCUMENT); the picked file (if any)
+     * player can pick a ROM / mod / save from anywhere (Downloads, Drive,
+     * etc.) without needing to know where the app's external files folder
+     * is. Requires API 19+ (ACTION_OPEN_DOCUMENT); the picked file (if any)
      * arrives later in onActivityResult, not synchronously here.
+     *
+     * @param destFilename basename under the app save identity (e.g.
+     *                     picked_rom.gb, picked_mod.zip, picked_save.sav)
      */
     @Keep
-    public static boolean showRomFilePicker() {
+    public static boolean showFilePicker(String destFilename) {
         if (android.os.Build.VERSION.SDK_INT < 19) return false;
         GameActivity self = (GameActivity) mSingleton;
         if (self == null) return false;
+        if (destFilename == null || destFilename.length() == 0) {
+            destFilename = PICKED_ROM_FILENAME;
+        }
+        // Reject path separators so a hostile JNI caller cannot escape the
+        // save identity directory.
+        if (destFilename.indexOf('/') >= 0 || destFilename.indexOf('\\') >= 0) {
+            Log.d("GameActivity", "refusing unsafe picker dest: " + destFilename);
+            return false;
+        }
 
+        self.pendingPickFilename = destFilename;
         Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
         intent.addCategory(Intent.CATEGORY_OPENABLE);
         intent.setType("*/*");
         try {
-            self.startActivityForResult(intent, ROM_PICKER_REQUEST_CODE);
+            self.startActivityForResult(intent, FILE_PICKER_REQUEST_CODE);
             return true;
         } catch (Exception e) {
-            Log.d("GameActivity", "could not open ROM file picker: " + e.getMessage());
+            Log.d("GameActivity", "could not open file picker: " + e.getMessage());
             return false;
         }
     }
 
+    /** ROM convenience wrapper; prefer showFilePicker with an explicit name. */
+    @Keep
+    public static boolean showRomFilePicker() {
+        return showFilePicker(PICKED_ROM_FILENAME);
+    }
+
+    /** Mod .zip convenience wrapper used by love.system.pickFile("mod"). */
+    @Keep
+    public static boolean showModFilePicker() {
+        return showFilePicker(PICKED_MOD_FILENAME);
+    }
+
+    /** Battery .sav convenience wrapper used by love.system.pickFile("sav"). */
+    @Keep
+    public static boolean showSaveFilePicker() {
+        return showFilePicker(PICKED_SAVE_FILENAME);
+    }
+
+    /**
+     * Shows ACTION_CREATE_DOCUMENT so the player can save a staged export
+     * (pending_export.sav in the app save identity) to Downloads / Drive /
+     * etc. Suggested name is the dialog's default filename.
+     */
+    @Keep
+    public static boolean showCreateDocument(String suggestedName) {
+        if (android.os.Build.VERSION.SDK_INT < 19) return false;
+        GameActivity self = (GameActivity) mSingleton;
+        if (self == null) return false;
+        if (suggestedName == null || suggestedName.length() == 0) {
+            suggestedName = "export.sav";
+        }
+        if (suggestedName.indexOf('/') >= 0 || suggestedName.indexOf('\\') >= 0) {
+            Log.d("GameActivity", "refusing unsafe create name: " + suggestedName);
+            return false;
+        }
+        File source = new File(
+            new File(self.getExternalFilesDir(null), "save"),
+            ROM_SAVE_IDENTITY + "/" + PENDING_EXPORT_FILENAME);
+        if (!source.isFile()) {
+            Log.d("GameActivity", "no pending export at " + source);
+            return false;
+        }
+
+        self.pendingCreateSuggestedName = suggestedName;
+        Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);
+        intent.addCategory(Intent.CATEGORY_OPENABLE);
+        intent.setType("application/octet-stream");
+        intent.putExtra(Intent.EXTRA_TITLE, suggestedName);
+        try {
+            self.startActivityForResult(intent, FILE_CREATE_REQUEST_CODE);
+            return true;
+        } catch (Exception e) {
+            Log.d("GameActivity", "could not open create-document picker: " + e.getMessage());
+            return false;
+        }
+    }
+
+    private File saveIdentityDir() {
+        return new File(new File(getExternalFilesDir(null), "save"), ROM_SAVE_IDENTITY);
+    }
+
+    private boolean copyFileToUri(File source, Uri destUri) {
+        InputStream in = null;
+        OutputStream out = null;
+        try {
+            in = new BufferedInputStream(new FileInputStream(source));
+            out = getContentResolver().openOutputStream(destUri);
+            if (out == null) return false;
+            byte[] buf = new byte[8192];
+            int n;
+            while ((n = in.read(buf)) != -1) {
+                out.write(buf, 0, n);
+            }
+            out.flush();
+            return true;
+        } catch (IOException e) {
+            Log.d("GameActivity", "copy to URI failed: " + e.getMessage());
+            return false;
+        } finally {
+            try { if (in != null) in.close(); } catch (IOException ignored) {}
+            try { if (out != null) out.close(); } catch (IOException ignored) {}
+        }
+    }
+
     @Override
     protected void onActivityResult(int requestCode, int resultCode, Intent data) {
         super.onActivityResult(requestCode, resultCode, data);
-        if (requestCode != ROM_PICKER_REQUEST_CODE) return;
+        if (requestCode == FILE_CREATE_REQUEST_CODE) {
+            if (resultCode != RESULT_OK || data == null || data.getData() == null) {
+                Log.d("GameActivity", "create-document cancelled");
+                return;
+            }
+            File source = new File(saveIdentityDir(), PENDING_EXPORT_FILENAME);
+            if (!source.isFile()) {
+                Log.d("GameActivity", "pending export missing at result time");
+                return;
+            }
+            Uri uri = data.getData();
+            if (copyFileToUri(source, uri)) {
+                // Signal Lua on next focus that the SAF export finished.
+                File flag = new File(saveIdentityDir(), EXPORT_DONE_FILENAME);
+                try {
+                    FileOutputStream fos = new FileOutputStream(flag, false);
+                    fos.write("ok".getBytes());
+                    fos.close();
+                } catch (IOException e) {
+                    Log.d("GameActivity", "could not write export_done flag: " + e.getMessage());
+                }
+                // Keep pending_export.sav so a retry still works; Lua may remove it.
+            } else {
+                Log.d("GameActivity", "could not write export to " + uri);
+            }
+            return;
+        }
+        if (requestCode != FILE_PICKER_REQUEST_CODE) return;
         if (resultCode != RESULT_OK || data == null || data.getData() == null) {
-            Log.d("GameActivity", "ROM picker returned no file (cancelled?)");
+            Log.d("GameActivity", "file picker returned no file (cancelled?)");
             return;
         }
 
         Uri uri = data.getData();
-        File destDir = new File(new File(getExternalFilesDir(null), "save"), ROM_SAVE_IDENTITY);
+        File destDir = saveIdentityDir();
         if (!destDir.exists() && !destDir.mkdirs()) {
             Log.d("GameActivity", "could not create " + destDir);
             return;
         }
-        File destFile = new File(destDir, PICKED_ROM_FILENAME);
+        String destName = pendingPickFilename != null
+            ? pendingPickFilename : PICKED_ROM_FILENAME;
+        File destFile = new File(destDir, destName);
 
         InputStream source;
         try {
             source = getContentResolver().openInputStream(uri);
         } catch (FileNotFoundException e) {
-            Log.d("GameActivity", "could not open picked ROM: " + e.getMessage());
+            Log.d("GameActivity", "could not open picked file: " + e.getMessage());
             return;
         }
         if (source == null) {
-            Log.d("GameActivity", "ContentResolver returned no stream for picked ROM");
+            Log.d("GameActivity", "ContentResolver returned no stream for picked file");
             return;
         }
         if (!copyAssetFile(source, destFile.getPath())) {
-            Log.d("GameActivity", "could not copy picked ROM to " + destFile);
+            Log.d("GameActivity", "could not copy picked file to " + destFile);
         }
     }
 

mods/examples/README.md

@@ -1,6 +1,6 @@
 # Example mod gallery
 
-Seven reference mods, one per modder persona. Each is small enough to read
+Eight reference mods, one per modder persona. Each is small enough to read
 in one sitting, exercises a different slice of the mod API, and is a real,
 runnable, tested mod — not a snippet.
 
@@ -16,6 +16,7 @@ Copy the one closest to what you want to build.
 | 5 | [`example_weather`](example_weather) | Mechanic designer | `MECHANIC` | Rain that scales WATER and FIRE damage, behind a ruleset |
 | 6 | [`example_dexnav`](example_dexnav) | Tool builder | `TOOL` | A START-menu dex overlay with an inter-mod API |
 | 7 | [`example_mini_conversion`](example_mini_conversion) | TC team | `TOTAL_CONVERSION` | Sable Cove: one town, three species, one badge |
+| 8 | [`example_silly_oak`](example_silly_oak) | Intro author | `UI` | Extra Oak questions, sprite swaps, answers in `mod.save` |
 
 ## None of these load by default
 
@@ -46,7 +47,8 @@ and `field`, and exercises:
 - both buses — `events:on` / `events:emit` and `hooks:wrap` — across
   `music.select`, `battle.damage`, `ui.start_menu.items`, `ui.options.rows`,
   `battle.started`, `battle.turn_started`, `battle.ended`, `flag.changed`,
-  `game.ready` and `assets.transformed`
+  `game.ready`, `assets.transformed`, `intro.oak_speech.build`,
+  `intro.oak_speech.answered` and `intro.oak_speech.finished`
 - `mod.save`, `mod.options`, `mod.exports`, `mod.commands`, `mod.ui`,
   `mod:read`, `mod.log` and `mod.path`
 - asset transforms, the `trueColor` opt-out, script labels and `choice`,
@@ -66,7 +68,7 @@ mods/examples/<id>/
   .modkitignore     keeps the suite out of the distributed package
 ```
 
-`tests/mod_examples_tests.lua` in the engine's own suite loads all seven
+`tests/mod_examples_tests.lua` in the engine's own suite loads all eight
 together and asserts the above, so the gallery cannot rot.
 
 These example mods arent perfect and are just examples to show you basics of wahts possible, but way more than just this is possible.

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_silly_oak/CHANGELOG.md

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

mods/examples/example_silly_oak/README.md

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

mods/examples/example_silly_oak/main.lua

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

mods/examples/example_silly_oak/manifest.json

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

mods/examples/example_silly_oak/mod.card

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

mods/examples/example_silly_oak/tests/example_silly_oak_test.lua

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

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

@@ -8,6 +8,7 @@
 local MoveEffects = require("src.battle.MoveEffects")
 local Runtime = require("src.mods.Runtime")
 local StatusRegistry = require("src.battle.StatusRegistry")
+local Strings = require("src.core.Strings")
 
 local EffectRegistry = {}
 
@@ -91,7 +92,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   if target.invulnerable and not neverMiss then
     -- Explosion/Selfdestruct still animate on a miss (HandleIfPlayerMoveMissed)
     if not (record and record.explode) then battle:cancelMoveAnim() end
-    battle:sayNext(("%s's\nattack missed!"):format(displayName(user)))
+    battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
     return
   end
 
@@ -113,7 +114,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     if not battle:accuracyRoll(move, user, target) then
       -- Explosion/Selfdestruct still animate on a miss (HandleIfPlayerMoveMissed)
       if not (record and record.explode) then battle:cancelMoveAnim() end
-      battle:sayNext(("%s's\nattack missed!"):format(displayName(user)))
+      battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
       -- Jump Kick crash, Explode self-destruct
       if record and record.onMiss then record.onMiss(ctx, "accuracy") end
       user.trappingTurns = nil
@@ -140,7 +141,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     end
     if not counterable or (battle.lastDamage or 0) == 0 then
       battle:cancelMoveAnim()
-      battle:sayNext(("%s's\nattack missed!"):format(displayName(user)))
+      battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
       return
     end
     dmg = math.min(65535, battle.lastDamage * 2)
@@ -163,14 +164,14 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   if info.typeMult == 0 then
     -- type immunity zeros damage and sets wMoveMissed in Gen 1, so no anim
     if not (record and record.explode) then battle:cancelMoveAnim() end
-    battle:sayNext(("It doesn't affect\n%s!"):format(displayName(target)))
+    battle:sayNext(Strings("It doesn't affect\n%s!", displayName(target)))
     if record and record.onMiss then record.onMiss(ctx, "immune") end
     return
   end
   if info.missed then
     -- 0.25x floored the damage to zero: the original registers a miss
     if not (record and record.explode) then battle:cancelMoveAnim() end
-    battle:sayNext(("%s's\nattack missed!"):format(displayName(user)))
+    battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
     if record and record.onMiss then record.onMiss(ctx, "floored") end
     return
   end
@@ -214,12 +215,12 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     -- multi-hit loop (core.asm .moveDidNotMiss before the jump back
     -- to GetPlayerAnimationType), so crit/effectiveness reprint on
     -- every strike -- damage was only rolled once
-    if info.crit then battle:sayNext("Critical hit!") end
-    if info.ohko then battle:sayNext("One-hit KO!") end
+    if info.crit then battle:sayNext(Strings("Critical hit!")) end
+    if info.ohko then battle:sayNext(Strings("One-hit KO!")) end
     if info.typeMult > 10 then
-      battle:sayNext("It's super\neffective!")
+      battle:sayNext(Strings("It's super\neffective!"))
     elseif info.typeMult < 10 then
-      battle:sayNext("It's not very\neffective...")
+      battle:sayNext(Strings("It's not very\neffective..."))
     end
     if Runtime.wants("battle.damage_dealt") then
       Runtime.emit("battle.damage_dealt", {
@@ -237,9 +238,9 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   if hits > 1 then
     -- player: _MultiHitText; enemy: _HitXTimesText (always plural)
     if user.isPlayer then
-      battle:sayNext(("Hit the enemy\n%d times!"):format(hits))
+      battle:sayNext(Strings("Hit the enemy\n%d times!", hits))
     else
-      battle:sayNext(("Hit %d times!"):format(hits))
+      battle:sayNext(Strings("Hit %d times!", hits))
     end
   end
 
@@ -251,7 +252,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   elseif moveInst.struggle then
     -- struggle recoils even when its effect id resolves to no record
     local recoil = math.max(1, math.floor(dmg / 2))
-    battle:sayNext(("%s's\nhit with recoil!"):format(displayName(user)))
+    battle:sayNext(Strings("%s's\nhit with recoil!", displayName(user)))
     battle:applyDamage(user, recoil)
   end
 

src/battle/MoveEffects.lua

@@ -15,6 +15,7 @@ local Logger = require("src.core.Logger")
 local StatusRegistry = require("src.battle.StatusRegistry")
 local TurnOrder = require("src.battle.TurnOrder")
 local TypeChart = require("src.battle.TypeChart")
+local Strings = require("src.core.Strings")
 
 local MoveEffects = {}
 
@@ -36,14 +37,14 @@ local STAT_LABEL = {
 local function changeStage(battle, who, stat, delta, fromEnemy)
   if fromEnemy and (who.substituteHP or who.mist) then
     if who.mist then
-      return { displayName(who) .. " is\nprotected by MIST!" }
+      return { Strings("%s is\nprotected by MIST!", displayName(who)) }
     end
-    return { "But, it failed!" }
+    return { Strings("But, it failed!") }
   end
   local cur = who.stages[stat] or 0
   local new = math.max(-6, math.min(6, cur + delta))
   if new == cur then
-    return { ("Nothing happened!") }
+    return { Strings("Nothing happened!") }
   end
   who.stages[stat] = new
   -- effects.asm:505-506: after any stat-stage change, modified stats are
@@ -53,13 +54,13 @@ local function changeStage(battle, who, stat, delta, fromEnemy)
   -- _MonsStatsRoseText/_MonsStatsFellText: "X's / STAT rose!"; the
   -- two-stage variants scroll "greatly" onto a third line
   if delta >= 2 then
-    return { ("%s's\n%s\ngreatly rose!"):format(displayName(who), STAT_LABEL[stat]) }
+    return { Strings("%s's\n%s\ngreatly rose!", displayName(who), STAT_LABEL[stat]) }
   elseif delta == 1 then
-    return { ("%s's\n%s rose!"):format(displayName(who), STAT_LABEL[stat]) }
+    return { Strings("%s's\n%s rose!", displayName(who), STAT_LABEL[stat]) }
   elseif delta == -1 then
-    return { ("%s's\n%s fell!"):format(displayName(who), STAT_LABEL[stat]) }
+    return { Strings("%s's\n%s fell!", displayName(who), STAT_LABEL[stat]) }
   end
-  return { ("%s's\n%s\ngreatly fell!"):format(displayName(who), STAT_LABEL[stat]) }
+  return { Strings("%s's\n%s\ngreatly fell!", displayName(who), STAT_LABEL[stat]) }
 end
 MoveEffects.changeStage = changeStage
 
@@ -88,10 +89,10 @@ end
 local function statusMove(status)
   return function(battle, user, target, move)
     if target.mon.status then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     if status == "PSN" and target.substituteHP then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     local msgs = inflictStatus(battle, target, status, {
       toxic = move and move.id == "TOXIC",
@@ -99,7 +100,7 @@ local function statusMove(status)
       source = move and move.id,
     })
     if #msgs == 0 then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     return msgs
   end
@@ -111,7 +112,7 @@ local function statusSide(status, chance)
     -- target (regardless of the burn roll)
     if move and move.type == "FIRE" and target.mon.status == "FRZ" then
       target.mon.status = nil
-      return { ("Fire defrosted\n%s!"):format(displayName(target)) }
+      return { Strings("Fire defrosted\n%s!", displayName(target)) }
     end
     if battle.rng(0, 255) >= chance then return {} end
     return inflictStatus(battle, target, status, {
@@ -144,10 +145,10 @@ end
 
 local function confuse(battle, target, pierceSub)
   if target.confusedTurns or (target.substituteHP and not pierceSub) then
-    return { "But, it failed!" }
+    return { Strings("But, it failed!") }
   end
   target.confusedTurns = battle.rng(2, 5)
-  return { ("%s\nbecame confused!"):format(displayName(target)) }
+  return { Strings("%s\nbecame confused!", displayName(target)) }
 end
 
 -- ---------------------------------------------------------------------
@@ -181,53 +182,53 @@ MoveEffects.primary = {
   LEECH_SEED_EFFECT = function(battle, user, target)
     -- leech_seed.asm has no substitute check: seeding lands through one
     if target.leechSeeded then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     for _, t in ipairs(target.curTypes) do
-      if t == "GRASS" then return { "But, it failed!" } end
+      if t == "GRASS" then return { Strings("But, it failed!") } end
     end
     target.leechSeeded = true
-    return { ("%s\nwas seeded!"):format(displayName(target)) }
+    return { Strings("%s\nwas seeded!", displayName(target)) }
   end,
 
   HEAL_EFFECT = function(battle, user, target, move)
     local mon = user.mon
     if move.id == "REST" then
-      if mon.hp == mon.stats.hp then return { "But, it failed!" } end
+      if mon.hp == mon.stats.hp then return { Strings("But, it failed!") } end
       mon.hp = mon.stats.hp
       mon.status = "SLP"
       user.sleepTurns = 2
       user.toxicCounter = nil
-      return { ("%s\nstarted sleeping!"):format(displayName(user)) }
+      return { Strings("%s\nstarted sleeping!", displayName(user)) }
     end
-    if mon.hp == mon.stats.hp then return { "But, it failed!" } end
+    if mon.hp == mon.stats.hp then return { Strings("But, it failed!") } end
     mon.hp = math.min(mon.stats.hp, mon.hp + math.floor(mon.stats.hp / 2))
-    return { ("%s\nregained health!"):format(displayName(user)) }
+    return { Strings("%s\nregained health!", displayName(user)) }
   end,
 
   LIGHT_SCREEN_EFFECT = function(battle, user)
-    if user.lightScreen then return { "But, it failed!" } end
+    if user.lightScreen then return { Strings("But, it failed!") } end
     user.lightScreen = true
-    return { ("%s's\nprotected against\nspecial attacks!"):format(displayName(user)) }
+    return { Strings("%s's\nprotected against\nspecial attacks!", displayName(user)) }
   end,
 
   REFLECT_EFFECT = function(battle, user)
-    if user.reflect then return { "But, it failed!" } end
+    if user.reflect then return { Strings("But, it failed!") } end
     user.reflect = true
-    return { ("%s\ngained armor!"):format(displayName(user)) }
+    return { Strings("%s\ngained armor!", displayName(user)) }
   end,
 
   MIST_EFFECT = function(battle, user)
-    if user.mist then return { "But, it failed!" } end
+    if user.mist then return { Strings("But, it failed!") } end
     user.mist = true
     -- _ShroudedInMistText (lowercase "mist")
-    return { ("%s's\nshrouded in mist!"):format(displayName(user)) }
+    return { Strings("%s's\nshrouded in mist!", displayName(user)) }
   end,
 
   FOCUS_ENERGY_EFFECT = function(battle, user)
-    if user.focusEnergy then return { "But, it failed!" } end
+    if user.focusEnergy then return { Strings("But, it failed!") } end
     user.focusEnergy = true
-    return { ("%s's\ngetting pumped!"):format(displayName(user)) }
+    return { Strings("%s's\ngetting pumped!", displayName(user)) }
   end,
 
   HAZE_EFFECT = function(battle, user, target)
@@ -254,33 +255,33 @@ MoveEffects.primary = {
       target.skipMove = true
     end
     target.mon.status = nil
-    return { "All STATUS changes\nare eliminated!" }
+    return { Strings("All STATUS changes\nare eliminated!") }
   end,
 
   SUBSTITUTE_EFFECT = function(battle, user)
-    if user.substituteHP then return { ("%s\nhas a SUBSTITUTE!"):format(displayName(user)) } end
+    if user.substituteHP then return { Strings("%s\nhas a SUBSTITUTE!", displayName(user)) } end
     local cost = math.floor(user.mon.stats.hp / 4)
     -- substitute.asm only fails on subtraction underflow (current HP
     -- strictly below maxHP/4); at equality the substitute is built and
     -- the user is left standing on exactly 0 HP (it faints only when
     -- the engine next checks HP, not here)
     if user.mon.hp < cost then
-      return { "Too weak to make\na SUBSTITUTE!" }
+      return { Strings("Too weak to make\na SUBSTITUTE!") }
     end
     user.mon.hp = user.mon.hp - cost
     user.substituteHP = cost + 1
     -- _SubstituteText
-    return { "It created a\nSUBSTITUTE!" }
+    return { Strings("It created a\nSUBSTITUTE!") }
   end,
 
   CONVERSION_EFFECT = function(battle, user, target)
     -- conversion.asm fails against a mid-Fly/Dig target (INVULNERABLE)
     if target.invulnerable then
-      return { "But, it failed!" }
+      return { Strings("But, it failed!") }
     end
     user.curTypes = { target.curTypes[1], target.curTypes[2] }
     -- _ConvertedTypeText
-    return { ("Converted type to\n%s's!"):format(displayName(target)) }
+    return { Strings("Converted type to\n%s's!", displayName(target)) }
   end,
 
   -- MIMIC_EFFECT lives in BattleState:resolveMimic: MimicEffect
@@ -311,27 +312,27 @@ MoveEffects.primary = {
       table.insert(user.curMoves, { id = mv.id, pp = 5, mimic = true })
     end
     -- _TransformedText: the copied name prints bare (wNameBuffer)
-    return { ("%s\ntransformed into\n%s!"):format(displayName(user), target.name) }
+    return { Strings("%s\ntransformed into\n%s!", displayName(user), target.name) }
   end,
 
   DISABLE_EFFECT = function(battle, user, target)
-    if target.disabledSlot then return { "But, it failed!" } end
+    if target.disabledSlot then return { Strings("But, it failed!") } end
     local usable = {}
     for i, mv in ipairs(target.curMoves) do
       if mv.pp > 0 then table.insert(usable, i) end
     end
-    if #usable == 0 then return { "But, it failed!" } end
+    if #usable == 0 then return { Strings("But, it failed!") } end
     local slot = usable[battle.rng(1, #usable)]
     target.disabledSlot = slot
     target.disabledTurns = battle.rng(1, 8)
     local id = target.curMoves[slot].id
     -- _MoveWasDisabledText: "X's / MOVE was / disabled!"
-    return { ("%s's\n%s was\ndisabled!"):format(displayName(target),
+    return { Strings("%s's\n%s was\ndisabled!", displayName(target),
                                                 battle.data.moves[id].name) }
   end,
 
   SPLASH_EFFECT = function()
-    return { "No effect!" }
+    return { Strings("No effect!") }
   end,
 }
 
@@ -428,7 +429,9 @@ local function drainHalf(text)
     local mon = ctx.user.mon
     mon.hp = math.min(mon.stats.hp, mon.hp + heal)
     ctx.drain()
-    ctx.say(text:format(displayName(ctx.target)))
+    -- `text` arrives as a source string (Strings.source at the call
+    -- site keeps it in the catalog); look it up here, at use time
+    ctx.say(Strings(text, displayName(ctx.target)))
   end
 end
 
@@ -436,7 +439,7 @@ end
 -- flags the miss before the special-damage override)
 local function immuneMsg(ctx)
   if TypeChart.effectiveness(ctx.move.type, ctx.target.curTypes) == 0 then
-    return ("It doesn't affect\n%s!"):format(displayName(ctx.target))
+    return Strings("It doesn't affect\n%s!", displayName(ctx.target))
   end
   return nil
 end
@@ -498,12 +501,12 @@ MoveEffects.full = {
       -- removed): overkill and substitute hits recoil at full strength
       local recoil = math.max(1, math.floor(ctx.rawDamage
                                             / (ctx.moveInst.struggle and 2 or 4)))
-      ctx.say(("%s's\nhit with recoil!"):format(displayName(ctx.user)))
+      ctx.say(Strings("%s's\nhit with recoil!", displayName(ctx.user)))
       ctx.battle:applyDamage(ctx.user, recoil)
     end,
   },
   DRAIN_HP_EFFECT = {
-    afterDamage = drainHalf("Sucked health from\n%s!"),
+    afterDamage = drainHalf(Strings.source("Sucked health from\n%s!")),
   },
   DREAM_EATER_EFFECT = {
     -- only works on sleeping targets (checked before damage)
@@ -511,7 +514,7 @@ MoveEffects.full = {
       if ctx.target.mon.status ~= "SLP" then return false, "But, it failed!" end
       return true
     end,
-    afterDamage = drainHalf("%s's\ndream was eaten!"),
+    afterDamage = drainHalf(Strings.source("%s's\ndream was eaten!")),
   },
 
   -- charge moves: first turn just charges; Fly AND Dig go
@@ -557,7 +560,7 @@ MoveEffects.full = {
           user.thrashTurns, user.thrashMove, user.thrashAnnounced = nil, nil, nil
           if not user.confusedTurns then
             user.confusedTurns = ctx.rng(2, 5)
-            ctx.say(("%s\nbecame confused!"):format(displayName(user)))
+            ctx.say(Strings("%s\nbecame confused!", displayName(user)))
           end
         end
       end
@@ -566,7 +569,7 @@ MoveEffects.full = {
   JUMP_KICK_EFFECT = {
     onMiss = function(ctx, reason)
       if reason ~= "accuracy" then return end
-      ctx.say(("%s\nkept going and\ncrashed!"):format(displayName(ctx.user)))
+      ctx.say(Strings("%s\nkept going and\ncrashed!", displayName(ctx.user)))
       ctx.damage(ctx.user, 1)
     end,
   },
@@ -581,8 +584,12 @@ MoveEffects.full = {
   },
   HYPER_BEAM_EFFECT = {
     afterDamage = function(ctx)
-      -- no recharge when the target faints OR its substitute breaks
-      if ctx.target.mon.hp > 0 and not ctx.brokeSub then
+      -- Gen 1: no recharge when the target faints OR its substitute breaks.
+      -- Ruleset hyperBeamSkipRechargeOnKO=false forces Gen 2+ always-recharge.
+      local ruleset = ctx.battle and ctx.battle.ruleset
+      local skipOnKO = not ruleset or ruleset.hyperBeamSkipRechargeOnKO ~= false
+      local targetDown = ctx.target.mon.hp <= 0 or ctx.brokeSub
+      if not skipOnKO or not targetDown then
         ctx.user.mustRecharge = true
       end
     end,
@@ -591,7 +598,7 @@ MoveEffects.full = {
     afterDamage = function(ctx)
       local battle = ctx.battle
       battle.payDay = (battle.payDay or 0) + 2 * ctx.user.mon.level
-      ctx.say("Coins scattered\neverywhere!")
+      ctx.say(Strings("Coins scattered\neverywhere!"))
     end,
   },
   SWIFT_EFFECT = { neverMiss = true },
@@ -606,7 +613,7 @@ MoveEffects.full = {
       local user = ctx.user
       user.bideTurns = ctx.rng(2, 3)
       user.bideDamage = 0
-      ctx.say(("%s\nis storing energy!"):format(displayName(user)))
+      ctx.say(Strings("%s\nis storing energy!", displayName(user)))
     end,
   },
   SWITCH_AND_TELEPORT_EFFECT = {
@@ -627,27 +634,27 @@ MoveEffects.full = {
         end
         if ok then
           if move.id == "ROAR" then
-            ctx.say(("%s\nran away scared!"):format(displayName(target)))
+            ctx.say(Strings("%s\nran away scared!", displayName(target)))
           elseif move.id == "WHIRLWIND" then
-            ctx.say(("%s\nwas blown away!"):format(displayName(target)))
+            ctx.say(Strings("%s\nwas blown away!", displayName(target)))
           else
-            ctx.say(("%s\nran from battle!"):format(displayName(user)))
+            ctx.say(Strings("%s\nran from battle!", displayName(user)))
           end
           battle.result = "run"
           battle.afterQueue = "finish"
         elseif move.id == "TELEPORT" then
           battle:cancelMoveAnim()
-          ctx.say("But, it failed!")
+          ctx.say(Strings("But, it failed!"))
         else
           battle:cancelMoveAnim()
-          ctx.say(("It didn't affect\n%s!"):format(displayName(target)))
+          ctx.say(Strings("It didn't affect\n%s!", displayName(target)))
         end
       elseif move.id == "TELEPORT" then
         battle:cancelMoveAnim()
-        ctx.say("But, it failed!")
+        ctx.say(Strings("But, it failed!"))
       else
         battle:cancelMoveAnim()
-        ctx.say(("%s\nis unaffected!"):format(displayName(target)))
+        ctx.say(Strings("%s\nis unaffected!", displayName(target)))
       end
     end,
   },
@@ -665,7 +672,7 @@ MoveEffects.full = {
     callsMove = function(ctx)
       local last = ctx.target.lastMove
       if not last then
-        ctx.say("The MIRROR MOVE\nfailed!")
+        ctx.say(Strings("The MIRROR MOVE\nfailed!"))
         return nil
       end
       return last

src/battle/Status.lua

@@ -5,6 +5,8 @@
 -- and residual sweep.  Callers without a battle (pure-module tests) fall
 -- back to the vanilla records, which is bit-identical behavior.
 
+local Strings = require("src.core.Strings")
+
 local Status = {}
 
 -- pokered's <USER>/<TARGET> text macros print "Enemy " before the enemy
@@ -28,8 +30,11 @@ local function hasType(battler, wanted)
 end
 
 -- shared PSN/BRN residual: 1/16 max HP, multiplied (and advanced) by the
--- Toxic counter (HandlePoisonBurnLeechSeed)
-local function damageOverTime(what)
+-- Toxic counter (HandlePoisonBurnLeechSeed).  The caller passes the whole
+-- sentence rather than the noun: "hurt by poison" and "hurt by the burn"
+-- decline differently once translated, so a shared fragment cannot be the
+-- translatable unit.
+local function damageOverTime(template)
   return function(battler)
     local mon = battler.mon
     local base = math.max(1, math.floor(mon.stats.hp / 16))
@@ -39,10 +44,15 @@ local function damageOverTime(what)
       battler.toxicCounter = battler.toxicCounter + 1
     end
     mon.hp = math.max(0, mon.hp - dmg)
-    return { ("%s's\nhurt by %s!"):format(name(battler), what) }
+    return { Strings(template, name(battler)) }
   end
 end
 
+-- Labels stay plain literals on purpose: this table is built at require
+-- time, before Strings.load has a catalog, so a Strings() here would
+-- freeze the English.  They are already translatable through the
+-- statuses registry (mod.content.statuses:patch(id, { label = ... })).
+--
 -- The five persistent conditions as records: the beforeMove gauntlet, the
 -- residual sweep, the inflict text/immunities (StatusRegistry.inflict),
 -- the catch/wobble bonuses (Catching.attempt), the HUD label, and the
@@ -57,13 +67,13 @@ Status.RECORDS = {
       battler.sleepTurns = (battler.sleepTurns or 1) - 1
       if battler.sleepTurns <= 0 then
         battler.mon.status = nil
-        return false, { name(battler) .. "\nwoke up!" } -- wakes but loses the turn
+        return false, { Strings("%s\nwoke up!", name(battler)) } -- wakes, loses the turn
       end
-      return false, { name(battler) .. "\nis fast asleep!" }
+      return false, { Strings("%s\nis fast asleep!", name(battler)) }
     end,
     onInflict = function(battle, target, opts, display)
       target.sleepTurns = battle.rng(1, 7)
-      return { ("%s\nfell asleep!"):format(display) }
+      return { Strings("%s\nfell asleep!", display) }
     end,
   },
   FRZ = {
@@ -71,35 +81,35 @@ Status.RECORDS = {
     catchBonus = 25, shakeBonus = 10,
     beforeMovePriority = 30,
     beforeMove = function(battler)
-      return false, { name(battler) .. "\nis frozen solid!" }
+      return false, { Strings("%s\nis frozen solid!", name(battler)) }
     end,
     canInflict = function(target) return not hasType(target, "ICE") end,
     onInflict = function(_, _, _, display)
-      return { ("%s\nwas frozen solid!"):format(display) }
+      return { Strings("%s\nwas frozen solid!", display) }
     end,
   },
   PSN = {
     id = "PSN", label = "PSN", hudLabel = "PSN",
     catchBonus = 12, shakeBonus = 5,
-    residual = damageOverTime("poison"),
+    residual = damageOverTime(Strings.source("%s's\nhurt by poison!")),
     canInflict = function(target) return not hasType(target, "POISON") end,
     onInflict = function(_, target, opts, display)
       if opts.toxic then
         target.toxicCounter = 1
         -- _BadlyPoisonedText
-        return { ("%s's\nbadly poisoned!"):format(display) }
+        return { Strings("%s's\nbadly poisoned!", display) }
       end
-      return { ("%s\nwas poisoned!"):format(display) }
+      return { Strings("%s\nwas poisoned!", display) }
     end,
   },
   BRN = {
     id = "BRN", label = "BRN", hudLabel = "BRN",
     catchBonus = 12, shakeBonus = 5,
     statPenalty = { stat = "attack", div = 2 },
-    residual = damageOverTime("the burn"),
+    residual = damageOverTime(Strings.source("%s's\nhurt by the burn!")),
     canInflict = function(target) return not hasType(target, "FIRE") end,
     onInflict = function(_, _, _, display)
-      return { ("%s\nwas burned!"):format(display) }
+      return { Strings("%s\nwas burned!", display) }
     end,
   },
   PAR = {
@@ -110,7 +120,7 @@ Status.RECORDS = {
     beforeMove = function(battler, rng)
       -- cp 25 percent / jr nc: fully paralyzed on rand < 63 (63/256)
       if rng(0, 255) < 63 then
-        return false, { name(battler) .. "'s\nfully paralyzed!" }
+        return false, { Strings("%s's\nfully paralyzed!", name(battler)) }
       end
       return true, {}
     end,
@@ -120,7 +130,7 @@ Status.RECORDS = {
     end,
     onInflict = function(_, _, _, display)
       -- _ParalyzedMayNotAttackText (primary and secondary paralysis)
-      return { ("%s's\nparalyzed! It may\nnot attack!"):format(display) }
+      return { Strings("%s's\nparalyzed! It may\nnot attack!", display) }
     end,
   },
 }
@@ -156,7 +166,7 @@ function Status.beforeMove(battler, rng, battle)
   end
   if battler.flinched then
     battler.flinched = false
-    return false, { name(battler) .. "\nflinched!" }
+    return false, { Strings("%s\nflinched!", name(battler)) }
   end
   local record = Status.recordFor(battleStatuses(battle), mon.status)
   local handler = record and record.beforeMove
@@ -174,23 +184,23 @@ function Status.beforeMove(battler, rng, battle)
   end
   if battler.boundTurns and battler.boundTurns > 0 then
     battler.boundTurns = battler.boundTurns - 1
-    msgs[#msgs + 1] = name(battler) .. "\ncan't move!"
+    msgs[#msgs + 1] = Strings("%s\ncan't move!", name(battler))
     return false, msgs
   end
   if battler.disabledTurns then
     battler.disabledTurns = battler.disabledTurns - 1
     if battler.disabledTurns <= 0 then
       battler.disabledTurns, battler.disabledSlot = nil, nil
-      table.insert(msgs, name(battler) .. "'s\ndisabled no more!")
+      table.insert(msgs, Strings("%s's\ndisabled no more!", name(battler)))
     end
   end
   if battler.confusedTurns then
     battler.confusedTurns = battler.confusedTurns - 1
     if battler.confusedTurns <= 0 then
       battler.confusedTurns = nil
-      table.insert(msgs, name(battler) .. "\nsnapped out of\nconfusion!")
+      table.insert(msgs, Strings("%s\nsnapped out of\nconfusion!", name(battler)))
     else
-      table.insert(msgs, name(battler) .. "\nis confused!")
+      table.insert(msgs, Strings("%s\nis confused!", name(battler)))
       -- cp 50 percent + 1 / jr c: hurt itself on rand >= 128 (128/256)
       if rng(0, 255) < 128 then
         return false, msgs, true -- hurt itself
@@ -231,7 +241,7 @@ function Status.residual(battler, opponent, battle)
     dmg = math.min(dmg, mon.hp)
     mon.hp = mon.hp - dmg
     opponent.mon.hp = math.min(opponent.mon.stats.hp, opponent.mon.hp + dmg)
-    table.insert(msgs, ("LEECH SEED saps\n%s!"):format(name(battler)))
+    table.insert(msgs, Strings("LEECH SEED saps\n%s!", name(battler)))
   end
   return msgs
 end

src/battle/StatusRegistry.lua

@@ -5,6 +5,7 @@
 
 local Runtime = require("src.mods.Runtime")
 local Status = require("src.battle.Status")
+local Strings = require("src.core.Strings")
 
 local StatusRegistry = {}
 
@@ -45,7 +46,7 @@ function StatusRegistry.inflict(battle, target, status, opts)
   if record and record.onInflict then
     msgs = record.onInflict(battle, target, opts, display)
   else
-    msgs = { ("%s\nwas afflicted\nby %s!"):format(display,
+    msgs = { Strings("%s\nwas afflicted\nby %s!", display,
                record and record.label or tostring(status)) }
   end
   Runtime.emit("battle.status_inflicted", {

src/battle/TrainerAI.lua

@@ -19,6 +19,7 @@
 -- enemy PP — Gen 1 AI never reads wEnemyMonPP).
 
 local TypeChart = require("src.battle.TypeChart")
+local Strings = require("src.core.Strings")
 
 local TrainerAI = {}
 
@@ -99,7 +100,7 @@ function TrainerAI.useItem(battle, item)
   local enemy = battle.enemy
   local trainerName = battle.trainer.name
   local itemName = battle.data.items[item] and battle.data.items[item].name or item
-  local msgs = { ("%s\nused %s!"):format(trainerName, itemName) }
+  local msgs = { Strings("%s\nused %s!", trainerName, itemName) }
   if item == "FULL_HEAL" then
     enemy.mon.status = nil
     enemy.toxicCounter = nil
@@ -112,10 +113,10 @@ function TrainerAI.useItem(battle, item)
   elseif X_STAT[item] then
     local stat = X_STAT[item]
     enemy.stages[stat] = math.min(6, (enemy.stages[stat] or 0) + 1)
-    table.insert(msgs, ("%s's\n%s rose!"):format(enemy.name, stat:upper()))
+    table.insert(msgs, Strings("%s's\n%s rose!", enemy.name, stat:upper()))
   elseif item == "GUARD_SPEC" then
     enemy.mist = true
-    table.insert(msgs, ("%s's\nprotected against\nstat changes!"):format(enemy.name))
+    table.insert(msgs, Strings("%s's\nprotected against\nstat changes!", enemy.name))
   end
   return msgs
 end

src/battle/rulesets/gen1_faithful.lua

@@ -16,4 +16,7 @@ return {
   -- Wild/trainer enemies never spend PP (DecrementPP only touches the
   -- player side in pokered). They therefore never Struggle from empty PP.
   enemyUnlimitedPP = true,
+  -- Gen 1 Hyper Beam: no recharge when the target faints (or its
+  -- substitute breaks).  Set false to always recharge like Gen 2+.
+  hyperBeamSkipRechargeOnKO = true,
 }

src/battle/rulesets/modern_clean.lua

@@ -11,4 +11,6 @@ return {
   focusEnergyBug = false,
   -- Gen 2+ style: AI opponents deplete PP and can Struggle when empty.
   enemyUnlimitedPP = false,
+  -- Gen 2+: Hyper Beam always forces a recharge turn, even on a KO.
+  hyperBeamSkipRechargeOnKO = false,
 }

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

@@ -9,6 +9,7 @@
 local Json = require("src.link.Json")
 local Logger = require("src.core.Logger")
 local Runtime = require("src.mods.Runtime")
+local Strings = require("src.core.Strings")
 
 local DiscordPresence = {
   APP_ID = "1529183141267374262",
@@ -436,7 +437,7 @@ end
 local function buildActivity()
   local details, activityState
   if state.activity == "battle" then
-    details = state.battleLabel or "In battle"
+    details = state.battleLabel or Strings("In battle")
     activityState = state.location and (state.location) or "Kanto"
   elseif state.activity == "exploring" and state.location then
     details = state.location
@@ -550,20 +551,20 @@ local function subscribe(game)
 
   track("battle.started", function(ev)
     local battle = ev and ev.battle
-    local label = "In battle"
+    local label = Strings("In battle")
     if ev and ev.kind == "wild" then
       local name = speciesName(game, ev.species)
       if name then
         label = "Battling wild " .. name
         if ev.level then label = label .. " Lv" .. tostring(ev.level) end
       else
-        label = "Wild battle"
+        label = Strings("Wild battle")
       end
     elseif ev and ev.kind == "trainer" then
       local tname = battle and battle.trainer and battle.trainer.name
-      label = tname and ("Battling " .. tname) or "Trainer battle"
+      label = tname and ("Battling " .. tname) or Strings("Trainer battle")
     elseif ev and ev.kind == "link" then
-      label = "Link battle"
+      label = Strings("Link battle")
     end
     local mapId = state.mapId
       or (game.save and game.save.player and game.save.player.map)
@@ -594,7 +595,7 @@ local function subscribe(game)
       state.mapId = nil
       setPresence({
         activity = "menu",
-        location = id == "IntroMovie" and "Watching the intro" or "Title screen",
+        location = id == "IntroMovie" and "Watching the intro" or Strings("Title screen"),
         clearBattle = true,
       })
     end
@@ -783,5 +784,6 @@ 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()
@@ -50,6 +53,9 @@ function Game:load()
   require("src.render.Font").load(Data)
   -- menu cursor/border/geometry constants; field.theme restyles them
   require("src.ui.Theme").load(Data)
+  -- the engine's own text, after the merge so a translation mod's catalog
+  -- is already in Data.strings; empty on a mod-free boot and skipped
+  require("src.core.Strings").load(Data)
 
   self.stack = StateStack
   StateStack:init()
@@ -93,6 +99,20 @@ function Game:load()
   end
 
   Logger.info("game loaded")
+  -- Scaling bug reports (#87, #208) are unanswerable without these three
+  -- numbers: LOVE units, drawable pixels, and the integer physical pixels
+  -- per GB pixel the renderer settled on.  Cheap, once, and it turns "it
+  -- looks stretched" into something reproducible.
+  if love.graphics and love.graphics.getDimensions then
+    local ww, wh = love.graphics.getDimensions()
+    local pw, ph = ww, wh
+    if love.graphics.getPixelDimensions then
+      pw, ph = love.graphics.getPixelDimensions()
+    end
+    Logger.info(string.format(
+      "display: %dx%d units, %dx%d px, fit scale %d px/GB px",
+      ww, wh, pw, ph, Renderer:fitScale()))
+  end
 end
 
 -- the merged field.boot: spawn, names, money and the naming presets a
@@ -177,9 +197,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 +215,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 +260,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 +363,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 +391,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 +408,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 +419,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 +432,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 +495,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/Music.lua

@@ -24,7 +24,31 @@ local FILTER_HIGHGAIN = { 0.4, 0.16, 0.064 }
 local filterLevel = 0
 
 local function applyVolume(src)
-  if src then pcall(src.setVolume, src, VOLUME * volumeScale) end
+  if not src then return end
+  local vol = VOLUME * volumeScale
+  if Runtime.wantsHook("music.volume") then
+    local ctx = {
+      song = state.current,
+      mapSong = state.mapSong,
+      onBike = state.onBike,
+      surfing = state.surfing,
+      fading = state.fade ~= nil,
+      optionScale = volumeScale,
+    }
+    local ok, Game = pcall(require, "src.core.Game")
+    if ok and Game then
+      local ow = Game.overworld
+      if ow and ow.player then
+        ctx.x, ctx.y = ow.player.cellX, ow.player.cellY
+        ctx.mapId = ow.map and ow.map.id
+        ctx.tod = ow.tod
+      end
+    end
+    vol = Runtime.call("music.volume", function(v) return v end, vol, ctx)
+    vol = tonumber(vol) or (VOLUME * volumeScale)
+    if vol < 0 then vol = 0 end
+  end
+  pcall(src.setVolume, src, vol)
 end
 
 -- Source:setFilter needs OpenAL EFX; the pcall degrades to unfiltered
@@ -408,6 +432,12 @@ end
 -- restores the map theme after a one-shot jingle
 function Music.update(data)
   if state.chip then require("src.core.ChipAudio").update() end
+  -- distance / indoor muffling mods re-apply volume every frame while
+  -- subscribed; otherwise applyVolume only runs on song/option changes
+  if Runtime.wantsHook("music.volume") and not state.fade then
+    applyVolume(state.source)
+    applyVolume(state.loopSource)
+  end
   -- volume ramp (Music.fadeOut): hold the current level for `control`
   -- frames, then drop one level (FadeOutAudio decrements both rAUDVOL
   -- nibbles when its counter reaches 0); at level 0 the music stops.

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,302 @@ 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
+
+-- Delete a registered slot: remove its main/.bak/.tmp files, drop it from the
+-- options registry, and if it was active point active at another remaining
+-- slot (or clear active when the list is empty).  Returns true, or false +
+-- an error string when the id is unknown / not registered.
+function SaveData.deleteSlot(version, slotId)
+  version = version or GameVersion.get()
+  if not knownVersion(version) then return false, "unknown version" end
+  if type(slotId) ~= "string" or slotId == "" then
+    return false, "missing slot id"
+  end
+  local fs = persistFs(nil)
+  ensureVersionSlots(version, fs)
+  local opts = SaveData.loadOptions(fs)
+  opts.saveSlots = opts.saveSlots or {}
+  local reg = opts.saveSlots[version]
+  if not reg or not reg.list then return false, "slot not registered" end
+  local found, idx = false, nil
+  for i, id in ipairs(reg.list) do
+    if id == slotId then found = true; idx = i; break end
+  end
+  if not found then return false, "slot not registered" end
+
+  local main, bak, tmp = slotNames(version, slotId)
+  remove(fs, main)
+  remove(fs, bak)
+  remove(fs, tmp)
+
+  table.remove(reg.list, idx)
+  if reg.active == slotId then
+    reg.active = reg.list[1]  -- may be nil when the list is now empty
+  end
+  opts.saveSlots[version] = reg
+  SaveData.saveOptions(opts, fs)
+  slotsChecked[version] = true
+  activeSlotCache[version] = reg.active or false
+  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 +840,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
@@ -837,9 +1155,16 @@ function SaveData.defaultHeal(boot)
 end
 
 -- Post-credits home (issue #103).  pokered left the player in HALL_OF_FAME
--- after jp Init; this port places CONTINUE at the NewGameWarp bedroom and
--- retargets LAST_MAP exits (Red's house mats) at the heal-point town so
--- leaving the house does not dump the player back at Indigo Plateau.
+-- after jp Init; this port relocates CONTINUE instead, and retargets
+-- LAST_MAP exits (Red's house mats) at the heal-point town so leaving the
+-- house does not dump the player back at Indigo Plateau.
+--
+-- The landing spot is the blackout point, not the NewGameWarp bedroom:
+-- HallOfFameResetEventsAndSaveScript sets wLastBlackoutMap := PALLET_TOWN,
+-- so resuming puts the player outside the front door.  Spawning them back
+-- in the upstairs bedroom was a port-only detour (#253).  Non-vanilla
+-- spawns are unaffected -- defaultHeal returns boot's own start map for
+-- those, which is what the bedroom branch resolved to anyway.
 -- Marks postGameHomeOk so a later intentional HoF save is not relocated.
 function SaveData.applyPostGameHome(save, boot)
   boot = type(boot) == "table" and boot or {}
@@ -847,9 +1172,9 @@ function SaveData.applyPostGameHome(save, boot)
   save.lastHeal = { map = heal.map, x = heal.x, y = heal.y }
   save.lastOutdoor = { id = heal.map, x = heal.x, y = heal.y }
   save.player = save.player or {}
-  save.player.map = boot.startMap or "REDS_HOUSE_2F"
-  save.player.x = boot.startX or 3
-  save.player.y = boot.startY or 6
+  save.player.map = heal.map
+  save.player.x = heal.x
+  save.player.y = heal.y
   save.player.facing = boot.startFacing or "down"
   save.postGameHomeOk = true
   return heal

src/core/Strings.lua

@@ -0,0 +1,134 @@
+-- The engine's own player-facing text, made overridable.
+--
+-- Extracted dialogue already had a home: `Data.text`, keyed by pokered's
+-- labels, which a mod reaches through `mod.content.text`.  The strings the
+-- engine *authors* had none.  Battle messages, item results, menu labels
+-- and the link-play screens were literals in Lua, so a translator could
+-- reach two thirds of the game and no more (#186, #245).
+--
+-- Those literals stay where they are, wrapped in `S(...)`, and the English
+-- source doubles as the catalog key:
+--
+--   self:say(S("But, it failed!"))
+--   self:say(S("Wild %s\nappeared!", self.enemy.name))
+--
+-- Keying on the source rather than on an invented id is deliberate.  It
+-- keeps the English readable at the point it is used (the alternative
+-- scatters a thousand `battle.it_failed` ids that have to be looked up to
+-- review a diff), it needs no id registry to stay in sync, and an entry a
+-- translation has not covered yet falls through to English instead of
+-- rendering a raw id at the player.  The cost is that editing an English
+-- string orphans its translations; `tools/modkit.py translation --refresh`
+-- reports those as changed keys rather than silently dropping them.
+--
+-- Same-source-different-meaning is the one case source keys cannot hold on
+-- their own ("OFF" as a filter setting vs "OFF" as a toggle, which some
+-- languages render differently).  Those sites pass a context:
+--
+--   S("OFF", "options.musicFilter")   -- key: "options.musicFilter|OFF"
+--
+-- A mod supplies the catalog through the `strings` registry:
+--
+--   mod.content.strings:override("But, it failed!", "Echec !")
+--
+-- With no mod loaded the catalog is empty and `S` is an identity function
+-- guarded by one boolean, so a vanilla boot draws byte-identical text.
+
+local Strings = {}
+
+local catalog = nil   -- Data.strings once a mod has put something in it
+local missing = {}    -- format-arity complaints, reported once each
+
+-- Called from Game after the mod merge, and again on dev-mode hot reload.
+-- Holding the table (not a copy) means a mod that registers late still
+-- takes effect without a second load.
+function Strings.load(data)
+  local t = data and data.strings
+  catalog = nil
+  if type(t) ~= "table" then return end
+  for _ in pairs(t) do
+    catalog = t
+    return
+  end
+end
+
+function Strings.active()
+  return catalog ~= nil
+end
+
+-- The lookup itself.  `context` is optional and only disambiguates sources
+-- that collide; the plain key is tried after it, so a translation that does
+-- not care about the distinction can supply one entry for both.
+function Strings.lookup(source, context)
+  if not catalog then return source end
+  if context then
+    local hit = catalog[context .. "|" .. source]
+    if type(hit) == "string" then return hit end
+  end
+  local hit = catalog[source]
+  if type(hit) == "string" then return hit end
+  return source
+end
+
+-- Count `%`-directives so a translation that drops or adds one is caught
+-- here rather than as a mid-battle `string.format` error.
+local function specifiers(s)
+  local n = 0
+  for spec in s:gmatch("%%(.)") do
+    if spec ~= "%" then n = n + 1 end
+  end
+  return n
+end
+
+-- S(source)                -> translated source
+-- S(source, ...)           -> translated source, string.format'ed
+-- S(source, context)       -> context-disambiguated lookup, no formatting
+--
+-- The two-argument forms are told apart by whether the source carries any
+-- format directives: a source with no `%s` cannot be formatting, so a lone
+-- string second argument is a context.
+function Strings.get(source, ...)
+  local argc = select("#", ...)
+  if argc == 0 then return Strings.lookup(source) end
+
+  local wants = specifiers(source)
+  if wants == 0 and argc == 1 and type((...)) == "string" then
+    return Strings.lookup(source, (...))
+  end
+
+  local text = Strings.lookup(source)
+  -- A translation with the wrong arity would raise inside string.format,
+  -- which in a battle means a crash the player cannot escape.  Fall back to
+  -- the English source, which is known to match, and say so once.
+  if specifiers(text) ~= wants then
+    if not missing[source] then
+      missing[source] = true
+      require("src.core.Logger").warn(
+        "strings: translation of %q has %d format directives, source has %d"
+        .. " -- using the source", source, specifiers(text), wants)
+    end
+    text = source
+  end
+  local ok, out = pcall(string.format, text, ...)
+  if not ok then return source end
+  return out
+end
+
+-- A marker, not a lookup: returns its argument untouched.
+--
+-- Some templates are declared in a module-level table and formatted much
+-- later (BattleState's charge-move lines, for one).  Translating at the
+-- declaration would freeze the English, because those tables are built at
+-- require time and Strings.load has no catalog yet; the use site therefore
+-- calls Strings(template, ...) and looks the source up then.  That works at
+-- runtime but leaves the literal invisible to the catalog generator, which
+-- only sees what is spelled out at a call site.  Wrapping the declaration in
+-- Strings.source puts it back in the harvest while changing nothing at all
+-- about when the lookup happens.
+function Strings.source(text)
+  return text
+end
+
+setmetatable(Strings, { __call = function(_, ...) return Strings.get(...) end })
+
+return Strings

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,120 @@
+-- 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 f then
+    local data = f:read("*a")
+    f:close()
+    if type(data) ~= "string" then return nil, "the save file was empty" end
+    return data
+  end
+  -- Android SAF drops (picked_save.sav) and USB copies land in the LOVE save
+  -- directory; io.open cannot see them, so fall back to love.filesystem.
+  if love and love.filesystem and love.filesystem.read then
+    local data = love.filesystem.read(source)
+    if type(data) == "string" then return data end
+  end
+  return nil, "could not read the save file: " .. tostring(openErr)
+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

@@ -12,6 +12,7 @@
 
 local Pokemon = require("src.pokemon.Pokemon")
 local Flags = require("src.script.Flags")
+local Strings = require("src.core.Strings")
 
 local ItemEffects = {}
 
@@ -114,12 +115,13 @@ 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
-    return "failed", { "OAK: " .. save.player.name
-      .. "!\nThis isn't the\ntime to use that!" }
+                 or itemId == "RARE_CANDY" or itemId == "COIN_CASE"
+                 or (itemDef and itemDef.machine)) then
+    return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!",
+                               save.player.name) }
   end
 
   if BALLS[itemId] then
@@ -137,11 +139,12 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
       local mapId, npc = adjacentSleepingSnorlax(save, ow)
       if npc then
         return "flute_wake", { data.text._PlayedFluteHadEffectText
-          or "{PLAYER} played the\nPOKé FLUTE." }, { mapId = mapId, npc = npc }
+          or Strings("{PLAYER} played the\nPOKé FLUTE.") },
+          { mapId = mapId, npc = npc }
       end
       -- otherwise: play the tune, nothing happens (ItemUsePokeFlute's
       -- PlayedFluteNoEffectText branch)
-      return "flute_field", { "Played the POKé\nFLUTE.\fNow, that's a\ncatchy tune!" }
+      return "flute_field", { Strings("Played the POKé\nFLUTE.\fNow, that's a\ncatchy tune!") }
     end
     local woke = false
     local function wake(mon)
@@ -156,24 +159,24 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
     -- WakeUpEntireParty runs on the enemy's bench too
     for _, mon in ipairs(battle.enemyParty or {}) do wake(mon) end
     if not woke then
-      return "failed", { "Played the POKé\nFLUTE.\fNow, that's a\ncatchy tune!" }
+      return "failed", { Strings("Played the POKé\nFLUTE.\fNow, that's a\ncatchy tune!") }
     end
-    return "flute", { ("%s played the\nPOKé FLUTE."):format(save.player.name),
-                      "All sleeping\nPOKéMON woke up!" }
+    return "flute", { Strings("%s played the\nPOKé FLUTE.", save.player.name),
+                      Strings("All sleeping\nPOKéMON woke up!") }
   end
 
   -- battle-only items
   if X_ITEMS[itemId] or itemId == "DIRE_HIT" or itemId == "GUARD_SPEC"
      or itemId == "POKE_DOLL" then
     if not battle then
-      return "failed", { "OAK: " .. save.player.name .. "!\nThis isn't the\ntime to use that!" }
+      return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
     end
     local b = battle.player
     if itemId == "X_ACCURACY" then
       -- ItemUseXAccuracy sets USING_X_ACCURACY: moves never miss
       -- (not an accuracy stage)
       b.xAccuracy = true
-      return "consumed", { ("%s's\nhits will never\nmiss!"):format(b.name) }
+      return "consumed", { Strings("%s's\nhits will never\nmiss!", b.name) }
     end
     if X_ITEMS[itemId] then
       local stat = X_ITEMS[itemId]
@@ -182,28 +185,28 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
       -- effect, so at +6 it is still consumed and StatModifierUpEffect
       -- just prints "Nothing happened!"
       if cur >= 6 then
-        return "consumed", { "Nothing happened!" }
+        return "consumed", { Strings("Nothing happened!") }
       end
       b.stages[stat] = cur + 1
-      return "consumed", { ("%s's\n%s rose!"):format(b.name, stat:upper()) }
+      return "consumed", { Strings("%s's\n%s rose!", b.name, stat:upper()) }
     end
     -- ItemUseDireHit/ItemUseGuardSpec always set the bit and consume
     -- the item, even when it is already active
     if itemId == "DIRE_HIT" then
       b.focusEnergy = true
-      return "consumed", { ("%s's\ngetting pumped!"):format(b.name) }
+      return "consumed", { Strings("%s's\ngetting pumped!", b.name) }
     end
     if itemId == "GUARD_SPEC" then
       b.mist = true
-      return "consumed", { ("%s's\nprotected against\nstat changes!"):format(b.name) }
+      return "consumed", { Strings("%s's\nprotected against\nstat changes!", b.name) }
     end
     if itemId == "POKE_DOLL" then
       if battle.kind ~= "wild" then
         -- ItemUsePokeDoll jumps to ItemUseNotTime in trainer battles
-        return "failed", { "OAK: " .. save.player.name
-          .. "!\nThis isn't the\ntime to use that!" }
+        return "failed", { Strings(
+          "OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
       end
-      return "consumed_escape", { "The wild POKéMON\nran away!" }
+      return "consumed_escape", { Strings("The wild POKéMON\nran away!") }
     end
   end
 
@@ -212,7 +215,7 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
   -- restore every move with no menu.
   if itemId == "ETHER" or itemId == "MAX_ETHER"
      or itemId == "ELIXER" or itemId == "MAX_ELIXER" then
-    if not target then return "failed", { "It won't have\nany effect." } end
+    if not target then return "failed", { Strings("It won't have\nany effect.") } end
     local restored = false
     local full = itemId == "MAX_ETHER" or itemId == "MAX_ELIXER"
     local allMoves = itemId == "ELIXER" or itemId == "MAX_ELIXER"
@@ -234,9 +237,9 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
       restored = mv and restore(mv) or false
     end
     if not restored then
-      return "failed", { "It won't have\nany effect." }
+      return "failed", { Strings("It won't have\nany effect.") }
     end
-    return "consumed", { ("%s's PP\nwas restored!"):format(monName(data, target)) }
+    return "consumed", { Strings("%s's PP\nwas restored!", monName(data, target)) }
   end
 
   local heal = HEAL_AMOUNT[itemId]
@@ -249,17 +252,17 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
       target.status = nil
       cureActiveToxic(battle, target)
       require("src.core.Sound").play(data, "Heal_Ailment")
-      return "consumed", { ("%s's\nstatus returned\nto normal!"):format(monName(data, target)) }
+      return "consumed", { Strings("%s's\nstatus returned\nto normal!", monName(data, target)) }
     end
     if not target or target.hp <= 0 or target.hp >= target.stats.hp then
-      return "failed", { "It won't have\nany effect." }
+      return "failed", { Strings("It won't have\nany effect.") }
     end
     if itemId == "MAX_POTION" or itemId == "FULL_RESTORE" then
       target.hp = target.stats.hp
     else
       target.hp = math.min(target.stats.hp, target.hp + heal)
     end
-    local msgs = { ("%s's HP\nwas restored!"):format(monName(data, target)) }
+    local msgs = { Strings("%s's HP\nwas restored!", monName(data, target)) }
     if itemId == "FULL_RESTORE" then
       target.status = nil
       cureActiveToxic(battle, target)
@@ -271,27 +274,27 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
   local cures = STATUS_HEAL[itemId]
   if cures then
     if not target or not target.status or not cures[target.status] then
-      return "failed", { "It won't have\nany effect." }
+      return "failed", { Strings("It won't have\nany effect.") }
     end
     target.status = nil
     cureActiveToxic(battle, target)
     require("src.core.Sound").play(data, "Heal_Ailment")
-    return "consumed", { ("%s's\nstatus returned\nto normal!"):format(monName(data, target)) }
+    return "consumed", { Strings("%s's\nstatus returned\nto normal!", monName(data, target)) }
   end
 
   if itemId == "REVIVE" or itemId == "MAX_REVIVE" then
     if not target or target.hp > 0 then
-      return "failed", { "It won't have\nany effect." }
+      return "failed", { Strings("It won't have\nany effect.") }
     end
     target.status = nil
     target.hp = itemId == "REVIVE" and math.floor(target.stats.hp / 2) or target.stats.hp
     require("src.core.Sound").play(data, "Heal_HP")
-    return "consumed", { ("%s\nis revitalized!"):format(monName(data, target)) }
+    return "consumed", { Strings("%s\nis revitalized!", monName(data, target)) }
   end
 
   if itemId == "RARE_CANDY" then
     if not target or target.level >= 100 then
-      return "failed", { "It won't have\nany effect." }
+      return "failed", { Strings("It won't have\nany effect.") }
     end
     local Growth = require("src.pokemon.Growth")
     local Stats = require("src.pokemon.Stats")
@@ -301,56 +304,56 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
     local old = target.stats
     target.stats = Stats.calc(speciesDef, target.level, target.dvs, target.statExp)
     target.hp = math.min(target.stats.hp, target.hp + (target.stats.hp - old.hp))
-    return "consumed", { ("%s grew\nto level %d!"):format(monName(data, target), target.level) },
+    return "consumed", { Strings("%s grew\nto level %d!", monName(data, target), target.level) },
            { leveledTo = target.level }
   end
 
   if STONES[itemId] then
-    if not target then return "failed", { "It won't have\nany effect." } end
+    if not target then return "failed", { Strings("It won't have\nany effect.") } end
     local speciesDef = data.pokemon[target.species]
     for _, evo in ipairs(speciesDef.evolutions) do
       if evo.method == "ITEM" and evo.item == itemId then
         return "consumed", nil, { evolveTo = evo.species }
       end
     end
-    return "failed", { "It won't have\nany effect." }
+    return "failed", { Strings("It won't have\nany effect.") }
   end
 
   -- vitamins: +2560 stat exp, refused at 25600+ (ItemUseVitamin,
   -- engine/items/item_effects.asm)
   local vitaminStat = VITAMINS[itemId]
   if vitaminStat then
-    if not target then return "failed", { "It won't have\nany effect." } end
+    if not target then return "failed", { Strings("It won't have\nany effect.") } end
     target.statExp = target.statExp or {}
     local cur = target.statExp[vitaminStat] or 0
     if cur >= 25600 then
-      return "failed", { "It won't have\nany effect." }
+      return "failed", { Strings("It won't have\nany effect.") }
     end
     target.statExp[vitaminStat] = math.min(65535, cur + 2560)
     local Stats = require("src.pokemon.Stats")
     target.stats = Stats.calc(data.pokemon[target.species], target.level,
                               target.dvs, target.statExp)
     target.hp = math.min(target.hp, target.stats.hp)
-    return "consumed", { ("%s's %s\nrose!"):format(monName(data, target),
+    return "consumed", { Strings("%s's %s\nrose!", monName(data, target),
       vitaminStat == "hp" and "HP" or vitaminStat:upper()) }
   end
 
   -- PP UP boosts the move the player picked (ItemUsePPUp's move menu)
   if itemId == "PP_UP" then
-    if not target then return "failed", { "It won't have\nany effect." } end
+    if not target then return "failed", { Strings("It won't have\nany effect.") } end
     local mv = target.moves[moveIndex or 1]
     local mdef = mv and data.moves[mv.id]
     if mdef and (mv.ppUps or 0) < 3 then
       mv.ppUps = (mv.ppUps or 0) + 1
       -- each PP UP adds maxPP/5 uses on top of the base maximum
       mv.pp = mv.pp + math.floor(mdef.pp / 5)
-      return "consumed", { ("%s's PP\nincreased!"):format(mdef.name) }
+      return "consumed", { Strings("%s's PP\nincreased!", mdef.name) }
     end
-    return "failed", { "It won't have\nany effect." }
+    return "failed", { Strings("It won't have\nany effect.") }
   end
 
   if itemDef and itemDef.machine then
-    if not target then return "failed", { "It won't have\nany effect." } end
+    if not target then return "failed", { Strings("It won't have\nany effect.") } end
     local speciesDef = data.pokemon[target.species]
     local ok = false
     for _, m in ipairs(speciesDef.tmhm) do
@@ -361,11 +364,11 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
       -- plays SFX_DENIED before MonCannotLearnMachineMoveText (the generic
       -- ItemUseNotTime/NoCyclingAllowedHere paths are silent)
       require("src.core.Sound").play(data, "Denied")
-      return "failed", { ("%s can't\nlearn that move!"):format(monName(data, target)) }
+      return "failed", { Strings("%s can't\nlearn that move!", monName(data, target)) }
     end
     for _, mv in ipairs(target.moves) do
       if mv.id == itemDef.machine.move then
-        return "failed", { "It knows that\nmove already!" }
+        return "failed", { Strings("It knows that\nmove already!") }
       end
     end
     -- HMs are never consumed; TMs are single-use
@@ -374,14 +377,14 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
 
   if itemId == "OLD_ROD" or itemId == "GOOD_ROD" or itemId == "SUPER_ROD" then
     if battle then
-      return "failed", { "OAK: " .. save.player.name .. "!\nThis isn't the\ntime to use that!" }
+      return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
     end
     return "fish", itemId
   end
 
   if itemId == "BICYCLE" then
     if battle then
-      return "failed", { "OAK: " .. save.player.name .. "!\nThis isn't the\ntime to use that!" }
+      return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
     end
     return "bicycle"
   end
@@ -391,26 +394,26 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
   end
   if itemId == "TOWN_MAP" then
     if battle then
-      return "failed", { "OAK: " .. save.player.name .. "!\nThis isn't the\ntime to use that!" }
+      return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
     end
     return "townmap"
   end
   if itemId == "ITEMFINDER" then
     if battle then
-      return "failed", { "OAK: " .. save.player.name .. "!\nThis isn't the\ntime to use that!" }
+      return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
     end
     return "itemfinder"
   end
   if itemId == "COIN_CASE" then
-    return "failed", { ("Coin count:\n%d"):format(save.coins or 0) }
+    return "failed", { Strings("Coin count:\n%d", save.coins or 0) }
   end
   if itemId == "REPEL" or itemId == "SUPER_REPEL" or itemId == "MAX_REPEL" then
     local steps = itemId == "REPEL" and 100 or itemId == "SUPER_REPEL" and 200 or 250
     save.repelSteps = steps
-    return "consumed", { ("%s used\n%s!"):format(save.player.name, name) }
+    return "consumed", { Strings("%s used\n%s!", save.player.name, name) }
   end
 
-  return "failed", { "OAK: " .. save.player.name .. "!\nThis isn't the\ntime to use that!" }
+  return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
 end
 
 return ItemEffects

src/link/LinkBattle.lua

@@ -21,6 +21,7 @@ local Logger = require("src.core.Logger")
 local Protocol = require("src.link.Protocol")
 local Runtime = require("src.mods.Runtime")
 local TurnOrder = require("src.battle.TurnOrder")
+local Strings = require("src.core.Strings")
 
 local LinkBattle = {}
 
@@ -177,18 +178,18 @@ function LinkBattle.new(game, net, opts)
   local theirName = opts.theirName or "FOE"
 
   if not Handshake.battleAllowed(opts.verdict) then
-    return nil, "Link battle needs\nthe same mods on\nboth games."
+    return nil, Strings("Link battle needs\nthe same mods on\nboth games.")
   end
 
   -- 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, 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))
+    return Strings("Your %s can't\nbattle on the\nother game.", tostring(p.species))
   end)
   if not myParty then return nil, myErr end
   local theirParty, theirErr = unpackParty(game, opts.theirParty, unpackOpts, function(p, why)
-    return ("Their %s isn't\nin this game.\n(%s)"):format(tostring(p.species), tostring(why))
+    return Strings("Their %s isn't\nin this game.\n(%s)", tostring(p.species), tostring(why))
   end)
   if not theirParty then return nil, theirErr end
   if #myParty == 0 or #theirParty == 0 then
@@ -232,7 +233,7 @@ function LinkBattle.new(game, net, opts)
   self.enemyParty = theirParty
   self.playerParty = myParty -- intro ball row uses the clamped copies
   self.opponentName = theirName
-  self.introText = ("%s wants\nto battle!"):format(theirName)
+  self.introText = Strings("%s wants\nto battle!", theirName)
   self.remoteHashes = {}
   self.localHashes = {}
   self.remoteParts = {}
@@ -292,7 +293,7 @@ function LinkBattle.new(game, net, opts)
       battle = s, side = s.sides[2], battler = s.enemy, previous = previous,
     })
     s.enemySendingOut = true
-    s:sayNext(("%s sent\nout %s!"):format(theirName, s.enemy.name))
+    s:sayNext(Strings("%s sent\nout %s!", theirName, s.enemy.name))
     s:actNext(function()
       s.enemySendingOut = false
       s:startGrowIn(s.enemy)
@@ -315,8 +316,9 @@ function LinkBattle.new(game, net, opts)
                 tostring(turn), component, tostring(localH), tostring(remoteH))
     Runtime.emit("link.desync", { turn = turn, component = component,
                                   localHash = localH, remoteHash = remoteH })
-    endAsDraw(s, ("Link desync!\n%s differs.\fAre both games\nrunning the same\nmods?")
-                 :format(component))
+    endAsDraw(s, Strings(
+      "Link desync!\n%s differs.\fAre both games\nrunning the same\nmods?",
+      component))
   end
 
   -- a verified turn stays recorded: consuming it here left a finished
@@ -349,7 +351,7 @@ function LinkBattle.new(game, net, opts)
   local function resolveLockstep(s, myMsg, theirMsg)
     if myMsg.kind == "run" or theirMsg.kind == "run" then
       local who = myMsg.kind == "run" and game.save.player.name or theirName
-      endAsDraw(s, ("%s ran from\nthe battle!"):format(who))
+      endAsDraw(s, Strings("%s ran from\nthe battle!", who))
       return
     end
     s.phase = "messages"
@@ -479,9 +481,9 @@ function LinkBattle.new(game, net, opts)
         party = myParty,
         onSwitch = function(mon)
           if mon == s.player.mon then
-            s:say(("%s is\nalready out!"):format(s.player.name))
+            s:say(Strings("%s is\nalready out!", s.player.name))
           elseif mon.hp <= 0 then
-            s:say("There's no will\nto fight!")
+            s:say(Strings("There's no will\nto fight!"))
           else
             s:resolveSwitch(mon)
           end
@@ -491,7 +493,7 @@ function LinkBattle.new(game, net, opts)
   end
 
   self.openItems = function(s)
-    s:say("Items can't be\nused in a link\nbattle!")
+    s:say(Strings("Items can't be\nused in a link\nbattle!"))
     s.phase = "messages"
     s.afterQueue = "menu"
   end
@@ -509,7 +511,7 @@ function LinkBattle.new(game, net, opts)
         return
       end
     end
-    s:sayNext(("%s is out of\nPOKéMON!\f%s wins!"):format(game.save.player.name,
+    s:sayNext(Strings("%s is out of\nPOKéMON!\f%s wins!", game.save.player.name,
                                                           theirName))
     s.result = "lose"
     s.afterQueue = "finish"
@@ -522,7 +524,7 @@ function LinkBattle.new(game, net, opts)
         return
       end
     end
-    s:sayNext(("%s is out of\nPOKéMON!\f%s wins!"):format(theirName,
+    s:sayNext(Strings("%s is out of\nPOKéMON!\f%s wins!", theirName,
                                                           game.save.player.name))
     s.result = "win"
     s.afterQueue = "finish"
@@ -543,13 +545,13 @@ function LinkBattle.new(game, net, opts)
         -- only a draw if our own simulation hasn't already decided
         -- (the winner's bye can arrive while we're still animating)
         if not s.result then
-          endAsDraw(s, ("%s left the\nbattle."):format(theirName))
+          endAsDraw(s, Strings("%s left the\nbattle.", theirName))
         end
       elseif msg.type == "forfeit" then
         -- the peer's own shot clock ran out; unlike a mutual RUN/desync
         -- draw, this has a definite winner (us)
         if not s.result then
-          endWithResult(s, "win", ("%s ran out of\ntime!"):format(theirName))
+          endWithResult(s, "win", Strings("%s ran out of\ntime!", theirName))
         end
       else
         -- a tournament control message (bracket_update, the next
@@ -582,7 +584,7 @@ function LinkBattle.new(game, net, opts)
       if s.turnClock <= 0 then
         s.turnClockActive = false
         send({ type = "forfeit" })
-        endWithResult(s, "lose", "Time's up! You\nforfeit the match.")
+        endWithResult(s, "lose", Strings("Time's up! You\nforfeit the match."))
       end
     elseif opts.turnLimit then
       s.turnClockActive = false
@@ -643,17 +645,16 @@ function LinkBattle.newSpectator(game, net, opts)
   local guestName = opts.guestName or "GUEST"
 
   if not Handshake.battleAllowed(opts.verdict) then
-    return nil, "Link battle needs\nthe same mods on\nboth games."
+    return nil, Strings("Link battle needs\nthe same mods on\nboth games.")
   end
 
   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))
+    return Strings("%s's %s can't\nbattle on this\ngame.", hostName, tostring(p.species))
   end)
   if not hostParty then return nil, hostErr end
   local guestParty, guestErr = unpackParty(game, opts.guestParty, unpackOpts, function(p, why)
-    return ("%s's %s can't\nbattle on this\ngame.\n(%s)"):format(
-      guestName, tostring(p.species), tostring(why))
+    return Strings("%s's %s can't\nbattle on this\ngame.\n(%s)", guestName, tostring(p.species), tostring(why))
   end)
   if not guestParty then return nil, guestErr end
   if #hostParty == 0 or #guestParty == 0 then
@@ -672,7 +673,7 @@ function LinkBattle.newSpectator(game, net, opts)
   self.enemyParty = guestParty
   self.playerParty = hostParty
   self.opponentName = guestName
-  self.introText = ("%s vs %s!"):format(hostName, guestName)
+  self.introText = Strings("%s vs %s!", hostName, guestName)
 
   local function orderMove(action)
     if action and action.id then return game.data.moves[action.id] end
@@ -712,7 +713,7 @@ function LinkBattle.newSpectator(game, net, opts)
       battle = s, side = s.sides[2], battler = s.enemy, previous = previous,
     })
     s.enemySendingOut = true
-    s:sayNext(("%s sent\nout %s!"):format(guestName, s.enemy.name))
+    s:sayNext(Strings("%s sent\nout %s!", guestName, s.enemy.name))
     s:actNext(function()
       s.enemySendingOut = false
       s:startGrowIn(s.enemy)
@@ -789,7 +790,7 @@ function LinkBattle.newSpectator(game, net, opts)
         return
       end
     end
-    s:sayNext(("%s is out of\nPOKéMON!\f%s wins!"):format(hostName, guestName))
+    s:sayNext(Strings("%s is out of\nPOKéMON!\f%s wins!", hostName, guestName))
     s.result = "guestWin"
     s.afterQueue = "finish"
   end
@@ -801,7 +802,7 @@ function LinkBattle.newSpectator(game, net, opts)
         return
       end
     end
-    s:sayNext(("%s is out of\nPOKéMON!\f%s wins!"):format(guestName, hostName))
+    s:sayNext(Strings("%s is out of\nPOKéMON!\f%s wins!", guestName, hostName))
     s.result = "hostWin"
     s.afterQueue = "finish"
   end

src/link/LinkState.lua

@@ -11,6 +11,7 @@ local Protocol = require("src.link.Protocol")
 local Runtime = require("src.mods.Runtime")
 local Screens = require("src.ui.Screens")
 local TextBox = require("src.render.TextBox")
+local Strings = require("src.core.Strings")
 
 local LinkState = {}
 LinkState.__index = LinkState
@@ -31,7 +32,12 @@ local function indexOf(list, value)
 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)
@@ -85,7 +91,7 @@ function LinkState.newJoinOnline(game, code)
     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 "?"))
+    self:exitWith(Strings("Link error:\n%s", self.net.error or "?"))
   end
   return self
 end
@@ -169,7 +175,7 @@ function LinkState:update(dt)
   if self.net then
     self.net:update()
     if self.net.error and not PRE_CONNECT_STAGES[self.stage] then
-      self:exitWith("Link error:\n" .. self.net.error:sub(1, 60))
+      self:exitWith(Strings("Link error:\n%s", self.net.error:sub(1, 60)))
       return
     end
     -- the peer vanished without a bye (only once the inbox is drained,
@@ -178,7 +184,7 @@ function LinkState:update(dt)
        and not PRE_CONNECT_STAGES[self.stage] and self.stage ~= "addrEntry"
        and self.stage ~= "codeEntry" and self.stage ~= "notice"
        and self.stage ~= "battleRunning" then
-      self:exitWith("The link was\nbroken.")
+      self:exitWith(Strings("The link was\nbroken."))
       return
     end
   end
@@ -196,7 +202,7 @@ function LinkState:update(dt)
         self.index = 1
       elseif self.index == 2 or self.index == 3 then
         if not Handshake.onlineAllowed(self.game) then
-          self:exitWith("Online play needs\nno mods enabled.\fDisable them in\nSTART > MODS.")
+          self:exitWith(Strings("Online play needs\nno mods enabled.\fDisable them in\nSTART > MODS."))
           return
         end
         if self.index == 2 then
@@ -222,7 +228,7 @@ function LinkState:update(dt)
         if self.net:host() then
           self.stage = "hosting"
         else
-          self:exitWith("Link error:\n" .. (self.net.error or "?"))
+          self:exitWith(Strings("Link error:\n%s", self.net.error or "?"))
         end
       else
         self.stage = "addrEntry"
@@ -241,7 +247,7 @@ function LinkState:update(dt)
         if self.net:hostOnline() then
           self.stage = "onlineHosting"
         else
-          self:exitWith("Link error:\n" .. (self.net.error or "?"))
+          self:exitWith(Strings("Link error:\n%s", self.net.error or "?"))
         end
       else
         self.stage = "codeEntry"
@@ -279,7 +285,7 @@ function LinkState:update(dt)
       if self.net:joinOnline(nil, code) then
         self.stage = "onlineJoining"
       else
-        self:exitWith("Link error:\n" .. (self.net.error or "?"))
+        self:exitWith(Strings("Link error:\n%s", self.net.error or "?"))
       end
     end
 
@@ -318,7 +324,7 @@ function LinkState:update(dt)
       if self.net:join(table.concat(octets, ".")) then
         self.stage = "joining"
       else
-        self:exitWith("Link error:\n" .. (self.net.error or "?"))
+        self:exitWith(Strings("Link error:\n%s", self.net.error or "?"))
       end
     end
 
@@ -428,7 +434,7 @@ function LinkState:update(dt)
         end
         if not battle then
           self.net:send({ type = "bye" })
-          self:exitWith(why or "Link battle\ncan't start.", "error")
+          self:exitWith(why or Strings("Link battle\ncan't start."), "error")
           return
         end
         self.game.stack:push(battle)
@@ -486,13 +492,21 @@ function LinkState:updateTrade(input)
   local t = self.trade
 
   if t.stage == "cancelled" then
-    self:exitWith(t.error and ("The trade stopped:\n%s."):format(t.error)
-                  or "The trade was\ncancelled.")
+    self:exitWith(t.error and Strings("The trade stopped:\n%s.", t.error)
+                  or Strings("The trade was\ncancelled."))
     return
   end
   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()
@@ -501,12 +515,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),
+          Strings("Trade completed!\f%s received\n%s!", 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,
@@ -524,7 +548,7 @@ function LinkState:updateTrade(input)
     -- the trade) -- B is dead after that, matching the A branch's own
     -- self.confirmed == nil guard
     self.net:send({ type = "bye" })
-    self:exitWith("The trade was\ncancelled.")
+    self:exitWith(Strings("The trade was\ncancelled."))
   elseif t.stage == "picking" and input:wasPressed("a") then
     if t:canPick(self.index) then
       self.net:send(t:pick(self.index))
@@ -551,30 +575,30 @@ end
 function LinkState:draw()
   if self.stage == "menu" then
     drawTitle("BOIS CLUB LIVE")
-    Font.draw("LINK CABLE (LAN)", 32, 44)
-    Font.draw("ONLINE MATCH", 32, 60)
-    Font.draw("TOURNAMENT", 32, 76)
+    Font.draw(Strings("LINK CABLE (LAN)"), 32, 44)
+    Font.draw(Strings("ONLINE MATCH"), 32, 60)
+    Font.draw(Strings("TOURNAMENT"), 32, 76)
     Font.drawCode(CURSOR, 24, 44 + (self.index - 1) * 16)
 
   elseif self.stage == "lanMenu" then
     drawTitle("LINK CABLE (LAN)")
-    Font.draw("HOST A GAME", 32, 48)
-    Font.draw("JOIN A GAME", 32, 68)
+    Font.draw(Strings("HOST A GAME"), 32, 48)
+    Font.draw(Strings("JOIN A GAME"), 32, 68)
     Font.drawCode(CURSOR, 24, self.index == 1 and 48 or 68)
-    Font.draw("UDP port " .. Net.defaultPort(), 8, 128)
+    Font.draw(Strings("UDP port %s", Net.defaultPort()), 8, 128)
 
   elseif self.stage == "onlineMenu" then
     drawTitle("ONLINE MATCH")
-    Font.draw("HOST ONLINE", 32, 48)
-    Font.draw("JOIN ONLINE", 32, 68)
+    Font.draw(Strings("HOST ONLINE"), 32, 48)
+    Font.draw(Strings("JOIN ONLINE"), 32, 68)
     Font.drawCode(CURSOR, 24, self.index == 1 and 48 or 68)
 
   elseif self.stage == "onlineHosting" then
     drawTitle("HOSTING ONLINE")
-    Font.draw("Tell your friend", 16, 40)
-    Font.draw("the code:", 16, 52)
+    Font.draw(Strings("Tell your friend"), 16, 40)
+    Font.draw(Strings("the code:"), 16, 52)
     Font.draw(self.net.code or "??????", 32, 68)
-    Font.draw("Waiting for join...", 8, 96)
+    Font.draw(Strings("Waiting for join..."), 8, 96)
 
   elseif self.stage == "codeEntry" then
     drawTitle("ENTER CODE")
@@ -586,18 +610,18 @@ function LinkState:draw()
         Font.drawCode(0xEE, x, 76) -- ▼ under the active slot
       end
     end
-    Font.draw("A: connect  B: back", 8, 128)
+    Font.draw(Strings("A: connect  B: back"), 8, 128)
 
   elseif self.stage == "onlineJoining" then
     drawTitle("CONNECTING...")
-    Font.draw("Calling...", 8, 56)
+    Font.draw(Strings("Calling..."), 8, 56)
     Font.draw(self.net.target or "", 8, 72)
 
   elseif self.stage == "hosting" then
     drawTitle("HOSTING")
-    Font.draw("Friend joins at:", 16, 48)
+    Font.draw(Strings("Friend joins at:"), 16, 48)
     Font.draw(self.net.address or "?", 16, 64)
-    Font.draw("Waiting for join...", 8, 96)
+    Font.draw(Strings("Waiting for join..."), 8, 96)
 
   elseif self.stage == "addrEntry" then
     drawTitle("ENTER HOST ADDRESS")
@@ -612,34 +636,34 @@ function LinkState:draw()
     for octet = 1, 3 do
       Font.draw(".", 16 + octet * 32 - 8, 64)
     end
-    Font.draw("Port: " .. Net.defaultPort(), 16, 96)
-    Font.draw("A: connect  B: back", 8, 128)
+    Font.draw(Strings("Port: %s", Net.defaultPort()), 16, 96)
+    Font.draw(Strings("A: connect  B: back"), 8, 128)
 
   elseif self.stage == "joining" then
     drawTitle("JOINING...")
-    Font.draw("Calling...", 8, 56)
+    Font.draw(Strings("Calling..."), 8, 56)
     Font.draw(self.net.target or "", 8, 72)
 
   elseif self.stage == "modeSelect" then
     drawTitle("CONNECTED!")
-    Font.draw("TRADE", 32, 48)
-    Font.draw("BATTLE", 32, 68)
+    Font.draw(Strings("TRADE"), 32, 48)
+    Font.draw(Strings("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(Strings("LEVELS:"), 16, 56)
     Font.draw(forceLevelLabel(self.levelChoice or ANY), 88, 56)
-    Font.draw("A: continue  B: back", 8, 128)
+    Font.draw(Strings("A: continue  B: back"), 8, 128)
 
   elseif self.stage == "waitMode" or self.stage == "waitHello" then
     drawTitle("CONNECTED!")
     if self.stage == "waitHello" then
-      Font.draw("Checking the", 16, 56)
-      Font.draw("other game...", 16, 72)
+      Font.draw(Strings("Checking the"), 16, 56)
+      Font.draw(Strings("other game..."), 16, 72)
     else
-      Font.draw("Waiting for the", 16, 56)
-      Font.draw("host to choose...", 16, 72)
+      Font.draw(Strings("Waiting for the"), 16, 56)
+      Font.draw(Strings("host to choose..."), 16, 72)
     end
 
   elseif self.stage == "notice" then
@@ -648,12 +672,12 @@ function LinkState:draw()
       if i > 8 then break end -- what fits above the prompt row
       Font.draw(line, 8, 24 + (i - 1) * 12)
     end
-    Font.draw(self.noticeExits and "A: back" or "A: trade anyway", 8, 128)
+    Font.draw(self.noticeExits and "A: back" or Strings("A: trade anyway"), 8, 128)
 
   elseif self.stage == "trade" then
     drawTitle("TRADE")
     local t = self.trade
-    Font.draw("YOURS", 8, 20)
+    Font.draw(Strings("YOURS"), 8, 20)
     for i, mon in ipairs(self.game.save.party) do
       local def = self.game.data.pokemon[mon.species]
       local label = (mon.nickname or def.name):sub(1, 8)
@@ -661,7 +685,7 @@ function LinkState:draw()
       Font.draw(label, 16, 20 + i * 12)
       if i == self.index then Font.drawCode(CURSOR, 8, 20 + i * 12) end
     end
-    Font.draw("THEIRS", 84, 20)
+    Font.draw(Strings("THEIRS"), 84, 20)
     for i, mon in ipairs(t.theirParty or {}) do
       local def = self.game.data.pokemon[mon.species]
       Font.draw((mon.nickname or def.name):sub(1, 8), 92, 20 + i * 12)
@@ -672,16 +696,16 @@ function LinkState:draw()
     elseif t.stage == "waitParty" then hint = "Exchanging data..."
     elseif t.stage == "picking" then
       hint = t:canPick(self.index) and "Pick one to trade"
-             or "X: not on theirs"
+             or Strings("X: not on theirs")
     elseif t.stage == "waitPick" then hint = "Waiting for them..."
     elseif t.stage == "confirming" then
-      hint = self.confirmed and "Waiting..." or "A: trade  B: cancel"
+      hint = self.confirmed and "Waiting..." or Strings("A: trade  B: cancel")
     end
     Font.draw(hint or "", 8, 132)
 
   elseif self.stage == "battleWait" or self.stage == "battleRunning" then
     drawTitle("LINK BATTLE")
-    Font.draw("Exchanging data...", 16, 64)
+    Font.draw(Strings("Exchanging data..."), 16, 64)
   end
   love.graphics.setColor(1, 1, 1, 1)
 end

src/link/Net.lua

@@ -26,6 +26,7 @@
 
 local Json = require("src.link.Json")
 local Logger = require("src.core.Logger")
+local Strings = require("src.core.Strings")
 
 local hasEnet, enet = pcall(require, "enet")
 if not hasEnet then enet = nil end
@@ -173,7 +174,7 @@ function Net:connectTCP(addr)
   tcp:settimeout(5)
   local ok, err = tcp:connect(host, port)
   if not ok then
-    self.error = ("can't reach relay %s:%d\n(%s)"):format(host, port, tostring(err))
+    self.error = Strings("can't reach relay %s:%d\n(%s)", host, port, tostring(err))
     return false
   end
   tcp:settimeout(0)
@@ -236,11 +237,14 @@ local function handleGenericRelayControl(self, msg)
     self.paired = true
     return true
   elseif msg.type == "join_error" then
-    self.error = ({
-      not_found = "That code wasn't\nfound.",
-      full = "That game already\nhas two players.",
-      expired = "That code has\nexpired.",
-    })[msg.reason] or ("Couldn't join:\n%s"):format(tostring(msg.reason))
+    self.error = Strings(({
+      not_found = Strings.source("That code wasn't\nfound."),
+      full = Strings.source("That game already\nhas two players."),
+      expired = Strings.source("That code has\nexpired."),
+    })[msg.reason] or "")
+    if self.error == "" then
+      self.error = Strings("Couldn't join:\n%s", tostring(msg.reason))
+    end
     self.closed = true
     return true
   elseif msg.type == "peer_gone" then
@@ -328,7 +332,7 @@ function Net:update()
       -- an unreachable join target surfaces as a service error
       -- (ICMP unreachable on the connected UDP socket)
       if self.mode == "joining" and not self.paired then
-        self.error = ("no answer from\n%s"):format(self.target or "the host")
+        self.error = Strings("no answer from\n%s", self.target or "the host")
       else
         self.error = tostring(event)
       end
@@ -358,14 +362,14 @@ function Net:update()
         self.closed = true
         if not self.paired then
           self.error = self.error or
-            ("no answer from\n%s"):format(self.target or "the host")
+            Strings("no answer from\n%s", self.target or "the host")
         end
       end
     end
   end
   if self.mode == "joining" and not self.paired
      and self.joinDeadline and now() > self.joinDeadline then
-    self.error = ("no answer from\n%s"):format(self.target or "the host")
+    self.error = Strings("no answer from\n%s", self.target or "the host")
     self.closed = true
     pcall(function() self.peer:disconnect_now() end)
   end

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,6 +78,14 @@ 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
@@ -81,8 +96,8 @@ function Protocol.unpackMon(data, packed, opts)
   -- 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 opts and opts.forceLevel then
-    level = math.max(2, math.min(100, math.floor(opts.forceLevel)))
+  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
@@ -115,10 +130,19 @@ function Protocol.unpackMon(data, packed, opts)
   -- 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 = opts and opts.forceLevel
+  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,
@@ -129,6 +153,8 @@ function Protocol.unpackMon(data, packed, opts)
     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

@@ -18,6 +18,7 @@ local Protocol = require("src.link.Protocol")
 local Runtime = require("src.mods.Runtime")
 local Sound = require("src.core.Sound")
 local TextBox = require("src.render.TextBox")
+local Strings = require("src.core.Strings")
 
 local Tournament = {}
 Tournament.__index = Tournament
@@ -57,7 +58,12 @@ 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)
@@ -123,7 +129,7 @@ end
 function Tournament:startHosting()
   self.net = Net.new()
   if not self.net:connectTCP(Net.defaultRelayAddress()) then
-    self:exitWith("Link error:\n" .. (self.net.error or "?"))
+    self:exitWith(Strings("Link error:\n%s", self.net.error or "?"))
     return
   end
   local size, minL, maxL = partyStats(self.game.save.party)
@@ -146,7 +152,7 @@ end
 function Tournament:startJoining(code)
   self.net = Net.new()
   if not self.net:connectTCP(Net.defaultRelayAddress()) then
-    self:exitWith("Link error:\n" .. (self.net.error or "?"))
+    self:exitWith(Strings("Link error:\n%s", self.net.error or "?"))
     return
   end
   local size, minL, maxL = partyStats(self.game.save.party)
@@ -166,9 +172,9 @@ end
 -- -------------------------------------------------------------------
 
 local JOIN_ERROR_TEXT = {
-  not_found = "That code wasn't\nfound.",
-  already_started = "That tournament\nhas already begun.",
-  expired = "That code has\nexpired.",
+  not_found = Strings.source("That code wasn't\nfound."),
+  already_started = Strings.source("That tournament\nhas already begun."),
+  expired = Strings.source("That code has\nexpired."),
 }
 
 function Tournament:handleMessage(msg)
@@ -193,17 +199,17 @@ function Tournament:handleMessage(msg)
     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(
-        msg.requiredPartySize, levelLabel(msg.minLevel), levelLabel(msg.maxLevel)))
+      self:exitWith(Strings("Can't host:\nneed %d Pokemon\nLv %s-%s.", msg.requiredPartySize, levelLabel(msg.minLevel), levelLabel(msg.maxLevel)))
     else
-      self:exitWith("Couldn't host\nthat tournament.")
+      self:exitWith(Strings("Couldn't host\nthat tournament."))
     end
   elseif msg.type == "tournament_join_error" then
     if msg.reason == "party_ineligible" then
-      self:exitWith(("Your party needs\n%d Pokemon, Lv\n%s-%s."):format(
-        msg.requiredPartySize, levelLabel(msg.minLevel), levelLabel(msg.maxLevel)))
+      self:exitWith(Strings("Your party needs\n%d Pokemon, Lv\n%s-%s.", msg.requiredPartySize, levelLabel(msg.minLevel), levelLabel(msg.maxLevel)))
     else
-      self:exitWith(JOIN_ERROR_TEXT[msg.reason] or "Couldn't join\nthat tournament.")
+      self:exitWith(JOIN_ERROR_TEXT[msg.reason]
+                    and Strings(JOIN_ERROR_TEXT[msg.reason])
+                    or Strings("Couldn't join\nthat tournament."))
     end
   elseif msg.type == "tournament_roster" then
     self.roster = msg.players
@@ -276,7 +282,7 @@ function Tournament:beginMatchBattle()
     -- shouldn't happen (both sides already passed the online-play mods
     -- gate), but a mismatched engine/build is still possible -- bail out
     -- of just this match rather than crash the tournament
-    self:exitWith("Link error:\nversion mismatch\nwith opponent.")
+    self:exitWith(Strings("Link error:\nversion mismatch\nwith opponent."))
     return
   end
   self.linkSeed = self.isHost and love.math.random(1, 2 ^ 30) or nil
@@ -346,11 +352,11 @@ function Tournament:update(dt)
     self.net:update()
     if self.net.error and self.stage ~= "menu" and self.stage ~= "hostSettings"
        and self.stage ~= "codeEntry" then
-      self:exitWith("Link error:\n" .. self.net.error:sub(1, 60))
+      self:exitWith(Strings("Link error:\n%s", self.net.error:sub(1, 60)))
       return
     end
     if self.net.closed and self.stage ~= "done" then
-      self:exitWith("The tournament\nconnection was\nlost.")
+      self:exitWith(Strings("The tournament\nconnection was\nlost."))
       return
     end
   end
@@ -376,7 +382,7 @@ function Tournament:update(dt)
           and LinkBattle.newHost(self.game, self.net, self.pendingBattleOpts)
           or LinkBattle.newGuest(self.game, self.net, self.pendingBattleOpts)
         if not battle then
-          self:exitWith(why or "Link battle\ncan't start.")
+          self:exitWith(why or Strings("Link battle\ncan't start."))
           return
         end
         -- anything after `party` in this same batch belongs to the
@@ -413,7 +419,7 @@ function Tournament:update(dt)
             forceLevel = levelForWire(self.settings.forceLevel),
           })
           if not battle then
-            self:exitWith(why or "Can't watch this\nmatch.")
+            self:exitWith(why or Strings("Can't watch this\nmatch."))
             return
           end
           for j = #msgs, i + 1, -1 do
@@ -536,8 +542,8 @@ local SETTINGS_LABELS = { "POKEMON", "MIN LV", "MAX LV", "TIMER", "LEVELS", "PLA
 function Tournament:draw()
   if self.stage == "menu" then
     drawTitle("TOURNAMENT")
-    Font.draw("HOST", 32, 48)
-    Font.draw("JOIN", 32, 68)
+    Font.draw(Strings("HOST"), 32, 48)
+    Font.draw(Strings("JOIN"), 32, 68)
     Font.drawCode(CURSOR, 24, self.index == 1 and 48 or 68)
 
   elseif self.stage == "hostSettings" then
@@ -556,7 +562,7 @@ function Tournament:draw()
       Font.draw(values[i], 96, y)
       if i == self.settingsIndex then Font.drawCode(CURSOR, 8, y) end
     end
-    Font.draw("START: create", 8, 128)
+    Font.draw(Strings("START: create"), 8, 128)
 
   elseif self.stage == "codeEntry" then
     drawTitle("ENTER CODE")
@@ -568,28 +574,27 @@ function Tournament:draw()
         Font.drawCode(0xEE, x, 76)
       end
     end
-    Font.draw("A: join  B: back", 8, 128)
+    Font.draw(Strings("A: join  B: back"), 8, 128)
 
   elseif self.stage == "registering" then
     drawTitle("CONNECTING...")
-    Font.draw("B: cancel", 8, 128)
+    Font.draw(Strings("B: cancel"), 8, 128)
 
   elseif self.stage == "bracket" or self.stage == "matchHello"
       or self.stage == "matchWaitParty" or self.stage == "spectateWait" then
-    drawTitle(("TOURNAMENT %s"):format(self.code or "??????"))
+    drawTitle(Strings("TOURNAMENT %s", self.code or "??????"))
     if self.bracket then
       local y = 20
       for _, round in ipairs(self.bracket.rounds) do
-        Font.draw(("ROUND %d"):format(round.round), 8, y)
+        Font.draw(Strings("ROUND %d", round.round), 8, y)
         y = y + 10
         for _, m in ipairs(round.matches) do
           local line
           if m.bye then
-            line = ("%s (bye)"):format(m.a or m.b or "?")
+            line = Strings("%s (bye)", m.a or m.b or "?")
           else
             local mark = m.state == "live" and "*" or (m.winner and "" or "")
-            line = ("%s%s vs %s%s"):format(
-              m.winner == m.a and ">" or " ", m.a or "?",
+            line = Strings("%s%s vs %s%s", m.winner == m.a and ">" or " ", m.a or "?",
               m.b or "?", m.winner == m.b and "<" or (mark == "*" and " *" or ""))
           end
           Font.draw(line, 12, y)
@@ -599,11 +604,11 @@ function Tournament:draw()
       end
     else
       if self.participating == false then
-        Font.draw("(organizing --", 16, 32)
-        Font.draw("not playing)", 16, 42)
+        Font.draw(Strings("(organizing --"), 16, 32)
+        Font.draw(Strings("not playing)"), 16, 42)
       end
-      Font.draw("Waiting for", 16, 48)
-      Font.draw("players to join:", 16, 60)
+      Font.draw(Strings("Waiting for"), 16, 48)
+      Font.draw(Strings("players to join:"), 16, 60)
       local y = 60
       for i, name in ipairs(self.roster) do
         y = 60 + i * 10
@@ -615,18 +620,18 @@ function Tournament:draw()
       end
     end
     if self.isCreator and #self.roster >= 2 and not self.bracket then
-      Font.draw("A: START  B: cancel", 8, 132)
+      Font.draw(Strings("A: START  B: cancel"), 8, 132)
     else
-      Font.draw("B: cancel", 8, 132)
+      Font.draw(Strings("B: cancel"), 8, 132)
     end
 
   elseif self.stage == "done" then
     drawTitle("TOURNAMENT OVER")
     if self.champion then
-      Font.draw(("%s is the"):format(self.champion), 16, 56)
-      Font.draw("champion!", 16, 68)
+      Font.draw(Strings("%s is the", self.champion), 16, 56)
+      Font.draw(Strings("champion!"), 16, 68)
     end
-    Font.draw("A: continue", 8, 128)
+    Font.draw(Strings("A: continue"), 8, 128)
   end
   love.graphics.setColor(1, 1, 1, 1)
 end

src/mods/LauncherMods.lua

@@ -0,0 +1,366 @@
+-- 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,
+-- installs a dropped/chosen .zip into the save-dir "mods/<id>/" tree, and
+-- uninstalls a mod by removing that tree + clearing options.mods[id].
+--
+-- Split in two: the pure derivation (deriveList, locateRoot) has no love and
+-- no filesystem, so the engine tier can table-drive it; the discovery,
+-- install, and uninstall 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
+
+-- uninstall(id) -> true  |  nil, errString
+-- Removes mods/<id>/ from the save directory and clears options.mods[id] so the
+-- loader and in-game manager no longer see it.  Rejects unknown / missing ids.
+-- Does not touch other mods' enable state.
+function LauncherMods.uninstall(id)
+  if type(id) ~= "string" or id == "" then
+    return nil, "missing mod id"
+  end
+  if id:find("[/\\]") or id == "." or id == ".." then
+    return nil, "invalid mod id"
+  end
+  if not (love and love.filesystem) then
+    return nil, "mod uninstall needs LOVE"
+  end
+  local fs = love.filesystem
+  local dest = "mods/" .. id
+  if not fs.getInfo(dest) then
+    return nil, "mod '" .. id .. "' is not installed"
+  end
+  removeTree(dest)
+  -- Drop the enable flag so a reinstall of the same id starts from the
+  -- loader's default (enabled) rather than a stale false.
+  local options = SaveData.loadOptions()
+  if options.mods and options.mods[id] ~= nil then
+    options.mods[id] = nil
+    SaveData.saveOptions(options)
+  end
+  return true
+end
+
+return LauncherMods

src/mods/Loader.lua

@@ -68,6 +68,7 @@ local devShim = { installed = false, permissions = {}, warned = {}, depth = 0 }
 local SUPPORTED_REQUIRES = {
   ["src.mods.Semver"] = true,
   ["src.audio.ChipAsm"] = true,
+  ["src.pokemon.Stats"] = true, -- Stats.isShiny / calc for indicator mods
 }
 
 local function scanRequire(name)

src/mods/ManagerState.lua

@@ -10,6 +10,7 @@ local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
 local Theme = require("src.ui.Theme")
 local OptionRows = require("src.ui.OptionRows")
+local Strings = require("src.core.Strings")
 
 local ManagerState = {}
 ManagerState.__index = ManagerState
@@ -269,7 +270,7 @@ function ManagerState:modRows()
     end
   end
   if #rows == 0 then
-    rows[1] = { header = true, label = "NO MODS INSTALLED" }
+    rows[1] = { header = true, label = Strings("NO MODS INSTALLED") }
   end
   return rows
 end
@@ -281,7 +282,7 @@ function ManagerState:profileRows()
     rows[#rows + 1] = { profile = p, label = p.name,
       glyph = opts.activeProfile == p.name and GLYPH.errored or " " }
   end
-  rows[#rows + 1] = { saveAs = true, label = "SAVE CURRENT AS.." }
+  rows[#rows + 1] = { saveAs = true, label = Strings("SAVE CURRENT AS..") }
   rows[#rows + 1] = { adhoc = true,
     label = opts.activeProfile and "[AD-HOC]" or "[AD-HOC] (LIVE)" }
   return rows
@@ -316,30 +317,30 @@ function ManagerState:detailRows(m)
   rows[#rows + 1] = { label = m.enabled and "DISABLE" or "ENABLE",
     action = function() self:beginToggle(m) end }
   if self:schemaFor(m) then
-    rows[#rows + 1] = { label = "OPTIONS..",
+    rows[#rows + 1] = { label = Strings("OPTIONS.."),
       action = function() self:openOptions(m) end }
   end
   if m.permissions and #m.permissions > 0 then
-    rows[#rows + 1] = { label = "PERMISSIONS..",
+    rows[#rows + 1] = { label = Strings("PERMISSIONS.."),
       action = function() self:goTo("permissions") end }
   end
   if m.error then
-    rows[#rows + 1] = { label = "VIEW ERROR..",
+    rows[#rows + 1] = { label = Strings("VIEW ERROR.."),
       action = function() self:goTo("errors") end }
   end
-  rows[#rows + 1] = { label = "BACK", action = function() self:goBack() end }
+  rows[#rows + 1] = { label = Strings("BACK"), action = function() self:goBack() end }
   return rows
 end
 
 function ManagerState:applyRows()
   local rows = {}
-  rows[#rows + 1] = { label = "APPLY & RESTART", action = function()
+  rows[#rows + 1] = { label = Strings("APPLY & RESTART"), action = function()
     self:openConfirm({ "RESTART NOW?" }, function() self:restartGame() end)
   end }
-  rows[#rows + 1] = { label = "DISCARD CHANGES", action = function()
+  rows[#rows + 1] = { label = Strings("DISCARD CHANGES"), action = function()
     self:discardChanges()
   end }
-  rows[#rows + 1] = { label = "BACK", action = function() self:goBack() end }
+  rows[#rows + 1] = { label = Strings("BACK"), action = function() self:goBack() end }
   return rows
 end
 
@@ -352,7 +353,7 @@ function ManagerState:permissionRows(m)
       label = info and info.text or name }
   end
   if #rows == 0 then
-    rows[1] = { inert = true, label = "DATA & API ONLY" }
+    rows[1] = { inert = true, label = Strings("DATA & API ONLY") }
   end
   return rows
 end
@@ -564,7 +565,7 @@ function ManagerState:openCascade(r, m, want)
   else
     local dep = self.byId[r.alsoDisable[1]]
     lines[#lines + 1] = (dep and dep.name or r.alsoDisable[1]) .. " NEEDS THIS."
-    lines[#lines + 1] = #r.alsoDisable > 1 and "DISABLE ALL?" or "DISABLE BOTH?"
+    lines[#lines + 1] = #r.alsoDisable > 1 and "DISABLE ALL?" or Strings("DISABLE BOTH?")
   end
   self.overlay = { kind = "confirm", lines = lines, index = 1,
     onYes = function() self:commitToggle(r.apply) end }
@@ -700,7 +701,7 @@ end
 function ManagerState:saveCurrentAs()
   local NamingScreen = require("src.ui.NamingScreen")
   self.game.stack:push(NamingScreen.new(self.game, {
-    title = "PROFILE NAME?",
+    title = Strings("PROFILE NAME?"),
     maxLen = 10,
     onDone = function(name)
       local opts = self:optionsTable()
@@ -726,7 +727,7 @@ end
 function ManagerState:renameProfile(p)
   local NamingScreen = require("src.ui.NamingScreen")
   self.game.stack:push(NamingScreen.new(self.game, {
-    title = "RENAME?",
+    title = Strings("RENAME?"),
     maxLen = 10,
     default = p.name,
     onDone = function(name)
@@ -886,7 +887,7 @@ function ManagerState:buildOptionRows(m, schema)
         end }
     end
   end
-  rows[#rows + 1] = { id = "__reset", label = "RESET DEFAULTS",
+  rows[#rows + 1] = { id = "__reset", label = Strings("RESET DEFAULTS"),
     value = function() return "" end,
     activate = function()
       for _, row in ipairs(schema) do
@@ -1047,7 +1048,7 @@ function ManagerState:drawApply()
     y = y + 1
   end
   if #staged == 0 then
-    Font.draw(Runtime.safeMode and "SAFE MODE" or "NO CHANGES", 16, y * 8)
+    Font.draw(Runtime.safeMode and "SAFE MODE" or Strings("NO CHANGES"), 16, y * 8)
     y = y + 1
   end
   local rows = self:rowsForScreen()
@@ -1076,12 +1077,12 @@ function ManagerState:drawOverlay()
   end
   if overlay.kind == "confirm" then
     local yesY = ty + #lines + 1
-    Font.draw("YES", 5 * 8, yesY * 8)
-    Font.draw("NO", 5 * 8, (yesY + 1) * 8)
+    Font.draw(Strings("YES"), 5 * 8, yesY * 8)
+    Font.draw(Strings("NO"), 5 * 8, (yesY + 1) * 8)
     Font.drawCode(Theme.cursor, 4 * 8,
                   (overlay.index == 1 and yesY or yesY + 1) * 8)
   else
-    Font.draw("A:OK", 5 * 8, (ty + #lines + 1) * 8)
+    Font.draw(Strings("A:OK"), 5 * 8, (ty + #lines + 1) * 8)
   end
 end
 
@@ -1090,7 +1091,7 @@ function ManagerState:draw()
     OptionRows.draw(self.game, self.optionRows or {}, self.cursor,
                     self.scroll or 0)
     love.graphics.setColor(0, 0, 0, 1)
-    Font.draw(self.notice or "B:DONE (NO RESTART)", 8, 136)
+    Font.draw(self.notice or Strings("B:DONE (NO RESTART)"), 8, 136)
     love.graphics.setColor(1, 1, 1, 1)
     if self.overlay then self:drawOverlay() end
     return
@@ -1099,7 +1100,7 @@ function ManagerState:draw()
   love.graphics.rectangle("fill", 0, 0, 160, 144)
   love.graphics.setColor(1, 1, 1, 1)
   Font.drawBox(0, 0, 20, 18)
-  Font.draw(self.banner or "MOD MANAGER", 16, 8)
+  Font.draw(self.banner or Strings("MOD MANAGER"), 16, 8)
   if self.screen == "list" then
     self:drawList()
   elseif self.screen == "detail" then

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 } })',
 }
@@ -565,6 +584,17 @@ R.text = {
   example = 'mod.content.text:override("_PalletTownText1", "HELLO!")',
 }
 
+-- The engine's own authored text, the half of the game `text` does not
+-- cover (src/core/Strings.lua).  The id is the English source string, so a
+-- translation supplies one entry per literal the engine draws and anything
+-- it has not reached yet keeps rendering in English.  Ids that collide in
+-- English but not elsewhere carry a "context|source" prefix.
+R.strings = {
+  semantics = "record", target = "strings",
+  value = f.str,
+  example = 'mod.content.strings:override("But, it failed!", "Echec !")',
+}
+
 -- the self-contained bytecode blob ChipAsm.song/sfx emit (13.1 shape 2);
 -- shared by every namespace that plays a chip program
 local chipProgram = f.rec{
@@ -791,6 +821,130 @@ 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,
+})]],
+  notes = [[
+Scales one battle pic by its asset path, overriding the species-level
+`battleScaleFront`/`battleScaleBack` (see [pokemon](#pokemon)) for that
+image. The only way to scale a pic that is not species-keyed, like the
+player's trainer back sprite. Resolution order at draw time:
+image-level, then species-level, then the defaults (1x front, 2x back).
+The pic stays grounded at any scale: player feet stay flush on the
+text-box top, the enemy pic stays bottom-pinned in its slot, and the
+scale composes with the send-out grow animation.]],
+}
+
 -- ------- progression
 
 R.evolution_methods = {
@@ -1015,6 +1169,12 @@ R.field = {
                                             name = f.opt(f.str) })),
       nest = f.opt(f.any) },
     flyOrder = f.list(f.str),
+    -- the player's own trainer art (FieldDefaults.PLAYER_PICS): the battle
+    -- back pic, the catch tutorial's old man, and the front pic the intro,
+    -- trainer card and Hall of Fame share.  Every key is optional so a
+    -- conversion can replace one pic and inherit the rest.
+    playerPics = f.rec{
+      back = f.opt(f.str), demoBack = f.opt(f.str), front = f.opt(f.str) },
     -- the new-game and boot config a total conversion replaces
     boot = f.rec{
       startMap = f.opt(f.str), startX = f.opt(f.int(0)), startY = f.opt(f.int(0)),

src/pokemon/Evolution.lua

@@ -14,6 +14,7 @@ local Runtime = require("src.mods.Runtime")
 local Screens = require("src.ui.Screens")
 local Stats = require("src.pokemon.Stats")
 local TextBox = require("src.render.TextBox")
+local Strings = require("src.core.Strings")
 
 local Evolution = {}
 
@@ -23,7 +24,7 @@ Evolution.METHODS = {
       return trigger.kind == "levelup" and mon.level >= (evo.level or 0)
     end,
     describe = function(evo)
-      return ("Level %d"):format(evo.level or 0)
+      return Strings("Level %d", evo.level or 0)
     end,
   },
   ITEM = {
@@ -106,21 +107,67 @@ 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,
+        Strings("%s learned\n%s!", 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"))
   local oldName = mon.nickname or game.data.pokemon[mon.species].name
   Evolution.apply(game, mon, newSpecies, via)
-  local msg = ("What?\n%s is\nevolving!\fCongratulations!\nYour %s\nevolved into\n%s!")
-              :format(oldName, oldName, game.data.pokemon[newSpecies].name)
+  local msg = Strings("What?\n%s is\nevolving!\fCongratulations!\nYour %s\nevolved into\n%s!",
+                      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 +185,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/pokemon/Sprites.lua

@@ -0,0 +1,97 @@
+-- Runtime Pokémon art resolution.  Content registries freeze after load,
+-- so a mod that lets the player pick an alternate skin mid-session cannot
+-- patch pokemon.spriteFront / icons.bySpecies.  These helpers are the
+-- sanctioned seam: every battle pic and party icon load goes through
+-- pokemon.sprite / pokemon.icon, which stay live for the whole process.
+--
+-- playerPath is the same seam for the player's own trainer art, whose
+-- vanilla paths are data (field.playerPics) rather than a species record.
+
+local Runtime = require("src.mods.Runtime")
+local FieldDefaults = require("src.world.FieldDefaults")
+
+local Sprites = {}
+
+local function samePath(path) return path end
+
+-- Resolve a battle / menu front or back pic path for `species`.
+-- side: "front" | "back"
+-- opts.mon: the live mon when available (per-instance skins)
+-- opts.kind: "battle" | "summary" | "dex" | "evolution" | "hof" | "trade"
+--            | "title" | "oak" | "credits" (informational for wrappers)
+-- Returns path, trueColor.
+function Sprites.path(data, species, side, opts)
+  opts = opts or {}
+  local def = data and data.pokemon and data.pokemon[species]
+  if not def then return nil, false end
+  local path = side == "back" and def.spriteBack or def.spriteFront
+  local ctx = {
+    species = species,
+    side = side == "back" and "back" or "front",
+    kind = opts.kind or "battle",
+    mon = opts.mon,
+    trueColor = def.trueColor and true or false,
+    data = data,
+  }
+  if path and Runtime.wantsHook("pokemon.sprite") then
+    local hooked = Runtime.call("pokemon.sprite", samePath, path, ctx)
+    if type(hooked) == "string" and hooked ~= "" then path = hooked end
+  end
+  return path, ctx.trueColor and true or false
+end
+
+-- Resolve the player's own trainer pic path.
+-- side: "back" (the battle intro pic) | "front" (intro / card / Hall of Fame)
+-- opts.kind: "battle" | "intro" | "trainer_card" | "hof"
+-- opts.demo: the catch tutorial, where the old man fights in the player's
+--            place and stands in for the back pic
+-- opts.battle: the live battle, for kind == "battle"
+-- Returns path, trueColor.
+function Sprites.playerPath(data, side, opts)
+  opts = opts or {}
+  side = side == "back" and "back" or "front"
+  -- one key per pic, so a conversion can replace the back and inherit the
+  -- rest; fieldValue folds data.field over FieldDefaults per key
+  local key = side == "front" and "front"
+              or (opts.demo and "demoBack" or "back")
+  local path = FieldDefaults.fieldValue(data, "playerPics", key)
+  local ctx = {
+    side = side,
+    kind = opts.kind or "battle",
+    demo = opts.demo and true or false,
+    battle = opts.battle,
+    trueColor = false,
+    data = data,
+  }
+  if path and Runtime.wantsHook("player.sprite") then
+    local hooked = Runtime.call("player.sprite", samePath, path, ctx)
+    if type(hooked) == "string" and hooked ~= "" then path = hooked end
+  end
+  return path, ctx.trueColor and true or false
+end
+
+-- Resolve a party-menu icon image path for `mon`.
+-- vanillaPath is the path PartyMenu already picked from icons.bySpecies /
+-- def.icon / icons.byDex; the hook may replace it.
+-- Returns path (possibly nil).
+function Sprites.iconPath(data, mon, vanillaPath, opts)
+  opts = opts or {}
+  if not vanillaPath and not Runtime.wantsHook("pokemon.icon") then
+    return vanillaPath
+  end
+  local species = mon and mon.species
+  local ctx = {
+    species = species,
+    mon = mon,
+    name = opts.name,
+    data = data,
+    kind = "icon",
+  }
+  if not Runtime.wantsHook("pokemon.icon") then return vanillaPath end
+  local hooked = Runtime.call("pokemon.icon", samePath, vanillaPath, ctx)
+  if type(hooked) == "string" and hooked ~= "" then return hooked end
+  if hooked == nil or hooked == false then return nil end
+  return vanillaPath
+end
+
+return Sprites

src/pokemon/Stats.lua

@@ -57,4 +57,20 @@ function Stats.applyStage(value, stage)
   return math.max(1, math.min(999, v))
 end
 
+-- Gen 2 shiny formula applied to Gen 1 DVs (the RBY "virtual shiny"):
+-- Defense/Speed/Special DV == 10 and Attack DV is even-high
+-- (2, 3, 6, 7, 10, 11, 14, or 15).  Used by shiny-indicator mods.
+local SHINY_ATK = {
+  [2] = true, [3] = true, [6] = true, [7] = true,
+  [10] = true, [11] = true, [14] = true, [15] = true,
+}
+
+function Stats.isShiny(dvs)
+  if type(dvs) ~= "table" then return false end
+  return (dvs.defense or 0) == 10
+     and (dvs.speed or 0) == 10
+     and (dvs.special or 0) == 10
+     and SHINY_ATK[dvs.attack or 0] == true
+end
+
 return Stats

src/render/Font.lua

@@ -102,35 +102,84 @@ local function pageFor(code)
   return nil
 end
 
+local SPACE = 0x7F
+
+-- Segment text into glyph spans: `{ from, to, code }` byte ranges, one per
+-- drawn glyph, code nil when the charmap has nothing.  A span is a whole
+-- charmap sequence, so a multi-byte char ("é", "♂") and an ASCII ligature
+-- ("<PK>", "'d") are each one glyph.
+--
+-- Every caller that *measures* or *cuts* text walks these instead of bytes.
+-- "POKéMON" is 8 bytes and 7 glyphs: measuring it as 8 wraps lines that fit
+-- (25 vanilla lines did), and cutting at byte 8 splits the é into two
+-- invalid bytes that both draw as spaces.  That distinction is the whole
+-- reason a non-English font can be shipped as a mod (#186, #245).
+--
+-- Safe before Font.load: with no charmap it falls back to UTF-8 lead-byte
+-- boundaries, which is all a headless paginate needs.
+function Font.split(text)
+  local spans = {}
+  local i, n = 1, #text
+  while i <= n do
+    local span
+    local candidates = state and state.byFirstByte[text:byte(i)]
+    if candidates then
+      for _, entry in ipairs(candidates) do
+        local len = #entry.seq
+        if text:sub(i, i + len - 1) == entry.seq then
+          span = { from = i, to = i + len - 1, code = entry.code }
+          break
+        end
+      end
+    end
+    if not span then
+      -- Nothing matched.  Still keep a UTF-8 sequence whole, so a cut never
+      -- lands mid-character even for a glyph we cannot draw.
+      local last = i
+      if text:byte(i) >= 0xC0 then
+        local k = i + 1
+        while k <= n do
+          local b = text:byte(k)
+          if b < 0x80 or b > 0xBF then break end
+          last, k = k, k + 1
+        end
+      end
+      span = { from = i, to = last }
+    end
+    spans[#spans + 1] = span
+    i = span.to + 1
+  end
+  return spans
+end
+
+-- How many leading spans fit in `budget` pixels.  Advances come from each
+-- glyph's own page, so a variable-width page measures correctly.
+function Font.spansFitting(spans, budget)
+  local used, fit = 0, 0
+  for _, span in ipairs(spans) do
+    used = used + Font.advanceOf(span.code or SPACE)
+    if used > budget then break end
+    fit = fit + 1
+  end
+  return fit
+end
+
 -- Convert a text string into a list of glyph codes.  Unknown characters
 -- render as space (and are reported once).
 local reported = {}
 function Font.encode(text)
   local codes = {}
-  local i = 1
-  while i <= #text do
-    local candidates = state.byFirstByte[text:byte(i)]
-    local matched = false
-    if candidates then
-      for _, entry in ipairs(candidates) do
-        local n = #entry.seq
-        if text:sub(i, i + n - 1) == entry.seq then
-          codes[#codes + 1] = entry.code
-          i = i + n
-          matched = true
-          break
-        end
-      end
-    end
-    if not matched then
-      local ch = text:sub(i, i)
-      if not reported[ch] and ch:byte() >= 32 then
+  for _, span in ipairs(Font.split(text)) do
+    local code = span.code
+    if not code then
+      local ch = text:sub(span.from, span.to)
+      if not reported[ch] and text:byte(span.from) >= 32 then
         reported[ch] = true
         require("src.core.Logger").warn("font: no glyph for %q", ch)
       end
-      codes[#codes + 1] = 0x7F -- space
-      i = i + 1
+      code = SPACE
     end
+    codes[#codes + 1] = code
   end
   return codes
 end

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

@@ -0,0 +1,45 @@
+-- Render targets measured in real framebuffer pixels.
+--
+-- love.graphics.newCanvas defaults its `dpiscale` to
+-- love.graphics.getDPIScale(), so on a highdpi surface the canvas texture is
+-- NOT the size it was asked for: newCanvas(160, 144) on a device reporting a
+-- DPI scale of 2.755 allocates a 441x397 texture, and the 160x144 GB scene
+-- then renders into it at 2.755 texels per GB pixel.  conf.lua sets
+-- t.window.highdpi on Android/iOS (required for Retina), and Android's
+-- DisplayMetrics.density is routinely non-integer (1.5, 2.75, ...), so this
+-- is the normal mobile case, not an edge case.
+--
+-- That fractional render breaks the whole premise of Renderer's integer
+-- scale pipeline.  Renderer:fitScale() picks a whole number of physical
+-- pixels per GB pixel (7 on 1080p) and the composite blit lands on it
+-- exactly -- but if the *source* already holds 2.755 texels per GB pixel,
+-- some GB pixels are 2 texels wide and some are 3, and the nearest-neighbour
+-- upscale turns them into 5 / 7 / 8 physical pixels instead of a uniform 7.
+-- Measured on a 1080p density-2.755 fixture, only 43 of 160 columns came out
+-- the right width.  Fonts show it worst: their strokes are single pixels.
+-- That is issue #208 ("some are noticeably stretched, especially fonts").
+--
+-- Forcing dpiscale = 1 makes canvas texels the pixels the renderer already
+-- believes it is drawing.  getWidth()/getHeight() are unaffected (they always
+-- reported the requested size), so no geometry anywhere changes -- only the
+-- resolution of the target.  Desktop is unchanged; dpiscale is already 1
+-- there because conf.lua sets highdpi on mobile only.
+--
+-- Exception: a canvas that is deliberately sized in LOVE *units* and blitted
+-- back at unit scale 1 (Renderer's presentCanvas) must keep the screen's DPI
+-- scale so its texture still covers the framebuffer; it is not built with
+-- this helper.
+
+local PixelCanvas = {}
+
+-- One framebuffer pixel per w/h unit, always.  `filter` is applied only when
+-- given, so callers that relied on LOVE's default ("linear") keep it.
+function PixelCanvas.new(w, h, filter)
+  local canvas = love.graphics.newCanvas(w, h, { dpiscale = 1 })
+  if filter and canvas and canvas.setFilter then
+    canvas:setFilter(filter, filter)
+  end
+  return canvas
+end
+
+return PixelCanvas

src/render/Renderer.lua

@@ -9,12 +9,30 @@
 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 PixelCanvas = require("src.render.PixelCanvas")
+local Runtime = require("src.mods.Runtime")
 
 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,32 +41,49 @@ 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()
-  self.canvas = love.graphics.newCanvas(self.WIDTH, self.HEIGHT)
-  self.canvas:setFilter("nearest", "nearest")
+  -- 160x144 real pixels, never DPI-scaled: see src/render/PixelCanvas.lua
+  -- (#208).  Every canvas below is sized in framebuffer pixels for the same
+  -- reason -- worldViewSize() already works in drawable pixels.
+  self.canvas = PixelCanvas.new(self.WIDTH, self.HEIGHT, "nearest")
   self.worldCanvas = nil
   self.worldActive = false
   -- tilt mode only: a transparent overlay canvas the size of the world
@@ -57,25 +92,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 +164,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 +186,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 +220,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)
@@ -157,8 +234,7 @@ function Renderer:beginWorldPass()
     -- the view size every frame, so without this the superseded canvases
     -- pile up in VRAM until a GC finalizer happens to run
     if self.worldCanvas and self.worldCanvas.release then self.worldCanvas:release() end
-    self.worldCanvas = love.graphics.newCanvas(vw, vh)
-    self.worldCanvas:setFilter("nearest", "nearest")
+    self.worldCanvas = PixelCanvas.new(vw, vh, "nearest")
   end
   self.worldActive = true
   PaletteFX.setPass("world")
@@ -186,8 +262,7 @@ function Renderer:beginUprightPass()
   if not self.uprightCanvas or self.uprightCanvas:getWidth() ~= cw
      or self.uprightCanvas:getHeight() ~= ch then
     if self.uprightCanvas and self.uprightCanvas.release then self.uprightCanvas:release() end
-    self.uprightCanvas = love.graphics.newCanvas(cw, ch)
-    self.uprightCanvas:setFilter("nearest", "nearest")
+    self.uprightCanvas = PixelCanvas.new(cw, ch, "nearest")
   end
   self.uprightActive = true
   PaletteFX.setPass(nil)
@@ -266,10 +341,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()
 
@@ -280,8 +356,7 @@ function Renderer:drawTiltedWorld(zoneList, s, wox, woy, target)
   if not self.tiltCanvas or self.tiltCanvas:getWidth() ~= wvw
      or self.tiltCanvas:getHeight() ~= wvh then
     if self.tiltCanvas and self.tiltCanvas.release then self.tiltCanvas:release() end
-    self.tiltCanvas = love.graphics.newCanvas(wvw, wvh)
-    self.tiltCanvas:setFilter("linear", "linear")
+    self.tiltCanvas = PixelCanvas.new(wvw, wvh, "linear")
   end
 
   love.graphics.setCanvas(self.tiltCanvas)
@@ -318,7 +393,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 +435,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,11 +456,23 @@ 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
        or self.presentCanvas:getHeight() ~= wh then
+      -- The one canvas NOT built through PixelCanvas: it is sized in LOVE
+      -- units and blitted back at unit scale 1 (and handed to mod present
+      -- passes as ww x wh), so it has to keep the screen's DPI scale for its
+      -- texture to cover the framebuffer.  Everything composited into it is
+      -- already native-resolution now, so #208's fractional source is gone;
+      -- what remains here is the dpiX vs dpiY truncation gap (well under 1%,
+      -- one seam across the window) that a single scalar dpiscale cannot
+      -- express.
       self.presentCanvas = love.graphics.newCanvas(ww, wh)
       self.presentCanvas:setFilter("linear", "linear")
     end
@@ -407,15 +495,27 @@ function Renderer:endFrame(zones, worldZones)
   love.graphics.setColor(clearR, clearG, clearB, 1)
   love.graphics.rectangle("fill", 0, 0, ww, wh)
   love.graphics.setColor(1, 1, 1, 1)
+  -- render.letterbox: SGB borders / custom void art in the bars around the
+  -- 160x144 (or world) blit.  Drawn after the clear and before the game
+  -- canvas so the playfield sits on top of the border.
+  if Runtime.wantsHook("render.letterbox") then
+    Runtime.call("render.letterbox", function() end, {
+      ww = ww, wh = wh, pw = pw, ph = ph,
+      ox = ox, oy = oy, vpw = vpw, vph = vph,
+      scale = Sp, dpiX = dpiX, dpiY = dpiY,
+      worldActive = self.worldActive and true or false,
+    })
+  end
 
-  -- 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 +531,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 +575,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 +601,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 +622,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 +638,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,70 @@ 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
+  -- maxCols is a column count, so the budget is that many vanilla 8px
+  -- cells.  Measuring in pixels rather than columns is what lets a mod's
+  -- variable-advance page wrap correctly (#186).
+  local budget = maxCols * 8
   local pages = {}
+  local contBefore = {}
+  -- Soft-wrap on glyph boundaries, never byte boundaries: a line is over
+  -- budget by what it *draws*, and the cut falls between glyphs so a
+  -- multi-byte char is never torn in half.
+  local function pushLine(lines, conts, line, wait)
+    while true do
+      local spans = Font.split(line)
+      local fit = Font.spansFitting(spans, budget)
+      if fit >= #spans then break end
+      -- a glyph wider than the whole box still has to advance by one
+      fit = math.max(fit, 1)
+      local cut = spans[fit].to
+      for i = fit, 1, -1 do
+        if line:sub(spans[i].from, spans[i].to) == " " then
+          cut = spans[i].to
+          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
 
@@ -138,6 +182,18 @@ function TextBox:update(dt)
       if self.autoSrc and self.autoSrc.isPlaying and self.autoSrc:isPlaying() then
         return -- the cry is still sounding (WaitForSoundToFinish)
       end
+      -- auto.wait: the pet-NPC cries (PewterNidoranHouseNidoranText,
+      -- ViridianNicknameHouseSpearowText) have nothing queued behind the
+      -- cry, so DisplayTextID's trailing WaitForTextScrollButtonPress still
+      -- runs once it is over -- their maps enable auto text box drawing,
+      -- which zeroes wDoNotWaitForButtonPressAfterDisplayingText
+      -- (home/window.asm AutoTextBoxDrawingCommon).  Drop the auto gate and
+      -- hand the box to the plain A/B path, which also starts the blinking
+      -- arrow, instead of popping it (#247, #251).
+      if self.auto.wait then
+        self.auto = nil
+        return
+      end
       self.autoTimer = self.autoTimer + 1
       local delay = self.auto.delay or 3
       -- auto.onOverlap: fired once when the delay elapses but before the
@@ -179,10 +235,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 +266,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