Merge pull request #93 from xCrystal/master

Document some move effects

engine/battle/core.asm

@@ -847,7 +847,7 @@ FaintEnemyPokemon ; 0x3c567
 	ld [hli], a
 	ld [hl], a
 	ld [W_ENEMYDISABLEDMOVE], a
-	ld [wccef], a
+	ld [wEnemyDisabledMoveNumber], a
 	ld [wccf3], a
 	ld hl, wPlayerUsedMove
 	ld [hli], a
@@ -1023,10 +1023,11 @@ TrainerBattleVictory: ; 3c696 (f:4696)
 	ld c, $28
 	call DelayFrames
 	call PrintEndBattleText
+; win money	
 	ld hl, MoneyForWinningText
 	call PrintText
 	ld de, wPlayerMoney + 2
-	ld hl, wd07b
+	ld hl, wAmountMoneyWon + 2
 	ld c, $3
 	predef_jump AddBCDPredef
 
@@ -1374,7 +1375,7 @@ EnemySendOutFirstMon: ; 3c92a (f:492a)
 	ld [hli],a
 	ld [hl],a
 	ld [W_ENEMYDISABLEDMOVE],a
-	ld [wccef],a
+	ld [wEnemyDisabledMoveNumber],a
 	ld [wccf3],a
 	ld hl,wPlayerUsedMove
 	ld [hli],a
@@ -1824,7 +1825,7 @@ SendOutMon: ; 3cc91 (f:4c91)
 	ld [hli], a
 	ld [hl], a
 	ld [W_PLAYERDISABLEDMOVE], a
-	ld [wccee], a
+	ld [wPlayerDisabledMoveNumber], a
 	ld [wccf7], a
 	ld b, $1
 	call GoPAL_SET
@@ -3447,10 +3448,10 @@ CheckPlayerStatusConditions: ; 3d854 (f:5854)
 	jr z,.ConfusedCheck
 	dec a
 	ld [hl],a
-	and a,$F ; did Disable counter hit 0?
+	and $f ; did Disable counter hit 0?
 	jr nz,.ConfusedCheck
 	ld [hl],a
-	ld [wccee],a
+	ld [wPlayerDisabledMoveNumber],a
 	ld hl,DisabledNoMoreText
 	call PrintText
 
@@ -3484,7 +3485,8 @@ CheckPlayerStatusConditions: ; 3d854 (f:5854)
 	jr .MonHurtItselfOrFullyParalysed
 
 .TriedToUseDisabledMoveCheck
-	ld a,[wccee]
+; prevents a disabled move that was selected before being disabled from being used
+	ld a,[wPlayerDisabledMoveNumber]
 	and a
 	jr z,.ParalysisCheck
 	ld hl,wPlayerSelectedMove
@@ -3508,7 +3510,7 @@ CheckPlayerStatusConditions: ; 3d854 (f:5854)
 	ld hl,W_PLAYERBATTSTATUS1
 	ld a,[hl]
 	; clear bide, thrashing, charging up, and trapping moves such as warp (already cleared for confusion damage)	
-	and a, (1 << AttackingMultipleTimes) | (1 << Flinched) | (1 << Invulnerable) | (1 << Confused) 
+	and $ff ^ ((1 << StoringEnergy) | (1 << ThrashingAbout) | (1 << ChargingUp) | (1 << UsingTrappingMove)) 
 	ld [hl],a
 	ld a,[W_PLAYERMOVEEFFECT]
 	cp a,FLY_EFFECT
@@ -3584,12 +3586,12 @@ CheckPlayerStatusConditions: ; 3d854 (f:5854)
 	ld hl,ThrashingAboutText
 	call PrintText
 	ld hl,wPlayerNumAttacksLeft
-	dec [hl] ; did Trashing About counter hit 0?
+	dec [hl] ; did Thrashing About counter hit 0?
 	ld hl,PlayerCalcMoveDamage ; skip DecrementPP
 	jp nz,.returnToHL 
 	push hl
 	ld hl,W_PLAYERBATTSTATUS1
-	res ThrashingAbout,[hl] ; no longer trashing about
+	res ThrashingAbout,[hl] ; no longer thrashing about
 	set Confused,[hl] ; confused
 	call BattleRandom
 	and a,3
@@ -4112,7 +4114,7 @@ CheckForDisobedience: ; 3dc88 (f:5c88)
 	ld a, [wBattleMonMoves + 1]
 	and a ; is the second move slot empty?
 	jr z, .monDoesNothing ; mon will not use move if it only knows one move
-	ld a, [wccee]
+	ld a, [wPlayerDisabledMoveNumber]
 	and a
 	jr nz, .monDoesNothing
 	ld a, [wPlayerSelectedMove]
@@ -5874,14 +5876,14 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	ld [wAnimationType], a
 	ld a,SLP_ANIM
 	call PlayMoveAnimation
-	jr .next1
+	jr .sleepDone
 .wokeUp
 	ld hl, WokeUpText
 	call PrintText
-.next1
+.sleepDone
 	xor a
 	ld [wEnemyUsedMove], a
-	ld hl, ExecuteEnemyMoveDone
+	ld hl, ExecuteEnemyMoveDone ; enemy can't move this turn
 	jp .enemyReturnToHL
 .checkIfFrozen
 	bit FRZ, [hl]
@@ -5890,7 +5892,7 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	call PrintText
 	xor a
 	ld [wEnemyUsedMove], a
-	ld hl, ExecuteEnemyMoveDone
+	ld hl, ExecuteEnemyMoveDone ; enemy can't move this turn
 	jp .enemyReturnToHL
 .checkIfTrapped
 	ld a, [W_PLAYERBATTSTATUS1]
@@ -5898,7 +5900,7 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	jp z, .checkIfFlinched
 	ld hl, CantMoveText
 	call PrintText
-	ld hl, ExecuteEnemyMoveDone
+	ld hl, ExecuteEnemyMoveDone ; enemy can't move this turn
 	jp .enemyReturnToHL
 .checkIfFlinched
 	ld hl, W_ENEMYBATTSTATUS1
@@ -5907,7 +5909,7 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	res Flinched, [hl]
 	ld hl, FlinchedText
 	call PrintText
