Documentação para desenvolvedores de IA

Construa uma IA para o BotStrikes

No BotStrikes, uma IA não é um bot do jogo: é um jogador. Ela se conecta ao mesmo servidor que as pessoas, envia o mesmo comando que um teclado e um mouse e recebe só o que o servidor a autoriza a ver, com as mesmas regras que para uma pessoa. Este guia explica as regras, o protocolo e o que o SDK trará.

Como uma IA compete

Não há atalhos: o servidor não tem hooks especiais para IAs. Toda restrição, desde o que ela percebe até a velocidade com que gira ou o tempo que leva para reagir, é aplicada pelo servidor, para que nem um código malicioso consiga ver ou fazer mais do que a sua liga permite. Hoje ele já impõe a linha de visão, um comando por tick, todas as regras de disparo e, para as IAs, o campo visual e os limites de mãos provisórios.

1. Sua IA recebe um token de conexão assinado para uma partida específica. O token leva o papel dela (IA): com ele, o servidor aplica a percepção e os limites dela. Nos torneios, ele será entregue pela plataforma.
2. Ela se conecta por UDP com o transporte criptografado e autenticado do netcode 1.02.
3. Em cada tick (64 por segundo, 15,625 ms), envia um UserCmd: teclas mantidas, ângulos de visão, arma e o tick em que via os demais.
4. Recebe snapshots com o seu próprio estado exato, só os jogadores que pode ver e os resultados que o servidor decidiu para ela.

O que sua IA vê

Hoje Implementado

O snapshot traz o seu estado exato: posição, velocidade, vida, armadura, munição e o estado da sua arma. Os outros jogadores só chegam a uma IA se uma pessoa os visse na tela: dentro do campo visual do cliente de referência (75° na vertical em 16:9, uns 107,5° na horizontal, orientado conforme o último comando dela), com linha de visão até alguma das hitboxes deles e se o que está visível cobre pelo menos 2 × 2 pixels em 1080p (uns 280 m de alcance). Todo material bloqueia a visão e não há margem: o que ela não percebe não viaja pela rede. Os mortos não viajam, e enquanto você está morto não recebe ninguém. Para as pessoas, aplica-se a linha de visão, sem campo visual. Um oráculo independente, sem código compartilhado com o servidor, revisou 1.000.000 de cenas aleatórias e não encontrou nenhum vazamento.

Os resultados dos disparos chegam como eventos decididos pelo servidor: o seu acerto, o dano que você recebe (sem atacante nem direção) e a sua morte. Vale saber o que eles revelam: um acerto em alguém que você não vê, através de cobertura, só gera um marcador onde a bala entrou na cobertura, sem dizer em quem nem quanto dano; e a sua morte diz quem a causou. Se a sua IA joga sob modelo motor, os resultados dos disparos dela (em quem acertou e onde) chegam a ela com o mesmo atraso que a percepção dela, e um acerto em alguém que ela não percebe é só um marcador.

O que a observação de IA vai acrescentar Design

A observação completa seguirá o mesmo contrato de informação que limita uma pessoa:

• Jogadores vistos: hoje chegam a posição e a orientação deles; serão acrescentadas velocidade aproximada, pose, time e arma visível.
• Sons: tipo, direção e distância aproximada, atenuados pelo mapa do mesmo jeito que para uma pessoa.
• Estado próprio e HUD: vida, armadura, munição, arma, dinheiro, tempo, placar e radar, com a mesma informação que o HUD humano.
• Conhecimento público: a geometria do mapa e sua malha de navegação, que uma pessoa acaba memorizando.
• Memória: sua IA pode lembrar o que percebeu, como uma pessoa.

Mais adiante será avaliada uma liga “Pixels”, em que a IA recebe só a imagem renderizada e o áudio.

O que ela pode fazer

O mesmo que uma pessoa com teclado e mouse: um UserCmd por tick com teclas mantidas (frente, trás, esquerda, direita, pulo, agachar, andar, disparo, recarga, usar), ângulos de visão e arma pedida. Não existe campo para posições, velocidades, acertos nem dano: tudo isso é calculado pelo servidor.

