Pular para o conteúdo principal

Conectando um Project ao Unity

Última atualização: 5 de agosto de 2026

Depois que o Project foi criado no PlayServ Backoffice, o próximo passo é conectá-lo ao Unity. Importe o pacote do SDK, informe as credenciais do Project, sincronize o Schema para gerar os Models e adicione um pequeno script de bootstrap — feito isso, o projeto Unity está pronto para se conectar ao PlayServ.

Antes de começar​

Antes de conectar o SDK no Unity, garanta que você já tem:

  • Unity 2021.3 ou mais recente (o Unity 6 é o das capturas de tela abaixo)
  • um Project criado no PlayServ Backoffice — veja Creating a New Project
  • uma key Client para usar como Game Access Token — veja API Key Management
  • o Game ID do Project
observação

A configuração fica na janela de controles do editor do PlayServ dentro do Unity, usando as credenciais geradas no Backoffice. A janela as resolve através do config asset do Project (Assets/Resources/PlayServConfig.asset).

Importe o SDK​

Importe o SDK do PlayServ no seu projeto. O Unity recompila os scripts depois da importação — espere a barra de progresso Compiling Scripts terminar antes de continuar.

Abra Assets ▸ Import Package ▸ Custom Package…, selecione playserv-unity-sdk-<version>.unitypackage, mantenha tudo marcado no diálogo Import Unity Package e clique em Import.

Diálogo de importação de pacote do Unity com o SDK do PlayServ
observação

Importado dessa forma, o SDK fica em Assets/playserv-unity-sdk e o Unity não lê o manifesto do próprio pacote. Se com.unity.nuget.newtonsoft-json não for instalado automaticamente, adicione "com.unity.nuget.newtonsoft-json": "3.2.2" ao Packages/manifest.json.

Configure os controles do editor do PlayServ​

Abra a janela PlayServ editor controls em Tools ▸ PlayServ ▸ Settings. É o único lugar para gerenciar a identidade de runtime, sincronizar Models e implantar código de servidor, com um atalho para o Dashboard do Backoffice. O cabeçalho mostra o Game ID atual e a SDK Version instalada.

A janela é organizada em seções:

  • Control Room → PlayServ Config — identidade de runtime, credenciais, endpoints fixos e o config asset do lado do Project
  • Server Code → Deployment — pré-visualize o fechamento do código RPC, sincronize a versão implantada e envie o pacote ZIP ao endpoint de deploy
  • Schema → Model Sync — verifique o Schema mais recente, compare timestamps e regenere os Models do lado do editor
  • Realtime → Events — gere a API de Events tipada e mantenha os contratos de payload próximos do runtime
  • Automation → Code Generation — gere DTOs sob demanda (opcionalmente de forma automática) e limpe a camada gerada quando precisar recomeçar

Um toggle no rodapé, Show this window on Unity startup, controla se a janela abre automaticamente, e Open Docs traz de volta para esta documentação.

Janela de controles do editor do PlayServ no Unity

Este guia usa PlayServ Config (abaixo) e Model Sync (Passo 3). As demais seções tratam de deploy de servidor e geração de código.

Em Control Room → PlayServ Config, preencha as credenciais do Project:

1

Confirme o config asset

O campo Config Asset deve apontar para Assets/Resources/PlayServConfig.asset. Se ele ainda não existir, a janela oferece criá-lo. Use Ping para localizá-lo na janela Project.

2

Informe o Game Access Token

Cole a key Client criada no Backoffice. Keys Client podem ser distribuídas com segurança em uma build do jogo — veja API Key Management.

perigo

Nunca use uma key Server como Game Access Token. Uma key Server extraída do binário do jogo dá a um atacante acesso total ao backend do seu Project.

3

Informe o Game ID e a versão

Defina o Game Id com o Game ID do seu Project, e o Game Version com a versão da sua build (por exemplo 1.0.0). Ative Allow Multiple Connections se uma mesma máquina abrir mais de um cliente — por exemplo, o play-in-editor junto com uma build.

aviso

Garanta que o token e o Game ID pertencem ao mesmo Project e ao mesmo Environment do PlayServ. Um token que não bate com o ID do Project impede o SDK de conectar corretamente.

dica

Se o seu fluxo trata o config asset como fonte da verdade, mantenha as credenciais nesta janela e não as sobrescreva de novo em componentes de cena, a menos que isso seja intencional.

Sincronize o Schema e gere os Models​