-	ld hl, ExecuteEnemyMoveDone
+	ld hl, ExecuteEnemyMoveDone ; enemy can't move this turn
 	jp .enemyReturnToHL
 .checkIfMustRecharge
 	ld hl, W_ENEMYBATTSTATUS2
@@ -5916,19 +5918,19 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	res NeedsToRecharge, [hl]
 	ld hl, MustRechargeText
 	call PrintText
-	ld hl, ExecuteEnemyMoveDone
+	ld hl, ExecuteEnemyMoveDone ; enemy can't move this turn
 	jp .enemyReturnToHL
 .checkIfAnyMoveDisabled
 	ld hl, W_ENEMYDISABLEDMOVE
 	ld a, [hl]
 	and a
 	jr z, .checkIfConfused
-	dec a
+	dec a ; decrement disable counter
 	ld [hl], a
-	and $f
+	and $f ; did disable counter hit 0?
 	jr nz, .checkIfConfused
 	ld [hl], a
-	ld [wccef], a
+	ld [wEnemyDisabledMoveNumber], a
 	ld hl, DisabledNoMoreText
 	call PrintText
 .checkIfConfused
@@ -5939,7 +5941,7 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	dec [hl]
 	jr nz, .isConfused
 	ld hl, W_ENEMYBATTSTATUS1
-	res Confused, [hl]
+	res Confused, [hl] ; if confused counter hit 0, reset confusion status
 	ld hl, ConfusedNoMoreText
 	call PrintText
 	jp .checkIfTriedToUseDisabledMove
@@ -5955,7 +5957,7 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	jr c, .checkIfTriedToUseDisabledMove
 	ld hl, W_ENEMYBATTSTATUS1
 	ld a, [hl]
-	and 1 << Confused
+	and 1 << Confused ; if mon hurts itself, clear every other status from W_ENEMYBATTSTATUS1
 	ld [hl], a
 	ld hl, HurtItselfText
 	call PrintText
@@ -5999,21 +6001,22 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	call ApplyDamageToEnemyPokemon
 	jr .monHurtItselfOrFullyParalysed
 .checkIfTriedToUseDisabledMove
-	ld a, [wccef]
+; prevents a disabled move that was selected before being disabled from being used
+	ld a, [wEnemyDisabledMoveNumber]
 	and a
 	jr z, .checkIfParalysed
 	ld hl, wEnemySelectedMove
 	cp [hl]
 	jr nz, .checkIfParalysed
 	call PrintMoveIsDisabledText
-	ld hl, ExecuteEnemyMoveDone
+	ld hl, ExecuteEnemyMoveDone ; if a disabled move was somehow selected, player can't move this turn
 	jp .enemyReturnToHL
 .checkIfParalysed
 	ld hl, wEnemyMonStatus
 	bit PAR, [hl]
 	jr z, .checkIfUsingBide
 	call BattleRandom
-	cp $3f
+	cp $3f ; 25% to be fully paralysed
 	jr nc, .checkIfUsingBide
 	ld hl, FullyParalyzedText
 	call PrintText
@@ -6021,7 +6024,7 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	ld hl, W_ENEMYBATTSTATUS1
 	ld a, [hl]
 	; clear bide, thrashing about, charging up, and multi-turn moves such as warp	
-	and (1 << AttackingMultipleTimes) | (1 << Flinched) | (1 << Invulnerable) | (1 << Confused)  
+	and $ff ^ ((1 << StoringEnergy) | (1 << ThrashingAbout) | (1 << ChargingUp) | (1 << UsingTrappingMove))
 	ld [hl], a
 	ld a, [W_ENEMYMOVEEFFECT]
 	cp FLY_EFFECT
@@ -6036,7 +6039,7 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	call PlayMoveAnimation
 .notFlyOrChargeEffect
 	ld hl, ExecuteEnemyMoveDone
-	jp .enemyReturnToHL
+	jp .enemyReturnToHL ; if using a two-turn move, enemy needs to recharge the first turn
 .checkIfUsingBide
 	ld hl, W_ENEMYBATTSTATUS1
 	bit StoringEnergy, [hl] ; is mon using bide?
@@ -6049,16 +6052,16 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	ld c, [hl]
 	ld hl, wEnemyBideAccumulatedDamage + 1
 	ld a, [hl]
-	add c
+	add c ; accumulate damage taken
 	ld [hld], a
 	ld a, [hl]
 	adc b
 	ld [hl], a
 	ld hl, wEnemyNumAttacksLeft
-	dec [hl]
+	dec [hl] ; did Bide counter hit 0?
 	jr z, .unleashEnergy
 	ld hl, ExecuteEnemyMoveDone
-	jp .enemyReturnToHL
+	jp .enemyReturnToHL ; unless mon unleashes energy, can't move this turn
 .unleashEnergy
 	ld hl, W_ENEMYBATTSTATUS1
 	res StoringEnergy, [hl] ; not using bide any more
@@ -6072,20 +6075,20 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	ld b, a
 	ld [W_DAMAGE + 1], a
 	ld a, [hl]
-	rl a
+	rl a ; double the damage
 	ld [W_DAMAGE], a
 	or b
-	jr nz, .next2
+	jr nz, .next
 	ld a, $1
 	ld [W_MOVEMISSED], a
-.next2
+.next
 	xor a
 	ld [hli], a
 	ld [hl], a
 	ld a, BIDE
 	ld [W_ENEMYMOVENUM], a
 	call SwapPlayerAndEnemyLevels
-	ld hl, handleIfEnemyMoveMissed
+	ld hl, handleIfEnemyMoveMissed ; skip damage calculation, DecrementPP and MoveHitTest
 	jp .enemyReturnToHL
 .checkIfThrashingAbout
 	bit ThrashingAbout, [hl] ; is mon using thrash or petal dance?
@@ -6095,8 +6098,8 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	ld hl, ThrashingAboutText
 	call PrintText
 	ld hl, wEnemyNumAttacksLeft
-	dec [hl]
+	dec [hl] ; did Thrashing About counter hit 0?
-	ld hl, EnemyCalcMoveDamage
+	ld hl, EnemyCalcMoveDamage ; skip DecrementPP
 	jp nz, .enemyReturnToHL
 	push hl
 	ld hl, W_ENEMYBATTSTATUS1
