Merge branch 'master' into master

1 files changed, 122 insertions, 101 deletions

diff --git a/src/engine/home.asm b/src/engine/home.asm
index 69cb3b5..cdb96c9 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -858,6 +858,7 @@ CallIndirect: ; 05b6 (0:05b6)
 	ld h, a
 	pop af
 ;	fallthrough
+
 CallHL: ; 05c1 (0:05c1)
 	jp hl
 ; 0x5c2
@@ -2811,19 +2812,21 @@ ExchangeRNG: ; 0f58 (0:0f58)
 	jp c, DuelTransmissionError
 	ret
 
-; sets hAIActionTableIndex to an AI action specified in register a.
-; send 10 bytes of data to the other game from hAIActionTableIndex, hTempCardIndex_ff9f,
+; sets hOppActionTableIndex to an AI action specified in register a.
+; send 10 bytes of data to the other game from hOppActionTableIndex, hTempCardIndex_ff9f,
 ; hTemp_ffa0, and hTempPlayAreaLocation_ffa1, and hTempRetreatCostCards.
 ; finally exchange RNG data.
-SetAIAction_SerialSendDuelData: ; 0f7f (0:0f7f)
+; the receiving side will use this data to read the OPP_ACTION_* value in
+; [hOppActionTableIndex] and match it by calling the correspoding OppAction* function
+SetOppAction_SerialSendDuelData: ; 0f7f (0:0f7f)
 	push hl
 	push bc
-	ldh [hAIActionTableIndex], a
+	ldh [hOppActionTableIndex], a
 	ld a, DUELVARS_DUELIST_TYPE
 	call GetNonTurnDuelistVariable
 	cp DUELIST_TYPE_LINK_OPP
 	jr nz, .not_link
-	ld hl, hAIActionTableIndex
+	ld hl, hOppActionTableIndex
 	ld bc, 10
 	call SerialSendBytes
 	call ExchangeRNG
@@ -2833,13 +2836,13 @@ SetAIAction_SerialSendDuelData: ; 0f7f (0:0f7f)
 	ret
 ; 0xf9b
 
-; receive 10 bytes of data from wSerialRecvBuf and store them into hAIActionTableIndex,
+; receive 10 bytes of data from wSerialRecvBuf and store them into hOppActionTableIndex,
 ; hTempCardIndex_ff9f, hTemp_ffa0, and hTempPlayAreaLocation_ffa1,
 ; and hTempRetreatCostCards. also exchange RNG data.
 SerialRecvDuelData: ; 0f9b (0:0f9b)
 	push hl
 	push bc
-	ld hl, hAIActionTableIndex
+	ld hl, hOppActionTableIndex
 	ld bc, 10
 	call SerialRecvBytes
 	call ExchangeRNG
@@ -3287,8 +3290,8 @@ MoveDiscardPileCardToHand: ; 1182 (0:1182)
 	ret
 ; 0x11a5
 
-; return in the z flag whether turn holder's prize a (0-7) has been taken or not
-; z: taken, nz: not taken
+; return in the z flag whether turn holder's prize a (0-7) has been drawn or not
+; z: drawn, nz: not drawn
 CheckPrizeTaken: ; 11a5 (0:11a5)
 	ld e, a
 	ld d, 0
@@ -3788,8 +3791,8 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	ldh a, [hTempCardIndex_ff98]
 	call PutHandCardInPlayArea
 	; update the Pokemon's HP with the difference
-	ldh a, [hTempPlayAreaLocation_ff9d]
-	ld a, e ; derp
+	ldh a, [hTempPlayAreaLocation_ff9d] ; derp
+	ld a, e
 	add DUELVARS_ARENA_CARD_HP
 	call GetTurnDuelistVariable
 	ld a, [wLoadedCard2HP]
@@ -4020,8 +4023,8 @@ PutHandCardInPlayArea: ; 14d2 (0:14d2)
 	ret
 ; 0x14dd
 
-; move the play area Pokemon card of the turn holder at CARD_LOCATION_PLAY_AREA + a
-; to the discard pile
+; move the Pokemon card of the turn holder in the
+; PLAY_AREA_* location given in e to the discard pile
 MovePlayAreaCardToDiscardPile: ; 14dd (0:14dd)
 	call EmptyPlayAreaSlot
 	ld l, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
