本页尚未翻译,当前显示英文版本。
C# Game server
C# Game server 在 PlayServ 上运行你的规则:每个 Room 按 tick 推进,你的代码步进模拟,SDK 把快照推送给玩家。 PlayServ 校验每个玩家并分发席位;你的服务器决定玩家能做什么、会发生什么。它是基于 PlayServ C# SDK 构建的 .NET 进程,部署方式与云函数相同。
| 你负责 | PlayServ 负责 |
|---|---|
| 规则 :玩家能做什么、会改变什么、谁获胜 | 玩家身份:每个连接到达时都带着已校验的 Player |
| 时钟与模拟 | 席位:容量、生命周期、空闲超时、最大 Room 数,来自 Room 设置 |
| 玩家发来什么、你回复什么 | 查找 Room:浏览、创建、加入,以及放玩家进入的票据 |
快速开始
创建项目
playserv init sky-arena --kind game_server生成的项目是一个可以直接部署的 echo 服务器。按下文用你的 Room 替换其中的服务器类。
部署
playserv functions deploy --slug sky-arena --kind game_server --src .slug 在整个组织内唯一,而不只是在你的 Project 内。
配置 Room 设置
playserv rooms config set sky-arena --capacity 8 --reservation-ttl 10 --lifetime 1800 --idle-timeout 120 --max-rooms 50也可以在 Servers → Room settings 中配置。在设置存在之前,玩家无法创建、浏览或加入它的 Room。
服务器类
每个项目一个类,派生自 PlatformGameServer,并带有一个无参数的公共构造函数。由 Program.cs 启动它:await PlatformHost.RunAsync<ArenaServer>(args);
| Hook | 何时触发 |
|---|---|
OnStartupAsync · OnShutdownAsync | 进程启动,或被要求停止。 |
OnPlayerConnected(session) | 玩家通过了握手。session.Id 是已校验的 Player,session.AdmittedRoomName 是其票据对应的 Room。 |
OnPlayerMessage(session, bytes) | 该玩家发来的一条消息。 |
OnPlayerDisconnected(session, reason) | 连接已关闭,或重连宽限期已过。 |
OnPlayerReconnected(session) | 玩家在 ReconnectGrace(默认 30 秒)内回来了。 |
OnTicketOfferAsync(room, playerId, params, ct) | PlayServ 在 签发票据之前询问该玩家能否加入该 Room。返回 false 即拒绝,例如用于私人 Room。 |
用 session.SendTextAsync、SendBinaryAsync 或 TrySendText 向玩家发送消息。每个玩家有一个 64 条消息的队列;跟不上的慢速玩家会被断开,而不是拖慢整个 Room。
Room
using PlayServ.Sdk;
using PlayServ.Sdk.Rooms;
public sealed class Pilot : RoomPlayer { public int Score; }
public sealed record ArenaConfig(int RoundSeconds);
public sealed class ArenaRoom : Room<Pilot, ArenaConfig>
{
public ArenaRoom(string name) : base(name, new ArenaConfig(300), capacity: 8) { }
protected override float SimStepSeconds => 0.1f; // 10 steps per second
protected override void OnSimStep(float dt)
{
// move ships, resolve hits, end the round
}
}
RoomHost 管理服务器上的所有 Room:new RoomHost<ArenaRoom, Pilot, ArenaConfig>(name => new ArenaRoom(name), tickHz: 10)。玩家创建 Room 时它负责新建,驱动每个 Room 的 tick,应用 Room 设置,大约每 5 秒向 PlayServ 发送一次各 Room 的心跳,并释放被 PlayServ 关闭的 Room。用 GetOrCreate(name) 自己开一个 Room;用 Find(name) 查找 Room。
Room 成员 | 作用 |
|---|---|
AddPlayer · RemovePlayer · GetPlayer · Players · IsFull | 名单。Room 已满时 AddPlayer 返回 false。 |
Lock | 所有读取或修改 Room 状态的操作都在这把锁下执行。SDK 在每个 tick 中会自动加锁;处理每条命令时需要你自己加锁。 |
OnPlayerJoined · OnPlayerLeft · OnIdle | 名单相关的 hook。只要 Room 被释放就会触发 OnIdle:空闲超时、生命周期结束,或运营方执行了 Delete room。 |
SetState · SetAttributes | 玩家浏览时看到并可用于过滤的内容。 |
MarkActive(player) | 记录活动,用于空闲超时判断。 |
DeclareConnect(new RoomConnect(host, port, transport), region) | 玩家连接的地址,以及 Room 运行的区域。 |
构造函数中的容量只用于本地运行:Room 设置中的容量会替换它。
模拟
OnSimStep(dt) 就是你的固定步长模拟。宿主在 Room 的锁下每隔 SimStepSeconds(默认 1/30)调用一次;出现卡顿后会追帧,每个 tick 最多 MaxCatchUpSteps 步(默认 6)。
把大型模拟拆分成系统:AddSystem(ISimSystem) 和 AddPlayerSystem(IPlayerSimSystem),每个系统归属一个阶段:Input、AI、Movement、Collision、Combat、Spawn、Scoring、Cleanup。默认的 OnSimStep 按这个顺序运行它们。
不要重写 OnTick
Room 的 tick 负责步进模拟、维护重连宽限期并发送快照。重写 OnTick 而不调用 base.OnTick,会把这三项全部关掉。请把逻辑写在 OnSimStep 中。
DeclareReconnect(lingerSeconds, removeOnExpiry, onExpire) 会移除所有在 lingerSeconds 内没有活动(由 MarkActive 记录)的玩家,无论是否在线。因此掉线玩家的席位会保留这么长时间。先运行 onExpire;removeOnExpiry 默认开启,开启时随后会移除玩家并运行 OnPlayerLeft。在那里重新计算 Room 的房主、队伍或回合顺序。玩家发来的每条命令都要调用 MarkActive,否则活跃玩家也会被移除。
快照
玩家通过你构建的快照看到 Room;何时发送由 SDK 决定。在 Room 的构造函数中声明一次发送计划:
DeclareSnapshot<ArenaSnapshot>(plan =>
{
plan.Cadence = SnapshotCadence.EveryN(20); // every 20 ticks
plan.Deliver = snapshot => Broadcast(snapshot);
plan.Assemble(_ => BuildSnapshot());
});
| 计划设置 | 作用 |
|---|---|
Assemble(...) | 在 tick 之后、在锁下构建快照。必填。 |
Deliver | 把快照发送给 Room 中的玩家。 |
Cadence | SnapshotCadence.EveryTick 或每 EveryN(n) 个 tick。 |
ForcePublishOnEvent | 默认开启:任何变更中调用 Events.Emit(...),都会在下一个 tick 发送快照,不必等待发送节奏。 |
AdaptiveCadence | 在预算范围内,于 MinHz(1)与 MaxHz(15)之间调整发送频率。 |
设置 Deliver,把快照发送到玩家的连接上。低频节奏加上每次变更时调用 Events.Emit,能让回合制游戏的响应显得即时。
玩家命令
玩家在 OnPlayerMessage 中发送什么,由你定义:用带请求 ID 的小型 JSON 消息,就能对每条命令作出回复。每条命令都在 Room 的锁下处理,出错时返回简短的错误码,而不是抛出异常。
信任会话,而不是消息
玩家身份从 session.Id 获取,绝不要用消息中的 ID。按你的规则检查每条命令:阶段是否正确、玩家是否正确、数值是否在范围内。
服务器还可以公开一些方法,供玩家通过 PlayServRpc.InvokeAsync 调用。
数据
已部署的服务器无需密钥即可读写你的数据:Platform.Table<T>()、Platform.Records 和 Platform.Singleton。每场对局保存一次对局结果,按自然键更新玩家资料,并定时重新读取实时设置,例如 singleton。
绝不要在 OnSimStep 中或 Room 的锁下等待数据调用:把它放到 tick 之外运行。DeclareDataMirror 和 DeclarePersistedCounter 会替你让玩家的数据行与 Room 保持同步。
玩家连接位置
玩家通过 RoomConnect 到达 Room:在机器池或你自己的机器上,用公网地址和端口调用 DeclareConnect。玩家用 CreateRoomSession 或 CreateGameConnection 连接,它们会发送票据;SDK 在 OnPlayerConnected 之前校验票 据,无效或过期的票据会导致连接被关闭。
限制
| 项目 | 限制 |
|---|---|
| 玩家发来的消息 | 1 MB |
| 握手 | 第一条消息,最大 4 KB,须在 10 秒内送达 |
| 每个玩家的队列 | 64 条消息 |
tickHz | 1–240 |
| 追帧 | 每个 tick 6 步 |
| Room 与席位 | 由 Room 设置决定 |
后续步骤
- 托管 Game server —— 两类服务器,以及 Unity Dedicated Server
- 使用 CLI 部署 —— 部署服务器、打标签和声明服务器
- 连接到游戏 —— 玩家如何到达你的 Room
更新于 2026年10月22日