Comment unreferenced local labels

engine/battle/animations.asm

@@ -22,7 +22,7 @@ DrawFrameBlock:
 	jp z, .flipHorizontalTranslateDown ; SUBANIMTYPE_HFLIP
 	dec a
 	jr z, .flipBaseCoords              ; SUBANIMTYPE_COORDFLIP
-.noTransformation
+; no transformation
 	ld a, [wBaseCoordY]
 	add [hl]
 	ld [de], a ; store Y
@@ -130,7 +130,7 @@ DrawFrameBlock:
 	ld a, [wNumFBTiles]
 	cp c
 	jp nz, .loop ; go back up if there are more tiles to draw
-.afterDrawingTiles
+; after drawing tiles
 	ld a, [wFBMode]
 	cp FRAMEBLOCKMODE_02
 	jr z, .advanceFrameBlockDestAddr ; skip delay and don't clean OAM buffer
@@ -185,7 +185,7 @@ PlayAnimation:
 	jr z, .AnimationOver
 	cp FIRST_SE_ID ; is this subanimation or a special effect?
 	jr c, .playSubanimation
-.doSpecialEffect
+; do Special Effect
 	ld c, a
 	ld de, SpecialEffectPointers
 .searchSpecialEffectTableLoop
@@ -296,7 +296,7 @@ LoadSubanimation:
 	cp SUBANIMTYPE_ENEMY << 5
 	vc_hook_blue Reduce_move_anim_flashing_Blizzard
 	jr nz, .isNotType5
-.isType5
+; Type 5
 	call GetSubanimationTransform2
 	jr .saveTransformation
 .isNotType5
@@ -427,11 +427,11 @@ MoveAnimation:
 	call PlayAnimation
 	vc_hook_red Stop_reducing_move_anim_flashing_Bubblebeam_Mega_Kick
 	vc_hook_blue Stop_reducing_move_anim_flashing_Spore
-	jr .next4
+	jr .next
 .animationsDisabled
 	ld c, 30
 	call DelayFrames
-.next4
+.next
 	vc_hook_red Stop_reducing_move_anim_flashing
 	vc_hook_blue Stop_reducing_move_anim_flashing_Rock_Slide_Dream_Eater
 	call PlayApplyingAttackAnimation ; shake the screen or flash the pic in and out (to show damage)
@@ -1097,6 +1097,8 @@ SetAnimationBGPalette:
 	ldh [rBGP], a
 	ret
 
+AnimationUnusedShakeScreen:
+; Shakes the screen for a while. Unreferenced.
 	ld b, $5
 
 AnimationShakeScreenVertically:

engine/battle/core.asm

@@ -1247,7 +1247,7 @@ SlideTrainerPicOffScreen:
 	ldh a, [hSlideAmount]
 	cp 8
 	jr z, .slideRight
-.slideLeft ; slide player sprite off screen
+; slide player sprite left off screen
 	ld a, [hld]
 	ld [hli], a
 	inc hl
@@ -3557,10 +3557,12 @@ CheckPlayerStatusConditions:
 	ld hl, AttackContinuesText
 	call PrintText
 	ld a, [wPlayerNumAttacksLeft]
-	dec a ; did multi-turn move end?
+	dec a
 	ld [wPlayerNumAttacksLeft], a
-	ld hl, GetPlayerAnimationType ; if it didn't, skip damage calculation (deal damage equal to last hit),
-	                ; DecrementPP and MoveHitTest
+	ld hl, GetPlayerAnimationType ; skip damage calculation (deal damage equal to last hit),
+	                              ; DecrementPP and MoveHitTest
+	; redundant code, we don't need to test here if wPlayerNumAttacksLeft hit 0,
+	; since CheckNumAttacksLeft will reset bit USING_TRAPPING_MOVE
 	jp nz, .returnToHL
 	jp .returnToHL
 
@@ -3626,7 +3628,7 @@ ConfusedNoMoreText:
 	text_far _ConfusedNoMoreText
 	text_end
 
-SavingEnergyText:
+SavingEnergyText: ; unreferenced
 	text_far _SavingEnergyText
 	text_end
 
@@ -4171,7 +4173,7 @@ GetDamageVarsForPlayerAttack:
 	ld a, [hl] ; a = [wPlayerMoveType]
 	cp SPECIAL ; types >= SPECIAL are all special
 	jr nc, .specialAttack
-.physicalAttack
+; physical attack
 	ld hl, wEnemyMonDefense
 	ld a, [hli]
 	ld b, a
@@ -4284,7 +4286,7 @@ GetDamageVarsForEnemyAttack:
 	ld a, [hl] ; a = [wEnemyMoveType]
 	cp SPECIAL ; types >= SPECIAL are all special
 	jr nc, .specialAttack
-.physicalAttack
+; physical attack
 	ld hl, wBattleMonDefense
 	ld a, [hli]
 	ld b, a
@@ -5301,7 +5303,6 @@ AdjustDamageForMoveType:
 	ld [hl], a
 	or b ; is damage 0?
 	jr nz, .skipTypeImmunity
-.typeImmunity
 ; if damage is 0, make the move miss
 ; this only occurs if a move that would do 2 or 3 damage is 0.25x effective against the target
 	inc a
@@ -5394,7 +5395,7 @@ MoveHitTest:
 	ldh a, [hWhoseTurn]
 	and a
 	jr nz, .enemyTurn
-.playerTurn
+; player's turn
 ; this checks if the move effect is disallowed by mist
 	ld a, [wPlayerMoveEffect]
 	cp ATTACK_DOWN1_EFFECT
@@ -5466,12 +5467,12 @@ MoveHitTest:
 	ld [wMoveMissed], a
 	ldh a, [hWhoseTurn]
 	and a
-	jr z, .playerTurn2
-.enemyTurn2
+	jr z, .playerTurn
+; enemy's turn
 	ld hl, wEnemyBattleStatus1
 	res USING_TRAPPING_MOVE, [hl] ; end multi-turn attack e.g. wrap
 	ret
-.playerTurn2
+.playerTurn
 	ld hl, wPlayerBattleStatus1
 	res USING_TRAPPING_MOVE, [hl] ; end multi-turn attack e.g. wrap
 	ret
