Functions related to using card from hand

5 files changed, 148 insertions, 36 deletions

diff --git a/src/engine/bank1.asm b/src/engine/bank1.asm
index 21d6eb1..d70d363 100644
--- a/src/engine/bank1.asm
+++ b/src/engine/bank1.asm
@@ -506,12 +506,14 @@ OpenActivePokemonScreen: ; 4376 (1:4376)
 	ret
 ; 0x438e
 
+; triggered by selecting the "Pkmn Power" item in the duel menu
 DuelMenu_PkmnPower: ; 438e (1:438e)
 	call $6431
 	jp c, DuelMainInterface
 	call Func_1730
 	jp DuelMainInterface
 
+; triggered by selecting the "Done" item in the duel menu
 DuelMenu_Done: ; 439a (1:439a)
 	ld a, $08
 	call $51e7
@@ -521,12 +523,13 @@ DuelMenu_Done: ; 439a (1:439a)
 	call $717a
 	ret
 
+; triggered by selecting the "Retreat" item in the duel menu
 DuelMenu_Retreat: ; 43ab (1:43ab)
 	ld a, DUELVARS_ARENA_CARD_STATUS
 	call GetTurnDuelistVariable
 	and CNF_SLP_PRZ
 	cp CONFUSED
-	ldh [hffa0], a
+	ldh [hTemp_ffa0], a
 	jr nz, Func_43f1
 	ld a, [wcc0c]
 	or a
@@ -579,23 +582,26 @@ Func_441f: ; 441f (1:441f)
 	call DrawWideTextBox_WaitForInput
 	jp PrintDuelMenu
 
+; triggered by selecting the "Hand" item in the duel menu
 DuelMenu_Hand: ; 4425 (1:4425)
 	ld a, DUELVARS_NUMBER_OF_CARDS_IN_HAND
 	call GetTurnDuelistVariable
 	or a
-	jr nz, Func_4436
+	jr nz, OpenPlayerHandScreen
 	ldtx hl, NoCardsInHandText
 	call DrawWideTextBox_WaitForInput
 	jp PrintDuelMenu
 
-Func_4436: ; 4436 (1:4436)
+; draw the screen for the player's hand and handle user input to for example check
+; a card or attempt to use a card, playing the card if possible in that case.
+OpenPlayerHandScreen: ; 4436 (1:4436)
 	call CreateHandCardList
 	call DrawCardListScreenLayout
 	ldtx hl, PleaseSelectHandText
 	call SetCardListInfoBoxText
 	ld a, $1
 	ld [wcbde], a
-.asm_4447
+.handle_input
 	call Func_55f0
 	push af
 	ld a, [wcbdf]
@@ -608,17 +614,18 @@ Func_4436: ; 4436 (1:4436)
 	ld a, [wLoadedCard1Type]
 	ld c, a
 	bit TYPE_TRAINER_F, c
-	jr nz, .asm_446f
+	jr nz, .trainer_card
 	bit TYPE_ENERGY_F, c
 	jr nz, UseEnergyCard
-	call $44db
-	jr c, UseEnergyCard.asm_44d2
+	call UsePokemonCard
+	jr c, ReloadCardListScreen ; jump if card not played
 	jp DuelMainInterface
-.asm_446f
+.trainer_card
 	call UseTrainerCard
-	jr c, UseEnergyCard.asm_44d2
+	jr c, ReloadCardListScreen ; jump if card not played
 	jp DuelMainInterface
 
+; use the energy card with deck index at hTempCardIndex_ff98
 ; c contains the type of energy card being played
 UseEnergyCard: ; 4477 (1:4477)
 	ld a, c
@@ -642,7 +649,7 @@ UseEnergyCard: ; 4477 (1:4477)
 	ldh [hTempPlayAreaLocationOffset_ffa1], a
 	ld e, a
 	ldh a, [hTempCardIndex_ff98]
-	ldh [hffa0], a
+	ldh [hTemp_ffa0], a
 	call PutHandCardInPlayArea
 	call $61b8
 	ld a, $3
@@ -661,20 +668,122 @@ UseEnergyCard: ; 4477 (1:4477)
 	jr z, .play_energy_set_played
 	ldtx hl, MayOnlyAttachOneEnergyCardText
 	call DrawWideTextBox_WaitForInput
-	jp Func_4436
+	jp OpenPlayerHandScreen
 
 .already_played_energy
 	ldtx hl, MayOnlyAttachOneEnergyCardText
 	call DrawWideTextBox_WaitForInput
