# FF-TCG Digital - Architecture Design Document

## Overview

This document describes the software architecture of the FF-TCG Digital implementation.

## Technology Stack

- **Game Engine**: Godot 4.2+
- **Language**: GDScript
- **Target Platform**: Linux Desktop
- **Rendering**: Forward+ renderer with 3D isometric view

## Architecture Principles

1. **Separation of Concerns**: Game logic is separate from visual presentation
2. **Event-Driven**: State changes emit signals for loose coupling
3. **Data-Driven**: Card definitions loaded from JSON, not hardcoded
4. **Testable**: Core game logic can be tested independently of visuals

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        Main Scene                                │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Table Scene │  │   UI Layer   │  │ Input Handler│          │
│  │   (3D View)  │  │  (2D Canvas) │  │              │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
├─────────────────────────────────────────────────────────────────┤
│                     Autoload Singletons                          │
│  ┌──────────────┐  ┌──────────────┐                             │
│  │ GameManager  │  │ CardDatabase │                             │
│  └──────────────┘  └──────────────┘                             │
├─────────────────────────────────────────────────────────────────┤
│                      Game State Engine                           │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│  │ GameState  │ │  Player    │ │   Zone     │ │ TurnManager  │ │
│  └────────────┘ └────────────┘ └────────────┘ └──────────────┘ │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐                  │
│  │  CPPool    │ │  Combat    │ │   Stack    │                  │
│  └────────────┘ └────────────┘ └────────────┘                  │
└─────────────────────────────────────────────────────────────────┘
```

## Core Components

### Autoload Singletons

#### GameManager (`scripts/autoload/GameManager.gd`)
Central coordinator for game flow. Responsibilities:
- Initialize new games
- Coordinate between game state and visuals
- Handle high-level game events
- Manage scene transitions

Signals:
- `game_started()`
- `game_ended(winner: int)`
- `turn_changed(player_index: int)`
- `phase_changed(phase: TurnPhase)`

#### CardDatabase (`scripts/autoload/CardDatabase.gd`)
Manages card definitions loaded from JSON. Responsibilities:
- Load and parse `data/cards.json`
- Provide card lookup by ID
- Validate card data on load
- Cache card textures

Methods:
- `get_card(id: String) -> CardData`
- `get_cards_by_element(element: Element) -> Array[CardData]`
- `get_cards_by_type(type: CardType) -> Array[CardData]`

### Game State Classes

#### GameState (`scripts/game/GameState.gd`)
Master game state container. Holds:
- Two Player instances
- Shared Stack for ability resolution
- Current turn/phase information
- Game rules enforcement

#### Player (`scripts/game/Player.gd`)
Individual player state. Contains:
- Hand (Zone)
- Deck (Zone)
- Field - Forwards area (Zone)
- Field - Backups area (Zone)
- Damage Zone (Zone)
- Break Zone (Zone)
- Current CP pool

#### Zone (`scripts/game/Zone.gd`)
Base class for card containers. Types:
- `DECK` - Hidden, ordered
- `HAND` - Hidden from opponent
- `FIELD_FORWARDS` - Public
- `FIELD_BACKUPS` - Public, max 5
- `DAMAGE` - Public, ordered
- `BREAK` - Public discard

Methods:
- `add_card(card: CardInstance)`
- `remove_card(card: CardInstance)`
- `get_cards() -> Array[CardInstance]`
- `shuffle()`

#### TurnManager (`scripts/game/TurnManager.gd`)
Handles turn structure and phase progression.

Phases (enum TurnPhase):
1. `ACTIVE` - Activate dull characters
2. `DRAW` - Draw cards
3. `MAIN_1` - Play cards/abilities
4. `ATTACK` - Combat
5. `MAIN_2` - Play cards/abilities
6. `END` - Cleanup

#### CPPool (`scripts/game/CPPool.gd`)
Tracks generated Crystal Points by element.

Properties:
- `cp: Dictionary` - Element -> count mapping

Methods:
- `add_cp(element: Element, amount: int)`
- `spend_cp(cost: Dictionary) -> bool`
- `can_afford(cost: Dictionary) -> bool`
- `clear()`

#### Combat (`scripts/game/Combat.gd`)
Handles attack phase logic.

States:
- `IDLE`
- `DECLARING_ATTACKER`
- `WAITING_BLOCKER`
- `RESOLVING_DAMAGE`

### Visual Components

#### TableCamera (`scripts/visual/TableCamera.gd`)
Isometric camera setup:
- 45° rotation on Y axis
- ~35° tilt down on X axis
- Orthographic or perspective projection
- Fixed position showing full board

#### CardVisual (`scripts/visual/CardVisual.gd`)
3D card representation:
- MeshInstance3D with PlaneMesh
- Dynamic texture from card image
- States: normal, highlighted, selected, dull
- Animation support for movement

#### ZoneVisual (`scripts/visual/ZoneVisual.gd`)
Visual representation of card zones:
- Manages card positioning
- Handles card enter/exit animations
- Supports stacking and spreading

## Data Flow

### Playing a Card

```
1. Player clicks card in hand
   │
