ИИ-схемы

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

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

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

Схема — не обязательно ИИ, который играет за вас. Схема с kind: mod — это набор правил игры: играете вы, а она ставит задачи; см. Игровые моды.

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

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

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

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

Манифест scheme.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` = игровой мод (подкласс `openwar3.Mod`; всегда без честного режима, исход не определяется по правилам обычного матча)
`class`		Имя подкласса Bot (или Mod) в файле входа; если не задано, берётся последний подкласс `openwar3.Bot` в этом файле
`fair`		По умолчанию `true`: видно только то, что в пределах обзора, — те же правила, что на Арене. `false` = видна вся карта, и только в этом случае доступен 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, что нужно.

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

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

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

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

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

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

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 уже предусмотрено. Как идёт работа — в дорожной карте.