@@ -6063,9 +6064,11 @@ CheckEnemyStatusConditions:
 	ld hl, AttackContinuesText
 	call PrintText
 	ld hl, wEnemyNumAttacksLeft
-	dec [hl] ; did multi-turn move end?
-	ld hl, GetEnemyAnimationType ; if it didn't, skip damage calculation (deal damage equal to last hit),
+	dec [hl]
+	ld hl, GetEnemyAnimationType ; skip damage calculation (deal damage equal to last hit),
 	                             ; DecrementPP and MoveHitTest
+	; redundant code, we don't need to test here if wEnemyNumAttacksLeft hit 0,
+	; since CheckNumAttacksLeft will reset bit USING_TRAPPING_MOVE
 	jp nz, .enemyReturnToHL
 	jp .enemyReturnToHL
 .checkIfUsingRage
@@ -6415,7 +6418,7 @@ QuarterSpeedDueToParalysis:
 	ldh a, [hWhoseTurn]
 	and a
 	jr z, .playerTurn
-.enemyTurn ; quarter the player's speed
+; enemy's turn, quarter the player's speed
 	ld a, [wBattleMonStatus]
 	and 1 << PAR
 	ret z ; return if player not paralysed
@@ -6458,7 +6461,7 @@ HalveAttackDueToBurn:
 	ldh a, [hWhoseTurn]
 	and a
 	jr z, .playerTurn
-.enemyTurn ; halve the player's attack
+; enemy's turn, halve the player's attack
 	ld a, [wBattleMonStatus]
 	and 1 << BRN
 	ret z ; return if player not burnt
@@ -6642,7 +6645,7 @@ LoadHudTilePatterns:
 	ldh a, [rLCDC]
 	add a ; is LCD disabled?
 	jr c, .lcdEnabled
-.lcdDisabled
+; LCD disabled
 	ld hl, BattleHudTiles1
 	ld de, vChars2 tile $6d
 	ld bc, BattleHudTiles1End - BattleHudTiles1

engine/battle/draw_hud_pokeball_gfx.asm

@@ -18,7 +18,7 @@ LoadPartyPokeballGfx:
 
 SetupOwnPartyPokeballs:
 	call PlacePlayerHUDTiles
-	ld hl, wPartyMon1
+	ld hl, wPartyMons
 	ld de, wPartyCount
 	call SetupPokeballs
 	ld a, $60

engine/battle/effects.asm

@@ -230,7 +230,7 @@ FreezeBurnParalyzeEffect:
 	jr z, .burn1
 	cp FREEZE_SIDE_EFFECT1
 	jr z, .freeze1
-; .paralyze1
+; paralyze1
 	ld a, 1 << PAR
 	ld [wEnemyMonStatus], a
 	call QuarterSpeedDueToParalysis ; quarter speed of affected mon
@@ -283,7 +283,7 @@ FreezeBurnParalyzeEffect:
 	jr z, .burn2
 	cp FREEZE_SIDE_EFFECT1
 	jr z, .freeze2
-; .paralyze2
+; paralyze2
 	ld a, 1 << PAR
 	ld [wBattleMonStatus], a
 	call QuarterSpeedDueToParalysis
@@ -593,7 +593,7 @@ StatModifierDownEffect:
 	ld a, [de]
 	cp ATTACK_DOWN2_EFFECT - $16 ; $24
 	jr c, .ok
-	cp EVASION_DOWN2_EFFECT + $5 ; $44
+	cp ATTACK_DOWN_SIDE_EFFECT ; move side effects, stat mod decrease is always 1
 	jr nc, .ok
 	dec b ; stat down 2 effects only (dec mod again)
 	jr nz, .ok
@@ -711,7 +711,7 @@ CantLowerAnymore:
 
 MoveMissed:
 	ld a, [de]
-	cp $44
+	cp ATTACK_DOWN_SIDE_EFFECT
 	ret nc
 	jp ConditionalPrintButItFailed
 
@@ -1321,7 +1321,7 @@ DisableEffect:
 	cp LINK_STATE_BATTLING
 	pop hl ; wEnemyMonMoves
 	jr nz, .playerTurnNotLinkBattle
-; .playerTurnLinkBattle
+; player's turn, Link Battle
 	push hl
 	ld hl, wEnemyMonPP
 .enemyTurn
@@ -1456,6 +1456,7 @@ PlayCurrentMoveAnimation2:
 .notEnemyTurn
 	and a
 	ret z
+; fallthrough
 
 PlayBattleAnimation2:
 ; play animation ID at a and animation type 6 or 3
@@ -1482,6 +1483,7 @@ PlayCurrentMoveAnimation:
 .notEnemyTurn
 	and a
 	ret z
+; fallthrough
 
 PlayBattleAnimation:
 ; play animation ID at a and predefined animation type

engine/battle/ghost_marowak_anim.asm

@@ -48,7 +48,7 @@ MarowakAnim:
 	call Delay3
 	jp ClearSprites
 
-; copies a mon pic's  from background VRAM to sprite VRAM and sets up OAM
+; copies a mon pic's from background VRAM to sprite VRAM and sets up OAM
 CopyMonPicFromBGToSpriteVRAM:
 	ld de, vFrontPic
 	ld hl, vSprites

engine/battle/move_effects/substitute.asm

@@ -37,8 +37,8 @@ SubstituteEffect_:
 	sbc 0
 	pop bc
 	jr c, .notEnoughHP ; underflow means user would be left with negative health
-                           ; bug: since it only branches on carry, it will possibly leave user with 0 HP
-.userHasZeroOrMoreHP
+                       ; bug: since it only branches on carry, it will possibly leave user with 0 HP
+; user has 0 or more HP
 	ld [hli], a ; save resulting HP after subtraction into current HP
 	ld [hl], d
 	ld h, b

engine/battle/move_effects/transform.asm

@@ -2,17 +2,22 @@ TransformEffect_:
 	ld hl, wBattleMonSpecies
 	ld de, wEnemyMonSpecies
 	ld bc, wEnemyBattleStatus3