@@ -4290,9 +4293,9 @@ GetNonTurnDuelistVariable: ; 1611 (0:1611)
 	ldh a, [hWhoseTurn]
 	ld h, OPPONENT_TURN
 	cp PLAYER_TURN
-	jr z, .asm_161c
+	jr z, .ok
 	ld h, PLAYER_TURN
-.asm_161c
+.ok
 	ld a, [hl]
 	ret
 ; 0x161e
@@ -4367,7 +4370,7 @@ Func_161e: ; 161e (0:161e)
 	call DrawWideTextBox_WaitForInput
 	call ExchangeRNG
 	call Func_7415
-	ld a, $07
+	ld a, EFFECTCMDTYPE_PKMN_POWER_TRIGGER
 	call TryExecuteEffectCommandFunction
 	ret
 ; 0x16ad
@@ -4452,15 +4455,15 @@ Func_16f6: ; 16f6 (0:16f6)
 	xor a
 	ld [wccec], a
 	ld [wEffectFunctionsFeedbackIndex], a
-	ld [wcced], a
+	ld [wEffectFailed], a
 	ld [wIsDamageToSelf], a
 	ld [wccef], a
 	ld [wccf0], a
-	ld [wccf1], a
+	ld [wNoEffectFromStatus], a
 	bank1call ClearNonTurnTemporaryDuelvars_CopyStatus
 	ret
 
-; use attack or Pokemon Power
+; Use an attack (from DuelMenu_Attack) or a Pokemon Power (from DuelMenu_PkmnPower)
 UseAttackOrPokemonPower: ; 1730 (0:1730)
 	ld a, [wSelectedMoveIndex]
 	ld [wPlayerAttackingMoveIndex], a
@@ -4472,52 +4475,51 @@ UseAttackOrPokemonPower: ; 1730 (0:1730)
 	cp POKEMON_POWER
 	jp z, UsePokemonPower
 	call Func_16f6
-	ld a, $1
+	ld a, EFFECTCMDTYPE_INITIAL_EFFECT_1
 	call TryExecuteEffectCommandFunction
 	jp c, DrawWideTextBox_WaitForInput_ReturnCarry
 	call CheckSandAttackOrSmokescreenSubstatus
-	jr c, .asm_1766
-	ld a, $2
+	jr c, .sand_attack_smokescreen
+	ld a, EFFECTCMDTYPE_INITIAL_EFFECT_2
 	call TryExecuteEffectCommandFunction
 	jp c, ReturnCarry
-	call Func_1874
-	jr .asm_1777
-.asm_1766
-	call Func_1874
+	call SendAttackDataToLinkOpponent
+	jr .next
+.sand_attack_smokescreen
+	call SendAttackDataToLinkOpponent
 	call HandleSandAttackOrSmokescreenSubstatus
 	jp c, ClearNonTurnTemporaryDuelvars_ResetCarry
-	ld a, $2
+	ld a, EFFECTCMDTYPE_INITIAL_EFFECT_2
 	call TryExecuteEffectCommandFunction
 	jp c, ReturnCarry
-.asm_1777
-	ld a, $9
-	call SetAIAction_SerialSendDuelData
-	ld a, $6
+.next
+	ld a, OPPACTION_USE_ATTACK
+	call SetOppAction_SerialSendDuelData
+	ld a, EFFECTCMDTYPE_DISCARD_ENERGY
 	call TryExecuteEffectCommandFunction
 	call CheckSelfConfusionDamage
-	jp c, DealConfusionDamageToSelf
+	jp c, HandleConfusionDamageToSelf
 	call DrawDuelMainScene_PrintPokemonsAttackText
 	call WaitForWideTextBoxInput
 	call ExchangeRNG
-	ld a, $5
+	ld a, EFFECTCMDTYPE_REQUIRE_SELECTION
 	call TryExecuteEffectCommandFunction
-	ld a, $a
-	call SetAIAction_SerialSendDuelData
+	ld a, OPPACTION_ATTACK_ANIM_AND_DAMAGE
+	call SetOppAction_SerialSendDuelData
 ;	fallthrough
 