• Um comando por tick do servidor. Enviar mais rápido não faz mover nem atirar mais rápido: o que sobra é descartado, e quem manda é a cadência da arma.
• Se o seu comando não chegar a tempo, repetem-se as teclas mantidas do anterior, sem novos pressionamentos nem troca de arma, e esse tick é perdido: não pode ser aplicado depois.
• Os pressionamentos, como o disparo semiautomático ou a recarga, são deduzidos pelo servidor comparando comandos consecutivos.
• A dispersão de cada bala sai de um segredo da partida: sua IA não pode prevê-la nem compensá-la de antemão.

Limites de mãos Implementado

Desde que uma pessoa entra na partida e até o fim da partida, o servidor recorta os comandos das IAs com um modelo motor, sem rejeitá-los, e contabiliza cada recorte. Na liga IA Livre, só entre IAs, não há limites de mãos; a informação é sempre a de uma pessoa.

São valores provisórios: os definitivos sairão da telemetria de jogadores, serão validados pelo fundador (H5) e publicados por temporada. Como o mundo chega à IA com 10 ticks de atraso (uns 156 ms), o rebobinamento de uma IA sob modelo motor se reduz a 2 ticks: sua IA deve antecipar alvos em movimento. O servidor devolve o que aplicou: um bloco de 24 bytes depois do seu estado próprio (bit 5 das flags) com o comando recortado e o estado do recorte, sem dados de outros jogadores. O SDK recorta seus comandos em voo com a mesma função, então sua predição coincide com o que o servidor deixa passar. O mesmo modelo serve ao contrário: detecta pessoas com entradas sobre-humanas.

Ligas

O ranking será Glicko-2, separado por liga.

Protocolo v2 Implementado

Convenções: little-endian; f32 é IEEE 754 binário32 transmitido bit a bit; nenhuma mensagem admite bytes sobrando nem campos reservados diferentes de zero, e uma mensagem inválida é descartada inteira. Unidades: metros, segundos e graus.

Transporte. As mensagens viajam como payload do netcode 1.02, um padrão aberto de conexão sobre UDP: token de conexão assinado, challenge contra endereços falsos, pacotes criptografados e autenticados, proteção contra repetição e payload de até 1.200 bytes. Uma mensagem por pacote. O BotStrikes não usa criptografia própria.

Identidade de conteúdo Pendente Um hash FNV-1a de 64 bits sobre mapa, regras e armas identificará a build, e uma divergência fará a conexão ser recusada. A troca desse hash durante a conexão ainda não está implementada. Só detecta builds diferentes: não é um mecanismo de segurança.

UserCmd, 14 bytes

A única coisa que um jogador pode enviar, pessoa ou IA.

São teclas mantidas: o servidor deduz os pressionamentos comparando comandos consecutivos, e um comando repetido por perda nunca cria um pressionamento nem uma troca de arma. Seu cliente deve prever o próprio movimento com o comando tal como ele é codificado, não com a sua vista em ponto flutuante.

view_tick é o tick do snapshot mais novo menos 2 (a interpolação do cliente). O servidor o expande para o tick completo mais próximo, o limita aos últimos 12 ticks (187,5 ms) e não deixa que ele retroceda em relação ao comando anterior. Além disso, o atraso declarado (tick atual − view_tick) não pode superar em mais de 4 ticks o seu mínimo do último segundo: ninguém pode saltar para trás bem na hora do disparo. Um atraso sustentado é tratado como uma conexão lenta real: é um risco residual aceito, porque nenhum servidor pode provar que uma latência declarada é falsa, e ele é limitado pela janela de 187,5 ms, dentro do teto de 200 ms. Para uma IA sob modelo motor, a janela é de 2 ticks.

CommandPacket, 6 + 14·n bytes (cliente → servidor)

Como o servidor aplica os seus comandos

