docs/ARCHITECTURE.md

# 🎮 RTS Game - Architecture Web Moderne

## 📋 Vue d'ensemble

Ce projet est une **réimplémentation complète** du jeu RTS Python/Pygame vers une architecture web moderne, optimisée pour HuggingFace Spaces avec Docker.

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Frontend (Browser)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  HTML5 Canvas│  │  JavaScript  │  │  CSS Moderne │  │
│  │   Rendering  │  │ Game Client  │  │   UI/UX      │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                            ↕ WebSocket
┌─────────────────────────────────────────────────────────┐
│              Backend (FastAPI + Python)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   FastAPI    │  │  WebSocket   │  │ Game Engine  │  │
│  │   Server     │  │   Manager    │  │  Simulation  │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────┐
│                  Docker Container                        │
│              (HuggingFace Spaces)                        │
└─────────────────────────────────────────────────────────┘
```

## 🎯 Composants Principaux

### Backend (`app.py`)

**FastAPI Server** avec les fonctionnalités suivantes :

- **WebSocket en temps réel** : Communication bidirectionnelle pour le jeu
- **Game State Manager** : Gestion de l'état du jeu côté serveur
- **Game Loop** : 20 ticks/seconde pour une simulation fluide
- **AI System** : Intelligence artificielle pour l'adversaire
- **Production System** : File d'attente et construction d'unités/bâtiments

**Classes Principales** :
- `GameState` : État global du jeu (unités, bâtiments, terrain, joueurs)
- `ConnectionManager` : Gestion des connexions WebSocket
- `Unit`, `Building`, `Player` : Entités de jeu avec dataclasses
- Enums : `UnitType`, `BuildingType`, `TerrainType`

### Frontend

#### `index.html` - Structure
- **Top Bar** : Ressources, connexion, statistiques
- **Left Sidebar** : Menu de construction et entraînement d'unités
- **Canvas Principal** : Zone de jeu interactive
- **Minimap** : Vue d'ensemble avec indicateur de viewport
- **Right Sidebar** : File de production, actions rapides, stats
- **Notifications** : Système de messages toast

#### `styles.css` - UI/UX Moderne
- **Design sombre** : Palette de couleurs professionnelle
- **Animations fluides** : Transitions, hover effects, pulse
- **Responsive** : Adapté aux différentes tailles d'écran
- **Gradients** : Effets visuels modernes
- **Glassmorphism** : Effets de transparence et de flou

#### `game.js` - Client de Jeu
- **GameClient Class** : Gestion complète du client
- **Canvas Rendering** : Dessin du terrain, unités, bâtiments
- **Input Handling** : Souris, clavier, drag-to-select
- **WebSocket Client** : Communication en temps réel
- **Camera System** : Pan, zoom, minimap
- **Selection System** : Sélection unitaire et multiple

## 🎮 Fonctionnalités

### Gameplay

✅ **Types d'unités**
- Infantry (Infanterie) - 100💰
- Tank (Char) - 300💰
- Harvester (Récolteur) - 200💰
- Helicopter (Hélicoptère) - 400💰
- Artillery (Artillerie) - 500💰

✅ **Types de bâtiments**
- HQ (Quartier Général) - Base principale
- Barracks (Caserne) - Entraînement infanterie
- War Factory (Usine) - Production véhicules
- Refinery (Raffinerie) - Traitement ressources
- Power Plant (Centrale) - Production énergie
- Defense Turret (Tourelle) - Défense

✅ **Système de ressources**
- Ore (Minerai) - Ressource standard
- Gem (Gemmes) - Ressource rare (valeur supérieure)
- Credits - Monnaie du jeu
- Power - Énergie pour les bâtiments

✅ **Contrôles intuitifs**
- Sélection par clic ou drag
- Commandes par clic droit
- Raccourcis clavier
- Interface tactile-ready

### UI/UX Améliorée

🎨 **Design Professionnel**
- Interface sombre avec accents colorés
- Icônes emoji pour accessibilité
- Barres de santé dynamiques
- Indicateurs visuels clairs

📊 **HUD Complet**
- Affichage ressources en temps réel
- Compteur d'unités et bâtiments
- État de connexion
- File de production visible

🗺️ **Minimap Interactive**
- Vue d'ensemble de la carte
- Indicateur de viewport
- Clic pour navigation rapide
- Code couleur joueur/ennemi

⚡ **Performances Optimisées**
- Rendu Canvas optimisé
- Mises à jour incrémentales
- Gestion efficace de la mémoire
- Animations fluides 60 FPS

## 🚀 Déploiement

### Local

```bash
# Installation
cd web/
pip install -r requirements.txt

# Démarrage
python3 start.py
# ou
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
```

### Docker

```bash
# Build
docker build -t rts-game .

# Run
docker run -p 7860:7860 rts-game
```

### HuggingFace Spaces

1. Créer un Space avec SDK Docker
2. Uploader tous les fichiers du dossier `web/`
3. HuggingFace build automatiquement avec le Dockerfile

## 📡 API WebSocket

### Messages Client → Serveur

**Déplacer unités**
```json
{
  "type": "move_unit",
  "unit_ids": ["uuid1", "uuid2"],
  "target": {"x": 100, "y": 200}
}
```

**Construire unité**
```json
{
  "type": "build_unit",
  "building_id": "uuid",
  "unit_type": "tank"
}
```

**Placer bâtiment**
```json
{
  "type": "build_building",
  "building_type": "barracks",
  "position": {"x": 240, "y": 240},
  "player_id": 0
}
```

### Messages Serveur → Client

**État initial**
```json
{
  "type": "init",
  "state": { ... }
}
```

**Mise à jour**
```json
{
  "type": "state_update",
  "state": {
    "tick": 1234,
    "players": {...},
    "units": {...},
    "buildings": {...},
    "terrain": [...],
    "fog_of_war": [...]
  }
}
```

## 🔧 Technologies Utilisées

### Backend
- **FastAPI** : Framework web moderne et performant
- **WebSockets** : Communication temps réel
- **Python 3.11** : Langage avec dataclasses, type hints
- **Uvicorn** : Serveur ASGI haute performance

### Frontend
- **HTML5 Canvas** : Rendu 2D performant
- **Vanilla JavaScript** : Pas de dépendances lourdes
- **CSS3** : Animations et design moderne
- **WebSocket API** : Communication bidirectionnelle

### DevOps
- **Docker** : Containerisation
- **HuggingFace Spaces** : Hébergement cloud
- **Git** : Contrôle de version

## 📈 Améliorations vs Version Pygame

### Accessibilité
✅ Fonctionne dans le navigateur (pas d'installation)
✅ Compatible multi-plateforme (Windows, Mac, Linux, mobile)
✅ Hébergeable sur le cloud
✅ Partage facile via URL

### UI/UX
✅ Interface moderne et professionnelle
✅ Design responsive
✅ Animations fluides
✅ Meilleure lisibilité

### Architecture
✅ Séparation client/serveur
✅ Prêt pour le multijoueur
✅ État du jeu côté serveur
✅ Communication temps réel

### Performance
✅ Rendu optimisé Canvas
✅ Mise à jour incrémentale
✅ Gestion efficace réseau
✅ Scalabilité améliorée

## 🎯 Prochaines Étapes Possibles

- [ ] Système de brouillard de guerre fonctionnel
- [ ] Pathfinding A* pour les unités
- [ ] Combat avec projectiles animés
- [ ] Système de son et musique
- [ ] Mode multijoueur réel
- [ ] Système de sauvegarde
- [ ] Campagne avec missions
- [ ] Éditeur de cartes
- [ ] Classements et statistiques
- [ ] Support tactile amélioré

## 📝 Notes Techniques

### Performance
- Game Loop : 20 ticks/seconde côté serveur
- Rendu : 60 FPS côté client
- Latence WebSocket : < 50ms en moyenne

### Sécurité
- Validation côté serveur de toutes les commandes
- Rate limiting possible
- Sanitization des inputs

### Scalabilité
- Architecture prête pour Redis (état partagé)
- Possibilité de load balancing
- Stateless pour scaling horizontal

---

**Développé avec ❤️ pour HuggingFace Spaces**