# Быстрый старт

> Дважды щёлкните start.bat — всё установится само; укажите папку игры в Farsight и запустите партию, чтобы посмотреть, как управление берёт пример бота. Около 15 минут.

Источник: https://war3ai.com/ru/docs/quickstart/

## Что понадобится

| | Требование | Пояснение |
|---|---|---|
| Система | Windows 10 / 11, 64-битная | Пока поддерживается только Windows |
| Игра | Warcraft III **1.27a** (The Frozen Throne, `Game.dll` 1.27.0.52240) | Ваш собственный легально приобретённый клиент; никакие файлы игры на диске не изменяются |

**Больше ничего заранее ставить не нужно.** `start.bat` скачивает только одно: Python 3.13 (официальный портативный пакет, около 14 МБ) — в папку `bin\env\` репозитория, права администратора не нужны, системный PATH не меняется, в китайских сетях автоматически выбираются зеркала; если на компьютере уже есть рабочий Python, используется он. PowerShell берётся тот, что уже есть в Windows; веб-интерфейс Farsight поставляется вместе с репозиторием уже собранным, Node.js не нужен.

## Установка

1. **Получите код**

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

   Или скачайте [архив](https://github.com/OPENXXAI/OpenWar3AI/archive/refs/heads/main.zip) и распакуйте его. Рантайм (внедряемая DLL и загрузчик) поставляется вместе с репозиторием, отдельно скачивать его не нужно.

2. **Дважды щёлкните `start.bat`**

   При первом запуске он сам:

   - скачает Python 3.13;
   - установит пакеты Python, проверит файлы рантайма и установит их;
   - скачает данные AMAI и сгенерирует из них стратегические данные для эталонного мозга (у AMAI собственная лицензия, сгенерированное в git не попадает; сбой затронет только эталонный мозг);
   - откроет главную страницу Farsight «Центр управления» `http://127.0.0.1:8866`.

   Результат каждого шага выводится на экран, а для неудавшегося шага скрипт подскажет, как это исправить. В дальнейшем каждый двойной щелчок — лишь проверка на одну-две секунды, после чего открывается Farsight.

   Чёрное окно через несколько секунд закроется само: Farsight продолжает работать в фоне и не остановится, даже если закрыть браузер.

3. **Укажите папку игры в «Центре управления»**

   В самом верху «Центра управления» можно нажать «Найти автоматически» или выбрать папку Warcraft III самостоятельно через «Обзор…». Farsight проверит версию игры и **извлечёт данные из вашей собственной копии игры** (таблицы юнитов, способности, предметы, таблица контр… файлы Blizzard вместе с кодом не распространяются).

   Если версия не 1.27a, вы увидите предупреждение. Карты и настройки следующего матча задаются относительно этой папки (можно выбрать карту из любой подпапки `<папка игры>\Maps`); сменить папку позже можно на странице «Настройки».

4. **Запустите партию и отдайте управление примеру бота**

   Проще всего — на странице Farsight «Экземпляры и запуск» отметить номер экземпляра, выбрать ИИ-схему и нажать «Начать тест». Можно и из командной строки:

   ```bash
   python tools/play.py --bot brains/examples/hello_bot.py
   ```

   Эта команда запускает экземпляр игры, внедряет рантайм, автоматически начинает партию и затем запускает бота. **Если крестьяне пошли на рудник, а ратуша начала нанимать крестьян — всё работает.**

   `python` в команде — это интерпретатор, записанный в `openwar3.json`; тот, что установил сам `start.bat`, лежит в `bin\env\python\python.exe`.

## start.bat и stop.bat

```bash
start.bat              # проверка развёртывания + открыть Farsight
start.bat setup        # полная проверка: переустановить пакеты Python, повторить AMAI
start.bat restart      # перезапустить только бэкенд Farsight (игры и службы не затрагиваются)
start.bat node         # заодно установит Node.js (нужен только для предпросмотра сайта, обычно не нужен)
start.bat 5 6          # заодно начать тест на экземплярах 5 и 6 (игра + эталонный мозг)
stop.bat               # полностью остановить всё; stop.bat --keep-llm оставляет локальную модель в видеопамяти
```

Шлюз, облачка реплик и локальная LLM тоже запускаются и останавливаются в «Центре управления» Farsight — искать другие скрипты не нужно. **Полная остановка**: дважды щёлкните `stop.bat` или нажмите «Остановить всё» в правом верхнем углу «Центра управления» — по очереди остановятся экземпляры игры, ИИ, шлюз, облачка, локальная модель, которую использует система, и бэкенд Farsight. MCP-сервер принадлежит клиентам вроде Claude и не останавливается.

> **Файл конфигурации**
>
> `openwar3.json` автоматически записывают `start.bat` и Farsight; в нём хранятся только локальные пути, в git он не попадает. Чтобы изменить порты, адрес локальной LLM или имя модели, укажите по образцу `openwar3.example.json` только то, что от него отличается.

## Параметры play.py

```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      # игра уже запущена, только подключаем Bot
python tools/play.py --bot my_bot.py --fair                 # честный режим: видно только то, что в зоне обзора
```

| Параметр | По умолчанию | Описание |
|---|---|---|
| `--bot` | обязателен | Путь к файлу бота (в файле должен быть подкласс `Bot`) |
| `--inst` | `9` | Номер экземпляра. Не занимайте номер уже работающего экземпляра (какие номера заняты, видно на странице Farsight «Экземпляры и запуск») |
| `--race` | `1` | Наша раса: 1 Люди, 2 Орда, 3 Нежить, 4 Ночные эльфы |
| `--enemy-race` | `0` | Раса противника |
| `--difficulty` | `2` | Сложность компьютерного противника: 2 лёгкая, 3 обычная, 4 безумная |
| `--speed` | `100` | Скорость игры (в процентах, 200 = скорость 2×) |
| `--map` | `default_map` из конфигурации | Карта |
| `--attach` | | Не запускать игру, только подключиться к уже работающему экземпляру |
| `--hz` | `5` | Сколько раз в секунду вызывать `on_tick` |
| `--minutes` | `60` | Максимальная длительность в минутах (реального времени) |
| `--fair` | | [Честный режим](https://war3ai.com/ru/docs/fair-mode/) |
| `--player` | | От имени игрока с каким номером командовать (для матчей AI против AI) |

> **Внимание**
>
> Не запускайте игру с `--minimize`: **когда окно свёрнуто, симуляция игры стоит** (часы не идут), и бот так и не дождётся начала партии.

Можно обойтись и без `play.py` и подключиться к уже работающему экземпляру через командную строку SDK:

```bash
python -m openwar3 run brains/examples/hello_bot.py --inst 5     # запустить Bot
python -m openwar3 status --inst 5                              # подключиться и вывести состояние снимка / быстрой полосы
python -m openwar3 catalog                                      # вывести каталог API
```

## Когда всё заработало

  - [Пишем первого бота](https://war3ai.com/ru/docs/first-bot/): Начинаем с минимального бота на 10 строк и шаг за шагом добавляем найм войск и атаку.
  - [Пусть его напишет LLM](https://war3ai.com/ru/docs/ai-bot/): Скопируйте шаблон промпта и опишите стратегию простыми словами.

## Самопроверка

```bash
python tools/run_tests.py          # SDK / эталонный мозг / рефлекторный слой / консоль / реплики / примеры — каждый набор в отдельном подпроцессе
```

Офлайн-тестам запущенная игра не нужна. В «Центре управления» Farsight тоже есть проверка окружения — там видно, все ли части установлены.