跳到主要内容
多人联机

本页尚未翻译,当前显示英文版本。

托管 Game server

你的 Game server 负责运行对局;PlayServ 负责列出它的 Room、分发席位并检查谁可以进入。 服务器注册自己托管的每个 Room,并通过心跳让它保持存活。玩家从 PlayServ 拿到票据后带给服务器,服务器校验通过才放他进入。本页介绍 Unity Dedicated Server;用 C# 编写的服务器见 C# Game Servers。


两类 Game server

Unity Dedicated ServerC# 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日