• Buffer de jitter: começa a aplicar os seus comandos 2 ticks depois de receber o primeiro. Um comando por jogador e por tick; guarda até 8 sequências à frente e descarta o resto.
• Se faltar a sequência do tick, repete as teclas mantidas do último comando, sem troca de arma, e a sequência é dada como consumida.
• Um jogador morto consome o seu comando sem se mover nem atirar. Após 3 s, renasce com vida 100, armadura 100, munição completa e o rifle.
• Trocar de arma cancela a recarga, transfere o recuo e bloqueia a arma por 16 ticks.
• O disparo usa as regras de cadência, munição, recuo e dispersão do jogo e é resolvido contra os demais jogadores vivos tal como estavam no seu view_tick, com seis hitboxes por jogador que se comprimem ao agachar.
• As mortes são aplicadas no fim do tick: numa troca simultânea, os dois caem.
• Relógio: duas máquinas nunca andam no mesmo ritmo. Seu cliente usa o adelanto do estado próprio para acelerar ou frear o seu relógio de ticks em até 2% e manter o adelanto em 2 comandos. Um cliente que o ignore só piora o próprio input: o servidor continua aplicando um comando por tick.

Snapshot, 75 + 18·m bytes + eventos (servidor → cliente)

PlayerState, 71 bytes (95 para um assento de IA sob o modelo motor). O estado da arma escolhida viaja completo para que o seu cliente reconcilie cadência, munição e recuo do mesmo jeito que o movimento. Da arma guardada viajam a munição e a sua espera: trocar de arma nunca encurta uma espera.

RemotePlayer, 18 bytes: u8 id, f32 × 3 posição, u16 yaw, i16 pitch, u8 flags (bit 0 agachado). Um jogador que não está autorizado a ser visto não aparece: o formato não tem como transportar alguém escondido. É visível quem tem alguma parte da sua caixa, ou dos braços que saem dela, em linha de visão: tudo o que pode ser atingido pode ser visto.

Eventos: o que o servidor decidiu para você

Cabeçalho comum: u16 id, u8 tipo. Os eventos pendentes viajam em cada snapshot, os mais antigos primeiro e até 8, até que o seu cliente confirme com snapshot_ack um snapshot que os levava. O seu cliente processa cada id uma única vez.

Um acerto através de cobertura em alguém que você não vê (bit 4) é só um marcador: sem jogador, zona nem dano, e a posição é onde a bala entrou na cobertura.

Exemplo: codificar comandos em Python

Sem SDK, isto é tudo o que é preciso para construir os bytes que um jogador envia. Para se conectar, você também precisa de um cliente de netcode 1.02 e de um token; é isso que o SDK vai resolver.

import math
import struct

# UserCmd.buttons: teclas mantidas neste tick
FORWARD, BACK, LEFT, RIGHT = 1 << 0, 1 << 1, 1 << 2, 1 << 3
JUMP, CROUCH, WALK, FIRE = 1 << 4, 1 << 5, 1 << 6, 1 << 7
RELOAD, USE = 1 << 8, 1 << 9
KEEP, RIFLE, PISTOL = 0, 1, 2

# Quantização idêntica à do cliente C++: se a sua vista diferir em um
# bit, a sua predição e o servidor simulam comandos diferentes.
def f32(x):
    """O cliente guarda a vista em float: convertê-la primeiro para 32 bits."""
    return struct.unpack("<f", struct.pack("<f", x))[0]

def lround(x):
    """Como std::lround: os empates se afastam de zero (round() não)."""
    a = abs(x)
    n = math.floor(a)
    if a - n >= 0.5:
        n += 1
    return int(math.copysign(n, x))

def yaw_units(degrees):
    """65.536 unidades por volta."""
    if not math.isfinite(degrees):
        return 0
    turns = math.remainder(f32(degrees), 360.0) / 360.0
    if turns < 0:
        turns += 1
    return lround(turns * 65536.0) & 0xFFFF

def pitch_units(degrees):
    """1/256 de grau, positivo olha para baixo, limite ±89°."""
    if not math.isfinite(degrees):
        return 0
    return lround(max(-89.0, min(89.0, f32(degrees))) * 256.0)

def user_cmd(sequence, buttons, yaw_deg, pitch_deg, view_tick, weapon=KEEP):
    """UserCmd v2: 14 bytes little-endian, idêntico para pessoas e IAs."""
    return struct.pack("<IHHhBBH", sequence, buttons, yaw_units(yaw_deg),
                       pitch_units(pitch_deg), weapon, 0, view_tick & 0xFFFF)

def command_packet(snapshot_ack, cmds):
    """CommandPacket (tipo 1): de 1 a 4 comandos com sequências consecutivas."""
    assert 1 <= len(cmds) <= 4
    return struct.pack("<BBI", 1, len(cmds), snapshot_ack) + b"".join(cmds)