@@ -6105,9 +6108,9 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	call BattleRandom
 	and $3
 	inc a
-	inc a
+	inc a ; confused for 2-5 turns
 	ld [W_ENEMYCONFUSEDCOUNTER], a
-	pop hl
+	pop hl ; skip DecrementPP
 	jp .enemyReturnToHL
 .checkIfUsingMultiturnMove
 	bit UsingTrappingMove, [hl] ; is mon using multi-turn move?
@@ -6115,14 +6118,15 @@ CheckEnemyStatusConditions: ; 3e88f (f:688f)
 	ld hl, AttackContinuesText
 	call PrintText
 	ld hl, wEnemyNumAttacksLeft
-	dec [hl]
+	dec [hl] ; did multi-turn move end?
-	ld hl, GetEnemyAnimationType
+	ld hl, GetEnemyAnimationType ; if it didn't, skip damage calculation (deal damage equal to last hit), 
+	                             ; DecrementPP and MoveHitTest
 	jp nz, .enemyReturnToHL
 	jp .enemyReturnToHL
 .checkIfUsingRage
 	ld a, [W_ENEMYBATTSTATUS2]
 	bit UsingRage, a ; is mon using rage?
-	jp z, .checkEnemyStatusConditionsDone
+	jp z, .checkEnemyStatusConditionsDone ; if we made it this far, mon can move normally this turn
 	ld a, RAGE
 	ld [wd11e], a
 	call GetMoveName
@@ -6956,9 +6960,9 @@ InitBattle_Common: ; 3efeb (f:6feb)
 
 _LoadTrainerPic: ; 3f04b (f:704b)
 ; wd033-wd034 contain pointer to pic
-	ld a, [wd033]
+	ld a, [wTrainerPicPointer] ; wd033
 	ld e, a
-	ld a, [wd034]
+	ld a, [wTrainerPicPointer + 1] ; wd034
 	ld d, a ; de contains pointer to trainer pic
 	ld a, [wLinkState]
 	and a
@@ -8494,19 +8498,20 @@ DisableEffect: ; 3fa8a (f:7a8a)
 	call MoveHitTest
 	ld a, [W_MOVEMISSED]
 	and a
-	jr nz, .asm_3fb06
+	jr nz, .moveMissed
 	ld de, W_ENEMYDISABLEDMOVE
 	ld hl, wEnemyMonMoves
 	ld a, [H_WHOSETURN]
 	and a
-	jr z, .asm_3faa4
+	jr z, .disableEffect
 	ld de, W_PLAYERDISABLEDMOVE
 	ld hl, wBattleMonMoves
-.asm_3faa4
+.disableEffect
+; no effect if target already has a move disabled
 	ld a, [de]
 	and a
-	jr nz, .asm_3fb06
+	jr nz, .moveMissed
-.asm_3faa8
+.pickMoveToDisable
 	push hl
 	call BattleRandom
 	and $3
@@ -8516,20 +8521,21 @@ DisableEffect: ; 3fa8a (f:7a8a)
 	ld a, [hl]
 	pop hl
 	and a
-	jr z, .asm_3faa8
+	jr z, .pickMoveToDisable ; loop until a non-00 move slot is found
-	ld [wd11e], a
+	ld [wd11e], a ; store move number
 	push hl
 	ld a, [H_WHOSETURN]
 	and a
 	ld hl, wBattleMonPP
-	jr nz, .asm_3facf
+	jr nz, .enemyTurn 
 	ld a, [wLinkState]
 	cp LINK_STATE_BATTLING
-	pop hl
+	pop hl ; wEnemyMonMoves
-	jr nz, .asm_3fae1
+	jr nz, .playerTurnNotLinkBattle
+; .playerTurnLinkBattle	
 	push hl
 	ld hl, wEnemyMonPP
-.asm_3facf
+.enemyTurn
 	push hl
 	ld a, [hli]
 	or [hl]
@@ -8538,36 +8544,37 @@ DisableEffect: ; 3fa8a (f:7a8a)
 	inc hl
 	or [hl]
 	and $3f
-	pop hl
+	pop hl ; wBattleMonPP or wEnemyMonPP
-	jr z, .asm_3fb05
+	jr z, .moveMissedPopHL ; nothing to do if all moves have no PP left
 	add hl, bc
 	ld a, [hl]
 	pop hl
 	and a
-	jr z, .asm_3faa8
+	jr z, .pickMoveToDisable ; pick another move if this one had 0 PP
-.asm_3fae1
+.playerTurnNotLinkBattle
+; non-link battle enemies have unlimited PP so the previous checks aren't needed
 	call BattleRandom
 	and $7
-	inc a
+	inc a ; 1-8 turns disabled
-	inc c
+	inc c ; move 1-4 will be disabled
-	swap c
+	swap c 
-	add c
+	add c ; map disabled move to high nibble of W_ENEMYDISABLEDMOVE / W_PLAYERDISABLEDMOVE
 	ld [de], a
 	call PlayCurrentMoveAnimation2
-	ld hl, wccee
+	ld hl, wPlayerDisabledMoveNumber
 	ld a, [H_WHOSETURN]
 	and a
-	jr nz, .asm_3faf8
+	jr nz, .printDisableText
-	inc hl
+	inc hl ; wEnemyDisabledMoveNumber
-.asm_3faf8
+.printDisableText
-	ld a, [wd11e]
+	ld a, [wd11e] ; move number
-	ld [hl], a
+	ld [hl], a  
 	call GetMoveName
 	ld hl, MoveWasDisabledText
 	jp PrintText
-.asm_3fb05
+.moveMissedPopHL
 	pop hl
-.asm_3fb06
+.moveMissed
 	jp PrintButItFailedText_
 
 MoveWasDisabledText: ; 3fb09 (f:7b09)

engine/battle/moveEffects/conversion_effect.asm

@@ -4,15 +4,16 @@ ConversionEffect_: ; 139a3 (4:79a3)
 	ld a, [H_WHOSETURN]
 	and a
 	ld a, [W_ENEMYBATTSTATUS1]