+;	fallthrough
 
-.asm_44d2
+; reload the card list screen after the card trying to play couldn't be played
+ReloadCardListScreen: ; 44d2 (1:44d2)
 	call CreateHandCardList
+	; skip doing the things that have already been done when initially opened
 	call DrawCardListScreenLayout.draw
-	jp Func_4436.asm_4447
+	jp OpenPlayerHandScreen.handle_input
 ; 0x44db
 
-	INCROM $44db,  $4585
+; use a basic Pokemon card on the arena or bench, or place an stage 1 or 2
+; Pokemon card over a Pokemon card already in play to evolve it.
+; the card to use is loaded in wLoadedCard1 and its deck index is at hTempCardIndex_ff98.
+; return nc if the card was played, carry if it wasn't.
+UsePokemonCard: ; 44db (1:44db)
+	ld a, [wLoadedCard1Stage]
+	or a ; BASIC
+	jr nz, .try_evolve ; jump if the card being played is a Stage 1 or 2 Pokemon
+	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
+	call GetTurnDuelistVariable
+	cp MAX_PLAY_AREA_POKEMON
+	jr nc, .no_space
+	ldh a, [hTempCardIndex_ff98]
+	ldh [hTemp_ffa0], a
+	call PutHandPokemonCardInPlayArea
+	ldh [hTempPlayAreaLocationOffset_ff9d], a
+	add DUELVARS_ARENA_CARD_STAGE
+	call GetTurnDuelistVariable
+	ld [hl], BASIC
+	ld a, $01
+	call SetDuelAIAction
+	ldh a, [hTempCardIndex_ff98]
+	call LoadCardDataToBuffer1_FromDeckIndex
+	ld a, $14
+	call Func_29f5
+	ld [hl], $00
+	ld hl, $0000
+	call LoadTxRam2
+	ldtx hl, PlacedOnTheBenchText
+	call DrawWideTextBox_WaitForInput
+	call Func_161e
+	or a
+	ret
+.no_space
+	ldtx hl, NoSpaceOnTheBenchText
+	call DrawWideTextBox_WaitForInput
+	scf
+	ret
+.try_evolve
+	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
+	call GetTurnDuelistVariable
+	ld c, a
+	ldh a, [hTempCardIndex_ff98]
+	ld d, a
+	ld e, PLAY_AREA_ARENA
+	push de
+	push bc
+.next_play_area_pkmn
+	push de
+	call CheckIfCanEvolveInto
+	pop de
+	jr nc, .can_evolve
+	inc e
+	dec c
+	jr nz, .next_play_area_pkmn
+	pop bc
+	pop de
+.find_cant_evolve_reason_loop
+	push de
+	call CheckIfCanEvolveInto
+	pop de
+	ldtx hl, CantEvolvePokemonInSameTurnItsPlacedText
+	jr nz, .cant_same_turn
+	inc e
+	dec c
+	jr nz, .find_cant_evolve_reason_loop
+	ldtx hl, NoPokemonCapableOfEvolvingText
+.cant_same_turn
+	call DrawWideTextBox_WaitForInput
+	scf
+	ret
+.can_evolve
+	pop bc
+	pop de
+	call IsPrehistoricPowerActive
+	jr c, .prehistoric_power
+	call HasAlivePokemonInPlayArea
+.try_evolve_loop
+	call OpenPlayAreaScreenForSelection
+	jr c, .done
+	ldh a, [hTempCardIndex_ff98]
+	ldh [hTemp_ffa0], a
+	ldh a, [hTempPlayAreaLocationOffset_ff9d]
+	ldh [hTempPlayAreaLocationOffset_ffa1], a
+	call EvolvePokemonCard
+	jr c, .try_evolve_loop ; jump if evolution wasn't successsful somehow
+	ld a, $02
+	call SetDuelAIAction
+	call $61b8
+	call $68fa
+	call Func_161e
+.done
+	or a
+	ret
+.prehistoric_power
+	call DrawWideTextBox_WaitForInput
+	scf
+	ret
+; 0x4585
 
+; triggered by selecting the "Check" item in the duel menu
 DuelMenu_Check: ; 4585 (1:4585)
 	call Func_3b31
 	call Func_3096
@@ -684,6 +793,7 @@ DuelMenu_Check: ; 4585 (1:4585)
 DuelMenuShortcut_BothActivePokemon:: ; 458e (1:458e)
 	INCROM $458e,  $46fc
 
