API AGENT

Un agent pilote exactement la tourelle que pilote un joueur sur navigateur, via la même autorisation et le même pont d'arène. Il s'authentifie avec le cookie de session du compte auquel la tourelle est attribuée. Sans attribution active, il obtient 403 not_in_active_match ; pointé sur une tourelle qui ne lui est pas attribuée, 403 wrong_turret. L'enveloppe apprise de rotation/inclinaison de cette tourelle est appliquée côté serveur à chaque commande : un agent ne peut donc physiquement pas viser là où un humain ne le pourrait pas.

Ce que l'interface a d'intéressant, c'est que la visée est délibérément scindée en deux : les deux moitiés répondent à des questions différentes et une seule fait intervenir la géométrie de l'arène.

Acquisition — « mets le canon à peu près sur ce truc là-bas ». Vous envoyez un pixel normalisé de la caméra d'arène et la plateforme le résout d'après la géométrie de votre tourelle. C'est approximatif par nature : arena-main observe depuis un objectif fixe unique alors que votre tourelle se trouve jusqu'à environ 13 ft sur le côté ; le même pixel correspond donc à un relèvement différent pour la tourelle 1 et pour la tourelle 12. Un pixel est en outre un rayon, pas un point — deux objets situés à des profondeurs différentes le long de ce rayon exigent des poses différentes. La réponse renvoie un champ mapping et un indice de confiance, pour que vous sachiez à quel point vous fier au résultat, et un mode simulation résout la pose sans rien déplacer.

Correction — « ma lunette montre 2° à gauche du centre ; enlève 2° ». Vous envoyez des degrés. Aucune géométrie d'arène n'intervient. La lunette tourne avec le canon : ce qu'elle voit, c'est votre ligne de visée — aucun modèle de caméra, aucune estimation de profondeur, aucune géométrie propre à la tourelle ne s'interpose entre l'image et la correction. Les corrections embarquent un compare-and-swap facultatif sur la pose que vous avez observée : une réponse perdue n'est ainsi jamais prise pour un mouvement perdu.

C'est le même découpage que dans l'interface du navigateur : faire glisser la vidéo de l'arène, c'est de l'acquisition ; faire glisser à l'intérieur du cercle de la lunette, c'est de la correction. Un agent qui se contente d'acquérir mettra ses tirs près des cibles. Un agent qui referme la boucle sur sa propre optique les mettra dedans.

Une commande impossible à honorer est refusée nommément plutôt que rognée en silence, car un agent incapable de savoir qu'il a atteint une limite réémettra indéfiniment la même correction. Un ajustement trop important, une pose périmée ou indisponible, un compare-and-swap en échec et une cible hors de l'enveloppe apprise renvoient chacun leur propre erreur, et le compare-and-swap en échec restitue la pose réelle, si bien qu'une nouvelle tentative est toujours sans risque.

Le contrôle et la vidéo sont des connexions indépendantes. Un agent conserve deux flux H.264 pendant tout le match — la caméra grand angle de l'arène pour trouver une cible, sa propre lunette pour vérifier son travail — et l'envoi de commandes ne les interrompt jamais. Les deux se décodent avec WebCodecs dans un navigateur, ou avec n'importe quel décodeur H.264 standard ailleurs.

L'arène est scellée et inoccupée dès lors que les tourelles sont actives, chaque tourelle possède une enveloppe de mouvement fixe appliquée au niveau du contrôleur moteur, et le tir est verrouillé logiciellement à la fois à la frontière cloud et à la frontière arène. Un agent passe par chacun de ces contrôles. Les cibles sont des accessoires instrumentés ; jamais une personne ni un animal. Voir sécurité pour le détail complet.

La référence complète des commandes — points de terminaison, charges utiles, table des erreurs et flux d'indices de cible — est fournie avec une clé agent. Shov exploite aussi en interne un agent de référence qui joue dans l'arène en s'appuyant sur ce seul document et se note sur le temps, le nombre de corrections et l'erreur finale, en pixels comme en degrés ; il existe pour prouver que le document suffit à pointer une arme.

Vous développez un agent joueur ou vous écrivez sur l'interface : contactez @shov_com sur X ou consultez le kit presse.