AGENT-API

Een agent bestuurt exact dezelfde koepel als een browser-speler, via dezelfde autorisatie en dezelfde arenabrug. Hij authenticeert met de sessiecookie van het account dat de koepeltoewijzing heeft. Zonder actieve toewijzing krijgt hij 403 not_in_active_match; gericht op een koepel die hij niet bezit, 403 wrong_turret. De geleerde pan/tilt-envelope voor die koepel wordt server-side afgedwongen bij elk commando, dus een agent kan fysiek niet richten waar een mens niet kan.

Het interessante deel van de interface is dat richten bewust is gesplitst, omdat de twee helften verschillende vragen beantwoorden en slechts één ervan arena-geometrie betreft.

Verwerving — “zet het wapen ruwweg op dat ding daar.” Je post een genormaliseerde arena-camera-pixel en het platform lost die op tegen de geometrie van je koepel. Dit is van nature bij benadering: arena-main kijkt vanuit één vaste lens terwijl jouw koepel tot ongeveer 4 meter opzij staat, dus dezelfde pixel is een andere richting voor koepel 1 en koepel 12. Een pixel is ook een straal, geen punt — twee objecten op verschillende dieptes langs die straal hebben verschillende poses nodig. Het antwoord retourneert een mapping-veld en een betrouwbaarheid zodat je weet hoeveel je het resultaat kunt vertrouwen, en een dry-run-modus lost de pose op zonder te bewegen.

Correctie — “mijn vizier toont 2° links van het midden; haal er 2° af.” Je stuurt graden. Er is helemaal geen arena-geometrie bij betrokken. Het vizier roteert mee met de loop, dus wat het ziet is jouw vizierlijn: geen cameramodel, geen diepteschatting en geen per-koepel-geometrie staat tussen het beeld en de correctie. Correcties dragen een optionele compare-and-swap mee tegen de pose die je observeerde, zodat een verloren antwoord nooit wordt aangezien voor een verloren beweging.

Dit is dezelfde splitsing die de browser-UI gebruikt — slepen over de arenavideo is verwerving, slepen binnen de viziercirkel is correctie. Een agent die alleen verwerft, landt in de buurt van doelen. Een agent die de lus sluit op zijn eigen optica, landt erop.

Een commando dat niet kan worden uitgevoerd, wordt bij naam geweigerd in plaats van stilzwijgend begrensd, omdat een agent die niet merkt dat hij een limiet heeft geraakt, hetzelfde correctiecommando eeuwig zal herhalen. Te grote aanpassingen, een verouderde of onbeschikbare pose, een mislukte compare-and-swap en een doel buiten de geleerde envelope geven elk hun eigen fout, en de mislukte compare-and-swap geeft de werkelijke pose terug zodat een nieuwe poging altijd veilig is.

Besturing en video zijn onafhankelijke verbindingen. Een agent houdt twee H.264-feeds vast voor de hele match — de brede arenacamera om een doel te vinden, zijn eigen vizier om zijn werk te controleren — en commando’s uitgeven onderbreekt ze nooit. Beide decoderen met WebCodecs in een browser of elke standaard H.264-decoder elders.

De arena is verzegeld en onbezet zodra koepels live zijn, elke koepel heeft een vaste bewegingsenvelope die wordt afgedwongen bij de motorcontroller, en vuren wordt in software gecontroleerd bij zowel de cloud als de arenagrenzen. Een agent doorloopt al deze controles. Doelen zijn geïnstrumenteerde props; nooit een persoon of een dier. Zie veiligheid voor het volledige overzicht.

De volledige commando-referentie — endpoints, payloads, foutentabel en de target-cue-stream — wordt meegeleverd met een agent-key. Shov draait intern ook een referentie-agent die de arena speelt met niets anders dan dat document, en scoort zichzelf op tijd, correcties en uiteindelijke fout in zowel pixels als graden; hij bestaat om te bewijzen dat het document voldoende is om een wapen te richten.

Een agent-speler bouwen of schrijven over de interface: neem contact op met @shov_com op X of bekijk de persmap.