CLOSES #1211, CLOSES #1228, CLOSES #1229, CLOSES #1232, CLOSES #1251, CLOSES #1265, CLOSES #1267, CLOSES #1276, CLOSES #1279, CLOSES #1282, CLOSES #1293, CLOSES #1296, CLOSES #1303, CLOSES #1329, CLOSES #1338, CLOSES #1341, CLOSES #1343, CLOSES #1344, CLOSES #1368, CLOSES #1385, CLOSES #1388, CLOSES #1389, CLOSES #1391

src/ui/DexEntryMenu.lua

@@ -14,6 +14,7 @@
 
 local Font = require("src.render.Font")
 local Strings = require("src.core.Strings")
+local Theme = require("src.ui.Theme")
 
 local DexEntryMenu = {}
 DexEntryMenu.__index = DexEntryMenu
@@ -36,6 +37,62 @@ local function resolveArgs(speciesOrOpts)
   return speciesOrOpts, false
 end
 
+local function ownedFor(game, def, forceOwned)
+  return forceOwned
+    or (game.save.pokedex and game.save.pokedex.owned[def.id]) or false
+end
+
+-- home/text.asm:245 (<PAGE>), home/text.asm:204 (<DEXEND>)
+local function descPages(game, def, forceOwned)
+  local e = def.dexEntry or {}
+  local owned = ownedFor(game, def, forceOwned)
+  local text = owned and e.text and game.data.text[e.text] or nil
+  if not text then return nil end
+  local pages = {}
+  for chunk in (text .. "\f"):gmatch("(.-)\f") do
+    local lines = {}
+    for line in (chunk:gsub("\v", "\n") .. "\n"):gmatch("(.-)\n") do
+      lines[#lines + 1] = line
+    end
+    while #lines > 0 and lines[#lines] == "" do table.remove(lines) end
+    if #lines > 0 then pages[#pages + 1] = lines end
+  end
+  if #pages == 0 then return nil end
+  local last = pages[#pages]
+  last[#last] = last[#last] .. "."
+  return pages
+end
+
+-- engine/gfx/load_pokedex_tiles.asm: gfx/pokedex/pokedex.png, codes $60..$71
+local frameCache = {}
+local function frameSheet(game)
+  local fx = game.data.field and game.data.field.overworldFx
+  local def = fx and fx.pokedexFrame
+  local path = def and def.path
+  if not path then return nil end
+  local hit = frameCache[path]
+  if hit ~= nil then return hit or nil end
+  local ok, img = pcall(love.graphics.newImage, path)
+  if not ok or not img then
+    frameCache[path] = false
+    return nil
+  end
+  local iw, ih = img:getDimensions()
+  local quads = {}
+  for i = 0, 17 do
+    quads[i] = love.graphics.newQuad((i % 3) * 8,
+                                     math.floor(i / 3) * 8, 8, 8, iw, ih)
+  end
+  frameCache[path] = { img = img, quads = quads }
+  return frameCache[path]
+end
+
+-- engine/menus/pokedex.asm:601
+local DIVIDER = {
+  0x68, 0x69, 0x6B, 0x69, 0x6B, 0x69, 0x6B, 0x69, 0x6B, 0x6B,
+  0x6B, 0x6B, 0x69, 0x6B, 0x69, 0x6B, 0x69, 0x6B, 0x69, 0x6A,
+}
+
 function DexEntryMenu.new(game, speciesOrOpts, onDone)
   local species, forceOwned = resolveArgs(speciesOrOpts)
   local self = setmetatable({ game = game, forceOwned = forceOwned,
@@ -43,13 +100,14 @@ function DexEntryMenu.new(game, speciesOrOpts, onDone)
   self.def = game.data.pokemon[species]
   local path, trueColor = require("src.pokemon.Sprites").path(
     game.data, species, "front", { kind = "dex" })
-  -- `path and pcall(...)` truncates to one value, so img was always nil and
-  -- every dex page drew without its pic (#307); the guard has to be a
-  -- statement for pcall's second return to survive.
+  -- pcall's second return has to survive the guard (#307)
   local ok, img = false, nil
   if path then ok, img = pcall(love.graphics.newImage, path) end
   self.sprite = ok and img or nil
   self.spriteTrueColor = self.sprite and trueColor or false
+  self.page = 1
+  local pages = descPages(game, self.def, forceOwned)
+  self.pageCount = pages and #pages or 1
   require("src.core.Sound").playCry(game.data, species)
   return self
 end
@@ -57,6 +115,11 @@ end
 function DexEntryMenu:update(dt)
   local input = self.game.input
   if input:wasPressed("a") or input:wasPressed("b") then
+    -- home/text.asm:245
+    if self.page < (self.pageCount or 1) then
+      self.page = self.page + 1
+      return
+    end
     self.game.stack:pop()
     if self.onDone then self.onDone() end
   end
@@ -64,64 +127,87 @@ end
 
 function DexEntryMenu:draw()
   DexEntryMenu.render(self.game, self.def, self.sprite, self.forceOwned,
-                      self.spriteTrueColor)
+                      self.spriteTrueColor, self.page)
 end
 
 -- Static entry-page renderer, shared with the printer stand-in
 -- (src/core/Printer.lua renders the same page into a PNG the way
 -- PrintPokedexEntry rendered it to the Game Boy Printer).
-function DexEntryMenu.render(game, def, sprite, forceOwned, trueColor)
+-- engine/menus/pokedex.asm:399
+function DexEntryMenu.render(game, def, sprite, forceOwned, trueColor, page)
+  page = page or 1
   love.graphics.setColor(1, 1, 1, 1)
   love.graphics.rectangle("fill", 0, 0, 160, 144)
+  local frame = frameSheet(game)
+  if frame then
+    local function tile(code, tx, ty)
+      love.graphics.draw(frame.img, frame.quads[code - 0x60], tx * 8, ty * 8)
+    end
+    -- engine/menus/pokedex.asm:418
+    for tx = 1, 18 do
+      tile(0x64, tx, 0)
+      tile(0x6f, tx, 17)
+    end
+    for ty = 1, 16 do
+      tile(0x66, 0, ty)
+      tile(0x67, 19, ty)
+    end
+    tile(0x63, 0, 0)
+    tile(0x65, 19, 0)
+    tile(0x6c, 0, 17)
+    tile(0x6e, 19, 17)
+    -- engine/menus/pokedex.asm:445
+    for tx = 0, 19 do
+      tile(DIVIDER[tx + 1], tx, 9)
+    end
+  end
   if sprite then
-    local y = math.max(0, 60 - sprite:getHeight())
-    love.graphics.draw(sprite, 8, y)
-    -- a full-color pic has to sit out the SGB recolor, so mark its bounds
-    -- for the unshaded pass (#350).  The printer path leaves trueColor nil:
-    -- it renders to its own PNG canvas, and a mark left behind there would
-    -- bleed into the next real frame.
+    -- engine/menus/pokedex.asm:503, home/pokemon.asm:96 (flipped)
+    local w, h = sprite:getDimensions()
+    local x = 8 + math.floor((8 - w / 8) / 2) * 8
+    local y = 8 + (7 - h / 8) * 8
+    love.graphics.draw(sprite, x + w, y, 0, -1, 1)
+    -- the unshaded pass needs the pic bounds (#350)
     if trueColor then
-      require("src.render.PaletteFX").markTrueColor(8, y, sprite:getDimensions())
+      require("src.render.PaletteFX").markTrueColor(x, y, w, h)
     end
   end
   love.graphics.setColor(0, 0, 0, 1)
-  Font.draw(def.name, 72, 8)
+  -- engine/menus/pokedex.asm:454
+  Font.draw(def.name, 72, 16)
   local e = def.dexEntry or {}
-  -- English R/B prints only the kind string (hlcoord 9,4 PlaceString).
-  -- PokeText ("#"/POKéMON) is an unreferenced JPN leftover in pokedex.asm;
-  -- appending " POKéMON" here clipped longer kinds ("LIZARD POKé").
-  Font.draw(e.kind or "?", 72, 20)
+  -- engine/menus/pokedex.asm:468, kind string only (PokeText is unreferenced)
+  Font.draw(e.kind or "?", 72, 32)
   -- same number width as the list (constants.dexDigits), so a dex past 999
   -- prints the extra digit everywhere at once
   local digits = (game.data.constants or {}).dexDigits or 3
-  Font.draw(Strings("No.") .. ("%0" .. digits .. "d"):format(def.dex or 0), 72, 32)
-  local owned = forceOwned
-    or (game.save.pokedex and game.save.pokedex.owned[def.id])
-  -- height/weight print only once owned, like the description
-  -- (pokedex.asm: "if the pokemon has not been owned, don't print the
-  -- height, weight, or description")
+  -- engine/menus/pokedex.asm:478
+  Font.draw(Strings("No.") .. ("%0" .. digits .. "d"):format(def.dex or 0),
+            16, 64)
+  local owned = ownedFor(game, def, forceOwned)
+  -- engine/menus/pokedex.asm:449, numbers only once owned
   if owned and e.heightFt then
-    -- feet/inches use the dex screen's ′/″ glyphs ("HT  ?′??″" in
-    -- pokedex.asm; the tiles come from gfx/pokedex/pokedex.png via
-    -- engine/gfx/load_pokedex_tiles.asm)
     if e.heightM then
-      Font.draw((Strings("GR. %.1fm", e.heightM):gsub("(%d)%.(%d)", "%1,%2")), 72, 44)
-      Font.draw((Strings("GEW. %.1fkg", e.weightKg or 0):gsub("(%d)%.(%d)", "%1,%2")), 72, 54)
+      Font.draw((Strings("GR. %.1fm", e.heightM):gsub("(%d)%.(%d)", "%1,%2")), 72, 48)
+      Font.draw((Strings("GEW. %.1fkg", e.weightKg or 0):gsub("(%d)%.(%d)", "%1,%2")), 72, 64)
     else
-      Font.draw(Strings("HT %d′%02d″", e.heightFt, e.heightIn or 0), 72, 44)
-      Font.draw(Strings("WT %.1flb", (e.weight or 0) / 10), 72, 54)
+      Font.draw(Strings("HT %d′%02d″", e.heightFt, e.heightIn or 0), 72, 48)
+      Font.draw(Strings("WT %.1flb", (e.weight or 0) / 10), 72, 64)
     end
   end
-  local text = owned and e.text and game.data.text[e.text] or nil
-  local y = 72
-  if text then
-    for line in (text:gsub("\v", "\n"):gsub("\f", "\n") .. "\n"):gmatch("(.-)\n") do
-      if y > 132 then break end
-      Font.draw(line, 8, y)
-      y = y + 10
+  local pages = descPages(game, def, forceOwned)
+  if pages then
+    -- engine/menus/pokedex.asm:568
+    local lines = pages[page] or pages[#pages]
+    for i, line in ipairs(lines) do
+      Font.draw(line, 8, 72 + i * 16)
+    end
+    -- home/text.asm:245
+    if page < #pages then
+      Font.drawCode(Theme.moreArrow, 144, 128)
     end
   else
-    Font.draw(Strings("Data unknown."), 8, y)
+    Font.draw(Strings("Data unknown."), 8, 88)
   end
   love.graphics.setColor(1, 1, 1, 1)
 end

src/ui/LeaguePC.lua

@@ -0,0 +1,112 @@
+-- PKMN LEAGUE hall-of-fame viewer (engine/menus/league_pc.asm:1)
+
+local Font = require("src.render.Font")
+local Strings = require("src.core.Strings")
+local HallOfFame = require("src.ui.HallOfFame")
+
+local LeaguePC = {}
+LeaguePC.__index = LeaguePC
+LeaguePC.isOpaque = true
+
+-- constants/pokemon_data_constants.asm:65
+local CAPACITY = 50
+
+-- SGB: SET_PAL_POKEMON_WHOLE_SCREEN per mon (engine/menus/league_pc.asm:95)
+function LeaguePC:sgbPalettes(game)
+  local P = require("src.render.PaletteFX")
+  local mon = self:currentMon()
+  local c = mon and P.monPal(game.data, mon.species)
+  if c then return { P.whole(c) } end
+  return P.wholeNamed(game.data, "MEWMON")
+end
+
+function LeaguePC.new(game, onDone)
+  local self = setmetatable({}, LeaguePC)
+  self.game = game
+  self.onDone = onDone
+  self.teams = (game.save and game.save.hallOfFame) or {}
+  self.teamIndex = math.max(1, #self.teams - CAPACITY + 1)
+  self.monIndex = 1
+  self.sprites = {}
+  self.spriteTrueColor = {}
+  self:loadMon()
+  return self
+end
+
+function LeaguePC:currentMon()
+  local team = self.teams[self.teamIndex]
+  return team and team[self.monIndex] or nil
+end
+
+function LeaguePC:loadMon()
+  local mon = self:currentMon()
+  if not mon then return end
+  local species = mon.species
+  if self.sprites[species] == nil then
+    local path, trueColor = require("src.pokemon.Sprites").path(
+      self.game.data, species, "front", { kind = "hof" })
+    local ok, img = false, nil
+    if path then ok, img = pcall(love.graphics.newImage, path) end
+    self.sprites[species] = ok and img or false
+    self.spriteTrueColor[species] = (ok and img and trueColor) or false
+  end
+  require("src.core.Sound").playCry(self.game.data, species)
+end
+
+function LeaguePC:close()
+  self.game.stack:pop()
+  if self.onDone then self.onDone() end
+end
+
+function LeaguePC:update(dt)
+  local input = self.game.input
+  if input:wasPressed("b") then
+    self:close()
+    return
+  end
+  if input:wasPressed("a") then
+    if not self:currentMon() then
+      self:close()
+      return
+    end
+    local team = self.teams[self.teamIndex]
+    if self.monIndex < #team then
+      self.monIndex = self.monIndex + 1
+    elseif self.teamIndex < #self.teams then
+      self.teamIndex = self.teamIndex + 1
+      self.monIndex = 1
+    else
+      self:close()
+      return
+    end
+    self:loadMon()
+  end
+end
+
+function LeaguePC:draw()
+  love.graphics.setColor(1, 1, 1, 1)
+  love.graphics.rectangle("fill", 0, 0, 160, 144)
+  local mon = self:currentMon()
+  if not mon then return end
+  local img = self.sprites[mon.species]
+  if img then
+    -- engine/menus/league_pc.asm:98 (hlcoord 12, 5)
+    local w, h = img:getDimensions()
+    local x = 96 + math.floor((8 - w / 8) / 2) * 8
+    local y = 40 + (7 - h / 8) * 8
+    love.graphics.draw(img, x, y)
+    if self.spriteTrueColor[mon.species] then
+      require("src.render.PaletteFX").markTrueColor(x, y, w, h)
+    end
+  end
+  -- engine/movie/hall_of_fame.asm:159
+  HallOfFame.drawMonInfo(self, mon)
+  -- engine/menus/league_pc.asm:102
+  Font.drawBox(0, 13, 20, 4)
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw(Strings("HALL OF FAME No"), 1 * 8, 15 * 8)
+  Font.draw(("%3d"):format(self.teamIndex), 16 * 8, 15 * 8)
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+return LeaguePC

src/ui/NamingScreen.lua

@@ -79,7 +79,16 @@ end
 function NamingScreen:enter()
   if self.presets and #self.presets > 0 then
     local Menu = require("src.ui.Menu")
-    local items = { { label = Strings("NEW NAME") } }
+    -- engine/movie/oak_speech/oak_speech2.asm:1
+    self.choosing = true
+    self.isOpaque = false
+    local items = { {
+      label = Strings("NEW NAME"),
+      onSelect = function()
+        self.choosing = nil
+        self.isOpaque = nil
+      end,
+    } }
     for _, preset in ipairs(self.presets) do
       table.insert(items, {
         label = preset,
@@ -193,6 +202,7 @@ function NamingScreen:update(dt)
 end
 
 function NamingScreen:draw()
+  if self.choosing then return end
   love.graphics.setColor(1, 1, 1, 1)
   love.graphics.rectangle("fill", 0, 0, 160, 144)
   love.graphics.setColor(0, 0, 0, 1)

src/ui/TownMap.lua

@@ -220,6 +220,20 @@ function TownMap.new(game, opts)
   -- the player's current location (guard: overworld may not be running)
   local mapId = game.overworld and game.overworld.map and game.overworld.map.id
   self.playerLoc = mapId and self.byMap[mapId] or nil
+  -- engine/items/town_map.asm:347
+  do
+    local playerSprites = (game.data.field and game.data.field.playerSprites)
+                          or {}
+    local sprites = game.data.sprites or {}
+    local red = sprites[playerSprites.walk or "SPRITE_RED"]
+                or sprites.SPRITE_RED
+    local ok, img = pcall(love.graphics.newImage, red and red.image)
+    if ok and img then
+      self.playerSheet = img
+      self.playerQuad = love.graphics.newQuad(0, 0, 16, 16,
+                                              img:getDimensions())
+    end
+  end
   self.sel = 1
   -- LoadTownMap_Fly always opens with hl on wFlyLocationsList[0], the FIRST
   -- fly destination (PALLET_TOWN), never the player's current town (#795).
@@ -345,18 +359,16 @@ function TownMap:draw()
       love.graphics.setColor(1, 1, 1, 1)
       return
     end
-    -- the player's current location blinks (slow phase).  Paint it with a
-    -- palette-safe DARK shade (red 0), not red: this screen composites through
-    -- the TOWNMAP SGB shade-remap shader (PaletteFX.shader), which keys ONLY on
-    -- the red channel, and a red-0.75 dot lands in the c1 bucket = TOWNMAP
-    -- {165,214,255}, the exact light-blue used for the water and the town-square
-    -- fill, so the marker was drawn but recolored invisible (#152).  Red 0 -> c3
-    -- {25,16,16} = a solid dark "you are here" dot, visible on land and water.
+    -- engine/items/town_map.asm:347; fallback dot stays red 0 for PaletteFX (#152)
     if self.playerLoc and self.blink < 20 then
       local x, y = markerXY(self.playerLoc)
-      love.graphics.setColor(0, 0, 0, 1)
-      love.graphics.rectangle("fill", x + 2, y + 2, 4, 4)
-      love.graphics.setColor(1, 1, 1, 1)
+      if self.playerSheet then
+        love.graphics.draw(self.playerSheet, self.playerQuad, x - 4, y - 3)
+      else
+        love.graphics.setColor(0, 0, 0, 1)
+        love.graphics.rectangle("fill", x + 2, y + 2, 4, 4)
+        love.graphics.setColor(1, 1, 1, 1)
+      end
     end
     -- blinking cursor on the selected location.  markerXY is the 8x8 cell's
     -- top-left; the cursor asset is a 16x16 hollow frame centered on its own
@@ -389,11 +401,16 @@ function TownMap:draw()
       drawSquare(loc)
     end
     if self.playerLoc and self.blink < 20 then
-      -- palette-safe dark, same red-channel shade-remap reason as the primary
-      -- grid path above (#152); stale-asset builds hit this fallback square
-      love.graphics.setColor(0, 0, 0, 1)
-      love.graphics.rectangle("fill", self.playerLoc.x * 8 + 2,
-                              self.playerLoc.y * 8 + 2, 4, 4)
+      -- engine/items/town_map.asm:347; fallback dot stays red 0 for PaletteFX (#152)
+      if self.playerSheet then
+        love.graphics.setColor(1, 1, 1, 1)
+        love.graphics.draw(self.playerSheet, self.playerQuad,
+                           self.playerLoc.x * 8 - 4, self.playerLoc.y * 8 - 3)
+      else
+        love.graphics.setColor(0, 0, 0, 1)
+        love.graphics.rectangle("fill", self.playerLoc.x * 8 + 2,
+                                self.playerLoc.y * 8 + 2, 4, 4)
+      end
     end
     if selected and self.blink % 16 < 10 then
       love.graphics.setColor(0, 0, 0, 1)

src/ui/gen2/BattleState.lua

@@ -49,6 +49,9 @@ BattleState.isOpaque = true
 -- the victory jingle can keep looping through the post-win prompts.
 local MESSAGE_FRAMES = 48
 
+-- engine/battle/effect_commands.asm:6661
+local MOVE_DELAY_FRAMES = 40
+
 -- home/hm_moves.asm:17-25 IsHMMove's .HMMoves.
 local HM_MOVES = {
   CUT = true, FLY = true, SURF = true, STRENGTH = true, FLASH = true,
@@ -239,15 +242,8 @@ function BattleState.new(game, opts)
   self.menuIndex = 1
   self.moveIndex = 1
   self.picCache = {}
-  -- Which side's pic box the tilemap has been left EMPTY in.  BattleBGEffect_
-  -- ReturnMon's last row (what swallows a mon into a thrown ball) and
-  -- MonFaintedAnimation both clear the box and neither puts anything back: it
-  -- stays blank until something DRAWS a pic into it, which on the cart is only
-  -- ever a send-out (ShowSetEnemyMonAndSendOutAnimation / SendOutPlayerMon).
-  -- Without this latch the pic came back the instant the animation let go of
-  -- the screen, so a caught mon stood there through "Gotcha!" and a fainted one
-  -- popped back up for its own faint line.  See stepAnim for why it is latched
-  -- at those two moments rather than off the runner's own last frame.
+  -- Which side's pic box stays EMPTY until a send-out redraws it: a catch
+  -- latches from stepAnim (data/moves/animations.asm:379), a faint from the slide.
   self.picHidden = { player = false, enemy = false }
   -- engine/battle/sliding_intro.asm: 72 frames of the two halves sliding in
   -- from opposite sides before the first message.
@@ -1050,10 +1046,10 @@ function BattleState:afterAnimFor(side)
   return "ANIM_PLAYER_DAMAGE"
 end
 
-function BattleState:animForMove(moveId, side)
+function BattleState:animForMove(moveId, side, param)
   local key = self.anims and self.anims.moves and self.anims.moves[moveId]
   local started = self:startAnim(key, {
-    turn = self:turnFor(side), animId = moveId, isMove = true,
+    turn = self:turnFor(side), animId = moveId, isMove = true, param = param,
   })
   if started then
     -- BattleAnimRunScript (anim_commands.asm:55-72): after the move script
@@ -1091,14 +1087,22 @@ function BattleState:animForId(idName, side, param)
   })
 end
 
+-- data/moves/animations.asm:379
+function BattleState:latchCaughtPic()
+  local anim = self.anim
+  if anim and anim.animId == "ANIM_THROW_POKE_BALL"
+      and self.ballThrow and self.ballThrow.caught then
+    self.picHidden.enemy = true
+  end
+end
+
 -- One logic frame of a running animation.  B cuts it short, the way holding B
 -- pages a text box.
 function BattleState:stepAnim(input)
   if not self.anim then return end
   if input and (input:wasPressed("b") or input:wasPressed("start")) then
-    -- Cut short: the BG effects never reached their own last step, so the
-    -- tilemap is whatever they had got to and nothing is latched -- the
-    -- explicit latches (a catch) are the only ones that survive a skip.
+    -- Cut short: only the explicit latches (a caught mon) survive a skip.
+    self:latchCaughtPic()
     self.anim = nil
     -- Cart still reaches the after-anim arm after a move script ends; a skip
     -- of the move should not drop the hit shake that follows it.
@@ -1106,6 +1110,7 @@ function BattleState:stepAnim(input)
     return self:endSendOutAnim()
   end
   if not self.anim:step() then
+    self:latchCaughtPic()
     -- pokegold data/moves/animations.asm .Click: anim_keepsprites means
     -- the OAM outlives the script, so keep the runner for drawing too.
     if not self.anim.keepSprites then self.anim = nil end
@@ -1391,16 +1396,14 @@ function BattleState:advanceQueue()
   end
   if event.text then
     self.message = event.text
-    -- Lines that must not hold the queue for A/B:
-    --   move   UsedMoveText -> text_end, then moveanim
-    --   level  GrewToLevel is text_end (battle.asm:336-343), then the stats
-    --          box's WaitPressAorB is the real hold
-    -- experience keeps the wait: _ExpPointsText ends in `prompt`
-    -- (common_1.asm:1660-1665).  update() runs stepExpAnim before that wait,
-    -- so the bar crawls under the line and A dismisses it before the battle
-    -- can end.
+    -- move/level lines do not hold for A/B (battle.asm:336-343); experience
+    -- keeps the wait (common_1.asm:1660-1665).
     if event.kind == "move" or event.kind == "level" then
       self.messageTimer = 0
+      -- engine/battle/effect_commands.asm:1958-1961
+      if event.kind == "move" and event.missed then
+        self.messageDelay = MOVE_DELAY_FRAMES
+      end
     else
       self.messageTimer = MESSAGE_FRAMES
     end
@@ -1422,17 +1425,12 @@ function BattleState:advanceQueue()
       if event.waitSfx then self.waitSfx = event.sfx end
     end
   end
-  -- The move's own animation plays over its "used X!" line, which is where
-  -- PlayBattleAnim sits in the effect command list.  Its after-anim (the hit
-  -- shake) is chained by animForMove / stepAnim, matching BattleAnimRunScript.
-  -- BattleCommand_MoveAnimNoSub (engine/battle/effect_commands.asm:1958) opens
-  -- with `ld a, [wAttackMissed] / and a / jp nz, BattleCommand_MoveDelay`: a
-  -- move that missed burns the delay and plays nothing.  Battle:markMissed sets
-  -- event.missed on every wAttackMissed path.
+  -- engine/battle/effect_commands.asm:1958: a missed move burns the delay
+  -- and plays nothing; the after-anim chain is animForMove / stepAnim's.
   if event.kind == "move" and not event.missed then
     self.afterAnimPlayed = nil
     self.pendingAfterAnim = nil
-    if not self:animForMove(event.move, event.side) then
+    if not self:animForMove(event.move, event.side, event.animParam) then
       -- BATTLE SCENE off skips the move script but still runs wBattleAfterAnim
       -- (anim_commands.asm:55-72 .disabled fallthrough).
       local options = self.game and self.game.options
@@ -1854,6 +1852,11 @@ function BattleState:update(_dt)
     -- (core.asm:6881-6888), with that line still on screen.  Run the crawl
     -- before any PromptButton wait so the bar does not sit frozen until A.
     if self:stepExpAnim() then return end
+    -- engine/battle/effect_commands.asm:6661
+    if (self.messageDelay or 0) > 0 then
+      self.messageDelay = self.messageDelay - 1
+      return
+    end
     if self.messageTimer > 0 then
       if self.tutorial then
         -- PromptButton waits for the button; the tutorial cannot press it, so
@@ -2463,14 +2466,6 @@ function BattleState:pushCaught(enemy, itemId)
   local save = self.save
   self.battle.over = true
   self.battle.outcome = "caught"
-  -- The mon is INSIDE the ball from here on.  BattleAnim_ThrowPokeBall's caught
-  -- arm ends on the return-mon BG effect, which leaves the enemy pic box
-  -- cleared, and PokeBallEffect never draws a frontpic again -- there is no
-  -- send-out left in a battle that is already over.  Latched here as well as
-  -- from the animation's own last step so that a throw the player skipped with
-  -- B (BattleAnimRunScript has no such skip; this port does) cannot put the
-  -- caught mon back on the field for the "Gotcha!" line.
-  self.picHidden.enemy = true
   -- PokeBallEffect's FRIEND_BALL arm: the caught mon's happiness is set to
   -- FRIEND_BALL_HAPPINESS (200) instead of the base 70.  That is the ball's
   -- whole effect; its catch rate is a plain ball's.  It applies on the box
@@ -2932,6 +2927,7 @@ function BattleState:useItem(itemId)
     -- wThrownBallWobbleCount 0, then `predef PlayBattleAnim`.  Everything
     -- pushed above is drained only once the ball has finished wobbling.
     self:startBallAnim(self:ballAnimParam(itemId), itemId)
+    if caught and not self.anim then self.picHidden.enemy = true end
     self.message = nil
     self.messageTimer = 0
     self.phase = "resolving"

src/ui/gen2/PokedexMenu.lua

@@ -144,12 +144,7 @@ function PokedexMenu.new(game, opts)
   self.game = game
   self.save = opts.save or (game and game.save)
   local data = game and game.data or {}
-  -- Held, not just read into the fields below.  CRY resolves its sample
-  -- through data.audio.cries and AREA resolves nests and landmark names
-  -- through data.maps / data.landmarks, and every one of those reads
-  -- `self.data` -- which nothing assigned, so `cries` folded to nil, playCry
-  -- returned before it reached Sound, and the button did nothing at all.
-  -- Taken by reference so a mod's merged cry or landmark is the one used.
+  -- engine/pokedex/pokedex.asm:447
   self.data = data
   self.dex = opts.pokedex or data.gen2Pokedex
   self.pokemon = opts.pokemon or data.pokemon
@@ -866,15 +861,6 @@ function PokedexMenu:drawArea()
   self:text(region == "kanto" and "KANTO" or "JOHTO", 1, 1)
 
   local G = love.graphics
-  local table_ = self.data and self.data.landmarks
-  local byIndex = self.landmarkByIndex
-  if not byIndex then
-    byIndex = {}
-    for _, entry in pairs((table_ and table_.landmarks) or {}) do
-      if entry and entry.index then byIndex[entry.index] = entry end
-    end
-    self.landmarkByIndex = byIndex
-  end
 
   if #nests == 0 then
     -- A species with no grass, water or roamer entry in this region. The cart
@@ -883,11 +869,11 @@ function PokedexMenu:drawArea()
     return
   end
 
-  -- Blinking markers, the way the cart flashes its OBJs.
+  -- engine/pokegear/pokegear.asm:2427
   local on = ((self.areaBlink or 0) % 32) < 20
   if cells and on then
     for _, index in ipairs(nests) do
-      local mark = byIndex[index]
+      local mark = Nests.landmark(self.data, index)
       if mark and mark.x and mark.y then
         G.setColor(0, 0, 0, 1)
         G.rectangle("fill", mark.x - 2, mark.y - 2, 5, 5)
@@ -900,7 +886,7 @@ function PokedexMenu:drawArea()
   -- Name the first one in words as well as on the map: the flashing dot is
   -- unreadable at this size on a modern display, and the landmark name is what
   -- a player actually wants off this screen.
-  local first = byIndex[nests[1]]
+  local first = Nests.landmark(self.data, nests[1])
   if first and first.name then
     local name = tostring(first.name):gsub("\n", " ")
     self:text(name, 1, 16)