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.
| Tipo | C# (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 * * *" } ]
}
| Campo | Significado |
|---|---|
name | Obrigató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. |
kind | Obrigatório. cloud_function ou game_server. |
language | Obrigatório. csharp, node, python ou go. |
entry | O tipo do handler, por exemplo MyNamespace.Server. Obrigatório para um Game server em C#; a estrutura gerada já o inclui. |
description | Texto livre opcional. |
sdk_version | A versão do SDK usada no build quando o arquivo de projeto não fixa nenhuma. Uma versão fixada no .csproj tem prioridade. |
auth | player (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. |
execute | Quem 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. |
env | Variáveis de ambiente simples. Nomes que começam com PLAYSERV_ ou PLATFORM_ são reservados. |
secrets | Os nomes dos secrets de que a Function precisa; os valores são definidos com playserv secrets set. |
scaling | policy, min_replicas, max_replicas, desired_replicas: a mesma especificação que functions scale define. |
triggers | Triggers 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ção | Padrão | Significado |
|---|---|---|
--slug | obrigatório | O nome da Function na plataforma. |
--kind | obrigatório | cloud_function ou game_server. |
--src | . | Um diretório ou um único arquivo-fonte. |
--language | detectada | Veja Linguagens. |
--tag | — | Faz o deploy com um nome de versão; veja Version tags. |
--poll-timeout | 1200 s | Quanto 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.
| Resultado | Código de saída | Significado |
|---|---|---|
| deployed | 0 | No ar. A CLI imprime o endereço da Function. |
| detached | 0 | --detach: o upload foi aceito. Confira depois com functions deploys get <id>. |
| upload refused | 2 | A plataforma rejeitou o pacote. |
| build failed | 3 | A mensagem diz o motivo; o restante está em functions logs. |
| timeout | 4 | A CLI parou de esperar; o build ainda pode terminar. |
| session expired | 5 | A 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 em | Como publicar |
|---|---|
| PlayServ no Cloud Run | playserv functions deploy --kind game_server ou publish, como qualquer Function. C# ou JavaScript. |
| Um pool de máquinas da PlayServ | playserv 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áquinas | playserv 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ção | Intervalo | Significado |
|---|---|---|
--capacity | 1–1000 | Players por Room. |
--reservation-ttl | 1–60 s | Por quanto tempo uma reserva do matchmaking segura uma vaga. |
--lifetime | ≥ 0 s | Tempo de vida máximo da Room; 0 significa sem limite e, nesse caso, exige --idle-timeout. |
--idle-timeout | ≥ 1 s | Fecha a Room depois de ficar esse tempo sem Players. Omita para remover o valor. |
--max-rooms | 1–10000 | Quantas 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