-	jr z, .asm_139b8
+	jr z, .conversionEffect
 	push hl
 	ld h, d
 	ld l, e
 	pop de
 	ld a, [W_PLAYERBATTSTATUS1]
-.asm_139b8
+.conversionEffect
 	bit Invulnerable, a ; is mon immune to typical attacks (dig/fly)
 	jr nz, PrintButItFailedText
+; copy target's types to user	
 	ld a, [hli]
 	ld [de], a
 	inc de

engine/battle/moveEffects/haze_effect.asm

@@ -1,9 +1,11 @@
 HazeEffect_: ; 139da (4:79da)
 	ld a, $7
+; store 7 on every stat mod	
 	ld hl, wPlayerMonAttackMod
 	call ResetStatMods
 	ld hl, wEnemyMonAttackMod
 	call ResetStatMods
+; copy unmodified stats to battle stats	
 	ld hl, wPlayerMonUnmodifiedAttack
 	ld de, wBattleMonAttack
 	call ResetStats
@@ -14,39 +16,42 @@ HazeEffect_: ; 139da (4:79da)
 	ld de, wEnemySelectedMove
 	ld a, [H_WHOSETURN]
 	and a
-	jr z, .asm_13a09
+	jr z, .cureStatuses
 	ld hl, wBattleMonStatus
-	dec de
+	dec de ; wPlayerSelectedMove
 
-.asm_13a09
+.cureStatuses
 	ld a, [hl]
 	ld [hl], $0
-	and $27
+	and SLP | (1 << FRZ)
-	jr z, .asm_13a13
+	jr z, .cureVolatileStatuses
+; prevent the Pokemon from executing a move if it was asleep or frozen	
 	ld a, $ff
 	ld [de], a
 
-.asm_13a13
+.cureVolatileStatuses
 	xor a
 	ld [W_PLAYERDISABLEDMOVE], a
 	ld [W_ENEMYDISABLEDMOVE], a
-	ld hl, wccee
+	ld hl, wPlayerDisabledMoveNumber
 	ld [hli], a
 	ld [hl], a
 	ld hl, W_PLAYERBATTSTATUS1
-	call CureStatuses
+	call CureVolatileStatuses
 	ld hl, W_ENEMYBATTSTATUS1
-	call CureStatuses
+	call CureVolatileStatuses
 	ld hl, PlayCurrentMoveAnimation
 	call CallBankF
 	ld hl, StatusChangesEliminatedText
 	jp PrintText
 
-CureStatuses: ; 13a37 (4:7a37)
+CureVolatileStatuses: ; 13a37 (4:7a37)
+; only cures statuses of the Pokemon not using Haze
 	res Confused, [hl]
 	inc hl ; BATTSTATUS2
 	ld a, [hl]
-	and (1 << UsingRage) | (1 << NeedsToRecharge) | (1 << HasSubstituteUp) | (1 << 3) ; clear all but these from BATTSTATUS2
+	; clear UsingXAccuracy, ProtectedByMist, GettingPumped, and Seeded statuses
+	and $ff ^((1 << UsingXAccuracy) | (1 << ProtectedByMist) | (1 << GettingPumped) | (1 << Seeded)) 
 	ld [hli], a ; BATTSTATUS3
 	ld a, [hl]
 	and %11110000 | (1 << Transformed) ; clear Bad Poison, Reflect and Light Screen statuses
@@ -56,7 +61,7 @@ CureStatuses: ; 13a37 (4:7a37)
 ResetStatMods: ; 13a43 (4:7a43)
 	ld b, $8
 .loop
-	ld [hli], a
+	ld [hli], a 
 	dec b
 	jr nz, .loop
 	ret

engine/battle/moveEffects/heal_effect.asm

@@ -4,22 +4,23 @@ HealEffect_: ; 3b9ec (e:79ec)
 	ld de, wBattleMonHP
 	ld hl, wBattleMonMaxHP
 	ld a, [W_PLAYERMOVENUM]
-	jr z, .asm_3ba03
+	jr z, .healEffect
 	ld de, wEnemyMonHP
 	ld hl, wEnemyMonMaxHP
 	ld a, [W_ENEMYMOVENUM]
-.asm_3ba03
+.healEffect
 	ld b, a
 	ld a, [de]
-	cp [hl]
+	cp [hl] ; most significant bytes comparison is ignored
+	        ; causes the move to miss if max HP is 255 or 511 points higher than the current HP
 	inc de
 	inc hl
 	ld a, [de]
 	sbc [hl]
-	jp z, .failed
+	jp z, .failed ; no effect if user's HP is already at its maximum
 	ld a, b
 	cp REST
-	jr nz, .asm_3ba37
+	jr nz, .healHP
 	push hl
 	push de
 	push af
@@ -28,31 +29,33 @@ HealEffect_: ; 3b9ec (e:79ec)
 	ld hl, wBattleMonStatus
 	ld a, [H_WHOSETURN]
 	and a
-	jr z, .asm_3ba25
+	jr z, .restEffect
 	ld hl, wEnemyMonStatus
-.asm_3ba25
+.restEffect
 	ld a, [hl]
 	and a
-	ld [hl], 2 ; Number of turns from Rest
+	ld [hl], 2 ; clear status and set number of turns asleep to 2
-	ld hl, StartedSleepingEffect
+	ld hl, StartedSleepingEffect ; if mon didn't have an status
-	jr z, .asm_3ba31
+	jr z, .printRestText
-	ld hl, FellAsleepBecameHealthyText
+	ld hl, FellAsleepBecameHealthyText ; if mon had an status
-.asm_3ba31
+.printRestText
 	call PrintText
 	pop af
 	pop de
 	pop hl
-.asm_3ba37
+.healHP
 	ld a, [hld]
 	ld [wHPBarMaxHP], a
 	ld c, a
 	ld a, [hl]
 	ld [wHPBarMaxHP+1], a
 	ld b, a
-	jr z, .asm_3ba47
+	jr z, .gotHPAmountToHeal
+; Recover and Softboiled only heal for half the mon's max HP
 	srl b
 	rr c
-.asm_3ba47
+.gotHPAmountToHeal
+; update HP
 	ld a, [de]
 	ld [wHPBarOldHP], a
 	add c
