# War3AI / OpenWar3

> Interface ouverte de Warcraft III 1.27 pour les agents IA : un runtime injecté pousse toutes les 50 ms l’état complet de la carte et le flux d’événements ; un programme externe envoie des commandes sémantiques appliquées en environ une frame, chacune avec un accusé de réception et un code de raison. Le SDK Python (openwar3) décrit tout avec les noms du jeu (codes à quatre caractères, noms d’ordre des sorts).

Le chemin le plus court pour écrire un Bot : lire « Les quinze règles » + les interfaces de api.json, hériter de openwar3.Bot, implémenter on_start(g) / on_tick(g) / on_event(g, ev) ; n’utiliser que les méthodes présentes dans api.json.
Toute la documentation dans un seul fichier : https://war3ai.com/fr/llms-full.txt

## Démarrer

- [Vue d’ensemble](https://war3ai.com/fr/docs/index.md): Documentation d’OpenWar3 : ce que c’est, ce qu’elle permet ; démarrage rapide, premier Bot, faire écrire l’IA par un LLM, API et protocole, passerelle et MCP — par quelle page commencer selon votre situation.
- [Démarrage rapide](https://war3ai.com/fr/docs/quickstart.md): Double-cliquez sur start.bat pour tout installer automatiquement, réglez le dossier du jeu dans Farsight, puis lancez une partie et regardez le Bot d'exemple prendre la main. Environ 15 minutes.
- [Votre premier Bot](https://war3ai.com/fr/docs/first-bot.md): Partez d'un Bot minimal de 10 lignes, ajoutez la production de paysans, la nourriture, l'armée, le héros et l'attaque, puis apprenez à lire les reçus.

## Faire écrire un Bot par l’IA

- [Écrire un Bot avec un LLM](https://war3ai.com/fr/docs/ai-bot.md): Pas besoin de savoir programmer : vous expliquez clairement comment il doit jouer, le LLM écrit le code. Copiez le modèle de prompt, décrivez votre stratégie, lancez-le, puis demandez des corrections.
- [Itération autonome d'un agent](https://war3ai.com/fr/docs/agent-loop.md): Laissez un agent de code jouer ses propres parties, lire les résultats, corriger le code et recommencer : il lui faut une commande qui tourne sans surveillance, un rapport de partie structuré et un objectif clair.
- [Un LLM comme conseiller stratégique](https://war3ai.com/fr/docs/llm-coach.md): Confiez à un LLM les questions « que faut-il économiser, où affecter les ouvriers, faut-il attaquer ou temporiser cette minute », et laissez la couche de règles se contenter d'exécuter et d'opposer son veto. Le cerveau de référence fonctionne déjà ainsi ; cette page en explique le modèle et les pièges.
- [Un LLM appelle directement des outils (MCP)](https://war3ai.com/fr/docs/mcp.md): tools/war3_mcp.py est un serveur MCP. Branchez-le sur Claude Code, Claude Desktop ou n’importe quel client compatible MCP : le LLM peut alors observer directement la partie, donner des ordres, parler au joueur à l’écran, lui poser des questions avec des cartes et prendre des captures d’écran, sans écrire de code au préalable.

## Concepts clés

- [Modèle mental](https://war3ai.com/fr/docs/concepts.md): Instantané, commande, reçu, événement, tick, lot. Comprenez ces six concepts et vous comprendrez pourquoi l'API a cette forme, et comment écrire du code rapide.
- [Les quinze règles](https://war3ai.com/fr/docs/rules.md): Chacune a été apprise dans de vraies parties. Relisez-les en écrivant un Bot : vous économiserez l’essentiel du temps de débogage.
- [Mode équitable](https://war3ai.com/fr/docs/fair-mode.md): Un client injecté dans le jeu peut lire toute la carte. Le mode équitable ne montre au Bot que ce qui se trouve dans son champ de vision — comme pour un joueur humain, et comme le veut la règle de l’arène.

## Guides

- [Recettes des joueurs pros](https://war3ai.com/fr/docs/cookbook.md): L'avantage des meilleurs joueurs tient surtout à des dizaines de « petites habitudes ». Cette page traduit une à une les techniques pro courantes en code SDK ; chaque extrait peut être copié tel quel dans on_tick.
- [Bots d’exemple](https://war3ai.com/fr/docs/examples.md): Quatre exemples, du plus simple au plus complet, tous exécutables tels quels ; chaque bloc de logique correspond à une capacité du SDK. S’y ajoute un cerveau de référence complet.
- [Débogage et performances](https://war3ai.com/fr/docs/debugging.md): Pourquoi un tick est lent, pourquoi une commande reste sans effet, pourquoi le jeu ne bouge pas. Diagnostiquez à partir du symptôme, puis confirmez avec les scripts de vérification en jeu fournis.

## Extensions de jeu

- [Compagnon RPG](https://war3ai.com/fr/docs/companion.md): Donnez au joueur un compagnon IA dans les cartes RPG et personnalisées : il vous suit, combat à vos côtés, vous soigne quand votre vie est basse et vous fait la conversation. Quatre modes ; héritez d’une classe, changez quelques attributs, et vous avez votre propre compagnon.
- [Canevas](https://war3ai.com/fr/docs/canvas.md): Dessinez sur l’écran du jeu des zones de texte, des panneaux, des barres de progression, des images, des cercles plaqués au sol et des tracés fléchés. Le runtime les dessine lui-même à chaque frame, sans modifier l’état du jeu : sans risque en multijoueur. Depuis Python, en HTTP ou en écrivant directement dans la mémoire partagée.
- [Interface et entrées](https://war3ai.com/fr/docs/ui-input.md): Les boutons et cartes de choix du canevas sont cliquables et s’illuminent automatiquement au survol ; enregistrez des raccourcis clavier, choisissez une position d’un clic au sol, lisez ce que pointe la souris et sachez ce que le joueur local a sélectionné. Clics, raccourcis clavier, sorts lancés, texte intégral du chat et départs de joueurs : tout arrive dans le flux d’événements.
- [Canal JASS](https://war3ai.com/fr/docs/jass.md): Les 1291 fonctions JASS dont disposent les créateurs de cartes s’appellent désormais par leur nom depuis l’extérieur du jeu : créer des unités, modifier des attributs, effets, panneaux, boîtes de dialogue, sons, caméra, brouillard… Quatre usages : console Farsight, ligne de commande, HTTP, Python.
- [Mods de jeu](https://war3ai.com/fr/docs/mods.md): Un schéma n’est pas forcément une IA qui joue à votre place : ce peut aussi être un ensemble de règles. Vous jouez vous-même dans la fenêtre du jeu ; le mod prépare le début de partie, fait apparaître les monstres, distribue les récompenses, vous présente boutons et cartes de choix à l’écran et décide de l’issue. Héritez de openwar3.Mod : un fichier, un gameplay complet.

## Outils

- [Console Farsight](https://war3ai.com/fr/docs/console.md): Console web locale et point d’entrée unique : régler le dossier du jeu, démarrer et arrêter les services comme les instances du jeu, régler la partie suivante, voir ce que pense l’IA, donner des ordres manuels, réalisation, historique des parties.
- [Schémas d’IA](https://war3ai.com/fr/docs/schemes.md): 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.
- [Bulles de dialogue et modèles locaux](https://war3ai.com/fr/docs/speech.md): Faites parler n’importe quelle unité du jeu, sous n’importe quelle identité, dans une bulle au-dessus de sa tête. Branchez un LLM local : une phrase entre, une réponse s’affiche au-dessus de l’unité.
- [Passerelle](https://war3ai.com/fr/docs/gateway.md): Passerelle WebSocket / JSON : les interfaces publiques que le SDK Python peut appeler le sont aussi depuis JS, C#, Go, Rust, une page web ou un programme sur une autre machine. Trois rôles, un client JS et une page de démonstration dans le navigateur fournis ; la latence est celle de la voie rapide, plus environ 1 ms.

## Référence

- [Protocole W3P](https://war3ai.com/fr/docs/protocol.md): L'intégralité du contrat entre le runtime et les programmes externes : huit blocs de mémoire partagée, lecture de l'état du monde, lecture des événements, envoi de commandes, reçus, rôles des voies, canevas, interface et entrées. Lisez cette page si vous vous connectez depuis un autre langage que Python.
- [Accusés de réception et codes de raison](https://war3ai.com/fr/docs/reason-codes.md): Chaque accusé de réception de commande porte un code d’état et un code de raison. C’est sur eux que les Bots et les agents s’appuient pour se corriger : le « pourquoi ça n’a pas marché » devient un nombre lisible par une machine.
- [D’où viennent les données](https://war3ai.com/fr/docs/data-sources.md): L’origine et la précision de chaque type de données. Quand quelque chose « semble faux », commencez par cette page.

## Divers

- [Questions fréquentes](https://war3ai.com/fr/docs/faq.md): Est-ce un logiciel de triche ? Quelles versions sont prises en charge ? Que peut voir et faire l’IA ? Peut-on s’en servir sans savoir programmer ?…
- [Limites d’utilisation](https://war3ai.com/fr/docs/legal.md): Ce qui est permis, ce qui ne l’est pas, les statistiques de visite de ce site, et les mentions relatives aux marques et aux licences tierces. En utilisant ce projet, vous acceptez de respecter ces limites.

## API

- [api.json](https://war3ai.com/fr/api.json): Les 103 méthodes de Game (name / category / status / latency / mechanism / signature / doc), générées depuis le code
- [Catalogue de l’API (web)](https://war3ai.com/fr/api/): Version consultable des mêmes données

## Optionnel

- [llms-full.txt](https://war3ai.com/fr/llms-full.txt): Toute la documentation + le catalogue de l’API, en une seule lecture
- [Limites d’utilisation](https://war3ai.com/fr/docs/legal.md): Uniquement avec un client que vous possédez légalement ; interdit sur Battle.net et sur tout serveur doté d’un anti-triche