-; deal attack damage
-Func_179a: ; 179a (0:179a)
+PlayAttackAnimation_DealAttackDamage: ; 179a (0:179a)
 	call Func_7415
 	ld a, [wLoadedMoveCategory]
 	and RESIDUAL
-	jr nz, .asm_17ad
+	jr nz, .deal_damage
 	call SwapTurn
 	call HandleNoDamageOrEffectSubstatus
 	call SwapTurn
-.asm_17ad
+.deal_damage
 	xor a
 	ldh [hTempPlayAreaLocation_ff9d], a
-	ld a, $3
+	ld a, EFFECTCMDTYPE_BEFORE_DAMAGE
 	call TryExecuteEffectCommandFunction
 	call ApplyDamageModifiers_DamageToTarget
 	call Func_189d
@@ -4532,9 +4534,9 @@ Func_179a: ; 179a (0:179a)
 	call GetNonTurnDuelistVariable
 	push de
 	push hl
-	call Func_7494
+	call PlayMoveAnimation
 	call Func_741a
-	call Func_7484
+	call WaitMoveAnimation
 	pop hl
 	pop de
 	call SubstractHP
@@ -4561,7 +4563,7 @@ Func_17ed: ; 17ed (0:17ed)
 Func_17fb: ; 17fb (0:17fb)
 	ld a, [wTempNonTurnDuelistCardID]
 	push af
-	ld a, $4
+	ld a, EFFECTCMDTYPE_AFTER_DAMAGE
 	call TryExecuteEffectCommandFunction
 	pop af
 	ld [wTempNonTurnDuelistCardID], a
@@ -4577,9 +4579,11 @@ DisplayUsePokemonPowerScreen_WaitForInput: ; 1819 (0:1819)
 	push hl
 	call DisplayUsePokemonPowerScreen
 	pop hl
+;	fallthrough
 
 DrawWideTextBox_WaitForInput_ReturnCarry: ; 181e (0:181e)
 	call DrawWideTextBox_WaitForInput
+;	fallthrough
 
 ReturnCarry: ; 1821 (0:1821)
 	scf
@@ -4590,7 +4594,9 @@ ClearNonTurnTemporaryDuelvars_ResetCarry: ; 1823 (0:1823)
 	or a
 	ret
 
-DealConfusionDamageToSelf: ; 1828 (0:1828)
+; called when attacker deals damage to itself due to confusion
+; display the corresponding animation and deal damage to self
+HandleConfusionDamageToSelf: ; 1828 (0:1828)
 	bank1call DrawDuelMainScene
 	ld a, 1
 	ld [wIsDamageToSelf], a
@@ -4599,7 +4605,7 @@ DealConfusionDamageToSelf: ; 1828 (0:1828)
 	ld a, $75
 	ld [wLoadedMoveAnimation], a
 	ld a, 20 ; damage
-	call Func_195c
+	call DealConfusionDamageToSelf
 	call Func_1bb4
 	call Func_6e49
 	bank1call ClearNonTurnTemporaryDuelvars
@@ -4609,24 +4615,27 @@ DealConfusionDamageToSelf: ; 1828 (0:1828)
 ; use Pokemon Power
 UsePokemonPower: ; 184b (0:184b)
 	call Func_7415
-	ld a, $2
+	ld a, EFFECTCMDTYPE_INITIAL_EFFECT_2
 	call TryExecuteEffectCommandFunction
 	jr c, DisplayUsePokemonPowerScreen_WaitForInput
-	ld a, $5
+	ld a, EFFECTCMDTYPE_REQUIRE_SELECTION
 	call TryExecuteEffectCommandFunction
 	jr c, ReturnCarry
-	ld a, $c
-	call SetAIAction_SerialSendDuelData
+	ld a, OPPACTION_USE_PKMN_POWER
+	call SetOppAction_SerialSendDuelData
 	call ExchangeRNG
