Battle animation annotations

8 files changed, 74 insertions, 71 deletions

diff --git a/battle/ai/items.asm b/battle/ai/items.asm
index f5d22d786..c7c8f8201 100644
--- a/battle/ai/items.asm
+++ b/battle/ai/items.asm
@@ -9,7 +9,7 @@ AI_SwitchOrTryItem: ; 38000
 	and a
 	ret nz
 
-	callba CheckSubstatus_RechargeChargedRampageBideRollout
+	callba CheckEnemyLockedIn
 	ret nz
 
 	ld a, [PlayerSubStatus5]
@@ -716,7 +716,7 @@ AI_Switch: ; 3846c
 	ld d, h
 	ld e, l
 	ld hl, EnemyMonStatus
-	ld bc, $0004
+	ld bc, MON_MAXHP - MON_STATUS
 	call CopyBytes
 	pop af
 
@@ -726,7 +726,7 @@ AI_Switch: ; 3846c
 
 .skiptext
 	ld a, 1
-	ld [wd264], a
+	ld [wAISwitch], a
 	callab NewEnemyMonStatus
 	callab ResetEnemyStatLevels
 	ld hl, PlayerSubStatus1
@@ -734,7 +734,7 @@ AI_Switch: ; 3846c
 	callba EnemySwitch
 	callba ResetBattleParticipants
 	xor a
-	ld [wd264], a
+	ld [wAISwitch], a
 	ld a, [wLinkMode]
 	and a
 	ret nz
diff --git a/battle/ai/move.asm b/battle/ai/move.asm
index 5f58bae3e..eb6a0536d 100755
--- a/battle/ai/move.asm
+++ b/battle/ai/move.asm
@@ -12,7 +12,7 @@ AIChooseMove: ; 440ce
 	ret nz
 
 ; No use picking a move if there's no choice.
-	callba CheckSubstatus_RechargeChargedRampageBideRollout
+	callba CheckEnemyLockedIn
 	ret nz
 
 
diff --git a/battle/anim_gfx.asm b/battle/anim_gfx.asm
index c84dda83f..996c17f1e 100644
--- a/battle/anim_gfx.asm
+++ b/battle/anim_gfx.asm
@@ -1,9 +1,9 @@
 AnimObj00GFX: ; 84a2e
-AnimObj01GFX: INCBIN "gfx/fx/001.2bpp.lz"
-AnimObj02GFX: INCBIN "gfx/fx/002.2bpp.lz"
-AnimObj03GFX: INCBIN "gfx/fx/003.2bpp.lz"
-AnimObj04GFX: INCBIN "gfx/fx/004.2bpp.lz"
-AnimObj05GFX: INCBIN "gfx/fx/005.2bpp.lz"
+AnimObjHitGFX: INCBIN "gfx/fx/001.2bpp.lz"
+AnimObjCutGFX: INCBIN "gfx/fx/002.2bpp.lz"
+AnimObjFireGFX: INCBIN "gfx/fx/003.2bpp.lz"
+AnimObjWaterGFX: INCBIN "gfx/fx/004.2bpp.lz"
+AnimObjLightningGFX: INCBIN "gfx/fx/005.2bpp.lz"
 AnimObj07GFX: INCBIN "gfx/fx/007.2bpp.lz"
 AnimObj08GFX: INCBIN "gfx/fx/008.2bpp.lz"
 AnimObj10GFX: INCBIN "gfx/fx/010.2bpp.lz"
diff --git a/battle/anims.asm b/battle/anims.asm
index 5d8050c83..66ae9ff1b 100644
--- a/battle/anims.asm
+++ b/battle/anims.asm
@@ -1323,7 +1323,7 @@ BattleAnim_Thundershock: ; c9b53
 
 BattleAnim_Thunderbolt: ; c9b66
 	anim_2gfx ANIM_GFX_LIGHTNING, ANIM_GFX_EXPLOSION