+; triggered by selecting the "Attack" item in the duel menu
 DuelMenu_Attack: ; 46fc (1:46fc)
 	call HandleCantAttackSubstatus
 	jr c, .alert_cant_attack_and_cancel_menu
@@ -1337,12 +1447,12 @@ Func_4b60: ; 4b60 (1:4b60)
 	call SwapTurn
 	call $4e84
 	call $4d97
-	ldh [hffa0], a
+	ldh [hTemp_ffa0], a
 	call SwapTurn
 	call $4d97
 	call SwapTurn
 	ld c, a
-	ldh a, [hffa0]
+	ldh a, [hTemp_ffa0]
 	ld b, a
 	and c
 	jr nz, .asm_4bd0
@@ -2573,10 +2683,10 @@ AIUseEnergyCard: ; 69a5 (1:69a5)
 	ldh a, [hTempPlayAreaLocationOffset_ffa1]
 	ldh [hTempPlayAreaLocationOffset_ff9d], a
 	ld e, a
-	ldh a, [hffa0]
+	ldh a, [hTemp_ffa0]
 	ldh [hTempCardIndex_ff98], a
 	call PutHandCardInPlayArea
-	ldh a, [hffa0]
+	ldh a, [hTemp_ffa0]
 	call LoadCardDataToBuffer1_FromDeckIndex
 	call $5e75
 	call $68e4
diff --git a/src/engine/home.asm b/src/engine/home.asm
index 91ef164..0a3c9b0 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -3509,7 +3509,7 @@ LoadCardDataToBuffer2_FromDeckIndex: ; 138c (0:138c)
 
 ; evolve a turn holder's Pokemon card in the play area slot determined by hTempPlayAreaLocationOffset_ff9d
 ; into another turn holder's Pokemon card identifier by it's deck index (0-59) in hTempCardIndex_ff98.
-; always returns nc, but it's unclear if it's intentional.
+; return nc if evolution was succesful.
 EvolvePokemonCard: ; 13a2 (0:13a2)
 	; first make sure the attempted evolution is viable
 	ldh a, [hTempCardIndex_ff98]
@@ -3562,9 +3562,9 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	call GetTurnDuelistVariable
 	ld a, [wLoadedCard1Stage]
 	ld [hl], a
-	; this is buggy but the return value would've always been the same anyway, as the Pokemon can't be basic
 	or a
-	ret ; !
+	ret
+
 	scf
 	ret
 ; 0x13f7
@@ -3572,6 +3572,7 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 ; check if the turn holder's Pokemon card e can evolve into the turn holder's Pokemon card d.
 ; e is the play area location offset (PLAY_AREA_*) of the Pokemon trying to evolve.
 ; d is the deck index (0-59) of the Pokemon card that was selected to be the evolution target.
+; return carry if can't evolve, plus nz if the reason for it is the card was played this turn.
 CheckIfCanEvolveInto: ; 13f7 (0:13f7)
 	push de
 	ld a, e
@@ -4352,7 +4353,7 @@ Func_1874: ; 1874 (0:1874)
 	ld a, [wccec]
 	or a
 	ret nz
-	ldh a, [hffa0]
+	ldh a, [hTemp_ffa0]
 	push af
 	ldh a, [hTempCardIndex_ff9f]
 	push af
@@ -4361,14 +4362,14 @@ Func_1874: ; 1874 (0:1874)
 	ld a, [wcc11]
 	ldh [hTempCardIndex_ff9f], a
 	ld a, [wcc10]
-	ldh [hffa0], a
+	ldh [hTemp_ffa0], a
 	ld a, $8
 	call SetDuelAIAction
 	call Func_0f58
 	pop af
 	ldh [hTempCardIndex_ff9f], a
 	pop af
-	ldh [hffa0], a
+	ldh [hTemp_ffa0], a
 	ret
 
 Func_189d: ; 189d (0:189d)
@@ -4428,8 +4429,9 @@ CheckSelfConfusionDamage: ; 18d7 (0:18d7)
 	ret
 ; 0x18f9
 
-; use the trainer card with deck index at hTempCardIndex_ff98
-; a trainer card is like a move effect, with its own effect commands
+; use 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)
 	call CheckCantUseTrainerDueToHeadache
 	jr c, .cant_use
