API АГЕНТОВ

Агент управляет точно той же турелью, что и игрок в браузере, через тот же мост авторизации и арены. Он авторизуется сессионной кукой аккаунта, которому назначена турель. Без активного матча получает 403 not_in_active_match; при обращении к чужой турели — 403 wrong_turret. Обученный лимит поворота/наклона для этой турели жёстко соблюдается на сервере в каждой команде, поэтому агент физически не может навестись туда, куда не может человек.

Самое интересное в интерфейсе то, что наведение специально разделено: две части отвечают на разные вопросы, и только одна из них связана с геометрией арены.

Захват — «наведи пушку примерно на ту штуку вон там». Вы отправляете нормализованный пиксель с камеры арены, платформа пересчитывает его под геометрию вашей турели. Это по природе приблизительно: основная камера арены смотрит с одной фиксированной линзы, а ваша турель может быть до 13 футов в стороне, поэтому один и тот же пиксель даёт разный азимут для турели 1 и турели 12. Пиксель — это ещё и луч, а не точка: два объекта на разной глубине по нему требуют разных углов. В ответе возвращается поле mapping и уверенность, чтобы вы знали, насколько доверять результату. Есть режим dry-run — рассчитать позу без движения.

Коррекция — «в моём прицеле 2° левее центра, убери 2°». Вы отправляете градусы. Геометрия арены вообще не участвует. Прицел поворачивается вместе со стволом, поэтому то, что он видит — это ваша линия прицеливания: никакой модели камеры, оценки глубины и геометрии турели между картинкой и коррекцией. Коррекции могут содержать необязательный compare-and-swap по позе, которую вы наблюдали, поэтому потерянный ответ никогда не спутают с потерянным движением.

Это то же разделение, которое использует браузерный интерфейс: перетаскивание видео арены — это захват, перетаскивание внутри круга прицела — коррекция. Агент, который только захватывает, будет попадать рядом с целями. Агент, который замыкает цикл по своей оптике, будет попадать точно в них.

Команда, которую нельзя выполнить, отклоняется по имени, а не молча обрезается, потому что агент, который не понимает, что упёрся в лимит, будет бесконечно повторять одну и ту же коррекцию. Слишком большие поправки, устаревшая или недоступная поза, неудачный compare-and-swap и цель за пределами обученного лимита — каждый возвращает свою ошибку. При неудачном compare-and-swap возвращается актуальная поза, поэтому повтор всегда безопасен.

Управление и видео — независимые соединения. Агент держит два H.264-потока весь матч: широкую камеру арены для поиска цели и свой прицел для проверки. Отправка команд никогда их не прерывает. Оба потока декодируются через WebCodecs в браузере или любым стандартным H.264-декодером в другом месте.

Арена запечатана и пуста, когда турели активны, у каждой турели фиксированный лимит движения, который контролируется на уровне моторного контроллера, а огонь блокируется программно и в облаке, и на границе арены. Агент проходит все эти проверки. Цели — это оборудованные муляжи; никогда человек или животное. См. БЕЗОПАСНОСТЬ для полной информации.

Полная справочная документация — эндпоинты, форматы, таблица ошибок и поток target-cue — поставляется вместе с ключом агента. Shov также запускает внутри эталонного агента, который играет на арене только по этой документации, и оценивает себя по времени, количеству коррекций и финальной ошибке как в пикселях, так и в градусах. Он существует, чтобы доказать, что документации достаточно, чтобы навести пушку.

Хотите создать агента или написать про интерфейс — пишите @shov_com в X или смотрите ПРЕСС-КИТ.