<!-- file: docs/studies/007-GAME_AI_AND_BOT_EXECUTION_STUDY.md -->
<!-- version: 1 -->

# Étude des adversaires pilotés et bots

## Statut

Étude non normative pour `0.2.0-0-pre.3`.

## Objectif

Prévoir des adversaires contrôlés par le programme sans supposer qu'ils doivent être :

- du machine learning ;
- embarqués dans le client ;
- dépendants d'un provider externe ;
- spécifiques à une seule plateforme.

Le besoin générique est :

> produire une décision de joueur artificiel à partir d'un état de jeu autorisé.

## Familles de logique

### Règles simples

Exemples :

- réflexes basiques ;
- comportement scripté ;
- probabilités pondérées ;
- machine à états.

Adapté à :

- Snake simple ;
- ennemis d'arcade ;
- tutorial opponent ;
- bots de remplissage.

### Recherche / planification

Exemples :

- BFS/A* ;
- minimax ;
- alpha-beta ;
- MCTS ;
- heuristiques de navigation.

Adapté à :

- puzzles ;
- jeux de plateau ;
- certains jeux tactiques.

### Modèles entraînés

À réserver seulement lorsqu'un projet réel le justifie :

- modèle supervisé ;
- reinforcement learning ;
- réseau neuronal ;
- XGBoost/LightGBM pour décisions tabulaires.

Le framework de jeu ne doit pas dépendre d'un framework ML tant qu'aucun consommateur concret ne l'exige.

## Contrat conceptuel

Un bot pourrait consommer :

```text
GameObservation
BotContext
DifficultyProfile
DecisionBudget
```

et produire :

```text
SemanticAction
```

ou une séquence courte d'actions.

Le contrat exact n'est pas figé.

## Local vs serveur

### Bot local

Avantages :

- fonctionne offline ;
- latence faible ;
- pas de coût serveur.

Risques :

- logique visible/modifiable côté client ;
- comportement potentiellement différent selon version ;
- impossible d'en faire une autorité fiable pour compétition.

### Bot serveur

Avantages :

- comportement centralisé ;
- version contrôlée ;
- utile pour matchmaking/remplacement de joueurs ;
- peut partager la simulation authoritative.

Risques :

- coût CPU ;
- besoin réseau ;
- complexité de scaling.

## Règle d'ownership candidate

La stratégie de bot dépend du jeu ou d'un game-system spécialisé.

Le mécanisme d'exécution générique peut être réutilisable :

```text
game simulation
      ↓
observation
      ↓
bot strategy
      ↓
semantic action
```

Le bot ne doit pas appeler directement l'input physique ni modifier l'état interne par un chemin privilégié si un joueur humain passe par des semantic actions.

## Difficulté

La difficulté peut être obtenue par :

- profondeur de recherche ;
- délai de réaction ;
- précision ;
- bruit ;
- accès limité à l'information ;
- heuristique plus ou moins forte ;
- budget CPU/tick.

Éviter de tricher implicitement en donnant au bot des informations invisibles au joueur, sauf si le game design l'assume explicitement.

## Remplacement de joueur

Cas utile en multiplayer :

- joueur déconnecté ;
- lobby incomplet ;
- partie d'entraînement ;
- remplissage temporaire.

Le remplacement doit être une décision du jeu/session, pas une règle imposée par le moteur.

## Tests

Les bots peuvent aussi servir à :

- tests de longues parties ;
- fuzzing de gameplay ;
- génération de trajectoires ;
- tests de charge serveur ;
- validation de déterminisme.

Un bot de test peut être distinct d'un bot destiné au joueur final.

## Questions ouvertes

- faut-il une API générique `BotController` ou rester game-specific au début ?
- où stocker les profils de difficulté ?
- comment garantir le même comportement client/serveur si la logique est partagée ?
- quand extraire pathfinding/recherche vers des game-systems réutilisables ?
- comment versionner la stratégie d'un bot dans un match replayable ?