-	ld a, $d
-	call SetAIAction_SerialSendDuelData
-	ld a, $3
+	ld a, OPPACTION_EXECUTE_PKMN_POWER_EFFECT
+	call SetOppAction_SerialSendDuelData
+	ld a, EFFECTCMDTYPE_BEFORE_DAMAGE
 	call TryExecuteEffectCommandFunction
-	ld a, $16
-	call SetAIAction_SerialSendDuelData
+	ld a, OPPACTION_DUEL_MAIN_SCENE
+	call SetOppAction_SerialSendDuelData
 	ret
 
-Func_1874: ; 1874 (0:1874)
+; called by UseAttackOrPokemonPower (on an attack only)
+; in a link duel, it's used to send the other game data about the
+; attack being in use, triggering a call to OppAction_BeginUseAttack in the receiver
+SendAttackDataToLinkOpponent: ; 1874 (0:1874)
 	ld a, [wccec]
 	or a
 	ret nz
@@ -4640,8 +4649,8 @@ Func_1874: ; 1874 (0:1874)
 	ldh [hTempCardIndex_ff9f], a
 	ld a, [wPlayerAttackingMoveIndex]
 	ldh [hTemp_ffa0], a
-	ld a, $8
-	call SetAIAction_SerialSendDuelData
+	ld a, OPPACTION_BEGIN_ATTACK
+	call SetOppAction_SerialSendDuelData
 	call ExchangeRNG
 	pop af
 	ldh [hTempCardIndex_ff9f], a
@@ -4706,10 +4715,10 @@ CheckSelfConfusionDamage: ; 18d7 (0:18d7)
 	ret
 ; 0x18f9
 
-; use the trainer card with deck index at hTempCardIndex_ff98.
+; play the trainer card with deck index at hTempCardIndex_ff98.
 ; a trainer card is like a move effect, with its own effect commands.
 ; return nc if the card was played, carry if it wasn't.
-UseTrainerCard: ; 18f9 (0:18f9)
+PlayTrainerCard: ; 18f9 (0:18f9)
 	call CheckCantUseTrainerDueToHeadache
 	jr c, .cant_use
 	ldh a, [hWhoseTurn]
@@ -4717,7 +4726,7 @@ UseTrainerCard: ; 18f9 (0:18f9)
 	ldh a, [hTempCardIndex_ff98]
 	ldh [hTempCardIndex_ff9f], a
 	call LoadNonPokemonCardEffectCommands
-	ld a, $01
+	ld a, EFFECTCMDTYPE_INITIAL_EFFECT_1
 	call TryExecuteEffectCommandFunction
 	jr nc, .can_use
 .cant_use
@@ -4725,20 +4734,20 @@ UseTrainerCard: ; 18f9 (0:18f9)
 	scf
 	ret
 .can_use
-	ld a, $02
+	ld a, EFFECTCMDTYPE_INITIAL_EFFECT_2
 	call TryExecuteEffectCommandFunction
 	jr c, .done
-	ld a, $06
-	call SetAIAction_SerialSendDuelData
+	ld a, OPPACTION_PLAY_TRAINER
+	call SetOppAction_SerialSendDuelData
 	call DisplayUsedTrainerCardDetailScreen
 	call ExchangeRNG
-	ld a, $06
+	ld a, EFFECTCMDTYPE_DISCARD_ENERGY
 	call TryExecuteEffectCommandFunction
-	ld a, $05
+	ld a, EFFECTCMDTYPE_REQUIRE_SELECTION
 	call TryExecuteEffectCommandFunction
-	ld a, $07
-	call SetAIAction_SerialSendDuelData
-	ld a, $03
+	ld a, OPPACTION_EXECUTE_TRAINER_EFFECTS
+	call SetOppAction_SerialSendDuelData
+	ld a, EFFECTCMDTYPE_BEFORE_DAMAGE
 	call TryExecuteEffectCommandFunction
 	ldh a, [hTempCardIndex_ff9f]
 	call MoveHandCardToDiscardPile
@@ -4770,8 +4779,7 @@ Func_1955: ; 1955 (0:1955)
 	pop af
 ;	fallthrough
 
-; this function appears to handle dealing damage to self due to confusion
-Func_195c: ; 195c (0:195c)
+DealConfusionDamageToSelf: ; 195c (0:195c)
 	ld hl, wDamage
 	ld [hli], a
 	ld [hl], 0
