# Team Wizard Battle - Documentation

## 🎮 Vue d'ensemble

**Team Wizard Battle** est un jeu éducatif compétitif où deux équipes s'affrontent dans une course aux DPS (Damage Per Second) contre un boss partagé. Les élèves doivent construire des phrases en anglais le plus rapidement possible pour infliger des dégâts.

## 🏆 Objectif Pédagogique

- **Pratique orale** : Les élèves crient les mots pour aider leur coéquipier
- **Construction de phrases** : Grammaire et syntaxe en contexte pressant
- **Collaboration** : L'équipe entière participe activement
- **Vitesse de réflexion** : Bonus pour les réponses rapides

## 🎯 Règles du Jeu

### Configuration
- **2 équipes** : Rouge vs Bleu
- **10 rounds maximum**
- **Boss partagé** : 500 HP
- **Alternance** : RED → BLUE → RED → BLUE...

### Gameplay
1. Une phrase en chinois apparaît
2. L'élève au tableau doit construire la traduction anglaise
3. Son équipe peut **crier les mots** pour l'aider
4. Plus c'est rapide, plus le DPS est élevé !
5. Après chaque réponse correcte, on passe à l'autre équipe

### Système de DPS
Le DPS gagné dépend de la **vitesse de réponse** :

| Temps | Multiplicateur | DPS | Feedback |
|-------|---------------|-----|----------|
| < 3 secondes | 250% | Damage × 2.5 | 🔥 CRITICAL! 250% DPS! |
| 3-5 secondes | 200% | Damage × 2.0 | ⚡ EXCELLENT! 200% DPS! |
| 5-8 secondes | 150% | Damage × 1.5 | ✨ GOOD! 150% DPS! |
| 8-12 secondes | 100% | Damage × 1.0 | 👍 Normal DPS |
| > 12 secondes | 50% | Damage × 0.5 | 🐌 TOO SLOW! 50% DPS |

### Victoire
Le jeu se termine quand :
- Le boss est vaincu (HP = 0), OU
- 10 rounds sont terminés

**L'équipe avec le PLUS de DPS total gagne !**

## 🐛 Bugs Corrigés

### Bug #1: Condition de victoire incorrecte
**Problème** : `currentRound >= maxRounds` arrêtait le jeu au round 9
**Fix** : Changé en `currentRound > maxRounds`
**Impact** : Les joueurs peuvent maintenant jouer tous les 10 rounds

### Bug #2: Conflit CSS
**Problème** : CSS ID utilisait encore `wizard-spell-caster-styles`
**Fix** : Changé en `team-wizard-battle-styles`
**Impact** : Évite les conflits si les deux jeux sont chargés

### Bug #3: Message d'erreur incorrect
**Problème** : Message d'erreur affichait "Wizard Spell Caster Error"
**Fix** : Changé en "Team Wizard Battle Error"
**Impact** : Clarté pour le débugging

### Bug #4: Boss attaque les joueurs
**Problème** : Le boss attaquait encore, causant des défaites
**Fix** : Désactivé `_startEnemyAttackSystem()`
**Impact** : Le jeu est maintenant une pure DPS race sans interruption

