Simplify comments

data/scripts/story2.lua

@@ -206,16 +206,10 @@ M.PALLET_TOWN = {
     end
 
     local function escortToLab(oak)
-      -- PalletMovementScript_OakMoveLeft (engine/overworld/auto_movement
+      -- PalletMovementScript_OakMoveLeft
-      -- .asm) is shared by Red and Yellow, but only Yellow's copy starts
+      -- (engine/overworld/auto_movement.asm) starts MUSIC_MUSEUM_GUY
-      -- MUSIC_MUSEUM_GUY there (the instant the movement script is
+      -- when the escort begins in Yellow. Until then, Pallet Town plays
-      -- armed, before Oak or the player takes a single step); pokered's
+      -- after the battle; Red/Blue leave MUSIC_MEET_PROF_OAK playing.
-      -- copy only sets BIT_NO_MAP_MUSIC and leaves whatever was already
-      -- playing (MUSIC_MEET_PROF_OAK, started when Oak first appears)
-      -- running uninterrupted all the way into the lab. Until Yellow's
-      -- switch fires (including the Whew.../Come with me lines right
-      -- after the Pikachu battle) the map's default Pallet Town theme
-      -- plays, restored by the battle's own exit path.
       if yellow then
         Music.play(game.data, "Music_MuseumGuy")
       end
@@ -263,17 +257,13 @@ M.PALLET_TOWN = {
           -- Oak turns toward the horizontally adjacent grass (left exit
           -- looks right, right exit looks left -- the
           -- EVENT_PLAYER_AT_RIGHT_EXIT_TO_PALLET_TOWN branch).
-          -- PalletTownOakGreetsPlayerScript (the turn) and
+          -- In pokeyellow, PalletTownOakGreetsPlayerScript turns Oak and
-          -- PalletTownPikachuBattleScript (arming wCurOpponent) are
+          -- PalletTownPikachuBattleScript arms the battle on the next
-          -- separate script ticks in pokeyellow, one main-loop iteration
+          -- overworld iteration. OverworldLoopLessDelay
-          -- apart: OverworldLoopLessDelay (home/overworld.asm) burns two
+          -- (home/overworld.asm) burns two DelayFrame calls at the top
-          -- DelayFrame calls per iteration, calls RunMapScript (via
+          -- of each iteration and calls RunMapScript before checking
-          -- JoypadOverworld) first, and only then checks wCurOpponent to
+          -- wCurOpponent, so those two DelayFrame calls are what keep
-          -- jump into the battle -- so the turn from iteration A is on
+          -- Oak's turn on screen before the battle check fires.
-          -- screen for the two DelayFrame calls that open iteration B,
-          -- before that same iteration's RunMapScript arms wCurOpponent
-          -- and falls straight into the battle check. Two frames, not
-          -- zero and not a deliberate pause.
           if oak then oak.facing = x == 10 and "right" or "left" end
           hold(2, nil, function()
             local battle = BattleState.newWild(game, "PIKACHU", 5)
@@ -281,11 +271,7 @@ M.PALLET_TOWN = {
             battle.onFinish = function()
               afterPikaBattle()
             end
-            -- InitWildBattle calls DoBattleTransitionAndInitBattleVariables
+            -- Use the standard wild-battle entry transition.
-            -- unconditionally (core.asm:6699) -- no BATTLE_TYPE_PIKACHU
-            -- special case -- so Oak's catch gets the flash + wipe like
-            -- any other wild battle (Commands.old_man_demo already does
-            -- this for the Viridian old man's tutorial catch).
             Commands.pushBattle(ctx, battle)
           end)
         end))

src/battle/BattleState.lua

@@ -2194,11 +2194,10 @@ function BattleState:openOldManBag()
   self.afterQueue = "menu"
   self:ui(function()
     local list
-    -- The canned one-item bag (POKE_BALL, neither reading from the real
+    -- The canned bag (POKE_BALL, not read from the player's real
-    -- inventory) differs by version: pokered's OldManItemList (core.asm
+    -- inventory) differs by version: pokered's OldManItemList has 50
-    -- :2212-2214) is quantity 50; pokeyellow's SimulatedInputBattleItemList
+    -- POKé BALLs; pokeyellow's SimulatedInputBattleItemList, shared by
-    -- (core.asm:2316-2319), shared by both the Viridian old man's demo and
+    -- the Viridian tutorial and Oak's catch, has one.
-    -- Oak's Pikachu catch, dropped that to quantity 1.
     local qty = require("src.core.GameVersion").isYellow() and "x1" or "x50"
     list = ListMenu.new(game, "ITEMS", {
       { value = "POKE_BALL", label = Strings("POKé BALL"), right = qty },

src/script/Commands.lua

@@ -280,19 +280,13 @@ function Commands.save_end_battle_text(ctx, textId)
   ctx.endBattleText = TextBox.substitute(ctx.game, text or textId)
 end
 
--- Every battle enters through the transition wipe, script-driven ones
+-- Route scripted battles through the standard entry transition. In the
--- included: BattleTransition (engine/battle/battle_transitions.asm:1) runs
+-- originals, InitWildBattle (engine/battle/init_battle.asm) always calls
--- from DoBattleTransitionAndInitBattleVariables for all of them, and
+-- DoBattleTransitionAndInitBattleVariables (engine/battle/core.asm), with
--- GetBattleTransitionID_WildOrTrainer picks the style from the battle
+-- no old-man or Pikachu-demo exception; BattleTransition then selects the
--- kind. InitWildBattle calls DoBattleTransitionAndInitBattleVariables
+-- wipe for the battle kind. Some tests provide only a partial overworld
--- unconditionally (core.asm:6699) -- there is no BATTLE_TYPE_OLD_MAN or
+-- double, so retain a logged fallback even though it skips the transition
--- BATTLE_TYPE_PIKACHU special case -- so the old-man tutorial and Oak's
+-- and battle music.
--- Pikachu catch get the wipe like any other wild battle, same as every
--- scripted trainer (gym leaders, the rival, Giovanni). ctx.overworld can
--- be a test double without the full OverworldState metatable, so this
--- falls back to a bare push; that fallback silently skips the wipe and
--- the battle-theme start, so it's worth a log rather than a quiet
--- behavior change.
 function Commands.pushBattle(ctx, battle)
   if ctx.overworld and ctx.overworld.pushBattle then
     ctx.overworld:pushBattle(battle)
@@ -334,10 +328,7 @@ function Commands.start_battle(ctx, kind, a, b)
     end
     runner:resume()
   end
-  -- Pushing the BattleState straight onto the stack skipped the wipe
+  -- A direct stack push would skip the battle-entry transition.
-  -- entirely, so every scripted trainer -- gym leaders, the rival, Giovanni --
-  -- and every scripted wild battle simply cut to the battle screen.  The
-  -- trainer-sight path already went through pushBattle; this one did not.
   Commands.pushBattle(ctx, battle)
   runner:yield()
 end

src/world/OverworldController.lua

@@ -453,12 +453,10 @@ function OverworldState:setMap(mapId, x, y, facing, opts)
   -- walks out of the warp, not beside him (#863)
   require("src.world.PikachuFollower").onMapEntered(Game, self, opts, true)
 
-  -- opts.keepMusic: the Oak-escort warp keeps whatever cutscene song is
+  -- opts.keepMusic preserves the Oak-escort song across the lab warp,
-  -- already playing going into the lab instead of cutting to it
+  -- matching BIT_NO_MAP_MUSIC: MUSIC_MUSEUM_GUY in Yellow and
-  -- (BIT_NO_MAP_MUSIC in wStatusFlags7) -- MUSIC_MUSEUM_GUY in Yellow
+  -- MUSIC_MEET_PROF_OAK in Red/Blue. keepMusicOnce is the equivalent
-  -- (started in escortToLab when Oak begins walking), MUSIC_MEET_PROF_OAK
+  -- one-shot set by play_music opts.keep.
-  -- in Red/Blue (pokered never switches songs for this walk); keepMusicOnce
-  -- is the play_music opts.keep one-shot of the same bit
   local keepMusic = (opts and opts.keepMusic) or self.keepMusicOnce
   self.keepMusicOnce = nil
   if not keepMusic then