-	anim_obj ANIM_OBJ_32, -15, 0,   7, 0, $2
+	anim_obj ANIM_OBJ_LIGHTNING_BOLT, -15, 0,   7, 0, $2
 	anim_wait 16
 	anim_bgeffect ANIM_BG_FLASH_INVERTED, $0, $4, $2
 	anim_sound 0, 1, SFX_THUNDERSHOCK
@@ -2497,10 +2497,10 @@ BattleAnim_Transform: ; ca54d
 	anim_call BattleAnim_FollowPlayerHead_0
 	anim_transform
 	anim_sound 0, 0, SFX_PSYBEAM
-	anim_bgeffect ANIM_BG_28, $0, $1, $0
+	anim_bgeffect ANIM_BG_WAVE_DEFORM_USER, $0, $1, $0
 	anim_wait 48
 	anim_updateactorpic
-	anim_incbgeffect ANIM_BG_28
+	anim_incbgeffect ANIM_BG_WAVE_DEFORM_USER
 	anim_wait 48
 	anim_call BattleAnim_ShowMon_0
 	anim_ret
@@ -2759,10 +2759,10 @@ BattleAnim_Minimize: ; ca78a
 	anim_1gfx ANIM_GFX_HIT
 	anim_call BattleAnim_FollowPlayerHead_0
 	anim_minimize
-	anim_bgeffect ANIM_BG_28, $0, $1, $0
+	anim_bgeffect ANIM_BG_WAVE_DEFORM_USER, $0, $1, $0
 	anim_wait 48
 	anim_updateactorpic
-	anim_incbgeffect ANIM_BG_28
+	anim_incbgeffect ANIM_BG_WAVE_DEFORM_USER
 	anim_wait 48
 	anim_call BattleAnim_ShowMon_0
 	anim_ret
@@ -2774,7 +2774,7 @@ BattleAnim_SkyAttack: ; ca7a1
 	anim_bgeffect ANIM_BG_27, $0, $1, $0
 	anim_wait 32
 	anim_sound 0, 0, SFX_HYPER_BEAM
-	anim_obj ANIM_OBJ_6E,   6, 0,  11, 0, $40
+	anim_obj ANIM_OBJ_SKY_ATTACK_FEAROW,   6, 0,  11, 0, $40
 	anim_wait 64
 	anim_incobj  1
 	anim_wait 21
@@ -2805,7 +2805,7 @@ BattleAnim_NightShade: ; ca7cc
 BattleAnim_Lick: ; ca7e5
 	anim_1gfx ANIM_GFX_WATER
 	anim_sound 0, 1, SFX_LICK
-	anim_obj ANIM_OBJ_6F, -15, 0,   7, 0, $0
+	anim_obj ANIM_OBJ_LICK, -15, 0,   7, 0, $0
 	anim_wait 64
 	anim_ret
 ; ca7f1
@@ -3025,9 +3025,9 @@ BattleAnim_Meditate: ; ca9d8
 	anim_1gfx ANIM_GFX_HIT
 	anim_call BattleAnim_FollowEnemyFeet_0
 	anim_sound 0, 0, SFX_PSYBEAM
-	anim_bgeffect ANIM_BG_28, $0, $1, $0
+	anim_bgeffect ANIM_BG_WAVE_DEFORM_USER, $0, $1, $0
 	anim_wait 48
-	anim_incbgeffect ANIM_BG_28
+	anim_incbgeffect ANIM_BG_WAVE_DEFORM_USER
 	anim_wait 48
 	anim_call BattleAnim_ShowMon_0
 	anim_ret
@@ -3765,13 +3765,13 @@ BattleAnim_Octazooka: ; cb06f
 BattleAnim_Spikes: ; cb092
 	anim_1gfx ANIM_GFX_MISC
 	anim_sound 6, 2, SFX_MENU
-	anim_obj ANIM_OBJ_8E,   6, 0,  11, 0, $20
+	anim_obj ANIM_OBJ_SPIKES,   6, 0,  11, 0, $20
 	anim_wait 8
 	anim_sound 6, 2, SFX_MENU
-	anim_obj ANIM_OBJ_8E,   6, 0,  11, 0, $30
+	anim_obj ANIM_OBJ_SPIKES,   6, 0,  11, 0, $30
 	anim_wait 8
 	anim_sound 6, 2, SFX_MENU
