跳到主要内容

PlayServ SDK 架构与组件

最后更新：2026 年 7 月 16 日

PlayServ 由一组组件构成，这些组件被划分为四个层次。理解这个结构，有助于你为每项任务找到合适的工具 —— 无论是建立 Session、查询数据、运行服务端逻辑，还是搭建一个多人 Room。

Gameplay ComponentsApplication ComponentsPlatform ComponentsBasic ComponentsMovement PredictionData InterpolationData BindingGroup (Room)SessionAuthorisationSDK ConfigurationModelEntityStateQuerySchemaCommand (RPC)PubSubEvent

四个层次​

组件图自上而下组织：上层依赖下层。

Basic Components 是地基，其余每一层都建立在它之上。数据访问、查询、订阅、RPC 命令、Event 和 Session 状态都在这里。

Platform Components 定义运行时上下文。Session、授权和 SDK 配置属于这一层 —— 在 gameplay 开始之前，是它们赋予客户端身份和运行状态。

Application Components 在地基之上提供产品级的功能。Group 和 Room 就在这一层。

Gameplay Components 是面向游戏的模块，消费数据和状态 —— 通常是游戏代码之前的最后一层。它们可能会应用插值、预测之类的手法。

Platform 层​

1

Session

Session 是客户端所处的运行时上下文。它保存当前状态 —— Offline、Recovering、Active 或 Banned —— 并驱动客户端在重连与正常运行之间的转移。SDK 中其余的一切都以存在一个 Session 为前提。想了解客户端如何在这些状态之间移动、每个状态对你的游戏意味着什么，请读 Session Lifecycle & States。

2

Authorisation

授权代表当前 Session 的权限级别。未认证的 Session 从最低权限开始。传入 UserToken 会提升它，把 Session 绑定到某个用户档案，并解锁受保护的操作。何时以及如何传这个 token，见 User Login & Authentication。

3

SDK configuration

SDK 配置保存着让运行时识别出正确 Project 和 Environment 的凭据与设置。如果你还没配置好 Project 凭据，SDK Initialisation & Handshake 会逐项讲清楚每个输入是什么、从哪里来，以及如何在 Unity 中配置。

Application 层​

1

Group (Room)

Group 负责组织客户端连接，支持广播式通信和在线状态跟踪。Group 位于基础层之上，借助基础层完成信令和服务端行为 —— 包括可扩展的加入和离开流程。如何创建、加入 Group，以及如何用自定义的服务端规则扩展它，见 Groups。

Basic 层​

1

Model, Query & Schema

Model 是操作游戏数据的入口，它把客户端代码接到查询、过滤、修改和订阅上。Query 负责构造和过滤数据请求。Schema 定义数据结构以及对象之间的关系 —— 正是它让嵌套读取和关系的自动展开成为可能。完整的查询语法见 Query Language & Data Retrieval。

2

PubSub

PubSub 是驱动实时更新的订阅机制。服务端数据一旦变化，Delta 会立即送达已订阅的客户端。第一次送达的是完整快照，之后的更新是自动应用的 JSONPatch Delta。如果你想在本地保有一份与服务端同步的数据副本、又不想轮询，Data Subscriptions & Live Updates 讲了怎么做。

3

Entity

Entity 提供以实体为中心的数据与行为视角。它位于数据访问和命令之间，正是它让你可以把领域行为 —— 比如 player.Shoot() —— 作为具名的 RPC 方法挂到某个 Model 类型上。如何持久化字段改动、如何用自定义方法扩展 Model，见 Data Mutation & Model Extending。

4

Command (RPC)

Command 是执行服务端具名操作的机制。服务端代码写在客户端代码库里，由代码分析器发现，并部署到服务端运行时。客户端代码通过 PlayServ.Remote(...) 调用它。完整的执行模型见 RPC & Server-side Game Logic。

5

Event

Event 是两端共享的强类型信令机制。Event 用 [Event] 声明，通过 Send(...) 或生成的语法糖发送，通过 Wait<T>(...) 接收。借助自动生成的 Event 描述类，客户端和服务端拿到的是同一份契约。完整 API 见 Events System。

6

State

State 是运行时各项功能底下的状态层。Session 的状态转移 —— Offline → Recovering → Active —— 是它最显眼的用途，但它同样支撑着 SDK 的其他组件。这些状态以及订阅它们的方式，见 Session Lifecycle & States。

连接路径​

组件图描述的是逻辑组件。物理入口 —— 客户端究竟如何连上 PlayServ —— 由 Proxy 和 handshake 流程单独负责。token 在那里被校验，连接策略在那里被执行，ClientReady 也在那里发出，之后 gameplay 系统才能安全启动。想弄清楚从调用 PlayServ.Ready(...) 到 Session 进入 Active 之间发生了什么，Proxy Module & Handshake 把这个流程讲得很细。

下一步​

按这个阅读顺序，从配置一路走到第一个处于 Active 的 Session：