Arquitetura e componentes do SDK do PlayServ
Última atualização: 16 de julho de 2026
O PlayServ é estruturado como um conjunto de componentes agrupados em quatro camadas. Entender essa estrutura ajuda você a encontrar a ferramenta certa para cada tarefa — seja configurar uma Session, consultar dados, rodar lógica no servidor ou montar uma Room de multiplayer.
Quatro camadas
O mapa de componentes é organizado de cima para baixo: as camadas superiores dependem das inferiores.
Basic Components formam a fundação. Todas as outras camadas são construídas sobre eles. É aqui que ficam o acesso a dados, as consultas, as Subscriptions, os comandos RPC, os Events e o estado da Session.
Platform Components definem o contexto de runtime. Session, autorização e configuração do SDK ficam aqui — são eles que dão ao cliente a sua identidade e o seu estado operacional antes que o gameplay possa começar.
Application Components oferecem funcionalidades de nível de produto construídas sobre a fundação. Groups e Rooms vivem nesta camada.
Gameplay Components são módulos voltados ao jogo que consomem dados e estado — normalmente a última camada antes do código do jogo. Eles podem aplicar padrões como interpolação e predição.
Camada Platform
Session
A Session é o contexto de runtime em que o cliente opera. Ela guarda o estado atual — Offline, Recovering, Active ou Banned — e conduz a forma como o cliente transita por reconexão e operação ativa. Todo o resto do SDK depende de haver uma Session. Para entender como o cliente se move entre esses estados e o que cada um significa para o seu jogo, leia o guia Session Lifecycle & States.
Authorisation
A autorização representa o nível de privilégio da Session atual. Uma Session não autenticada começa com acesso mínimo. Passar um UserToken a eleva, vinculando a Session a um perfil de usuário e liberando operações protegidas. Como e quando passar esse token está em User Login & Authentication.
SDK configuration
A configuração do SDK guarda as credenciais e os ajustes que permitem ao runtime identificar o Project e o Environment corretos. Se você ainda não configurou as credenciais do seu Project, SDK Initialisation & Handshake mostra o que é cada entrada, de onde ela vem e como configurá-la no Unity.
Camada Application
Group (Room)
Groups organizam as conexões dos clientes e viabilizam comunicação em broadcast e rastreamento de presença. Um Group fica acima da camada básica e a utiliza para sinalização e comportamento no servidor — incluindo fluxos extensíveis de join e leave. Como criar, entrar e estender Groups com regras próprias no servidor está no guia Groups.
Camada Basic
Model, Query & Schema
O Model é o ponto de entrada para as operações sobre os dados do jogo. Ele liga o código do cliente às consultas, filtros, mutações e Subscriptions. A Query cuida da construção e da filtragem das requisições de dados. O Schema define a estrutura dos dados e as relações entre objetos — é o que torna possível a busca aninhada e a expansão automática de relações. A sintaxe completa de consulta está descrita em Query Language & Data Retrieval.
PubSub
O PubSub é o mecanismo de Subscription que move as atualizações ao vivo. Quando os dados mudam no servidor, os Deltas são entregues imediatamente aos clientes inscritos. A primeira entrega é um snapshot completo; as atualizações seguintes são Deltas em JSONPatch aplicados automaticamente. Se você quer manter uma cópia local dos dados do servidor em sincronia sem ficar consultando, Data Subscriptions & Live Updates explica como.
Entity
A Entity oferece uma visão dos dados e do comportamento centrada na entidade. Ela fica entre o acesso a dados e os comandos, e é o que torna possível anexar comportamento de domínio — como player.Shoot() — na forma de métodos RPC nomeados sobre um tipo de Model. Como persistir mudanças de campo e estender Models com métodos próprios está em Data Mutation & Model Extending.
Command (RPC)
O Command é o mecanismo para executar operações nomeadas no servidor. O código de servidor é escrito dentro do codebase do cliente, descoberto pelo analisador de código e implantado no runtime do servidor. O código do cliente o chama via PlayServ.Remote(...). O modelo de execução completo está descrito em RPC & Server-side Game Logic.
Event
O Event é o mecanismo de sinalização tipado compartilhado pelos dois lados. Um Event é declarado com [Event], enviado via Send(...) ou pelo açúcar gerado, e recebido via Wait<T>(...). O mesmo contrato fica disponível no cliente e no servidor graças à geração automática das classes de descrição do Event. Para a API completa, veja o guia Events System.
State
O State é a camada de estado usada por baixo pelos recursos de runtime. As transições de estado da Session — Offline → Recovering → Active — são o seu uso mais visível, mas ele também sustenta outros componentes do SDK. Os estados e como assiná-los estão descritos em Session Lifecycle & States.
Caminho da conexão
O mapa de componentes descreve componentes lógicos. O ponto de entrada físico — como o cliente de fato se conecta ao PlayServ — é tratado à parte pelo Proxy e pelo fluxo de handshake. É ali que os tokens são validados, a política de conexão é aplicada e o ClientReady é emitido antes que os sistemas de gameplay possam começar com segurança. Se você quer entender o que acontece entre chamar PlayServ.Ready(...) e a Session chegar a Active, o guia Proxy Module & Handshake cobre esse fluxo em detalhe.
Próximos passos
Siga esta ordem de leitura para ir da configuração até uma primeira Session ativa:
- SDK Initialisation & Handshake — configure as credenciais do seu Project e coloque o SDK para rodar
- Proxy Module & Handshake — como o cliente se conecta e chega ao
ClientReady - Session Lifecycle & States — as transições
Offline→Recovering→Active - User Login & Authentication — eleve a Session com um
UserToken