+	; bug: on enemy's turn, a is overloaded with hWhoseTurn,
+	; before the check for INVULNERABLE
 	ld a, [wEnemyBattleStatus1]
 	ldh a, [hWhoseTurn]
 	and a
 	jr nz, .hitTest
+; player's turn
 	ld hl, wEnemyMonSpecies
 	ld de, wBattleMonSpecies
 	ld bc, wPlayerBattleStatus3
 	ld [wPlayerMoveListIndex], a
+	; bug: this should be target's BattleStatus1 (ie wEnemyBattleStatus1)
 	ld a, [wPlayerBattleStatus1]
 .hitTest
 	bit INVULNERABLE, a ; is mon invulnerable to typical attacks? (fly/dig)
+	                    ; this check doesn't work due to above bugs
 	jp nz, .failed
 	push hl
 	push de

engine/events/diploma.asm

@@ -73,8 +73,8 @@ DisplayDiploma::
 	jp GBPalNormal
 
 UnusedPlayerNameLengthFunc:
-; Unused function that does a calculation involving the length of the player's
-; name.
+; Unused function that performs bc = -(player name's length)
+; leftover from the JPN versions
 	ld hl, wPlayerName
 	lb bc, $ff, $00
 .loop

engine/events/pokemart.asm

@@ -99,7 +99,7 @@ DisplayPokemartDialogue_::
 	dec a
 	jr z, .sellMenuLoop
 
-.sellItem
+; sell item
 	ld a, [wBoughtOrSoldItemInMart]
 	and a
 	jr nz, .skipSettingFlag1
@@ -177,7 +177,7 @@ DisplayPokemartDialogue_::
 	dec a
 	jr z, .buyMenuLoop
 
-.buyItem
+; buy item
 	call .isThereEnoughMoney
 	jr c, .notEnoughMoney
 	ld hl, wNumBagItems

engine/events/prize_menu.asm

@@ -195,7 +195,7 @@ HandlePrizeChoice:
 .getMonName
 	call GetMonName
 .givePrize
-	ld hl, SoYouWantPrizeTextPtr
+	ld hl, SoYouWantPrizeText
 	call PrintText
 	call YesNoChoice
 	ld a, [wCurrentMenuItem] ; yes/no answer (Y=0, N=1)
@@ -243,25 +243,25 @@ HandlePrizeChoice:
 	predef SubBCDPredef
 	jp PrintPrizePrice
 .bagFull
-	ld hl, PrizeRoomBagIsFullTextPtr
+	ld hl, PrizeRoomBagIsFullText
 	jp PrintText
 .notEnoughCoins
 	ld hl, SorryNeedMoreCoinsText
 	jp PrintText
 .printOhFineThen
-	ld hl, OhFineThenTextPtr
+	ld hl, OhFineThenText
 	jp PrintText
 
 UnknownPrizeData:
 ; XXX what's this?
 	db $00,$01,$00,$01,$00,$01,$00,$00,$01
 
-HereYouGoTextPtr:
+HereYouGoText: ; unreferenced
 	text_far _HereYouGoText
 	text_waitbutton
 	text_end
 
-SoYouWantPrizeTextPtr:
+SoYouWantPrizeText:
 	text_far _SoYouWantPrizeText
 	text_end
 
@@ -270,12 +270,12 @@ SorryNeedMoreCoinsText:
 	text_waitbutton
 	text_end
 
-PrizeRoomBagIsFullTextPtr:
+PrizeRoomBagIsFullText:
 	text_far _OopsYouDontHaveEnoughRoomText
 	text_waitbutton
 	text_end
 
-OhFineThenTextPtr:
+OhFineThenText:
 	text_far _OhFineThenText
 	text_waitbutton
 	text_end

engine/flag_action.asm

@@ -43,10 +43,10 @@ FlagAction:
 	ld a, b
 	and a
 	jr z, .reset
-	cp 2
+	cp FLAG_TEST
 	jr z, .read
 
-.set
+; set
 	ld b, [hl]
 	ld a, d
 	or b

engine/items/inventory.asm

@@ -118,7 +118,6 @@ RemoveItemFromInventory_::
 	jr nz, .skipMovingUpSlots
 ; if the remaining quantity is 0,
 ; remove the emptied item slot and move up all the following item slots
-.moveSlotsUp
 	ld e, l
 	ld d, h
 	inc de

engine/items/item_effects.asm

@@ -156,7 +156,7 @@ ItemUseBall:
 	dec a
 	jr nz, .notOldManBattle
 
-.oldManBattle
+; Old Man Battle
 	ld hl, wGrassRate
 	ld de, wPlayerName
 	ld bc, NAME_LENGTH
@@ -645,7 +645,7 @@ ItemUseBicycle:
 	jp z, ItemUseNotTime
 	dec a ; is player already bicycling?
 	jr nz, .tryToGetOnBike
-.getOffBike
+; get off bike
 	call ItemUseReloadOverworldData
 	xor a
 	ld [wWalkBikeSurfState], a ; change player state to walking
@@ -671,13 +671,13 @@ ItemUseSurfboard:
 	ld [wWalkBikeSurfStateCopy], a
 	cp 2 ; is the player already surfing?
 	jr z, .tryToStopSurfing
-.tryToSurf
+; try to Surf
 	call IsNextTileShoreOrWater
 	jp c, SurfingAttemptFailed
 	ld hl, TilePairCollisionsWater
 	call CheckForTilePairCollisions
 	jp c, SurfingAttemptFailed
-.surf
+; surfing
 	call .makePlayerMoveForward
 	ld hl, wStatusFlags5
 	set BIT_SCRIPTED_MOVEMENT_STATE, [hl]
@@ -921,7 +921,7 @@ ItemUseMedicine:
 	ld [wHPBarOldHP], a ; current HP stored at wHPBarOldHP (2 bytes, big-endian)
 	or b
 	jr nz, .notFainted
-.fainted
+; fainted
 	ld a, [wCurItem]
 	cp REVIVE
 	jr z, .updateInBattleFaintedData
@@ -973,7 +973,7 @@ ItemUseMedicine:
 .skipComparingLSB
 	pop hl
 	jr nz, .notFullHP
-.fullHP ; if the pokemon's current HP equals its max HP
+; if the pokemon's current HP equals its max HP
 	ld a, [wCurItem]
 	cp FULL_RESTORE
 	jp nz, .healingItemNoEffect
@@ -1753,8 +1753,8 @@ ItemUsePokeFlute:
 ; OUTPUT:
 ; [wWereAnyMonsAsleep]: set to 1 if any pokemon were asleep
 WakeUpEntireParty:
-	ld de, 44
-	ld c, 6
+	ld de, PARTYMON_STRUCT_LENGTH
+	ld c, PARTY_LENGTH
 .loop
 	ld a, [hl]
 	push af
@@ -1995,7 +1995,7 @@ ItemUsePPRestore:
 	ld a, [wPPRestoreItem]
 	cp ETHER
 	jr nc, .useEther ; if Ether or Max Ether
-.usePPUp
+; use PP Up
 	ld bc, MON_PP - MON_MOVES
 	add hl, bc
 	ld a, [hl] ; move PP

engine/link/cable_club.asm

@@ -673,7 +673,7 @@ TradeCenter_PrintPartyListNames:
 	pop de
 	inc de
 	pop hl
-	ld bc, 20
+	ld bc, SCREEN_WIDTH
 	add hl, bc
 	pop bc
 	inc c

engine/menus/main_menu.asm

@@ -495,6 +495,7 @@ DisplayOptionMenu:
 	jr nz, .exitMenu
 	bit B_PAD_A, b
 	jr z, .checkDirectionKeys
+; A was pressed
 	ld a, [wTopMenuItemY]
 	cp 16 ; is the cursor on Cancel?
 	jr nz, .loop
@@ -518,7 +519,7 @@ DisplayOptionMenu:
 	jr z, .cursorInBattleStyle
 	cp 16 ; cursor on Cancel?
 	jr z, .loop
-.cursorInTextSpeed
+; cursor in Text Speed
 	bit B_PAD_LEFT, b
 	jp nz, .pressedLeftInTextSpeed
 	jp .pressedRightInTextSpeed
@@ -625,7 +626,7 @@ SetOptionsFromCursorPositions:
 	ld a, [wOptionsBattleAnimCursorX] ; battle animation cursor X coordinate
 	dec a
 	jr z, .battleAnimationOn
-.battleAnimationOff
+; battle animation Off
 	set BIT_BATTLE_ANIMATION, d
 	jr .checkBattleStyle
 .battleAnimationOn
@@ -634,7 +635,7 @@ SetOptionsFromCursorPositions:
 	ld a, [wOptionsBattleStyleCursorX] ; battle style cursor X coordinate
 	dec a
 	jr z, .battleStyleShift
-.battleStyleSet
+; battle style Set
 	set BIT_BATTLE_SHIFT, d
 	jr .storeOptions
 .battleStyleShift

engine/menus/naming_screen.asm

@@ -379,12 +379,13 @@ PrintNicknameAndUnderscores:
 	hlcoord 10, 3
 	ld a, [wNamingScreenType]
 	cp NAME_MON_SCREEN
-	jr nc, .pokemon1
-	ld b, 7 ; player or rival max name length
-	jr .playerOrRival1
-.pokemon1
-	ld b, 10 ; pokemon max name length
-.playerOrRival1
+	jr nc, .pokemon
+; player or rival
+	ld b, PLAYER_NAME_LENGTH - 1
+	jr .gotUnderscoreCount
+.pokemon
+	ld b, NAME_LENGTH - 1
+.gotUnderscoreCount
 	ld a, $76 ; underscore tile id
 .placeUnderscoreLoop
 	ld [hli], a
@@ -394,13 +395,15 @@ PrintNicknameAndUnderscores:
 	cp NAME_MON_SCREEN
 	ld a, [wNamingScreenNameLength]
 	jr nc, .pokemon2
-	cp 7 ; player or rival max name length
-	jr .playerOrRival2
+; player or rival
+	cp PLAYER_NAME_LENGTH - 1
+	jr .checkEmptySpaces
 .pokemon2
-	cp 10 ; pokemon max name length
-.playerOrRival2
-	jr nz, .emptySpacesRemaining
-	; when all spaces are filled, force the cursor onto the ED tile
+	cp NAME_LENGTH - 1
+.checkEmptySpaces
+	jr nz, .placeRaisedUnderscore ; jump if empty spaces remain
+	; when all spaces are filled, force the cursor onto the ED tile,
+	; and keep the last underscore raised
 	call EraseMenuCursor
 	ld a, $11 ; "ED" x coord
 	ld [wTopMenuItemX], a
@@ -408,11 +411,10 @@ PrintNicknameAndUnderscores:
 	ld [wCurrentMenuItem], a
 	ld a, [wNamingScreenType]
 	cp NAME_MON_SCREEN
-	ld a, 9 ; keep the last underscore raised
-	jr nc, .pokemon3
-	ld a, 6 ; keep the last underscore raised
-.pokemon3
-.emptySpacesRemaining
+	ld a, NAME_LENGTH - 2
+	jr nc, .placeRaisedUnderscore
+	ld a, PLAYER_NAME_LENGTH - 2
+.placeRaisedUnderscore
 	ld c, a
 	ld b, $0
 	hlcoord 10, 3

engine/menus/party_menu.asm

@@ -90,7 +90,7 @@ RedrawPartyMenu_::
 	jr nz, .placeMoveLearnabilityString
 	ld de, .notAbleToLearnMoveText
 .placeMoveLearnabilityString
-	ld bc, 20 + 9 ; down 1 row and right 9 columns
+	ld bc, SCREEN_WIDTH + 9 ; 1 row down and 9 columns right
 	push hl
 	add hl, bc
 	call PlaceString
@@ -102,7 +102,7 @@ RedrawPartyMenu_::
 	pop hl
 	pop de
 	inc de
-	ld bc, 2 * 20
+	ld bc, 2 * SCREEN_WIDTH
 	add hl, bc
 	pop bc
 	inc c

engine/menus/pokedex.asm

@@ -105,7 +105,7 @@ HandlePokedexSideMenu:
 	jr z, .choseCry
 	dec a
 	jr z, .choseArea
-.choseQuit
+; chose Quit
 	ld b, 1
 .exitSideMenu
 	pop af
@@ -286,7 +286,7 @@ HandlePokedexListMenu:
 	call HandleMenuInput
 	bit B_PAD_B, a
 	jp nz, .buttonBPressed
-.checkIfUpPressed
+; check if Up pressed
 	bit B_PAD_UP, a
 	jr z, .checkIfDownPressed
 .upPressed ; scroll up one row
@@ -299,7 +299,7 @@ HandlePokedexListMenu:
 .checkIfDownPressed
 	bit B_PAD_DOWN, a
 	jr z, .checkIfRightPressed
-.downPressed ; scroll down one row
+; Down pressed, scroll down one row
 	ld a, [wDexMaxSeenMon]
 	cp 7
 	jp c, .loop ; can't if the list is shorter than 7
@@ -314,7 +314,7 @@ HandlePokedexListMenu:
 .checkIfRightPressed
 	bit B_PAD_RIGHT, a
 	jr z, .checkIfLeftPressed
-.rightPressed ; scroll down 7 rows
+; Right pressed, scroll down 7 rows
 	ld a, [wDexMaxSeenMon]
 	cp 7
 	jp c, .loop ; can't if the list is shorter than 7
@@ -332,7 +332,7 @@ HandlePokedexListMenu:
 .checkIfLeftPressed ; scroll up 7 rows
 	bit B_PAD_LEFT, a
 	jr z, .buttonAPressed
-.leftPressed
+; Left pressed
 	ld a, [wListScrollOffset]
 	sub 7
 	ld [wListScrollOffset], a
@@ -593,8 +593,8 @@ HeightWeightText:
 	db   "HT  ?′??″"
 	next "WT   ???lb@"
 
-; XXX does anything point to this?
-PokeText:
+; leftover from JPN Pokedex, where species have the suffix "Pokemon"
+PokeText: ; unreferenced
 	db "#@"
 
 ; horizontal line that divides the pokedex text description from the rest of the data

engine/menus/start_sub_menus.asm

@@ -340,7 +340,7 @@ StartMenu_Item::
 	ld a, [wCurItem]
 	cp BICYCLE
 	jp z, .useOrTossItem
-.notBicycle1
+; not Bicycle
 	ld a, USE_TOSS_MENU_TEMPLATE
 	ld [wTextBoxID], a
 	call DisplayTextBoxID
@@ -370,14 +370,14 @@ StartMenu_Item::
 	call CopyToStringBuffer
 	ld a, [wCurItem]
 	cp BICYCLE
-	jr nz, .notBicycle2
+	jr nz, .notBicycle
 	ld a, [wStatusFlags6]
 	bit BIT_ALWAYS_ON_BIKE, a
 	jr z, .useItem_closeMenu
 	ld hl, CannotGetOffHereText
 	call PrintText
 	jp ItemMenuLoop
-.notBicycle2
+.notBicycle
 	ld a, [wCurrentMenuItem]
 	and a
 	jr nz, .tossItem

engine/menus/swap_items.asm

@@ -76,7 +76,7 @@ HandleItemListSwapping::
 	ld a, [hli]
 	cp b
 	jr z, .swapSameItemType
-.swapDifferentItems
+; swap different items
 	ldh [hSwapItemID], a ; save second item ID
 	ld a, [hld]
 	ldh [hSwapItemQuantity], a ; save second item quantity

engine/movie/credits.asm

@@ -146,7 +146,10 @@ CreditsCopyTileMapToVRAM:
 	jp Delay3
 
 ZeroMemory:
-; zero bc bytes at hl
+; zero every second byte at hl, writing a total of bc bytes
+; When applied to VRAM font characters, it shifts their color index,
+; allowing palette-controlled text fade-in during the Credits roll,
+; while the black bars remain solid
 	ld [hl], 0
 	inc hl
 	inc hl

engine/overworld/auto_movement.asm

@@ -1,5 +1,6 @@
 PlayerStepOutFromDoor::
 	ld hl, wStatusFlags5 ; should this be wMovementFlags?
+	ASSERT BIT_EXITING_DOOR == BIT_UNKNOWN_5_1
 	res BIT_EXITING_DOOR, [hl]
 	call IsPlayerStandingOnDoorTile
 	jr nc, .notStandingOnDoor

engine/overworld/missable_objects.asm

@@ -178,10 +178,10 @@ MissableObjectFlagAction:
 	ld a, b
 	and a
 	jr z, .reset
-	cp 2
+	cp FLAG_TEST
 	jr z, .read
 
-.set
+; set
 	ld a, [hl]
 	ld b, a
 	ld a, d

engine/overworld/movement.asm

@@ -140,7 +140,7 @@ UpdateNPCSprite:
 	ld b, a
 	ld a, [wFontLoaded]
 	bit BIT_FONT_LOADED, a
-	jp nz, notYetMoving
+	jp nz, NotYetMoving
 	ld a, b
 	cp $2
 	jp z, UpdateSpriteMovementDelay  ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] == 2
