One of the most basic and important card effects in the official TCG is to attach an energy from your hand to one of your Pokémon with an attack or an ability. In this tutorial, we will create code that can make this effect happen. Note that this version of the code used Shaoden's Poketcg_v2 as its base, so some of the code may need to be modified for the original poketcg base.
Contents
1. Attach Energy from Hand Attack version
First, let's start with the easy part and make some text for these commands. Go to text_offsets and put in the following:
+ChooseABasicEnergyToAttachText
+ChooseABasicEnergyText
+NoHandEnergyText
And then in one of the subsequent texts of your choice, define them.
+ChooseABasicEnergyToAttachText:
+ text "Choose a basic Energy in your"
+ line "hand and attach it to a Pokémon."
+ done
+ChooseABasicEnergyText:
+ text "Choose a basic"
+ line "Energy"
+ done
+NoHandEnergyText:
+ text "No basic energies in hand."
+ done
With that done, we will make an attack that attaches a basic energy from hand to field. Go to Effect Commands and insert the following as a new effect command:
+Attach1EnergyFromHandEffectCommands:
+ dbw EFFECTCMDTYPE_INITIAL_EFFECT_1, CheckBasicEnergyInHand
+ dbw EFFECTCMDTYPE_REQUIRE_SELECTION, Attach1BasicEnergyFromHandToPokemonEffect
+ dbw EFFECTCMDTYPE_AI_SELECTION, AttachBasicEnergyFromHand_AISelection
+ dbw EFFECTCMDTYPE_AFTER_DAMAGE, AttachBasicEnergyFromHand_AttachEffect
+ db $00
Then as per usual, we will head to Effect Functions to program in everything above. The first command is CheckBasicEnergyInHand.
+CheckBasicEnergyInHand:
+ call CreateHandCardList
+ ld hl, wDuelTempList ; Opens hand to check cards in hand
+.loop
+ ld a, [hli]
+ cp $ff
+ jr z, .none_found ; If no cards in hand, skip and return.
+ call GetCardTypeFromDeckIndex_SaveDE ; Othwerwise, get card type
+ bit TYPE_ENERGY_F, a ; Check if the first card in your hand is an energy
+ jr z, .loop ; skip if not an Energy card ; skip if not
+ cp TYPE_ENERGY + NUM_COLORED_TYPES ; Check if it's a colored energy
+ jr nc, .loop ; skip if it provides Colorless Energy (i.e. not Basic)
+ or a
+ ret ; if successful, return and do the rest of the code.
+.none_found
+ ldtx hl, NoHandEnergyText
+ scf
+ ret
Note that if you wanted to make an effect which attaches any energy from hand to field, you would do the same thing except delete the + NUM_COLORED_TYPES in the cp line, as well as alter some of that text in the first section. Either way, next we have to define the code for actually attaching the energy after confirming that the player has energy in their hand, so copy these two effect functions:
+Attach1BasicEnergyFromHandToPokemonEffect:
+ ldtx hl, Choose1BasicEnergyCardFromHandText
+ call DrawWideTextBox_WaitForInput
+ call CreateHandCardList
+ lb de, SEARCHEFFECT_BASIC_ENERGY, 0 ; remnant of the energy spike code
+ bank1call InitAndDrawCardListScreenLayout_WithSelectCheckMenu
+ ldtx hl, Choose1BasicEnergyCardFromHandText
+.loop_input
+ bank1call DisplayCardList
+ jr c, .loop_input ; the B button was pressed, cannot exit this menu
+ call CheckDeckIndexForBasicEnergy
+ jr nc, .loop_input; not a Basic Energy card
+ ldh a, [hTempCardIndex_ff98] ; a Basic Energy card was selected
+ ldh [hTemp_ffa0], a ; loads it to [hTemp_ffa0]
+; now to choose an in-play Pokemon to attach it to
+ call EmptyScreen
+ ldtx hl, ChoosePokemonToAttachEnergyCardText
+ call DrawWideTextBox_WaitForInput
+ call InitPlayAreaScreenVars
+.loop_inputPKMN
+ bank1call OpenPlayAreaScreenForSelection
+ jr c, .loop_inputPKMN ; must choose, B button can't be used to exit
+ ldh [hTempPlayAreaLocation_ffa1], a ; loads the pokemon the energy is to be attached to.
+ ret
+AttachBasicEnergyFromHand_AttachEffect:
+ ldh a, [hTempPlayAreaLocation_ffa1]
+ ld e, a
+ ldh a, [hTemp_ffa0]
+ call PutHandCardInPlayArea
+ call IsPlayerTurn
+ ret c ; return if it's player's turn
+; not Player, so show detail screen and which Pokemon was chosen to attach Energy
+ ldh a, [hTempPlayAreaLocation_ffa1]
+ add DUELVARS_ARENA_CARD
+ get_turn_duelist_var
+ call LoadCardDataToBuffer1_FromDeckIndex
+ ld hl, wLoadedCard1Name
+ ld de, wTxRam2_b
+ ld a, [hli]
+ ld [de], a
+ inc de
+ ld a, [hli]
+ ld [de], a
+ ldh a, [hTemp_ffa0]
+ ldtx hl, AttachedEnergyToPokemonText
+ bank1call DisplayCardDetailScreen
+ ret
And that's it for the player. But now we have to make the AI understand this code, so add the following:
+AttachBasicEnergyFromHand_AISelection:
+ call CreateHandCardList
+ ld hl, wDuelTempList
+.loop_hand
+ ld a, [hli]
+ ldh [hTemp_ffa0], a
+ cp $ff
+ ret z ; reached the end of the list
+ call CheckDeckIndexForBasicEnergy
+ jr nc, .loop_hand ; card isn't a Basic Energy
+ xor a ; PLAY_AREA_ARENA
+ ldh [hTempPlayAreaLocation_ffa1], a
+ ret
An attack that attaches a basic energy card from hand to any Pokémon on the field has now been created. However, we can go even further by putting this on an ability, which is even more powerful. Furthermore, now that we have defined this function as an attack, it becomes easier to code it in as an ability.
2. Attach Energy from Hand Pokepower version
Here are the effect commands for the pokepower version of this effect:
+AttachBasicEnergyFromHandPowerEffectCommands:
+ dbw EFFECTCMDTYPE_INITIAL_EFFECT_2, CheckBasicEnergyInHandPower
+ dbw EFFECTCMDTYPE_REQUIRE_SELECTION, AttachBasicEnergyCardFromHandToPkmn_PowerEffect
dbw EFFECTCMDTYPE_AI_SELECTION, AttachBasicEnergyFromHand_AISelection
dbw EFFECTCMDTYPE_BEFORE_DAMAGE, AttachBasicEnergyFromHand_AttachEffect
db $00
Note that AttachBasicEnergyFromHand_AttachEffect and its AI counterpart are the exact same version as the attack effect commands, so we only need to worry about the first two commands.
For the pokepower version of checking if the player has any basic energy in hand, we're going to code it in a way that optimizes this function. Essentially, it is the exact same command as the attack version except we have to check if pokepowers are disabled or if the the pokepower has already been used this turn already. So what we do is that we put those conditions in a command above CheckBasicEnergyInHand and then fallthrough if the pokepower's conditions are met.
+CheckBasicEnergyInHandPower:
+ ldh a, [hTempPlayAreaLocation_ff9d]
+ ldh [hTemp_ffa0], a
+ call OncePerTurnPokePowerCheck ;checks both if used already or if toxic gas is active
+ ret c ; can't use due to status or Toxic Gas
+ ; otherwise fallthrough to CheckBasicEnergyInHand
CheckBasicEnergyInHand:
call CreateHandCardList
ld hl, wDuelTempList
...
...
Likewise, the effect of attaching an energy card from hand to field as a pokemon power is exactly the same but with the checking usage of the power. So we will use the exact same trick for optimization:
+AttachBasicEnergyCardFromHandToPkmn_PowerEffect:
+ ldh a, [hTemp_ffa0]
+ add DUELVARS_ARENA_CARD_FLAGS
+ get_turn_duelist_var
+ set USED_PKMN_POWER_THIS_TURN_F, [hl]
+ ldh a, [hAIPkmnPowerEffectParam]
+ or a
+ ;fallthrough to AttachBasicEnergyCardFromHandToPkmnEffect
Attach1BasicEnergyFromHandToPokemonEffect:
call CreateHandCardList
...
...
And just like that, we've saved a ton of code. Instead oc copying the effects verbatim for a pokemon power, we have typed in a few lines and used the attack code to do everything else.