@@ -72,7 +75,8 @@ HealEffect_: ; 3b9ec (e:79ec)
 	dec hl
 	ld a, [de]
 	sbc [hl]
-	jr c, .asm_3ba6f
+	jr c, .playAnim
+; copy max HP to current HP if an overflow ocurred	
 	ld a, [hli]
 	ld [de], a
 	ld [wHPBarNewHP+1], a
@@ -80,17 +84,17 @@ HealEffect_: ; 3b9ec (e:79ec)
 	ld a, [hl]
 	ld [de], a
 	ld [wHPBarNewHP], a
-.asm_3ba6f
+.playAnim
 	ld hl, PlayCurrentMoveAnimation
 	call BankswitchEtoF
 	ld a, [H_WHOSETURN]
 	and a
 	hlCoord 10, 9
 	ld a, $1
-	jr z, .asm_3ba83
+	jr z, .updateHPBar
 	hlCoord 2, 2
 	xor a
-.asm_3ba83
+.updateHPBar
 	ld [wHPBarType], a
 	predef UpdateHPBar2
 	ld hl, DrawHUDsAndHPBars

engine/battle/moveEffects/leech_seed_effect.asm

@@ -1,30 +1,31 @@
 LeechSeedEffect_: ; 2bea9 (a:7ea9)
 	callab MoveHitTest
-	ld a, [W_MOVEMISSED] ; W_MOVEMISSED
+	ld a, [W_MOVEMISSED] 
 	and a
-	jr nz, .asm_2bee7
+	jr nz, .moveMissed
-	ld hl, W_ENEMYBATTSTATUS2 ; W_ENEMYBATTSTATUS2
+	ld hl, W_ENEMYBATTSTATUS2 
-	ld de, wEnemyMonType1 ; wcfea (aliases: wEnemyMonType)
+	ld de, wEnemyMonType1 
-	ld a, [H_WHOSETURN] ; $fff3
+	ld a, [H_WHOSETURN] 
 	and a
-	jr z, .asm_2bec8
+	jr z, .leechSeedEffect
-	ld hl, W_PLAYERBATTSTATUS2 ; W_PLAYERBATTSTATUS2
+	ld hl, W_PLAYERBATTSTATUS2 
-	ld de, wBattleMonType1 ; wd019 (aliases: wBattleMonType)
+	ld de, wBattleMonType1 
-.asm_2bec8
+.leechSeedEffect
+; miss if the target is grass-type or already seeded
 	ld a, [de]
 	cp GRASS
-	jr z, .asm_2bee7
+	jr z, .moveMissed 
 	inc de
 	ld a, [de]
 	cp GRASS
-	jr z, .asm_2bee7
+	jr z, .moveMissed
 	bit Seeded, [hl]
-	jr nz, .asm_2bee7
+	jr nz, .moveMissed
 	set Seeded, [hl]
 	callab PlayCurrentMoveAnimation
 	ld hl, WasSeededText ; $7ef2
 	jp PrintText
-.asm_2bee7
+.moveMissed
 	ld c, $32
 	call DelayFrames
 	ld hl, EvadedAttackText ; $7ef7

engine/battle/moveEffects/mist_effect.asm

@@ -1,17 +1,17 @@
 MistEffect_: ; 33f2b (c:7f2b)
 	ld hl, W_PLAYERBATTSTATUS2
-	ld a, [$fff3]
+	ld a, [H_WHOSETURN]
 	and a
-	jr z, .asm_33f36
+	jr z, .mistEffect
 	ld hl, W_ENEMYBATTSTATUS2
-.asm_33f36
+.mistEffect
 	bit ProtectedByMist, [hl] ; is mon protected by mist?
-	jr nz, .asm_33f4a
+	jr nz, .mistAlreadyInUse
 	set ProtectedByMist, [hl] ; mon is now protected by mist
 	callab PlayCurrentMoveAnimation
 	ld hl, ShroudedInMistText
 	jp PrintText
-.asm_33f4a
+.mistAlreadyInUse
 	ld hl, PrintButItFailedText_
 	ld b, BANK(PrintButItFailedText_)
 	jp Bankswitch

engine/battle/moveEffects/one_hit_ko_effect.asm

@@ -7,12 +7,13 @@ OneHitKOEffect_: ; 33f57 (c:7f57)
 	ld [wCriticalHitOrOHKO], a
 	ld hl, wBattleMonSpeed + 1
 	ld de, wEnemyMonSpeed + 1
-	ld a, [H_WHOSETURN] ; $fff3
+	ld a, [H_WHOSETURN] 
 	and a
-	jr z, .asm_33f72
+	jr z, .compareSpeed
 	ld hl, wEnemyMonSpeed + 1
 	ld de, wBattleMonSpeed + 1
-.asm_33f72
+.compareSpeed
+; set damage to 65535 and OHKO flag is the user's current speed is higher than the target's
 	ld a, [de]
 	dec de
 	ld b, a
@@ -22,7 +23,7 @@ OneHitKOEffect_: ; 33f57 (c:7f57)
 	ld b, a
 	ld a, [hl]
 	sbc b
-	jr c, .asm_33f8a
+	jr c, .userIsSlower
 	ld hl, W_DAMAGE 
 	ld a, $ff
 	ld [hli], a
@@ -30,7 +31,8 @@ OneHitKOEffect_: ; 33f57 (c:7f57)
 	ld a, $2
 	ld [wCriticalHitOrOHKO], a
 	ret
-.asm_33f8a
+.userIsSlower
+; keep damage at 0 and set move missed flag if target's current speed is higher instead
 	ld a, $1
 	ld [W_MOVEMISSED], a 
 	ret

engine/battle/moveEffects/pay_day_effect.asm

@@ -5,24 +5,26 @@ PayDayEffect_ ; 2feb8 (b:7eb8)
 	ld a, [H_WHOSETURN]
 	and a
 	ld a, [wBattleMonLevel]
-	jr z, .asm_2fec8
+	jr z, .payDayEffect
 	ld a, [wEnemyMonLevel]
-.asm_2fec8
+.payDayEffect
-	add a
+; level * 2
+	add a 
 	ld [H_DIVIDEND + 3], a
 	xor a
 	ld [H_DIVIDEND], a
 	ld [H_DIVIDEND + 1], a
 	ld [H_DIVIDEND + 2], a