@@ -389,14 +389,15 @@ UpdateSpriteMovementDelay:
 	jr .moving
 .tickMoveCounter
 	dec [hl]                ; x#SPRITESTATEDATA2_MOVEMENTDELAY
-	jr nz, notYetMoving
+	jr nz, NotYetMoving
 .moving
 	dec h
 	ldh a, [hCurrentSpriteOffset]
 	inc a
 	ld l, a
 	ld [hl], $1             ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = 1 (mark as ready to move)
-notYetMoving:
+	; fallthrough
+NotYetMoving:
 	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
 	add SPRITESTATEDATA1_ANIMFRAMECOUNTER
@@ -411,7 +412,7 @@ MakeNPCFacePlayer:
 ; disabled. This is only done when rubbing the S.S. Anne captain's back.
 	ld a, [wStatusFlags3]
 	bit BIT_NO_NPC_FACE_PLAYER, a
-	jr nz, notYetMoving
+	jr nz, NotYetMoving
 	res BIT_FACE_PLAYER, [hl]
 	ld a, [wPlayerDirection]
 	bit PLAYER_DIR_BIT_UP, a
@@ -435,7 +436,7 @@ MakeNPCFacePlayer:
 	add $9
 	ld l, a
 	ld [hl], c              ; [x#SPRITESTATEDATA1_FACINGDIRECTION]: set facing direction
-	jr notYetMoving
+	jr NotYetMoving
 
 InitializeSpriteStatus:
 	ld [hl], $1   ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = ready

engine/overworld/pathfinding.asm

@@ -94,7 +94,7 @@ CalcPositionOfPlayerRelativeToNPC:
 	ld a, [hli] ; NPC sprite screen Y position in pixels
 	call CalcDifference
 	jr nc, .NPCSouthOfOrAlignedWithPlayer
-.NPCNorthOfPlayer
+; NPC North of player
 	push hl
 	ld hl, hNPCPlayerRelativePosFlags
 	bit BIT_PLAYER_LOWER_Y, [hl]
@@ -122,7 +122,7 @@ CalcPositionOfPlayerRelativeToNPC:
 	ld a, [hl] ; NPC sprite screen X position in pixels
 	call CalcDifference
 	jr nc, .NPCEastOfOrAlignedWithPlayer
-.NPCWestOfPlayer
+; NPC West of player
 	push hl
 	ld hl, hNPCPlayerRelativePosFlags
 	bit BIT_PLAYER_LOWER_X, [hl]

engine/overworld/push_boulder.asm

@@ -43,7 +43,7 @@ TryPushingBoulder::
 	jr z, .pushBoulderLeft
 	cp SPRITE_FACING_RIGHT
 	jr z, .pushBoulderRight
-.pushBoulderDown
+; push boulder Down
 	bit B_PAD_DOWN, b
 	ret z
 	ld de, PushBoulderDownMovementData

engine/pokemon/add_mon.asm

@@ -375,7 +375,7 @@ _MoveMon::
 .copySpecies
 	ld [hli], a          ; write new mon ID
 	ld [hl], $ff         ; write new sentinel
-.findMonDataDest
+; find mon data dest
 	ld a, [wMoveMonType]
 	dec a
 	ld hl, wPartyMons
@@ -457,7 +457,7 @@ _MoveMon::
 	ld bc, NAME_LENGTH
 	call CopyData
 	ld a, [wMoveMonType]
-.findNickDest
+; find nick dest
 	cp PARTY_TO_DAYCARE
 	ld de, wDayCareMonName
 	jr z, .findNickSrc

engine/pokemon/load_mon_data.asm

@@ -31,7 +31,7 @@ LoadMonData_::
 	ld hl, wEnemyMons
 	jr z, .getMonEntry
 
-	cp 2
+	cp BOX_DATA
 	ld hl, wBoxMons
 	ld bc, BOXMON_STRUCT_LENGTH
 	jr z, .getMonEntry

home/joypad2.asm

@@ -25,7 +25,7 @@ JoypadLowSensitivity::
 	ldh a, [hJoyPressed] ; newly pressed buttons
 	and a ; have any buttons been newly pressed since last check?
 	jr z, .noNewlyPressedButtons
-.newlyPressedButtons
+; newly pressed buttons
 	ld a, 30 ; half a second delay
 	ldh [hFrameCounter], a
 	ret
@@ -33,7 +33,7 @@ JoypadLowSensitivity::
 	ldh a, [hFrameCounter]
 	and a ; is the delay over?
 	jr z, .delayOver
-.delayNotOver
+; delay not over
 	xor a
 	ldh [hJoy5], a ; report no buttons as pressed
 	ret

home/list_menu.asm

@@ -65,7 +65,7 @@ DisplayListMenuIDLoop::
 	ld a, [wBattleType]
 	and a ; is it the Old Man battle?
 	jr z, .notOldManBattle
-.oldManBattle
+; Old Man battle
 	ld a, '▶'
 	ldcoord_a 5, 4 ; place menu cursor in front of first menu entry
 	ld c, 80
@@ -178,7 +178,7 @@ DisplayListMenuIDLoop::
 	bit B_PAD_DOWN, b
 	ld hl, wListScrollOffset
 	jr z, .upPressed
-.downPressed
+; Down pressed
 	ld a, [hl]
 	add 3
 	ld b, a
@@ -380,7 +380,7 @@ PrintListMenuEntries::
 	jr z, .pokemonPCMenu
 	cp MOVESLISTMENU
 	jr z, .movesMenu
-.itemMenu
+; item menu
 	call GetItemName
 	jr .placeNameString
 .pokemonPCMenu
@@ -411,7 +411,7 @@ PrintListMenuEntries::
 	ld a, [wPrintItemPrices]
 	and a ; should prices be printed?
 	jr z, .skipPrintingItemPrice
-.printItemPrice
+; print item price
 	push hl
 	ld a, [de]
 	ld de, ItemPrices
@@ -426,7 +426,7 @@ PrintListMenuEntries::
 	ld a, [wListMenuID]
 	and a ; PCPOKEMONLISTMENU?
 	jr nz, .skipPrintingPokemonLevel
-.printPokemonLevel
+; print Pokemon level
 	ld a, [wNamedObjectIndex]
 	push af
 	push hl
@@ -451,7 +451,7 @@ PrintListMenuEntries::
 	ld a, [wMonDataLocation]
 	and a ; is it a list of party pokemon or box pokemon?
 	jr z, .skipCopyingLevel
-.copyLevel
+; copy level
 	ld a, [wLoadedMonBoxLevel]
 	ld [wLoadedMonLevel], a
 .skipCopyingLevel
@@ -468,7 +468,7 @@ PrintListMenuEntries::
 	ld a, [wListMenuID]
 	cp ITEMLISTMENU
 	jr nz, .nextListEntry
-.printItemQuantity
+; print item quantity
 	ld a, [wNamedObjectIndex]
 	ld [wCurItem], a
 	call IsKeyItem ; check if item is unsellable

home/load_font.asm

@@ -2,7 +2,7 @@ LoadFontTilePatterns::
 	ldh a, [rLCDC]
 	bit B_LCDC_ENABLE, a
 	jr nz, .on
-.off
+; off
 	ld hl, FontGraphics
 	ld de, vFont
 	ld bc, FontGraphicsEnd - FontGraphics
@@ -18,7 +18,7 @@ LoadTextBoxTilePatterns::
 	ldh a, [rLCDC]
 	bit B_LCDC_ENABLE, a
 	jr nz, .on
-.off
+; off
 	ld hl, TextBoxGraphics
 	ld de, vChars2 tile $60
 	ld bc, TextBoxGraphicsEnd - TextBoxGraphics
@@ -34,7 +34,7 @@ LoadHpBarAndStatusTilePatterns::
 	ldh a, [rLCDC]
 	bit B_LCDC_ENABLE, a
 	jr nz, .on
-.off
+; off
 	ld hl, HpBarAndStatusGraphics
 	ld de, vChars2 tile $62
 	ld bc, HpBarAndStatusGraphicsEnd - HpBarAndStatusGraphics

home/map_objects.asm

@@ -115,7 +115,7 @@ CheckCoords::
 	ld hl, wCoordIndex
 	inc [hl]
 	pop hl
-.compareYCoord
+; compare Y coord
 	cp b
 	jr z, .compareXCoord
 	inc hl
@@ -124,7 +124,7 @@ CheckCoords::
 	ld a, [hli]
 	cp c
 	jr nz, .loop
-.inArray
+; in array
 	scf
 	ret
 .notInArray

home/move_mon.asm

@@ -106,7 +106,7 @@ CalcStat::
 	jr z, .getSpeedIV
 	cp $5
 	jr z, .getSpecialIV
-.getHpIV
+; get HP IV
 	push bc
 	ld a, [hl]  ; Atk IV
 	swap a

home/overworld.asm

@@ -546,7 +546,7 @@ ContinueCheckWarpsNoCollisionLoop::
 
 ; if no matching warp was found
 CheckMapConnections::
-.checkWestMap
+; check West map
 	ld a, [wXCoord]
 	cp $ff
 	jr nz, .checkEastMap
@@ -1097,8 +1097,7 @@ IsSpriteOrSignInFrontOfPlayer::
 	ld a, [hli] ; sign X
 	cp e
 	jr nz, .retry
-.xCoordMatched
-; found sign
+; X coord matched: found sign
 	push hl
 	push bc
 	ld hl, wSignTextIDs
@@ -2047,7 +2046,7 @@ LoadMapHeader::
 ; copy connection data (if any) to WRAM
 	ld a, [wCurMapConnections]
 	ld b, a
-.checkNorth
+; check North
 	bit NORTH_F, b
 	jr z, .checkSouth
 	ld de, wNorthConnectionHeader
@@ -2080,7 +2079,7 @@ LoadMapHeader::
 	ld de, wMapBackgroundTile
 	ld a, [hli]
 	ld [de], a
-.loadWarpData
+; load warp data
 	ld a, [hli]
 	ld [wNumberOfWarps], a
 	and a

home/print_bcd.asm

@@ -31,9 +31,9 @@ PrintBCDNumber::
 	inc de
 	dec c
 	jr nz, .loop
-	bit BIT_LEADING_ZEROES, b
+	bit BIT_LEADING_ZEROES, b ; were any non-zero digits printed?
 	jr z, .done ; if so, we are done
-.numberEqualsZero ; if every digit of the BCD number is zero
+; if every digit of the BCD number is zero, print the last 0
 	bit BIT_LEFT_ALIGN, b
 	jr nz, .skipRightAlignmentAdjustment
 	dec hl ; if the string is right-aligned, it needs to be moved back one space

home/print_num.asm

@@ -82,7 +82,8 @@ MACRO print_digit
 	call .NextDigit
 ENDM
 
-.millions          print_digit 1000000
+; millions
+                   print_digit 1000000
 .hundred_thousands print_digit 100000
 .ten_thousands     print_digit 10000
 .thousands         print_digit 1000
@@ -113,7 +114,7 @@ ENDM
 .next
 
 	call .NextDigit
-.ones
+; ones
 	ld a, '0'
 	add b
 	ld [hli], a

home/print_text.asm

@@ -24,7 +24,7 @@ PrintLetterDelay::
 .checkButtons
 	call Joypad
 	ldh a, [hJoyHeld]
-.checkAButton
+; check A button
 	bit B_PAD_A, a
 	jr z, .checkBButton
 	jr .endWait

home/start_menu.asm

@@ -14,7 +14,7 @@ RedisplayStartMenu::
 .loop
 	call HandleMenuInput
 	ld b, a
-.checkIfUpPressed
+; check if Up pressed
 	bit B_PAD_UP, a
 	jr z, .checkIfDownPressed
 	ld a, [wCurrentMenuItem] ; menu selection

home/trainers.asm

@@ -19,7 +19,7 @@ ExecuteCurMapScriptInTable::
 	ld hl, wStatusFlags7
 	bit BIT_USE_CUR_MAP_SCRIPT, [hl]
 	res BIT_USE_CUR_MAP_SCRIPT, [hl]
-	jr z, .useProvidedIndex   ; test if map script index was overridden manually
+	jr z, .useProvidedIndex ; test if map script index was overridden manually
 	ld a, [wCurMapScript]
 .useProvidedIndex
 	pop hl
@@ -32,11 +32,11 @@ LoadGymLeaderAndCityName::
 	push de
 	ld de, wGymCityName
 	ld bc, GYM_CITY_LENGTH
-	call CopyData   ; load city name
+	call CopyData ; load city name
 	pop hl
 	ld de, wGymLeaderName
 	ld bc, NAME_LENGTH
-	jp CopyData     ; load gym leader name
+	jp CopyData   ; load gym leader name
 
 ; reads specific information from trainer header (pointed to at wTrainerHeaderPtr)
 ; a: offset in header data
@@ -155,7 +155,7 @@ ENDC
 	ldh [hJoyHeld], a
 	call TrainerWalkUpToPlayer_Bank0
 	ld hl, wCurMapScript
-	inc [hl]      ; increment map script index (next script function is usually DisplayEnemyTrainerTextAndStartBattle)
+	inc [hl] ; increment map script index (next script function is usually DisplayEnemyTrainerTextAndStartBattle)
 	ret
 
 ; display the before battle text after the enemy trainer has walked up to the player's sprite
@@ -179,7 +179,7 @@ StartTrainerBattle::
 	ld hl, wStatusFlags4
 	set BIT_UNKNOWN_4_1, [hl]
 	ld hl, wCurMapScript
-	inc [hl]        ; increment map script index (next script function is usually EndTrainerBattle)
+	inc [hl] ; increment map script index (next script function is usually EndTrainerBattle)
 	ret
 
 EndTrainerBattle::
@@ -201,14 +201,14 @@ EndTrainerBattle::
 	call TrainerFlagAction   ; flag trainer as fought
 	ld a, [wEnemyMonOrTrainerClass]
 	cp OPP_ID_OFFSET
-	jr nc, .skipRemoveSprite    ; test if trainer was fought (in that case skip removing the corresponding sprite)
+	jr nc, .skipRemoveSprite ; test if trainer was fought (in that case skip removing the corresponding sprite)
 	ld hl, wMissableObjectList
 	ld de, $2
 	ld a, [wSpriteIndex]
-	call IsInArray              ; search for sprite ID
+	call IsInArray ; search for sprite ID
 	inc hl
 	ld a, [hl]
-	ld [wMissableObjectIndex], a               ; load corresponding missable object index and remove it
+	ld [wMissableObjectIndex], a ; load corresponding missable object index and remove it
 	predef HideObject
 .skipRemoveSprite
 	ld hl, wStatusFlags5
@@ -269,7 +269,7 @@ CheckForEngagingTrainers::
 .trainerLoop
 	call StoreTrainerHeaderPointer   ; set trainer header pointer to current trainer
 	ld a, [de]
-	ld [wSpriteIndex], a                     ; store trainer flag's bit
+	ld [wSpriteIndex], a             ; store trainer flag's bit
 	ld [wTrainerHeaderFlagBit], a
 	cp -1
 	ret z
@@ -278,7 +278,7 @@ CheckForEngagingTrainers::
 	ld b, FLAG_TEST
 	ld a, [wTrainerHeaderFlagBit]
 	ld c, a
-	call TrainerFlagAction        ; read trainer flag
+	call TrainerFlagAction           ; read trainer flag
 	ld a, c
 	and a ; has the trainer already been defeated?
 	jr nz, .continue
@@ -299,7 +299,7 @@ CheckForEngagingTrainers::
 	pop hl
 	ld a, [wTrainerSpriteOffset]
 	and a
-	ret nz        ; break if the trainer is engaging
+	ret nz ; break if the trainer is engaging
 .continue
 	ld hl, $c
 	add hl, de
@@ -364,8 +364,8 @@ PrintEndBattleText::
 GetSavedEndBattleTextPointer::
 	ld a, [wBattleResult]
 	and a
-; won battle
 	jr nz, .lostBattle
+; won battle
 	ld a, [wEndBattleWinTextPointer]
 	ld h, a
 	ld a, [wEndBattleWinTextPointer + 1]

home/window.asm

@@ -52,11 +52,11 @@ HandleMenuInput_::
 	ld b, a
 	bit B_PAD_UP, a
 	jr z, .checkIfDownPressed
-.upPressed
+; Up pressed
 	ld a, [wCurrentMenuItem] ; selected menu item
 	and a ; already at the top of the menu?
 	jr z, .alreadyAtTop
-.notAtTop
+; not at top
 	dec a
 	ld [wCurrentMenuItem], a ; move selected menu item up one space
 	jr .checkOtherKeys
@@ -70,14 +70,14 @@ HandleMenuInput_::
 .checkIfDownPressed
 	bit B_PAD_DOWN, a
 	jr z, .checkOtherKeys
-.downPressed
+; Down pressed
 	ld a, [wCurrentMenuItem]
 	inc a
 	ld c, a
 	ld a, [wMaxMenuItem]
 	cp c
 	jr nc, .notAtBottom
-.alreadyAtBottom
+; already at bottom
 	ld a, [wMenuWrappingEnabled]
 	and a ; is wrapping around enabled?
 	jr z, .noWrappingAround
@@ -93,7 +93,7 @@ HandleMenuInput_::
 	ldh a, [hJoy5]
 	and PAD_A | PAD_B
 	jr z, .skipPlayingSound
-.AButtonOrBButtonPressed
+; A or B pressed
 	push hl
 	ld hl, wMiscFlags
 	bit BIT_NO_MENU_BUTTON_SOUND, [hl]
@@ -153,7 +153,7 @@ PlaceMenuCursor::
 	ld a, [hl]
 	cp '▶' ; was an arrow next to the previously selected menu item?
 	jr nz, .skipClearingArrow
-.clearArrow
+; clear arrow
 	ld a, [wTileBehindCursor]
 	ld [hl], a
 .skipClearingArrow

macros/scripts/events.asm

@@ -343,7 +343,7 @@ MACRO ResetEventRange
 		IF event_fill_count > 1
 			ld hl, wEventFlags + event_fill_start
 
-			; force xor a if we just to wrote to it above
+			; force xor a if we just wrote to it above
 			IF (_NARG < 3) || (((\1) % 8) != 0)
 				xor a
 			ENDC

scripts/BillsHouse.asm

@@ -82,13 +82,13 @@ BillsHouseBillExitsMachineScript:
 	call DelayFrames
 	ld a, BILLSHOUSE_BILL1
 	ldh [hSpriteIndex], a
-	ld de, BillExitMachineMovement
+	ld de, .BillExitMachineMovement
 	call MoveSprite
 	ld a, SCRIPT_BILLSHOUSE_CLEANUP
 	ld [wBillsHouseCurScript], a
 	ret
 
-BillExitMachineMovement:
+.BillExitMachineMovement:
 	db NPC_MOVEMENT_DOWN
 	db NPC_MOVEMENT_RIGHT
 	db NPC_MOVEMENT_RIGHT

scripts/Colosseum.asm

@@ -1,4 +1,5 @@
 Colosseum_Script:
+	ASSERT TRADECENTER_OPPONENT == COLOSSEUM_OPPONENT
 	jp TradeCenter_Script
 
 Colosseum_TextPointers: