# Godot 4 Project Structure — Squadron TD Clone

## Top-Level Layout

```
squadron-td/
├── project.godot
├── export_presets.cfg
├── .gitignore
├── CHANGELOG.md
│
├── assets/                   # Raw art & audio (imported by Godot)
│   ├── sprites/
│   │   ├── towers/           # One folder per race
│   │   │   ├── ghost/
│   │   │   ├── fortress/
│   │   │   ├── phantom/
│   │   │   └── ancient/
│   │   ├── creeps/
│   │   ├── ui/
│   │   └── environment/
│   ├── audio/
│   │   ├── sfx/
│   │   └── music/
│   └── fonts/
│
├── data/                     # Game balance data (JSON or GDScript constants)
│   ├── towers/               # One .json per race, defines all tower entries
│   │   ├── ghost.json
│   │   ├── fortress.json
│   │   ├── phantom.json
│   │   └── ancient.json
│   ├── waves.json            # All 31 wave definitions
│   └── sends.json            # Send unit definitions + income values
│
├── scenes/                   # Godot .tscn scene files
│   ├── main/
│   │   ├── Main.tscn         # Root scene, bootstraps game
│   │   └── GameLoop.tscn     # Phase state machine
│   ├── ui/
│   │   ├── HUD.tscn          # In-game HUD (minerals, gas, wave counter)
│   │   ├── BuildPanel.tscn   # Tower build/upgrade UI
│   │   ├── RaceSelect.tscn   # Builder race selection screen
│   │   └── GameOver.tscn
│   ├── gameplay/
│   │   ├── Lane.tscn         # One player's lane (tilemap + path)
│   │   ├── SecuritySystem.tscn
│   │   ├── TowerSlot.tscn    # Placeable cell on the lane grid
│   │   ├── Tower.tscn        # Base tower scene (morphs to fighter)
│   │   ├── Fighter.tscn      # Fighter unit (AI-controlled during combat)
│   │   ├── Creep.tscn        # Enemy unit following path
│   │   └── Worker.tscn       # Economy worker
│   └── effects/
│       ├── Projectile.tscn
│       └── HitEffect.tscn
│
├── scripts/                  # GDScript source files
│   ├── autoload/             # Singletons (add to Project > Autoload)
│   │   ├── GameState.gd      # Global game state (phase, wave number, etc.)
│   │   ├── Economy.gd        # Mineral/gas tracking and income calculation
│   │   ├── WaveManager.gd    # Wave sequencing and creep spawning
│   │   └── EventBus.gd       # Global signal bus (decoupled communication)
│   ├── gameplay/
│   │   ├── Lane.gd
│   │   ├── TowerSlot.gd
│   │   ├── Tower.gd          # Data-driven; loads stats from data/towers/
│   │   ├── Fighter.gd        # AI: seek nearest creep, attack
│   │   ├── Creep.gd          # Path follow, HP, armor type
│   │   ├── Worker.gd
│   │   └── SecuritySystem.gd
│   ├── ui/
│   │   ├── HUD.gd
│   │   ├── BuildPanel.gd
│   │   ├── RaceSelect.gd
│   │   └── GameOver.gd
│   ├── data/
│   │   ├── TowerData.gd      # Resource class for tower definitions
│   │   ├── WaveData.gd       # Resource class for wave definitions
│   │   └── DataLoader.gd     # Loads and validates JSON data files
│   └── utils/
│       ├── DamageCalc.gd     # Armor/attack type damage matrix
│       └── PathUtils.gd      # Pathfinding helpers
│
└── tests/                    # GUT (Godot Unit Testing) test files
    ├── test_damage_calc.gd
    ├── test_economy.gd
    └── test_wave_data.gd
```

---

## Key Architectural Decisions

### Data-Driven Towers
Tower stats live in `data/towers/<race>.json`. The `Tower.gd` script reads these at runtime — adding a new tower means editing JSON, not code.

### Phase State Machine
`GameLoop.tscn` drives a state machine with three states: `BUILD`, `COMBAT`, `INCOME`. Transitions are signaled via `EventBus`.

### Autoload Singletons
| Singleton | Responsibility |
|---|---|
| GameState | Current phase, wave number, player list |
| Economy | Per-player minerals/gas, income tracking |
| WaveManager | Spawning creeps, tracking wave completion |
| EventBus | Decoupled signals (wave_started, creep_died, etc.) |

### Fighter AI
During `COMBAT` phase, towers emit their fighter node (or morph in place). `Fighter.gd` uses a simple priority: find nearest creep in range → attack. No pathfinding needed for fighters — they engage from position.

### Multiplayer (stretch)
Use Godot 4's built-in `MultiplayerAPI` (ENet or WebRTC). `GameState` and `Economy` will need `@rpc` annotations. Design scripts to be authority-aware from the start.

---

## Godot Project Settings to Configure

- **Main Scene:** `scenes/main/Main.tscn`
- **Autoloads:** GameState, Economy, WaveManager, EventBus
- **Input Map:** `build_mode`, `cancel`, `next_wave`, `send_unit`
- **Rendering:** 2D, pixel art mode if using pixel sprites (`snap 2D transforms`)
- **Physics Layers:** Layer 1 = Creeps, Layer 2 = Fighters, Layer 3 = Projectiles

---

## .gitignore (Godot 4)

```gitignore
# Godot 4 generated files
.godot/
*.translation
export_presets.cfg   # machine-specific, keep out of repo unless needed

# OS
.DS_Store
Thumbs.db
```