Quickstart - War3AI

What you need

	Requirement	Notes
OS	Windows 10 / 11, 64-bit	Only Windows is supported for now
Game	Warcraft III 1.27a (The Frozen Throne, `Game.dll` 1.27.0.52240)	A client you legally own; no game files on disk are modified

Nothing else needs to be installed first. start.bat downloads exactly one thing: Python 3.13 (the official portable package, about 14 MB), into the repository’s bin\env\: no administrator rights, no changes to the system PATH, and it switches to mirrors automatically on networks in mainland China. If your computer already has a working copy of Python, it uses that. PowerShell is the copy built into Windows; Farsight’s web UI ships pre-built with the repository, so Node.js isn’t needed.

Installation

Get the code
```
git clone https://github.com/OPENXXAI/OpenWar3AI.git
```
Or download the zip and extract it. The runtime (the injection DLL and the launcher) ships with the repository; no separate download needed.
Double-click start.bat

The first time, it will:
- Download Python 3.13;
- Install the Python packages, and check and install the runtime files;
- Download AMAI and generate the strategy data the reference brain needs (AMAI has a custom license, so the generated files are not committed to git; a failure here only affects the reference brain);
- Open Farsight’s home page, Control Center, at http://127.0.0.1:8866.
Every step prints its result, and a step that fails tells you how to fix it. After that, each double-click just runs a check of a second or two and opens Farsight.

The black window closes by itself after a few seconds: Farsight keeps running in the background, and closing the browser doesn’t stop it.
Set the game folder in Control Center

At the top of Control Center, use Find automatically, or Browse… to pick your Warcraft III folder yourself. Farsight checks the game version and extracts data from your own copy of the game (unit table, abilities, items, counter table… Blizzard’s files are not distributed with the code).

If the version isn’t 1.27a, it warns you. Maps and the next game’s settings are relative to this folder (maps in any folder under <game folder>\Maps can be picked); to change the folder later, use the Settings page.
Start a game and let the example Bot take over

The easiest way is Farsight’s Instances & Setup page: tick an instance number, pick an AI scheme and click Start test. You can also use the command line:
```
python tools/play.py --bot brains/examples/hello_bot.py
```
This command starts a game instance, injects the runtime, starts the game automatically, and then launches the Bot. Once you see peasants heading to mine and the hall starting to train peasants, it works.

The python in the command is the one recorded in openwar3.json; the one start.bat installed itself is at bin\env\python\python.exe.

start.bat and stop.bat

start.bat              # deployment check + open Farsight
start.bat setup        # full check: reinstall Python packages, retry AMAI
start.bat restart      # restart only the Farsight backend (games and services are unaffected)
start.bat node         # also installs a copy of Node.js (only needed for previewing the website; not needed otherwise)
start.bat 5 6          # also start tests on instances 5 and 6 (game + reference brain)
stop.bat               # stop everything completely; stop.bat --keep-llm keeps the local model in VRAM

The gateway, speech bubbles and the local LLM are also started and stopped from Farsight’s Control Center, so there are no other scripts to hunt down. To stop everything completely, double-click stop.bat, or click Stop all in the top-right corner of Control Center: game instances, AIs, the gateway, bubbles, the local model this system uses and the Farsight backend all stop in turn. The MCP server is managed by clients such as Claude and is not stopped.

Config file

openwar3.json is written automatically by start.bat and Farsight; it stores only local paths and is not committed to git. To change ports or the local LLM’s address and model name, follow openwar3.example.json and include only the entries that differ from it.

play.py options

python tools/play.py --bot my_bot.py --inst 9 --race 2 --enemy-race 1 --difficulty 3 --speed 200
python tools/play.py --bot my_bot.py --inst 9 --attach      # the game is already running; only attach the Bot
python tools/play.py --bot my_bot.py --fair                 # fair mode: can only see what's in vision

Option	Default	Description
`--bot`	Required	Path to the Bot file (the file must contain a subclass of `Bot`)
`--inst`	`9`	Instance number. Don’t reuse the number of an instance that’s already running (Farsight’s Instances & Setup page shows which numbers are in use)
`--race`	`1`	Our race: 1 Human, 2 Orc, 3 Undead, 4 Night Elf
`--enemy-race`	`0`	Opponent’s race
`--difficulty`	`2`	Computer opponent difficulty: 2 Easy, 3 Normal, 4 Insane
`--speed`	`100`	Game speed (percent, 200 = 2×)
`--map`	`default_map` from the config	Map
`--attach`		Don’t start a game; only attach to an instance that’s already running
`--hz`	`5`	How many times per second `on_tick` is called
`--minutes`	`60`	Maximum run time in minutes (wall clock)
`--fair`		Fair mode
`--player`		Which player number to command as (for AI vs. AI)

Don’t start the game with --minimize: the game simulation stops while the window is minimized (the clock doesn’t move), and the Bot will wait forever for the game to start.

You can also skip play.py and use the SDK’s command line to attach directly to an instance that’s already running:

python -m openwar3 run brains/examples/hello_bot.py --inst 5     # run a Bot
python -m openwar3 status --inst 5                              # connect and print snapshot / fast lane status
python -m openwar3 catalog                                      # print the API reference

Once it’s running

Write your first Bot Start with a 10-line minimal Bot and add training units and attacks step by step. Let an LLM write it for you Copy the prompt template and describe your strategy in plain words.

Self-check

python tools/run_tests.py          # SDK / reference brain / reflex layer / console / speech bubbles / examples, one subprocess per suite

Offline tests don’t require the game to be running. Farsight’s Control Center also has an Environment check that shows whether each part is installed.