# Overview

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

Source: https://war3ai.com/en/docs/

**OpenWar3** is War3AI's open interface layer: a runtime injected into Warcraft III 1.27, plus a Python SDK.

- Every **50 ms**, the runtime pushes the complete state of the entire map into shared memory: every player's resources and food; every unit's HP and mana, order, current target, ability cooldowns, buffs and inventory; items on the ground, trees, production queues, and time of day. There's also an **event stream**: units appearing and dying, every single hit of damage, production completing…
- External programs issue **semantic commands** with **about one frame** of latency: move, attack, gather, build, train, cast, learn skills, revive, use items, buy… Every command returns a **receipt** that says whether the engine accepted it and, if not, the reason code.
- You only say *what* to do: units by four-character code and abilities by order string, the same names the game uses. *How* it gets done is the runtime's job.

So an LLM needs no low-level knowledge and never has to look at the screen. Once it has read the docs, it can write a bot that runs an economy and fights, then revise it on its own from the receipts and events after it plays.

It's not just for matches: the [canvas](https://war3ai.com/en/docs/canvas/) draws your own panels and markers on the game screen, [UI & input](https://war3ai.com/en/docs/ui-input/) makes the buttons you draw clickable and your hotkeys work, the [JASS channel](https://war3ai.com/en/docs/jass/) calls the game's 1291 functions from outside, and in RPG maps you can bring along an [AI companion](https://war3ai.com/en/docs/companion/). A finished AI can be packaged as a [scheme](https://war3ai.com/en/docs/schemes/) to switch to with one click, or export and share; a whole new set of gameplay can be written as a [gameplay mod](https://war3ai.com/en/docs/mods/).

You can connect without writing Python, too: the [gateway](https://war3ai.com/en/docs/gateway/) lets any language or browser page call the same APIs over WebSocket / JSON, and the [MCP server](https://war3ai.com/en/docs/mcp/) lets agents such as Claude Code call tools directly to read the game and issue commands.

  - [Quickstart](https://war3ai.com/en/docs/quickstart/): Set up your environment, start a game with one command, and watch the example bot take over.
  - [Write a bot with an LLM](https://war3ai.com/en/docs/ai-bot/): No programming required: copy the prompt, describe your strategy, and hand it to an agent.
  - [Mental model](https://war3ai.com/en/docs/concepts/): Snapshots, commands, receipts, events, ticks. Spend five minutes here before you write a bot.
  - [API catalog](https://war3ai.com/en/api/): Every API, each labeled with its test status, latency tier and underlying mechanism.

## Pick your path

| You | Start here | Then |
|---|---|---|
| Play Warcraft, don't code | [Quickstart](https://war3ai.com/en/docs/quickstart/) → [Write a bot with an LLM](https://war3ai.com/en/docs/ai-bot/) | If you get stuck, see the [FAQ](https://war3ai.com/en/docs/faq/) |
| Know Python | [Your first bot](https://war3ai.com/en/docs/first-bot/) → [Mental model](https://war3ai.com/en/docs/concepts/) → [Fifteen rules](https://war3ai.com/en/docs/rules/) | [Pro strategy cookbook](https://war3ai.com/en/docs/cookbook/), [Example bots](https://war3ai.com/en/docs/examples/) |
| Build coding agents / automation | [Autonomous agent loop](https://war3ai.com/en/docs/agent-loop/) | [Receipts and reason codes](https://war3ai.com/en/docs/reason-codes/), [`llms-full.txt`](https://war3ai.com/en/llms-full.txt) |
| Want an LLM making in-game decisions | [LLM strategy coach](https://war3ai.com/en/docs/llm-coach/) | [Speech bubbles and local models](https://war3ai.com/en/docs/speech/) |
| Want an agent to operate the game directly (Claude Code, etc.) | [LLM calls tools directly (MCP)](https://war3ai.com/en/docs/mcp/) | [UI & input](https://war3ai.com/en/docs/ui-input/) |
| Use another language (JS, C#, Go, Rust…) | [Gateway](https://war3ai.com/en/docs/gateway/) | Lower level: [W3P protocol](https://war3ai.com/en/docs/protocol/) |
| Want AIs from different people to play each other | [Fair mode](https://war3ai.com/en/docs/fair-mode/) | [Arena](https://war3ai.com/en/arena/) |
| Want to build your own gameplay in RPG / custom maps | [Gameplay mods](https://war3ai.com/en/docs/mods/) | [UI & input](https://war3ai.com/en/docs/ui-input/), [Canvas](https://war3ai.com/en/docs/canvas/), [JASS channel](https://war3ai.com/en/docs/jass/), [RPG companion](https://war3ai.com/en/docs/companion/) |
| Want to share your AI with others | [AI schemes](https://war3ai.com/en/docs/schemes/) | [Farsight console](https://war3ai.com/en/docs/console/) |

## What's in the repository

```text
start.bat       The single entry point: deploys from scratch + opens Farsight; stop.bat stops everything
sdk/python/     Interface layer. openwar3/ is the public facade (Game + Bot); start here
brains/         Decision layer
  examples/       hello_bot (economy) → rush_bot (army) → macro_bot (macro) → micro_bot (micro + creeping); buddy (RPG companion);
                  mod_hero_roguelike / mod_endless_defense (gameplay mods)
  xwar3/          Reference brain: strategy layer (seconds) + reflex layer (4 processes) + win-rate model
console/        Farsight web console (FastAPI + React)
gateway/        Gateway (WebSocket / JSON) + JS client + browser demo page
director/       Auto camera, overhead health bars
speech/         Overhead chat bubbles + local LLM
runtime/        Multi-instance orchestration (each game restarts with your settings)
data/           order-ids.txt; tools to extract data from your own game
schemes/        Your AI schemes (mine/) and schemes shared by others (installed/); not checked into the repo
tools/          play.py (start a game with one command), run_scheme.py (scheme runner), war3_mcp.py (MCP server), run_tests.py, live verification scripts
docs/           API catalog api.json (generated from code), protocol, manual
```

The only thing between the runtime and your code is a versioned [W3P protocol](https://war3ai.com/en/docs/protocol/). The Python SDK is the easiest route, but any other language can connect by following the protocol.

## What an API's test status means

Every API in the catalog is labeled with one of three statuses:

- **Verified in live games**: the underlying path (action ID, argument shape, the effect read back) has been verified in real games and is guarded by a verification script.
- **Experimental**: a newly added API that already works on a test instance and is still being verified item by item in live games. You can use it, but API details may still change.
- **Inferred / not fully tested**: the underlying mechanism copies what the engine itself does (for example, the equivalent JASS function), but it hasn't been checked item by item in a game yet. Check the receipt before relying on it.

> **Note**
>
> Only **Warcraft III 1.27** (The Frozen Throne) is supported for now. Versions 1.24–1.28 share the same engine structure, and multi-version support is phase P4 of the [roadmap](https://war3ai.com/en/roadmap/). 1.29 and later, as well as Reforged, use a different engine and are out of scope.