docs/QUICKSTART.md

# 🚀 Quick Start Guide - RTS Commander

## Pour les utilisateurs

### Jouer en ligne
👉 **[Cliquez ici pour jouer](https://huggingface.co/spaces/YOUR_USERNAME/rts-commander)**

Aucune installation requise ! Le jeu se lance directement dans votre navigateur.

### Contrôles du jeu

#### Souris
- **Clic gauche** : Sélectionner une unité
- **Clic gauche + Glisser** : Sélection multiple (boîte)
- **Shift + Clic** : Ajouter à la sélection
- **Clic droit** : Déplacer les unités / Attaquer
- **Clic sur minimap** : Déplacer la caméra

#### Clavier
- **W/A/S/D** ou **Flèches** : Déplacer la caméra
- **Ctrl + A** : Sélectionner toutes les unités
- **Esc** : Annuler l'action en cours

#### Interface
- **Menu gauche** : Construire bâtiments et entraîner unités
- **Menu droit** : File de production et actions rapides
- **Boutons +/-** : Zoom
- **Bouton 🎯** : Réinitialiser la vue

### Conseils de démarrage

1. **Économie d'abord** 💰
   - Construisez une Raffinerie (Refinery)
   - Entraînez des Récolteurs (Harvesters)
   - Collectez les minerais (jaune) et gemmes (violet)

2. **Énergie** ⚡
   - Construisez des Centrales (Power Plants)
   - Surveillez votre consommation d'énergie

3. **Armée** ⚔️
   - Caserne (Barracks) → Infanterie
   - Usine (War Factory) → Chars, Artillerie
   - Mélangez les types d'unités

4. **Défense** 🛡️
   - Placez des Tourelles (Defense Turrets)
   - Gardez des unités près de votre base

---

## Pour les développeurs

### Installation locale

#### Prérequis
- Python 3.11+
- pip

#### Méthode 1 : Script automatique
```bash
cd web/
python3 start.py
```

#### Méthode 2 : Manuel
```bash
cd web/
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
```

Ouvrez http://localhost:7860 dans votre navigateur.

### Tests

```bash
cd web/
./test.sh
```

### Build Docker

```bash
cd web/
docker build -t rts-game .
docker run -p 7860:7860 rts-game
```

### Structure du projet

```
web/
├── app.py              # Backend FastAPI
├── static/
│   ├── index.html      # Interface HTML
│   ├── styles.css      # Design CSS
│   └── game.js         # Client JavaScript
├── Dockerfile          # Configuration Docker
├── requirements.txt    # Dépendances Python
└── README.md          # Documentation HuggingFace
```

### Déploiement HuggingFace Spaces

1. **Créer un Space**
   - Allez sur https://huggingface.co/spaces
   - Cliquez sur "Create new Space"
   - Nom : `rts-commander`
   - SDK : **Docker**
   - License : MIT

2. **Uploader les fichiers**
   - Tous les fichiers du dossier `web/`
   - Particulièrement important : `Dockerfile`, `README.md`

3. **Configuration automatique**
   - HuggingFace détecte le Dockerfile
   - Build automatique
   - Déploiement en quelques minutes

4. **Vérification**
   - Le Space s'ouvre automatiquement
   - Vérifiez l'endpoint `/health`
   - Testez la connexion WebSocket

### Variables d'environnement (optionnel)

```bash
# .env (si besoin)
HOST=0.0.0.0
PORT=7860
DEBUG=False
```

### Développement

#### Structure du code

**Backend (`app.py`)**
- FastAPI application
- WebSocket manager
- Game state management
- AI system

**Frontend**
- `index.html` : Structure UI
- `styles.css` : Design moderne
- `game.js` : Logique client

#### Ajouter une nouvelle unité

1. **Backend** : Ajouter dans `UnitType` enum
```python
class UnitType(str, Enum):
    # ...
    NEW_UNIT = "new_unit"
```

2. **Frontend** : Ajouter bouton dans `index.html`
```html
<button class="unit-btn" data-type="new_unit">
    <span class="unit-icon">🆕</span>
    <span class="unit-name">New Unit</span>
    <span class="unit-cost">123</span>
</button>
```

3. **Rendering** : Ajouter dans `game.js`
```javascript
case 'new_unit':
    // Code de rendu
    break;
```

#### Ajouter un nouveau bâtiment

Même process que pour les unités, mais avec `BuildingType`.

### API Reference

#### WebSocket Endpoint
```
ws://localhost:7860/ws
```

#### REST Endpoints
- `GET /` : Interface de jeu
- `GET /health` : Health check

#### WebSocket Messages

**Client → Serveur**
```javascript
// Déplacer unités
ws.send(JSON.stringify({
    type: "move_unit",
    unit_ids: ["uuid1", "uuid2"],
    target: {x: 100, y: 200}
}));

// Construire unité
ws.send(JSON.stringify({
    type: "build_unit",
    building_id: "uuid",
    unit_type: "tank"
}));

// Placer bâtiment
ws.send(JSON.stringify({
    type: "build_building",
    building_type: "barracks",
    position: {x: 240, y: 240},
    player_id: 0
}));
```

**Serveur → Client**
```javascript
{
    type: "state_update",
    state: {
        tick: 1234,
        players: {...},
        units: {...},
        buildings: {...},
        terrain: [...],
        fog_of_war: [...]
    }
}
```

### Performance Tips

1. **Canvas rendering**
   - Utilisez `requestAnimationFrame()`
   - Évitez les redessins complets
   - Utilisez les layers

2. **WebSocket**
   - Envoyez seulement les changements
   - Compressez les données si nécessaire
   - Throttle les mises à jour

3. **Game loop**
   - 20 ticks/sec est suffisant
   - Interpolation côté client
   - Prediction pour fluidité

### Debugging

#### Backend
```bash
# Activer logs détaillés
uvicorn app:app --log-level debug
```

#### Frontend
```javascript
// Dans la console du navigateur
console.log(window.gameClient.gameState);
console.log(window.gameClient.selectedUnits);
```

#### WebSocket
```javascript
// Monitorer les messages
ws.addEventListener('message', (e) => {
    console.log('Received:', JSON.parse(e.data));
});
```

### Troubleshooting

#### Le jeu ne se charge pas
- Vérifiez la console du navigateur (F12)
- Vérifiez que le serveur est lancé
- Testez `/health` endpoint

#### WebSocket se déconnecte
- Vérifiez les logs serveur
- Problème de firewall ?
- Timeout trop court ?

#### Lag/Performance
- Réduisez le zoom
- Fermez autres onglets
- Vérifiez la connexion réseau

### Contributing

Les contributions sont les bienvenues !

1. Fork le projet
2. Créer une branche (`git checkout -b feature/AmazingFeature`)
3. Commit vos changements (`git commit -m 'Add some AmazingFeature'`)
4. Push vers la branche (`git push origin feature/AmazingFeature`)
5. Ouvrir une Pull Request

### Support

- 📧 Email : support@example.com
- 💬 Discord : [Lien Discord]
- 🐛 Issues : [GitHub Issues]

### License

MIT License - voir le fichier LICENSE pour plus de détails.

---

**Bon jeu ! 🎮**