# War3AI / OpenWar3

> Открытый интерфейс Warcraft III 1.27 для ИИ-агентов: внедряемый рантайм каждые 50 ms публикует полное состояние всей карты и поток событий; внешняя программа отдаёт семантические команды примерно за кадр, и на каждую приходит квитанция с кодом причины. Python SDK (openwar3) описывает всё в терминах самой игры (четырёхсимвольные коды, строки приказов способностей).

Кратчайший путь к боту: прочитайте «Пятнадцать правил» и методы из api.json, унаследуйте openwar3.Bot и реализуйте on_start(g) / on_tick(g) / on_event(g, ev); используйте только методы, которые есть в api.json.
Вся документация в одном файле: https://war3ai.com/ru/llms-full.txt

## Начало

- [Обзор документации](https://war3ai.com/ru/docs/index.md): Документация OpenWar3: что это и что умеет; быстрый старт, первый бот, LLM пишет бота, API и протокол, шлюз и MCP — с какой страницы начать чтение в вашей ситуации.
- [Быстрый старт](https://war3ai.com/ru/docs/quickstart.md): Дважды щёлкните start.bat — всё установится само; укажите папку игры в Farsight и запустите партию, чтобы посмотреть, как управление берёт пример бота. Около 15 минут.
- [Первый бот](https://war3ai.com/ru/docs/first-bot.md): Начинаем с минимального бота на 10 строк, добавляем найм крестьян, постройку ферм, армию, героя и атаку, а в конце разбираемся с квитанциями.

## ИИ пишет бота

- [Пишем бота с помощью LLM](https://war3ai.com/ru/docs/ai-bot.md): Можно и без навыков программирования: вы объясняете, как бот должен играть, а LLM пишет код. Скопируйте шаблон промпта, опишите стратегию, запустите — и просите доработать.
- [Автономные итерации агента](https://war3ai.com/ru/docs/agent-loop.md): Пусть Coding Agent сам играет партии, читает результаты, правит код и запускает снова. Для этого ему нужны команда, работающая без присмотра, структурированный отчёт о партии и чёткая цель.
- [LLM как стратегический советник](https://war3ai.com/ru/docs/llm-coach.md): Отдайте LLM вопросы «на что копить, куда ставить рабочих, атаковать или выжидать в эту минуту», а слою правил оставьте только исполнение и право вето. Эталонный мозг уже работает так; на этой странице — сам паттерн и подводные камни.
- [LLM вызывает инструменты (MCP)](https://war3ai.com/ru/docs/mcp.md): tools/war3_mcp.py — это MCP-сервер. Подключите его к Claude Code, Claude Desktop или любому клиенту с поддержкой MCP, и LLM сможет сама смотреть на обстановку, отдавать команды, писать игроку на экране, задавать ему вопросы карточками и делать скриншоты — без заранее написанного кода.

## Основные понятия

- [Ментальная модель](https://war3ai.com/ru/docs/concepts.md): Снимок, команда, квитанция, событие, тик, пачка. Разберитесь в этих шести понятиях — и станет ясно, почему интерфейсы устроены именно так и как писать быстрый код.
- [Пятнадцать правил](https://war3ai.com/ru/docs/rules.md): Каждое выстрадано в реальных матчах. Сверяйтесь с ними, когда пишете бота, — это сэкономит большую часть времени на поиск ошибок.
- [Честный режим](https://war3ai.com/ru/docs/fair-mode.md): Клиент с внедрённым рантаймом видит всю карту. Честный режим оставляет боту только то, что в пределах обзора, — как у живого игрока и как по правилам Арены.

## Руководства

- [Книга рецептов: приёмы профи](https://war3ai.com/ru/docs/cookbook.md): Преимущество сильных игроков по большей части складывается из десятков «мелких привычек». На этой странице типичные приёмы профессиональной игры по одному переложены на код SDK — каждый фрагмент можно сразу скопировать в on_tick.
- [Примеры ботов](https://war3ai.com/ru/docs/examples.md): Четыре примера от простого к сложному: каждый запускается как есть, каждый фрагмент логики соответствует одной возможности SDK. Плюс полноценный эталонный мозг.
- [Отладка и производительность](https://war3ai.com/ru/docs/debugging.md): Почему тик медленный, почему команда не сработала, почему игра стоит. Ищите по симптомам, а затем подтверждайте встроенными скриптами проверки в реальной игре.

## Расширения игры

- [RPG-компаньон](https://war3ai.com/ru/docs/companion.md): ИИ-компаньон для игрока в RPG и пользовательских картах: ходит за вами, помогает бить крипов, лечит, когда у вас мало здоровья, и разговаривает с вами. Четыре режима; унаследуйте один класс, поменяйте пару атрибутов — и компаньон уже ваш.
- [Холст](https://war3ai.com/ru/docs/canvas.md): Текстовые блоки, панели, полоски прогресса, изображения, круги на земле и маршруты со стрелками поверх игровой картинки. Рантайм сам рисует их каждый кадр и не меняет состояние игры, поэтому это безопасно и в многопользовательской игре; работать можно через Python, HTTP или напрямую через общую память.
- [Интерфейс и ввод](https://war3ai.com/ru/docs/ui-input.md): Кнопки и карточки выбора на холсте нажимаются и подсвечиваются при наведении; можно регистрировать горячие клавиши, выбирать точку кликом по земле, узнавать, куда указывает мышь и кого выбрал локальный игрок. Клики, горячие клавиши, применение способностей, полный текст чата, уход игроков — всё попадает в поток событий.
- [JASS-канал](https://war3ai.com/ru/docs/jass.md): 1291 функцию JASS, доступную авторам карт, теперь можно вызывать по имени извне игры: создавать юнитов, менять свойства, эффекты, панели, диалоги, звук, камеру, туман войны… Четыре способа: консоль Farsight, командная строка, HTTP и Python.
- [Игровые моды](https://war3ai.com/ru/docs/mods.md): Схема — это не только ИИ, который играет за вас, но и набор правил: вы сами играете в окне игры, а мод расставляет всё на старте, выпускает волны врагов, выдаёт награды, показывает вам на экране кнопки и карточки выбора и определяет исход. Унаследуйте openwar3.Mod — один файл, один геймплей.

## Инструменты

- [Консоль Farsight](https://war3ai.com/ru/docs/console.md): Локальная веб-консоль и единственная точка входа: папка игры, запуск и остановка служб и экземпляров игры, настройка следующего матча, мысли ИИ, ручные приказы, режиссура, история матчей.
- [ИИ-схемы](https://war3ai.com/ru/docs/schemes.md): Одна схема — один полноценный ИИ. Переключение в Farsight в один клик, причём даже в идущем матче управление сразу перейдёт к новому ИИ; экспорт в zip, чтобы поделиться, импорт чужих схем для тестов и автоматическая статистика результатов по каждой схеме.
- [Реплики и локальные модели](https://war3ai.com/ru/docs/speech.md): Любой юнит в игре может заговорить от любого имени — в облачке над головой. Подключите локальную LLM: фраза на входе, ответ появляется над юнитом.
- [Шлюз](https://war3ai.com/ru/docs/gateway.md): Шлюз WebSocket / JSON: публичный API, доступный из Python SDK, можно вызывать из JS, C#, Go, Rust, со страницы в браузере или из программы на другой машине. Три роли, в комплекте JS-клиент и демо-страница для браузера; задержка — быстрая полоса плюс около 1 ms.

## Справочник

- [Протокол W3P](https://war3ai.com/ru/docs/protocol.md): Полный контракт между рантаймом и внешними программами: восемь блоков общей памяти, чтение состояния мира, чтение событий, отправка команд, квитанции, роли полос, холст, интерфейс и ввод. Читайте эту страницу, если подключаетесь не из Python.
- [Квитанции и коды причин](https://war3ai.com/ru/docs/reason-codes.md): Квитанция каждой команды содержит код статуса и код причины. На них опирается самокоррекция ботов и агентов: «почему не получилось» превращается в машиночитаемое число.
- [Откуда данные](https://war3ai.com/ru/docs/data-sources.md): Источник и точность каждого вида данных. Если что-то «выглядит не так», начните с этой страницы.

## Прочее

- [Частые вопросы](https://war3ai.com/ru/docs/faq.md): Это чит? Какие версии поддерживаются? Что ИИ видит и что умеет? Можно ли обойтись без программирования?…
- [Условия использования](https://war3ai.com/ru/docs/legal.md): Что можно и чего нельзя, статистика посещений этого сайта, а также сведения о товарных знаках и сторонних лицензиях. Используя проект, вы соглашаетесь соблюдать эти условия.

## API

- [api.json](https://war3ai.com/ru/api.json): Все методы Game, 103 шт. (name / category / status / latency / mechanism / signature / doc), генерируются из кода
- [Каталог API (веб-версия)](https://war3ai.com/ru/api/): Те же данные с поиском

## Необязательно

- [llms-full.txt](https://war3ai.com/ru/llms-full.txt): Вся документация + каталог API за одно чтение
- [Условия использования](https://war3ai.com/ru/docs/legal.md): Только для клиента, которым вы владеете на законных основаниях; нельзя использовать в Battle.net и на любых серверах с античитом