跳到主要内容
多人联机

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

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 中的玩家。
CadenceSnapshotCadence.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 条消息
tickHz1–240
追帧每个 tick 6 步
Room 与席位由 Room 设置决定

后续步骤

更新于 2026年10月22日