CLOSES #1181, CLOSES #1212, CLOSES #1214, CLOSES #1224, CLOSES #1230, CLOSES #1249, CLOSES #1271, CLOSES #1272, CLOSES #1273, CLOSES #1298, CLOSES #1305, CLOSES #1307, CLOSES #1318, CLOSES #1328, CLOSES #1330, CLOSES #1331, CLOSES #1333, CLOSES #1334, CLOSES #1335, CLOSES #1340, CLOSES #1345, CLOSES #1346, CLOSES #1360, CLOSES #1362

src/world/OverworldController.lua

@@ -1969,8 +1969,11 @@ function OverworldState:tryBookshelf(fx, fy)
     return true
   end
   if entry.screen then
-    -- Blue's house shelf opens the TOWN MAP (TownMapText)
-    pcall(Screens.push, Game, entry.screen)
+    -- engine/events/hidden_events/town_map.asm:1
+    Game.stack:push(TextBox.new(Game,
+      t[entry.text] or t._TownMapText
+      or romText(Game.data, "_TownMapText", "A TOWN MAP."),
+      function() pcall(Screens.push, Game, entry.screen) end))
     return true
   end
   local kind = entry.kind
@@ -2136,14 +2139,17 @@ function OverworldState:tryHiddenObject(fx, fy)
   for _, h in ipairs(extras.pcTiles[self.map.id] or {}) do
     if h.x == fx and h.y == fy and (not h.facing or h.facing == facing) then
       if self.map.id == "REDS_HOUSE_2F" then