-	ld a, $64
+; convert to BCD	
+	ld a, 100
 	ld [H_DIVISOR], a
 	ld b, $4
 	call Divide
 	ld a, [H_QUOTIENT + 3]
-	ld [hli], a
+	ld [hli], a 
 	ld a, [H_REMAINDER]
 	ld [H_DIVIDEND + 3], a
-	ld a, $a
+	ld a, 10
 	ld [H_DIVISOR], a
 	ld b, $4
 	call Divide

engine/battle/moveEffects/recoil_effect.asm

@@ -3,10 +3,10 @@ RecoilEffect_: ; 1392c (4:792c)
 	and a
 	ld a, [W_PLAYERMOVENUM]
 	ld hl, wBattleMonMaxHP
-	jr z, .asm_1393d
+	jr z, .recoilEffect
 	ld a, [W_ENEMYMOVENUM]
 	ld hl, wEnemyMonMaxHP
-.asm_1393d
+.recoilEffect
 	ld d, a
 	ld a, [W_DAMAGE]
 	ld b, a
@@ -15,22 +15,23 @@ RecoilEffect_: ; 1392c (4:792c)
 	srl b
 	rr c
 	ld a, d
-	cp STRUGGLE
+	cp STRUGGLE ; struggle deals 50% recoil damage
-	jr z, .asm_13953
+	jr z, .gotRecoilDamage
 	srl b
 	rr c
-.asm_13953
+.gotRecoilDamage
 	ld a, b
 	or c
-	jr nz, .asm_13958
+	jr nz, .updateHP
-	inc c
+	inc c ; minimum recoil damage is 1
-.asm_13958
+.updateHP
+; substract HP from user due to the recoil damage
 	ld a, [hli]
 	ld [wHPBarMaxHP+1], a
 	ld a, [hl]
 	ld [wHPBarMaxHP], a
 	push bc
-	ld bc, $fff2
+	ld bc, wBattleMonHP - wBattleMonMaxHP
 	add hl, bc
 	pop bc
 	ld a, [hl]
@@ -43,22 +44,23 @@ RecoilEffect_: ; 1392c (4:792c)
 	sbc b
 	ld [hl], a
 	ld [wHPBarNewHP+1], a
-	jr nc, .asm_13982
+	jr nc, .getHPBarCoords
-	xor a
+; if recoil damage is higher than the Pokemon's HP, set its HP to 0
+	xor a 
 	ld [hli], a
 	ld [hl], a
 	ld hl, wHPBarNewHP
 	ld [hli], a
 	ld [hl], a
-.asm_13982
+.getHPBarCoords
 	hlCoord 10, 9
 	ld a, [H_WHOSETURN]
 	and a
 	ld a, $1
-	jr z, .asm_13990
+	jr z, .updateHPBar
 	hlCoord 2, 2
 	xor a
-.asm_13990
+.updateHPBar
 	ld [wHPBarType], a
 	predef UpdateHPBar2
 	ld hl, HitWithRecoilText

engine/battle/moveEffects/reflect_light_screen_effect.asm

@@ -3,10 +3,10 @@ ReflectLightScreenEffect_: ; 3bb97 (e:7b97)
 	ld de, W_PLAYERMOVEEFFECT
 	ld a, [H_WHOSETURN]
 	and a
-	jr z, .asm_3bba8
+	jr z, .reflectLightScreenEffect
 	ld hl, W_ENEMYBATTSTATUS3
 	ld de, W_ENEMYMOVEEFFECT
-.asm_3bba8
+.reflectLightScreenEffect
 	ld a, [de]
 	cp LIGHT_SCREEN_EFFECT
 	jr nz, .reflect
@@ -14,13 +14,13 @@ ReflectLightScreenEffect_: ; 3bb97 (e:7b97)
 	jr nz, .moveFailed
 	set HasLightScreenUp, [hl] ; mon is now protected by light screen
 	ld hl, LightScreenProtectedText
-	jr .asm_3bbc1
+	jr .playAnim
 .reflect
 	bit HasReflectUp, [hl] ; is mon already protected by reflect?
 	jr nz, .moveFailed
 	set HasReflectUp, [hl] ; mon is now protected by reflect
 	ld hl, ReflectGainedArmorText
-.asm_3bbc1
+.playAnim
 	push hl
 	ld hl, PlayCurrentMoveAnimation
 	call BankswitchEtoF

engine/battle/moveEffects/substitute_effect.asm

@@ -11,46 +11,48 @@ SubstituteEffect_: ; 17dad (5:7dad)
 	ld de, wEnemySubstituteHP
 	ld bc, W_ENEMYBATTSTATUS2
 .notEnemy
-	ld a, [bc]                    ;load flags
+	ld a, [bc] 
-	bit HasSubstituteUp, a        ;user already has substitute?
+	bit HasSubstituteUp, a ; user already has substitute?
-	jr nz, .alreadyHasSubstitute  ;skip this code if so
+	jr nz, .alreadyHasSubstitute 
-	                              ;user doesn't have a substitute [yet]
+; quarter health to remove from user
+; assumes max HP is 1023 or lower	
 	push bc
-	ld a, [hli]  ;load max hp
+	ld a, [hli]
 	ld b, [hl]
-	srl a        ;max hp / 4, [quarter health to remove from user]
+	srl a 
 	rr b
 	srl a
-	rr b
+	rr b ; max hp / 4
 	push de
 	ld de, wBattleMonHP - wBattleMonMaxHP
-	add hl, de    ; point hl to current HP
+	add hl, de ; point hl to current HP low byte
 	pop de
-	ld a, b
+	ld a, b 
-	ld [de], a    ;save copy of HP to subtract in ccd7/ccd8 [how much HP substitute has]
+	ld [de], a ; save copy of HP to subtract in ccd7/ccd8 [how much HP substitute has]
-	ld a, [hld]   ;load current hp
+	ld a, [hld]
-	sub b         ;subtract [max hp / 4]
+; subtract [max hp / 4] to current HP	
-	ld d, a       ;save low byte result in D
+	sub b 
+	ld d, a
 	ld a, [hl]
