Clean up bugs commented in the source code (#912)

Co-authored-by: Rangi <remy.oukaour+rangi42@gmail.com>

data/battle/ai/sunny_day_moves.asm

@@ -1,6 +1,7 @@
 ; AI_SMART prefers these moves during harsh sunlight.
 
 SunnyDayMoves:
+; BUG: "Smart" AI does not encourage Solar Beam, Flame Wheel, or Moonlight during Sunny Day (see docs/bugs_and_glitches.md)
 	db FIRE_PUNCH
 	db EMBER
 	db FLAMETHROWER

data/events/happiness_probabilities.asm

@@ -9,4 +9,5 @@ HappinessData_YoungerHaircutBrother:
 	db -1,             4, HAPPINESS_YOUNGCUT3 ; 10% chance
 
 HappinessData_DaisysGrooming:
+; BUG: Daisy's grooming doesn't always increase happiness (see docs/bugs_and_glitches.md)
 	db -1,             2, HAPPINESS_GROOMING ; 99.6% chance

data/items/attributes.asm

@@ -294,6 +294,7 @@ ItemAttributes:
 	item_attribute $9999, HELD_NONE, 0, NO_LIMITS, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
 ; METAL_COAT
 	item_attribute 100, HELD_STEEL_BOOST, 10, CANT_SELECT, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
+; BUG: Dragon Scale, not Dragon Fang, boosts Dragon-type moves (see docs/bugs_and_glitches.md)
 ; DRAGON_FANG
 	item_attribute 100, HELD_NONE, 0, CANT_SELECT, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
 ; ITEM_91

data/moves/effects.asm

@@ -575,7 +575,8 @@ DefenseDownHit:
 	supereffectivetext
 	checkfaint
 	buildopponentrage
-	effectchance ; bug: duplicate effectchance shouldn't be here
+; BUG: Moves that lower Defense can do so after breaking a Substitute (see docs/bugs_and_glitches.md)
+	effectchance
 	defensedown
 	statdownmessage
 	endmove
@@ -706,6 +707,7 @@ DefenseUpHit:
 	applydamage
 	criticaltext
 	supereffectivetext
+; BUG: Moves that do damage and increase your stats do not increase stats after a KO (see docs/bugs_and_glitches.md)
 	checkfaint
 	buildopponentrage
 	defenseup

data/text/common_2.asm

@@ -100,6 +100,7 @@ Text_Gained::
 	text_end
 
 _BoostedExpPointsText::
+; BUG: Five-digit experience gain is printed incorrectly (see docs/bugs_and_glitches.md)
 	text_start
 	line "a boosted"
 	cont "@"
@@ -108,6 +109,7 @@ _BoostedExpPointsText::
 	prompt
 
 _ExpPointsText::
+; BUG: Five-digit experience gain is printed incorrectly (see docs/bugs_and_glitches.md)
 	text_start
 	line "@"
 	text_decimal wStringBuffer2, 2, 4

data/trainers/dvs.asm

@@ -43,6 +43,7 @@ TrainerClassDVs:
 	dn  7,  8,  8,  8 ; SWIMMERF
 	dn  9,  8,  8,  8 ; SAILOR
 	dn  9,  8,  8,  8 ; SUPER_NERD
+; BUG: RIVAL2 has lower DVs than RIVAL1 (see docs/bugs_and_glitches.md)
 	dn  9,  8,  8,  8 ; RIVAL2
 	dn  9,  8,  8,  8 ; GUITARIST
 	dn 10,  8,  8,  8 ; HIKER

engine/battle/ai/items.asm

@@ -552,6 +552,7 @@ EnemyUsedMaxPotion:
 	jr FullRestoreContinue
 
 EnemyUsedFullRestore:
+; BUG: AI use of Full Heal does not cure confusion status (see docs/bugs_and_glitches.md)
 	call AI_HealStatus
 	ld a, FULL_RESTORE
 	ld [wCurEnemyItem], a
@@ -559,6 +560,7 @@ EnemyUsedFullRestore:
 	res SUBSTATUS_CONFUSED, [hl]
 	xor a
 	ld [wEnemyConfuseCount], a
+	; fallthrough
 
 FullRestoreContinue:
 	ld de, wCurHPAnimOldHP
@@ -725,6 +727,7 @@ EnemyUsedFullHealRed: ; unreferenced
 	jp PrintText_UsedItemOn_AND_AIUpdateHUD
 
 AI_HealStatus:
+; BUG: AI use of Full Heal or Full Restore does not cure Nightmare status (see docs/bugs_and_glitches.md)
 	ld a, [wCurOTMon]
 	ld hl, wOTPartyMon1Status
 	ld bc, PARTYMON_STRUCT_LENGTH
@@ -732,14 +735,6 @@ AI_HealStatus:
 	xor a
 	ld [hl], a
 	ld [wEnemyMonStatus], a
-	; Bug: this should reset SUBSTATUS_NIGHTMARE
-	; Uncomment the 2 lines below to fix
-	; ld hl, wEnemySubStatus1
-	; res SUBSTATUS_NIGHTMARE, [hl]
-	; Bug: this should reset SUBSTATUS_CONFUSED
-	; Uncomment the 2 lines below to fix
-	; ld hl, wEnemySubStatus3
-	; res SUBSTATUS_CONFUSED, [hl]
 	ld hl, wEnemySubStatus5
 	res SUBSTATUS_TOXIC, [hl]
 	ret

engine/battle/ai/redundant.asm

@@ -176,6 +176,7 @@ AI_Redundant:
 	ret
 
 .FutureSight:
+; BUG: AI does not discourage Future Sight when it's already been used (see docs/bugs_and_glitches.md)
 	ld a, [wEnemyScreens]
 	bit 5, a
 	ret

engine/battle/ai/scoring.asm

@@ -1665,9 +1665,10 @@ AI_Smart_Thief:
 	ret
 
 AI_Smart_Conversion2:
+; BUG: "Smart" AI discourages Conversion2 after the first turn (see docs/bugs_and_glitches.md)
 	ld a, [wLastPlayerMove]
 	and a
-	jr nz, .discourage ; should be jr z
+	jr nz, .discourage
 
 	push hl
 	dec a
@@ -1743,8 +1744,8 @@ AI_Smart_MeanLook:
 	pop hl
 	jp z, AIDiscourageMove
 
-; 80% chance to greatly encourage this move if the enemy is badly poisoned (buggy).
+; 80% chance to greatly encourage this move if the enemy is badly poisoned.
-; Should check wPlayerSubStatus5 instead.
+; BUG: "Smart" AI encourages Mean Look if its own Pokémon is badly poisoned (see docs/bugs_and_glitches.md)
 	ld a, [wEnemySubStatus5]
 	bit SUBSTATUS_TOXIC, a
 	jr nz, .encourage

engine/battle/anim_hp_bar.asm

@@ -179,16 +179,12 @@ LongAnim_UpdateVariables:
 	ld c, a
 	ld a, [hli]
 	ld b, a
-	; This routine is buggy. The result from ComputeHPBarPixels is stored
+; BUG: HP bar animation is slow for high HP (see docs/bugs_and_glitches.md)
-	; in e. However, the pop de opcode deletes this result before it is even
-	; used. The game then proceeds as though it never deleted that output.
-	; To fix, uncomment the line below.
 	call ComputeHPBarPixels
-	; ld a, e
 	pop bc
 	pop de
 	pop hl
-	ld a, e ; Comment or delete this line to fix the above bug.
+	ld a, e
 	ld hl, wCurHPBarPixels
 	cp [hl]
 	jr z, .loop
@@ -373,17 +369,14 @@ ShortHPBar_CalcPixelFrame:
 	call AddNTimes
 
 	ld b, 0
-; This routine is buggy. If [wCurHPAnimMaxHP] * [wCurHPBarPixels] is
-; divisible by HP_BAR_LENGTH_PX, the loop runs one extra time.
-; To fix, uncomment the line below.
 .loop
+; BUG: HP bar animation off-by-one error for low HP (see docs/bugs_and_glitches.md)
 	ld a, l
 	sub HP_BAR_LENGTH_PX
 	ld l, a
 	ld a, h
 	sbc $0
 	ld h, a
-	; jr z, .done
 	jr c, .done
 	inc b
 	jr .loop

engine/battle/battle_transition.asm

@@ -214,8 +214,7 @@ DEF TRANS_NO_CAVE_F  EQU 1 ; bit set in TRANS_NO_CAVE and TRANS_NO_CAVE_STRONGER
 StartTrainerBattle_DetermineWhichAnimation:
 ; The screen flashes a different number of times depending on the level of
 ; your lead Pokemon relative to the opponent's.
-; BUG: wBattleMonLevel and wEnemyMonLevel are not set at this point, so whatever
+; BUG: Battle transitions fail to account for enemy's level (see docs/bugs_and_glitches.md)
-; values happen to be there will determine the animation.
 	ld de, 0
 	ld a, [wBattleMonLevel]
 	add 3

engine/battle/core.asm

@@ -295,6 +295,7 @@ HandleBetweenTurnEffects:
 	jp HandleEncore
 
 CheckFaint_PlayerThenEnemy:
+; BUG: Perish Song and Spikes can leave a Pokemon with 0 HP and not faint (see docs/bugs_and_glitches.md)
 	call HasPlayerFainted
 	jr nz, .PlayerNotFainted
 	call HandlePlayerMonFaint
@@ -319,6 +320,7 @@ CheckFaint_PlayerThenEnemy:
 	ret
 
 CheckFaint_EnemyThenPlayer:
+; BUG: Perish Song and Spikes can leave a Pokemon with 0 HP and not faint (see docs/bugs_and_glitches.md)
 	call HasEnemyFainted
 	jr nz, .EnemyNotFainted
 	call HandleEnemyMonFaint
@@ -387,6 +389,7 @@ HandleBerserkGene:
 	call GetPartyLocation
 	xor a
 	ld [hl], a
+; BUG: Berserk Gene's confusion lasts for 256 turns or the previous Pokémon's confusion count (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS3
 	call GetBattleVarAddr
 	push af
@@ -4186,6 +4189,7 @@ PursuitSwitch:
 	or [hl]
 	jr nz, .done
 
+; BUG: A Pokémon that fainted from Pursuit will have its old status condition when revived (see docs/bugs_and_glitches.md)
 	ld a, $f0
 	ld [wCryTracks], a
 	ld a, [wBattleMonSpecies]
@@ -5759,8 +5763,8 @@ CheckPlayerHasUsableMoves:
 	jr .loop
 
 .done
-	; Bug: this will result in a move with PP Up confusing the game.
+; BUG: A Disabled but PP Up–enhanced move may not trigger Struggle (see docs/bugs_and_glitches.md)
-	and a ; should be "and PP_MASK"
+	and a
 	ret nz
 
 .force_struggle
@@ -6159,13 +6163,14 @@ LoadEnemyMon:
 	jr nz, .Happiness
 
 ; Get Magikarp's length
+; BUG: Magikarp length limits have a unit conversion error (see docs/bugs_and_glitches.md)
 	ld de, wEnemyMonDVs
 	ld bc, wPlayerID
 	callfar CalcMagikarpLength
 
 ; No reason to keep going if length > 1536 mm (i.e. if HIGH(length) > 6 feet)
 	ld a, [wMagikarpLength]
-	cp HIGH(1536) ; should be "cp 5", since 1536 mm = 5'0", but HIGH(1536) = 6
+	cp HIGH(1536)
 	jr nz, .CheckMagikarpArea
 
 ; 5% chance of skipping both size checks
@@ -6174,7 +6179,7 @@ LoadEnemyMon:
 	jr c, .CheckMagikarpArea
 ; Try again if length >= 1616 mm (i.e. if LOW(length) >= 4 inches)
 	ld a, [wMagikarpLength + 1]
-	cp LOW(1616) ; should be "cp 4", since 1616 mm = 5'4", but LOW(1616) = 80
+	cp LOW(1616)
 	jr nc, .GenerateDVs
 
 ; 20% chance of skipping this check
@@ -6183,23 +6188,11 @@ LoadEnemyMon:
 	jr c, .CheckMagikarpArea
 ; Try again if length >= 1600 mm (i.e. if LOW(length) >= 3 inches)
 	ld a, [wMagikarpLength + 1]
-	cp LOW(1600) ; should be "cp 3", since 1600 mm = 5'3", but LOW(1600) = 64
+	cp LOW(1600)
 	jr nc, .GenerateDVs
 
 .CheckMagikarpArea:
-; The "jr z" checks are supposed to be "jr nz".
+; BUG: Magikarp in Lake of Rage are shorter, not longer (see docs/bugs_and_glitches.md)
-
-; Instead, all maps in GROUP_LAKE_OF_RAGE (Mahogany area)
-; and Routes 20 and 44 are treated as Lake of Rage.
-
-; This also means Lake of Rage Magikarp can be smaller than ones
-; caught elsewhere rather than the other way around.
-
-; Intended behavior enforces a minimum size at Lake of Rage.
-; The real behavior prevents a minimum size in the Lake of Rage area.
-
-; Moreover, due to the check not being translated to feet+inches, all Magikarp
-; smaller than 4'0" may be caught by the filter, a lot more than intended.
 	ld a, [wMapGroup]
 	cp GROUP_LAKE_OF_RAGE
 	jr z, .Happiness
@@ -6212,7 +6205,7 @@ LoadEnemyMon:
 	jr c, .Happiness
 ; Try again if length < 1024 mm (i.e. if HIGH(length) < 3 feet)
 	ld a, [wMagikarpLength]
-	cp HIGH(1024) ; should be "cp 3", since 1024 mm = 3'4", but HIGH(1024) = 4
+	cp HIGH(1024)
 	jr c, .GenerateDVs ; try again
 
 ; Finally done with DVs
@@ -6805,6 +6798,7 @@ BadgeStatBoosts:
 	ld hl, wBattleMonAttack
 	ld c, 4
 .CheckBadge:
+; BUG: Glacier Badge may not boost Special Defense depending on the value of Special Attack (see docs/bugs_and_glitches.md)
 	ld a, b
 	srl b
 	call c, BoostStat
@@ -6814,9 +6808,6 @@ BadgeStatBoosts:
 	srl b
 	dec c
 	jr nz, .CheckBadge
-; Check GlacierBadge again for Special Defense.
-; This check is buggy because it assumes that a is set by the "ld a, b" in the above loop,
-; but it can actually be overwritten by the call to BoostStat.
 	srl a
 	call c, BoostStat
 	ret
@@ -7637,6 +7628,7 @@ SendOutMonText:
 	ld hl, GoMonText
 	jr z, .skip_to_textbox
 
+; BUG: Switching out or switching against a Pokémon with max HP below 4 freezes the game (see docs/bugs_and_glitches.md)
 	; compute enemy health remaining as a percentage
 	xor a
 	ldh [hMultiplicand + 0], a

engine/battle/effect_commands.asm

@@ -1401,13 +1401,9 @@ BattleCheckTypeMatchup:
 	and a
 	jr z, CheckTypeMatchup
 	ld hl, wBattleMonType1
+ 	; fallthrough
 CheckTypeMatchup:
-; There is an incorrect assumption about this function made in the AI related code: when
+; BUG: AI makes a false assumption about CheckTypeMatchup (see docs/bugs_and_glitches.md)
-; the AI calls CheckTypeMatchup (not BattleCheckTypeMatchup), it assumes that placing the
-; offensive type in a will make this function do the right thing. Since a is overwritten,
-; this assumption is incorrect. A simple fix would be to load the move type for the
-; current move into a in BattleCheckTypeMatchup, before falling through, which is
-; consistent with how the rest of the code assumes this code works like.
 	push hl
 	push de
 	push bc
@@ -1865,9 +1861,7 @@ BattleCommand_EffectChance:
 	jr z, .got_move_chance
 	ld hl, wEnemyMoveStruct + MOVE_CHANCE
 .got_move_chance
-
+; BUG: Moves with a 100% secondary effect chance will not trigger it in 1/256 uses (see docs/bugs_and_glitches.md)
-	; BUG: 1/256 chance to fail even for a 100% effect chance,
-	; since carry is not set if BattleRandom == [hl] == 255
 	call BattleRandom
 	cp [hl]
 	pop hl
@@ -2089,6 +2083,7 @@ BattleCommand_FailureText:
 	inc hl
 	ld a, [hl]
 
+; BUG: Beat Up may fail to raise Substitute (see docs/bugs_and_glitches.md)
 	cp EFFECT_MULTI_HIT
 	jr z, .multihit
 	cp EFFECT_DOUBLE_HIT
@@ -2510,6 +2505,7 @@ DittoMetalPowder:
 	pop bc
 	ret nz
 
+; BUG: Metal Powder can increase damage taken with boosted (Special) Defense (see docs/bugs_and_glitches.md)
 	ld a, c
 	srl a
 	add c
@@ -2646,6 +2642,7 @@ TruncateHL_BC:
 	inc l
 
 .finish
+; BUG: Reflect and Light Screen can make (Special) Defense wrap around above 1024 (see docs/bugs_and_glitches.md)
 	ld a, [wLinkMode]
 	cp LINK_COLOSSEUM
 	jr z, .done
@@ -2772,6 +2769,7 @@ SpeciesItemBoost:
 	ret nz
 
 ; Double the stat
+; BUG: Thick Club and Light Ball can make (Special) Attack wrap around above 1024 (see docs/bugs_and_glitches.md)
 	sla l
 	rl h
 	ret
@@ -2901,8 +2899,7 @@ HitSelfInConfusion:
 
 BattleCommand_DamageCalc:
 ; Return a damage value for move power d, player level e, enemy defense c and player attack b.
-
+; BUG: Confusion damage is affected by type-boosting items and Explosion/Self-Destruct doubling (see docs/bugs_and_glitches.md)
-; Return 1 if successful, else 0.
 
 	ld a, BATTLE_VARS_MOVE_EFFECT
 	call GetBattleVar
@@ -5263,6 +5260,7 @@ BattleCommand_EndLoop:
 	jr .double_hit
 
 .only_one_beatup
+; BUG: Beat Up works incorrectly with only one Pokémon in the party (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS3
 	call GetBattleVarAddr
 	res SUBSTATUS_IN_LOOP, [hl]
@@ -6546,7 +6544,7 @@ INCLUDE "engine/battle/move_effects/future_sight.asm"
 INCLUDE "engine/battle/move_effects/thunder.asm"
 
 CheckHiddenOpponent:
-; BUG: This routine is completely redundant and introduces a bug, since BattleCommand_CheckHit does these checks properly.
+; BUG: Lock-On and Mind Reader don't always bypass Fly and Dig (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS3_OPP
 	call GetBattleVar
 	and 1 << SUBSTATUS_FLYING | 1 << SUBSTATUS_UNDERGROUND

engine/battle/move_effects/beat_up.asm

@@ -24,6 +24,7 @@ BattleCommand_BeatUp:
 	ld [wCurBeatUpPartyMon], a
 
 .got_mon
+; BUG: Beat Up can desynchronize link battles (see docs/bugs_and_glitches.md)
 	ld a, [wCurBeatUpPartyMon]
 	ld hl, wPartyMonNicknames
 	call GetNickname
@@ -35,8 +36,6 @@ BattleCommand_BeatUp:
 	ld a, [wCurBeatUpPartyMon]
 	ld c, a
 	ld a, [wCurBattleMon]
-	; BUG: this can desynchronize link battles
-	; Change "cp [hl]" to "cp c" to fix
 	cp [hl]
 	ld hl, wBattleMonStatus
 	jr z, .active_mon
@@ -196,6 +195,7 @@ BattleCommand_BeatUp:
 	jp SkipToBattleCommand
 
 BattleCommand_BeatUpFailText:
+; BUG: Beat Up may trigger King's Rock even if it failed (see docs/bugs_and_glitches.md)
 	ld a, [wBeatUpHitAtLeastOnce]
 	and a
 	ret nz

engine/battle/move_effects/belly_drum.asm

@@ -1,7 +1,5 @@
 BattleCommand_BellyDrum:
-; This command is buggy because it raises the user's attack
+; BUG: Belly Drum sharply boosts Attack even with under 50% HP (see docs/bugs_and_glitches.md)
-; before checking that it has enough HP to use the move.
-; Swap the order of these two blocks to fix.
 	call BattleCommand_AttackUp2
 	ld a, [wAttackMissed]
 	and a

engine/battle/move_effects/counter.asm

@@ -34,7 +34,7 @@ BattleCommand_Counter:
 	cp SPECIAL
 	ret nc
 
-	; BUG: Move should fail with all non-damaging battle actions
+; BUG: Counter and Mirror Coat still work if the opponent uses an item (see docs/bugs_and_glitches.md)
 	ld hl, wCurDamage
 	ld a, [hli]
 	or [hl]

engine/battle/move_effects/frustration.asm

@@ -1,4 +1,5 @@
 BattleCommand_FrustrationPower:
+; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
 	push bc
 	ld hl, wBattleMonHappiness
 	ldh a, [hBattleTurn]

engine/battle/move_effects/mirror_coat.asm

@@ -35,7 +35,7 @@ BattleCommand_MirrorCoat:
 	cp SPECIAL
 	ret c
 
-	; BUG: Move should fail with all non-damaging battle actions
+; BUG: Counter and Mirror Coat still work if the opponent uses an item (see docs/bugs_and_glitches.md)
 	ld hl, wCurDamage
 	ld a, [hli]
 	or [hl]

engine/battle/move_effects/present.asm

@@ -1,4 +1,5 @@
 BattleCommand_Present:
+; BUG: Present damage is incorrect in link battles (see docs/bugs_and_glitches.md)
 	ld a, [wLinkMode]
 	cp LINK_COLOSSEUM
 	jr z, .colosseum_skippush

engine/battle/move_effects/return.asm

@@ -1,4 +1,5 @@
 BattleCommand_HappinessPower:
+; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
 	push bc
 	ld hl, wBattleMonHappiness
 	ldh a, [hBattleTurn]

engine/battle/move_effects/sketch.asm

@@ -12,6 +12,7 @@ BattleCommand_Sketch:
 	call CheckSubstituteOpp
 	jp nz, .fail
 ; If the opponent is transformed, fail.
+; BUG: A Transformed Pokémon can use Sketch and learn otherwise unobtainable moves (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS5_OPP
 	call GetBattleVarAddr
 	bit SUBSTATUS_TRANSFORMED, [hl]

engine/battle/move_effects/teleport.asm

@@ -66,14 +66,13 @@ BattleCommand_Teleport:
 	inc c
 	; Generate a number less than c
 .loop_enemy
+; BUG: Wild Pokémon can always Teleport regardless of level difference (see docs/bugs_and_glitches.md)
 	call BattleRandom
 	cp c
 	jr nc, .loop_enemy
 	; b = player level / 4
 	srl b
 	srl b
-	; This should be "jr c, .failed"
-	; As written, it makes enemy use of Teleport always succeed if able
 	cp b
 	jr nc, .run_away
 

engine/battle/start_battle.asm

@@ -93,7 +93,7 @@ PlayBattleMusic:
 	cp RED
 	jr z, .done
 
-	; They should have included EXECUTIVEM, EXECUTIVEF, and SCIENTIST too...
+; BUG: Team Rocket battle music is not used for Executives or Scientists (see docs/bugs_and_glitches.md)
 	ld de, MUSIC_ROCKET_BATTLE
 	cp GRUNTM
 	jr z, .done

engine/battle_anims/anim_commands.asm

@@ -653,9 +653,9 @@ BattleAnimCmd_ResetObp0:
 	ret
 
 BattleAnimCmd_ClearObjs:
-; BUG: This function only clears the first 6⅔ objects
+; BUG: BattleAnimCmd only clears the first 6⅔ objects (see docs/bugs_and_glitches.md)
 	ld hl, wActiveAnimObjects
-	ld a, $a0 ; should be NUM_ANIM_OBJECTS * BATTLEANIMSTRUCT_LENGTH
+	ld a, $a0
 .loop
 	ld [hl], 0
 	inc hl

engine/events/haircut.asm

@@ -37,13 +37,6 @@ HaircutOrGrooming:
 	call CopyPokemonName_Buffer1_Buffer3
 	pop hl
 	call Random
-; Bug: Subtracting $ff from $ff fails to set c.
-; This can result in overflow into the next data array.
-; In the case of getting a grooming from Daisy, we bleed
-; into CopyPokemonName_Buffer1_Buffer3, which passes
-; $d0 to ChangeHappiness and returns $73 to the script.
-; The end result is that there is a 0.4% chance your
-; Pokemon's happiness will not change at all.
 .loop
 	sub [hl]
 	jr c, .ok

engine/events/halloffame.asm

@@ -363,8 +363,9 @@ _HallOfFamePC:
 	call ClearBGPalettes
 	pop hl
 	call DisplayHOFMon
+; BUG: A "HOF Master!" title for 200-Time Famers is defined but inaccessible (see docs/bugs_and_glitches.md)
 	ld a, [wHallOfFameTempWinCount]
-	cp HOF_MASTER_COUNT + 1 ; should be HOF_MASTER_COUNT
+	cp HOF_MASTER_COUNT + 1
 	jr c, .print_num_hof
 	ld de, .HOFMaster
 	hlcoord 1, 2

engine/events/magikarp.asm

@@ -278,12 +278,11 @@ CalcMagikarpLength:
 	ret
 
 .BCLessThanDE:
-; Intention: Return bc < de.
+; BUG: Magikarp lengths can be miscalculated (see docs/bugs_and_glitches.md)
-; Reality: Return b < d.
 	ld a, b
 	cp d
 	ret c
-	ret nc ; whoops
+	ret nc
 	ld a, c
 	cp e
 	ret

engine/events/overworld.asm

@@ -400,6 +400,7 @@ SurfFromMenuScript:
 	special UpdateTimePals
 
 UsedSurfScript:
+; BUG: Surfing directly across a map connection does not load the new map (see docs/bugs_and_glitches.md)
 	writetext UsedSurfText ; "used SURF!"
 	waitbutton
 	closetext

engine/games/slot_machine.asm

@@ -483,12 +483,13 @@ SlotsAction_PayoutAnim:
 	jr c, .okay
 	inc de
 .okay
+; BUG: Slot machine payout sound effects cut each other off (see docs/bugs_and_glitches.md)
 	ld [hl], e
 	dec hl
 	ld [hl], d
 	ld a, [wSlotsDelay]
 	and $7
-	ret z ; ret nz would be more appropriate
+	ret z
 	ld de, SFX_GET_COIN_FROM_SLOTS
 	call PlaySFX
 	ret

engine/items/item_effects.asm

@@ -210,6 +210,7 @@ ItemEffects:
 ; NoEffect would be appropriate, with the table then being NUM_ITEMS long.
 
 PokeBallEffect:
+; BUG: The Dude's catching tutorial may crash if his Poké Ball can't be used (see docs/bugs_and_glitches.md)
 	ld a, [wBattleMode]
 	dec a
 	jp nz, UseBallInTrainerBattle
@@ -226,6 +227,7 @@ PokeBallEffect:
 	jp z, Ball_BoxIsFullMessage
 
 .room_in_party
+; BUG: Using a Park Ball in non-Contest battles has a corrupt animation (see docs/bugs_and_glitches.md)
 	xor a
 	ld [wWildMon], a
 	ld a, [wCurItem]
@@ -334,17 +336,12 @@ PokeBallEffect:
 	jr nz, .statuscheck
 	ld a, 1
 .statuscheck
-; This routine is buggy. It was intended that SLP and FRZ provide a higher
+; BUG: BRN/PSN/PAR do not affect catch rate (see docs/bugs_and_glitches.md)
-; catch rate than BRN/PSN/PAR, which in turn provide a higher catch rate than
-; no status effect at all. But instead, it makes BRN/PSN/PAR provide no
-; benefit.
-; Uncomment the line below to fix this.
 	ld b, a
 	ld a, [wEnemyMonStatus]
 	and 1 << FRZ | SLP_MASK
 	ld c, 10
 	jr nz, .addstatus
-	; ld a, [wEnemyMonStatus]
 	and a
 	ld c, 5
 	jr nz, .addstatus
@@ -356,13 +353,10 @@ PokeBallEffect:
 	ld a, $ff
 .max_1
 
-	; BUG: farcall overwrites a, and GetItemHeldEffect takes b anyway.
+; BUG: HELD_CATCH_CHANCE has no effect (see docs/bugs_and_glitches.md)
-	; This is probably the reason the HELD_CATCH_CHANCE effect is never used.
-	; Uncomment the line below to fix.
 	ld d, a
 	push de
 	ld a, [wBattleMonItem]
-	; ld b, a
 	farcall GetItemHeldEffect
 	ld a, b
 	cp HELD_CATCH_CHANCE
@@ -446,9 +440,7 @@ PokeBallEffect:
 	push af
 	set SUBSTATUS_TRANSFORMED, [hl]
 
-; This code is buggy. Any wild Pokémon that has Transformed will be
+; BUG: Catching a Transformed Pokémon always catches a Ditto (see docs/bugs_and_glitches.md)
-; caught as a Ditto, even if it was something else like Mew.
-; To fix, do not set [wTempEnemyMonSpecies] to DITTO.
 	bit SUBSTATUS_TRANSFORMED, a
 	jr nz, .ditto
 	jr .not_ditto
@@ -761,13 +753,10 @@ ParkBallMultiplier:
 	ret
 
 HeavyBall_GetDexEntryBank:
-; This function is buggy.
+; BUG: Heavy Ball uses wrong weight value for three Pokémon (see docs/bugs_and_glitches.md)
-; It gets the wrong bank for Kadabra (64), Tauros (128), and Sunflora (192).
-; Uncomment the line below to fix this.
 	push hl
 	push de
 	ld a, [wEnemyMonSpecies]
-	; dec a
 	rlca
 	rlca
 	maskbits NUM_DEX_ENTRY_BANKS
@@ -905,9 +894,6 @@ LureBallMultiplier:
 	ret
 
 MoonBallMultiplier:
-; This function is buggy.
-; Intent:  multiply catch rate by 4 if mon evolves with moon stone
-; Reality: no boost
 	push bc
 	ld a, [wTempEnemyMonSpecies]
 	dec a
@@ -931,9 +917,7 @@ MoonBallMultiplier:
 	inc hl
 	inc hl
 
-; Moon Stone's constant from Pokémon Red is used.
+; BUG: Moon Ball does not boost catch rate (see docs/bugs_and_glitches.md)
-; No Pokémon evolve with Burn Heal,
-; so Moon Balls always have a catch rate of 1×.
 	push bc
 	ld a, BANK("Evolutions and Attacks")
 	call GetFarByte
@@ -951,9 +935,6 @@ MoonBallMultiplier:
 	ret
 
 LoveBallMultiplier:
-; This function is buggy.
-; Intent:  multiply catch rate by 8 if mons are of same species, different sex
-; Reality: multiply catch rate by 8 if mons are of same species, same sex
 
 	; does species match?
 	ld a, [wTempEnemyMonSpecies]
@@ -974,9 +955,9 @@ LoveBallMultiplier:
 	jr c, .done1 ; no effect on genderless
 
 	ld d, 0 ; male
-	jr nz, .playermale
+	jr nz, .got_player_gender
 	inc d   ; female
-.playermale
+.got_player_gender
 
 	; check wild mon species
 	push de
@@ -988,15 +969,16 @@ LoveBallMultiplier:
 	jr c, .done2 ; no effect on genderless
 
 	ld d, 0 ; male
-	jr nz, .wildmale
+	jr nz, .got_wild_gender
 	inc d   ; female
-.wildmale
+.got_wild_gender
 
+; BUG: Love Ball boosts catch rate for the wrong gender (see docs/bugs_and_glitches.md)
 	ld a, d
 	pop de
 	cp d
 	pop bc
-	ret nz ; for the intended effect, this should be "ret z"
+	ret nz
 
 	sla b
 	jr c, .max
@@ -1016,17 +998,13 @@ LoveBallMultiplier:
 	ret
 
 FastBallMultiplier:
-; This function is buggy.
-; Intent:  multiply catch rate by 4 if enemy mon is in one of the three
-;          FleeMons tables.
-; Reality: multiply catch rate by 4 if enemy mon is one of the first three in
-;          the first FleeMons table.
 	ld a, [wTempEnemyMonSpecies]
 	ld c, a
 	ld hl, FleeMons
 	ld d, 3
 
 .loop
+; BUG: Fast Ball only boosts catch rate for three Pokémon (see docs/bugs_and_glitches.md)
 	ld a, BANK(FleeMons)
 	call GetFarByte
 
@@ -1034,7 +1012,7 @@ FastBallMultiplier:
 	cp -1
 	jr z, .next
 	cp c
-	jr nz, .next ; for the intended effect, this should be "jr nz, .loop"
+	jr nz, .next
 	sla b
 	jr c, .max
 

engine/movie/credits.asm

@@ -76,6 +76,7 @@ Credits::
 
 	call GetCreditsPalette
 	call SetPalettes
+; BUG: Credits sequence changes move selection menu behavior (see docs/bugs_and_glitches.md)
 	ldh a, [hVBlank]
 	push af
 	ld a, $5

engine/overworld/events.asm

@@ -554,7 +554,7 @@ TryObjectEvent:
 	ld a, [hl]
 	and %00001111
 
-; Bug: If IsInArray returns nc, data at bc will be executed as code.
+; BUG: TryObjectEvent arbitrary code execution (see docs/bugs_and_glitches.md)
 	push bc
 	ld de, 3
 	ld hl, ObjectEventTypeArray
@@ -569,7 +569,6 @@ TryObjectEvent:
 	jp hl
 
 .nope
-	; pop bc
 	xor a
 	ret
 

engine/overworld/map_objects.asm

@@ -2689,7 +2689,7 @@ ResetObject:
 	add hl, bc
 	ld a, [hl]
 	cp -1
-	jp z, .set_standing ; a jr would have been appropriate here
+	jp z, .set_standing
 	push bc
 	call GetMapObject
 	ld hl, MAPOBJECT_MOVEMENT

engine/overworld/npc_movement.asm

@@ -4,10 +4,10 @@ CanObjectMoveInDirection:
 	bit SWIMMING_F, [hl]
 	jr z, .not_swimming
 
+; BUG: Swimming NPCs aren't limited by their movement radius (see docs/bugs_and_glitches.md)
 	ld hl, OBJECT_FLAGS1
 	add hl, bc
-	bit NOCLIP_TILES_F, [hl] ; lost, uncomment next line to fix
+	bit NOCLIP_TILES_F, [hl]
-	; jr nz, .noclip_tiles
 	push hl
 	push bc
 	call WillObjectBumpIntoLand

engine/overworld/overworld.asm

@@ -346,8 +346,7 @@ AddSpriteGFX:
 	ret
 
 LoadSpriteGFX:
-; Bug: b is not preserved, so it's useless as a next count.
+; BUG: LoadSpriteGFX does not limit the capacity of UsedSprites (see docs/bugs_and_glitches.md)
-; Uncomment the lines below to fix.
 
 	ld hl, wUsedSprites
 	ld b, SPRITE_GFX_LIST_CAPACITY
@@ -366,9 +365,7 @@ LoadSpriteGFX:
 	ret
 
 .LoadSprite:
-	; push bc
 	call GetSprite
-	; pop bc
 	ld a, l
 	ret
 

engine/overworld/player_movement.asm

@@ -391,14 +391,9 @@ DoPlayerMovement::
 	db FACE_UP | FACE_LEFT    ; COLL_HOP_UP_LEFT
 
 .CheckWarp:
-; Bug: Since no case is made for STANDING here, it will check
+; BUG: No bump noise if standing on tile $3E (see docs/bugs_and_glitches.md)
-; [.EdgeWarps + $ff]. This resolves to $3e.
-; This causes wWalkingIntoEdgeWarp to be nonzero when standing on tile $3e,
-; making bumps silent.
 
 	ld a, [wWalkingDirection]
-	; cp STANDING
-	; jr z, .not_warp
 	ld e, a
 	ld d, 0
 	ld hl, .EdgeWarps
@@ -410,7 +405,6 @@ DoPlayerMovement::
 	ld a, TRUE
 	ld [wWalkingIntoEdgeWarp], a
 	ld a, [wWalkingDirection]
-	; This is in the wrong place.
 	cp STANDING
 	jr z, .not_warp
 

engine/overworld/scripting.asm

@@ -1240,11 +1240,7 @@ Script_memcall:
 	; fallthrough
 
 ScriptCall:
-; Bug: The script stack has a capacity of 5 scripts, yet there is
+; BUG: ScriptCall can overflow wScriptStack and crash (see docs/bugs_and_glitches.md)
-; nothing to stop you from pushing a sixth script.  The high part
-; of the script address can then be overwritten by modifications
-; to wScriptDelay, causing the script to return to the rst/interrupt
-; space.
 
 	push de
 	ld hl, wScriptStackSize

engine/overworld/wildmons.asm

@@ -313,14 +313,14 @@ ChooseWildEncounter:
 	inc b
 ; Store the level
 .ok
+; BUG: ChooseWildEncounter doesn't really validate the wild Pokemon species (see docs/bugs_and_glitches.md)
 	ld a, b
 	ld [wCurPartyLevel], a
 	ld b, [hl]
-	; ld a, b
 	call ValidateTempWildMonSpecies
 	jr c, .nowildbattle
 
-	ld a, b ; This is in the wrong place.
+	ld a, b
 	cp UNOWN
 	jr nz, .done
 

engine/phone/phone.asm

@@ -498,6 +498,7 @@ PhoneCall::
 	ld [hl], "☎"
 	inc hl
 	inc hl
+; BUG: The unused phonecall script command may crash (see docs/bugs_and_glitches.md)
 	ld a, [wPhoneScriptBank]
 	ld b, a
 	ld a, [wPhoneCaller]

engine/pokedex/pokedex.asm

@@ -465,6 +465,7 @@ DexEntryScreen_MenuActionJumptable:
 	ret
 
 .Cry:
+; BUG: Playing Entei's Pokédex cry can distort Raikou's and Suicune's (see docs/bugs_and_glitches.md)
 	call Pokedex_GetSelectedMon
 	ld a, [wTempSpecies]
 	call GetCryIndex

engine/pokemon/breeding.asm

@@ -620,6 +620,7 @@ GetBreedmonMovePointer:
 	ret
 
 GetEggFrontpic:
+; BUG: A hatching Unown egg would not show the right letter (see docs/bugs_and_glitches.md)
 	push de
 	ld [wCurPartySpecies], a
 	ld [wCurSpecies], a

engine/pokemon/experience.asm

@@ -32,6 +32,7 @@ CalcLevel:
 
 CalcExpAtLevel:
 ; (a/b)*n**3 + c*n**2 + d*n - e
+; BUG: Experience underflow for level 1 Pokémon with Medium-Slow growth rate (see docs/bugs_and_glitches.md)
 	ld a, [wBaseGrowthRate]
 	add a
 	add a

engine/pokemon/move_mon.asm

@@ -879,6 +879,7 @@ RetrieveBreedmon:
 	ld a, TRUE
 	ld [wSkipMovesBeforeLevelUp], a
 	predef FillMoves
+; BUG: Pokémon deposited in the Day-Care might lose experience (see docs/bugs_and_glitches.md)
 	ld a, [wPartyCount]
 	dec a
 	ld [wCurPartyMon], a

engine/pokemon/party_menu.asm

@@ -385,6 +385,7 @@ PlacePartyMonEvoStoneCompatibility:
 	ret
 
 .DetermineCompatibility:
+; BUG: Only the first three evolution entries can have Stone compatibility reported correctly (see docs/bugs_and_glitches.md)
 	ld de, wStringBuffer1
 	ld a, BANK(EvosAttacksPointers)
 	ld bc, 2
@@ -399,6 +400,7 @@ PlacePartyMonEvoStoneCompatibility:
 	call FarCopyBytes
 	ld hl, wStringBuffer1
 .loop2
+; BUG: EVOLVE_STAT can break Stone compatibility reporting (see docs/bugs_and_glitches.md)
 	ld a, [hli]
 	and a
 	jr z, .nope

engine/pokemon/search_owned.asm

@@ -56,6 +56,7 @@ CheckOwnMonAnywhere:
 	and a
 	ret z
 
+; BUG: CheckOwnMon does not check the Day-Care (see docs/bugs_and_glitches.md)
 	ld d, a
 	ld e, 0
 	ld hl, wPartyMon1Species
@@ -221,7 +222,8 @@ CheckOwnMon:
 
 	ld hl, wPlayerName
 
-rept NAME_LENGTH_JAPANESE - 2 ; should be PLAYER_NAME_LENGTH - 2
+; BUG: CheckOwnMon only checks the first five letters of OT names (see docs/bugs_and_glitches.md)
+rept NAME_LENGTH_JAPANESE - 2
 	ld a, [de]
 	cp [hl]
 	jr nz, .notfound

home/init.asm

@@ -186,6 +186,7 @@ ClearVRAM::
 ClearWRAM::
 ; Wipe swappable WRAM banks (1-7)
 ; Assumes CGB or AGB
+; BUG: ClearWRAM only clears WRAM bank 1 (see docs/bugs_and_glitches.md)
 
 	ld a, 1
 .bank_loop
@@ -198,7 +199,7 @@ ClearWRAM::
 	pop af
 	inc a
 	cp 8
-	jr nc, .bank_loop ; Should be jr c
+	jr nc, .bank_loop
 	ret
 
 ClearsScratch::

home/map.asm

@@ -146,12 +146,10 @@ LoadMetatiles::
 	ld e, l
 	ld d, h
 	; Set hl to the address of the current metatile data ([wTilesetBlocksAddress] + (a) tiles).
-	; This is buggy; it wraps around past 128 blocks.
+; BUG: LoadMetatiles wraps around past 128 blocks (see docs/bugs_and_glitches.md)
-	; To fix, uncomment the line below.
+	add a
-	add a ; Comment or delete this line to fix the above bug.
 	ld l, a
 	ld h, 0
-	; add hl, hl
 	add hl, hl
 	add hl, hl
 	add hl, hl
@@ -584,18 +582,16 @@ ReadObjectEvents::
 	call CopyMapObjectEvents
 
 ; get NUM_OBJECTS - [wCurMapObjectEventCount]
+; BUG: ReadObjectEvents overflows into wObjectMasks (see docs/bugs_and_glitches.md)
 	ld a, [wCurMapObjectEventCount]
 	ld c, a
-	ld a, NUM_OBJECTS ; - 1
+	ld a, NUM_OBJECTS
 	sub c
 	jr z, .skip
-	; jr c, .skip
 
 	; could have done "inc hl" instead
 	ld bc, 1
 	add hl, bc
-; Fill the remaining sprite IDs and y coords with 0 and -1, respectively.
-; Bleeds into wObjectMasks due to a bug.  Uncomment the above code to fix.
 	ld bc, MAPOBJECT_LENGTH
 .loop
 	ld [hl],  0

maps/DragonsDenB1F.asm

@@ -41,6 +41,7 @@ DragonsDenB1F_MapScripts:
 	endcallback
 
 DragonsDenB1F_ClairScene:
+; BUG: Clair can give TM24 Dragonbreath twice (see docs/bugs_and_glitches.md)
 	appear DRAGONSDENB1F_CLAIR
 	opentext
 	writetext ClairText_Wait