-        -- The player's bedroom PC is the one location in Red/Blue whose PC
-        -- callback is OpenRedsPC (engine/events/hidden_objects/players_pc.asm),
-        -- which runs the PlayerPC predef directly -- item storage, no
-        -- SOMEONE'S/BILL'S PC main menu (DisplayPCMainMenu).  Every other
-        -- pcTile is a Pokémon Center-style PC that shows the multi-PC menu. (#228)
+        -- OpenRedsPC (engine/events/hidden_objects/players_pc.asm) runs the
+        -- PlayerPC predef directly, no DisplayPCMainMenu (#228)
         require("src.core.Sound").play(Game.data, "Turn_On_PC")
-        -- direct access: ExitPlayerPC rings SFX_TURN_OFF_PC (players_pc.asm, #960)
-        Screens.push(Game, "PlayerPC", { direct = true })
+        -- engine/menus/players_pc.asm:16
+        Game.stack:push(TextBox.new(Game,
+          (Game.data.text or {})._TurnedOnPC2Text
+          or romText(Game.data, "_TurnedOnPC2Text", "{PLAYER} turned on\nthe PC."),
+          function()
+            -- direct access: ExitPlayerPC rings SFX_TURN_OFF_PC (players_pc.asm, #960)
+            Screens.push(Game, "PlayerPC", { direct = true })
+          end, { instant = true }))
       else
         self:openPC()
       end
@@ -2892,13 +2898,16 @@ function OverworldState:openPC(onDone)
     done()
   end
   table.insert(items, { label = Strings("LOG OFF"), onSelect = logOff })
-  -- pokered sets BIT_NO_MENU_BUTTON_SOUND for the whole PC session
-  -- (engine/overworld/pokecenter_pc.asm / player_pc.asm); DisplayPCMainMenu
-  -- calls TextBoxBorder with c=14 (interior width, +2 for the border), so
-  -- tw here (total width) is 16
-  Game.stack:push(Menu.new(Game, items,
+  -- BIT_NO_MENU_BUTTON_SOUND for the whole PC session; DisplayPCMainMenu's
+  -- TextBoxBorder c=14 interior -> tw 16 (engine/overworld/pokecenter_pc.asm)
+  local menu = Menu.new(Game, items,
     { tx = 0, ty = 0, tw = 16, th = #items * 2 + 2, onCancel = logOff,
-      noSound = true }))
+      noSound = true })
+  -- engine/menus/pc.asm:5
+  Game.stack:push(TextBox.new(Game,
+    (Game.data.text or {})._TurnedOnPC1Text
+    or romText(Game.data, "_TurnedOnPC1Text", "{PLAYER} turned on\nthe PC."),
+    function() Game.stack:push(menu) end))
 end
 
 -- The PROF. OAK's PC session (engine/menus/oaks_pc.asm OpenOaksPC): the

src/world/gen2/StepEvents.lua

@@ -78,7 +78,7 @@ function StepEvents.poisonStep(party)
     return { kind = "poisonFaint", fainted = fainted, hurt = hurt, blocks = true }
   end
   if #hurt > 0 then
-    -- .PlayPoisonSFX and the two-frame red flash, then `xor a`: no carry, so
+    -- .PlayPoisonSFX and the four-frame BG flash, then `xor a`: no carry, so
     -- the step still counts and the wild roll still happens.
     return { kind = "poisonHurt", hurt = hurt, blocks = false }
   end

src/world/gen2/World.lua

@@ -2123,6 +2123,11 @@ function World:updateShake()
   shake.phase = (shake.left % 2 == 0) and shake.amplitude or -shake.amplitude
 end
 
+-- engine/events/poisonstep_pals.asm:9
+function World:poisonBGFlash()
+  self.poisonFlash = 4
+end
+
 -- Script_warp / Script_warpfacing: a raw destination CELL, distinct from the
 -- warp_events World:takeWarp follows.  `facing` is nil for `warp` and a
 -- Movement direction for `warpfacing` (PLAYERSPRITESETUP_CUSTOM_FACING).  A
@@ -2400,7 +2405,9 @@ end
 function World:playMapMusic()
   local data = self.game and self.game.data
   if data and data.audio and data.audio.runtime and self.map then
-    Music.playMap(data, self.map.id)
+    -- SpecialMapMusic (home/audio.asm:397)
+    Music.playMap(data, self.map.id, nil,
+                  FieldMoves.isSurfing(self.playerState))
   end
 end
 
@@ -3246,7 +3253,9 @@ function World:surfStartStep(mon)
   self:applyPlayerState(FieldMoves.surfType(mon))
   local audio = self.game and self.game.data and self.game.data.audio
   if audio and audio.runtime and self.map then
-    Music.playMap(self.game.data, self.map.id)
+    -- SpecialMapMusic (home/audio.asm:397)
+    Music.playMap(self.game.data, self.map.id, nil,
+                  FieldMoves.isSurfing(self.playerState))
   end
   if p.scriptStep then p:scriptStep(p.facing) end
   self.fieldMove = { phase = "step" }
@@ -5363,7 +5372,9 @@ function World:runSurf(result)
     self:applyPlayerState(result.state)
     local audio = self.game and self.game.data and self.game.data.audio
     if audio and audio.runtime and self.map then
-      Music.playMap(self.game.data, self.map.id)
+      -- SpecialMapMusic (home/audio.asm:397)
+      Music.playMap(self.game.data, self.map.id, nil,
+                    FieldMoves.isSurfing(self.playerState))
     end
     if self.player and self.player.scriptStep then
       self.player:scriptStep(self.player.facing)
@@ -8524,13 +8535,12 @@ function World:setMap(mapId, cx, cy, facing, opts)
   -- rebuildPeople may have pooled fresh NPCs; give them their colors too.
   self:applyPalettes()
   local audio = self.game and self.game.data and self.game.data.audio
-  -- PlayMapMusicBike (home/audio.asm), which is the mapsetup every load uses:
-  -- a player still on the bike keeps the bike theme across the warp instead of
-  -- hearing the new map's song.  Music.play dedupes the same label, so this is
-  -- safe on seamless edge crossings.
+  -- PlayMapMusicBike / SpecialMapMusic (home/audio.asm:335, :397): a biking
+  -- player keeps the bike theme; Music.play dedupes seamless edge crossings.
   if audio and audio.runtime then
     if not (FieldMoves.isBiking(self.playerState) and self:playBikeMusic()) then
-      Music.playMap(self.game.data, mapId)
+      Music.playMap(self.game.data, mapId, nil,
+                    FieldMoves.isSurfing(self.playerState))
     end
   end
   -- Fires with the map fully built and BEFORE the map's own scene script, so a
@@ -8912,14 +8922,13 @@ function World:movePlayer(dir)
     if result == "moved"
         and Permissions.surfable(map:cellCollision(p.targetX, p.targetY))
           == "land" then
-      -- .ExitWater: GetOutOfWater writes PLAYER_NORMAL and runs
-      -- UpdatePlayerSprite BEFORE .DoStep, so the player is already off the
-      -- Lapras for the step that puts them on the beach, and PlayMapMusic then
-      -- swaps the surfing theme back for the map's own.
+      -- .ExitWater: GetOutOfWater writes PLAYER_NORMAL before .DoStep, then
+      -- PlayMapMusic swaps the surf theme back (home/audio.asm:308)
       self:applyPlayerState(FieldMoves.PLAYER_NORMAL)
       local audio = self.game and self.game.data and self.game.data.audio
       if audio and audio.runtime then
-        Music.playMap(self.game.data, map.id)
+        Music.playMap(self.game.data, map.id, nil,
+                      FieldMoves.isSurfing(self.playerState))
       end
     end
   end
@@ -9159,7 +9168,7 @@ function World:countStep()
   elseif event.kind == "poisonFaint" then
     self:poisonFaintScript(event)
   elseif event.kind == "poisonHurt" then
-    -- .PlayPoisonSFX alone: the sound and the two-frame red flash, no script.
+    -- .PlayPoisonSFX alone: the sound and the four-frame BG flash, no script.
     CallAsm.run(self, "PlayPoisonSFX")
   elseif event.kind == "repel" then
     self:repelWoreOff()
@@ -10031,6 +10040,18 @@ function World:draw()
     G.setColor(1, 1, 1, 1)
   end
 
+  -- engine/events/poisonstep_pals.asm:9-42
+  if self.poisonFlash and self.poisonFlash > 0 then
+    self.poisonFlash = self.poisonFlash - 1
+    if GbcPalette.mode == "gbc" then
+      G.setColor(28 / 31, 21 / 31, 1, 0.55)
+    else
+      G.setColor(0, 0, 0, 0.45)
+    end
+    G.rectangle("fill", 0, 0, w, h)
+    G.setColor(1, 1, 1, 1)
+  end
+
   -- FadeOutToWhite / FadeOutToBlack, held until a FadeInFrom* clears it.  On
   -- the cart the pair brackets a scripted cutscene's set change (the Elite Four
   -- doors, the Radio Tower takeover, Lugia's chamber); the port has no