-	sbc a, 0      ;borrow from high byte if needed
+	sbc 0 
 	pop bc
-	jr c, .notEnoughHP  ;underflow means user would be left with negative health
+	jr c, .notEnoughHP ; underflow means user would be left with negative health
-                        ;bug: note since it only brances on carry, it will possibly leave user with 0HP
+                           ; bug: since it only brances on carry, it will possibly leave user with 0 HP
 .userHasZeroOrMoreHP
-	ldi [hl], a  ;store high byte HP
+	ldi [hl], a ; save resulting HP after substraction into current HP
-	ld [hl], d   ;store low byte HP
+	ld [hl], d   
 	ld h, b
 	ld l, c
-	set HasSubstituteUp, [hl] ;set bit 4 of flags, user now has substitute
+	set HasSubstituteUp, [hl] 
-	ld a, [W_OPTIONS]         ;load options
+	ld a, [W_OPTIONS]         
-	bit 7, a                  ;battle animation is enabled?
+	bit 7, a ; battle animation is enabled?
-	ld hl, PlayCurrentMoveAnimation         ;animation enabled: 0F:7BA8
+	ld hl, PlayCurrentMoveAnimation         
 	ld b, BANK(PlayCurrentMoveAnimation)
 	jr z, .animationEnabled
-	ld hl, AnimationSubstitute ;animation disabled: 1E:56E0
+	ld hl, AnimationSubstitute 
 	ld b, BANK(AnimationSubstitute)
 .animationEnabled
-	call Bankswitch           ;jump to routine depending on animation setting
+	call Bankswitch ; jump to routine depending on animation setting
 	ld hl, SubstituteText
 	call PrintText
 	ld hl, DrawHUDsAndHPBars

engine/battle/moveEffects/transform_effect.asm

@@ -5,13 +5,13 @@ TransformEffect_: ; 3bab1 (e:7ab1)
 	ld a, [W_ENEMYBATTSTATUS1]
 	ld a, [H_WHOSETURN]
 	and a
-	jr nz, .asm_3bad1
+	jr nz, .hitTest
 	ld hl, wEnemyMonSpecies
 	ld de, wBattleMonSpecies
 	ld bc, W_PLAYERBATTSTATUS3
 	ld [wPlayerMoveListIndex], a
 	ld a, [W_PLAYERBATTSTATUS1]
-.asm_3bad1
+.hitTest
 	bit Invulnerable, a ; is mon invulnerable to typical attacks? (fly/dig)
 	jp nz, .failed
 	push hl
@@ -20,10 +20,11 @@ TransformEffect_: ; 3bab1 (e:7ab1)
 	ld hl, W_PLAYERBATTSTATUS2
 	ld a, [H_WHOSETURN]
 	and a
-	jr z, .asm_3bae4
+	jr z, .transformEffect
 	ld hl, W_ENEMYBATTSTATUS2
-.asm_3bae4
+.transformEffect
-	bit HasSubstituteUp, [hl]
+; animation(s) played are different if target has Substitute up
+	bit HasSubstituteUp, [hl] 
 	push af
 	ld hl, Func_79747
 	ld b, BANK(Func_79747)
@@ -32,10 +33,10 @@ TransformEffect_: ; 3bab1 (e:7ab1)
 	add a
 	ld hl, PlayCurrentMoveAnimation
 	ld b, BANK(PlayCurrentMoveAnimation)
-	jr nc, .asm_3baff
+	jr nc, .gotAnimToPlay
 	ld hl, AnimationTransformMon
 	ld b, BANK(AnimationTransformMon)
-.asm_3baff
+.gotAnimToPlay
 	call Bankswitch
 	ld hl, Func_79771
 	ld b, BANK(Func_79771)
@@ -43,15 +44,18 @@ TransformEffect_: ; 3bab1 (e:7ab1)
 	call nz, Bankswitch
 	pop bc
 	ld a, [bc]
-	set Transformed, a
+	set Transformed, a ; mon is now Transformed
 	ld [bc], a
 	pop de
 	pop hl
 	push hl
-	ld a, [hl]
+; transform user into opposing Pokemon	
+; species
+	ld a, [hl] 
 	ld [de], a
+; type 1, type 2, catch rate, and moves	
 	ld bc, $5
-	add hl, bc
+	add hl, bc 
 	inc de
 	inc de
 	inc de
@@ -62,20 +66,23 @@ TransformEffect_: ; 3bab1 (e:7ab1)
 	call CopyData
 	ld a, [H_WHOSETURN]
 	and a
-	jr z, .asm_3bb32
+	jr z, .next
+; save enemy mon DVs in wcceb/wccec (enemy turn only)
 	ld a, [de]
 	ld [wcceb], a
 	inc de
 	ld a, [de]
 	ld [wccec], a
 	dec de
-.asm_3bb32
+.next
+; DVs
 	ld a, [hli]
 	ld [de], a
 	inc de
 	ld a, [hli]
 	ld [de], a
 	inc de
+; Attack, Defense, Speed, and Special stats	
 	inc hl
 	inc hl
 	inc hl
@@ -84,48 +91,51 @@ TransformEffect_: ; 3bab1 (e:7ab1)
 	inc de
 	ld bc, $8
 	call CopyData
-	ld bc, $ffef
+	ld bc, wBattleMonMoves - wBattleMonPP 
-	add hl, bc
+	add hl, bc ; ld hl, wBattleMonMoves
-	ld b, $4
+	ld b, NUM_MOVES
-.asm_3bb4a
+.copyPPLoop
+; 5 PP for all moves
 	ld a, [hli]
 	and a
-	jr z, .asm_3bb57
+	jr z, .lessThanFourMoves
 	ld a, $5
 	ld [de], a
 	inc de
 	dec b
-	jr nz, .asm_3bb4a
+	jr nz, .copyPPLoop
-	jr .asm_3bb5d
+	jr .copyStats
-.asm_3bb57
+.lessThanFourMoves
+; 0 PP for blank moves
 	xor a
 	ld [de], a
 	inc de
 	dec b
