Card Picking

It is strongly recommended to have a good grasp of the Action System before delving into card picking.

Card Picking Process

One of the more complicated actions a player will take in a deck-builder is the act of actually picking cards. As a result, a rather complex interface was needed in order to ensure every use case is handled. Due to this complexity a step by step breakdown has been provided. This describes what exactly happens when a card pick action is invoked:

1. ActionBasePickCards.perform_action() is called from the ActionHandler.

2. The raw input cardset is obtained. This is determined from the card picking type, aka the pile. This can be things like:

   a. The card invoking the action. Important to note is this is the only way a card can pick itself, as when a card is in play it is in limbo (removed from ALL piles) and thus not target-able through other pile selections. If you'd like to target the card and other cards, you'll need 2 card pick actions. You may also use a BaseCardsetAction with pick_played_card = true and skip the picking process if just selecting the played card.

   b. The player's hand

   b. Their discard/draw/exhaust pile

   c. The combat deck (hand + draw + discard)

   d. Their permanent deck. Any modifications made to these cards will persist between combats.

   e. The 2 cards adjacent in hand to the invoking card if played from hand. Will auto-fail if not played from hand.

   f. A pre-supplied list of cards via pick_draft_cards = true and draft_cards. This is used by the game for drafting from card rewards.

   g. A list of dynamically generated cards if draft_from_card_pool = true. This can either be from a specific card pack, or from the list of cards available to the player for drafting. See ActionBasePickCards.get_drafted_cards() for more. Of note is these cards only exist within the context of the card pick action and you'll almost always want to add them to the player's deck, hand, or another pile via cardset action (see below).

3. This input cardset is then filtered down with a CardFilter using whatever validators you've supplied. This can allow you to do things like asking the player to only pick attack cards, or cards with a cost of 1 etc.

4. An optional step may also throttle the list of cards down to the first N occurrences, good for things like top N cards of draw/discard pile.

5. After the filters, the parameters of the selection are determined. The min and max amount, if the selection is random, and if the minimum number of cards are needed for actions. Depending on how many cards are pickable and these parameters the selection may automatically pass/fail, or require user input

   a. If there are fewer pickable cards than the min required AND you need the minimum to perform actions, it will fail and end the picking action.

   b. If there are fewer pickable cards than the min required AND you DO NOT need the minimum to perform actions, it will automatically select the cards. This is usually paired with a min amount that's high, so that you can auto-select things like your entire hand without user input.

   c. If there are exactly the right number of cards, it will automatically perform the selection.

   d. If there are more cards than the minimum AND the selection is random, the cards will be randomly selected without user input.

   e. If there are more cards than the minimum and it's not random, it will prompt for user input.

6. If the selection is not automatic, one of 3 different user selections will be brought up depending on the type of pile. If the selection happens in the Hand, it will prompt that. If it's a specific pile or a deck selection, the CardSelectionOverlay is used. And if it's a draft selection, CardDraftSelectionOverlay is used.

7. The card picking action will await for the user to select the cards. If can_back_out = true, the user may also back out of the selection in which case an empty selection is returned.

8. After the selection has been made either automatically or by the player, perform_async_action() is called. Depending on what type of card picking action is used, some behavior is executed against the selected cards. For the vast majority of use cases, the ActionPickCards concrete class is used, in which case the child actions will be generated and supplied the selected cards. These actions are almost always (with some exceptions such as ActionConfirmRestAction) extended from BaseCardsetAction, which are designed to work in tandem with card picking actions.

9. The cardset actions will iterate over the list of cards and perform some behavior against them like changing their card cost, card_values, upgrading them, or discarding/exhausting/etc.

10. The card picking action finishes and moves on to the next action.