本页尚未翻译,当前显示英文版本。
浏览、创建与加入 Room
PlayServMatchmaking 为玩家找到一个 Room,并给他一份预订:一张对应一个席位、有效期很短的票据。 游戏可以浏览你的服务器正在运行的 Room 并按名称加入,也可以请求创建一个新 Room。拿到预订后,游戏用它连接 Room 的服务器。本页是参考文档,完整流程见 Connecting to a Game。
using System.Collections.Generic;
using Playserv.Matchmaking;
using Playserv.Wrapper;
PlayServRoomBrowsePage page = await PlayServMatchmaking.BrowseRoomsAsync(
"sky-arena", new PlayServRoomBrowseQuery { PlacementState = "open", Region = "eu" });
PlayServMatchResult result = await PlayServMatchmaking.JoinRoomAsync("sky-arena", page.Rooms[0].RoomName);
PlayServMatchReservation reservation = result.Reservation;
每次调用都需要一个 client key 和一个已登录的 Player,否则在发出任何请求之前就会抛出 InvalidOperationException。第一个参数是 Room 类型,即你的 Game server 的 slug,例如 sky-arena。它必须配置了 Room 设置,否则每次调用都会以 RoomTypeNotFound 失败。
浏览 Room
BrowseRoomsAsync(roomType, query) 返回你的服务器已注册的 Room 的一页结果。
过滤条件(PlayServRoomBrowseQuery) | 取值 |
|---|---|
PlacementState | open、full、self_closed、draining 或 session_closing。 |
Region | 最多 32 个字符。 |
Attributes | 最多 4 个对 Room 属性的精确匹配。 |
Limit · Cursor | 每页 1–200 个 Room,默认 50;传入 page.CursorNext 获取下一页。HasMore 表示是否还有下一页。 |
每个 Room(PlayServRoomListing) | 说明 |
|---|---|
RoomName | 用于加入的名称。 |
Players · Capacity | 已占用席位数和总席位数。容量调低后,Players 可能超过 Capacity。 |
State · Attributes | 由你的服务器上报,例如 "lobby" 或地图。 |
PlacementState · Region | Room 是否接收玩家,以及运行在哪里。 |
Connect | 连接地址。服务器上报之前为 null。 |
列表中可能包含处于 session_closing 的 Room,这些 Room 无法加入。
按名称加入 Room
JoinRoomAsync(roomType, roomName) 请求该 Room 中的一个席位。如果要向服务器的准入检查传递数据,例如队伍,就使用请求对象的形式:
var result = await PlayServMatchmaking.JoinRoomAsync(new PlayServJoinRoomRequest
{
FunctionSlug = "sky-arena",
RoomName = roomName,
Params = new { team = "red" }, // sent as JSON; the server sees it when it admits the player
});
返回结果要么是一份预订,要么是异常:被拒绝时抛出 PlayServMatchmakingException,见 错误。在你对该 Room 的预订仍然有效时再次请求,会返回同一份预订。已经在 Room 中的玩家即使 Room 已满或正在排空,也能重新进入。
创建新 Room
HostRoomAsync(request) 请求你的某台服务器开一个 Room,并给玩家一份该 Room 的预订。
var result = await PlayServMatchmaking.HostRoomAsync(new PlayServHostRoomRequest
{
FunctionSlug = "sky-arena",
Attributes = new Dictionary<string, object> { ["map"] = "canyon" },
Region = "eu",
});
| 细节 | 结果 |
|---|---|
| Room 名称 | 由 PlayServ 生成,从 result.Reservation.RoomName 读取。 |
| 属性 | 扁平对象,序列化为 JSON 后最多 2048 字节。这只是一个期望值,服务器可以修改或拒绝;以预订中的属性为准。 |
| 预订 | 已经是给创建者的预订,不要再次加入该 Room。 |
| 超时 | 默认 45 秒。 |
再次创建可能产生第二个 Room
HostRoomAsync 超时后,Room 仍可能已经创建。再次调用可能会再开一个 Room;重试之前,先浏览一下第一个是否已经存在。
预订
PlayServMatchReservation | 说明 |
|---|---|
RoomName | 对应的 Room。 |
ReservationToken | 由服务器校验的票据。这是机密信息,不要写进日志。 |
Connect | Host、Port、Transport 和 ConnectString。服务器尚未上报时可能为 null。 |
Region · Attributes | Room 运行的区域,以及它的属性。 |
RemainingLifetime | 票据还剩多长有效期。 |
预订在 Room 类型的 Reservation TTL(1–60 秒)内有效,且只能使用一次。拿到后立即连接,中间不要插入确认界面。请使用 RemainingLifetime,而不是 ExpiresAt:ExpiresAt 用的是平台时钟,可能与设备时钟不一致。Room 关闭后,其未使用的预订随即失效。
一次调用完成加入与连接
JoinRoomAndConnectAsync(request, options, connector) 先加入,等到预订带有可用的 Connect,再用它运行你的 connector,最后返回预订。
var reservation = await PlayServMatchmaking.JoinRoomAndConnectAsync(
new PlayServJoinRoomRequest { FunctionSlug = "sky-arena", RoomName = roomName },
connector: (r, ct) => myTransport.ConnectAsync(r.Connect, r.ReservationToken, ct));
选项(PlayServRoomJoinOptions) | 默认值 |
|---|---|
Timeout —— 整个调用 | 45 秒 |
ConnectTimeout —— 等待 Connect | 30 秒 |
MaxUnreachableRetries —— 服务器无应答时重试加入的次数 | 3 |
使用 connector 时,请在 Unity 主线程上调用,connector 也会在主线程上运行。connector 失败不会重试。超时则抛出带 room_join_timeout 的 PlayServMatchmakingException。
Room session
对于使用 PlayServ 自带游戏连接的服务器,CreateRoomSession(protocolFactory) 会让玩家一直留在 Room 中:它通过 HostAsync、JoinAsync 或 ConnectAsync 进入,连接断开时再用新的预订重新加入。
| 细节 | 作用 |
|---|---|
State | Idle、Entering、Ready、Reconnecting、Failed 或 Closed;每次变化都会触发 StateChanged。 |
| 消息 | SendTextAsync 和 MessageReceived 事件。 |
| 恢复 | 120 秒内最多重新加入 3 次。创建 Room 的操作从不重复。 |
| 离开 | 先 LeaveAsync,再 Dispose。 |
你的 IPlayServRoomProtocol 要在 EnterAsync 完成之前确认服务器已放玩家进入。CreateGameConnection() 提供同样的连接,但不带重新加入的逻辑。
错误
拒绝会抛出 PlayServMatchmakingException。按 RoomFailureCode 分支处理;RetryAfter 表示何时可以重试。
RoomFailureCode | 何时出现 |
|---|---|
RoomNotFound | 没有这个名称的 Room。 |
RoomFull | 没有空闲席位。 |
RoomClosed | Room 已关闭或正在排空。 |
RoomRefused | 你的服务器拒绝了该玩家或该 Room。 |
RoomUnreachable | 服务器未能及时应答。等待 RetryAfter 后重试。 |
RoomTypeNotFound | 该 Room 类型没有 Room 设置。 |
RoomQuotaExceeded | 创建时:该 Room 类型运行的 Room 数已达 Max rooms。 |
RoomHostUnavailable · RoomHostCapacityExhausted | 创建时:目前没有服务器能开新 Room。 |
RegionUnavailable | 创建时:该区域 没有服务器。 |
Unknown | 其他所有情况。被运营方移出 Room 的玩家会收到 Unknown,其 UnifiedError.SourceCode 为 removed_from_room。 |
自动匹配
即将推出
由 PlayServ 为玩家挑选 Room 的自动匹配目前尚不可用。在此之前,玩家通过浏览按名称加入 Room,或自己创建一个。
后续步骤
- 连接到游戏 —— 从登录到游戏的完整流程
- 托管 Game server —— 服务器端:注册 Room 并放玩家进入
- Game Rooms —— 在 Backoffice 中查看和管理运行中的 Room
更新于 2026年10月22日