-	jr nz, .asm_3bb57
+	jr nz, .lessThanFourMoves
-.asm_3bb5d
+.copyStats
+; original (unmodified) stats and stat mods
 	pop hl
 	ld a, [hl]
 	ld [wd11e], a
 	call GetMonName
 	ld hl, wEnemyMonUnmodifiedAttack
 	ld de, wPlayerMonUnmodifiedAttack
-	call .copyBasedOnTurn
+	call .copyBasedOnTurn ; original (unmodified) stats
 	ld hl, wEnemyMonStatMods
 	ld de, wPlayerMonStatMods
-	call .copyBasedOnTurn
+	call .copyBasedOnTurn ; stat mods
 	ld hl, TransformedText
 	jp PrintText
 
 .copyBasedOnTurn
 	ld a, [H_WHOSETURN]
 	and a
-	jr z, .asm_3bb86
+	jr z, .gotStatsOrModsToCopy
 	push hl
 	ld h, d
 	ld l, e
 	pop de
-.asm_3bb86
+.gotStatsOrModsToCopy
 	ld bc, $8
 	jp CopyData
 

engine/battle/read_trainer_party.asm

@@ -141,9 +141,10 @@ ReadTrainer: ; 39c53 (e:5c53)
 .GiveStarterMove
 	ld a,b
 	ld [wEnemyMon6Moves + 2],a
-.FinishUp ; XXX this needs documenting
+.FinishUp
-	xor a       ; clear D079-D07B
+; clear wAmountMoneyWon addresses
-	ld de,wd079
+	xor a       
+	ld de,wAmountMoneyWon
 	ld [de],a
 	inc de
 	ld [de],a
@@ -152,13 +153,14 @@ ReadTrainer: ; 39c53 (e:5c53)
 	ld a,[W_CURENEMYLVL]
 	ld b,a
 .LastLoop
+; update wAmountMoneyWon addresses (money to win) based on enemy's level
 	ld hl,wd047
-	ld c,2
+	ld c,2 ; wAmountMoneyWon is a 3-byte number
 	push bc
 	predef AddBCDPredef
 	pop bc
 	inc de
 	inc de
 	dec b
-	jr nz,.LastLoop
+	jr nz,.LastLoop ; repeat W_CURENEMYLVL times
 	ret

home.asm

@@ -2908,7 +2908,7 @@ GetTrainerInformation:: ; 3566 (0:3566)
 	ld hl, TrainerPicAndMoneyPointers
 	ld bc, $5
 	call AddNTimes
-	ld de, wd033
+	ld de, wTrainerPicPointer
 	ld a, [hli]
 	ld [de], a
 	inc de
@@ -2922,7 +2922,7 @@ GetTrainerInformation:: ; 3566 (0:3566)
 	ld [de], a
 	jp BankswitchBack
 .linkBattle
-	ld hl, wd033
+	ld hl, wTrainerPicPointer
 	ld de, RedPicFront
 	ld [hl], e
 	inc hl

text.asm

@@ -1114,7 +1114,7 @@ _EnemyMonFaintedText:: ; 0x896c7
 
 _MoneyForWinningText:: ; 896dd (22:56dd)
 	text $52, " got ¥@"
-	TX_BCD wd079, $c3
+	TX_BCD wAmountMoneyWon, $c3
 	db $0
 	line "for winning!"
 	prompt

wram.asm

@@ -432,16 +432,22 @@ wSafariBaitFactor:: ; cce9
 
 wcceb:: ds 1
 wccec:: ds 1
-wMonIsDisobedient:: ds 1
-wccee:: ds 1
-wccef:: ds 1
-wccf0:: ds 1
-wPlayerUsedMove:: ds 1
-wEnemyUsedMove:: ds 1
-wccf3:: ds 1
-wMoveDidntMiss:: ds 1
 
-wPartyFoughtCurrentEnemyFlags::
+wMonIsDisobedient:: ds 1 ; cced
+
+wPlayerDisabledMoveNumber:: ds 1 ; ccee 
+wEnemyDisabledMoveNumber:: ds 1 ; ccef
+
+wccf0:: ds 1
+
+wPlayerUsedMove:: ds 1 ; ccf1
+wEnemyUsedMove:: ds 1 ; ccf2
+
+wccf3:: ds 1
+
+wMoveDidntMiss:: ds 1 ; ccf4
+
+wPartyFoughtCurrentEnemyFlags:: ; ccf5
 ; flags that indicate which party members have fought the current enemy mon
 	flag_array 6
 
@@ -943,8 +949,9 @@ W_TRAINERCLASS:: ; d031
 
 	ds 1
 
-wd033:: ds 1
+wTrainerPicPointer:: ; wd033
-wd034:: ds 2
+	ds 2
+	ds 1
 wd036:: ds 16
 wd046:: ds 1
 wd047:: ds 1
@@ -1066,11 +1073,13 @@ W_PLAYERCONFUSEDCOUNTER:: ; wd06b
 W_PLAYERTOXICCOUNTER:: ; d06c
 	ds 1
 W_PLAYERDISABLEDMOVE:: ; d06d
+; high nibble: which move is disabled (1-4)
+; low nibble: disable turns left
 	ds 1
 
 	ds 1
 
-wEnemyNumAttacksLeft::
+wEnemyNumAttacksLeft:: ; d06f
 ; when the enemy is attacking multiple times, the number of attacks left
 	ds 1
 
@@ -1080,6 +1089,8 @@ W_ENEMYCONFUSEDCOUNTER:: ; wd070
 W_ENEMYTOXICCOUNTER:: ; d071
 	ds 1
 W_ENEMYDISABLEDMOVE:: ; d072
+; high nibble: which move is disabled (1-4)
+; low nibble: disable turns left
 	ds 1
 
 	ds 1
@@ -1093,15 +1104,16 @@ wPlayerBideAccumulatedDamage:: ; d074
 wUnknownSerialCounter2:: ; d075
 ; 2 bytes
 
-ds 4
+	ds 4
 
 wEscapedFromBattle::
 ; non-zero when an item or move that allows escape from battle was used
 	ds 1
 
-wd079:: ds 1
+wd079:: 
+wAmountMoneyWon:: ds 1 ; wd079 - wd07b
 wd07a:: ds 1
-wd07b:: ds 1
+	ds 1
 
 W_ANIMATIONID:: ; d07c
 ; ID number of the current battle animation