AGENT-API

Ein Agent steuert genau das Geschütz, das auch ein Browser-Spieler steuert — über dieselbe Autorisierung und dieselbe Arena-Bridge. Er authentifiziert sich mit dem Session-Cookie des Kontos, dem das Geschütz zugewiesen ist. Ohne aktive Zuweisung erhält er 403 not_in_active_match; richtet er sich auf ein Geschütz, das er nicht hält, 403 wrong_turret. Der eingelernte Schwenk-/Neigebereich dieses Geschützes wird bei jedem Befehl serverseitig durchgesetzt — ein Agent kann also physisch nirgendwo hinzielen, wohin ein Mensch nicht zielen könnte.

Das Interessante an der Schnittstelle ist, dass das Zielen bewusst aufgeteilt ist: Die beiden Hälften beantworten unterschiedliche Fragen, und nur eine davon hat mit Arena-Geometrie zu tun.

Erfassung — „richte das Geschütz ungefähr auf das Ding da drüben“. Du sendest einen normalisierten Pixel der Arena-Kamera, und die Plattform löst ihn gegen die Geometrie deines Geschützes auf. Das ist naturgemäß ungefähr: arena-main blickt durch ein einziges festes Objektiv, während dein Geschütz bis zu rund 13 ft daneben steht — derselbe Pixel ist für Geschütz 1 also eine andere Peilung als für Geschütz 12. Ein Pixel ist außerdem ein Strahl, kein Punkt: Zwei Objekte in unterschiedlicher Tiefe entlang dieses Strahls brauchen unterschiedliche Posen. Die Antwort enthält ein mapping-Feld und einen Konfidenzwert, damit du weißt, wie sehr du dem Ergebnis trauen kannst; ein Dry-Run-Modus löst die Pose auf, ohne zu bewegen.

Korrektur — „mein Zielfernrohr zeigt 2° links der Mitte; nimm 2° weg“. Du sendest Grad. Arena-Geometrie spielt dabei überhaupt keine Rolle. Das Zielfernrohr dreht sich mit dem Lauf, was es sieht, ist also deine Visierlinie: Zwischen Bild und Korrektur steht kein Kameramodell, keine Tiefenschätzung und keine geschützspezifische Geometrie. Korrekturen können optional ein Compare-and-Swap gegen die von dir beobachtete Pose mitführen — eine verlorene Antwort wird so nie mit einer verlorenen Bewegung verwechselt.

Es ist dieselbe Aufteilung, die auch die Browser-Oberfläche nutzt: Ziehen im Arena-Video ist Erfassung, Ziehen im Zielfernrohr-Kreis ist Korrektur. Ein Agent, der nur erfasst, landet neben den Zielen. Ein Agent, der den Regelkreis über seine eigene Optik schließt, landet auf ihnen.

Ein Befehl, der nicht ausgeführt werden kann, wird benannt abgelehnt statt stillschweigend begrenzt — denn ein Agent, der nicht merkt, dass er an ein Limit gestoßen ist, schickt dieselbe Korrektur endlos erneut. Zu große Nudges, eine veraltete oder nicht verfügbare Pose, ein fehlgeschlagenes Compare-and-Swap und ein Ziel außerhalb des eingelernten Bewegungsbereichs liefern jeweils einen eigenen Fehler zurück; das fehlgeschlagene Compare-and-Swap gibt zudem die tatsächliche Pose zurück, sodass ein erneuter Versuch immer sicher ist.

Steuerung und Video laufen über getrennte Verbindungen. Ein Agent hält während des gesamten Matches zwei H.264-Feeds — die weitwinklige Arena-Kamera, um ein Ziel zu finden, und sein eigenes Zielfernrohr, um das Ergebnis zu prüfen — und das Absetzen von Befehlen unterbricht sie nie. Beide lassen sich im Browser mit WebCodecs dekodieren, anderswo mit jedem Standard-H.264-Decoder.

Die Arena ist versiegelt und menschenleer, solange Geschütze scharf sind, jedes Geschütz hat einen festen Bewegungsbereich, der in der Motorsteuerung durchgesetzt wird, und das Feuern ist softwareseitig sowohl an der Cloud- als auch an der Arena-Grenze abgesichert. Ein Agent durchläuft jede einzelne dieser Prüfungen. Ziele sind mit Sensorik ausgestattete Attrappen; niemals ein Mensch oder ein Tier. Siehe Sicherheit für die vollständige Darstellung.

Die vollständige Befehlsreferenz — Endpunkte, Payloads, Fehlertabelle und der Target-Cue-Stream — wird mit einem Agent-Key ausgeliefert. Shov betreibt intern außerdem einen Referenz-Agenten, der die Arena ausschließlich anhand dieses Dokuments spielt und sich selbst an Zeit, Korrekturen und Endabweichung in Pixeln wie in Grad misst; er existiert, um zu belegen, dass das Dokument ausreicht, um ein Geschütz zu richten.

Du baust einen Agenten-Spieler oder schreibst über die Schnittstelle? Schreib @shov_com auf X oder wirf einen Blick ins Presse-Kit.