Improve effect commands documentation, misc improvements

Author: ElectroDeoxys

CONTRIBUTING.md

@@ -139,7 +139,7 @@ CopyLine::
 ;   e = attack index (0 or 1)
 ;   wAttachedEnergies and wTotalAttachedEnergies
 ; returns: carry if not enough energy, nc if enough energy.
-_CheckIfEnoughEnergiesToAttack:
+CheckIfEnoughEnergiesForGivenAttack:
 ```
 
 ```asm
@@ -258,7 +258,7 @@ wTextHeader4:: ; ce3a
 ; such as PrintPlayAreaCardLocation, PrintPlayAreaCardInformation and PrintPlayAreaCardHeader
 wCurPlayAreaSlot:: ; cbc9
 
-; X position to display the attached energies, HP bar, and Pluspower/Defender icons
+; X position to display the attached energies, HP bar, and PlusPower/Defender icons
 ; obviously different for player and opponent side. used by DrawDuelHUD.
 wHUDEnergyAndHPBarsX:: ; cbc9
 	ds $1

bugs_and_glitches.md

@@ -412,7 +412,7 @@ AIDecide_FullHeal:
 
 ### AI might use a Pkmn Power as an attack
 
-Under very specific conditions, the AI might attempt to use its Arena card's Pkmn Power as an attack. This is because when the AI plays Pluspower, it is hardcoding which attack to use when it finally decides to attack. This does not account for the case where afterwards, for example, the AI plays a Professor Oak and obtains an evolution of that card, and then evolves that card. If the new evolved Pokémon has Pkmn Power on the first "attack slot", and the AI hardcoded to use that attack, then it will be used. This specific combination can be seen when playing with John, since his deck contains Professor Oak, Pluspower, and Doduo and its evolution Dodrio (which has the Pkmn Power Retreat Aid).
+Under very specific conditions, the AI might attempt to use its Arena card's Pkmn Power as an attack. This is because when the AI plays PlusPower, it is hardcoding which attack to use when it finally decides to attack. This does not account for the case where afterwards, for example, the AI plays a Professor Oak and obtains an evolution of that card, and then evolves that card. If the new evolved Pokémon has Pkmn Power on the first "attack slot", and the AI hardcoded to use that attack, then it will be used. This specific combination can be seen when playing with John, since his deck contains Professor Oak, PlusPower, and Doduo and its evolution Dodrio (which has the Pkmn Power Retreat Aid).
 
 **Fix:** Edit `AIDecideEvolution` in [src/engine/duel/ai/hand_pokemon.asm](https://github.com/pret/poketcg/blob/master/src/engine/duel/ai/hand_pokemon.asm):
 ```diff

src/constants/deck_ai_constants.asm

@@ -80,13 +80,13 @@ DEF AI_ENERGY_FLAG_SKIP_ARENA_CARD EQU 1 << 7 ; whether to include Arena card in
 
 	const AI_TRAINER_CARD_PHASE_13 ; $d
 	; Defender
-	; Pluspower
+	; PlusPower
 	; Lass
 	; Pokémon Flute
 
 	const AI_TRAINER_CARD_PHASE_14 ; $e
 	; Defender
-	; Pluspower
+	; PlusPower
 
 	const AI_TRAINER_CARD_PHASE_15 ; $f
 	; Professor Oak

src/constants/duel_constants.asm

@@ -57,12 +57,12 @@ DEF DUELVARS_BENCH2_CARD_ATTACHED_DEFENDER    EQUS "LOW(wPlayerBench2CardAttache
 DEF DUELVARS_BENCH3_CARD_ATTACHED_DEFENDER    EQUS "LOW(wPlayerBench3CardAttachedDefender)"  ; dd
 DEF DUELVARS_BENCH4_CARD_ATTACHED_DEFENDER    EQUS "LOW(wPlayerBench4CardAttachedDefender)"  ; de
 DEF DUELVARS_BENCH5_CARD_ATTACHED_DEFENDER    EQUS "LOW(wPlayerBench5CardAttachedDefender)"  ; df
-DEF DUELVARS_ARENA_CARD_ATTACHED_PLUSPOWER    EQUS "LOW(wPlayerArenaCardAttachedPluspower)"  ; e0
-DEF DUELVARS_BENCH1_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench1CardAttachedPluspower)" ; e1
-DEF DUELVARS_BENCH2_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench2CardAttachedPluspower)" ; e2
-DEF DUELVARS_BENCH3_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench3CardAttachedPluspower)" ; e3
-DEF DUELVARS_BENCH4_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench4CardAttachedPluspower)" ; e4
-DEF DUELVARS_BENCH5_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench5CardAttachedPluspower)" ; e5
+DEF DUELVARS_ARENA_CARD_ATTACHED_PLUSPOWER    EQUS "LOW(wPlayerArenaCardAttachedPlusPower)"  ; e0
+DEF DUELVARS_BENCH1_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench1CardAttachedPlusPower)" ; e1
+DEF DUELVARS_BENCH2_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench2CardAttachedPlusPower)" ; e2
+DEF DUELVARS_BENCH3_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench3CardAttachedPlusPower)" ; e3
+DEF DUELVARS_BENCH4_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench4CardAttachedPlusPower)" ; e4
+DEF DUELVARS_BENCH5_CARD_ATTACHED_PLUSPOWER   EQUS "LOW(wPlayerBench5CardAttachedPlusPower)" ; e5
 DEF DUELVARS_ARENA_CARD_SUBSTATUS1            EQUS "LOW(wPlayerArenaCardSubstatus1)"         ; e7
 DEF DUELVARS_ARENA_CARD_SUBSTATUS2            EQUS "LOW(wPlayerArenaCardSubstatus2)"         ; e8
 DEF DUELVARS_ARENA_CARD_CHANGED_WEAKNESS      EQUS "LOW(wPlayerArenaCardChangedWeakness)"    ; e9
@@ -134,19 +134,19 @@ DEF DBLPSN_DAMAGE EQU 20
 ; substatus conditions (DUELVARS_ARENA_CARD_SUBSTATUS*)
 
 ; SUBSTATUS1 are checked on a defending Pokemon
-DEF SUBSTATUS1_AGILITY      EQU $0c
-DEF SUBSTATUS1_FLY          EQU $0d
-DEF SUBSTATUS1_HARDEN       EQU $0e
-DEF SUBSTATUS1_NO_DAMAGE_STIFFEN  EQU $0f
-DEF SUBSTATUS1_NO_DAMAGE_10 EQU $10
-DEF SUBSTATUS1_NO_DAMAGE_11 EQU $11
-DEF SUBSTATUS1_REDUCE_BY_20 EQU $13
-DEF SUBSTATUS1_BARRIER      EQU $14
-DEF SUBSTATUS1_HALVE_DAMAGE EQU $15
-DEF SUBSTATUS1_DESTINY_BOND EQU $16
-DEF SUBSTATUS1_NO_DAMAGE_17 EQU $17
+DEF SUBSTATUS1_AGILITY                 EQU $0c
+DEF SUBSTATUS1_FLY                     EQU $0d
+DEF SUBSTATUS1_PREVENT_LESS_THAN_40    EQU $0e
+DEF SUBSTATUS1_NO_DAMAGE_STIFFEN       EQU $0f
+DEF SUBSTATUS1_NO_DAMAGE_WITHDRAW      EQU $10
+DEF SUBSTATUS1_NO_DAMAGE_HIDE_IN_SHELL EQU $11
+DEF SUBSTATUS1_REDUCE_BY_20            EQU $13
+DEF SUBSTATUS1_BARRIER                 EQU $14
+DEF SUBSTATUS1_HALVE_DAMAGE            EQU $15
+DEF SUBSTATUS1_DESTINY_BOND            EQU $16
+DEF SUBSTATUS1_NO_DAMAGE_SCRUNCH       EQU $17
 DEF SUBSTATUS1_NEXT_TURN_DOUBLE_DAMAGE EQU $19
-DEF SUBSTATUS1_REDUCE_BY_10 EQU $1e
+DEF SUBSTATUS1_REDUCE_BY_10            EQU $1e
 
 ; SUBSTATUS2 are checked on an attacking Pokemon
 DEF SUBSTATUS2_SMOKESCREEN    EQU $01
@@ -157,7 +157,7 @@ DEF SUBSTATUS2_TAIL_WAG       EQU $05
 DEF SUBSTATUS2_LEER           EQU $06
 DEF SUBSTATUS2_POUNCE         EQU $07
 DEF SUBSTATUS2_CONVERSION2    EQU $08
-DEF SUBSTATUS2_UNABLE_RETREAT EQU $09
+DEF SUBSTATUS2_ACID           EQU $09
 DEF SUBSTATUS2_BONE_ATTACK    EQU $0b
 DEF SUBSTATUS2_GROWL          EQU $12
 

src/data/cards.asm

@@ -7903,7 +7903,7 @@ MewtwoLv60Card:
 	dw NONE ; description (cont)
 	db 0 ; damage
 	db RESIDUAL ; category
-	dw MewtwoLv60EnergyAbsorptionEffectCommands ; effect commands
+	dw MewtwoEnergyAbsorptionEffectCommands ; effect commands
 	db NONE ; flags 1
 	db NONE ; flags 2
 	db SPECIAL_AI_HANDLING ; flags 3
@@ -7954,7 +7954,7 @@ MewtwoAltLV60Card:
 	dw NONE ; description (cont)
 	db 0 ; damage
 	db RESIDUAL ; category
-	dw MewtwoAltLV60EnergyAbsorptionEffectCommands ; effect commands
+	dw MewtwoAltEnergyAbsorptionEffectCommands ; effect commands
 	db NONE ; flags 1
 	db NONE ; flags 2
 	db SPECIAL_AI_HANDLING ; flags 3

src/data/duel/ai_trainer_card_logic.asm

@@ -12,8 +12,8 @@ AITrainerCardLogic:
 	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_11, SUPER_POTION,           AIDecide_SuperPotion2,                   AIPlay_SuperPotion
 	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_13, DEFENDER,               AIDecide_Defender1,                      AIPlay_Defender
 	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_14, DEFENDER,               AIDecide_Defender2,                      AIPlay_Defender
-	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_13, PLUSPOWER,              AIDecide_Pluspower1,                     AIPlay_Pluspower
-	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_14, PLUSPOWER,              AIDecide_Pluspower2,                     AIPlay_Pluspower
+	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_13, PLUSPOWER,              AIDecide_PlusPower1,                     AIPlay_PlusPower
+	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_14, PLUSPOWER,              AIDecide_PlusPower2,                     AIPlay_PlusPower
 	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_09, SWITCH,                 AIDecide_Switch,                         AIPlay_Switch
 	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_07, GUST_OF_WIND,           AIDecide_GustOfWind,                     AIPlay_GustOfWind
 	ai_trainer_card_logic AI_TRAINER_CARD_PHASE_10, GUST_OF_WIND,           AIDecide_GustOfWind,                     AIPlay_GustOfWind

src/engine/duel/ai/attacks.asm

@@ -52,11 +52,11 @@ AIProcessAndTryToUseAttack:
 ; AI will use it if wAIExecuteProcessedAttack is 0.
 ; in either case, return carry if an attack is chosen to be used.
 AIProcessAttacks:
-; if AI used Pluspower, load its attack index
+; if AI used PlusPower, load its attack index
 	ld a, [wPreviousAIFlags]
 	and AI_FLAG_USED_PLUSPOWER
 	jr z, .no_pluspower
-	ld a, [wAIPluspowerAttack]
+	ld a, [wAIPlusPowerAttack]
 	ld [wSelectedAttack], a
 	jr .attack_chosen
 

src/engine/duel/ai/damage_calculation.asm

@@ -167,7 +167,7 @@ CalculateDamage_VersusDefendingPokemon:
 	ldh a, [hTempPlayAreaLocation_ff9d]
 	add CARD_LOCATION_ARENA
 	ld b, a
-	call ApplyAttachedPluspower
+	call ApplyAttachedPlusPower
 	call SwapTurn
 	ld b, CARD_LOCATION_ARENA
 	call ApplyAttachedDefender
@@ -404,7 +404,7 @@ CalculateDamage_FromDefendingPokemon:
 	; apply pluspower and defender boosts
 	call SwapTurn
 	ld b, CARD_LOCATION_ARENA
-	call ApplyAttachedPluspower
+	call ApplyAttachedPlusPower
 	call SwapTurn
 	ldh a, [hTempPlayAreaLocation_ff9d]
 	add CARD_LOCATION_ARENA

src/engine/duel/ai/trainer_cards.asm

@@ -755,22 +755,22 @@ AIDecide_Defender2:
 	or a
 	ret
 
-AIPlay_Pluspower:
+AIPlay_PlusPower:
 	ld a, [wCurrentAIFlags]
 	or AI_FLAG_USED_PLUSPOWER
 	ld [wCurrentAIFlags], a
 	ld a, [wAITrainerCardParameter]
-	ld [wAIPluspowerAttack], a
+	ld [wAIPlusPowerAttack], a
 	ld a, [wAITrainerCardToPlay]
 	ldh [hTempCardIndex_ff9f], a
 	ld a, OPPACTION_EXECUTE_TRAINER_EFFECTS
 	bank1call AIMakeDecision
 	ret
 
-; returns carry if using a Pluspower can KO defending Pokémon
+; returns carry if using a PlusPower can KO defending Pokémon
 ; if active card cannot KO without the boost.
 ; outputs in a the attack to use.
-AIDecide_Pluspower1:
+AIDecide_PlusPower1:
 ; this is mistakenly duplicated
 	xor a ; PLAY_AREA_ARENA
 	ldh [hTempPlayAreaLocation_ff9d], a
@@ -811,7 +811,7 @@ AIDecide_Pluspower1:
 	jr c, .no_carry
 
 ; check both attacks and decide which one
-; can KO with Pluspower boost.
+; can KO with PlusPower boost.
 ; if neither can KO, return no carry.
 	xor a ; FIRST_ATTACK_OR_PKMN_POWER
 	ld [wSelectedAttack], a
@@ -826,14 +826,14 @@ AIDecide_Pluspower1:
 	or a
 	ret
 
-; first attack can KO with Pluspower.
+; first attack can KO with PlusPower.
 .kos_with_pluspower_1
 	call .check_mr_mime
 	jr nc, .no_carry
 	xor a ; FIRST_ATTACK_OR_PKMN_POWER
 	scf
 	ret
-; second attack can KO with Pluspower.
+; second attack can KO with PlusPower.
 .kos_with_pluspower_2
 	call .check_mr_mime
 	jr nc, .no_carry
@@ -842,7 +842,7 @@ AIDecide_Pluspower1:
 	ret
 
 ; return carry if attack is useable and KOs
-; defending Pokémon with Pluspower boost.
+; defending Pokémon with PlusPower boost.
 .check_ko_with_pluspower
 	farcall CheckIfSelectedAttackIsUnusable
 	jr c, .unusable
@@ -856,23 +856,23 @@ AIDecide_Pluspower1:
 	jr c, .no_carry
 	jr z, .no_carry
 	ld a, [hl]
-	add 10 ; add Pluspower boost
+	add 10 ; add PlusPower boost
 	ld c, a
 	ld a, b
 	sub c
 	ret c ; return carry if damage > HP left
 	ret nz ; does not KO
 	scf
-	ret ; KOs with Pluspower boost
+	ret ; KOs with PlusPower boost
 .unusable
 	or a
 	ret
 
-; returns carry if Pluspower boost does
+; returns carry if PlusPower boost does
 ; not exceed 30 damage when facing Mr. Mime.
 .check_mr_mime
 	ld a, [wDamage]
-	add 10 ; add Pluspower boost
+	add 10 ; add PlusPower boost
 	cp 30 ; no danger in preventing damage
 	ret c
 	call SwapTurn
@@ -888,11 +888,11 @@ AIDecide_Pluspower1:
 	ret
 
 ; returns carry 7/10 of the time
-; if selected attack is useable, can't KO without Pluspower boost
-; can damage Mr. Mime even with Pluspower boost
+; if selected attack is useable, can't KO without PlusPower boost
+; can damage Mr. Mime even with PlusPower boost
 ; and has a minimum damage > 0.
 ; outputs in a the attack to use.
-AIDecide_Pluspower2:
+AIDecide_PlusPower2:
 	xor a ; PLAY_AREA_ARENA
 	ldh [hTempPlayAreaLocation_ff9d], a
 	call .check_can_ko
@@ -907,11 +907,11 @@ AIDecide_Pluspower2:
 	or a
 	ret
 
-; returns carry if Pluspower boost does
+; returns carry if PlusPower boost does
 ; not exceed 30 damage when facing Mr. Mime.
 .check_mr_mime
 	ld a, [wDamage]
-	add 10 ; add Pluspower boost
+	add 10 ; add PlusPower boost
 	cp 30 ; no danger in preventing damage
 	ret c
 	call SwapTurn

src/engine/duel/core.asm

@@ -1268,18 +1268,18 @@ CheckIfEnoughEnergiesToAttack:
 	ld d, [hl] ; card's deck index (0 to 59)
 	inc hl
 	ld e, [hl] ; attack index (0 or 1)
-	call _CheckIfEnoughEnergiesToAttack
+	call CheckIfEnoughEnergiesForGivenAttack
 	pop bc
 	pop hl
 	ret
 
 ; check if a pokemon card has enough energy attached to it in order to use an attack
 ; input:
 ;   d = deck index of card (0 to 59)
-;   e = attack index (0 or 1)
+;   e = attack index (SECOND_ATTACK or FIRST_ATTACK_OR_PKMN_POWER)
 ;   wAttachedEnergies and wTotalAttachedEnergies
 ; returns: carry if not enough energy, nc if enough energy.
-_CheckIfEnoughEnergiesToAttack:
+CheckIfEnoughEnergiesForGivenAttack:
 	push de
 	ld a, d
 	call LoadCardDataToBuffer1_FromDeckIndex
@@ -2290,12 +2290,10 @@ PlayDeckShuffleAnimation:
 	ld e, DUEL_ANIM_OPP_SHUFFLE
 .load_anim
 ; play animation 3 times
+REPT 3
 	ld a, e
 	call PlayDuelAnimation
-	ld a, e
-	call PlayDuelAnimation
-	ld a, e
-	call PlayDuelAnimation
+ENDR
 
 .loop_anim
 	call DoFrame
@@ -2543,7 +2541,7 @@ DrawDuelHUD:
 	ld b, HP_BAR_LENGTH / 2 ; second row of the HP bar
 	call SafeCopyDataHLtoDE
 
-	; print number of attached Pluspower and Defender with respective icon, if any
+	; print number of attached PlusPower and Defender with respective icon, if any
 	ld hl, wHUDEnergyAndHPBarsX
 	ld a, [hli]
 	add 6
@@ -2557,7 +2555,7 @@ DrawDuelHUD:
 	ld a, SYM_PLUSPOWER
 	call WriteByteToBGMap0
 	inc b
-	ld a, [hl] ; number of attached Pluspower
+	ld a, [hl] ; number of attached PlusPower
 	add SYM_0
 	call WriteByteToBGMap0
 	dec b
@@ -3256,7 +3254,7 @@ DisplayCardList:
 	ld hl, wSelectedDuelSubMenuItem
 	ld [hli], a
 	ld [hl], a
-	ld a, 1
+	ld a, TRUE
 	ld [wSortCardListByID], a
 	call EraseCursor
 	jr .reload_list
@@ -3423,7 +3421,7 @@ PrintSortNumberInCardList_SetPointer:
 	ld [hl], e
 	inc hl
 	ld [hl], d
-	ld a, 1
+	ld a, TRUE
 	ld [wSortCardListByID], a
 	ret
 
@@ -5474,7 +5472,7 @@ PrintPlayAreaCardHeader:
 	call CheckPrintDoublePoisoned
 
 .skip_status
-	; finally check whether to print the Pluspower and/or Defender symbols
+	; finally check whether to print the PlusPower and/or Defender symbols
 	ld a, [wCurPlayAreaSlot]
 	add DUELVARS_ARENA_CARD_ATTACHED_PLUSPOWER
 	call GetTurnDuelistVariable
@@ -6830,7 +6828,7 @@ HandleBetweenTurnsEvents:
 	call IsArenaPokemonAsleepOrPoisoned
 	call SwapTurn
 	jr c, .something_to_handle
-	call DiscardAttachedPluspowers
+	call DiscardAttachedPlusPowers
 	call SwapTurn
 	call DiscardAttachedDefenders
 	call SwapTurn
@@ -6877,7 +6875,7 @@ HandleBetweenTurnsEvents:
 	call WaitForWideTextBoxInput
 
 .discard_pluspower
-	call DiscardAttachedPluspowers
+	call DiscardAttachedPlusPowers
 	call SwapTurn
 	ld a, DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
@@ -6898,7 +6896,7 @@ HandleBetweenTurnsEvents:
 	ret
 
 ; discard any PLUSPOWER attached to the turn holder's arena and/or bench Pokemon
-DiscardAttachedPluspowers:
+DiscardAttachedPlusPowers:
 	ld a, DUELVARS_ARENA_CARD_ATTACHED_PLUSPOWER
 	call GetTurnDuelistVariable
 	ld e, MAX_PLAY_AREA_POKEMON