-	anim_obj ANIM_OBJ_8E,   6, 0,  11, 0, $28
+	anim_obj ANIM_OBJ_SPIKES,   6, 0,  11, 0, $28
 	anim_wait 64
 	anim_ret
 ; cb0b0
@@ -3784,7 +3784,7 @@ BattleAnim_ZapCannon: ; cb0b0
 	anim_obj ANIM_OBJ_A3,   8, 0,  11, 4, $2
 	anim_wait 40
 	anim_sound 0, 1, SFX_THUNDERSHOCK
-	anim_obj ANIM_OBJ_32, -15, 0,   7, 0, $2
+	anim_obj ANIM_OBJ_LIGHTNING_BOLT, -15, 0,   7, 0, $2
 	anim_wait 16
 	anim_obj ANIM_OBJ_31, -15, 0,   7, 0, $0
 	anim_wait 128
@@ -3830,14 +3830,14 @@ BattleAnim_PerishSong: ; cb113
 	anim_bgeffect ANIM_BG_06, $0, $2, $0
 	anim_bgeffect ANIM_BG_ALTERNATE_HUES, $0, $2, $0
 	anim_sound 0, 2, SFX_PERISH_SONG
-	anim_obj ANIM_OBJ_A6,  11, 0,   0, 0, $0
-	anim_obj ANIM_OBJ_A6,  11, 0,   0, 0, $8
-	anim_obj ANIM_OBJ_A6,  11, 0,   0, 0, $10
-	anim_obj ANIM_OBJ_A6,  11, 0,   0, 0, $18
-	anim_obj ANIM_OBJ_A6,  11, 0,   0, 0, $20
-	anim_obj ANIM_OBJ_A6,  11, 0,   0, 0, $28
-	anim_obj ANIM_OBJ_A6,  11, 0,   0, 0, $30
-	anim_obj ANIM_OBJ_A6,  11, 0,   0, 0, $38
+	anim_obj ANIM_OBJ_PERISH_SONG,  11, 0,   0, 0, $0
+	anim_obj ANIM_OBJ_PERISH_SONG,  11, 0,   0, 0, $8
+	anim_obj ANIM_OBJ_PERISH_SONG,  11, 0,   0, 0, $10
+	anim_obj ANIM_OBJ_PERISH_SONG,  11, 0,   0, 0, $18
+	anim_obj ANIM_OBJ_PERISH_SONG,  11, 0,   0, 0, $20
+	anim_obj ANIM_OBJ_PERISH_SONG,  11, 0,   0, 0, $28
+	anim_obj ANIM_OBJ_PERISH_SONG,  11, 0,   0, 0, $30
+	anim_obj ANIM_OBJ_PERISH_SONG,  11, 0,   0, 0, $38
 	anim_wait 112
 	anim_ret
 ; cb14c
@@ -4087,7 +4087,7 @@ BattleAnim_Spark: ; cb34d
 	anim_incobj  2
 	anim_wait 1
 	anim_sound 0, 1, SFX_THUNDERSHOCK
-	anim_obj ANIM_OBJ_32, -15, 0,   7, 0, $2
+	anim_obj ANIM_OBJ_LIGHTNING_BOLT, -15, 0,   7, 0, $2
 	anim_obj ANIM_OBJ_33, -15, 0,   7, 0, $0
 	anim_wait 32
 	anim_ret
diff --git a/battle/core.asm b/battle/core.asm
index 7e6eea9c6..34e43a9ab 100644
--- a/battle/core.asm
+++ b/battle/core.asm
@@ -7,7 +7,7 @@ DoBattle: ; 3c000
 	ld [wPlayerAction], a
 	ld [BattleEnded], a
 	inc a
-	ld [wd264], a
+	ld [wAISwitch], a
 	ld hl, OTPartyMon1HP
 	ld bc, PARTYMON_STRUCT_LENGTH - 1
 	ld d, BATTLEACTION_SWITCH1 - 1