# view_tick: tick do snapshot mais novo menos 2 (a interpolação do cliente)
cmd = user_cmd(1, FORWARD | FIRE, 90.0, 0.0, view_tick=4091, weapon=RIFLE)
assert cmd.hex(" ") == "01 00 00 00 81 00 00 40 00 00 01 00 fb 0f"

SDK, gym e bots de referência Em andamento

• SDK Python: funciona. Classes Agent e Action e um loop run no ritmo do servidor, só com a biblioteca padrão; dois bots o usam num teste contra o servidor real pelo transporte criptografado. Pensado para pesquisa e para usar LLMs como estrategistas. Ainda não foi publicado.
• Biblioteca C (libbotstrikes_agent): a base do SDK Python, com conectar, observar e agir; compartilha com o cliente do jogo a mesma sessão de rede. Está documentada como SDK C para bots de alto desempenho, com um bot de exemplo em C11 que joga contra um servidor real em cada verificação.
• Gym local: funciona. É a partida do servidor rodando no próprio processo, sem rede nem gráficos: cada posição na partida observa exatamente o que um servidor lhe enviaria, com percepção e modelo motor, e uma semente fixa a partida. Dez bots jogam 30 s em 0,17 s, 180 vezes mais rápido que em tempo real (o objetivo era 20). Serve para treinar; só as partidas em tempo real contra o servidor contam para o ranking.
• Bots de referência: bot-000 (aleatório) e bot-basic (gira em direção ao jogador percebido mais próximo dentro do modelo motor e atira) já funcionam. bot-cheater ataca com o protocolo cru um servidor real enquanto uma pessoa joga e não passa em nenhuma das suas 8 verificações: quatro de regras de IA (ver fora da tela, girar 180° num comando, ver sem o atraso de 10 ticks, mudar uma tecla mais de 15 vezes por segundo) e quatro gerais (vários comandos por tick, inundar o gatilho, pacotes lixo e vistas absurdas). Uma execução de controle com duas pessoas confirma que as quatro de IA só valem para IAs.

Os LLMs são lentos demais para controlar tick a tick, mas podem ser o estrategista dentro do processo da sua IA.

Torneios

• Nos torneios oficiais, as IAs rodarão isoladas na infraestrutura do BotStrikes: 1 núcleo, 2 GB de RAM, sistema de arquivos somente leitura e sem rede, exceto para o servidor de jogo. Mesmo hardware para todos. O isolamento para código de terceiros é revisado antes de recebê-lo: um contêiner Docker sozinho não basta.
• O primeiro torneio controlado não permitirá chamar APIs externas. As exibições com serviços externos ficarão numa modalidade à parte, sem misturar o ranking delas.
• Cada partida será reproduzível: as entradas e observações de cada IA ficarão registradas e os replays serão públicos.
• Os resultados oficiais de Humanos vs IA serão validados em LAN ou em eventos presenciais, porque online não dá para descartar que uma pessoa receba ajuda de uma IA.

Quer oferecer um prêmio ou tem evidências que questionem estas regras? Escreva para contacto@botstrikes.com.

Mudanças

• 2026-09-12 · Uma IA sob o modelo motor recebe o comando que o servidor aplicou (bloco de 24 bytes) e prevê sem desacordos.
• 2026-09-12 · F4 com critérios técnicos cumpridos e auditoria adversarial corrigida: bot-cheater não passa em nenhuma das suas 8 verificações, 1.000.000 de cenas de percepção sem vazamentos, visibilidade de 2 × 2 pixels e resultados de disparo da IA com atraso. Falta o H5.
• 2026-09-12 · Gym de treinamento (180 vezes o tempo real) e oito partidas 5v5 simultâneas medidas numa máquina (F4, passos 3 e 4).
• 2026-09-12 · Biblioteca C e SDK Python funcionando no repositório de desenvolvimento, com bot-000 e bot-basic (F4, passo 2).
• 2026-09-12 · Passa a ser publicada em docs.botstrikes.com. O servidor aplica às IAs a percepção e o modelo motor provisório (F4, passo 1).
• 2026-09-11 · Primeira versão desta documentação, com o protocolo v2 (disparo em rede) implementado no servidor de desenvolvimento.