本页尚未翻译,当前显示英文版本。
托管 Game server
你的 Game server 负责运行对局;PlayServ 负责列出它的 Room、分发席位并检查谁可以进入。 服务器注册自己托管的每个 Room,并通过心跳让它保持存活。玩家从 PlayServ 拿到票据后带给服务器,服务器校验通过才放他进入。本页介绍 Unity Dedicated Server;用 C# 编写的服务器见 C# Game Servers。
两类 Game server
| Unity Dedicated Server | C# Game server | |
|---|---|---|
| 是什么 | 使用 Dedicated Server 目标平台并带有 com.playserv.game-server 包的 Unity build | 基于 PlayServ C# SDK 构建的 .NET 进程 |
| 游戏循环与 netcode | 由你负责:Unity,加上 Netcode for GameObjects、Mirror 或其他任何方案 | PlayServ 的 Room tick 和模拟,运行在 PlayServ 的游戏连接之上 |
| 运行在 | PlayServ 机器池,或你自己的机器 | PlayServ(Cloud Run)、机器池,或你自己的机器 |
| 指南 | 本页 | C# Game Servers |
各自运行在哪里,在 Servers 中配置。
PlayServ 负责的部分
Room 类型的 Room 设置具有最终决定权:容量、Reservation TTL、Room 生命周期、空闲超时和最大 Room 数。服务器读取这些设置,并在下一次心跳时拿到变更,无需重启。调低容量不会移除任何人。
先配置 Room 设置
Game server 在拥有 Room 设置之前可以连接,但它尝试注册的每个 Room 都会被拒绝,玩家会收到 RoomTypeNotFound。
搭建 Unity Dedicated Server
安装包
在 Tools ▸ PlayServ ▸ Settings 中安装配套包 com.playserv.game-server,SDK 版本与游戏保持一致。
为服务器构建
使用 Dedicated Server 目标平台构建。在普通的客户端 build 中,所有 PlayServGameServer 调用都会被拒绝。
配置
在做任何其他事情之前,在主线程上调用一次 Configure:
using Playserv.GameServer;
PlayServGameServer.Configure(new PlayServGameServerOptions
{
ExecutorSlug = "sky-arena",
ServerKeyProvider = new PlayServDelegateServerKeyProvider(ct => secrets.GetServerKeyAsync(ct)),
});PlayServ 在机器池上启动的服务器会自动获得凭据。StartRoomAsync 会自行把服务器连接到 PlayServ。你自己运行的服务器需要一个 server key;从你的密钥存储中加载它,绝不要把它放进受版本控制的场景、asset 或配置文件里。
注册 Room
StartRoomAsync 注册一个 Room,然后每 5 秒发送一次心跳让它保持存活:
var room = await PlayServGameServer.StartRoomAsync(new PlayServStartRoomRequest(
"sky-arena",
new PlayServGameRoomSnapshot("canyon-1", players: 0, capacity: 8,
state: "lobby", attributes: new { map = "canyon" },
connect: new PlayServGameRoomConnect(publicHost, 7777, "udp"), region: "eu")), ct);
| 快照字段 | 含义 |
|---|---|
roomName | 玩家加入时使用的名称。 |
players · capacity · open | 已占用席位数、总席位数,以及是否接收玩家。 |
state · attributes | 自由文本,以及玩家浏览时可用于过滤的值。 |
connect · region | 玩家连接的地址,以及 Room 运行的区域。没有 connect,玩家就不知道该连到哪里。 |
有变化时调用 room.Update(snapshot),例如状态从 lobby 变为 playing。停止发送心跳的 Room 会在 15 秒后被标记为过期,随后被移除。
room.State | 含义 |
|---|---|
Active | 已注册,心跳正常。 |
Degraded | 某次心跳因网络原因失败;SDK 会持续重试。 |
Draining · Closed | 正在关闭,或已关闭。 |
Terminated | 被永久拒绝,例如密钥无效。Terminated 事件会带着错误触发。 |
Room 生命周期结束、PlayServ 将其关闭时,会触发 LifetimeClosed。
玩家请求创建的 Room
玩家调用 HostRoomAsync 时,PlayServ 会请你的某台服务器开一个 Room。设置 RoomFactory 来响应:
RoomFactory = (request, ct) =>
{
var wish = request.Attributes as IDictionary<string, object>;
var map = wish != null && wish.TryGetValue("map", out var m) ? m as string : "canyon";
if (map != "canyon" && map != "orbit")
return Task.FromResult(PlayServRoomCreateDecision.Refuse(PlayServRoomCreateRefusal.ContentRefused, "Unknown map"));
return Task.FromResult(PlayServRoomCreateDecision.Accept(new PlayServGameRoomSnapshot(
request.RoomName, 0, request.Configuration.Capacity, attributes: new { map },
connect: new PlayServGameRoomConnect(publicHost, 7777, "udp"))));
},
保留 PlayServ 给出的 Room 名称。玩家请求的属性只是期望值,Room 最终使用的是你返回的属性。拒绝时可用 RoomNameConflict、InstanceDraining、RoomQuotaExceeded、RoomCreateFailed 或 ContentRefused;只有 InstanceDraining 会让 PlayServ 不再向这台服务器分配新 Room。factory 有 5 秒时间作答。
放玩家进入
玩家带着加入时拿到的预订票据来连接。请在 netcode 的连接审批中、玩家进入之前校验它:
room.Admission.AdmissionRejected += rejected => network.Disconnect(rejected.AdmissionId);
var admission = room.Admission.TryAdmit(reservationToken); // synchronous
if (!admission.Ok) return false; // refuse the connection
network.Accept(connectionId, admission.PlayerId, admission.AdmissionId);
TryAdmit 同时会通知 PlayServ 玩家已加入。玩家 ID 要从返回结果中取,绝不要用客户端发来的值。在接受任何连接之前先订阅 AdmissionRejected:PlayServ 仍可能在稍后拒绝某次准入,这时你要断开对应的那个连接。
在票据签发之前,TicketOfferHandler 选项就可以在 3 秒内接受或拒绝玩家,例如让私人 Room 保持私密。玩家加入时发送的 Params 包含在这次 offer 中。
重连。 room.CreateConnectionTracker() 会为掉线玩家保留席位,默认 30 秒。用 tracker.TryAdmit(connectionId, token) 代替 Admission.TryAdmit,连接断开时调用 tracker.ReportDisconnected(connectionId),并在席位释放时处理 ConnectionRemoved。回来的玩家会带着新票据和新连接。
移除玩家与关闭 Room
| 调用 | 作用 |
|---|---|
room.ReportLeave(playerId) · room.Kick(playerId) | 通知 PlayServ 该玩家已离开。连接需要你自己关闭:SDK 从不关闭你的 socket。 |
tracker.RemovePlayer(playerId) | 移除玩家,不等待重连宽限期。 |
room.CloseAsync() | 关闭 Room。其未使用的票据随即失效。 |
Backoffice 操作暂时无法作用于 Unity 服务器
Game Rooms 中的 Delete room 和 Remove from room 不会停止 Unity Dedicated Server 上的 Room,也不会断开玩家:只要服务器还保留着该 Room,它就停在 Session closing 状态,被移除的玩家只是无法重新加入。请在你的服务器上关闭 Room 和移除玩家。
响应 RPC 调用
玩家通过 PlayServRpc.InvokeAsync 调用你的服务器。在 Configure 之前注册方法:
var round = new PlayServServerRpcParameter<int>("Round"); // matches the client's field name, case included
var registry = new PlayServServerRpcRegistry();
registry.Register<RoundPreview>("round.preview", new[] { round },
(caller, args, ct) => Task.FromResult(BuildPreview(caller.PlayerId, args.Get(round))));
options.RpcRegistry = registry;
caller.PlayerId 由 PlayServ 校验。调用在主线程上逐个执行,每个必须在 HttpTimeout(默认 10 秒)内完成。
发送 Event 与关停
PlayServGameServer.Events.PublishAsync(group, eventType, payload) 向 Group 中的所有人发送 Event。
进程退出前,await PlayServGameServer.ShutdownAsync():它会停止接收新 Room、关闭自己的 Room 并断开连接。只调用 Dispose 只能尽力而为。
运行在哪里
| 位置 | 方式 |
|---|---|
| PlayServ 机器池 | 在 Editor 中(Deployment ▸ Server Images)或用 playserv image push 构建并推送 linux/amd64 镜像,然后在 Servers 中该服务器的 Hosting 标签页上配置机器池。 |
| 你自己的机器 | 用 playserv functions declare <slug> --kind game_server 声明 Game server,见 Deploying with the CLI。 |
发布新镜像会关闭 Room
把机器池切换到新镜像会重启其中的机器,上面的 Room 也会随之关闭。请在对局间隙发布。
达到 Max rooms 后,新 Room 会被拒绝,发起创建的玩家会收到 RoomQuotaExceeded。在每 Room 一进程模式下,机器池已满时发起创建的玩家最多等待 90 秒,然后收到 RoomUnreachable;而 HostRoomAsync 默认 45 秒后就停止等待,除非你调大它的 Timeout。
PlayServ 为单个 Room 启动的服务器。 在每 Room 一进程模式下,PlayServ 会为玩家请求的那个 Room 启动一个进程。这个进程只注册那一个 Room:PlayServServerLaunch.GetRoomName() 返回它的名称,PlayServServerLaunch.ResolveConnect(listenPort) 返回玩家连接用的公网地址。
后续步骤
- 连接到游戏 —— 流程中玩家这一侧
- Servers —— 服务器集群、Room 设置和机器池
- Game Rooms —— 你的服务器注册的 Room,在 Backoffice 中实时查看
更新于 2026年10月22日