@@ -60,7 +60,7 @@ DoBattle: ; 3c000
 	xor a
 	ld [CurPartyMon], a
 .loop2
-	call CheckIfPartyHasPkmnToBattleWith
+	call CheckIfCurPartyMonIsFitToFight
 	jr nz, .alive2
 	ld hl, CurPartyMon
 	inc [hl]
@@ -170,7 +170,7 @@ BattleTurn: ; 3c12f
 	xor a
 	ld [wPlayerIsSwitching], a
 	ld [wEnemyIsSwitching], a
-	ld [wd264], a
+	ld [wAISwitch], a
 	ld [wPlayerJustGotFrozen], a
 	ld [wEnemyJustGotFrozen], a
 	ld [CurDamage], a
@@ -2497,7 +2497,7 @@ WinTrainerBattle: ; 3cfa4
 	call PrintWinLossText
 
 .skip_win_loss_text
-	jp HandleBattleReward
+	jp .GiveMoney
 
 .mobile
 	call BattleWinSlideInEnemyTrainerFrontpic
@@ -2524,9 +2524,8 @@ WinTrainerBattle: ; 3cfa4
 	call ClearTileMap
 	call ClearBGPalettes
 	ret
-; 3d02b
 
-HandleBattleReward: ; 3d02b
+.GiveMoney
 	ld a, [wAmuletCoin]
 	and a
 	call nz, .DoubleReward
@@ -3024,7 +3023,7 @@ PickPartyMonInBattle: ; 3d33c
 	call JumpToPartyMenuAndPrintText
 	call SelectBattleMon
 	ret c
-	call CheckIfPartyHasPkmnToBattleWith
+	call CheckIfCurPartyMonIsFitToFight
 	jr z, .loop
 	xor a
 	ret
@@ -3373,14 +3372,14 @@ CheckWhetherSwitchmonIsPredetermined: ; 3d533
 .not_linked
 	ld a, [wEnemySwitchMonIndex]
 	and a
-	jr z, .check_wd264
+	jr z, .check_wAISwitch
 
 	dec a
 	ld b, a
 	jr .return_carry
 
-.check_wd264
-	ld a, [wd264]
+.check_wAISwitch
+	ld a, [wAISwitch]
 	and a
 	ld b, $0
 	jr nz, .return_carry
@@ -3656,7 +3655,7 @@ LoadEnemyPkmnToSwitchTo: ; 3d6ca
 ; 3d714
 
 CheckWhetherToAskSwitch: ; 3d714
-	ld a, [wd264]
+	ld a, [wAISwitch]
 	dec a
 	jp z, .return_nc
 	ld a, [PartyCount]
@@ -3836,19 +3835,19 @@ CheckPlayerPartyForFitPkmn: ; 3d873
 	xor a
 	ld hl, PartyMon1HP
 	ld bc, PartyMon2 - (PartyMon1 + 1)
-.asm_3d87e
+.loop
 	or [hl]
 	inc hl
 	or [hl]
 	add hl, bc
 	dec e
-	jr nz, .asm_3d87e
+	jr nz, .loop
 	ld d, a
 	ret
 ; 3d887
 
 
-CheckIfPartyHasPkmnToBattleWith: ; 3d887
+CheckIfCurPartyMonIsFitToFight: ; 3d887
 	ld a, [CurPartyMon]
 	ld hl, PartyMon1HP
 	call GetPartyLocation
@@ -3856,9 +3855,9 @@ CheckIfPartyHasPkmnToBattleWith: ; 3d887
 	or [hl]
 	ret nz
 
-	ld a, [wd264]
+	ld a, [wAISwitch]
 	and a
-	jr nz, .asm_3d8b1
+	jr nz, .finish_fail
 	ld hl, PartySpecies
 	ld a, [CurPartyMon]
 	ld c, a
@@ -3867,14 +3866,14 @@ CheckIfPartyHasPkmnToBattleWith: ; 3d887
 	ld a, [hl]
 	cp EGG
 	ld hl, BattleText_AnEGGCantBattle