@@ -6536,7 +6538,7 @@ HandleMenuInput: ; 264b (0:264b)
 	ret
 
 ; plays an "open screen" sound if [hCurrentMenuItem] != 0xff
-; plays a "exit screen" sound if [hCurrentMenuItem] == 0xff
+; plays an "exit screen" sound if [hCurrentMenuItem] == 0xff
 PlayOpenOrExitScreenSFX: ; 26c0 (0:26c0)
 	push af
 	ldh a, [hCurrentMenuItem]
@@ -7164,7 +7166,7 @@ Func_2bc7: ; 2bc7 (0:2bc7)
 Func_2bcf: ; 2bcf (0:2bcf)
 	ld a, $4
 	call Func_2bdb
-	ldh [hffa0], a
+	ldh [hTemp_ffa0], a
 	ret
 
 Func_2bd7: ; 2bd7 (0:2bd7)
@@ -8894,7 +8896,7 @@ CheckCantUseTrainerDueToHeadache: ; 35a9 (0:35a9)
 	ret
 ; 0x35b7
 
-; return carry if turn holder has Aerodactyl and its Prehistoric Power Pkmn Power is active
+; return carry if any duelist has Aerodactyl and its Prehistoric Power Pkmn Power is active
 IsPrehistoricPowerActive: ; 35b7 (0:35b7)
 	ld a, AERODACTYL
 	call CountPokemonIDInBothPlayAreas
diff --git a/src/hram.asm b/src/hram.asm
index 58c455b..b96ee37 100644
--- a/src/hram.asm
+++ b/src/hram.asm
@@ -70,7 +70,7 @@ hTempCardIndex_ff9f:: ; ff9f
 	ds 1
 
 ; multipurpose temp storage
-hffa0:: ; ffa0
+hTemp_ffa0:: ; ffa0
 	ds 1
 
 hTempPlayAreaLocationOffset_ffa1:: ; ffa1
diff --git a/src/text/text1.asm b/src/text/text1.asm
index f08651f..9819511 100644
--- a/src/text/text1.asm
+++ b/src/text/text1.asm
@@ -420,7 +420,7 @@ Text0060: ; 36ab7 (d:6ab7)
 	line "into ", TX_RAM2, "."
 	done
 
-Text0061: ; 36aca (d:6aca)
+PlacedOnTheBenchText: ; 36aca (d:6aca)
 	text "Placed ", TX_RAM2, ""
 	line "on the Bench."
 	done
@@ -833,12 +833,12 @@ NoSpaceOnTheBenchText: ; 374fa (d:74fa)
 	text "There is no space on the Bench."
 	done
 
-Text00b3: ; 3751b (d:751b)
+NoPokemonCapableOfEvolvingText: ; 3751b (d:751b)
 	text "There are no Pok`mon capable"
 	line "of Evolving."
 	done
 
-Text00b4: ; 37546 (d:7546)
+CantEvolvePokemonInSameTurnItsPlacedText: ; 37546 (d:7546)
 	text "You cannot Evolve a Pok`mon"
 	line "in the same turn it was placed."
 	done
diff --git a/src/text/text_offsets.asm b/src/text/text_offsets.asm
index 20f1339..025f424 100644
--- a/src/text/text_offsets.asm
+++ b/src/text/text_offsets.asm
@@ -98,7 +98,7 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text005e                                ; 0x005e
 	textpointer Text005f                                ; 0x005f
 	textpointer Text0060                                ; 0x0060
-	textpointer Text0061                                ; 0x0061
+	textpointer PlacedOnTheBenchText                                ; 0x0061
 	textpointer Text0062                                ; 0x0062
 	textpointer Text0063                                ; 0x0063
 	textpointer Text0064                                ; 0x0064
@@ -180,8 +180,8 @@ TextOffsets:: ; 34000 (d:4000)
 	textpointer Text00b0                                ; 0x00b0
 	textpointer Text00b1                                ; 0x00b1
 	textpointer NoSpaceOnTheBenchText                   ; 0x00b2
-	textpointer Text00b3                                ; 0x00b3
-	textpointer Text00b4                                ; 0x00b4
+	textpointer NoPokemonCapableOfEvolvingText                                ; 0x00b3
+	textpointer CantEvolvePokemonInSameTurnItsPlacedText                                ; 0x00b4
 	textpointer Text00b5                                ; 0x00b5
 	textpointer Text00b6                                ; 0x00b6
 	textpointer Text00b7                                ; 0x00b7