Ciclo de vida da batalha

Uma batalha é uma máquina de estados com um número fixo de assentos. A gravação, o feed ao vivo e o webhook penduram todos numa transição dessa máquina, então leia esta página antes das páginas de API.

Os seis estados

OPEN aceita jogadores, RUNNING significa assentos gravando, e os três estados restantes são terminais.

As transições são negadas por padrão nas duas direções: um estado sem saída registrada não transiciona, e um destino não listado é recusado. Uma transição recusada deixa o status intacto, em vez de errar para um estado meio aplicado.

De	Pode virar
OPEN	STARTING, CANCELLED
STARTING	RUNNING, COMPLETED, FAILED
RUNNING	COMPLETED, FAILED
COMPLETED / FAILED / CANCELLED	nada, terminal

STARTING chega a COMPLETED ou FAILED sem passar por RUNNING quando um lançamento se resolve ou falha antes de qualquer assento começar a gravar. As duas arestas são alcançáveis.

Assentos

Uma batalha tem entre 2 e 8 assentos, fixados na criação. Cada assento roda o próprio ciclo, independente do da batalha.

Status do assento	Significado
EMPTY	Ninguém nele
FILLED	Reivindicado, mas sem sessão de jogo, então não pode jogar
READY	Reivindicado com URL de sessão, então pode jogar
PLAYING	Gravação em andamento
DONE	Gravação terminada, desfecho conhecido

FILLED não é READY. Um assento só vira READY quando tem uma URL de sessão de jogo, e é por isso que o assento do criador pode cair em qualquer um dos dois estados.

O assento do criador

Criar uma batalha senta o criador no índice 0. Um campo decide se esse assento cai em FILLED ou READY:

• creator_game_url informado: assento 0 é READY
• creator_game_url omitido: assento 0 é FILLED, e o criador precisa informar a URL depois

Uma batalha de dois assentos criada sem creator_game_url portanto não inicia sozinha quando o outro jogador entra, porque o assento 0 continua FILLED.

Início automático

Não existe endpoint de início. O lobby começa sozinho no momento em que todos os assentos estão READY, verificado a cada mudança de assento. Uma lista vazia de assentos nunca satisfaz a checagem, então uma batalha de zero assentos nunca inicia sozinha.

As três formas de chegar a STARTING são portanto todas mudanças de assento:

1. O último jogador humano ocupa o último assento.
2. O criador preenche os assentos restantes com bots.
3. Um jogador com assento FILLED promove para READY informando uma URL.

O que acontece em RUNNING

Na transição, o SlotBattle despacha um gravador por assento, cada um uma invocação isolada rodando um browser headless contra o jogo de verdade. Os assentos se coordenam por barreiras no Redis, para começarem a girar juntos em vez de derivarem pelo tempo que cada browser levou para subir.

Cada gravador captura seu assento em vídeo HLS e envia os segmentos conforme são produzidos, o que é o que permite à plateia assistir a um assento enquanto ele ainda está girando. Cada gravador reporta o resultado terminal do seu assento por um callback interno assinado, e o SlotBattle agrega todos eles em exatamente um evento terminal de batalha.

O control plane nunca toca num browser nem num encoder de vídeo. Veja Arquitetura.

Chegando a um estado terminal

Estado terminal	Como a batalha chega lá
COMPLETED	Todos os assentos reportaram
FAILED	O lançamento falhou, um assento falhou sem recuperação, ou a janela de execução expirou
CANCELLED	O criador cancelou, o criador saiu, ou a janela do lobby expirou com a batalha ainda OPEN

Cancelar é só do criador e só em OPEN. Um não-criador pedindo cancelamento é recusado, e cancelar uma batalha que já começou também. Um criador que sai cancela a batalha: sair não passa o lobby para outra pessoa. Um não-criador que sai libera o próprio assento de volta para EMPTY.

As três janelas

Três TTLs limitam quanto tempo uma batalha pode ficar num estado não terminal. Uma varredura em background reconcilia o que passar do prazo.

Janela	Limita	Estouro vira
Lobby	Quanto tempo um lobby OPEN aceita jogadores	CANCELLED
Starting	Quanto tempo uma batalha pode ficar em STARTING	FAILED
Execução	Quanto tempo uma batalha RUNNING pode levar	FAILED

São os únicos valores de ajuste mutáveis em runtime, pelo console admin, nas configurações lobby com escopo de plataforma. Valem a partir da próxima batalha, não do próximo deploy.

Zero significa "use o padrão", nunca "expire agora"

Um campo de formulário não tocado envia zero, e ler isso literalmente fecharia todo lobby no instante em que ele abrisse. O formulário, o resolvedor e o serviço recusam zero como janela, cada um de forma independente.

Duas regras que moldam integrações

Uma batalha ativa por jogador, por casino. Um jogador já sentado numa batalha não terminal não pode criar nem entrar em outra no mesmo tenant. A tentativa é recusada, e não concedida como segundo assento.

URLs de sessão de jogo nunca saem do processo. A URL que permite a um browser jogar uma sessão de dinheiro real é criptografada em repouso e não aparece em nenhuma resposta HTTP, linha de log, frame de WebSocket, mensagem de pub/sub ou webhook. A API nunca a expõe. Veja Chaves e credenciais.

Próximo

• Eventos: o que cada transição emite, e quais eventos o seu front end enxerga
• Arquitetura: o que roda onde durante RUNNING
• API de batalhas: os endpoints que dirigem essa máquina