@@ -4784,13 +4792,13 @@ Func_195c: ; 195c (0:195c)
 	push af
 	ld a, [wTempTurnDuelistCardID]
 	ld [wTempNonTurnDuelistCardID], a
-	bank1call ApplyDamageModifiers_DamageToSelf ; switch to bank 1, but call a home func
+	bank1call ApplyDamageModifiers_DamageToSelf ; this is at bank 0
 	ld a, [wDamageEffectiveness]
 	ld c, a
 	ld b, $0
 	ld a, DUELVARS_ARENA_CARD_HP
 	call GetTurnDuelistVariable
-	bank1call Func_7469
+	bank1call PlayAttackAnimation_DealAttackDamageSimple
 	call PrintKnockedOutIfHLZero
 	pop af
 	ld [wTempNonTurnDuelistCardID], a
@@ -5037,11 +5045,11 @@ PrintKnockedOut: ; 1ad3 (0:1ad3)
 	ret
 ; 0x1af3
 
-; seems to be a function to deal damage to a card, but can be used
-; to deal damage to a benched Pokemon.
+; deal damage to turn holder's Pokemon card at play area location at b (PLAY_AREA_*).
+; damage to deal is given in de.
 ; shows the defending player's play area screen when dealing the damage
-; instead of the main duel interface, and has a fixed move animation
-Func_1af3: ; 1af3 (0:1af3)
+; instead of the main duel interface, and has a fixed move animation.
+DealDamageToPlayAreaPokemon: ; 1af3 (0:1af3)
 	ld a, $78
 	ld [wLoadedMoveAnimation], a
 	ld a, b
@@ -5105,7 +5113,7 @@ Func_1af3: ; 1af3 (0:1af3)
 	ld b, a
 	or a ; cp PLAY_AREA_ARENA
 	jr nz, .benched
-	; add damage at de to [wDealtDamage]
+	; if arena Pokemon, add damage at de to [wDealtDamage]
 	ld hl, wDealtDamage
 	ld a, e
 	add [hl]
@@ -5118,7 +5126,7 @@ Func_1af3: ; 1af3 (0:1af3)
 	add DUELVARS_ARENA_CARD_HP
 	call GetTurnDuelistVariable
 	push af
-	bank1call Func_7469
+	bank1call PlayAttackAnimation_DealAttackDamageSimple
 	pop af
 	or a
 	jr z, .skip_knocked_out
@@ -5174,10 +5182,10 @@ Func_1bb4: ; 1bb4 (0:1bb4)
 	call ExchangeRNG
 	ret
 
-; prints one of the ThereWasNoEffectFrom*Text if wcced contains $1,
-; and WasUnsuccessfulText if wcced contains $2
+; prints one of the ThereWasNoEffectFrom*Text if wEffectFailed contains EFFECT_FAILED_NO_EFFECT,
+; and prints WasUnsuccessfulText if wEffectFailed contains EFFECT_FAILED_UNSUCCESSFUL
 Func_1bca: ; 1bca (0:1bca)
-	ld a, [wcced]
+	ld a, [wEffectFailed]
 	or a
 	ret z
 	cp $1
@@ -6238,7 +6246,10 @@ LoadPlacingThePrizesScreenTiles: ; 20f0 (0:20f0)
 	ld de, v0Tiles1 + $20 tiles
 	ld b, $d
 	call CopyFontsOrDuelGraphicsTiles
-	; load the Deck and the Discard Pile icons
+; fallthrough
+
+; load the Deck and the Discard Pile icons
+LoadDeckAndDiscardPileIcons: ; 20fb (0:20fb)
 	ld hl, DuelDmgSgbSymbolGraphics + $54 tiles - $4000
 	ld a, [wConsole]
 	cp CONSOLE_CGB
@@ -9276,12 +9287,12 @@ CompareDEtoBC: ; 3090 (0:3090)
 	cp c
 	ret
 
-Func_3096: ; 3096 (0:3096)
+OpenDuelCheckMenu: ; 3096 (0:3096)
 	ldh a, [hBankROM]
 	push af
