# Quickstart

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

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

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

1. **Get the code**

   ```bash
   git clone https://github.com/OPENXXAI/OpenWar3AI.git
   ```

   Or [download the zip](https://github.com/OPENXXAI/OpenWar3AI/archive/refs/heads/main.zip) and extract it. The runtime (the injection DLL and the launcher) ships with the repository; no separate download needed.

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

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

4. **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:

   ```bash
   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

```bash
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

```bash
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](https://war3ai.com/en/docs/fair-mode/) |
| `--player` | | Which player number to command as (for AI vs. AI) |

> **Warning**
>
> 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:

```bash
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](https://war3ai.com/en/docs/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](https://war3ai.com/en/docs/ai-bot/): Copy the prompt template and describe your strategy in plain words.

## Self-check

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