Os Models C# do lado do editor são gerados a partir do Schema do Project, que é a fonte da verdade. Sincronize-os antes de escrever código de gameplay.

1

Verifique mudanças no Schema

Em Schema → Model Sync, a janela consulta o servidor em busca de mudanças no Schema. Quando ela informar A newer schema is available, revise o Current schema e o Latest available schema — compare o hash e o timestamp de cada um.

2

Aplique o Schema mais recente

Clique em Apply New Schema para aceitar o Schema mais recente vindo do servidor.

3

Regenere os Models

Clique em Re-generate Models. Os Models gerados são escritos em Assets/Shared/Generated/Models.

dica

Use Check Updates a qualquer momento para ver se os seus Models locais estão atrás do Schema do servidor. Rode Re-generate Models de novo sempre que o Schema mudar no Backoffice.

Adicione um script de bootstrap à cena​

Com as configurações prontas, crie um script de bootstrap e anexe-o a um GameObject na cena. Esse script lê a configuração do PlayServ, aplica os ajustes do SDK, conecta quando a cena inicia e mantém a conexão disponível entre carregamentos de cena.

1

Crie um objeto de bootstrap persistente

Crie um GameObject vazio na primeira cena do projeto e chame-o de PlayServBootstrap. Um objeto de bootstrap persistente é um bom lugar para a lógica de conexão.

2

Anexe o script de bootstrap

Anexe o script abaixo ao objeto.

using System;
using System.Threading.Tasks;
using Playserv.Proxy.Common;
using Playserv.Wrapper;
using UnityEngine;
using UnityEngine.Serialization;

namespace Playserv.Examples
{
    /// <summary>
    /// Persistent bootstrap component for configuring and connecting PlayServ in samples.
    /// </summary>
    public sealed class PlayServBootstrapSample : MonoBehaviour
    {
        private static PlayServBootstrapSample _instance;

        [Header("Credentials")]
        [SerializeField] private string gameAccessToken = "your-token";
        [SerializeField] private string gameId = "game-001";
        [SerializeField] private string userId = "player-001";
        [SerializeField] private string gameVersion = "1.0.0";
        [SerializeField] private bool overrideCredentialsFromInspector;

        [Header("Resolved Endpoints (Read Only)")]
        [FormerlySerializedAs("remoteEndpoint")]
        [SerializeField] private string backendServerAddress = PlayServSettings.DefaultBackendServerAddress;
        [SerializeField] private string deployApiServerAddress = PlayServSettings.DefaultDeployApiServerAddress;
        [SerializeField] private string schemaApiServerAddress = PlayServSettings.DefaultSchemaApiServerAddress;

        [Header("Behavior")]
        [SerializeField] private bool autoConnect;
        [SerializeField] private bool disconnectOnDestroy = true;

        [Header("KeepAlive")]
        [SerializeField] private int keepAlivePingIntervalMs = 5000;
        [SerializeField] private int keepAlivePongTimeoutMs = 5000;

        private bool _isOwner;

        private void Awake()
        {
            if (_instance != null && _instance != this)
            {
                Destroy(gameObject);
                return;
            }

            _instance = this;
            _isOwner = true;
            DontDestroyOnLoad(gameObject);
            RefreshResolvedEndpointsPreview();
        }

        private void Start()
        {
            if (!_isOwner)
                return;

            Configure();

            if (autoConnect &&
                PlayServ.State != PlayServState.Online &&
                PlayServ.State != PlayServState.Connecting &&
                PlayServ.State != PlayServState.Handshaking)
            {
                _ = ConnectAsync();
            }
        }

        private void OnEnable()
        {
            if (!_isOwner)
                return;

            PlayServ.OnTransportError += OnTransportError;
        }

        private void OnDisable()
        {
            if (!_isOwner)
                return;

            PlayServ.OnTransportError -= OnTransportError;
        }

        private void OnDestroy()
        {
            if (_instance == this)
                _instance = null;

            if (_isOwner && disconnectOnDestroy)
                PlayServ.Disconnect();
        }

        private void OnValidate()
        {
            RefreshResolvedEndpointsPreview();
        }

