跳到主要内容
多人联机

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

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 ServerPlayServGameServer.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。
TimeoutException10 秒内没有应答。
InvalidOperationException游戏尚未连接。

被拒绝的加入请求,重试也没有用。


Group 不是什么

Group 没有成员列表,没有在线状态,无法接受或拒绝玩家,也不能关闭。需要席位、服务器以及准入控制的对局,请使用 Room。


后续步骤

更新于 2026年10月22日