# Schémas d’IA

> Un schéma est une IA complète. Changez-en en un clic dans Farsight, y compris pour reprendre sur-le-champ la partie en cours ; exportez-le en zip pour le partager, importez celui d’un autre pour le tester ; le bilan de chaque schéma est compilé automatiquement.

Source: https://war3ai.com/fr/docs/schemes/

Un **schéma** = une IA complète : un dossier + un manifeste `scheme.json` + du code. Chaque instance du jeu utilise un schéma ; dans Farsight, on en change en un clic, et **la partie en cours peut être reprise immédiatement par le nouveau schéma**.

Les schémas partagés par d’autres sont importés dans **un espace à part**, sans interférer avec les vôtres ; pour en modifier un, utilisez « Copier dans mes schémas ».

```text
schemes/
  mine/<id>/          Mes schémas : écrits par vous, ou copiés d'un autre schéma pour être modifiés (modifiables à volonté, effet à la partie suivante)
  installed/<id>/     Installés : les zip partagés par d'autres sont décompressés ici (confiance à confirmer avant la première exécution)
brains/xwar3/         Intégré : cerveau de référence (IA complète)
brains/examples/      Intégrés : quatre exemples pédagogiques hello / rush / macro / micro, l'exemple de compagnon buddy, deux mods de jeu (Roguelike de héros, Défense sans fin)
```

