FFCardGame/docs/DESIGN.md

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