本页尚未翻译,当前显示英文版本。
Groups
Group 是一个命名通道:你的服务器向它发送 Event,所有加入了该 Group 的玩家都会收到。 用它通知一场对局中的所有人回合开始了,或者通知大厅里的所有人地图换了,而不必知道这些人是谁。游戏负责加入和离开 Group;只有你的服务器能向 Group 发送。
using Playserv.Wrapper;
await PlayServEvents.SubscribeGroupAsync("arena-7"); // after PlayServ.Connect()
var sub = PlayServEvents.Subscribe<RoundStarted>(e => hud.ShowRound(e.Round));
// Later
sub.Dispose();
await PlayServEvents.UnsubscribeGroupAsync("arena-7");
Group 如何工作
| 方面 | 机制 |
|---|---|
| 成员资格 | 属于游戏的连接。玩家从 SubscribeGroupAsync 起就在 Group 中,直到调用 UnsubscribeGroupAsync 或会话结束。不做任何持久化。 |
| 发送 | 你的 Game server 或云函数按 Group 名称发送 Event。 |
| 接收 | Group 中的每个连接都会收到该 Event。游戏用 PlayServEvents.Subscribe<T> 按类型挑选 Event,见 Server Events。 |
| 重连 | 重连后,SDK 会让游戏重新加入原来的 Group。断线期间发送的 Event 不会补发。 |
送达的 Event 不会标明它来自哪个 Group。如果游戏同时在多个 Group 中并且需要区分,就把这一信息放进 Event 本身,例如加一个 RoomName 字段。
加入与离开
SubscribeGroupAsync(name) 和 UnsubscribeGroupAsync(name) 在平台应答后返回。调用逐个执行,每个最多等待 10 秒,超时则抛出 TimeoutException。游戏必须已连接,并且有已登录的 Player。
Group 名称的作用域是你的 Project:游戏使用不带前缀的名称,例如 arena-7,PlayServ 会把它与其他 Project 的 Group 区分开。任何名称都无法触及其他 Project 的 Group。
Group 不是访问控制
你的 Project 中任何游戏都能按名称加入任何 Group。不要向 Group 发送只允许部分玩家看到的内容;对局用的 Group,请使用玩家猜不到的名称,例如 PlayServ 分配给 Room 的名称。
向 Group 发送
| 发送方 | 调用 |
|---|---|
| 云函数 | Platform.Publish<T>(group, payload)。直接使用不带前缀的 Group 名称即可,Event 类型就是 C# 类型的名称。 |
| Unity Dedicated Server | PlayServGameServer.Events.PublishAsync(group, eventType, payload)。Group 必须使用带 Project 作用域的形式;传入不带前缀的名称会抛出 ArgumentException。eventType 必须与游戏订阅的类名一致。 |
PublishAsync 在 Event 离开服务器时即完成:它不等待玩家收到,重连后也不会重发。
游戏不能向 Group 发送
PlayServEvents.PublishForGroup 以及其他 Publish 调用总是抛出 PlayServEventPublishingException。聊天消息或“准备就绪”信号,请通过 Function 调用或 RPC 发给你的服务器,再由服务器发送到 Group。
限制
| 项目 | 限制 |
|---|---|
| 每个连接的 Group 数 | 64 |
| Group 名称 | 最多 256 个字符,包括 PlayServ 添加的 Project 前缀 |
| Event 大小 | 1 MiB |
| 加入或离开 | 10 秒 |
错误
| 错误 | 何时出现 |
|---|---|
PlayServGroupSubscriptionException,带 group_subscription_limit_reached | 游戏已在 64 个 Group 中,或名称过长。 |
PlayServGroupSubscriptionException,带 group_outside_project | 该名称属于其他 Project。 |
TimeoutException | 10 秒内没有应答。 |
InvalidOperationException | 游戏尚未连接。 |
被拒绝的加入请求,重试也没有用。
Group 不是什么
Group 没有成员列表,没有在线状态,无法接受或拒绝玩家,也不能关闭。需要席位、服务器以及准入控制的对局,请使用 Room。
后续步骤
- 服务器 Event —— 在游戏中接收带类型的 Event
- 连接到游戏 —— 玩家加入的 Room
- 托管 Game server —— 从 Game server 发送 Event
更新于 2026年10月22日