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

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

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

### Card Object

```json
{
  "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):
```json
"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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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