### Bug #5: Cast Button jamais réactivé 🔴 **CRITIQUE**
**Problème** : Après un sort RÉUSSI, le bouton cast restait désactivé pour toujours
**Fix** : Ajout de `castButton.disabled = false` dans `_generateNewSpells()`
**Impact** : Le jeu est maintenant jouable ! (c'était game-breaking)

### Bug #6: Spam-click sur boutons de victoire 🟠 **MAJEUR**
**Problème** : Aucune protection contre les enfants qui spam-cliquent "Play Again"
**Fix** : Ajout de `{ once: true }` et `disabled = true` sur les event listeners
**Impact** : Pas de memory leaks ni navigation cassée

### Bug #7: Spam-click sur bouton Exit 🟡 **MOYEN**
**Problème** : Bouton Exit sans protection spam-click
**Fix** : Ajout de `{ once: true }` et `disabled = true`
**Impact** : Navigation stable et prévisible

## 🎨 Interface Utilisateur

```
┌─────────────────────────────────────────────────────────┐
│  🔴 RED TEAM          Round: 3/10          🔵 BLUE TEAM │
│  450 DPS         🔴 RED TEAM TURN           320 DPS     │
├─────────────────────────────────────────────────────────┤
│              Boss HP: ████████░░ 350/500                │
├─────────────────────────────────────────────────────────┤
│                                                         │
│        🧙‍♂️                      👹                      │
│    Wizard Master            Grammar Demon              │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  [Spell Cards avec phrases chinoises]                  │
│                                                         │
│  Form your spell incantation:                           │
│  [Zone de construction de la phrase]                    │
│                                                         │
│  [Word Bank - Mots disponibles]                        │
│                                                         │
│  [🔥 CAST SPELL 🔥]                                     │
└─────────────────────────────────────────────────────────┘
```

## 🧪 Tests Effectués

### Tests d'architecture
✅ Initialisation du jeu
✅ Injection/suppression du CSS unique
✅ Système de DPS avec multiplicateurs de temps
✅ Alternance RED → BLUE → RED
✅ Incrémentation des rounds (cycle complet)
✅ Condition de victoire (10 rounds OU boss vaincu)
✅ Écran de victoire avec équipe gagnante
✅ Désactivation des attaques du boss
✅ Syntaxe JavaScript valide

### Tests spam-click (enfants) 🧒
✅ Cast button réactivé après succès
✅ Cast button réactivé après échec
✅ Protection double-click sur "Play Again"
✅ Protection double-click sur "Exit Victory"
✅ Protection spam-click sur "Exit" en jeu
✅ Word tiles idempotent (toggle safe)
✅ Spell cards remplacement safe

## 🚀 Comment Utiliser

### Test Standalone
```
http://localhost:8080/test-team-wizard.html
```

### Intégration dans l'Application
Le jeu s'intègre automatiquement via le système de modules :
- Fichier : `src/games/TeamWizardBattle.js`
- Module : `TeamWizardBattle`
- Game ID : `team-wizard-battle`

### Dépendances
- `eventBus` : Pour la communication inter-modules
- `content` : Doit contenir au minimum 12 phrases avec `english` et `chinese`

## 📊 Statistiques de Développement

- **Temps de développement** : ~1h45
- **Lignes de code** : 2828 lignes
- **Basé sur** : WizardSpellCaster.js (code prouvé et stable)
- **Bugs trouvés et corrigés** : 7 (dont 1 critique game-breaking !)
- **Tests effectués** : 16 (9 architecture + 7 spam-click)

## 🎓 Pour la Présentation Parents

### Points à souligner :
1. **Oral English naturel** - Les enfants crient spontanément en anglais
2. **Collaboration active** - Pas un élève seul, toute l'équipe participe
3. **Compétition saine** - Red vs Blue crée de l'engagement
4. **Gamification éducative** - Apprendre en s'amusant
5. **Vitesse de pensée** - Bonus pour la rapidité encourage la fluidité

### Scénario de démonstration :
1. Diviser la classe en 2 équipes (ou élèves vs parents !)
2. Premier élève de RED au tableau
3. Question apparaît en chinois
4. **L'équipe RED crie les mots** pendant que l'élève clique
5. Feedback immédiat avec le DPS gagné
6. Tour de BLUE
7. Répéter jusqu'à la victoire d'une équipe

## 🔧 Maintenance Future

### Améliorations possibles :
- [ ] Ajout de power-ups spéciaux d'équipe
- [ ] Système de combos pour réponses consécutives rapides
- [ ] Leaderboard des meilleures équipes
- [ ] Choix de difficulté (Easy/Normal/Hard boss HP)
- [ ] Sons d'équipe (acclamations, etc.)

### Code à surveiller :
- `_switchTeam()` : Logique d'alternance
- `_castSpell()` : Calcul DPS avec multiplicateurs
- `_handleVictory()` : Détermination de l'équipe gagnante

---

**Créé le** : 2025-11-02
**Version** : 1.0.0
**Status** : ✅ Production Ready (1h30 avant la présentation !)
