Schémas d’IA

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 ».

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.

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

{
  "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 (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 (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 :

# 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)

{"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) :

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.

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.