Pular para o conteúdo principal
Engenharia

Esta página ainda não foi traduzida: mostrando a versão em inglês.

Deploy com a CLI

Você envia código-fonte, não contêineres. A CLI empacota o seu código com o platform.json e faz o upload; a plataforma faz o build e o executa, então não há Docker na sua máquina, exceto para Game servers em pools de máquinas. Tudo aqui roda dentro de uma sessão com login feito; veja Interface de linha de comando.


Início rápido

Do zero a uma Function publicada:

playserv init --solution Acme --function hello-fn --kind cloud_function
cd Acme
playserv publish --dry-run
playserv publish --yes
playserv functions logs hello-fn --tail 50

init não exige login e não cria nada na plataforma; a Function aparece no primeiro deploy. publish encontra cada platform.json da solution e faz o deploy de cada Function do mesmo jeito que functions deploy faz com uma só.


Linguagens

Functions podem ser escritas em C#, JavaScript, Python ou Go; Game servers, em C# ou JavaScript.

TipoC# (csharp)JavaScript (node)Python (python)Go (go)
cloud_function✓✓✓✓
game_server✓✓——

Quando --language é omitido, a CLI detecta a linguagem: um .csproj indica C#, package.json indica JavaScript, go.mod indica Go, e requirements.txt ou main.py indicam Python; um arquivo único é detectado pela extensão. Sem nenhum desses marcadores, ela assume C#. init só cria projetos em C#; projetos nas outras linguagens são escritos à mão.

Uma Function em C# implementa IPlatformFunction do PlayServ SDK. Uma Function em outra linguagem é um servidor HTTP comum que escuta em $PORT e responde com JSON. Estas são Functions completas, prontas para deploy:

using PlayServ.Sdk;

namespace HelloFunc;

public class Hello : IPlatformFunction
{
    public Task<FunctionResponse> HandleAsync(FunctionRequest req, CancellationToken ct = default)
        => Task.FromResult(FunctionResponse.Json(new { message = "hello from playserv" }));
}
const http = require('http');
const port = process.env.PORT || 8080;

http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ message: 'hello world' }));
}).listen(port);

TypeScript também funciona: aponte --src para uma pasta com package.json, tsconfig.json e src/index.ts. A plataforma transpila o código durante o build sem verificar tipos, então rode tsc no seu próprio CI.

import json, os
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

class Handler(BaseHTTPRequestHandler):
    def _respond(self):
        data = json.dumps({"message": "hello world"}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(data)
    do_GET = do_POST = _respond

ThreadingHTTPServer(("", int(os.environ.get("PORT", "8080"))), Handler).serve_forever()
package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(map[string]string{"message": "hello world"})
	})
	http.ListenAndServe(":"+port, nil)
}

O manifesto: platform.json

Cada diretório de Function tem um platform.json: a identidade e os bindings da Function, versionados no git. publish também o usa para encontrar as Functions.

{
  "name": "hello-fn",
  "kind": "cloud_function",
  "language": "csharp",
  "auth": "player",
  "execute": { "client": true, "server": true, "backend": false },
  "env": { "GREETING": "hi" },
  "secrets": ["STRIPE_API_KEY"],
  "triggers": [ { "type": "scheduled", "cron": "0 5 * * *" } ]
}
CampoSignificado
nameObrigatório. O slug: letras minúsculas, dígitos e hifens, de 3 a 50 caracteres, começando com letra, sem hífen no final nem hifens duplos.
kindObrigatório. cloud_function ou game_server.
languageObrigatório. csharp, node, python ou go.
entryO tipo do handler, por exemplo MyNamespace.Server. Obrigatório para um Game server em C#; a estrutura gerada já o inclui.
descriptionTexto livre opcional.
sdk_versionA versão do SDK usada no build quando o arquivo de projeto não fixa nenhuma. Uma versão fixada no .csproj tem prioridade.
authplayer (padrão): um jogo que chama com uma key de cliente precisa ter um Player logado, senão recebe 401 player_auth_required. none: não é preciso Player. Chamadas com uma key de servidor não são afetadas. Toda chamada precisa de uma API key.
executeQuem pode chamar a Function: client, server, backend, cada um true ou false. Quem não tem permissão recebe 403 function_execute_forbidden. Os que forem omitidos são permitidos.
envVariáveis de ambiente simples. Nomes que começam com PLAYSERV_ ou PLATFORM_ são reservados.
secretsOs nomes dos secrets de que a Function precisa; os valores são definidos com playserv secrets set.
scalingpolicy, min_replicas, max_replicas, desired_replicas: a mesma especificação que functions scale define.
triggersTriggers adicionais, como agendamentos cron.

O arquivo pode conter comentários // e vírgulas finais. A validação é rígida e igual em todo lugar: um arquivo malformado falha com invalid_bundle, uma regra violada com invalid_manifest, e --dry-run executa as verificações locais sem fazer upload.


Deploy de uma Function

playserv functions deploy --slug <slug> --kind cloud_function|game_server [--src <dir>] [--language <lang>] \
                          [--tag <tag>] [--poll-timeout <s>] [--dry-run | --detach]