        [ContextMenu("Configure SDK")]
        public void Configure()
        {
            var settings = BuildSettingsFromConfig();

            if (overrideCredentialsFromInspector)
            {
                settings.GameAccessToken = gameAccessToken;
                settings.GameId = gameId;
                settings.UserId = userId;
                settings.GameVersion = gameVersion;
            }

            settings.KeepAlivePingIntervalMs = keepAlivePingIntervalMs;
            settings.KeepAlivePongTimeoutMs = keepAlivePongTimeoutMs;

            PlayServ.Config(settings);
            ApplyResolvedEndpointsPreview(settings);
            Debug.Log(
                $"[PlayServ][Sample] Configured. gameId={settings.GameId}, credentialsSource={(overrideCredentialsFromInspector ? "inspector" : "config")}, backend={settings.BackendServerAddress}, pingInterval={settings.KeepAlivePingIntervalMs}ms, pongTimeout={settings.KeepAlivePongTimeoutMs}ms");
        }

        [ContextMenu("Connect SDK")]
        public void Connect()
        {
            _ = ConnectAsync();
        }

        [ContextMenu("Disconnect SDK")]
        public void Disconnect()
        {
            PlayServ.Disconnect();
            Debug.Log("[PlayServ][Sample] Disconnected.");
        }

        public async Task ConnectAsync()
        {
            try
            {
                bool connected = await PlayServ.Connect();
                Debug.Log(connected
                    ? "[PlayServ][Sample] Connected."
                    : "[PlayServ][Sample] Connection failed.");
            }
            catch (Exception ex)
            {
                Debug.LogError($"[PlayServ][Sample] Connect error: {ex.Message}");
            }
        }

        private void OnTransportError(TransportError error)
        {
            Debug.LogError($"[PlayServ][Sample] Transport error: {error}");
        }

        private void RefreshResolvedEndpointsPreview()
        {
            var settings = BuildSettingsFromConfig();
            ApplyResolvedEndpointsPreview(settings);
        }

        private void ApplyResolvedEndpointsPreview(PlayServSettings settings)
        {
            if (settings == null)
                return;

            backendServerAddress = settings.BackendServerAddress;
            deployApiServerAddress = settings.DeployApiServerAddress;
            schemaApiServerAddress = settings.SchemaApiServerAddress;
        }

        private static PlayServSettings BuildSettingsFromConfig()
        {
            var config = Resources.Load<PlayServConfig>("PlayServConfig");
            if (config == null)
                return PlayServPackageDefaultsProvider.LoadSettingsOrDefault();

#if UNITY_EDITOR
            return PlayServSettingsResolver.ResolveEditorSettings(config);
#else
            return config.ToSettings();
#endif
        }
    }
}
observação

No fluxo padrão, este script lê as credenciais do config asset do PlayServ. Ative overrideCredentialsFromInspector apenas quando você quiser, de propósito, sobrescrever os valores definidos na janela de controles do editor do PlayServ.

Rode a cena e verifique a conexão​

Entre em Play Mode. Se a configuração estiver correta, o componente de bootstrap configura o SDK, conecta automaticamente quando autoConnect está ativo, e mantém a conexão viva enquanto o objeto existir.

Verifique a conexão no Console do Unity. Procure por:

  • [PlayServ][Sample] Configured.
  • [PlayServ][Sample] Connected.

Se algo der errado, o script também reporta falhas de conexão, erros de transporte e problemas de configuração.

Como essa configuração funciona​

Este fluxo separa a configuração do comportamento em runtime:

  • a janela de controles do editor do PlayServ guarda a configuração do SDK e mantém os Models do lado do editor em sincronia com o Schema
  • o script de bootstrap aplica essa configuração em runtime e abre a conexão

Ou seja: as credenciais do Project são gerenciadas em um só lugar, os Models de dados são gerados a partir do Schema em vez de escritos à mão, e a cena só precisa de um componente de bootstrap pequeno e reutilizável.

dica

Use um único objeto de bootstrap persistente para o projeto inteiro, em vez de espalhar scripts de conexão separados por várias cenas.

Coisas comuns para verificar​

Se o Project não conectar como esperado, confira se:

  • o pacote do SDK foi importado corretamente
  • o Game Access Token é uma key Client e foi copiado corretamente
  • o Game ID corresponde ao mesmo Project do Backoffice
  • o config asset do PlayServ existe e está preenchido
  • os Models foram regenerados depois da última mudança de Schema
  • o script de bootstrap está anexado a um GameObject ativo
  • autoConnect está ativo, se você espera conexão ao iniciar a cena
aviso

Se as credenciais estão definidas na janela de controles do editor do PlayServ, cuidado para não sobrescrevê-las sem querer com valores diferentes no inspector do componente de bootstrap.

Próximos passos​

Etiquetas:
Última atualização em