Un schéma n’est pas forcément une IA qui joue à votre place : un schéma `kind: mod` est un ensemble de **règles de jeu** — vous jouez vous-même, il vous lance les défis. Voir [Mods de jeu](https://war3ai.com/fr/docs/mods/).

## Dans Farsight

Page « Schémas d’IA » (barre latérale « Système → Schémas d’IA ») :

| Action | Effet |
|---|---|
| Importer un schéma (zip) | L’installe dans `installed/` ; si le même id est déjà installé, demande s’il faut le remplacer (après remplacement, la confiance doit être redonnée) |
| Appliquer à une instance… | Choisir l’instance + « Effet immédiat » (arrête l’IA actuelle, le nouveau schéma reprend la partie en cours) ou « Effet au prochain lancement du test » |
| Copier dans mes schémas | En fait une copie dans `mine/`, avec « moi » pour auteur et la version 0.1.0, en notant de quel schéma et de quelle version elle provient |
| Exporter en zip | Crée `<id>-<version>.zip` : l’envoyer à quelqu’un, c’est le partager |
| Ouvrir le dossier | Ouvre le dossier du schéma dans l’Explorateur de fichiers, pour modifier directement le code |
| Faire confiance | Obligatoire avant la première exécution d’un schéma d’autrui (voir « Confiance et sécurité » plus bas) |
| Bilan récent | Victoire ou défaite, durée et cause de fin de chaque partie de ce schéma |
| Supprimer | Uniquement pour « Mes schémas » et « Installés » ; impossible si une instance l’utilise |

La fiche de chaque instance comporte aussi une ligne « Schéma d’IA » : choisissez le schéma dans la liste → « Changer (effet immédiat) ». Quand l’instance ne tourne pas, le bouton s’appelle « Sélectionner », et le prochain « Lancer le test » démarrera l’IA avec ce schéma.

## Le manifeste scheme.json

```json
{
  "format": 1,
  "id": "fast-rush",
  "name": "Rush en trois minutes",
  "version": "1.2.0",
  "author": "Untel",
  "description": "Une phrase qui résume le style de jeu de cette IA",
  "entry": "rush_bot.py",
  "class": "RushBot",
  "fair": true,
  "hz": 5,
  "races": ["human", "orc"],
  "license": "MIT"
}
```

| Champ | Obligatoire | Description |
|---|---|---|
| `id` | ✔ | Lettres minuscules, chiffres, `-`, `_`, de 2 à 41 caractères |
| `entry` | ✔ | Un fichier `.py` du dossier du schéma (pas de chemin absolu, pas de `..`) |
| `kind` | | `bot` par défaut (sous-classe de `openwar3.Bot`, joue à votre place) ; `mod` = [mod de jeu](https://war3ai.com/fr/docs/mods/) (sous-classe de `openwar3.Mod`, jamais en mode équitable, issue jamais jugée selon les règles de mêlée) |
| `class` | | Nom de la sous-classe de Bot (ou de Mod) dans le fichier d’entrée ; à défaut, la dernière sous-classe de `openwar3.Bot` du fichier d’entrée est utilisée |
| `fair` | | `true` par défaut : ne voit que ce qui est dans le champ de vision, même règle que sur l’Arène. `false` = toute la carte visible, et c’est aussi la seule façon d’utiliser le [canal JASS](https://war3ai.com/fr/docs/jass/) (nécessaire aux compagnons) |
| `judge` | | `true` par défaut : la partie est jugée selon les règles de mêlée. Les schémas RPG / compagnon mettent `false` |
| `hz` | | Nombre d’appels à `on_tick` par seconde, 5 par défaut |
| `format` | | Version du format du manifeste, actuellement 1 ; un format plus récent que votre OpenWar3 est refusé, avec une invitation à mettre à jour |
| Autres | | `name`, `version`, `author`, `description`, `races`, `license`, `homepage`, `forked_from` ne servent qu’à l’affichage |

Le dossier du schéma est ajouté au chemin de recherche des modules Python : le fichier d’entrée peut importer (`import`) les autres fichiers du même dossier. Les paquets tiers (numpy, torch…) ne sont pas installés automatiquement — indiquez clairement dans `description` ce qui est nécessaire.

**Le plus petit schéma tient en deux fichiers** :

```python
# my_bot.py
from openwar3 import Bot

class MyBot(Bot):
    def on_tick(self, g):
        for w in g.idle_workers():
            mine = g.nearest(g.gold_mines(), w)
            if mine:
                g.gather(w, mine)
```

```json
{"id": "my-first", "name": "Ma première IA", "entry": "my_bot.py"}
```

Placez-les dans `schemes/mine/my-first/`, rafraîchissez Farsight et le schéma apparaît. Point de départ encore plus simple : choisissez un exemple dans « Intégrés » et cliquez sur « Copier dans mes schémas ».

## Exécution et bilan

Les schémas sont exécutés par l’**exécuteur de schémas** (c’est lui que démarrent « Lancer le test / Changer » dans Farsight) :

```bash
python tools/run_scheme.py --inst 20 --scheme builtin/micro --hours 6
```

- Chaque instance a un processus superviseur permanent, qui **lance un sous-processus à chaque partie** pour exécuter le schéma : si le code du schéma plante, le superviseur n’est pas entraîné dans sa chute ; si vous modifiez le code d’un de « Mes schémas », la partie suivante utilise automatiquement la nouvelle version.
- À la fin de chaque partie, une ligne de bilan est enregistrée : schéma, version, auteur, issue, cause, durée de jeu, nombre d’erreurs. Les taux de victoire affichés dans Farsight sont calculés à partir de là.

Comment l’issue est déterminée :

| Situation | Résultat enregistré |
|---|---|
| Tous les bâtiments adverses sont détruits | Victoire |
| Tous nos bâtiments sont détruits (même s’il reste des troupes — c’est ainsi qu’une partie de mêlée juge la défaite) | Défaite |
| Toutes nos unités sont détruites | Défaite |
| Fin / arrêt manuel depuis Farsight | Indéterminé |
| Lors du changement, la partie durait déjà depuis plus de 60 secondes de jeu (reprise en cours de route) | Compté à part, **exclu du taux de victoire** |
| L’horloge du jeu reste longtemps bloquée | Indéterminé |

Une fois l’issue connue, l’exécuteur ferme l’écran des scores, lance la partie suivante selon les « Réglages de la partie suivante », et le schéma reprend la main — vous pouvez le laisser tourner toute la nuit pour accumuler un bilan. Une pause n’est pas une fin : pendant la pause, le Bot continue de tourner normalement, seule l’horloge du jeu s’arrête.

## Confiance et sécurité

**Un schéma, c’est du code, qui s’exécute avec exactement les mêmes droits que vous** (il peut lire et écrire des fichiers, accéder au réseau). Par conséquent :

- les schémas de `installed/` ne sont **pas de confiance** par défaut : Farsight et l’exécuteur refusent de les lancer tant que vous n’avez pas cliqué sur « Faire confiance » ;
- remplacer l’installation d’un schéma de même id **réinitialise la confiance** (nouvelle version = nouveau code) ;
- l’import vérifie : zip de 50 MB au plus, 2000 fichiers au plus ; ni chemin absolu ni `..` (pour empêcher toute écriture hors du dossier du schéma) ; un manifeste invalide ou un fichier d’entrée absent entraîne un refus immédiat.

> **Attention**
>
> Avant de faire confiance, cliquez sur « Ouvrir le dossier » et lisez le code. Ne prenez de schémas qu’auprès de personnes en qui vous avez confiance.

## API (pour les scripts)

| Interface | Description |
|---|---|
| `GET /api/schemes` | Liste des schémas + bilans + schéma choisi et schéma en cours d’exécution pour chaque instance |
| `GET /api/schemes/results?ref=` | Les 30 dernières parties d’un schéma |
| `POST /api/schemes/import` | Importer un zip |
| `GET /api/schemes/export?ref=` | Télécharger le zip |
| `POST /api/schemes/fork` | Copier dans mes schémas |
| `POST /api/schemes/trust` | Faire confiance |
| `DELETE /api/schemes?ref=` | Supprimer (refusé si une instance l’utilise) |
| `POST /api/instances/{n}/scheme` | Changer le schéma d’une instance : reprise immédiate de la partie en cours, ou effet au prochain lancement du test |

En Python, utilisez directement la bibliothèque : `from openwar3 import schemes` (`list_schemes`, `install_zip`, `export_zip`, `fork`, `trust`, `stats`…).

## À venir : le site de schémas

Le zip exporté est l’unité de partage ; le site n’a qu’à ajouter une couche autour : envoi en un clic depuis Farsight ; téléchargement depuis le site, avec exactement les mêmes vérifications que « Importer un schéma » et la même confirmation de confiance ; envoi facultatif des bilans, le site agrégeant les taux de victoire par version. Le bouton « Partager sur le site de schémas » a déjà sa place réservée dans Farsight. Avancement : voir la [feuille de route](https://war3ai.com/fr/roadmap/).