本页尚未翻译,当前显示英文版本。
服务器 Event
你的服务器向 Player 推送强类型 Event;游戏用 PlayServEvents.Subscribe<T> 监听它们。 Game server 或 Cloud Function 向某个 Group 发送 Event,该 Group 中的每个 Player 都会通过 SDK 已经保持的连接收到它。Event 是单向的:从你的服务器发往游戏。
using System;
using Playserv.Wrapper;
using UnityEngine;
[Serializable]
public class MatchFinished
{
public string WinnerCallsign;
public int Score;
}
public sealed class MatchEvents : MonoBehaviour
{
IDisposable _sub;
async void Start()
{
await PlayServEvents.SubscribeGroupAsync("arena-7");
_sub = PlayServEvents.Subscribe<MatchFinished>(e => Debug.Log($"{e.WinnerCallsign} wins with {e.Score}"));
}
void OnDestroy() => _sub?.Dispose();
}
投递机制
| 组成部分 | 作用 |
|---|---|
| Event 类型 | 一个带公共字段的普通 [Serializable] C# 类,无需基类。 |
| Group | 一个具名频道。Player 只会收到发往其游戏通过 SubscribeGroupAsync 加入的 Group 的 Event,其他一概收不到。 |
| 发送方 | 你的 Game server 或 Cloud Function,负责向 Group 发送 Event。 |
| 处理器 | Subscribe<T> 从游戏收到的所有内容中挑出类型为 T 的 Event。 |
Event 按类型名匹配:发送方指明 Event 类型,游戏把它投递给同名类的订阅者。请在两端使用相同的类名。只有当游戏订阅的其他类中没有同名类时,命名空间才可以不同。
Event 不会被保存
Event 只会送达发送那一刻在 Group 中的 Player。之后才加入的 Player,或当时离线的 Player,都收不到它。对于 Player 必须看到的状态,请使用 Record,Event 只用来通知某件事发生了。
订阅
| 调用 | 作用 |
|---|---|
PlayServEvents.Subscribe<T>(handler) | 每收到一个类型为 T 的 Event 就调用一次 handler。返回一个 IDisposable:释放它即可停止。 |
PlayServEvents.SubscribeGroupAsync(name) | 加入一个 Group,让它的 Event 送达这个游戏。 |
PlayServEvents.UnsubscribeGroupAsync(name) | 离开一个 Group。 |
请在 PlayServ.Connect() 之后调用它们:游戏连接之 前订阅会抛出 InvalidOperationException。同一类型的多个处理器共用一个订阅。
重新连接后,SDK 会让游戏重新加入原来的 Group 并保留处理器,你无需写任何代码。游戏断开期间发送的 Event 不会再投递。
Group 及其命名和限制,详见 Groups。
谁发送 Event
| 发送方 | 调用 |
|---|---|
| Unity Dedicated Server | PlayServGameServer.Events.PublishAsync(group, eventType, payload),使用 Group 带 Project 前缀的名称,参见 Groups。 |
| C# Cloud Function | Platform.Publish<T>(group, payload),以 C# 类型名作为 Event 类型。 |
游戏不能发送 Event
SDK 中虽然有 PlayServEvents.Publish、PublishForGroup 和 PublishForUser,但它们总是抛出 PlayServEventPublishingException。Editor 为 [Event] 类型生成的 Send… 辅助方法也是如此。要让其他 Player 那边发生某件事,请调用 Function 或你的 Game server,由它来发送 Event。
限制
| 项目 | 上限 |
|---|---|
| 每个连接的 Group 数 | 64 |
| Group 名称 | 最多 256 个字符,包括 PlayServ 添加的 Project 前缀 |
| Event 大小 | 1 MiB |
| 加入或离开 Group | 10 秒,超时抛出 TimeoutException |
错误
| 错误 | 何时出现 |
|---|---|
PlayServGroupSubscriptionException | 加入 Group 被拒绝:UnifiedError.SourceCode 为 group_subscription_limit_reached 或 group_outside_project。重试无济于事。 |
TimeoutException | 平台没有在 10 秒内响应加入或离开 Group 的请求。 |
PlayServEventPublishingException | 游戏尝试发送 Event。 |
无法解析为 T 的 Event 会被记录日志并丢弃;其他 Event 照常送达。
后续步骤
- Groups —— Event 发往的频道
- Cloud Function 与 RPC —— 请求服务器执行操作
- 托管 Game server —— 从 Unity Game server 发送 Event
更新于 2026年10月22日