new options, and hot keys and readme clean up (#148)

* main menu scrollable when over 8 items

* buggies

* more buggies

* Lorelei, Bruno, and Agatha now push their AfterBattle text right after a win

* more and more bugs

README.md

@@ -33,8 +33,32 @@ audio channel programs copied out of the verified ROM.
 
 ## Controls
 
-arrow keys or WASD move; Z, Enter, or Space is A; X or Backspace is
-B; Escape opens START. F1 saves and F2 loads. Controllers are supported.
+| Action | Keyboard | Controller |
+|--------|----------|------------|
+| Move | Arrow keys / WASD | D-pad / left stick |
+| A | Z / Enter / Space | A |
+| B | X / Backspace | B |
+| Start | Escape | Start |
+| Select | Tab / Shift | Back / Select |
+
+Rebind any of these in-game under **OPTIONS → CONTROLS**. Controllers are
+supported out of the box.
+
+### Hotkeys
+
+| Key | What it does |
+|-----|----------------|
+| `-` / `=` | Zoom out / in (overworld; also mouse wheel) |
+| `2` | Cycle COLORS |
+| `3` | Cycle TILT (free-roam overworld) |
+| `4` | Cycle ZOOM through every level (free-roam overworld) |
+| `5` | Cycle GBC FX |
+| `F1` | Save |
+| `F2` | Load |
+| `F10` | Open / close the mod manager |
+
+COLORS, TILT, ZOOM, GBC FX, and VOID FILL are also in the Options menu
+and persist in `options.lua`.
 
 ## Running From Source
 

data/scripts/story3.lua

@@ -61,6 +61,50 @@ M.ROUTE_12_SUPER_ROD_HOUSE = {
 M.ROUTE_12_SUPER_ROD_HOUSE.talk.TEXT_ROUTE12SUPERRODHOUSE_FISHING_GURU[9] =
   { "show_text", "_Route12SuperRodHouseFishingGuruTryFishingText" }
 
+-- -------------------------------------------------------------------
+-- Pokemon Tower 5F purified zone (scripts/PokemonTower5F.asm
+-- PokemonTower5FDefaultScript): the 2x2 center pad heals the party once
+-- per visit.  EVENT_IN_PURIFIED_ZONE latches until the player steps off;
+-- while on the pad the map script also sets BIT_NO_BATTLES (we return
+-- true from onStep so wild encounters are skipped the same way).
+-- -------------------------------------------------------------------
+
+local TOWER_5F_PURIFIED = {
+  [10 * 256 + 8] = true, [11 * 256 + 8] = true,
+  [10 * 256 + 9] = true, [11 * 256 + 9] = true,
+}
+
+-- HealParty -> GBFadeOutToWhite -> Delay3 -> Delay3 -> GBFadeInFromWhite
+-- -> TEXT_POKEMONTOWER5F_PURIFIEDZONE (no Music_PkmnHealed).
+local TOWER_5F_HEAL = {
+  { "heal_party" },
+  { "fade", "out", "white" },
+  { "wait", 3 },
+  { "wait", 3 },
+  { "fade", "in", "white" },
+  { "show_text", "_PokemonTower5FPurifiedZoneText" },
+}
+
+M.POKEMON_TOWER_5F = {
+  onStep = function(game, ow, x, y)
+    if not TOWER_5F_PURIFIED[x * 256 + y] then
+      game.save.flags.EVENT_IN_PURIFIED_ZONE = nil
+      return false
+    end
+    if game.save.flags.EVENT_IN_PURIFIED_ZONE then
+      return true
+    end
+    if ow.runner and ow.runner:isRunning() then return false end
+    game.save.flags.EVENT_IN_PURIFIED_ZONE = true
+    if ow.runner then
+      ow.runner:run(TOWER_5F_HEAL)
+    elseif ow.queueScript then
+      ow:queueScript(TOWER_5F_HEAL)
+    end
+    return true
+  end,
+}
+
 -- -------------------------------------------------------------------
 -- The ghost Marowak (scripts/PokemonTower6F.asm): blocks the stairs at
 -- (10,16) until defeated.

docs/new-features.md

@@ -8,27 +8,42 @@ behavior is in docs/behavior-porting-notes.md.
 
 ## Survey zoom
 
-The mouse wheel (or `-`/`=`) zooms the overworld between 1 pixel per world
-pixel (full survey) and 2× the window fit scale (close-up), in crisp
-integer steps. This has no Game Boy equivalent:
+The mouse wheel (or `-`/`=`), the Options **ZOOM** row, or hotkey `4`
+zooms the overworld between 1 pixel per world pixel (full survey) and 2×
+the window fit scale (close-up), in crisp integer steps. This has no Game
+Boy equivalent:
 
 - Connected maps render their full bodies, and their NPCs appear as
   visual-only "ghosts",  they wander but have no sight lines, triggers,
   dialogue, or collision until the map is actually entered.
 - Menus, text boxes, and battles draw at normal scale on top of the
   zoomed world. Zoom input is ignored while a script, menu, or battle is
-  active; the zoom level persists across warps and is never saved.
-- Beyond the border ring the border block repeats indefinitely (interiors
-  stay black, seaside towns stay water,  except OVERWORLD-tileset maps,
-  whose beyond-edge space fills with the solid tree wall instead of the
-  per-map border block), and each visible map area is colorized with its
-  own SGB palette (the original recolored the whole screen per map).
+  active; the zoom offset is persisted as `save.options.zoom` (default
+  `0` = FIT) and survives New Game via `options.lua`.
+- Hotkey `4` ticks through every integer zoom level (survey → FIT →
+  close-up → wrap). The Options row shows `FIT` / `OUTn` / `INn`.
+- Beyond the border ring the void fill repeats indefinitely (see VOID
+  FILL below); interiors keep their own border block. Each visible map
+  area is colorized with its own SGB palette (the original recolored the
+  whole screen per map).
 - Neighbor maps load two connection hops out so corner-adjacent maps
   don't pop in and out, and ghost NPCs share instances with the real ones
   so their wander positions persist across seamless connection crossings
   (a warp or fresh map entry still respawns everything at its script
   position, like the original's per-entry sprite init).
 
+## VOID FILL
+
+The Options **VOID FILL** row picks what paints the infinite beyond-edge
+space on OVERWORLD-tileset maps during survey zoom:
+
+- **TREES** (default): solid tree wall block `$0F`.
+- **WATER**: animated water tile `$14` (same hshift cycle as on-map water).
+- **BLACK**: solid black.
+
+Other tilesets are unchanged (house/cave borders stay as authored).
+Persisted as `save.options.voidFill`.
+
 ## Tilt mode
 
 The `3` key (and the Options menu TILT row) cycles a visual-only perspective
@@ -139,7 +154,7 @@ Nidorino-vs-Gengar attract scene) mirror the original.
 Options persist in a standalone `options.lua` (separate from the game
 progress `save.lua`), so audio/display/battle preferences survive New Game
 and aren't wiped when a save slot is cleared. Changing a row in the Options
-menu or cycling hotkeys `2`/`3`/`5` writes immediately; an in-game save also
+menu or cycling hotkeys `2`/`3`/`4`/`5` writes immediately; an in-game save also
 flushes the live options. Old saves that still embed an `options` table are
 migrated once into `options.lua` on load.
 
@@ -150,6 +165,18 @@ migrated once into `options.lua` on load.
   hotkey `2` (OG RED = GBC boot-ROM look; RED++ uses pokered-gbc
   SuperPalettes + per-species mon colors)
 - TILT (OFF / 15 / 35 / 50),  also hotkey `3` while free-roaming
+- ZOOM (FIT / OUTn / INn),  also hotkey `4` while free-roaming; wheel and
+  `-`/`=` step one level and save
+- VOID FILL (TREES / WATER / BLACK) for OVERWORLD beyond-edge space
 - GBC FX (OFF / 1 / 2 / 3 / 4),  also hotkey `5`
 - MAX FPS (30 / 40 / 50 / 60 / 75 / 90 / 100 / 120 / 144 / 160, default 60),
-  a hard render frame-rate cap (`save.options.fpsCap`).
+  a hard render frame-rate cap (`save.options.fpsCap`).
+
+## Battle transition cascade + white battle letterbox
+
+Into-battle wipes still run the original eight styles inside the classic
+160×144 letterbox. On wide/tall windows (survey zoom), matching black 8×8
+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.

src/battle/BattleState.lua

@@ -30,6 +30,9 @@ local TypeChart = require("src.battle.TypeChart")
 local BattleState = {}
 BattleState.__index = BattleState
 BattleState.isOpaque = true
+-- Letterbox voids around the 160x144 battle canvas fill white so the
+-- window reads as one continuous battle screen (no black bars).
+BattleState.letterboxWhite = true
 
 -- Battle colors itself per-pixel (species pics + HP bar tints), so the
 -- SGB whole-screen remap must not run over it.

src/battle/EffectRegistry.lua

@@ -176,25 +176,51 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   end
   battle.lastDamage = dmg -- wDamage (shared by both sides, read by Counter)
 
-  -- the hit blink + damage sound ride the queue behind the animation:
-  -- on the move's anim row when one was announced, else on a bare hit
-  -- row (thrash/rage continuations), placed BEFORE the drain rows the
-  -- hits loop inserts so the blink precedes the bar drain
-  local hitRow = battle.moveAnimRow
-  if not hitRow then
-    battle.nextInsert = (battle.nextInsert or 0) + 1
-    hitRow = { hitRow = true }
-    table.insert(battle.queue, battle.nextInsert, hitRow)
-  end
+  -- the hit blink + damage sound ride each animation row, placed BEFORE
+  -- that hit's drain so the blink precedes the bar.  Multi-hit moves
+  -- replay PlayMoveAnimation per strike (pokered: GetPlayerAnimationType
+  -- / GetEnemyAnimationType loop on wNumAttacksLeft); hit 1 reuses the
+  -- announcement-time moveAnimRow, later hits queue fresh anim rows.
+  -- Thrash/rage continuations have no announcement anim -- a bare
+  -- hitRow carries the blink instead.
+  local hitSfx = info.typeMult > 10 and "Super_Effective"
+                 or info.typeMult < 10 and "Not_Very_Effective" or "Damage"
+  local hitFx = { sfx = hitSfx,
+                  blink = battle:animationsOn() and target or nil }
 
   local totalDealt = 0
   local landed, brokeSub = 0, false
   for h = 1, hits do
     if target.mon.hp <= 0 then break end
+    local hitRow
+    if h == 1 then
+      hitRow = battle.moveAnimRow
+      if not hitRow then
+        battle.nextInsert = (battle.nextInsert or 0) + 1
+        hitRow = { hitRow = true }
+        table.insert(battle.queue, battle.nextInsert, hitRow)
+      end
+    else
+      battle.nextInsert = (battle.nextInsert or 0) + 1
+      hitRow = { anim = move.id, attackerIsPlayer = user.isPlayer }
+      table.insert(battle.queue, battle.nextInsert, hitRow)
+    end
     local hadSub = target.substituteHP ~= nil
     local dealt = battle:applyDamage(target, dmg)
     totalDealt = totalDealt + dealt
     landed = h
+    if dealt > 0 then hitRow.hit = hitFx end
+    -- PrintCriticalOHKOText + DisplayEffectiveness run inside the
+    -- 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.typeMult > 10 then
+      battle:sayNext("It's super\neffective!")
+    elseif info.typeMult < 10 then
+      battle:sayNext("It's not very\neffective...")
+    end
     if Runtime.wants("battle.damage_dealt") then
       Runtime.emit("battle.damage_dealt", {
         battle = battle, user = user, target = target, move = move,
@@ -208,23 +234,6 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     end
   end
   hits = landed > 0 and landed or hits
-  if totalDealt > 0 then
-    -- the original's per-hit sound: normal / super / not-very-effective
-    local hitSfx = info.typeMult > 10 and "Super_Effective"
-                   or info.typeMult < 10 and "Not_Very_Effective" or "Damage"
-    hitRow.hit = { sfx = hitSfx,
-                   blink = battle:animationsOn() and target or nil }
-  end
-  -- PrintCriticalOHKOText prints "Critical hit!"/"One-hit KO!" right
-  -- after the damage lands, BEFORE DisplayEffectiveness (core.asm
-  -- .moveDidNotMiss); the multi-hit count follows the last hit
-  if info.crit then battle:sayNext("Critical hit!") end
-  if info.ohko then battle:sayNext("One-hit KO!") end
-  if info.typeMult > 10 then
-    battle:sayNext("It's super\neffective!")
-  elseif info.typeMult < 10 then
-    battle:sayNext("It's not very\neffective...")
-  end
   if hits > 1 then
     -- player: _MultiHitText; enemy: _HitXTimesText (always plural)
     if user.isPlayer then

src/core/Game.lua

@@ -246,7 +246,11 @@ end
 function Game:zoomStep(delta)
   local Zoom = require("src.render.Zoom")
   if not Zoom.gateOK(self.stack:top(), self.overworld) then return end
-  Zoom.step(delta, Renderer:fitScale())
+  local offset = Zoom.step(delta, Renderer:fitScale())
+  if self.save and self.save.options then
+    self.save.options.zoom = offset
+    self:writeOptions()
+  end
 end
 
 function Game:wheelmoved(_, dy)
@@ -320,9 +324,19 @@ function Game:keypressed(key)
       self:writeOptions()
     end
     return
+  elseif key == "4" then
+    -- cycle ZOOM through every integer level (survey → FIT → close-up → wrap)
+    local Zoom = require("src.render.Zoom")
+    if Zoom.gateOK(self.stack:top(), self.overworld) then
+      self.save.options.zoom = Zoom.cycle(Renderer:fitScale())
+      self:writeOptions()
+    end
+    return
   elseif key == "5" then
     -- cycle GBC FX OFF → 1 → 2 → 3 → 4 (unlit-GBC ladder); always on
+    -- desktop.  Mobile refuses the present shader (issue #136).
     local GBCFX = require("src.render.GBCFX")
+    if not GBCFX.isSupported() then return end
     self.save.options.gbcfx = GBCFX.cycle()
     self:writeOptions()
     return
@@ -443,12 +457,17 @@ function Game:applyOptions(opts)
   if Sound.applyOptions then Sound.applyOptions(opts) end
   require("src.render.PaletteFX").applyOptions(opts)
   require("src.render.Tilt").applyOptions(opts)
-  require("src.render.GBCFX").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
+  local gbcCleared = require("src.render.GBCFX").applyOptions(opts)
   require("src.core.VideoMode").applyOptions(opts)
   -- normalizes a nil/garbage cap to the 60 default, so old saves with no
   -- fpsCap key pace at the standard rate (issue #88)
   require("src.core.FrameCap").applyOptions(opts)
   Input:applyBindings(opts.bindings)
+  -- heal soft-bricked APK installs that already saved gbcfx > 0 (#136)
+  if gbcCleared then self:writeOptions() end
 end
 
 function Game:restoreSave(loaded, recovered)

src/core/Input.lua

@@ -11,7 +11,12 @@ local DEFAULT_BINDINGS = {
   z = "a", ["return"] = "a", space = "a",
   x = "b", backspace = "b",
   ["kpenter"] = "start", escape = "start",
+  -- Select: fight-menu move reorder + bag item reorder. Tab is the
+  -- discoverable default (shown in CONTROLS); both shifts stay as
+  -- aliases so Right-Shift muscle memory from older builds still works.
+  tab = "select",
   rshift = "select",
+  lshift = "select",
 }
 
 -- keys that map to "start" but also to "a" would conflict; keep Enter = a,

src/core/SaveData.lua

@@ -186,10 +186,14 @@ function SaveData.defaultOptions()
     musicFilter = 0,
     -- logic fast-forward multiplier; audio is unaffected (GameSpeed.lua)
     speed = 1,
-    -- port display options (OptionsMenu / hotkeys 2/3/5)
+    -- port display options (OptionsMenu / hotkeys 2/3/4/5)
     colors = "gbc",
     tilt = 0,
     gbcfx = 0,
+    -- survey zoom offset from window fit scale (0 = FIT); see Zoom.lua
+    zoom = 0,
+    -- OVERWORLD beyond-edge fill: trees | water | black
+    voidFill = "trees",
     -- windowed | borderless (desktop fullscreen); ignored on mobile
     videoMode = "windowed",
     -- hard render frame-rate cap; render-only pacing (issue #88, FrameCap.lua)

src/core/TouchInput.lua

@@ -48,7 +48,7 @@ local KEY = {
   a = "z",
   b = "x",
   start = "escape",
-  select = "rshift",
+  select = "tab",
 }
 
 local function nowMs()

src/render/BattleTransition.lua

@@ -230,6 +230,11 @@ function BattleTransition:draw()
 
   love.graphics.setColor(0, 0, 0, 1)
   local prog = math.min(1, self.t / self.wipeLen)
+  -- Cascade black 8x8 blocks across the window area *outside* the classic
+  -- 160x144 wipe square, in lockstep with the OG wipe progress.  Renderer
+  -- paints them in screen space after the world blit (see endFrame).
+  local renderer = self.game and self.game.renderer
+  if renderer then renderer.battleCascadeProg = prog end
   local style = self.style
 
   -- a registered style may draw itself; the eight built-ins do not

src/render/GBCFX.lua

@@ -22,6 +22,15 @@ GBCFX.level = 0
 
 local shader -- false = unavailable (headless / no shader support)
 
+-- Mobile GPUs often compile this pass but present a black frame, and the
+-- level persists in options.lua -- soft-bricking the APK until a manual
+-- edit (issue #136).  Desktop is unchanged; Android/iOS refuse the effect.
+function GBCFX.isSupported()
+  if not love or not love.system or not love.system.getOS then return true end
+  local osName = love.system.getOS()
+  return osName ~= "Android" and osName ~= "iOS"
+end
+
 -- GLSL 1.20-compatible (no array initializers; wavelength terms and the
 -- shadow blur are unrolled by hand).
 local SHADER_SRC = [[
@@ -214,6 +223,7 @@ vec4 effect(vec4 color, Image tex, vec2 tc, vec2 pc)
 GBCFX.SHADER_SRC = SHADER_SRC -- exposed for the standalone compile check
 
 function GBCFX.shader()
+  if not GBCFX.isSupported() then return nil end
   if shader == nil then
     local ok, sh = pcall(love.graphics.newShader, SHADER_SRC)
     shader = ok and sh or false
@@ -222,6 +232,10 @@ function GBCFX.shader()
 end
 
 function GBCFX.setLevel(level)
+  if not GBCFX.isSupported() then
+    GBCFX.level = 0
+    return
+  end
   level = math.floor(tonumber(level) or 0)
   if level < 0 then level = 0 end
   if level > 4 then level = 4 end
@@ -230,12 +244,26 @@ end
 
 -- Advance OFF → 1 → 2 → 3 → 4 → OFF.  Returns the new level.
 function GBCFX.cycle()
+  if not GBCFX.isSupported() then
+    GBCFX.level = 0
+    return 0
+  end
   GBCFX.setLevel((GBCFX.level + 1) % 5)
   return GBCFX.level
 end
 
+-- Apply opts.gbcfx.  On unsupported platforms force OFF and clear a
+-- persisted non-zero value so boot recovers from a soft-brick.  Returns
+-- true when opts was sanitized (caller should persist options.lua).
 function GBCFX.applyOptions(opts)
+  if not GBCFX.isSupported() then
+    local had = opts and (tonumber(opts.gbcfx) or 0) ~= 0
+    if opts then opts.gbcfx = 0 end
+    GBCFX.level = 0
+    return had and true or false
+  end
   GBCFX.setLevel(opts and opts.gbcfx or 0)
+  return false
 end
 
 function GBCFX.levelLabel(level)
@@ -243,7 +271,7 @@ function GBCFX.levelLabel(level)
 end
 
 function GBCFX.active()
-  return GBCFX.level > 0 and GBCFX.shader() ~= nil
+  return GBCFX.isSupported() and GBCFX.level > 0 and GBCFX.shader() ~= nil
 end
 
 -- Draw `canvas` fullscreen through the GBC FX shader into the current

src/render/PaletteFX.lua

@@ -353,18 +353,21 @@ local TILESET_GROUP_EXCEPTIONS = {
   CEMETERY = { tiles = { [0x22] = true }, group = 0 },
 }
 
--- pokered-gbc's lobby.bst repoints the Celadon roof table's flat top
+-- pokered-gbc's lobby.bst repoints the Celadon LOBBY table's flat top
 -- (block 29, cells 5/6/9/10) at a duplicate tile ($5a, BROWN) so the
 -- tabletop and the checkerboard floor -- both raw tile $37 -- can take
 -- different palettes; the vanilla-derived blockset shares the one tile
 -- id, so the RED++ atlas path re-creates the duplicate: the alias slot
 -- is baked as a copy of `tile` in `group`'s colors, and the listed
 -- 0-based block cells draw the alias instead of the shared tile.
+-- Same block appears on CELADON_MART_ROOF (#52) and CELADON_DINER (#84).
+local LOBBY_TABLE_TOP_ALIAS = {
+  { block = 29, cells = { [5] = true, [6] = true, [9] = true, [10] = true },
+    tile = 0x37, alias = 0x5a, group = 5 },
+}
 PaletteFX.TILE_ALIASES = {
-  CELADON_MART_ROOF = {
-    { block = 29, cells = { [5] = true, [6] = true, [9] = true, [10] = true },
-      tile = 0x37, alias = 0x5a, group = 5 },
-  },
+  CELADON_MART_ROOF = LOBBY_TABLE_TOP_ALIAS,
+  CELADON_DINER = LOBBY_TABLE_TOP_ALIAS,
 }
 local ROOF_GROUP = 6
 local ROUTE_6_SAFFRON = { mapId = "ROUTE_6", useMapId = "SAFFRON_CITY", cellYBelow = 2 }

src/render/Renderer.lua

@@ -94,6 +94,8 @@ function Renderer:beginFrame(transparent)
   -- warp-fade overlay from Transition (issue #121); cleared each frame so
   -- a popped transition cannot leave a sticky black veil
   self.worldFadeAlpha = nil
+  -- battle-transition cascade outside the 160x144 wipe (BattleTransition)
+  self.battleCascadeProg = nil
   -- last frame's trueColor rects and sprite redraws go before anything
   -- draws this one
   PaletteFX.clearTrueColor()
@@ -107,6 +109,46 @@ function Renderer:beginFrame(transparent)
   end
 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)
+  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)
+  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
+      -- 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))
+        order[#order + 1] = { x, y, dist }
+      end
+    end
+  end
+  if #order == 0 then return end
+  table.sort(order, function(a, b)
+    if a[3] ~= b[3] then return a[3] < b[3] end
+    if a[2] ~= b[2] then return a[2] < b[2] end
+    return a[1] < b[1]
+  end)
+  local n = math.floor(#order * math.min(1, prog) + 1e-6)
+  if prog >= 1 then n = #order end
+  love.graphics.setColor(0, 0, 0, 1)
+  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)
+  end
+  love.graphics.setScissor()
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
 function Renderer:beginWorldPass()
   local vw, vh = self:worldViewSize()
   if not self.worldCanvas or self.worldCanvas:getWidth() ~= vw
@@ -349,7 +391,20 @@ function Renderer:endFrame(zones, worldZones)
     present = self.presentCanvas
     love.graphics.setCanvas(present)
   end
-  love.graphics.setColor(0, 0, 0, 1)
+  -- Default letterbox is black.  Battle (and any state that opts in via
+  -- letterboxWhite) fills the voids white so the window matches the
+  -- white battle canvas instead of showing black bars.
+  local clearR, clearG, clearB = 0, 0, 0
+  if not self.worldActive then
+    local ok, Game = pcall(require, "src.core.Game")
+    local stack = ok and Game and Game.stack
+    local base = stack and stack.visibleBase and stack:visibleBase()
+    local state = base and stack.states and stack.states[base]
+    if state and state.letterboxWhite then
+      clearR, clearG, clearB = 1, 1, 1
+    end
+  end
+  love.graphics.setColor(clearR, clearG, clearB, 1)
   love.graphics.rectangle("fill", 0, 0, ww, wh)
   love.graphics.setColor(1, 1, 1, 1)
 
@@ -460,6 +515,11 @@ function Renderer:endFrame(zones, worldZones)
       love.graphics.rectangle("fill", 0, 0, ww, wh)
       love.graphics.setColor(1, 1, 1, 1)
     end
+    -- 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)
+    end
   end
   -- UI stays in the classic centered GB letterbox
   blit(self.canvas, S, zones, S, ox, oy, ox, oy, vpw, vph)

src/render/TileRenderer.lua

@@ -10,19 +10,57 @@ TileRenderer.__index = TileRenderer
 
 local BORDER_BLOCKS = 3 -- ring width; > half a screen (2.5 blocks)
 
--- OVERWORLD maps fill beyond-edge space with the solid tree wall
--- (blockset $0F: four regular-tree metatiles, tiles $40/$41/$50/$51, 
--- the border block of ViridianCity/CeruleanCity/CeladonCity et al.),
--- not each map's own border_block, which can be grass ($0B, the
--- CutTreeBlockSwaps $0B->$0A cut-grass block) or water; other
--- tilesets keep their designated border (interiors stay black/void)
+-- OVERWORLD maps fill beyond-edge space from save.options.voidFill:
+--   trees (default) — solid tree wall $0F (Viridian/Cerulean/Celadon)
+--   water           — solid water $43 (Cinnabar/Route 19 border block)
+--   black           — solid black (no tiled metatile)
+-- Other tilesets keep their designated border (interiors stay black/void).
 local TREE_WALL_BLOCK = 0x0F
+local WATER_BORDER_BLOCK = 0x43
+TileRenderer.VOID_FILLS = { "trees", "water", "black" }
+TileRenderer.voidFill = "trees"
+
 local function borderBlockFor(map)
-  if map.def.tileset == "OVERWORLD" then return TREE_WALL_BLOCK end
+  if map.def.tileset == "OVERWORLD" then
+    local mode = TileRenderer.voidFill or "trees"
+    if mode == "water" then return WATER_BORDER_BLOCK end
+    if mode == "black" then return false end
+    return TREE_WALL_BLOCK
+  end
   return map.def.borderBlock
 end
 TileRenderer.borderBlockFor = borderBlockFor
 
+function TileRenderer.setVoidFill(mode)
+  local ok = false
+  for _, m in ipairs(TileRenderer.VOID_FILLS) do
+    if m == mode then ok = true; break end
+  end
+  TileRenderer.voidFill = ok and mode or "trees"
+end
+
+function TileRenderer.cycleVoidFill()
+  local cur = TileRenderer.voidFill or "trees"
+  local idx = 1
+  for i, m in ipairs(TileRenderer.VOID_FILLS) do
+    if m == cur then idx = i; break end
+  end
+  TileRenderer.setVoidFill(
+    TileRenderer.VOID_FILLS[idx % #TileRenderer.VOID_FILLS + 1])
+  return TileRenderer.voidFill
+end
+
+function TileRenderer.applyOptions(opts)
+  TileRenderer.setVoidFill(opts and opts.voidFill or "trees")
+end
+
+function TileRenderer.voidFillLabel(mode)
+  mode = mode or TileRenderer.voidFill or "trees"
+  if mode == "water" then return "WATER" end
+  if mode == "black" then return "BLACK" end
+  return "TREES"
+end
+
 local imageCache = {}
 
 local function getImage(path)
@@ -55,8 +93,29 @@ local FLOWER_IMAGES = {
 local SPINNER_STRIP = "assets/generated/tilesets/spinners.png"
 
 local animFrame = 0
-function TileRenderer.tick()
-  animFrame = animFrame + 1
+local animAccum = 0
+local ANIM_STEP = 1 / 60 -- Game Boy logic rate (matches FixedStep.STEP)
+
+-- Advance water/flower/spinner tile animation.  Called from the overworld
+-- draw path so it keeps running under dialogs (overworld update does not),
+-- but consumes wall-clock dt into 60Hz steps so high/low display refresh
+-- no longer speeds up or slows the cycle (issue #4).
+-- tick() / tick(nil) with no love.timer.getDelta (headless tests) still
+-- advances exactly one frame per call.
+function TileRenderer.tick(dt)
+  if dt == nil and love and love.timer and love.timer.getDelta then
+    dt = love.timer.getDelta()
+  end
+  if dt == nil then
+    animFrame = animFrame + 1
+    return
+  end
+  -- Cap catch-up so a long stall cannot jump many water/flower periods
+  animAccum = math.min(animAccum + dt, 0.25)
+  while animAccum >= ANIM_STEP do
+    animAccum = animAccum - ANIM_STEP
+    animFrame = animFrame + 1
+  end
 end
 
 -- ------------------------------------------------------------------
@@ -466,42 +525,118 @@ function TileRenderer.new(map, data)
   self.anims = anims
   self.claimedBy = claimedBy
 
-  -- a repeating 32x32 image of the border block, tiled behind
-  -- everything the 3-block ring doesn't cover (the survey zoom sees
-  -- far past the ring; interiors keep their black border this way)
-  pcall(function()
-    local border = map.tileset.blocks[borderBlockFor(map) + 1]
-    if not border then return end
-    local canvas = love.graphics.newCanvas(32, 32)
-    love.graphics.push("all")
-    love.graphics.setCanvas(canvas)
-    love.graphics.clear(1, 1, 1, 1)
-    for ty = 0, 3 do
-      for tx = 0, 3 do
-        local quad = self.quads[border[ty * 4 + tx + 1]]
-        if quad then love.graphics.draw(self.image, quad, tx * 8, ty * 8) end
-      end
-    end
-    love.graphics.setCanvas()
-    love.graphics.pop()
-    local img = love.graphics.newImage(canvas:newImageData())
-    img:setWrap("repeat", "repeat")
-    img:setFilter("nearest", "nearest")
-    self.borderFill = img
-  end)
+  -- border-fill image is built lazily in :ensureBorderFill so a VOID FILL
+  -- option change can swap trees/water/black without reloading the map
+  self.borderFillMode = nil
+  self.borderFill = nil
 
   return self
 end
 
+-- Bake a static repeating 32x32 of `block` into self.borderFill.
+local function bakeBorderFill(self, block)
+  local border = self.map.tileset.blocks[block + 1]
+  if not border then return end
+  local canvas = love.graphics.newCanvas(32, 32)
+  love.graphics.push("all")
+  love.graphics.setCanvas(canvas)
+  love.graphics.clear(1, 1, 1, 1)
+  for ty = 0, 3 do
+    for tx = 0, 3 do
+      local quad = self.quads[border[ty * 4 + tx + 1]]
+      if quad then love.graphics.draw(self.image, quad, tx * 8, ty * 8) end
+    end
+  end
+  love.graphics.setCanvas()
+  love.graphics.pop()
+  local img = love.graphics.newImage(canvas:newImageData())
+  img:setWrap("repeat", "repeat")
+  img:setFilter("nearest", "nearest")
+  self.borderFill = img
+end
+
+-- WATER void fill: the eight hshift frames of tile $14 (same cycle as map
+-- water), wrap-tiled so the void scrolls in lockstep with on-map water.
+local function ensureWaterBorderFill(self)
+  if self.borderWaterTextures then return true end
+  local map = self.map
+  local perRow = map.tileset.tilesPerRow
+  local colors, gbcKey
+  if self.gbcAtlas and self.data then
+    local group = PaletteFX.worldGroupAt(map.tileset.id, map.id, WATER_TILE)
+    local groupColors = PaletteFX.worldGroupColors(
+      self.data, map.tileset.id, map.id, nil)
+    colors = group and groupColors and groupColors[group + 1] or nil
+    gbcKey = "#gbc:" .. map.id
+  end
+  local textures = getShiftVariants(map.tileset.image, perRow, WATER_TILE,
+                                    colors, gbcKey)
+  if not textures then return false end
+  for _, img in ipairs(textures) do
+    img:setWrap("repeat", "repeat")
+    img:setFilter("nearest", "nearest")
+  end
+  self.borderWaterTextures = textures
+  return true
+end
+
+-- (re)build the repeating border image when the VOID FILL mode or tileset
+-- choice changes.  OVERWORLD "black" leaves borderFill nil and draws a
+-- solid clear; "water" keeps the live hshift textures instead of a bake.
+function TileRenderer:ensureBorderFill()
+  local block = borderBlockFor(self.map)
+  local mode = block == false and "black"
+              or ((self.map.def.tileset == "OVERWORLD")
+                  and (TileRenderer.voidFill or "trees")
+                  or "map")
+  local ready = (mode == "black")
+                or (mode == "water" and self.borderWaterTextures)
+                or (mode ~= "water" and mode ~= "black" and self.borderFill)
+  if self.borderFillMode == mode and ready then return end
+  if self.borderFill and self.borderFill.release then
+    pcall(self.borderFill.release, self.borderFill)
+  end
+  self.borderFill = nil
+  -- shared shift-variant cache: drop the reference only, never release
+  self.borderWaterTextures = nil
+  self.borderFillMode = mode
+  if mode == "black" or block == false or block == nil then return end
+  if mode == "water" then
+    if ensureWaterBorderFill(self) then return end
+    -- headless / missing pixels: fall back to the static water block bake
+  end
+  pcall(bakeBorderFill, self, block)
+end
+
 -- tile the border block across the whole view (world-aligned so it
 -- meshes seamlessly with the ring batch)
 function TileRenderer:drawBorderFill(camX, camY, vw, vh)
-  if not self.borderFill then return end
+  self:ensureBorderFill()
+  if self.borderFillMode == "black" then
+    love.graphics.setColor(0, 0, 0, 1)
+    love.graphics.rectangle("fill", 0, 0, vw, vh)
+    love.graphics.setColor(1, 1, 1, 1)
+    return
+  end
   if self.trueColor then PaletteFX.markTrueColor(0, 0, vw, vh) end
   local x, y = math.floor(camX), math.floor(camY)
   -- one reused Quad per renderer, mutated in place: this runs every
   -- overworld frame, so allocating a fresh Quad here churned the GC
   local q = self.borderQuad
+  if self.borderFillMode == "water" and self.borderWaterTextures then
+    local step = math.floor(animFrame / ANIM_PERIOD) % #WATER_OFFSETS + 1
+    local tex = self.borderWaterTextures[WATER_OFFSETS[step] + 1]
+    if not tex then return end
+    if q then
+      q:setViewport(x, y, vw, vh, 8, 8)
+    else
+      q = love.graphics.newQuad(x, y, vw, vh, 8, 8)
+      self.borderQuad = q
+    end
+    love.graphics.draw(tex, q, 0, 0)
+    return
+  end
+  if not self.borderFill then return end
   if q then
     q:setViewport(x, y, vw, vh, 32, 32)
   else
@@ -709,6 +844,9 @@ function TileRenderer:releaseBatches()
   safeRelease(self.winBatch); self.winBatch = nil
   safeRelease(self.borderFill); self.borderFill = nil
   safeRelease(self.borderQuad); self.borderQuad = nil
+  -- shared shift-variant cache; only drop the reference
+  self.borderWaterTextures = nil
+  self.borderFillMode = nil
   self.win = nil
   if self.quads then
     for _, q in pairs(self.quads) do safeRelease(q) end

src/render/Zoom.lua

@@ -1,6 +1,7 @@
 -- Overworld survey zoom: integer pixels-per-world-pixel scales stepped
--- by the mouse wheel.  Stored as an offset from the window fit scale S
--- so a resize keeps the relative zoom.  Session-only; never saved.
+-- by the mouse wheel, Options ZOOM row, or hotkey `4`.  Stored as an
+-- offset from the window fit scale S so a resize keeps the relative
+-- zoom.  Persisted as save.options.zoom (default 0 = FIT).
 -- Spec: docs/new-features.md (survey zoom)
 
 local Zoom = {}
@@ -12,16 +13,51 @@ function Zoom.scale(S)
   return math.max(1, math.min(2 * S, S + Zoom.offset))
 end
 
+-- legal offset range for a given fit scale
+function Zoom.offsetRange(S)
+  S = math.max(1, math.floor(tonumber(S) or 1))
+  return 1 - S, S
+end
+
+function Zoom.clampOffset(offset, S)
+  local lo, hi = Zoom.offsetRange(S)
+  offset = math.floor(tonumber(offset) or 0)
+  if offset < lo then return lo end
+  if offset > hi then return hi end
+  return offset
+end
+
 function Zoom.step(delta, S)
-  Zoom.offset = Zoom.offset + delta
-  if S + Zoom.offset < 1 then Zoom.offset = 1 - S end
-  if S + Zoom.offset > 2 * S then Zoom.offset = S end
+  Zoom.offset = Zoom.clampOffset(Zoom.offset + delta, S)
+  return Zoom.offset
+end
+
+-- Advance one zoom level toward max close-up, then wrap to full survey.
+-- Returns the new offset.
+function Zoom.cycle(S)
+  local lo, hi = Zoom.offsetRange(S)
+  local next = Zoom.offset + 1
+  if next > hi then next = lo end
+  Zoom.offset = next
+  return Zoom.offset
 end
 
 function Zoom.reset()
   Zoom.offset = 0
 end
 
+function Zoom.applyOptions(opts)
+  Zoom.offset = math.floor(tonumber(opts and opts.zoom) or 0)
+end
+
+-- FIT / OUT1 / OUT2 / … / IN1 / IN2 / …
+function Zoom.offsetLabel(offset)
+  offset = math.floor(tonumber(offset) or 0)
+  if offset == 0 then return "FIT" end
+  if offset < 0 then return "OUT" .. tostring(-offset) end
+  return "IN" .. tostring(offset)
+end
+
 -- world pixels covered by a w x h letterbox viewport at fit scale S
 -- (legacy GB-framed size; prefer fillViewSize for the live world pass)
 function Zoom.viewSize(S, w, h)

src/ui/BindingsMenu.lua

@@ -11,7 +11,9 @@ local Input = require("src.core.Input")
 local BindingsMenu = setmetatable({}, { __index = ListMenu })
 BindingsMenu.__index = BindingsMenu
 
--- Input.lua's map, primary key first where several keys share a button
+-- Input.lua's map, primary key first where several keys share a button.
+-- `pad` is the default SDL gamecontroller button (see Input.lua); shown
+-- on the SELECT row so controller Back/View is discoverable (#73).
 local BUTTONS = {
   { id = "up", label = "UP", key = "up" },
   { id = "down", label = "DOWN", key = "down" },
@@ -20,7 +22,7 @@ local BUTTONS = {
   { id = "a", label = "A", key = "z" },
   { id = "b", label = "B", key = "x" },
   { id = "start", label = "START", key = "escape" },
-  { id = "select", label = "SELECT", key = "rshift" },
+  { id = "select", label = "SELECT", key = "tab", pad = "back" },
 }
 
 -- a binding is a plain key string or { key, pad }; absent = the fixed
@@ -32,13 +34,29 @@ local function boundKey(overlay, def)
   return def.key
 end
 
+local function boundPad(overlay, def)
+  local b = overlay and overlay[def.id]
+  if type(b) == "table" and b.pad then return b.pad end
+  return def.pad
+end
+
+-- Key column for every row. SELECT also appends "/PAD" (default BACK)
+-- so controller Select/View is visible without opening a second legend.
+local function boundRight(overlay, def)
+  local key = boundKey(overlay, def)
+  if def.id ~= "select" then return key:upper() end
+  local pad = boundPad(overlay, def)
+  if pad then return (key .. "/" .. pad):upper() end
+  return key:upper()
+end
+
 function BindingsMenu.new(game)
   local overlay = game.save and game.save.options
                   and game.save.options.bindings
   local items = {}
   for i, def in ipairs(BUTTONS) do
     items[i] = { label = def.label,
-                 right = boundKey(overlay, def):upper(), button = def }
+                 right = boundRight(overlay, def), button = def }
   end
   local self = setmetatable(ListMenu.new(game, "CONTROLS", items, {}),
                             BindingsMenu)
@@ -78,7 +96,7 @@ function BindingsMenu:storeBinding(slot, value)
   end
   b[slot] = value
   opts.bindings[item.button.id] = b
-  item.right = boundKey(opts.bindings, item.button):upper()
+  item.right = boundRight(opts.bindings, item.button)
   Input:applyBindings(opts.bindings)
   if game.writeOptions then game:writeOptions() end
 end

src/ui/OptionsMenu.lua

@@ -3,7 +3,8 @@
 -- (cycles the merged rulesets registry; gen1_faithful keeps the original
 -- quirks), plus the port's audio rows and display rows: music/SFX
 -- volume (0-7), music low-pass filter (OFF/1X/2X/3X), COLORS / TILT /
--- GBC FX / VIDEO MODE, and the MODS row that opens the mod manager.
+-- GBC FX / ZOOM / VOID FILL / VIDEO MODE, and the MODS row that opens
+-- the mod manager.
 -- Rows are descriptors fed through the ui.options.rows hook, so mods can
 -- add their own; CANCEL is appended after the hook and stays fixed on the
 -- bottom line like pokered's.
@@ -11,12 +12,15 @@
 local PaletteFX = require("src.render.PaletteFX")
 local Tilt = require("src.render.Tilt")
 local GBCFX = require("src.render.GBCFX")
+local Zoom = require("src.render.Zoom")
+local TileRenderer = require("src.render.TileRenderer")
 local GameSpeed = require("src.core.GameSpeed")
 local VideoMode = require("src.core.VideoMode")
 local FrameCap = require("src.core.FrameCap")
 local Logger = require("src.core.Logger")
 local Runtime = require("src.mods.Runtime")
 local OptionRows = require("src.ui.OptionRows")
+local Renderer = require("src.render.Renderer")
 
 local OptionsMenu = {}
 OptionsMenu.__index = OptionsMenu
@@ -110,7 +114,7 @@ local function sameRows(_, rows) return rows end
 -- the vanilla rows as descriptors; each step body is the old per-index
 -- ladder's, so the save.options mutations are unchanged
 local function buildRows(game)
-  return {
+  local rows = {
     { id = "textSpeed", label = "TEXT SPEED",
       value = function(g) return SPEEDS[speedIndex(g)][2] end,
       step = function(g)
@@ -201,6 +205,37 @@ local function buildRows(game)
         GBCFX.setLevel(o.gbcfx)
         return true
       end },
+    { id = "zoom", label = "ZOOM",
+      value = function(g)
+        return Zoom.offsetLabel(g.save.options.zoom or 0)
+      end,
+      step = function(g, dir)
+        local o = g.save.options
+        local S = Renderer:fitScale()
+        local lo, hi = Zoom.offsetRange(S)
+        local off = (o.zoom or 0) + dir
+        if off > hi then off = lo
+        elseif off < lo then off = hi end
+        o.zoom = off
+        Zoom.offset = off
+        return true
+      end },
+    { id = "voidFill", label = "VOID FILL",
+      value = function(g)
+        return TileRenderer.voidFillLabel(g.save.options.voidFill)
+      end,
+      step = function(g, dir)
+        local o = g.save.options
+        local modes = TileRenderer.VOID_FILLS
+        local cur = o.voidFill or "trees"
+        local i = 1
+        for idx, m in ipairs(modes) do
+          if m == cur then i = idx; break end
+        end
+        o.voidFill = modes[wrapIndex(i - 1 + dir, #modes) + 1]
+        TileRenderer.setVoidFill(o.voidFill)
+        return true
+      end },
     { id = "videoMode", label = "VIDEO MODE",
       value = function(g)
         return VideoMode.modeLabel(g.save.options.videoMode)
@@ -252,6 +287,15 @@ local function buildRows(game)
         require("src.ui.Screens").push(g, "BindingsMenu")
       end },
   }
+  -- issue #136: hide GBC FX on Android/iOS -- the present shader soft-bricks
+  if not GBCFX.isSupported() then
+    local filtered = {}
+    for _, row in ipairs(rows) do
+      if row.id ~= "gbcfx" then filtered[#filtered + 1] = row end
+    end
+    rows = filtered
+  end
+  return rows
 end
 
 function OptionsMenu.new(game)

src/ui/PartyMenu.lua

@@ -11,6 +11,8 @@ local Logger = require("src.core.Logger")
 local Runtime = require("src.mods.Runtime")
 local Screens = require("src.ui.Screens")
 local Theme = require("src.ui.Theme")
+local FieldDefaults = require("src.world.FieldDefaults")
+local Map = require("src.world.Map")
 
 local PartyMenu = {}
 PartyMenu.__index = PartyMenu
@@ -355,8 +357,12 @@ function PartyMenu:update(dt)
       -- Battle still excludes this list via `not self.battle`. Softboiled
       -- can appear for a fainted user; its heal transfer then no-ops.
       if not self.battle and ow then
+        -- FLY/TELEPORT: CheckIfInOutsideMap (OVERWORLD + PLATEAU —
+        -- Route 23 / Indigo Plateau outdoor), not OVERWORLD alone (#83)
+        local outside = Map.isOutside(ow.map.def,
+          FieldDefaults.field(self.game.data, "outsideTilesets"))
         for _, mv in ipairs(mon.moves) do
-          if mv.id == "FLY" and ow.map.def.tileset == "OVERWORLD"
+          if mv.id == "FLY" and outside
              and self.game.save.inventory.THUNDERBADGE then
             table.insert(items, { label = "FLY", action = "fly" })
           elseif mv.id == "FLASH" and ow.dark
@@ -375,7 +381,7 @@ function PartyMenu:update(dt)
             table.insert(items, { label = "STRENGTH", action = "strength" })
           elseif mv.id == "SOFTBOILED" then
             table.insert(items, { label = "SOFTBOILED", action = "softboiled" })
-          elseif mv.id == "TELEPORT" and ow.map.def.tileset == "OVERWORLD" then
+          elseif mv.id == "TELEPORT" and outside then
             -- TELEPORT works only OUTDOORS (start_sub_menus.asm
             -- .teleport -> CheckIfInOutsideMap); dark maps don't
             -- block it

src/world/OverworldController.lua

@@ -2431,6 +2431,27 @@ function OverworldState:runVictoryHook()
   if hooks and hooks.onVictory then hooks.onVictory(Game, self) end
 end
 
+-- pokered player sprite is fixed at screen ($40, $3c).  TrainerEngage reads
+-- the NPC's 8-bit SPRITESTATEDATA1 X/Y pixels and CalcDifference; engage
+-- distance is stored as range<<4 (pixels).  There is no tile LOS check for
+-- interposed NPCs / walls -- but unsigned 8-bit Y makes a sprite exactly 4
+-- tiles north of the player sit at Y=$fc, so |$3c-$fc|=$c0 and a range-4
+-- DOWN trainer does not engage that tile (Route 9 Bug Catcher / issue #76).
+local PLAYER_SCREEN_X, PLAYER_SCREEN_Y = 0x40, 0x3c
+local function u8(n) return n % 256 end
+local function calcDiff(a, b)
+  a, b = u8(a), u8(b)
+  return a >= b and a - b or b - a
+end
+local function trainerSightPixelDist(npc, player, horizontal)
+  if horizontal then
+    return calcDiff(PLAYER_SCREEN_X,
+                    u8(PLAYER_SCREEN_X + (npc.cellX - player.cellX) * 16))
+  end
+  return calcDiff(PLAYER_SCREEN_Y,
+                  u8(PLAYER_SCREEN_Y + (npc.cellY - player.cellY) * 16))
+end
+
 -- STAY trainers with a facing spot the player crossing their line of
 -- sight (range from the extracted trainer headers), walk up and battle.
 function OverworldState:checkTrainerSight()
@@ -2448,22 +2469,23 @@ function OverworldState:checkTrainerSight()
       local range = header and header.range or 0
       local vec = DIRVEC[npc.facing]
       if range > 0 and vec then
-        local dist
+        local dist, horizontal
         if vec[1] ~= 0 and npc.cellY == p.cellY then
           dist = (p.cellX - npc.cellX) * vec[1]
+          horizontal = true
         elseif vec[2] ~= 0 and npc.cellX == p.cellX then
           dist = (p.cellY - npc.cellY) * vec[2]
+          horizontal = false
         end
-        -- pokered's TrainerEngage / CheckSpriteCanSeePlayer compares screen
-        -- coordinates only (home/trainers.asm, engine/overworld/
-        -- trainer_sight.asm) -- there is no line-of-sight obstruction check.
-        -- An aligned trainer within range engages through interposed NPCs and
-        -- unwalkable tiles, and the scripted walk-up below (scriptMove) also
-        -- ignores collision, so the trainer simply walks/overlaps through
-        -- anything on the line -- exactly as OAM sprites overlap on hardware.
-        if dist and dist >= 1 and dist <= range then
-          self:startTrainerApproach(npc, dist)
-          return
+        -- Screen-pixel range (CheckSpriteCanSeePlayer), not cell count:
+        -- same facing-line rule as before, but the $fc Y quirk excludes the
+        -- 4-tiles-north tile that cell math would still count as in range.
+        if dist and dist >= 1 then
+          local pixelDist = trainerSightPixelDist(npc, p, horizontal)
+          if pixelDist > 0 and pixelDist <= range * 16 then
+            self:startTrainerApproach(npc, dist)
+            return
+          end
         end
       end
     end
@@ -3492,7 +3514,9 @@ function OverworldState:billboard(fx, fy, vw, vh, colors, keyed, drawFn)
 end
 
 function OverworldState:drawWorld()
-  -- advance the water/flower tile animation (runs under dialogs too)
+  -- advance the water/flower tile animation (runs under dialogs too).
+  -- TileRenderer.tick uses wall-clock 60Hz steps so display refresh rate
+  -- does not speed or slow the cycle (issue #4).
   require("src.render.TileRenderer").tick()
   -- let the renderer know whether a spinner puzzle is currently sliding
   -- the player, so it can flicker the arrow tiles between the blur and

src/world/Player.lua

@@ -81,6 +81,14 @@ end
 
 -- Advance one fixed step; returns true when a step just completed.
 function Player:update()
+  -- land-frame walk pose lasts only through the draw after completion;
+  -- the next update (idle or a chained step) clears it
+  self.stepLanded = false
+  -- Ledge-hop arc is cosmetic but must track the fixed 60Hz logic step,
+  -- not love.draw's display refresh (issue #4: >59fps ended early).
+  if self.hopFrames and self.hopFrames > 0 then
+    self.hopFrames = self.hopFrames - 1
+  end
   if self.turnTimer > 0 then
     self.turnTimer = self.turnTimer - 1
   end
@@ -109,6 +117,11 @@ function Player:update()
     self.px, self.py = self.cellX * 16, self.cellY * 16
     self.moving = false
     self.stepFlip = not self.stepFlip
+    -- keep animClock's pose on this frame (issue #82): bike steps land
+    -- mid-cycle (animClock % 16 == 8), and walkPhase used to snap to
+    -- stand whenever moving cleared — a stand flash every tile on the
+    -- bike, and sometimes after dismount when the clock is desynced
+    self.stepLanded = true
     return true
   end
   return false
@@ -119,7 +132,7 @@ function Player:facingCell()
 end
 
 function Player:walkPhase()
-  if not self.moving then return 0 end
+  if not self.moving and not self.stepLanded then return 0 end
   -- walk frame during the middle of each 16-frame animation cycle
   local p = (self.animClock or self.progress) % 16
   return (p >= 4 and p < 12) and 1 or 0
@@ -129,10 +142,13 @@ local SPIN_ORDER = { "down", "left", "up", "right" }
 
 function Player:draw(camX, camY)
   local py = self.py
-  -- ledge hops arc (set for 2 cells by the ledge handler); surfing bobs
+  -- ledge hops arc (set for 2 cells by the ledge handler); surfing bobs.
+  -- hopFrames counts down in Player:update (fixed step), never here.
   if self.hopFrames and self.hopFrames > 0 then
-    self.hopFrames = self.hopFrames - 1
-    local t = 1 - self.hopFrames / (self.hopTotal or 32)
+    local total = self.hopTotal or 32
+    -- update runs before draw, so remaining N means N steps already
+    -- consumed this hop → t matches the old draw-side post-decrement phase
+    local t = 1 - self.hopFrames / total
     py = py - math.floor(10 * math.sin(t * math.pi) + 0.5)
     -- the shadow stays on the ground under the jumper: one 8x8 tile
     -- mirrored into a 2x2 block (normal/XFLIP/YFLIP/both) whose top-left

tests/mod_graphics_tests.lua

@@ -620,6 +620,22 @@ check(PaletteFX.pal({ palettes = nil }, "ROUTE") == gbc.palettes.ROUTE,
       "RED++ still has ROUTE (aliased from VIRIDIAN)")
 check(PaletteFX.effectiveColors(gbc.palettes.MEWMON) == gbc.palettes.MEWMON,
       "RED++ passes zone colors through like GBC")
+-- issue #84: CELADON_DINER shares LOBBY block 29 (table top) with
+-- CELADON_MART_ROOF (#52); both need the $37->$5a BROWN alias
+do
+  local aliases = PaletteFX.TILE_ALIASES
+  local roof = aliases and aliases.CELADON_MART_ROOF
+  local diner = aliases and aliases.CELADON_DINER
+  check(roof ~= nil and diner ~= nil,
+        "CELADON_MART_ROOF and CELADON_DINER both have TILE_ALIASES")
+  check(diner == roof,
+        "diner reuses the same lobby table-top alias as the mart roof")
+  local al = diner and diner[1]
+  check(al and al.block == 29 and al.tile == 0x37 and al.alias == 0x5a
+        and al.group == 5 and al.cells[5] and al.cells[6]
+        and al.cells[9] and al.cells[10],
+        "lobby table-top alias remaps block 29 cells 5/6/9/10")
+end
 -- issue #128: RED++'s gbc pack is Red-derived; Blue must keep ROM LOGO1
 -- (and the Blue-only SLOTS* rows) so the title ribbon is blue, not red
 do
@@ -738,6 +754,97 @@ do
   love.graphics.rectangle, love.graphics.setColor = savedRect, savedColor
 end
 
+-- ------- battle transition cascade outside the OG square + white letterbox
+do
+  local rects = {}
+  local color = { 1, 1, 1, 1 }
+  local savedRect, savedColor = love.graphics.rectangle, love.graphics.setColor
+  local savedGetDims = love.graphics.getDimensions
+  local savedGetPix = love.graphics.getPixelDimensions
+  -- taller-than-fit window so the 160x144 letterbox leaves real voids
+  -- (default 640x576 is an exact 4x fit with nothing outside the square)
+  love.graphics.getDimensions = function() return 800, 600 end
+  love.graphics.getPixelDimensions = function() return 800, 600 end
+  love.graphics.rectangle = function(mode, x, y, w, h)
+    rects[#rects + 1] = {
+      mode = mode, x = x, y = y, w = w, h = h,
+      r = color[1], g = color[2], b = color[3], a = color[4],
+    }
+  end
+  love.graphics.setColor = function(r, g, b, a)
+    color[1], color[2], color[3], color[4] = r, g, b, a or 1
+  end
+
+  Renderer:init()
+  local btGame = { renderer = Renderer, stack = { pop = noop } }
+  local wipe = BattleTransition.new(btGame, nil, {})
+  wipe.phase = "wipe"
+  wipe.t = math.floor(wipe.wipeLen / 2)
+  Renderer:beginFrame(true)
+  Renderer:beginWorldPass()
+  Renderer:endWorldPass()
+  wipe:draw()
+  check(Renderer.battleCascadeProg ~= nil
+        and Renderer.battleCascadeProg > 0
+        and Renderer.battleCascadeProg < 1,
+        "battle wipe publishes mid-progress cascade to the renderer")
+  rects = {}
+  Renderer:endFrame(nil, fullWorldZones())
+  local cascadeTile
+  for _, r in ipairs(rects) do
+    -- fitScale at 800x600 is min(5,4)=4 → 32px tiles outside the letterbox
+    if r.mode == "fill" and r.r == 0 and r.a == 1 and r.w == 32 and r.h == 32 then
+      cascadeTile = r
+      break
+    end
+  end
+  check(cascadeTile ~= nil,
+        "endFrame paints cascading black tiles outside the OG wipe square")
+  love.graphics.rectangle, love.graphics.setColor = savedRect, savedColor
+  love.graphics.getDimensions = savedGetDims
+  love.graphics.getPixelDimensions = savedGetPix
+end
+
+do
+  -- BattleState asks for white letterbox voids instead of black bars
+  local BattleState = require("src.battle.BattleState")
+  check(BattleState.letterboxWhite == true,
+        "BattleState opts into white letterbox fill")
+  local rects = {}
+  local color = { 1, 1, 1, 1 }
+  local savedRect, savedColor = love.graphics.rectangle, love.graphics.setColor
+  love.graphics.rectangle = function(mode, x, y, w, h)
+    rects[#rects + 1] = {
+      mode = mode, x = x, y = y, w = w, h = h,
+      r = color[1], g = color[2], b = color[3], a = color[4],
+    }
+  end
+  love.graphics.setColor = function(r, g, b, a)
+    color[1], color[2], color[3], color[4] = r, g, b, a or 1
+  end
+  local Game = require("src.core.Game")
+  local savedStack = Game.stack
+  Game.stack = {
+    states = { { letterboxWhite = true, isOpaque = true } },
+    visibleBase = function() return 1 end,
+  }
+  Renderer:init()
+  Renderer:beginFrame(false)
+  rects = {}
+  Renderer:endFrame(nil, nil)
+  local clear
+  for _, r in ipairs(rects) do
+    if r.mode == "fill" and r.x == 0 and r.y == 0 and r.w == 640 and r.h == 576 then
+      clear = r
+      break
+    end
+  end
+  check(clear and clear.r == 1 and clear.g == 1 and clear.b == 1,
+        "endFrame fills the window white when the visible base wants letterboxWhite")
+  Game.stack = savedStack
+  love.graphics.rectangle, love.graphics.setColor = savedRect, savedColor
+end
+
 -- ------- the transition.style hook
 
 local stack = { pop = function() end }

tests/mod_ui_tests.lua

@@ -206,7 +206,8 @@ end
 local om = OptionsMenu.new(optGame())
 local WANT_IDS = { "textSpeed", "animations", "battleStyle", "ruleset",
                    "musicVol", "sfxVol", "musicFilter", "colors", "tilt",
-                   "gbcfx", "videoMode", "fpsCap", "speed", "mods", "controls" }
+                   "gbcfx", "zoom", "voidFill", "videoMode", "fpsCap",
+                   "speed", "mods", "controls" }
 check(#om.rows == #WANT_IDS, "vanilla options row count (plus MODS/CONTROLS)")
 for i, id in ipairs(WANT_IDS) do
   check(om.rows[i].id == id, "options row order: " .. id)
@@ -236,17 +237,35 @@ check(om.game.save.options.musicVol == 6, "music volume steps down")
 for _ = 1, 10 do om.rows[5].step(om.game, -1) end
 check(om.game.save.options.musicVol == 0, "music volume clamps at 0")
 
+-- ZOOM / VOID FILL rows
+local Zoom = require("src.render.Zoom")
+local TileRenderer = require("src.render.TileRenderer")
+om.game.save.options.zoom = 0
+Zoom.offset = 0
+check(om.rows[11].value(om.game) == "FIT", "ZOOM row shows FIT at offset 0")
+om.rows[11].step(om.game, 1)
+check(om.game.save.options.zoom == 1 and Zoom.offset == 1,
+  "ZOOM row steps to IN1")
+om.rows[12].step(om.game, 1)
+check(om.game.save.options.voidFill == "water"
+      and TileRenderer.voidFill == "water",
+  "VOID FILL row cycles TREES → WATER")
+om.rows[12].step(om.game, 1)
+check(om.game.save.options.voidFill == "black", "VOID FILL steps to BLACK")
+om.rows[12].step(om.game, 1)
+check(om.game.save.options.voidFill == "trees", "VOID FILL wraps to TREES")
+
 -- the MAX FPS row cycles the render-cap steps and shows the value plain
 om.game.save.options.fpsCap = nil
-check(om.rows[12].value(om.game) == "60",
+check(om.rows[14].value(om.game) == "60",
   "MAX FPS row defaults to 60 with no saved cap")
-om.rows[12].step(om.game, 1)
+om.rows[14].step(om.game, 1)
 check(om.game.save.options.fpsCap == 75, "MAX FPS steps up from 60 to 75")
-check(om.rows[12].value(om.game) == "75", "the MAX FPS row renders the cap")
+check(om.rows[14].value(om.game) == "75", "the MAX FPS row renders the cap")
 om.game.save.options.fpsCap = 160
-om.rows[12].step(om.game, 1)
+om.rows[14].step(om.game, 1)
 check(om.game.save.options.fpsCap == 30, "MAX FPS wraps past the ceiling to 30")
-om.rows[12].step(om.game, -1)
+om.rows[14].step(om.game, -1)
 check(om.game.save.options.fpsCap == 160, "MAX FPS wraps back down to the ceiling")
 
 -- ------- FrameCap normalize / cycle (issue #88)
@@ -276,7 +295,7 @@ check(FrameCap.current == 60, "FrameCap.applyOptions defaults a missing key to 6
 -- the MODS row is the manager's discoverable home
 local mgGame = optGame()
 om = OptionsMenu.new(mgGame)
-om.rows[14].activate(mgGame)
+om.rows[16].activate(mgGame)
 check(getmetatable(mgGame.stack:top()) == ManagerState,
   "the MODS row opens the manager")
 check(mgGame.stack:top().screenId == "ManagerState",
@@ -286,7 +305,7 @@ check(mgGame.stack:top().screenId == "ManagerState",
 local BindingsMenu = require("src.ui.BindingsMenu")
 local cbGame = optGame()
 om = OptionsMenu.new(cbGame)
-om.rows[15].activate(cbGame)
+om.rows[17].activate(cbGame)
 local bm = cbGame.stack:top()
 check(getmetatable(bm) == BindingsMenu,
   "the CONTROLS row opens the rebind list")
@@ -295,7 +314,8 @@ check(bm.screenId == "BindingsMenu",
 check(#bm.items == 8, "one row per logical button")
 check(bm.items[1].label == "UP" and bm.items[1].right == "UP"
   and bm.items[5].label == "A" and bm.items[5].right == "Z"
-  and bm.items[7].label == "START" and bm.items[7].right == "ESCAPE",
+  and bm.items[7].label == "START" and bm.items[7].right == "ESCAPE"
+  and bm.items[8].label == "SELECT" and bm.items[8].right == "TAB/BACK",
   "with no rebind the rows mirror the fixed map")
 check(cbGame.save.options.bindings == nil,
   "opening the screen alone writes nothing")

tests/parity_I_M.lua

@@ -432,6 +432,50 @@ check(actsFaint.fly and actsFaint.cut and actsFaint.surf and actsFaint.strength,
       "fainted mon still lists FLY/CUT/SURF/STRENGTH in the party submenu")
 popToOW()
 
+-- ===========================================================================
+-- #83: FLY/TELEPORT use CheckIfInOutsideMap (OVERWORLD + PLATEAU), so the
+-- outdoor strip between Victory Road and the Elite Four / Indigo Plateau
+-- building allows Fly like any other outdoor overworld map.
+-- ===========================================================================
+Game.save.party = { mkMon("AERODACTYL", "FLY", "TELEPORT") }
+Game.save.inventory = { THUNDERBADGE = true }
+ow = pushOW("INDIGO_PLATEAU", 10, 5, "down")
+eq(ow.map.def.tileset, "PLATEAU", "Indigo Plateau outdoor uses PLATEAU tileset")
+local pmIndigo = PartyMenu.new(Game)
+Game.stack:push(pmIndigo)
+frame({ "a" })
+local actsIndigo = submenuActions(pmIndigo)
+check(actsIndigo.fly, "FLY listed on Indigo Plateau outdoor (PLATEAU)")
+check(actsIndigo.escape, "TELEPORT listed on Indigo Plateau outdoor (PLATEAU)")
+popToOW()
+
+ow = pushOW("ROUTE_23", 10, 6, "down")
+eq(ow.map.def.tileset, "PLATEAU", "Route 23 uses PLATEAU tileset")
+local pmR23 = PartyMenu.new(Game)
+Game.stack:push(pmR23)
+frame({ "a" })
+check(submenuActions(pmR23).fly, "FLY listed on Route 23 (PLATEAU)")
+popToOW()
+
+-- Indoors at the lobby still blocks FLY/TELEPORT (MART tileset)
+ow = pushOW("INDIGO_PLATEAU_LOBBY", 7, 8, "down")
+check(ow.map.def.tileset ~= "OVERWORLD" and ow.map.def.tileset ~= "PLATEAU",
+      "Indigo lobby is not an outside tileset")
+local pmLobby = PartyMenu.new(Game)
+Game.stack:push(pmLobby)
+frame({ "a" })
+local actsLobby = submenuActions(pmLobby)
+check(not actsLobby.fly, "FLY omitted inside Indigo Plateau lobby")
+check(not actsLobby.escape, "TELEPORT omitted inside Indigo Plateau lobby")
+popToOW()
+
+-- restore fainted field-move mon for the STRENGTH/SURF cases below
+Game.save.party = { fainted }
+Game.save.inventory = {
+  THUNDERBADGE = true, CASCADEBADGE = true,
+  RAINBOWBADGE = true, SOULBADGE = true,
+}
+
 -- STRENGTH activation from a fainted user (name text + strengthActive)
 ow = pushOW("SEAFOAM_ISLANDS_1F", 17, 10, "right")
 clearCaptured()

tests/parity_bike_walk_anim.lua

@@ -0,0 +1,97 @@
+-- Regression: bike / desynced walk steps must not flash stand on land (issue #82).
+--
+-- walkPhase used to return 0 whenever moving was false.  A step clears
+-- moving on its final FixedStep tick, so the draw after landing snapped
+-- to stand even when animClock was mid walk-cycle.  Bike steps are 8
+-- frames, so they land at animClock % 16 == 8 (walk) every tile — always
+-- stuttery.  Walking after a bike ride inherits a desynced animClock and
+-- hit the same stand flash "sometimes."
+--
+-- Self-contained; run via `luajit tests/parity_bike_walk_anim.lua`.
+package.path = "./?.lua;./?/init.lua;" .. package.path
+if not _G.love then _G.love = require("tests.love_stub") end
+
+local Data = require("src.core.Data")
+if not (Data.maps and Data.maps.PALLET_TOWN) then Data:load() end
+
+local Player = require("src.world.Player")
+local S = require("tests.harness").suite("parity bike walk anim")
+local check, eq = S.check, S.eq
+
+local function makePlayer(onBike)
+  local p = Player.new(Data, 5, 5, "down")
+  p.onBike = onBike
+  if onBike then
+    p.stepFramesCur = p.bikeStepFrames or 8
+  else
+    p.stepFramesCur = p.stepFrames or 16
+  end
+  p.animClock = 0
+  return p
+end
+
+local function startStep(p)
+  p.moving = true
+  p.progress = 0
+  p.targetX, p.targetY = p.cellX, p.cellY + 1
+end
+
+-- --- bike: every land frame mid-cycle must stay walk ---
+local bike = makePlayer(true)
+local landPhases = {}
+for tile = 1, 4 do
+  startStep(bike)
+  local stepLen = bike.stepFramesCur
+  for _ = 1, stepLen do
+    local done = bike:update()
+    if done then
+      landPhases[#landPhases + 1] = bike:walkPhase()
+      eq(bike.moving, false, "bike step clears moving on land")
+      check(bike.stepLanded, "bike land latches stepLanded for draw")
+    end
+  end
+end
+-- lands at animClock 8, 16, 24, 32 → %16 = 8, 0, 8, 0
+-- walk band is 4..11, so lands at 8 must be phase 1; at 0 must be phase 0
+eq(landPhases[1], 1, "bike land at animClock%16==8 keeps walk pose")
+eq(landPhases[2], 0, "bike land at animClock%16==0 is stand (in-band)")
+eq(landPhases[3], 1, "bike land at animClock%16==8 keeps walk pose again")
+eq(landPhases[4], 0, "bike land at animClock%16==0 is stand again")
+
+-- continuous bike phases across two tiles: no forced stand in the walk band
+bike = makePlayer(true)
+local phases = {}
+for _ = 1, 2 do
+  startStep(bike)
+  for _ = 1, bike.stepFramesCur do
+    bike:update()
+    phases[#phases + 1] = bike:walkPhase()
+  end
+end
+-- frames 4..11 of animClock are walk; across 16 ticks that is indices 4..11
+for i = 4, 11 do
+  eq(phases[i], 1, "bike continuous walk band has no stand flash at " .. i)
+end
+
+-- idle after land: next update drops the latch → stand
+bike = makePlayer(true)
+startStep(bike)
+for _ = 1, bike.stepFramesCur do bike:update() end
+eq(bike:walkPhase(), 1, "latched land frame still walk")
+bike:update()
+eq(bike.stepLanded, false, "idle update clears stepLanded")
+eq(bike:walkPhase(), 0, "truly idle is stand")
+
+-- --- walk after desynced animClock (post-bike): land must not force stand ---
+local walk = makePlayer(false)
+walk.animClock = 8 -- leftover from a bike half-cycle
+startStep(walk)
+local lastPhase
+for _ = 1, walk.stepFramesCur do
+  walk:update()
+  lastPhase = walk:walkPhase()
+end
+eq(walk.animClock % 16, 8, "desynced walk lands mid walk-cycle")
+eq(lastPhase, 1, "desynced walk land keeps walk pose (no post-bike stutter)")
+
+S.finish()

tests/parity_gbcfx.lua

@@ -80,5 +80,46 @@ check(drawn and drawn[1] == canvas and drawn[2] == 0 and drawn[3] == 0,
 
 GBCFX.setLevel(0)
 
+-- issue #136: Android/iOS refuse GBC FX (shader soft-bricks the APK)
+check(GBCFX.isSupported(), "desktop / headless stub supports GBC FX")
+local prevSystem = love.system
+love.system = { getOS = function() return "Android" end }
+check(not GBCFX.isSupported(), "Android reports GBC FX unsupported")
+GBCFX.setLevel(3)
+eq(GBCFX.level, 0, "setLevel forces OFF on Android")
+eq(GBCFX.cycle(), 0, "cycle stays OFF on Android")
+local opts = { gbcfx = 4 }
+check(GBCFX.applyOptions(opts) == true,
+      "applyOptions reports a cleared persisted level on Android")
+eq(opts.gbcfx, 0, "applyOptions clears opts.gbcfx on Android")
+eq(GBCFX.level, 0, "applyOptions leaves level OFF on Android")
+check(not GBCFX.active(), "active() is false on Android")
+eq(GBCFX.shader(), nil, "shader() is nil on Android")
+love.system = { getOS = function() return "iOS" end }
+check(not GBCFX.isSupported(), "iOS reports GBC FX unsupported")
+love.system = prevSystem
+check(GBCFX.isSupported(), "support restores when OS stub is removed")
+-- desktop path still applies a level after leaving the mobile gate
+GBCFX.applyOptions({ gbcfx = 2 })
+eq(GBCFX.level, 2, "applyOptions still sets levels on desktop")
+GBCFX.setLevel(0)
+
+-- Options menu hides the GBC FX row on Android
+local OptionsMenu = require("src.ui.OptionsMenu")
+love.system = { getOS = function() return "Android" end }
+local om = OptionsMenu.new({
+  data = { rulesets = {}, constants = {} },
+  save = { options = {} },
+  stack = { pop = function() end },
+  input = { wasPressed = function() return false end },
+  modStatus = { available = {} },
+})
+local hasGbc = false
+for _, row in ipairs(om.rows) do
+  if row.id == "gbcfx" then hasGbc = true end
+end
+check(not hasGbc, "Options menu omits GBC FX on Android")
+love.system = prevSystem
+
 -- === summary ===
 S.finish()

tests/parity_move_swap.lua

@@ -0,0 +1,129 @@
+-- Parity / regression for #73: Gen 1 fight-menu SELECT reorders moves.
+--
+-- Select marks a slot, move the cursor, Select (or A) swaps. Defaults:
+-- Tab / either Shift / gamepad Back. Self-contained; also picked up by
+-- tests/run_tests.lua's parity_* glob.
+package.path = "./?.lua;./?/init.lua;" .. package.path
+if not _G.love then _G.love = require("tests.love_stub") end
+
+local Data = require("src.core.Data")
+if not (Data.pokemon and Data.pokemon.RATTATA) then Data:load() end
+local TypeChart = require("src.battle.TypeChart")
+TypeChart.load(Data)
+
+local Pokemon = require("src.pokemon.Pokemon")
+local BattleState = require("src.battle.BattleState")
+local Input = require("src.core.Input")
+local S = require("tests.harness").suite("parity move swap")
+local check, eq = S.check, S.eq
+
+local function freshGame()
+  local mon = Pokemon.new(Data, "NIDORAN_M", 8)
+  mon.moves = {
+    { id = "TACKLE", pp = 35 },
+    { id = "LEER", pp = 30 },
+    { id = "HORN_ATTACK", pp = 25 },
+    { id = "POISON_STING", pp = 35 },
+  }
+  return {
+    data = Data,
+    input = Input,
+    save = {
+      party = { mon },
+      player = { name = "RED" },
+      inventory = {},
+      options = {},
+      pokedex = { seen = {}, owned = {} },
+      flags = {},
+      money = 0,
+    },
+    stack = { push = function() end, pop = function() end, top = function() end },
+  }
+end
+
+local function tapKey(battle, key)
+  Input:keypressed(key)
+  Input:step()
+  battle:update(0)
+  Input:keyreleased(key)
+end
+
+local function tapPad(battle, button)
+  Input:gamepadpressed(nil, button)
+  Input:step()
+  battle:update(0)
+  Input:gamepadreleased(nil, button)
+end
+
+-- Default Select sources all edge the logical select button.
+do
+  Input:init()
+  for _, key in ipairs({ "tab", "rshift", "lshift" }) do
+    Input:reset()
+    Input:keypressed(key)
+    Input:step()
+    check(Input:wasPressed("select"), key .. " maps to select")
+  end
+  Input:reset()
+  Input:gamepadpressed(nil, "back")
+  Input:step()
+  check(Input:wasPressed("select"), "gamepad back maps to select")
+end
+
+-- Fight menu: Select, move, Select swaps slots 1 and 2.
+do
+  Input:init()
+  local game = freshGame()
+  local battle = BattleState.newWild(game, "PIDGEY", 5)
+  battle.phase = "moveSelect"
+  battle.moveIndex = 1
+  battle.moveSwapIndex = nil
+  local a = battle.player.curMoves[1].id
+  local b = battle.player.curMoves[2].id
+  tapKey(battle, "tab")
+  eq(battle.moveSwapIndex, 1, "first Select marks the current slot")
+  tapKey(battle, "down")
+  eq(battle.moveIndex, 2, "cursor moved to slot 2")
+  tapKey(battle, "tab")
+  check(battle.moveSwapIndex == nil, "second Select clears the mark")
+  eq(battle.player.curMoves[1].id, b, "slot 1 holds the former slot 2 move")
+  eq(battle.player.curMoves[2].id, a, "slot 2 holds the former slot 1 move")
+  eq(battle.player.mon.moves[1].id, b, "party moves table stays in sync")
+end
+
+-- Same reorder via gamepad Back (SDL "back" = controller Select/View).
+do
+  Input:init()
+  local game = freshGame()
+  local battle = BattleState.newWild(game, "PIDGEY", 5)
+  battle.phase = "moveSelect"
+  battle.moveIndex = 1
+  battle.moveSwapIndex = nil
+  local a = battle.player.curMoves[1].id
+  local b = battle.player.curMoves[2].id
+  tapPad(battle, "back")
+  tapPad(battle, "dpdown")
+  tapPad(battle, "back")
+  eq(battle.player.curMoves[1].id, b, "pad Select swaps slot 1")
+  eq(battle.player.curMoves[2].id, a, "pad Select swaps slot 2")
+end
+
+-- A confirms a pending swap (bag-style), without starting the turn.
+do
+  Input:init()
+  local game = freshGame()
+  local battle = BattleState.newWild(game, "PIDGEY", 5)
+  battle.phase = "moveSelect"
+  battle.moveIndex = 1
+  battle.moveSwapIndex = nil
+  local a = battle.player.curMoves[1].id
+  local b = battle.player.curMoves[2].id
+  tapKey(battle, "tab")
+  tapKey(battle, "down")
+  tapKey(battle, "z") -- A
+  eq(battle.phase, "moveSelect", "A completes a pending swap without attacking")
+  eq(battle.player.curMoves[1].id, b, "A-confirm swapped slot 1")
+  eq(battle.player.curMoves[2].id, a, "A-confirm swapped slot 2")
+end
+
+S.finish()

tests/parity_tower_heal_pad.lua

@@ -0,0 +1,98 @@
+-- Parity test: Pokemon Tower 5F purified-zone heal pad (#81).
+--
+-- pokered scripts/PokemonTower5F.asm PokemonTower5FDefaultScript:
+--   coords (10,8)/(11,8)/(10,9)/(11,9); CheckAndSetEvent
+--   EVENT_IN_PURIFIED_ZONE so the heal fires once until the player
+--   leaves; HealParty -> GBFadeOutToWhite -> Delay3 x2 ->
+--   GBFadeInFromWhite -> _PokemonTower5FPurifiedZoneText (no heal jingle).
+--
+-- Self-contained; run via `luajit tests/parity_tower_heal_pad.lua`.
+package.path = "./?.lua;./?/init.lua;" .. package.path
+if not _G.love then _G.love = require("tests.love_stub") end
+local S = require("tests.harness").suite("parity tower heal pad")
+local check, eq = S.check, S.eq
+
+local M = dofile("data/scripts/story3.lua")
+local tower = M.POKEMON_TOWER_5F
+check(tower ~= nil and type(tower.onStep) == "function",
+      "POKEMON_TOWER_5F has an onStep heal-pad trigger")
+
+local function cmds(rows)
+  local out = {}
+  for _, row in ipairs(rows) do out[#out + 1] = row[1] end
+  return out
+end
+
+local function gameWith(flags)
+  return { save = { flags = flags or {} } }
+end
+
+local function owWith()
+  local ran = {}
+  return {
+    runner = {
+      isRunning = function() return false end,
+      run = function(_, rows) ran[#ran + 1] = rows end,
+    },
+  }, ran
+end
+
+-- ---- 1. pad coords + leave clears latch --------------------------------
+do
+  local game = gameWith()
+  local ow, ran = owWith()
+  check(not tower.onStep(game, ow, 9, 8), "off-pad X does not heal")
+  check(not tower.onStep(game, ow, 10, 7), "off-pad Y does not heal")
+  eq(#ran, 0, "no script off the pad")
+end
+
+do
+  local game = gameWith()
+  local ow, ran = owWith()
+  check(tower.onStep(game, ow, 10, 8), "first step on (10,8) heals")
+  check(game.save.flags.EVENT_IN_PURIFIED_ZONE, "latches EVENT_IN_PURIFIED_ZONE")
+  eq(#ran, 1, "heal script runs once")
+
+  check(tower.onStep(game, ow, 11, 9),
+        "staying on the pad still consumes the step (BIT_NO_BATTLES)")
+  eq(#ran, 1, "heal does not re-fire while still on the pad")
+
+  check(not tower.onStep(game, ow, 12, 9), "stepping off clears and returns false")
+  check(not game.save.flags.EVENT_IN_PURIFIED_ZONE,
+        "EVENT_IN_PURIFIED_ZONE resets off the pad")
+
+  check(tower.onStep(game, ow, 11, 8), "re-entering the pad heals again")
+  eq(#ran, 2, "a fresh visit runs the heal script again")
+end
+
+-- ---- 2. all four pad tiles trigger -------------------------------------
+for _, cell in ipairs({ { 10, 8 }, { 11, 8 }, { 10, 9 }, { 11, 9 } }) do
+  local game = gameWith()
+  local ow, ran = owWith()
+  check(tower.onStep(game, ow, cell[1], cell[2]),
+        ("pad tile (%d,%d) heals"):format(cell[1], cell[2]))
+  eq(#ran, 1, ("pad tile (%d,%d) queued a script"):format(cell[1], cell[2]))
+end
+
+-- ---- 3. heal sequence matches pokered order ----------------------------
+do
+  local game = gameWith()
+  local ow, ran = owWith()
+  tower.onStep(game, ow, 10, 9)
+  local rows = ran[1]
+  check(rows ~= nil, "heal rows captured")
+  local sequence = table.concat(cmds(rows), ",")
+  eq(sequence, "heal_party,fade,wait,wait,fade,show_text",
+     "Tower pad sequence is heal → fade out → Delay3×2 → fade in → text")
+  eq(rows[2][3], "white", "fades out to white")
+  eq(rows[3][2], 3, "first Delay3 is 3 frames")
+  eq(rows[4][2], 3, "second Delay3 is 3 frames")
+  eq(rows[5][3], "white", "fades in from white")
+  eq(rows[6][2], "_PokemonTower5FPurifiedZoneText",
+     "shows the purified-zone text")
+  for _, row in ipairs(rows) do
+    check(row[1] ~= "play_once", "no Music_PkmnHealed on the Tower pad")
+  end
+end
+
+S.finish()

tests/parity_trainer_sight.lua

@@ -169,4 +169,53 @@ do
         "tile behind the trainer never engages (CheckPlayerIsInFrontOfSprite)")
 end
 
+-- === (4) Route 9 Bug Catcher: 4-tiles-north screen Y $fc quirk ===
+-- Object 7 = SPRITE_YOUNGSTER at (22,2), STAY DOWN, OPP_BUG_CATCHER
+-- (data/maps/objects/Route9.asm); header range 4 (Route9TrainerHeader6).
+-- A ledge sits on (22,5); the walkable tile below it is (22,6) at cell
+-- distance 4.  Cell math would engage, but pokered's unsigned screen-Y
+-- distance with SPRITESTATEDATA1_YPIXELS=$fc is $c0 > range<<4 ($40), so
+-- the trainer must not challenge through that ledge (GitHub #76).
+local ROUTE9_BUG_CATCHER = 7
+
+local function freshRoute9(px, py, facing)
+  while Game.stack:top() do Game.stack:pop() end
+  Game.save = SaveData.newGame()
+  Input:init()
+  OW.engaging = false
+  OW.emote = nil
+  Game.stack:push(OW, "ROUTE_9", px, py, facing)
+  local ow = Game.stack:top()
+  local trainer
+  for _, npc in ipairs(ow.npcs) do
+    if npc.def.index == ROUTE9_BUG_CATCHER then trainer = npc end
+  end
+  return ow, trainer
+end
+
+do
+  local ow, trainer = freshRoute9(22, 6, "up")
+  check(trainer ~= nil and trainer.cellX == 22 and trainer.cellY == 2,
+        "Route 9 Bug Catcher stands at (22,2)")
+  eq(trainer.facing, "down", "Bug Catcher faces down (STAY DOWN)")
+  local header = Data:trainerHeader("Route9", ROUTE9_BUG_CATCHER)
+  eq(header and header.range, 4, "Bug Catcher sight range is 4")
+
+  for _ = 1, 10 do frame(ow) end
+  check(not ow.engaging,
+        "distance 4 south of DOWN trainer: no engage (screen Y $fc quirk)")
+
+  -- same plateau, still in pixel range: distance 2 and 3 must engage
+  local ow2, t2 = freshRoute9(22, 4, "up")
+  local guard = 0
+  while not ow2.engaging and guard < 10 do guard = guard + 1; frame(ow2) end
+  check(ow2.engaging and t2.cellY == 2,
+        "distance 2 on the upper plateau still engages")
+
+  local ow3 = freshRoute9(22, 3, "up")
+  guard = 0
+  while not ow3.engaging and guard < 10 do guard = guard + 1; frame(ow3) end
+  check(ow3.engaging, "distance 3 on the upper plateau still engages")
+end
+
 S.finish()

tests/run_tests.lua

@@ -1072,6 +1072,81 @@ do
   mh:performMove(mh.player, mh.enemy, { id = "DOUBLESLAP", pp = 10 })
   check(hasText(mh, "Hit the enemy\n5 times!"),
         "player multi-hit uses _MultiHitText")
+  -- #85: multi-hit replays PlayMoveAnimation per strike (pokered
+  -- GetPlayerAnimationType loop), interleaved with each HP drain
+  do
+    local anims, seq = 0, {}
+    for _, r in ipairs(mh.queue) do
+      if r.anim == "DOUBLESLAP" then
+        anims = anims + 1
+        seq[#seq + 1] = "anim"
+      elseif r.drain then
+        seq[#seq + 1] = "drain"
+      end
+    end
+    eq(anims, 5, "multi-hit queues the move animation once per hit")
+    eq(table.concat(seq, ","),
+       "anim,drain,anim,drain,anim,drain,anim,drain,anim,drain",
+       "multi-hit interleaves anim + drain per strike")
+    for _, r in ipairs(mh.queue) do
+      if r.anim == "DOUBLESLAP" then
+        check(r.hit ~= nil, "each multi-hit anim carries hit blink/sfx")
+      end
+    end
+  end
+  -- #85: crit / effectiveness reprint each strike (.moveDidNotMiss
+  -- before the GetPlayerAnimationType loop-back).  DOUBLE_KICK is a
+  -- fixed 2-hit Fighting move -- SE vs Normal SNORLAX.
+  do
+    local function countText(b, s)
+      local n = 0
+      for _, it in ipairs(b.queue) do
+        if it.text and it.text:find(s, 1, true) then n = n + 1 end
+      end
+      return n
+    end
+    Game.save.party = { Pokemon.new(Data, "BULBASAUR", 20) }
+    local mhk = BattleState.newWild(Game, "SNORLAX", 40)
+    mhk.rng = mkseq({ 0, 255, 255 }) -- hit, no crit, max roll
+    mhk:performMove(mhk.player, mhk.enemy, { id = "DOUBLE_KICK", pp = 10 })
+    eq(countText(mhk, "It's super\neffective!"), 2,
+       "multi-hit prints effectiveness once per strike")
+    local seq = {}
+    for _, r in ipairs(mhk.queue) do
+      if r.anim == "DOUBLE_KICK" then seq[#seq + 1] = "anim"
+      elseif r.drain then seq[#seq + 1] = "drain"
+      elseif r.text == "It's super\neffective!" then seq[#seq + 1] = "se"
+      elseif r.text and r.text:find("times!", 1, true) then seq[#seq + 1] = "count"
+      end
+    end
+    eq(table.concat(seq, ","), "anim,drain,se,anim,drain,se,count",
+       "multi-hit queues SE text between strikes, count after")
+
+    local Runtime = require("src.mods.Runtime")
+    local Hooks = require("src.mods.Hooks")
+    local Events = require("src.mods.Events")
+    local savedE, savedH = Runtime.events, Runtime.hooks
+    local hooks = Hooks.new()
+    Runtime.install(Events.new(), hooks)
+    local unsub = hooks:wrap("battle.crit", function() return true end)
+    local mhc = BattleState.newWild(Game, "SNORLAX", 40)
+    mhc.rng = mkseq({ 0, 255 }) -- acc, damage; crit from the hook
+    mhc:performMove(mhc.player, mhc.enemy, { id = "DOUBLE_KICK", pp = 10 })
+    eq(countText(mhc, "Critical hit!"), 2,
+       "multi-hit prints Critical hit! once per strike")
+    local cseq = {}
+    for _, r in ipairs(mhc.queue) do
+      if r.anim == "DOUBLE_KICK" then cseq[#cseq + 1] = "anim"
+      elseif r.drain then cseq[#cseq + 1] = "drain"
+      elseif r.text == "Critical hit!" then cseq[#cseq + 1] = "crit"
+      elseif r.text == "It's super\neffective!" then cseq[#cseq + 1] = "se"
+      end
+    end
+    eq(table.concat(cseq, ","), "anim,drain,crit,se,anim,drain,crit,se",
+       "crit then effectiveness follow each multi-hit drain")
+    unsub()
+    Runtime.install(savedE, savedH)
+  end
   Game.save.party = { Pokemon.new(Data, "SNORLAX", 30) }
   local mh2 = BattleState.newWild(Game, "RATTATA", 5)
   mh2.rng = mkseq({ 7, 0, 255, 255 })
@@ -1498,6 +1573,13 @@ do
   eq(back.options.colors, "og", "options.lua round-trips colors")
   eq(back.options.tilt, 2, "options.lua round-trips tilt")
   eq(back.options.gbcfx, 3, "options.lua round-trips gbcfx")
+  -- zoom / voidFill ride the same options.lua path when present
+  rep.options.zoom = -2
+  rep.options.voidFill = "water"
+  SD.saveOptions(rep.options)
+  local optBack = SD.loadOptions()
+  eq(optBack.zoom, -2, "options.lua round-trips zoom")
+  eq(optBack.voidFill, "water", "options.lua round-trips voidFill")
   local origOpts, loadedOpts = rep.options, back.options
   rep.options, back.options = nil, nil
   local same, where = deepEq(rep, back, "save")
@@ -1645,6 +1727,16 @@ do
   ow.runner = { isRunning = function() return true end }
   check(not Zoom.gateOK(ow, ow), "gate closed while a script runs")
   Zoom.reset()
+
+  -- cycle wraps survey → … → close-up → survey; labels track offset
+  eq(Zoom.offsetLabel(0), "FIT", "zoom label FIT at offset 0")
+  eq(Zoom.offsetLabel(-2), "OUT2", "zoom label OUT for negative offset")
+  eq(Zoom.offsetLabel(3), "IN3", "zoom label IN for positive offset")
+  Zoom.offset = S -- max close-up
+  eq(Zoom.cycle(S), 1 - S, "zoom cycle wraps from max in to full survey")
+  Zoom.applyOptions({ zoom = -1 })
+  eq(Zoom.offset, -1, "applyOptions restores saved zoom offset")
+  Zoom.reset()
 end
 
 -- ---------------------------------------------------------------- zoom camera
@@ -2232,6 +2324,8 @@ do
   eq(og.save.options.colors, "gbc", "new saves default COLORS to GBC")
   eq(og.save.options.tilt, 0, "new saves default TILT to OFF")
   eq(og.save.options.gbcfx, 0, "new saves default GBC FX to OFF")
+  eq(og.save.options.zoom, 0, "new saves default ZOOM to FIT")
+  eq(og.save.options.voidFill, "trees", "new saves default VOID FILL to TREES")
   eq(og.save.options.videoMode, "windowed",
      "new saves default VIDEO MODE to WINDOWED")
   eq(om.scroll, 0, "options viewport starts at the top")
@@ -2270,7 +2364,25 @@ do
   for _ = 1, 4 do press("a") end
   eq(og.save.options.gbcfx, 0, "GBC FX wraps back to OFF")
   press("down")
-  eq(om.index, 11, "cursor reaches VIDEO MODE")
+  eq(om.index, 11, "cursor reaches ZOOM")
+  local ZoomOpt = require("src.render.Zoom")
+  press("a")
+  eq(og.save.options.zoom, 1, "A cycles ZOOM to IN1")
+  eq(ZoomOpt.offset, 1, "Zoom.offset tracks ZOOM option")
+  press("left")
+  eq(og.save.options.zoom, 0, "left steps ZOOM back to FIT")
+  press("down")
+  eq(om.index, 12, "cursor reaches VOID FILL")
+  local TR = require("src.render.TileRenderer")
+  press("a")
+  eq(og.save.options.voidFill, "water", "A cycles VOID FILL to WATER")
+  eq(TR.voidFill, "water", "TileRenderer.voidFill tracks VOID FILL option")
+  press("a")
+  eq(og.save.options.voidFill, "black", "A cycles VOID FILL to BLACK")
+  press("a")
+  eq(og.save.options.voidFill, "trees", "VOID FILL wraps back to TREES")
+  press("down")
+  eq(om.index, 13, "cursor reaches VIDEO MODE")
   press("a")
   eq(og.save.options.videoMode, "borderless",
      "A cycles VIDEO MODE to BORDERLESS")
@@ -2278,7 +2390,7 @@ do
   eq(og.save.options.videoMode, "windowed",
      "VIDEO MODE wraps back to WINDOWED")
   press("down")
-  eq(om.index, 12, "cursor reaches MAX FPS")
+  eq(om.index, 14, "cursor reaches MAX FPS")
   press("a")
   eq(og.save.options.fpsCap, 75, "A cycles MAX FPS up from 60 to 75")
   eq(FrameCap.current, 75, "the live render cap tracks the MAX FPS option")
@@ -2287,7 +2399,7 @@ do
   for _ = 1, #FrameCap.STEPS - 1 do press("a") end
   eq(og.save.options.fpsCap, 60, "MAX FPS wraps back to 60")
   press("down")
-  eq(om.index, 13, "cursor reaches GAME SPEED")
+  eq(om.index, 15, "cursor reaches GAME SPEED")
   press("a")
   eq(og.save.options.speed, 2, "A cycles GAME SPEED to 2X")
   -- Driven by the level list rather than a literal press count: adding a
@@ -2296,25 +2408,27 @@ do
   for _ = 1, #GameSpeed.LEVELS - 1 do press("a") end
   eq(og.save.options.speed, 1, "GAME SPEED wraps back to NORMAL")
   press("down")
-  eq(om.index, 14, "cursor reaches MODS")
+  eq(om.index, 16, "cursor reaches MODS")
   press("down")
-  eq(om.index, 15, "cursor reaches CONTROLS")
+  eq(om.index, 17, "cursor reaches CONTROLS")
   press("down")
-  eq(om.index, 16, "CANCEL stays the fixed final row")
-  eq(om.scroll, 11, "CANCEL keeps the last option boxes on screen")
+  eq(om.index, 18, "CANCEL stays the fixed final row")
+  eq(om.scroll, 13, "CANCEL keeps the last option boxes on screen")
   om:draw() -- smoke: scrolled layout draws under the headless stub
   press("a")
   check(popped, "A on CANCEL closes the options menu")
   local om2 = OptionsMenu.new(og)
   OInput.pressed = { up = true }; om2:update(1 / 60); OInput.pressed = {}
-  eq(om2.index, 16, "up from the top wraps to CANCEL")
-  eq(om2.scroll, 11, "wrapping to CANCEL scrolls to the tail")
+  eq(om2.index, 18, "up from the top wraps to CANCEL")
+  eq(om2.scroll, 13, "wrapping to CANCEL scrolls to the tail")
   -- headless-safe: no love.audio, setters only update internal state
   require("src.core.Music").applyOptions(og.save.options)
   require("src.core.Sound").applyOptions(og.save.options)
   PaletteFX.applyOptions(og.save.options)
   Tilt.applyOptions(og.save.options)
   GBCFX.applyOptions(og.save.options)
+  require("src.render.Zoom").applyOptions(og.save.options)
+  require("src.render.TileRenderer").applyOptions(og.save.options)
   VideoMode.applyOptions(og.save.options)
 end
 end
@@ -2611,22 +2725,67 @@ do
                     tostring(c[3]), tostring(c[4])))
   end
 end
+
+-- == issue #4: ledge hop countdown is fixed-step, not draw-rate ==
+-- hopFrames used to decrement inside Player:draw, so >59fps ended the
+-- arc early and <59fps stretched it. Countdown belongs in update().
+do
+  local Player = require("src.world.Player")
+  local p = Player.new(Data, 5, 6, "down")
+  p.hopFrames, p.hopTotal = 32, 32
+  p:draw(0, 0)
+  p:draw(0, 0)
+  p:draw(0, 0)
+  eq(p.hopFrames, 32, "draw does not consume hopFrames")
+  for _ = 1, 10 do p:update() end
+  eq(p.hopFrames, 22, "ten fixed updates consume ten hopFrames")
+  for _ = 1, 22 do p:update() end
+  eq(p.hopFrames, 0, "hop expires after hopTotal fixed updates")
+  p:update()
+  eq(p.hopFrames, 0, "hopFrames stays at 0 once expired")
+end
+
+-- == issue #4: tile anim tick accumulates wall-clock into 60Hz steps ==
+do
+  local TileRenderer = require("src.render.TileRenderer")
+  TileRenderer.setSpinning(true)
+  local before = TileRenderer.spinBlurActive()
+  for _ = 1, 8 do TileRenderer.tick(1 / 60) end
+  check(before ~= TileRenderer.spinBlurActive(),
+        "tick(1/60) advances water/spinner clock at fixed 60Hz")
+  local mid = TileRenderer.spinBlurActive()
+  TileRenderer.tick(1 / 120)
+  eq(TileRenderer.spinBlurActive(), mid,
+     "sub-frame dt does not advance the tile anim clock")
+  TileRenderer.tick(1 / 120)
+  -- second half-frame completes one step; phase may or may not flip
+  -- (8-tick blur period), but the clock must have accepted the step
+  TileRenderer.setSpinning(false)
+end
 end
 
 -- ================= BUGS.md batch: border-tree =================
 do
--- ---------------------------------------------------------------- border fill (tree wall)
+-- ---------------------------------------------------------------- border fill (tree wall / VOID FILL)
 local TileRenderer = require("src.render.TileRenderer")
--- OVERWORLD maps fill beyond-edge space with the solid tree wall $0F
--- (ViridianCity/CeruleanCity/CeladonCity border_block: four regular-tree
--- metatiles); per-map borders like Pallet's all-grass $0B (the
--- CutTreeBlockSwaps $0B->$0A block) only apply to other tilesets
+-- OVERWORLD maps fill beyond-edge space from VOID FILL (default trees $0F);
+-- per-map borders like Pallet's all-grass $0B only apply to other tilesets
+TileRenderer.setVoidFill("trees")
 eq(TileRenderer.borderBlockFor({ def = { tileset = "OVERWORLD", borderBlock = 33 } }), 0x0F,
    "OVERWORLD border fill uses the tree wall block")
 eq(TileRenderer.borderBlockFor({ def = { tileset = "HOUSE", borderBlock = 7 } }), 7,
    "interior border fill keeps the map's border block")
 eq(TileRenderer.borderBlockFor({ def = Data.maps.PALLET_TOWN }), 0x0F,
    "Pallet Town border fill is trees, not its all-grass border block")
+TileRenderer.setVoidFill("water")
+eq(TileRenderer.borderBlockFor({ def = { tileset = "OVERWORLD", borderBlock = 33 } }), 0x43,
+   "VOID FILL water uses the solid water border block")
+TileRenderer.setVoidFill("black")
+eq(TileRenderer.borderBlockFor({ def = { tileset = "OVERWORLD", borderBlock = 33 } }), false,
+   "VOID FILL black disables the tiled border block")
+eq(TileRenderer.borderBlockFor({ def = { tileset = "HOUSE", borderBlock = 7 } }), 7,
+   "VOID FILL does not change interior borders")
+TileRenderer.setVoidFill("trees")
 local treeWallCuttable = false
 for _, swap in ipairs(Data.field.cutTreeSwaps) do
   if swap.before == 0x0F then treeWallCuttable = true end