Pular para o conteúdo principal

Grupos

Última atualização: 14 de setembro de 2026

Um grupo é um canal nomeado de eventos. Uma conexão assina um grupo pelo nome, e tudo o que é publicado nesse grupo é entregue a todos os assinantes. É como você espalha uma mensagem para um conjunto de clientes de uma vez — um chat de lobby, um sinal de "jogador pronto", um broadcast para todos em uma sessão — sem conhecê-los individualmente.

Grupos são construídos diretamente sobre o sistema de Events: um grupo é apenas um escopo de roteamento para o mesmo publish/subscribe que você já usa para eventos.

informação

A participação em um grupo tem escopo de conexão. Você assina em uma conexão ativa e permanece membro enquanto essa conexão viver; não há roster armazenado nem um "sair do grupo para sempre" explícito. Se a conexão cair, a assinatura cai junto — e o SDK reassina você aos seus grupos automaticamente após uma reconexão transparente.

observação

Um grupo é um canal de mensagens, não uma sala de jogo com assentos. Se você quer que a plataforma aloque jogadores e mantenha uma partida ao vivo — tickets de reserva, capacidade, um game server — veja Conectando-se a um Jogo. As salas de jogo são, na verdade, construídas sobre grupos: uma sala transmite aos seus jogadores publicando em um grupo.

O modelo​

Dois verbos cobrem quase tudo: assinar um grupo para receber seus eventos e publicar em um grupo para enviar um.

PublicadorPublishForGroupGrupo"lobby-42"AssinanteAssinanteAssinantepublicarroteado a cada assinante

Entrar e sair​

Assine um grupo para começar a receber seus eventos e cancele a assinatura para parar. Ambos são awaitable e retornam se o comando teve sucesso.

await PlayServEvents.SubscribeGroupAsync("lobby-42");
// ... mais tarde
await PlayServEvents.UnsubscribeGroupAsync("lobby-42");

Você não precisa cancelar a assinatura ao sair: como a participação está atrelada à conexão, fechar a conexão remove você de todos os grupos. Cancelar a assinatura serve para quando você quer sair de um grupo permanecendo conectado. Os comandos de grupo têm um timeout curto (10 segundos) — uma assinatura que falha surge como PlayServGroupSubscriptionException.

observação

Não há etapa de aceitar/rejeitar no servidor nem roster de participantes. Assinar é uma instrução de roteamento, não um pedido que o servidor julga — qualquer um conectado ao seu projeto pode assinar qualquer nome de grupo dele. Coloque a autorização nos eventos que você publica, ou proteja ações sensíveis atrás de cloud functions, não atrás da participação em um grupo.

Publicar em um grupo​

Publique um evento tipado e cada assinante atual o recebe:

PlayServEvents.PublishForGroup("lobby-42", new ChatMessage { Text = "gg" });

O evento é entregue como um envelope GroupEventMessage que carrega o nome do grupo, o nome do tipo de evento e o payload JSON; os assinantes o recebem tipado. Além da variante de grupo, há dois envios relacionados:

  • Publish<T>(evt) — publica sem escopo de grupo.
  • PublishForUser<T>(userId, evt) — entrega às conexões de um usuário específico.

Receber eventos​

Assine um tipo para tratar os eventos que chegam de qualquer grupo em que você entrou:

PlayServEvents.Subscribe<ChatMessage>(msg => {
    // renderizar msg.Text
});

Subscribe<T> retorna um IDisposable que você descarta para parar de ouvir (há também uma sobrecarga IObservable<T> e SubscribeRaw<T> para o JSON bruto). O recebimento é por tipo de evento — entrar no grupo decide quais eventos chegam até você; a assinatura do tipo decide como você os trata.

Nomes de grupo têm escopo do seu projeto​

Um nome de grupo é automaticamente isolado por projeto, então "lobby-42" no seu projeto nunca pode colidir com — ou ser assinado a partir de — outro projeto. Tentar assinar um nome fora do escopo do seu projeto falha com GroupOutsideProject.

Limites​

LimiteValor
Grupos por conexão64
Tamanho do nome do grupoaté 256 caracteres

Exceder a contagem por conexão faz a assinatura falhar com GroupSubscriptionLimitReached. O teto é por conexão, então ele limita o fan-in de um cliente, não a quantidade de grupos que seu projeto pode ter.

O que grupos não são​

Para deixar claro, grupos deliberadamente não oferecem:

  • Presença / lista de membros — não há consulta de "quem está neste grupo" nem eventos SomeoneJoined / SomeoneLeft. A participação não é rastreada como estado; é um conjunto de roteamento ao vivo. Se você precisa de presença, modele-a você mesmo publicando um evento "olá"/"tchau", ou use o próprio roster de sala do game server.
  • Aceitar/rejeitar no servidor ao entrar — assinar não é recusado por usuário.
  • Fechar / encerrar — você não fecha um grupo; ele simplesmente fica sem assinantes quando todos se desconectam ou cancelam a assinatura.

Próximos passos​

Etiquetas:
Última atualização em