API АГЕНТІВ

Агент керує точно тією самою туреллю, що й гравець у браузері, через ту саму авторизацію та той самий arena bridge. Він авторизується за допомогою session cookie облікового запису, якому призначена турель. Без активного призначення отримує 403 not_in_active_match; якщо вказати турель, якою він не володіє — 403 wrong_turret. Taught pan/tilt envelope для цієї турелі примусово контролюється на сервері для кожної команди, тому агент фізично не може націлитися туди, куди не може людина.

Цікава частина інтерфейсу в тому, що ціління навмисно розділене, бо дві половини відповідають на різні питання і лише одна з них стосується геометрії арени.

Acquisition — «навести гармату приблизно на ту штуку он там». Ви надсилаєте нормалізований піксель з камери арени, а платформа розраховує його відносно геометрії вашої турелі. Це за природою приблизно: arena-main дивиться з одного фіксованого об’єктива, а ваша турель може бути до 13 футів убік, тому той самий піксель — це різні напрямки для турелі 1 і турелі 12. Піксель — це також промінь, а не точка: два об’єкти на різній глибині по ньому потребують різних положень. У відповіді повертається поле mapping та впевненість, щоб ви знали, наскільки довіряти результату, а режим dry-run розраховує позу без руху.

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

Це те саме розділення, яке використовує браузерний інтерфейс — перетягування відео арени це acquisition, перетягування всередині кола прицілу це correction. Агент, який лише виконує acquire, буде приземлятися біля цілей. Агент, який замикає цикл на власній оптиці, буде приземлятися точно на них.

Команда, яку неможливо виконати, відхиляється за назвою, а не мовчки обрізається, бо агент, який не може зрозуміти, що вдарився об ліміт, буде постійно повторювати ту саму корекцію. Надто великі зсуви, застаріла або недоступна поза, невдалий compare-and-swap та ціль поза taught envelope — кожен повертає свою помилку. Невдалий compare-and-swap повертає фактичну позу, тому повторна спроба завжди безпечна.

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

Арена герметична і порожня щоразу, коли турелі активні, кожна турель має фіксований movement envelope, який контролюється на рівні моторного контролера, а стрільба заблокована програмно як у хмарі, так і на межах арени. Агент проходить усі ці перевірки. Цілі — це інструментовані реквізити; ніколи людина чи тварина. Див. БЕЗПЕКА для повної інформації.

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

Створюєте агента-гравця або пишете про інтерфейс: пишіть @shov_com в X або перегляньте прес-кіт.