-	jr z, .asm_3d8ae
+	jr z, .print_textbox
 
 	ld hl, BattleText_TheresNoWillToBattle
 
-.asm_3d8ae
+.print_textbox
 	call StdBattleTextBox
 
-.asm_3d8b1
+.finish_fail
 	xor a
 	ret
 ; 3d8b3
@@ -4501,6 +4500,8 @@ HandleHPHealingItem: ; 3dd2f
 	ld hl, BattleMonMaxHP
 
 .go
+; If, and only if, Pokemon's HP is less than half max, use the item.
+; Store current HP in Buffer 3/4
 	push bc
 	ld a, [de]
 	ld [Buffer3], a
@@ -4528,6 +4529,7 @@ HandleHPHealingItem: ; 3dd2f
 
 .less
 	call ItemRecoveryAnim
+	; store max HP in Buffer1/2
 	ld a, [hli]
 	ld [Buffer2], a
 	ld a, [hl]
@@ -5434,7 +5436,7 @@ TryPlayerSwitch: ; 3e358
 	jp BattleMenuPKMN_Loop
 
 .try_switch
-	call CheckIfPartyHasPkmnToBattleWith
+	call CheckIfCurPartyMonIsFitToFight
 	jp z, BattleMenuPKMN_Loop
 	ld a, [CurBattleMon]
 	ld [LastPlayerMon], a
@@ -5675,15 +5677,15 @@ MoveSelectionScreen: ; 3e4bc
 	ld c, $2c
 	ld a, [wMoveSelectionMenuType]
 	dec a
-	ld b, $c1
+	ld b, D_DOWN | D_UP | A_BUTTON
 	jr z, .okay
 	dec a
-	ld b, $c3
+	ld b, D_DOWN | D_UP | A_BUTTON | B_BUTTON
 	jr z, .okay
 	ld a, [wLinkMode]
 	and a
 	jr nz, .okay
-	ld b, $c7
+	ld b, D_DOWN | D_UP | A_BUTTON | B_BUTTON | SELECT
 
 .okay
 	ld a, b
@@ -5727,6 +5729,7 @@ MoveSelectionScreen: ; 3e4bc
 	bit SELECT_F, a
 	jp nz, .pressed_select
 	bit B_BUTTON_F, a
+	; A button
 	push af
 
 	xor a
@@ -6106,7 +6109,7 @@ ParseEnemyAction: ; 3e7c1
 	jp .finish
 
 .skip_encore
-	call CheckSubstatus_RechargeChargedRampageBideRollout
+	call CheckEnemyLockedIn
 	jp nz, ResetVarsForSubstatusRage
 	jr .continue
 
@@ -6173,7 +6176,7 @@ ParseEnemyAction: ; 3e7c1
 .skip_load
 	call SetEnemyTurn
 	callab UpdateMoveData
-	call CheckSubstatus_RechargeChargedRampageBideRollout
+	call CheckEnemyLockedIn
 	jr nz, .raging
 	xor a
 	ld [wEnemyCharging], a
@@ -6219,7 +6222,7 @@ ResetVarsForSubstatusRage: ; 3e8c1
 	ret
 ; 3e8d1
 
-CheckSubstatus_RechargeChargedRampageBideRollout: ; 3e8d1
+CheckEnemyLockedIn: ; 3e8d1
 	ld a, [EnemySubStatus4]
 	and 1 << SUBSTATUS_RECHARGE
 	ret nz
@@ -8025,7 +8028,7 @@ SendOutPkmnText: ; 3f26d
 
 	ld hl, JumpText_GoPkmn ; If we're in a LinkBattle print just "Go <PlayerMon>"
 
-	ld a, [wd264] ; unless this (unidentified) variable is set
+	ld a, [wAISwitch] ; unless this (unidentified) variable is set
 	and a
 	jr nz, .skip_to_textbox
 
@@ -8482,7 +8485,7 @@ BattleIntro: ; 3f4dd
 	ld [hMapAnims], a
 	callba PlayBattleMusic
 	callba ShowLinkBattleParticipants
