Card Upgrade Standard

Card Upgrade Standard

Rules every card upgrade in cards.json must follow.

Maintainer: Team 6 Member 1 (Zhenyu He).

Task: #431 — Card Presentation, Story Backgrounds and Game Balance

Related pages:

• Card Design and Naming Standards
• Card Upgrade System (how the campfire upgrade screen works)
• Round 2 Master Card List

Last verified against the repository: 13 October 2026 (main at d06674fb).

Why this exists

The campfire (CardUpgradeSelection) only offers copies of cards that have an upgrade block, and silently skips the rest. On main at d06674fb, only 5 of 26 cards had one (strike, sealed_pact, blood_price, doom_sigil, iron_oath), so most cards could never be upgraded. Sprint 4 gives every card an upgrade.

Where upgrades live

An upgrade is an inline upgrade object on the card in source/core/assets/configs/cards.json. Do not create a separate <id>_upgraded card. Upgraded copies reuse the base card's ID, type, target, artwork and lore.

"upgrade": {
  "name": "Defend+",
  "description": "Gain 8 block.",
  "cost": 1,
  "rarity": "COMMON",
  "effects": [{ "type": "BLOCK", "value": 8, "duration": 0 }]
}

Rules

CardUpgradeStandardTest checks these automatically for every card that has an upgrade.

Rule	Reason
name is the base name plus +, e.g. Strike+	Matches the existing upgrades
rarity is the same as the base card	Rarity decides the card frame and reward weights
cost is not higher than the base cost	An upgrade should never be a downgrade
Same number of effects, same effect types, same order	Keeps the card's identity and resolution order, e.g. SUNDER before DAMAGE
No effect value or duration goes down	Same reason
At least one value, duration or the cost improves	Otherwise it is not an upgrade
description is rewritten to match the upgraded numbers	The card face shows the upgraded description
No lore in the upgrade block	Upgrades reuse the base lore

CardValidator also still applies to upgrade effects: positive values, the right duration rules for each effect type, and effects compatible with the card's target.

Breaking one of these rules on purpose (for example, adding a new effect on upgrade) needs agreement from the balance lead (Yu Zhu) and, for any change to effect behaviour, the mechanic owner.

Choosing what to upgrade

VULNERABLE: the damage multiplier is a fixed 1.5x and the effect value is not used. Always configure VULNERABLE with value 1. Upgrades increase duration, never value. Card text says 'Apply Vulnerable for N turns' without a number before 'Vulnerable'. Re-applying Vulnerable currently overwrites the existing duration (reported to Team 7).

• Vulnerable: the damage bonus is a fixed 1.5x multiplier while the status is active (StatusEffectCalculator), so a higher value does nothing in combat. Upgrade Vulnerable by duration.
• Poison: value is damage per tick and duration is the number of ticks. Either can be upgraded.
• Damage, Pierce, Block, Heal, Strength, Fortify, Sunder: upgrade the value.

How to add upgrades for your cards

1. Add an upgrade block to each of your four cards in cards.json.
2. Remove your card IDs from PENDING_UPGRADES in source/core/src/test/com/csse3200/game/cards/CardUpgradeStandardTest.java in the same PR. The test fails if a card in that set has an upgrade, or a card outside it does not.
3. Run ./gradlew :core:test and ./gradlew formatCheck from source/.
4. Send the values to Yu Zhu for balance review before merging.

Deadline: 16 October 2026.

Initial card upgrades

Added in the #431 PR from task/sprint4-story-and-upgrades. Values are pending balance review.

Card	Base	Upgrade
Defend	Gain 5 block	Gain 8 block
Poison Dagger	Deal 4 damage, 3 Poison for 3 turns	Deal 6 damage, 4 Poison for 3 turns
Expose	Apply Vulnerable to all enemies for 2 turns	Apply Vulnerable to all enemies for 3 turns
Inner Focus	Gain 2 Strength (2 energy)	Gain 3 Strength (2 energy)
Bandage	Heal 6	Heal 9