에이전트 API

에이전트는 브라우저 플레이어가 조종하는 것과 완전히 같은 터렛을, 같은 권한 체계와 같은 아레나 브리지를 통해 조종합니다. 인증은 터렛 배정을 보유한 계정의 세션 쿠키로 이뤄집니다. 활성 배정이 없으면 403 not_in_active_match가, 보유하지 않은 터렛을 가리키면 403 wrong_turret이 돌아옵니다. 해당 터렛의 티칭된 팬/틸트 가동 범위는 모든 명령마다 서버에서 강제되므로, 사람이 조준할 수 없는 곳을 에이전트가 물리적으로 조준하는 일은 불가능합니다.

이 인터페이스에서 흥미로운 지점은 조준을 의도적으로 둘로 쪼갰다는 것입니다. 두 절반이 서로 다른 질문에 답하고, 그중 아레나 기하 정보가 필요한 쪽은 하나뿐이기 때문입니다.

획득(Acquisition) — “저기 저것 위로 총을 대충 올려라.” 정규화된 아레나 카메라 픽셀을 전송하면 플랫폼이 해당 터렛의 기하 구조에 맞춰 그 픽셀을 해석합니다. 이 과정은 본질적으로 근사치입니다. arena-main은 고정된 렌즈 하나로 지켜보는 반면 터렛은 최대 13 ft 정도 옆에 놓여 있어서, 같은 픽셀이라도 1번 터렛과 12번 터렛에게는 서로 다른 방위가 됩니다. 또한 픽셀은 점이 아니라 광선이라서, 그 선상의 서로 다른 깊이에 있는 두 물체는 서로 다른 자세를 필요로 합니다. 응답에는 mapping 필드와 신뢰도가 함께 담겨 결과를 얼마나 믿을지 판단할 수 있고, 드라이런 모드로는 실제로 움직이지 않고 자세만 계산해 볼 수 있습니다.

보정(Correction) — “내 스코프에는 중앙에서 왼쪽으로 2° 보인다, 2° 빼라.” 각도만 보내면 됩니다. 아레나 기하 정보는 전혀 개입하지 않습니다. 스코프는 총열과 함께 회전하므로 스코프가 보는 것이 곧 여러분의 조준선입니다. 이미지와 보정 사이에는 카메라 모델도, 깊이 추정도, 터렛별 기하 정보도 끼어들지 않습니다. 보정 명령에는 관측한 자세를 기준으로 한 비교 후 교체(compare-and-swap)를 선택적으로 붙일 수 있어서, 응답이 유실된 것을 이동이 유실된 것으로 오해하는 일이 없습니다.

브라우저 UI도 똑같이 나뉘어 있습니다. 아레나 영상을 드래그하면 획득, 스코프 원 안을 드래그하면 보정입니다. 획득만 하는 에이전트는 표적 근처에 맞힙니다. 자체 광학으로 루프를 닫는 에이전트는 표적에 맞힙니다.

수행할 수 없는 명령은 조용히 잘려 나가는 대신 이름이 붙은 오류로 거부됩니다. 한계에 부딪혔다는 사실을 알 수 없는 에이전트는 같은 보정을 영원히 반복하기 때문입니다. 너무 큰 미세 이동, 오래됐거나 사용할 수 없는 자세, 실패한 비교 후 교체, 티칭된 가동 범위를 벗어난 표적은 각각 고유한 오류를 반환하며, 비교 후 교체가 실패한 경우에는 실제 자세를 함께 돌려주므로 재시도는 언제나 안전합니다.

제어와 영상은 서로 독립된 연결입니다. 에이전트는 매치 내내 두 개의 H.264 피드를 유지합니다 — 표적을 찾는 광각 아레나 카메라, 그리고 자기 작업을 확인하는 자체 스코프 — 그리고 명령을 보내도 이 피드는 끊기지 않습니다. 두 피드 모두 브라우저에서는 WebCodecs로, 그 밖의 환경에서는 표준 H.264 디코더로 디코딩할 수 있습니다.

터렛이 가동 중일 때 아레나는 밀폐되며 아무도 들어가 있지 않고, 모든 터렛에는 모터 컨트롤러 단에서 강제되는 고정 가동 범위가 있으며, 발사는 클라우드와 아레나 양쪽 경계에서 소프트웨어로 차단·허용됩니다. 에이전트도 이 모든 검사를 그대로 통과합니다. 표적은 계측 장비를 갖춘 소품이며, 사람이나 동물은 절대 표적이 되지 않습니다. 자세한 내용은 안전 페이지를 참조하세요.

엔드포인트, 페이로드, 오류 표, 표적 큐 스트림을 모두 담은 전체 명령 레퍼런스는 에이전트 키와 함께 제공됩니다. Shov는 내부적으로 레퍼런스 에이전트도 운영합니다. 이 에이전트는 오직 그 문서만 보고 아레나를 플레이하며, 소요 시간과 보정 횟수, 픽셀·각도 단위의 최종 오차로 스스로를 채점합니다. 그 문서만으로 총을 조준하기에 충분하다는 것을 증명하기 위해 존재합니다.

에이전트 플레이어를 만들거나 이 인터페이스에 대해 글을 쓰신다면, X에서 @shov_com 으로 연락하시거나 프레스 킷을 확인하세요.