Miscellaneous cleanup (#488)

Co-authored-by: SatoMew <SatoMew@users.noreply.github.com>

data/predef_pointers.asm

@@ -61,7 +61,7 @@ PredefPointers::
 	add_predef BattleTransition
 	add_predef CopyTileIDsFromList
 	add_predef PlayIntro
-	add_predef GetMoveSoundB
+	add_predef GetIntroMoveSound
 	add_predef FlashScreen
 	add_predef GetTileAndCoordsInFrontOfPlayer
 	add_predef StatusScreen

engine/battle/animations.asm

@@ -2187,8 +2187,8 @@ AnimCopyRowRight:
 	jr nz, AnimCopyRowRight
 	ret
 
-; get the sound of the move id in b
-GetMoveSoundB:
+; only used by the unreferenced PlayIntroMoveSound
+GetIntroMoveSound:
 	ld a, b
 	call GetMoveSound
 	ld b, a

engine/battle/core.asm

@@ -2015,6 +2015,7 @@ DisplayBattleMenu::
 	call DisplayTextBoxID
  ; handle menu input if it's not the old man tutorial
 	ld a, [wBattleType]
+	ASSERT BATTLE_TYPE_OLD_MAN == 1
 	dec a
 	jp nz, .handleBattleMenuInput
 ; the following happens for the old man tutorial

engine/battle/trainer_ai.asm

@@ -635,7 +635,7 @@ AICureStatus:
 	res BADLY_POISONED, [hl]
 	ret
 
-AIUseXAccuracy: ; unused
+AIUseXAccuracy: ; unreferenced
 	call AIPlayRestoringSFX
 	ld hl, wEnemyBattleStatus2
 	set USING_X_ACCURACY, [hl]
@@ -649,7 +649,7 @@ AIUseGuardSpec:
 	ld a, GUARD_SPEC
 	jp AIPrintItemUse
 
-AIUseDireHit: ; unused
+AIUseDireHit: ; unreferenced
 	call AIPlayRestoringSFX
 	ld hl, wEnemyBattleStatus2
 	set GETTING_PUMPED, [hl]

engine/debug/debug_party.asm

@@ -92,7 +92,7 @@ IF DEF(_DEBUG)
 
 	; Get some debug items.
 	ld hl, wNumBagItems
-	ld de, DebugItemsList
+	ld de, DebugNewGameItemsList
 .items_loop
 	ld a, [de]
 	cp -1
@@ -116,9 +116,10 @@ IF DEF(_DEBUG)
 	; Rival chose Squirtle,
 	; Player chose Charmander.
 	ld hl, wRivalStarter
+	ASSERT wRivalStarter + 2 == wPlayerStarter
 	ld a, STARTER2
 	ld [hli], a
-	inc hl ; hl = wPlayerStarter
+	inc hl
 	ld a, STARTER1
 	ld [hl], a
 
@@ -134,7 +135,7 @@ DebugSetPokedexEntries:
 	ld [hl], %01111111
 	ret
 
-DebugItemsList:
+DebugNewGameItemsList:
 	db BICYCLE, 1
 	db FULL_RESTORE, 99
 	db FULL_HEAL, 99
@@ -148,7 +149,7 @@ DebugItemsList:
 	db LIFT_KEY, 1
 	db -1 ; end
 
-DebugUnusedList:
+DebugUnusedList: ; unreferenced
 	db -1 ; end
 ELSE
 	ret

engine/events/evolve_trade.asm

@@ -1,4 +1,4 @@
-EvolveTradeMon:
+InGameTrade_CheckForTradeEvo:
 ; Verify the TradeMon's species name before
 ; attempting to initiate a trade evolution.
 
@@ -34,7 +34,7 @@ EvolveTradeMon:
 	ld a, [wPartyCount]
 	dec a
 	ld [wWhichPokemon], a
-	ld a, $1
+	ld a, TRUE
 	ld [wForceEvolution], a
 	ld a, LINK_STATE_TRADING
 	ld [wLinkState], a

engine/events/hidden_objects/vermilion_gym_trash.asm

@@ -47,7 +47,7 @@ GymTrashScript:
 	add hl, de
 	ld a, [hli]
 
-; There is a bug in this code. It should calculate a value in the range [0, 3]
+; Bug: This code should calculate a value in the range [0, 3],
 ; but if the mask and random number don't have any 1 bits in common, then
 ; the result of the AND will be 0. When 1 is subtracted from that, the value
 ; will become $ff. This will result in 255 being added to hl, which will cause

engine/events/in_game_trades.asm

@@ -137,7 +137,7 @@ InGameTrade_DoTrade:
 	ld [wMonDataLocation], a
 	call AddPartyMon
 	call InGameTrade_CopyDataToReceivedMon
-	callfar EvolveTradeMon
+	callfar InGameTrade_CheckForTradeEvo
 	call ClearScreen
 	call InGameTrade_RestoreScreen
 	farcall RedrawMapView

engine/items/item_effects.asm

@@ -468,7 +468,7 @@ ItemUseBall:
 
 	push hl
 
-; If the Pokémon is transformed, the Pokémon is assumed to be a Ditto.
+; Bug: If the Pokémon is transformed, the Pokémon is assumed to be a Ditto.
 ; This is a bug because a wild Pokémon could have used Transform via
 ; Mirror Move even though the only wild Pokémon that knows Transform is Ditto.
 	ld hl, wEnemyBattleStatus3
@@ -774,7 +774,7 @@ ItemUseEvoStone:
 	jr c, .canceledItemUse
 	ld a, b
 	ld [wCurPartySpecies], a
-	ld a, $01
+	ld a, TRUE
 	ld [wForceEvolution], a
 	ld a, SFX_HEAL_AILMENT
 	call PlaySoundWaitForCurrent
@@ -2077,10 +2077,10 @@ ItemUsePPRestore:
 	ret
 .fullyRestorePP
 	ld a, [hl] ; move PP
-; Note that this code has a bug. It doesn't mask out the upper two bits, which
-; are used to count how many PP Ups have been used on the move. So, Max Ethers
-; and Max Elixirs will not be detected as having no effect on a move with full
-; PP if the move has had any PP Ups used on it.
+; Bug: This code doesn't mask out the upper two bits, which are used to count
+; how many PP Ups have been used on the move.
+; So, Max Ethers and Max Elixirs will not be detected as having no effect on
+; a move with full PP if the move has had any PP Ups used on it.
 	cp b ; does current PP equal max PP?
 	ret z
 	jr .storeNewAmount

engine/link/cable_club.asm

@@ -57,8 +57,8 @@ CableClub_DoBattleOrTradeAgain:
 	ld [hli], a
 	dec b
 	jr nz, .zeroPlayerDataPatchListLoop
-	ld hl, wGrassRate
-	ld bc, wTrainerHeaderPtr - wGrassRate
+	ld hl, wLinkEnemyTrainerName
+	ld bc, wTrainerHeaderPtr - wLinkEnemyTrainerName
 .zeroEnemyPartyLoop
 	xor a
 	ld [hli], a
@@ -818,7 +818,7 @@ TradeCenter_Trade:
 	ld a, [wPartyCount]
 	dec a
 	ld [wWhichPokemon], a
-	ld a, $1
+	ld a, TRUE
 	ld [wForceEvolution], a
 	ld a, [wTradingWhichEnemyMon]
 	ld hl, wEnemyPartySpecies

engine/movie/intro.asm

@@ -275,9 +275,8 @@ CopyTileIDsFromList_ZeroBaseTileID:
 	ld c, 0
 	predef_jump CopyTileIDsFromList
 
-PlayMoveSoundB:
-; unused
-	predef GetMoveSoundB
+PlayIntroMoveSound: ; unreferenced
+	predef GetIntroMoveSound
 	ld a, b
 	jp PlaySound
 
@@ -325,6 +324,7 @@ PlayShootingStar:
 	call DelayFrames
 	farcall AnimateShootingStar
 	push af
+	; A `call LoadPresentsGraphic` here was removed in localization
 	pop af
 	jr c, .next ; skip the delay if the user interrupted the animation
 	ld c, 40
@@ -356,7 +356,11 @@ IntroDrawBlackBars:
 	ld c,  BG_MAP_WIDTH * 4
 	jp IntroPlaceBlackTiles
 
-EmptyFunc2:
+LoadPresentsGraphic: ; unreferenced
+	; This routine loaded the "PRESENTS" text graphic (tiles
+	; $67, $68, $69, $6A, $6B, and $6C from gamefreak_presents.2bpp)
+	; at coordinates (11, 7) in the Japanese versions.
+	; It was dummied out in the English localization.
 	ret
 
 IntroNidorinoAnimation0:

engine/movie/title.asm

@@ -1,4 +1,4 @@
-CopyDebugName: ; unused
+CopyDebugName:
 	ld bc, NAME_LENGTH
 	jp CopyData
 

engine/pokemon/evos_moves.asm

@@ -94,8 +94,10 @@ Evolution_PartyMonLoop: ; loop over party mons
 	jr .doEvolution
 .checkItemEvo
 	ld a, [hli]
+	; Bug: Wild encounters can cause stone evolutions without
+	; having any stones available. This was fixed in Yellow.
 	ld b, a ; evolution item
-	ld a, [wCurItem]
+	ld a, [wCurItem] ; same as [wCurPartySpecies]
 	cp b ; was the evolution item in this entry used?
 	jp nz, .nextEvoEntry1 ; if not, go to the next evolution entry
 .checkLevel

engine/slots/slot_machine.asm

@@ -298,8 +298,8 @@ SlotMachine_StopWheel1Early:
 	cp HIGH(SLOTSCHERRY)
 	jr nz, .stopWheel
 	ret
-; It looks like this was intended to make the wheel stop when a 7 symbol was
-; visible, but it has a bug and so the wheel stops randomly.
+; Bug: This looks intended to make the wheel stop when a
+; 7 symbol was visible, but instead the wheel stops randomly.
 .sevenAndBarMode
 	ld c, $3
 .loop

home/pokemon.asm

@@ -114,7 +114,11 @@ LoadFrontSpriteByMonIndex::
 	cp NUM_POKEMON + 1
 	jr c, .validDexNumber   ; dex >#151 invalid
 .invalidDexNumber
-	ld a, RHYDON ; $1
+	; This is the so-called "Rhydon trap" or "Rhydon glitch"
+	; to fail-safe invalid dex numbers
+	; (see https://glitchcity.wiki/wiki/Rhydon_trap
+	; or https://bulbapedia.bulbagarden.net/wiki/Rhydon_glitch)
+	ld a, RHYDON
 	ld [wCurPartySpecies], a
 	ret
 .validDexNumber

home/text.asm

@@ -111,7 +111,7 @@ NextChar::
 	inc de
 	jp PlaceNextChar
 
-NullChar:: ; unused
+NullChar::
 	ld b, h
 	ld c, l
 	pop hl

home/yes_no.asm

@@ -26,7 +26,7 @@ YesNoChoicePokeCenter::
 	lb bc, 8, 12
 	jr DisplayYesNoChoice
 
-WideYesNoChoice:: ; unused
+WideYesNoChoice:: ; unreferenced
 	call SaveScreenTilesToBuffer1
 	ld a, WIDE_YES_NO_MENU
 	ld [wTwoOptionMenuID], a

scripts/HallOfFame.asm

@@ -33,7 +33,7 @@ HallOfFameResetEventsAndSaveScript:
 	res BIT_NO_MAP_MUSIC, [hl]
 	assert wStatusFlags7 + 1 == wElite4Flags
 	inc hl
-	set BIT_UNUSED_BEAT_ELITE_4, [hl] ; debug, unused?
+	set BIT_UNUSED_BEAT_ELITE_4, [hl] ; unused
 	xor a ; SCRIPT_*_DEFAULT
 	ld hl, wLoreleisRoomCurScript
 	ld [hli], a ; wLoreleisRoomCurScript