Пишем бота с помощью LLM

Подходит тем, кто играет в Warcraft III, но не умеет программировать, а также разработчикам, которые хотят сэкономить время. Весь процесс — это диалог: вы описываете стратегию → модель пишет код → вы играете партию → рассказываете модели, что увидели → она исправляет.

Сначала настройте окружение по Быстрому старту и добейтесь, чтобы hello_bot заработал (крестьяне пошли добывать золото). Тогда при проблемах вы сможете отличить ошибку окружения от ошибки в боте.

1. Подготовьте материалы для модели

Насколько хорошо модель напишет код, на восемьдесят процентов зависит от того, прочитала ли она правильные материалы. Выберите вариант под свой инструмент:

Что вы используете	Как передать материалы
Coding Agent с доступом к репозиторию (Claude Code, Cursor, Codex и т. п.)	Откройте его в папке репозитория и попросите сначала прочитать `docs/BOT_HANDBOOK_ZH.md`, `docs/api.json` и один пример (для экономики — `brains/examples/macro_bot.py`, для боя — `micro_bot.py`)
Чат-модель с доступом в интернет	Попросите её сначала прочитать `https://war3ai.com/llms-full.txt` — вся документация сайта собрана в этом одном файле
Веб-чат без доступа в интернет	Вставьте руководство, `api.json` и один файл-пример после промпта
Локальная модель (LM Studio, Ollama)	То же самое. Контекстное окно лучше от 32K токенов, иначе руководство и каталог API не поместятся

Если нужен какой-то приём профи, добавьте ещё соответствующий рецепт из Книги рецептов.

2. Скопируйте этот промпт

Замените последний блок «Стратегия, которую я хочу» своими словами — чем конкретнее, тем лучше:

Напиши AI (на Python) для Warcraft III 1.27. Используй только методы Game, перечисленные в api.json,
не выдумывай несуществующие методы. Пиши по образцу rush_bot.py: наследуйся от openwar3.Bot, реализуй on_start(g) и on_tick(g).

Правила:
- on_tick вызывается примерно 5 раз в секунду и должен быть быстрым (никаких sleep внутри).
- Значение, которое не удалось прочитать, — это None, а не 0; сначала проверяй, потом используй.
- Команда возвращает квитанцию (Receipt): `if r:` означает «движок принял»; если не принял, в `r.reason` указана причина
  (не хватает пищи, не хватает золота, цель не видна, такой герой уже есть…) — попробуй снова в следующий тик или иначе.
- Атаковать конкретного врага — g.attack(юниты, враг); враг должен быть в зоне обзора, невидимого отклонят.
- Погибшего героя воскрешают через g.revive(алтарь), нанять второго такого же нельзя.
- Здания строй через g.build_near(рабочий, код_здания, x, y): он сам найдёт место, куда здание влезет, и отследит результат; если не хватает денег, ничего не делает.
- Чтобы знать, «что только что произошло» (кто погиб, кто получил урон, герой получил уровень, выпал предмет), реализуй on_event(g, ev).
- Не отдавай одному и тому же юниту одну и ту же команду каждый тик (это прерывает то, что он делает); приказывай «бездельникам».
- На добычу отправляй только рабочих из idle_workers(). На одном золотом руднике не больше 5 рабочих.
- В очереди найма держи только 1 юнит (следующего ставь, когда g.queue(здание) пуста); упёрлись ли в пищу — смотри g.production(здание).blocked.
- Если за один тик нужно отдать много команд, оберни их в with g.batch(): (игровой поток ждём только один раз).
- Кого бить, выбирай через g.time_to_kill(моя_группа, враг) (учитывает контры и броню); куда идти — через g.path_distance (если не дойти, вернёт None).
- В честном режиме видно только то, что в зоне обзора; врагов, которых видели раньше, бери из g.last_seen().
- Юниты обозначаются четырёхсимвольными кодами (крестьянин Людей hpea, пехотинец hfoo, казарма hbar…), заклинания — строками приказов (thunderbolt — Молот бурь,
  blizzard — Снежная буря, holybolt — Свет небес…, полный список в data/order-ids.txt), изучение способностей — четырёхсимвольными кодами (AHtb, AHbz…).

