跳到主要内容
服务端逻辑与 Events

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

服务器 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 ServerPlayServGameServer.Events.PublishAsync(group, eventType, payload),使用 Group 带 Project 前缀的名称,参见 Groups。
C# Cloud FunctionPlatform.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
加入或离开 Group10 秒,超时抛出 TimeoutException

错误

错误何时出现
PlayServGroupSubscriptionException加入 Group 被拒绝:UnifiedError.SourceCode 为 group_subscription_limit_reached 或 group_outside_project。重试无济于事。
TimeoutException平台没有在 10 秒内响应加入或离开 Group 的请求。
PlayServEventPublishingException游戏尝试发送 Event。

无法解析为 T 的 Event 会被记录日志并丢弃;其他 Event 照常送达。


后续步骤

更新于 2026年10月22日