Overview

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 draws your own panels and markers on the game screen, UI & input makes the buttons you draw clickable and your hotkeys work, the JASS channel calls the game’s 1291 functions from outside, and in RPG maps you can bring along an AI companion. A finished AI can be packaged as a scheme to switch to with one click, or export and share; a whole new set of gameplay can be written as a gameplay mod.

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

Pick your path

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

What’s in the repository

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