-	ld a, BANK(Func_8000)
+	ld a, BANK(_OpenDuelCheckMenu)
 	call BankswitchROM
-	call Func_8000
+	call _OpenDuelCheckMenu
 	pop af
 	call BankswitchROM
 	ret
@@ -9299,27 +9310,33 @@ OpenInPlayAreaScreen_FromSelectButton: ; 30a6 (0:30a6)
 	call BankswitchROM
 	ret
 
-Func_30bc: ; 30bc (0:30bc)
+; loads tiles and icons to display Your Play Area / Opp. Play Area screen,
+; and draws the screen according to the turn player
+; input: h -> [wCheckMenuPlayAreaWhichDuelist] and l -> [wCheckMenuPlayAreaWhichLayout]
+; similar to DrawYourOrOppPlayArea (bank 2) except it also draws a wide text box.
+; this is because bank 2's DrawYourOrOppPlayArea is supposed to come from the Check Menu,
+; so the text box is always already there.
+DrawYourOrOppPlayAreaScreen_Bank0: ; 30bc (0:30bc)
 	ld a, h
-	ld [wce50], a
+	ld [wCheckMenuPlayAreaWhichDuelist], a
 	ld a, l
-	ld [wce51], a
+	ld [wCheckMenuPlayAreaWhichLayout], a
 	ldh a, [hBankROM]
 	push af
-	ld a, BANK(Func_8211)
+	ld a, BANK(_DrawYourOrOppPlayAreaScreen)
 	call BankswitchROM
-	call Func_8211
+	call _DrawYourOrOppPlayAreaScreen
 	call DrawWideTextBox
 	pop af
 	call BankswitchROM
 	ret
 
-Func_30d7: ; 30d7 (0:30d7)
+DrawPlayersPrizeAndBenchCards: ; 30d7 (0:30d7)
 	ldh a, [hBankROM]
 	push af
-	ld a, BANK(Func_833c)
+	ld a, BANK(_DrawPlayersPrizeAndBenchCards)
 	call BankswitchROM
-	call Func_833c
+	call _DrawPlayersPrizeAndBenchCards
 	pop af
 	call BankswitchROM
 	ret
@@ -10197,8 +10214,10 @@ IsPrehistoricPowerActive: ; 35b7 (0:35b7)
 	ret
 ; 0x35c7
 
-; clears some SUBSTATUS2 conditions from the turn holder's active Pokemon
-Func_35c7: ; 35c7 (0:35c7)
+; clears some SUBSTATUS2 conditions from the turn holder's active Pokemon.
+; more specifically, those conditions that reduce the damage from an attack
+; or prevent the opposing Pokemon from attacking the substatus condition inducer.
+ClearDamageReductionSubstatus2: ; 35c7 (0:35c7)
 	ld a, DUELVARS_ARENA_CARD_SUBSTATUS2
 	call GetTurnDuelistVariable
 	or a
@@ -11201,19 +11220,21 @@ Func_3b31: ; 3b31 (0:3b31)
 	call BankswitchROM
 	ret
 
-Func_3b52: ; 3b52 (0:3b52)
+; return nc if wd42a, wd4c0, and wAnimationQueue[] are all equal to $ff
+; nc means no animation is playing (or animation(s) has/have ended)
+CheckAnyAnimationPlaying: ; 3b52 (0:3b52)
 	push hl
 	push bc
 	ld a, [wd42a]
 	ld hl, wd4c0
 	and [hl]
-	ld hl, wd423
-	ld c, $7
-.asm_3b60
+	ld hl, wAnimationQueue
+	ld c, ANIMATION_QUEUE_LENGTH
+.loop
 	and [hl]
 	inc hl
 	dec c
-	jr nz, .asm_3b60
+	jr nz, .loop
 	cp $ff
 	pop bc
 	pop hl
@@ -11236,7 +11257,7 @@ Func_3b6a: ; 3b6a (0:3b6a)
 	ld a, [wd4ac]
 	cp [hl]
 	jr nz, .asm_3b90
-	call Func_3b52
+	call CheckAnyAnimationPlaying
 	jr nc, .asm_3b95
 .asm_3b90
 	call $4a31