Events 系统

最后更新：2026 年 7 月 16 日

在 PlayServ 中，客户端与服务端之间的交互建立在 Event 之上。客户端和服务端都使用 Client SDK 提供的 Event。

何时使用 Events

当你需要通过 Client SDK 的 Event 机制把一个强类型 payload 从一端送到另一端时，就使用 Event：

用 [Event] 定义契约 —— 标识符和 payload
用 Send(...) 或生成的语法糖发送 Event
通过 Wait<T>(...) 订阅来接收
通过 Stop() 停止接收

信息

Event 为客户端与服务端之间的数据交换提供了一致、类型安全的契约：

payload 的结构由 [Event] 定义固定下来
借助自动生成的 Event 描述类，两端拿到的是同一份 Event 契约
语法糖减少了发送已注册 Event 时的样板代码

定义一个 Event

必须先定义 Event。定义会给它一个标识符，并说明它携带的 payload。

[Event]
class ChatMessage {
  string text;
  int priority;
}

Event 声明之后，代码分析器会根据这些声明生成语法糖，简化对已注册 Event 的使用。

发送 Event

Event 既可以用显式写法发送，也可以用生成的语法糖发送。

PlayServ.Send(new ChatMessage { text = "hello", priority = 1 });

PlayServ.SendChatMessage({ text = "hello", priority = 1 });  // sugar
PlayServ.SendChatMessage("hello", 1);                        // sugar

接收 Event

要在远端接收 Event，用 Wait 创建一个订阅。

var waiting = PlayServ.Wait<ChatMessage>(data => {
  chat.Write($"Message {data.text}");
});

取消订阅

要取消订阅，使用 Stop。

waiting.Stop();

两端共享的 Event 契约

对于在发送方代码中发现的每一个外部 [Event]，都必须在接收方代码中自动生成对应的 Event 描述类 —— 例如 ChatMessage。

注意

客户端与服务端共用同一份代码库是很常见的情况。此时在接收方生成 Event 描述类，可以保证契约在两端保持统一且类型安全。

下一步

RPC & Server-side Game Logic —— 与 Event 并行使用的、服务端具名操作
Groups —— Group 的 Event 使用同一套 Events API 和同样的语法糖模式

何时使用 Events​

定义一个 Event​

发送 Event​

接收 Event​

取消订阅​

两端共享的 Event 契约​

下一步​