Стратегия, которую я хочу:
<напиши здесь простыми словами, например:
  "Люди, в начале 5 крестьян на золото и 1 на лес; первый герой — Архимаг; две казармы, пехотинцы и стрелки;
   набрав 12 юнитов, идём с героем на экспансию противника; если здоровье героя ниже 30% — отступаем домой;
   на крипинге сначала лагеря поближе к базе.">

Как понятно описать стратегию

Больше всего модель боится расплывчатых требований. Вместо «играй агрессивнее» полезнее такие сведения:

Раса и герой: какого героя брать первым, порядок прокачки (например, Архимаг: Элементаль воды, Снежная буря, Элементаль воды…).
Порядок постройки: на каком крестьянине ставить казарму, когда улучшать ратушу, сколько нужно казарм.
Состав армии: пехотинцы + стрелки? С какого количества выходить?
Условия атаки и отступления: с какой армией нападать, при каком здоровье героя отступать, если армию потрепали — домой, собирать заново.
Крипинг: крипить ли, когда (после наступления темноты?), только лагеря, которые по силам?
Честность: если потом собираетесь на Арену, укажите «использовать только врагов, которых видно в зоне обзора».

3. Запустите

Сохраните код от модели как brains/my_bot.py, затем:

python tools/play.py --bot brains/my_bot.py --race 1 --difficulty 2

Чтобы увидеть результат быстрее, добавьте --speed 200 (скорость игры 2×).

4. Просите исправить

Ошибка: вставьте модели весь текст ошибки как есть и попросите «исправь».
Играет плохо: описывайте, что вы видите в игре, а не свои догадки о причине. Например: «герой всё время стоит на базе», «войска идут в бой по одному», «все крестьяне столпились на одном руднике».
Хотите новый приём: добавляйте по одной вещи за раз, сыграйте партию, убедитесь, что ничего не сломалось, и только потом добавляйте следующую.

Coding Agent, который умеет сам запускать команды, может взять на себя и шаги 3 и 4: сыграть партию, прочитать логи и квитанции, поправить код, запустить снова. Как дать ему достаточно информации, см. в разделе Автономные итерации агента.

5. Частые проблемы

Симптом	Скорее всего
Ничего не двигается	Неверный номер экземпляра (`--inst`) или игра ещё не вошла в партию
Крестьяне не добывают золото	Приказ отдан уже занятым крестьянам; отправляйте только `idle_workers()`
Здания никак не строятся	Используйте `build_near`, не прописывайте координаты жёстко; проверьте `reason` в квитанции — может, не хватает денег
Герой не появляется	Смотрите квитанцию `train`: не хватает пищи? Или герой погиб (нужен `revive`)?
Герой не применяет заклинания	Способность не изучена (`learn`) или нет маны; после применения проверьте через `cooldown()`, ушла ли она на перезарядку
Войска дёргаются каждый тик	Команды отдаются заново каждый тик; приказывайте только бездельничающим юнитам
Войска не нанимаются, деньги копятся	Упёрлись в лимит пищи: смотрите `g.production(казарма).blocked`
Модель использует несуществующие методы	Ещё раз подчеркните в промпте «только методы из api.json» и вставьте api.json целиком

Что дальше

Все интерфейсы и механизм каждого из них: каталог API;
эталонный мозг (brains/xwar3/strategy) — это полноценный AI, который занимает экспансии, крипует и атакует; можно дать модели изучить его подход, но он использует более низкоуровневые интерфейсы, поэтому копировать его напрямую не советуем;
на Арене будут видны только враги в зоне обзора — добавьте --fair уже сейчас, чтобы потом ничего не переделывать.