-	callba FindFirstAliveMon
+	callba FindFirstAliveMonAndStartBattle
 	call DisableSpriteUpdates
 	callba ClearBattleRAM
 	call InitEnemy
diff --git a/battle/moves/move_effects.asm b/battle/moves/move_effects.asm
index 454a1ac9b..2d4c06a33 100644
--- a/battle/moves/move_effects.asm
+++ b/battle/moves/move_effects.asm
@@ -2095,7 +2095,7 @@ FutureSight:
 	damagestats
 	damagecalc
 	futuresight
-	damagevariation
+	damagevariation ; skip here if last turn
 	checkhit
 	hittargetnosub
 	failuretext
diff --git a/battle/objects/data.asm b/battle/objects/data.asm
index 7ae0dc371..8a3f42f85 100755
--- a/battle/objects/data.asm
+++ b/battle/objects/data.asm
@@ -156,7 +156,7 @@ endm
 ; ANIM_OBJ_31
 	battleanimobj $21, $90, BATTLEANIMFRAMESET_36, BATTLEANIMFUNC_00, $03, $05
 
-; ANIM_OBJ_32
+; ANIM_OBJ_LIGHTNING_BOLT
 	battleanimobj $21, $90, BATTLEANIMFRAMESET_37, BATTLEANIMFUNC_03, $02, $08
 
 ; ANIM_OBJ_33
@@ -336,10 +336,10 @@ endm
 ; ANIM_OBJ_6D
 	battleanimobj $01, $88, BATTLEANIMFRAMESET_7A, BATTLEANIMFUNC_31, $03, $11
 
-; ANIM_OBJ_6E
+; ANIM_OBJ_SKY_ATTACK_FEAROW
 	battleanimobj $21, $88, BATTLEANIMFRAMESET_7B, BATTLEANIMFUNC_32, $02, $20
 
-; ANIM_OBJ_6F
+; ANIM_OBJ_LICK
 	battleanimobj $21, $98, BATTLEANIMFRAMESET_7C, BATTLEANIMFUNC_00, $02, $04
 
 ; ANIM_OBJ_70
@@ -432,7 +432,7 @@ endm
 ; ANIM_OBJ_8D
 	battleanimobj $21, $a0, BATTLEANIMFRAMESET_99, BATTLEANIMFUNC_35, $04, $19
 
-; ANIM_OBJ_8E
+; ANIM_OBJ_SPIKES
 	battleanimobj $21, $70, BATTLEANIMFRAMESET_8B, BATTLEANIMFUNC_3F, $02, $1f
 
 ; ANIM_OBJ_8F
@@ -504,7 +504,7 @@ endm
 ; ANIM_OBJ_A5
 	battleanimobj $61, $90, BATTLEANIMFRAMESET_A9, BATTLEANIMFUNC_46, $02, $23
 
-; ANIM_OBJ_A6
+; ANIM_OBJ_PERISH_SONG
 	battleanimobj $00, $00, BATTLEANIMFRAMESET_24, BATTLEANIMFUNC_47, $02, $0e
 
 ; ANIM_OBJ_A7
diff --git a/battle/objects/gfx_headers.asm b/battle/objects/gfx_headers.asm
index bec34ce74..eadd1abfb 100755
--- a/battle/objects/gfx_headers.asm
+++ b/battle/objects/gfx_headers.asm
@@ -8,11 +8,11 @@ object_gfx: MACRO
 ENDM
 
 	object_gfx  0, AnimObj00GFX
-	object_gfx 21, AnimObj01GFX
-	object_gfx  6, AnimObj02GFX
-	object_gfx  6, AnimObj03GFX
-	object_gfx 20, AnimObj04GFX
-	object_gfx 26, AnimObj05GFX
+	object_gfx 21, AnimObjHitGFX
+	object_gfx  6, AnimObjCutGFX
+	object_gfx  6, AnimObjFireGFX
+	object_gfx 20, AnimObjWaterGFX
+	object_gfx 26, AnimObjLightningGFX
 	object_gfx 18, AnimObj06GFX
 	object_gfx 12, AnimObj07GFX
 	object_gfx  9, AnimObj08GFX