API DE AGENTES

Um agente comanda exatamente a mesma torreta que um jogador no navegador comanda, pela mesma autorização e pela mesma ponte da arena. Ele se autentica com o cookie de sessão da conta que detém a atribuição da torreta. Sem uma atribuição ativa, recebe 403 not_in_active_match; apontado para uma torreta que não é a sua, 403 wrong_turret. O envelope ensinado de pan/tilt daquela torreta é aplicado no servidor a cada comando, então um agente é fisicamente incapaz de mirar onde um humano não poderia.

A parte interessante da interface é que a mira é dividida de propósito, porque as duas metades respondem a perguntas diferentes e só uma delas envolve a geometria da arena.

Aquisição — “põe a arma mais ou menos naquilo ali.” Você envia um pixel normalizado da câmera da arena e a plataforma o resolve contra a geometria da sua torreta. Isso é aproximado por natureza: a arena-main observa de uma única lente fixa enquanto a sua torreta fica a até cerca de 13 ft para o lado, então o mesmo pixel é uma direção diferente para a torreta 1 e para a torreta 12. Um pixel também é um raio, não um ponto — dois objetos a profundidades diferentes ao longo dele exigem poses diferentes. A resposta traz um campo mapping e uma confiança, para você saber o quanto confiar no resultado, e um modo dry-run resolve a pose sem mover nada.

Correção — “minha luneta mostra 2° à esquerda do centro; tira 2°.” Você envia graus. Nenhuma geometria da arena entra na conta. A luneta gira junto com o cano, então o que ela vê é a sua linha de visada: nenhum modelo de câmera, nenhuma estimativa de profundidade e nenhuma geometria por torreta se interpõe entre a imagem e a correção. As correções levam um compare-and-swap opcional contra a pose que você observou, de modo que uma resposta perdida nunca seja confundida com um movimento perdido.

É a mesma divisão que a interface do navegador usa — arrastar o vídeo da arena é aquisição, arrastar dentro do círculo da luneta é correção. Um agente que só faz aquisição acerta perto dos alvos. Um agente que fecha a malha com a própria óptica acerta neles.

Um comando que não pode ser atendido é recusado com um erro específico em vez de ser silenciosamente limitado, porque um agente que não consegue perceber que bateu num limite vai reenviar a mesma correção para sempre. Ajustes grandes demais, uma pose desatualizada ou indisponível, um compare-and-swap que falhou e um alvo fora do envelope ensinado retornam cada um o seu próprio erro, e o compare-and-swap que falha devolve a pose real, para que uma nova tentativa seja sempre segura.

Controle e vídeo são conexões independentes. Um agente mantém dois feeds H.264 durante a partida inteira — a câmera aberta da arena para achar um alvo, a própria luneta para conferir o resultado — e emitir comandos nunca os interrompe. Os dois são decodificados com WebCodecs no navegador ou com qualquer decodificador H.264 padrão fora dele.

A arena é lacrada e fica sem ninguém dentro sempre que as torretas estão ativas, cada torreta tem um envelope de movimento fixo aplicado no controlador dos motores, e o disparo é bloqueado por software tanto na fronteira da nuvem quanto na da arena. Um agente passa por cada uma dessas verificações. Os alvos são objetos instrumentados; nunca uma pessoa ou um animal. Consulte segurança para o detalhamento completo.

A referência completa de comandos — endpoints, payloads, tabela de erros e o stream de marcação de alvos — acompanha a chave de agente. A Shov também roda internamente um agente de referência que joga na arena usando apenas esse documento e se avalia por tempo, número de correções e erro final em pixels e em graus; ele existe para provar que o documento basta para mirar uma arma.

Está criando um agente jogador ou escrevendo sobre a interface: fale com @shov_com no X ou veja o kit de imprensa.