跳到主要内容
多人联机

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

浏览、创建与加入 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)取值
PlacementStateopen、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 · RegionRoom 是否接收玩家,以及运行在哪里。
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由服务器校验的票据。这是机密信息,不要写进日志。
ConnectHost、Port、Transport 和 ConnectString。服务器尚未上报时可能为 null。
Region · AttributesRoom 运行的区域,以及它的属性。
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 —— 等待 Connect30 秒
MaxUnreachableRetries —— 服务器无应答时重试加入的次数3

使用 connector 时,请在 Unity 主线程上调用,connector 也会在主线程上运行。connector 失败不会重试。超时则抛出带 room_join_timeout 的 PlayServMatchmakingException。


Room session

对于使用 PlayServ 自带游戏连接的服务器,CreateRoomSession(protocolFactory) 会让玩家一直留在 Room 中:它通过 HostAsync、JoinAsync 或 ConnectAsync 进入,连接断开时再用新的预订重新加入。

细节作用
StateIdle、Entering、Ready、Reconnecting、Failed 或 Closed;每次变化都会触发 StateChanged。
消息SendTextAsync 和 MessageReceived 事件。
恢复120 秒内最多重新加入 3 次。创建 Room 的操作从不重复。
离开先 LeaveAsync,再 Dispose。

你的 IPlayServRoomProtocol 要在 EnterAsync 完成之前确认服务器已放玩家进入。CreateGameConnection() 提供同样的连接,但不带重新加入的逻辑。


错误

拒绝会抛出 PlayServMatchmakingException。按 RoomFailureCode 分支处理;RetryAfter 表示何时可以重试。

RoomFailureCode何时出现
RoomNotFound没有这个名称的 Room。
RoomFull没有空闲席位。
RoomClosedRoom 已关闭或正在排空。
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,或自己创建一个。


后续步骤

更新于 2026年10月22日