OpçãoPadrãoSignificado
--slugobrigatórioO nome da Function na plataforma.
--kindobrigatóriocloud_function ou game_server.
--src.Um diretório ou um único arquivo-fonte.
--languagedetectadaVeja Linguagens.
--tag—Faz o deploy com um nome de versão; veja Version tags.
--poll-timeout1200 sQuanto tempo a CLI espera pelo upload e pelo build. Se a CLI parar de esperar, o build continua na plataforma.
--dry-run—Valida tudo o que dá para verificar localmente e mostra o que seria enviado. Nada é enviado.
--detach—Retorna assim que o upload é aceito e imprime o ID do deploy. Não pode ser combinado com --dry-run.

O pacote inclui tudo dentro de --src, exceto bin/, obj/, .git/, .vs/, .idea/, node_modules/ e qualquer arquivo cujo nome comece com .env. Projetos compartilhados referenciados de fora de --src entram no pacote automaticamente.

ResultadoCódigo de saídaSignificado
deployed0No ar. A CLI imprime o endereço da Function.
detached0--detach: o upload foi aceito. Confira depois com functions deploys get <id>.
upload refused2A plataforma rejeitou o pacote.
build failed3A mensagem diz o motivo; o restante está em functions logs.
timeout4A CLI parou de esperar; o build ainda pode terminar.
session expired5A sessão expirou durante a espera; o ID do deploy é impresso.

Publicar a solution inteira

playserv publish [--src <path>] [--solution-path <file>] [--only <slug>]... [--tag <tag>] \
                 [--parallel N] [--poll-timeout <s>] [--dry-run] [--yes]

publish encontra cada diretório com platform.json dentro da solution, compara a lista com o que está publicado no Environment, mostra o plano e pede confirmação. Em seguida, faz o deploy de cada Function, até --parallel ao mesmo tempo (padrão 1). No CI, passe --yes. O comando sai com 1 se alguma Function falhar; tente de novo só essa com --only <slug>.


Version tags

--tag <tag> em functions deploy ou publish publica uma versão ao lado da mais recente sem tag. O tráfego normal continua indo para a mais recente; quem chama seleciona a versão com tag pelo header X-Playserv-Function-Version: <tag>. Uma tag desconhecida retorna 404 function_version_not_found, sem cair na versão mais recente. Fazer o deploy de uma tag de novo a aponta para a nova versão.

Uma tag tem de 3 a 22 letras minúsculas, dígitos e hifens, começa com letra e termina com letra ou dígito. Um uso típico é publicar com --tag ver2-canary, apontar um cliente de teste para ela e, quando ela se mostrar estável, publicar o mesmo código sem tag.


Chamar uma Function

Em um jogo Unity, chame uma Function com PlayServCode.CallAsync; veja Cloud Functions & RPC. As chamadas abaixo são para as suas próprias ferramentas e servidores.

As Functions publicadas respondem em /fn/<slug> na plataforma e são chamadas com uma credencial de runtime, não com a sessão da CLI. A partir de um servidor, use uma key de servidor:

curl -X POST <platform-url>/fn/<slug> \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"n":5}'

Em nome de um Player, use uma key de cliente mais o token de sessão do Player:

curl -X POST <platform-url>/fn/<slug> \
  -H "X-PlayServ-Client: pk_..." \
  -H "Authorization: Bearer <player-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"n":5}'

Qual dessas formas uma Function aceita depende das configurações auth e execute dela.


Game servers

Um Game server é publicado de uma de três formas, conforme o lugar onde ele roda (veja Servers).

Roda emComo publicar
PlayServ no Cloud Runplayserv functions deploy --kind game_server ou publish, como qualquer Function. C# ou JavaScript.
Um pool de máquinas da PlayServplayserv image push --slug <slug> --tag <version> --roll faz o build de uma imagem linux/amd64, envia para o registry do projeto e passa o pool para ela. Exige Docker com buildx. Um Game server em C# não precisa de Dockerfile: a CLI gera um.
Suas próprias máquinasplayserv functions declare <slug> --kind game_server o registra sem nenhum build, para que as Rooms dele possam se registrar imediatamente. --hosting-mode multi-room (padrão) ou process-per-room.

Crie o pool antes e deixe os servidores em pool fora do publish

image push --roll não cria um pool de máquinas: se o Game server não tem pool no Environment, a imagem é enviada e o comando falha com pool_not_found. Crie o pool na aba Hosting do Game server em Servers. E deixe um Game server em pool fora do publish usando --only: um build no Cloud Run o tiraria do pool.

As configurações de Room também podem ser definidas pelo terminal — as mesmas de Servers → Room settings. rooms config set substitui a configuração inteira, então todas as opções, exceto --idle-timeout, são obrigatórias:

OpçãoIntervaloSignificado
--capacity1–1000Players por Room.
--reservation-ttl1–60 sPor quanto tempo uma reserva do matchmaking segura uma vaga.
--lifetime≥ 0 sTempo de vida máximo da Room; 0 significa sem limite e, nesse caso, exige --idle-timeout.
--idle-timeout≥ 1 sFecha a Room depois de ficar esse tempo sem Players. Omita para remover o valor.
--max-rooms1–10000Quantas Rooms este Game server pode executar ao mesmo tempo.

rooms config get mostra as configurações atuais, e rooms config delete as remove; a exclusão é recusada enquanto houver alguma Room registrada.


Próximos passos

  • Interface de linha de comando — login, todos os comandos, códigos de saída e erros
  • Functions — Functions publicadas, os logs e as configurações delas no Backoffice
  • Servers — frotas, pools de máquinas e configurações de Room

Atualizado em 14 de out. de 2026