# ИИ-схемы

> Одна схема — один полноценный ИИ. Переключение в Farsight в один клик, причём даже в идущем матче управление сразу перейдёт к новому ИИ; экспорт в zip, чтобы поделиться, импорт чужих схем для тестов и автоматическая статистика результатов по каждой схеме.

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

**Схема** = один полноценный ИИ: папка + манифест `scheme.json` + код. Каждому экземпляру игры назначается одна схема; в Farsight она переключается в один клик, и **даже в идущем матче управление сразу переходит к новой схеме**.

Схемы, которыми поделились другие, импортируются в **отдельный раздел** и никак не затрагивают ваши; чтобы изменить такую схему, нажмите «Копировать в мои».

```text
schemes/
  mine/<id>/          мои схемы: написанные вами или скопированные из других для правки (меняйте как угодно, действует со следующего матча)
  installed/<id>/     установленные: сюда распаковываются zip-архивы, которыми поделились другие (перед первым запуском нужно подтвердить доверие)
brains/xwar3/         встроенные: эталонный мозг (полноценный ИИ)
brains/examples/      встроенные: четыре учебных примера hello / rush / macro / micro, пример компаньона buddy, два игровых мода («Рогалик с героем», «Бесконечная оборона»)
```

Схема — не обязательно ИИ, который играет за вас. Схема с `kind: mod` — это **набор правил игры**: играете вы, а она ставит задачи; см. [Игровые моды](https://war3ai.com/ru/docs/mods/).

## Использование в Farsight

Страница «ИИ-схемы» (левая панель «Система → ИИ-схемы»):

| Действие | Что делает |
|---|---|
| Импорт схемы (zip) | Устанавливает схему в `installed/`; если схема с таким id уже установлена, спросит, заменить ли её (после замены доверие нужно подтвердить заново) |
| Применить к экземпляру… | Выбор экземпляра + «Сразу» (текущий ИИ останавливается, новая схема подхватывает этот матч) или «Со следующего „Начать тест“» |
| Копировать в мои | Копия в `mine/`: автором записываетесь «я», версия 0.1.0, и запоминается, из какой версии какой схемы сделана копия |
| Экспорт в zip | Упаковывает в `<id>-<версия>.zip` — отправьте файл другому, и вы поделились схемой |
| Открыть папку | Открывает каталог схемы в Проводнике, чтобы сразу править код |
| Доверять | Для чужих схем обязательно перед первым запуском (см. ниже «Доверие и безопасность») |
| Последние результаты | Победа или поражение, длительность и причина завершения каждого матча этой схемы |
| Удалить | Удалять можно только «Мои» и «Установленные»; схему, которую сейчас использует какой-либо экземпляр, удалить нельзя |

На карточке экземпляра тоже появилась строка «ИИ-схема»: выберите схему в выпадающем списке → «Переключить (сразу)». Если экземпляр не запущен, кнопка называется «Выбрать» — при следующем «Начать тест» ИИ запустится по этой схеме.

## Манифест scheme.json

```json
{
  "format": 1,
  "id": "fast-rush",
  "name": "Раш за три минуты",
  "version": "1.2.0",
  "author": "Некто",
  "description": "Одной фразой: какую стратегию играет этот ИИ",
  "entry": "rush_bot.py",
  "class": "RushBot",
  "fair": true,
  "hz": 5,
  "races": ["human", "orc"],
  "license": "MIT"
}
```

| Поле | Обязательно | Пояснение |
|---|---|---|
| `id` | ✔ | Строчные латинские буквы, цифры, `-`, `_`; от 2 до 41 символа |
| `entry` | ✔ | Файл `.py` внутри каталога схемы (абсолютные пути и `..` запрещены) |
| `kind` | | По умолчанию `bot` (подкласс `openwar3.Bot`, играет за вас); `mod` = [игровой мод](https://war3ai.com/ru/docs/mods/) (подкласс `openwar3.Mod`; всегда без честного режима, исход не определяется по правилам обычного матча) |
| `class` | | Имя подкласса Bot (или Mod) в файле входа; если не задано, берётся последний подкласс `openwar3.Bot` в этом файле |
| `fair` | | По умолчанию `true`: видно только то, что в пределах обзора, — те же правила, что на Арене. `false` = видна вся карта, и только в этом случае доступен [JASS-канал](https://war3ai.com/ru/docs/jass/) (он нужен компаньону) |
| `judge` | | По умолчанию `true`: победа и поражение определяются по правилам обычного матча. Для RPG-схем и схем компаньонов — `false` |
| `hz` | | Сколько раз в секунду вызывается `on_tick`, по умолчанию 5 |
| `format` | | Версия формата манифеста, сейчас 1; если она новее, чем поддерживает ваш OpenWar3, схема отклоняется с предложением обновиться |
| Остальные | | `name`, `version`, `author`, `description`, `races`, `license`, `homepage`, `forked_from` — только для отображения |

Каталог схемы добавляется в путь поиска модулей Python, так что файл входа может импортировать (`import`) другие файлы из того же каталога. Сторонние пакеты (numpy, torch…) автоматически не устанавливаются — укажите в `description`, что нужно.

**Минимальной схеме хватает двух файлов**:

```python
# my_bot.py
from openwar3 import Bot

class MyBot(Bot):
    def on_tick(self, g):
        for w in g.idle_workers():
            mine = g.nearest(g.gold_mines(), w)
            if mine:
                g.gather(w, mine)
```

```json
{"id": "my-first", "name": "Мой первый ИИ", "entry": "my_bot.py"}
```

Положите их в `schemes/mine/my-first/` и обновите Farsight — схема появится. Начать ещё проще так: выберите пример во «Встроенных» и нажмите «Копировать в мои».

## Запуск и результаты

Схемы запускает **раннер схем** (кнопки «Начать тест» / «Переключить» в Farsight запускают именно его):

```bash
python tools/run_scheme.py --inst 20 --scheme builtin/micro --hours 6
```

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

Как определяется исход:

| Ситуация | Записывается как |
|---|---|
| У соперника не осталось зданий | Победа |
| У нас не осталось зданий (даже если войска живы — в обычном матче поражение засчитывается именно так) | Поражение |
| У нас не осталось юнитов | Поражение |
| Матч завершён / остановлен вручную в Farsight | Не определено |
| При переключении матч уже шёл больше 60 игровых секунд (схема подхватила его на полпути) | Учитывается отдельно, **в процент побед не входит** |
| Игровые часы долго не идут | Не определено |

Когда исход определён, раннер закрывает экран итогов, запускает следующий матч по настройкам «Следующий матч», и схема снова берёт управление — можно оставить всё на ночь копить статистику. Пауза — не конец матча: во время паузы бот работает как обычно, стоят только игровые часы.

## Доверие и безопасность

**Схема — это код, и при запуске у неё те же права, что и у вас** (читать и записывать файлы, выходить в сеть). Поэтому:

- схемы в `installed/` по умолчанию **не считаются доверенными**: Farsight и раннер отказываются их запускать, пока вы не нажмёте «Доверять»;
- установка поверх схемы с тем же id **сбрасывает доверие** (новая версия — это новый код);
- при импорте проверяется: zip не больше 50 MB и не больше 2000 файлов; абсолютные пути и `..` запрещены (чтобы ничего не записалось за пределы каталога схемы); некорректный манифест или отсутствующий файл входа — сразу отказ.

> **Внимание**
>
> Прежде чем доверять схеме, нажмите «Открыть папку» и прочитайте код. Берите схемы только у тех, кому доверяете.

## API (для скриптов)

| Метод | Описание |
|---|---|
| `GET /api/schemes` | Список схем + результаты + выбранная и запущенная схема каждого экземпляра |
| `GET /api/schemes/results?ref=` | Последние 30 матчей одной схемы |
| `POST /api/schemes/import` | Импорт zip |
| `GET /api/schemes/export?ref=` | Скачать zip |
| `POST /api/schemes/fork` | Копировать в мои |
| `POST /api/schemes/trust` | Доверять |
| `DELETE /api/schemes?ref=` | Удалить (отказ, если схему использует экземпляр) |
| `POST /api/instances/{n}/scheme` | Сменить схему экземпляра: сразу подхватить текущий матч или со следующего «Начать тест» |

В Python можно напрямую использовать библиотеку: `from openwar3 import schemes` (`list_schemes`, `install_zip`, `export_zip`, `fork`, `trust`, `stats`…).

## Дальше: сайт схем

Экспортированный zip — это и есть единица обмена, сайту остаётся лишь добавить слой поверх: загрузка из Farsight в один клик; скачивание с сайта с теми же проверками, что при «Импорте схемы», и тем же обязательным подтверждением доверия; по желанию — отправка результатов, а сайт сводит процент побед по версиям. Место для кнопки «Поделиться на сайте схем» в Farsight уже предусмотрено. Как идёт работа — в [дорожной карте](https://war3ai.com/ru/roadmap/).