This page describes the structure and validation rules of card data: what a card definition contains, which values are valid, and how to add new cards.

Owner: Card Data Model (#31)
Related pages: Card Library API · Initial Cards

• Overview
• CardConfig
• EffectConfig
• Enumerations
• Validation contract
• JSON format
• Adding a new card
• Known limitations
• Test coverage

Card definitions are stored in source/core/assets/configs/cards.json and deserialised into CardConfig objects.

A card's category (CardType) is deliberately separate from its behaviour (effects). This allows any card type to contain any combination of effects. For example, an ATTACK card can both deal damage and apply a debuff.

Adding a card normally requires editing JSON only. Java changes are needed only when the card requires a new effect type.

Class: com.csse3200.game.cards.configs.CardConfig

CardConfig uses public fields without getters, following the convention used by PlayerConfig and NPCConfigs elsewhere in the codebase.

CardValidator does not require description, but CardConfigLoader rejects JSON in which description is missing or null.

As a result:

• a manually constructed CardConfig with a blank description passes validation;
• the same card loaded from JSON is rejected.

This inconsistency is tracked under Known limitations.

The target field belongs to the card, not to individual effects. One target therefore governs every effect on the card.

For example, the current model cannot represent a card that deals damage to an enemy and grants block to the player. Supporting mixed targets would require moving target onto EffectConfig.

Class: com.csse3200.game.cards.configs.EffectConfig

new EffectConfig();
// DAMAGE, value 0, duration 0

new EffectConfig(EffectType type, int value);
// duration defaults to 0

new EffectConfig(EffectType type, int value, int duration);

effects is intentionally declared as EffectConfig[], rather than List<EffectConfig>. The shared static Json instance in FileLoader cannot resolve the element type of List<T> because of generic type erasure, so a list does not deserialise correctly.

CardConfigTest.shouldDeclareEffectsAsArray verifies the array declaration through reflection. Changing the field to a list therefore fails the build instead of silently failing at runtime.

Each effect type declares whether it uses duration through EffectType.usesDuration(). Validation reads this flag instead of maintaining a separate hard-coded list.

STRENGTH uses duration = 0 because it lasts for the whole combat. In this case, zero means “not measured in turns,” not “expires immediately.”

The available rarity values are COMMON, UNCOMMON, and RARE. Rarity is used when cards are offered as rewards.

CardValidator.validate(CardConfig) returns a List<String> containing every validation error. CardValidator.isValid(CardConfig) returns a boolean.

Validation errors are aggregated, so callers receive all detected problems rather than only the first one.

A card is rejected when any of the following conditions is true:

• id is null, blank, or contains leading or trailing whitespace;
• name is null or blank;
• type, rarity, or target is null;
• texturePath is null or blank;
• effects is null or empty;
• an effect entry is null, or its type is null;
• cost is negative;
• an effect's value is <= 0;
• an effect for which usesDuration() is true has duration <= 0;
• an effect for which usesDuration() is false has duration != 0.

CardLibrary.register() applies the complete validation contract. Partially populated configurations—for example, a test stub without texturePath—are rejected during registration as well as during file loading.

The configuration file is a wrapper object containing one cards array, matching the NPCConfigs pattern used elsewhere. It is not a bare JSON array.

{
  "cards": [
    {
      "id": "poison_dagger",
      "name": "Poison Dagger",
      "description": "Deal 4 damage. Apply 3 Poison for 3 turns.",
      "cost": 1,
      "type": "ATTACK",
      "rarity": "UNCOMMON",
      "target": "SINGLE_ENEMY",
      "effects": [
        { "type": "DAMAGE", "value": 4, "duration": 0 },
        { "type": "POISON", "value": 3, "duration": 3 }
      ],
      "texturePath": "images/cards/poison_dagger.png"
    }
  ]
}

Effects are applied in array order. Enumeration values must use their exact uppercase constant names; the loader rejects unrecognised values.

1. Add a card object to the cards array in source/core/assets/configs/cards.json.

2. Assign a unique id without surrounding whitespace.

3. Include every field, including description.

4. Set duration according to the selected effect type.

5. Add the artwork at the path specified by texturePath.

6. Run the core test suite:

   ./gradlew core:test

The loader and end-to-end tests validate the real cards.json, so malformed card data fails the build. Card-count assertions have been removed; adding cards does not require updating a fixed expected count.

Loading and registry behaviour is covered separately by CardConfigLoaderTest, CardLibraryTest, and CardsEndToEndTest.