Spell06 Conditional Effects and Card Pools

Part 6: Conditionals & Card Pools (Hymnist Recruit)

← Part 5: Card Triggers | Back to Course Overview

In this final lesson of the spell card series, we explore conditional effects and custom card pools.

Until now, our cards performed effects that always executed unconditionally. Here, we will build Hymnist Recruit, a 1-Ember card that adds one random Hymnist card to your hand and spends 50 gold to add a second one!

---

1. Asset Setup

Download the custom card art:

• Download Art: Save your card art texture as HymnistRecruit.png.
• Save Location: Save it to your mod project under textures/HymnistRecruit.png.

---

2. Complete JSON Definition

In Plugin.cs, add "json/spells/HymnistRecruit.json" to your AddMergedJsonFile call. Then create json/spells/HymnistRecruit.json and add:

{
  "$schema": "https://github.com/Monster-Train-2-Modding-Group/Trainworks-Reloaded/releases/latest/download/schema.json",
  "cards": [
    {
      "id": "HymnistRecruit",
      "cost": 1,
      "names": {
        "english": "Hymnist Recruit"
      },
      "descriptions": {
        "english": "Add an <b>Hymnist</b> to your hand. Spend 50[coin] and add another."
      },
      "rarity": "common",
      "targets_room": true,
      "targetless": false,
      "class": "ClassBanished",
      "card_art": "@HymnistRecruitCardArt",
      "pools": [
        "MegaPool"
      ],
      "effects": [
        "@RecruitAHymnist",
        "@Spend50GoldIfPossible",
        "@RecruitAHymnist"
      ]
    }
  ],
  "effects": [
    {
      "id": "RecruitAHymnist",
      "name": "CardEffectAddBattleCard",
      "param_int": 3,
      "param_int_2": 1,
      "param_bool": true,
      "param_card_pool": "@HymnistRecruitPool"
    },
    {
      "id": "Spend50GoldIfPossible",
      "name": "CardEffectRewardGold",
      "param_int": -50,
      "param_bool": true,
      "should_cancel_subsequent_effects_if_test_fails": true
    }
  ],
  "card_pools": [
    {
      "id": "HymnistRecruitPool",
      "cards": [
        "DeathmetalHymnist",
        "LeadSongbird",
        "PunkrockReveler",
        "UpbeatWarbler"
      ]
    }
  ],
  "game_objects": [
    {
      "id": "HymnistRecruitCardArt",
      "type": "card_art",
      "extensions": {
        "card_art": {
          "sprite": "@HymnistRecruitSprite"
        }
      }
    }
  ],
  "sprites": [
    {
      "id": "HymnistRecruitSprite",
      "path": "textures/HymnistRecruit.png"
    }
  ]
}

---

3. What’s New in This Recipe

Multiple effects and reuse

"effects": [
  "@RecruitAHymnist",
  "@Spend50GoldIfPossible",
  "@RecruitAHymnist"
]

Cards can execute multiple effects in sequence and can reference the same effect more than once.

---

Adding Cards During Combat

{
  "id": "RecruitAHymnist",
  "name": "CardEffectAddBattleCard",
  "param_int": 3,
  "param_int_2": 1,
  "param_bool": true,
  "param_card_pool": "@HymnistRecruitPool"
}

• name: CardEffectAddBattleCard creates cards temporarily for the current battle. (To add cards permanently across the whole run, use CardEffectAddRunCard instead).
• param_int: Specifies the destination pile using the CardPile enum (3 = HandPile):
  • 0 = DeckPile (Bottom of deck)
  • 1 = DiscardPile
  • 2 = ExhaustedPile (Consume pile)
  • 3 = HandPile (Player hand)
  • 5 = DeckPileTop (Top of deck)
  • 7 = DeckPileRandom (Random position in deck)
  • 8 = EatenPile
• param_int_2: Quantity of cards to add (1).
• param_bool: true: Requires available space in the player's hand; if the hand is full, the effect test fails. We explain what effect tests are in the next section.
• param_card_pool: References the card pool to draw from.

---

Conditional Flow: Deducting Gold and Cancelling Effects

{
  "id": "Spend50GoldIfPossible",
  "name": "CardEffectRewardGold",
  "param_int": -50,
  "param_bool": true,
  "should_cancel_subsequent_effects_if_test_fails": true
}

• CardEffectRewardGold: Can deduct gold by passing a negative integer in param_int (-50).
• param_bool: true: Enforces a test check requiring the player to currently possess at least 50 gold.
• should_cancel_subsequent_effects_if_test_fails: true: If the test fails (the player has under 50 gold), this effect fails and skips all remaining effects in the card's array. The first card addition succeeds, but gold deduction and the second card addition are aborted.

Additional Execution Flags

• "should_fail_to_cast_if_test_fails": true: Use this if you want the card to be completely unplayable whenever the player cannot fulfill a singular effect condition.
• "should_test": false: Disables condition testing entirely (seldomly used, defaults to true).

Card Effect Tests

Each card effect tests if the effect can be applied prior to firing the effect. If the test fails then the effect won't play and in some cases the card can not be played.

Generally if a card targets cards with one effect and units in another we have to disable the test. When in doubt, check a similar card to what are you attempting to create in the MonsterTrain2GameData repository

---

Custom Card Pools & Probability Weighting

"card_pools": [
  {
    "id": "HymnistRecruitPool",
    "cards": [
      "DeathmetalHymnist",
      "LeadSongbird",
      "PunkrockReveler",
      "UpbeatWarbler"
    ]
  }
]

• When referencing base-game cards, use internal asset names rather than localized display names (e.g., Punk Shredder is internally named PunkrockReveler) These can also be looked up in the MonsterTrain2GameData repo linked above.
• By default, every entry listed once has an equal chance of being selected.
• To create weighted probabilities, repeat card IDs in the array. For example, in a 10-entry pool, listing a card 3 times gives it a 30% pick chance:

{
  "id": "HymnistRecruitPoolWeighted",
  "cards": [
    "DeathmetalHymnist",
    "LeadSongbird", "LeadSongbird", "LeadSongbird",
    "PunkrockReveler", "PunkrockReveler",
    "UpbeatWarbler", "UpbeatWarbler", "UpbeatWarbler", "UpbeatWarbler"
  ]
}

---

Description Formatting

      "descriptions": {
        "english": "Add an <b>Hymnist</b> to your hand. Spend 50[coin] and add another."
      },

• <b>...</b>: HTML tags like bolding are supported directly inside card descriptions.
• [coin]: Replaced by the gold coin icon.

---

4. Testing Your Card

1. Build and copy your files to BepInEx/plugins/<YourMod>/.
2. Launch Monster Train 2 and inspect the BepInEx console log to confirm clean registration.
3. Enter combat with at least 50 gold:
   • Cast Hymnist Recruit: verify 50 gold is deducted and two random Hymnist cards are placed into your hand.
4. Enter combat with less than 50 gold:
   • Cast Hymnist Recruit: verify no gold is deducted and exactly one Hymnist card is placed into your hand.
5. Test with a hand at the hand-size limit: confirm the effect handles full hand limitations cleanly.

---

Course Completed!

You have completed the Custom Spell Cards tutorial series! You now know how to:

• Set up cards and schemas using Trainworks Reloaded.
• Apply targeted and room-wide damage and status effects.
• Attach temporary and permanent stat upgrades to combat units.
• Scale spell effects dynamically based on battle metrics.
• Build passive turn-end hand triggers for unplayable cards.
• Multiple effects and control execution with conditions. Custom card pools and weighting.

Next Up: Custom Monster Cards