Match Coordinator
O Match Coordinator é o microserviço responsável por gerenciar o ciclo de formação de partidas na plataforma Tacthub.
Ele permite que aplicações cliente integrem fluxos de matchmaking sem precisar implementar por conta própria a lógica de fila, composição de grupos, confirmação de partida e comunicação em tempo real com os jogadores.
O que este serviço faz
Ao integrar com o Match Coordinator, sua aplicação pode delegar ao serviço responsabilidades como:
- entrada e saída de jogadores na fila
- organização de grupos
- composição de partidas conforme as regras do modo de jogo
- confirmação de participação
- notificação de eventos em tempo real
- registro de histórico de partidas, como vitórias, derrotas e abandonos
Como a integração funciona
A integração com o serviço é baseada em dois mecanismos principais:
API HTTP
A API HTTP é usada para executar ações no sistema, como:
- entrar na fila
- cancelar busca
- criar ou gerenciar grupos
- confirmar ou recusar uma partida
- iniciar, finalizar ou abandonar jogos
Server-Sent Events (SSE)
A comunicação em tempo real é feita por meio de SSE (Server-Sent Events).
Sua aplicação deve manter uma conexão SSE ativa para receber eventos como:
- partida encontrada
- solicitação de confirmação
- atualizações de estado
- eventos relacionados ao ciclo da partida e do jogo
Autenticação e identificação do jogador
O serviço utiliza autenticação via Bearer Token (JWT).
O usuário deve estar previamente autenticado na plataforma por meio do serviço de identidade. O Match Coordinator não gerencia cadastro, login ou perfil de usuário diretamente.
A identificação do jogador é feita a partir do campo sub do token JWT. Esse identificador é utilizado internamente para:
- associar o jogador à fila
- relacionar o jogador a grupos e partidas
- direcionar eventos SSE
- registrar o histórico de participação
Presença online
No Match Coordinator, o estado de presença do jogador é determinado pela conexão SSE.
Quando o cliente mantém uma conexão SSE ativa, o jogador pode ser tratado como online para fins de comunicação em tempo real. Se essa conexão for perdida, o serviço pode considerar o jogador indisponível em etapas sensíveis do fluxo, como durante a confirmação de partida.
Por esse motivo, recomenda-se que a aplicação cliente:
- estabeleça a conexão SSE antes de iniciar fluxos de matchmaking
- implemente reconexão automática
- trate perda de conexão como evento relevante de integração
O que você encontrará nesta documentação
Esta documentação está organizada para ajudar desenvolvedores a integrar suas aplicações com o serviço.
Getting Started
Guia inicial de integração, incluindo:
- autenticação
- conexão SSE
- primeiros endpoints
- fluxo mínimo de uso
API
Referência dos endpoints HTTP e da especificação OpenAPI.
Matchmaking
Explicação do fluxo de formação de partidas, regras de composição, confirmação e transições de estado.
Eventos
Catálogo dos eventos enviados em tempo real, com descrição e exemplos de payload.
Exemplos
Cenários práticos de integração, incluindo fluxos comuns e situações de falha.
Leitura recomendada
Se esta é sua primeira integração com o Match Coordinator, a ordem sugerida de leitura é:
- Getting Started
- SSE
- Eventos
- Matchmaking
- API
Resumo
O Match Coordinator centraliza a lógica de matchmaking da plataforma e fornece uma interface de integração baseada em API HTTP para ações e SSE para eventos em tempo real.
Com isso, sua aplicação pode focar na experiência do usuário e delegar ao serviço a coordenação da fila, das partidas e do ciclo de confirmação.