2. InputHandler detects selection
   │
3. GameManager.request_play_card(card)
   │
4. GameState.validate_play(card)
   ├── Check phase (must be Main Phase)
   ├── Check CP requirements
   └── Check field limits
   │
5. If valid: GameState.execute_play(card)
   ├── CPPool.spend_cp(card.cost)
   ├── Hand.remove_card(card)
   └── Field.add_card(card)
   │
6. GameState emits card_played signal
   │
7. Visual layer animates card movement
```

### Combat Flow

```
1. Attack Phase begins
   │
2. Active player selects attacker
   ├── Must be active Forward
   └── Must be able to attack
   │
3. Attacker is dulled
   │
4. Defending player may select blocker
   ├── Must be active Forward
   └── Optional
   │
5. Damage resolution
   ├── If blocked: Exchange damage equal to Power
   └── If unblocked: Deal 1 damage to player
   │
6. Check for broken Forwards
   │
7. Return to step 2 or end Attack Phase
```

## File Organization

```
scripts/
├── autoload/
│   ├── GameManager.gd      # Game flow coordinator
│   └── CardDatabase.gd     # Card data management
├── game/
│   ├── GameState.gd        # Master game state
│   ├── Player.gd           # Player state
│   ├── Zone.gd             # Zone base class
│   ├── CardInstance.gd     # Runtime card instance
│   ├── TurnManager.gd      # Turn/phase handling
│   ├── CPPool.gd           # CP tracking
│   ├── Combat.gd           # Combat resolution
│   └── Enums.gd            # Shared enumerations
├── visual/
│   ├── TableCamera.gd      # Isometric camera
│   ├── CardVisual.gd       # 3D card rendering
│   ├── ZoneVisual.gd       # Zone rendering
│   └── TableSetup.gd       # Table scene setup
└── ui/
    ├── GameUI.gd           # Main UI controller
    ├── CardDetailPanel.gd  # Card info popup
    ├── CPDisplay.gd        # CP pool display
    └── TurnIndicator.gd    # Turn/phase display
```

## Signals Reference

### GameManager Signals
| Signal | Parameters | Description |
|--------|------------|-------------|
| `game_started` | none | New game initialized |
| `game_ended` | `winner: int` | Game over |
| `turn_changed` | `player: int` | Active player changed |
| `phase_changed` | `phase: TurnPhase` | Phase advanced |

### GameState Signals
| Signal | Parameters | Description |
|--------|------------|-------------|
| `card_played` | `card, player` | Card deployed to field |
| `card_moved` | `card, from, to` | Card changed zones |
| `damage_dealt` | `player, amount` | Player took damage |
| `forward_broken` | `card` | Forward destroyed |

### Player Signals
| Signal | Parameters | Description |
|--------|------------|-------------|
| `hand_changed` | none | Hand contents updated |
| `cp_changed` | `pool` | CP pool updated |
| `field_changed` | none | Field contents updated |

## Testing Strategy

### Unit Tests
- Card data validation
- CP calculation
- Combat damage resolution
- Zone operations

### Integration Tests
- Full turn cycle
- Complete game to win condition
- Edge cases (deck empty, backup limit)

### Manual Testing
- Visual correctness
- Input responsiveness
- Animation smoothness