FFCardGame/docs/CARD_FORMAT.md

Card Data Format Specification

Overview

Card data is stored in data/cards.json as a JSON file. This document describes the schema and valid values for card definitions.

Schema

Root Object

{
  "version": "1.0",
  "cards": [ ... ]
}

Field	Type	Required	Description
version	string	Yes	Schema version for compatibility
cards	array	Yes	Array of card objects

Card Object

{
  "id": "1-003C",
  "name": "Red Mage",
  "type": "Backup",
  "element": "Fire",
  "cost": 2,
  "power": null,
  "job": "Standard Unit",
  "category": "II",
  "is_generic": false,
  "has_ex_burst": false,
  "abilities": [ ... ],
  "image": "1-003C_eg.jpg"
}

Field	Type	Required	Description
id	string	Yes	Unique card identifier (e.g., "1-003C")
name	string	Yes	Card name
type	string	Yes	Card type: "Forward", "Backup", "Summon", "Monster"
element	string/array	Yes	Element(s): see Element Values
cost	integer	Yes	CP cost to play (0-10)
power	integer/null	Conditional	Power value (required for Forwards, null otherwise)
job	string	No	Job class (for characters)
category	string	No	Game category (e.g., "II", "VII", "XIV")
is_generic	boolean	No	If true, can have multiple copies on field (default: false)
has_ex_burst	boolean	No	If true, has EX Burst ability (default: false)
abilities	array	No	Array of ability objects
image	string	No	Image filename in assets/cards/

Element Values

Single element (string):

• "Fire" - Red
• "Ice" - Cyan/Light Blue
• "Wind" - Green
• "Lightning" - Purple
• "Water" - Blue
• "Earth" - Yellow/Brown
• "Light" - White
• "Dark" - Black

Multi-element (array):

"element": ["Fire", "Ice"]

Card Types

Type	Description	Has Power	Notes
Forward	Combat units	Yes	Can attack and block
Backup	Support units	No	Generate CP, max 5
Summon	One-time effects	No	Goes to Break Zone
Monster	Special characters	Varies	Can have unique rules

Ability Object

{
  "type": "action",
  "name": "Cure",
  "cost": {
    "fire": 1,
    "dull": true
  },
  "effect": "Choose 1 Forward. It cannot block this turn.",
  "is_ex_burst": false
}

Field	Type	Required	Description
type	string	Yes	Ability type (see Ability Types)
name	string	No	Named ability (for Special abilities)
cost	object	Conditional	Cost to activate (for action/special)
effect	string	Yes	Effect text description
is_ex_burst	boolean	No	If true, this is the EX Burst ability
trigger	string	Conditional	Trigger condition (for auto abilities)

Ability Types

Type	Description	Has Cost
field	Always active while on field	No
auto	Triggers on specific events	No (but may have conditions)
action	Activated by paying cost	Yes
special	Named ability requiring card discard	Yes

Cost Object

{
  "generic": 2,
  "fire": 1,
  "ice": 0,
  "wind": 0,
  "lightning": 0,
  "water": 0,
  "earth": 0,
  "light": 0,
  "dark": 0,
  "dull": false,
  "discard": 0,
  "specific_discard": null
}

Field	Type	Default	Description
generic	integer	0	Any element CP
fire	integer	0	Fire element CP required
ice	integer	0	Ice element CP required
wind	integer	0	Wind element CP required
lightning	integer	0	Lightning element CP required
water	integer	0	Water element CP required
earth	integer	0	Earth element CP required
light	integer	0	Light element CP required
dark	integer	0	Dark element CP required
dull	boolean	false	Requires dulling this card
discard	integer	0	Number of cards to discard
specific_discard	string	null	Specific card name to discard

Examples

Forward Card

{
  "id": "1-006H",
  "name": "Garland",
  "type": "Forward",
  "element": "Fire",
  "cost": 5,
  "power": 8000,
  "job": "Knight",
  "category": "DFF-I",
  "is_generic": false,
  "has_ex_burst": false,
  "abilities": [
    {
      "type": "field",
      "effect": "Brave"
    },
    {
      "type": "auto",
      "trigger": "When Garland attacks",
      "effect": "Garland gains +4000 power until the end of the turn."
    }
  ],
  "image": "1-006H_eg.jpg"
}

Backup Card

{
  "id": "1-003C",
  "name": "Red Mage",
  "type": "Backup",
  "element": "Fire",
  "cost": 2,
  "power": null,
  "job": "Standard Unit",
  "category": "II",
  "is_generic": true,
  "has_ex_burst": false,
  "abilities": [
    {
      "type": "action",
      "cost": {
        "fire": 1,
        "dull": true
      },
      "effect": "Choose 1 Forward. It cannot block this turn."
    }
  ],
  "image": "1-003C_eg.jpg"
}

Summon Card

{
  "id": "1-023R",
  "name": "Ifrit",
  "type": "Summon",
  "element": "Fire",
  "cost": 3,
  "power": null,
  "category": "III",
  "has_ex_burst": true,
  "abilities": [
    {
      "type": "auto",
      "effect": "If a Fire Forward has entered your field this turn, the cost required to cast Ifrit is reduced by 3. Choose 1 Forward. Deal it 7000 damage.",
      "is_ex_burst": true
    }
  ],
  "image": "1-023R_eg.jpg"
}

Multi-Element Card

{
  "id": "12-001H",
  "name": "Vaan",
  "type": "Forward",
  "element": ["Fire", "Lightning"],
  "cost": 4,
  "power": 8000,
  "job": "Sky Pirate",
  "category": "XII",
  "abilities": [
    {
      "type": "auto",
      "trigger": "When Vaan enters the field",
      "effect": "Choose 1 Forward. Dull it."
    }
  ]
}

Validation Rules

1. ID Uniqueness: Each card must have a unique id
2. Power Requirement: power must be set for Forwards, null for others
3. Element Validity: Elements must be from the valid list
4. Cost Range: cost must be 0-10
5. Power Range: power must be 1000-99000 in increments of 1000
6. Ability Costs: Action and Special abilities must have a cost object

Loading Process

1. Read data/cards.json
2. Parse JSON
3. Validate each card against schema
4. Build lookup dictionaries (by ID, by element, by type)
5. Pre-load referenced images
6. Report any validation errors