# War3AI / OpenWar3

> An open API for Warcraft III 1.27, built for AI agents. An injected runtime pushes the complete state of the entire map and an event stream every 50 ms; external programs issue semantic commands in about one frame, and every command returns a receipt and a reason code. The Python SDK (openwar3) describes everything with the game's own names (four-character codes, ability order strings).

Shortest path to a bot: read "Fifteen rules" + the APIs in api.json, subclass openwar3.Bot, and implement on_start(g) / on_tick(g) / on_event(g, ev). Use only methods that exist in api.json.
All docs in one file: https://war3ai.com/en/llms-full.txt

## Get started

- [Overview](https://war3ai.com/en/docs/index.md): OpenWar3 docs: what it is, what it can do; quickstart, your first bot, write a bot with an LLM, API and protocol, gateway and MCP — and which page to start with for your situation.
- [Quickstart](https://war3ai.com/en/docs/quickstart.md): Double-click start.bat to install everything, set your game folder in Farsight, and start a game to watch an example Bot take over. About 15 minutes.
- [Your First Bot](https://war3ai.com/en/docs/first-bot.md): Start with a 10-line minimal Bot, then add training peasants, building for food, producing an army, heroes and attacking — and finally learn to read receipts.

## Let AI write your bot

- [Write a Bot with an LLM](https://war3ai.com/en/docs/ai-bot.md): No coding required: you explain how you want it to play, and the LLM writes the code. Copy the prompt template, describe your strategy, run it, then have the model revise it.
- [Agent Self-Iteration](https://war3ai.com/en/docs/agent-loop.md): Let a coding agent play games, read the results, change the code and play again on its own. It needs a command that runs unattended, a structured game report, and a clear goal.
- [LLM as Strategy Coach](https://war3ai.com/en/docs/llm-coach.md): Hand "what to save for, where to put workers, attack or hold this minute" to an LLM, and let the rule layer only execute and veto. The reference brain already works this way; this page explains the pattern and the pitfalls.
- [LLM calls tools directly (MCP)](https://war3ai.com/en/docs/mcp.md): tools/war3_mcp.py is an MCP server. Hook it up to Claude Code, Claude Desktop or any MCP-capable client, and the LLM can read the game, issue commands, talk to the player on screen, ask the player with pop-up cards and look at screenshots — no code to write first.

## Core concepts

- [Mental Model](https://war3ai.com/en/docs/concepts.md): Snapshots, commands, receipts, events, ticks and batches. Understand these six concepts and you'll understand why the API looks the way it does, and how to write fast code.
- [Fifteen rules](https://war3ai.com/en/docs/rules.md): Every one was learned the hard way in real games. Check your bot against them and you'll skip most of your debugging.
- [Fair mode](https://war3ai.com/en/docs/fair-mode.md): A client injected into the game can read the whole map. Fair mode limits your bot to what's within its vision, just like a human player and just like the Arena rules.

## Guides

- [Pro Playbook Cookbook](https://war3ai.com/en/docs/cookbook.md): Most of a top player's edge comes from dozens of small habits. This page maps common pro techniques, one by one, onto SDK code — every snippet can be pasted straight into on_tick.
- [Example bots](https://war3ai.com/en/docs/examples.md): Four examples, from simple to complex. Each one runs as-is, and every piece of logic maps to an SDK capability. Plus a complete reference brain.
- [Debugging and performance](https://war3ai.com/en/docs/debugging.md): Why a tick is slow, why a command didn't take effect, why the game isn't moving. Troubleshoot by symptom, then confirm with the bundled live verification scripts.

## Gameplay extensions

- [RPG companion](https://war3ai.com/en/docs/companion.md): Give the player an AI companion in RPG and custom maps that follows you, helps you fight, heals you when you're low, and chats with you. Four modes; subclass one class and change a few attributes to make it your own.
- [Canvas](https://war3ai.com/en/docs/canvas.md): Draw text boxes, panels, progress bars, images, circles that hug the ground and routes with arrows on the game screen. The runtime draws them itself every frame without changing game state, so it's safe in multiplayer games; use it from Python, over HTTP, or by writing shared memory directly.
- [UI & input](https://war3ai.com/en/docs/ui-input.md): Buttons and choice cards on the canvas are clickable and highlight automatically on hover; register hotkeys, pick a position by clicking the ground, read what the mouse is pointing at, and know who the local player has selected. Clicks, hotkeys, spell casts, full chat text and players leaving all go into the event stream.
- [JASS channel](https://war3ai.com/en/docs/jass.md): The 1291 JASS functions available to map makers can now be called by name from outside the game: create units, change properties, effects, boards, dialogs, sound, camera, fog… Four ways to use it: the Farsight console, the command line, HTTP and Python.
- [Gameplay mods](https://war3ai.com/en/docs/mods.md): A scheme doesn't have to be an AI that plays for you — it can also be a set of rules. You play in the game window yourself, and the mod sets up the start, spawns enemies, hands out rewards, gives you buttons and choice cards on screen, and decides who wins. Subclass openwar3.Mod, and one file is a whole game mode.

## Tools

- [Farsight console](https://war3ai.com/en/docs/console.md): A local web console and the single entry point: set the game folder, start and stop services and game instances, set up the next game, see what the AI is thinking, issue manual commands, direct the camera, and review match history.
- [AI schemes](https://war3ai.com/en/docs/schemes.md): A scheme is a complete AI. Switch with one click in Farsight — even the game in progress can be taken over right away. Export a zip to share with others, import other people's schemes to test them, and every scheme's results are tracked automatically.
- [Speech bubbles and local models](https://war3ai.com/en/docs/speech.md): Pop up a speech bubble over any unit in the game, speaking as any character. Hook up a local LLM, and one line goes in while the reply appears over the unit's head.
- [Gateway](https://war3ai.com/en/docs/gateway.md): A WebSocket / JSON gateway: the public APIs the Python SDK can call are callable from JS, C#, Go, Rust, browser pages and programs on another machine. Three roles, with a bundled JS client and browser demo page; latency is the fast lane plus about 1 ms.

## Reference

- [W3P Protocol](https://war3ai.com/en/docs/protocol.md): The complete contract between the runtime and external programs: eight shared memory blocks, reading world state, reading events, issuing commands, receipts, lane roles, the canvas, and UI & input. Read this page if you're integrating from a language other than Python.
- [Receipts and reason codes](https://war3ai.com/en/docs/reason-codes.md): Every command's receipt carries a status code and a reason code. They're how bots and agents correct themselves, turning “why didn't it work?” into a machine-readable number.
- [Data sources](https://war3ai.com/en/docs/data-sources.md): Where each kind of data comes from and how precise it is. When something looks wrong, check this page first.

## Other

- [FAQ](https://war3ai.com/en/docs/faq.md): Is this a cheat? Which versions are supported? What can the AI see and do? Can I use it without programming?…
- [Terms of use](https://war3ai.com/en/docs/legal.md): What you can and can't do, analytics on this website, and trademark and third-party license notices. By using this project, you agree to stay within these terms.

## API

- [api.json](https://war3ai.com/en/api.json): All 103 Game methods (name / category / status / latency / mechanism / signature / doc), generated from code
- [API catalog (web)](https://war3ai.com/en/api/): Searchable version of the same data

## Optional

- [llms-full.txt](https://war3ai.com/en/llms-full.txt): All docs + the API catalog, in a single read
- [Terms of use](https://war3ai.com/en/docs/legal.md): Only for clients you legally own; must not be used on Battle.net or any server with anti-cheat