本页尚未翻译,当前显示英文版本。
实时 Record
订阅一个查询或一个 Record 后,游戏会先收到它的完整当前状态,之后每次变化都会收到一份新的副本。 无需编写轮询代码:当其他 Player、某个 Function 或 Backoffice 中的运营人员修改了数据,你的 Changed 处理器就会带着新状态运行。示例使用 Sky Arena 的 Schema;C# 类型的写法见读取 Record。
using System.Collections.Generic;
using System.Linq;
using Playserv.Data;
using Playserv.DataSubscription;
using Playserv.Wrapper;
ISharedCollection<MatchResults> top = await PlayServData.Records<MatchResults>().SubscribeAsync(
new PlayServRecordQuery<MatchResults>()
.Where(m => m.Score >= 1000)
.WithLimit(50));
void Show(IReadOnlyList<MatchResults> results) =>
leaderboard.Show(results.OrderByDescending(m => m.Score).Take(10)); // sort on the client
Show(top.Items); // the current state, already there when SubscribeAsync returns
top.Changed += Show; // every change after that
订阅一组 Record
Records<T>().SubscribeAsync(query) 返回一个 ISharedCollection<T>。Items 保存匹配 Record 的值:SubscribeAsync 返回时,当前状态已经在其中。此后每次变化,Changed 都会带着完整的集合触发。Changed 不会为初始状态触发,所以要先显示 Items。每次都是整个集合被替换,而不是一份变更列表。
实时查询支持的功能比一次性读取的查询少:
| 功能 | 一次性读取 | 实时 |
|---|---|---|
Where、And、Include | 是 | 是 |
Or | 否 | 是,最多 8 组 |
对关联的关联使用 Include | 否 | 是 |
OrderBy、Search、Hide、游标 | 是 | 否:请在客户端排序 Record。 |
如果查询用到了该调用不支持的功能,会抛出 PlayServQueryCapabilityException,并指出需要去掉什么。
订阅单个 Record
record.SubscribeAsync() 让一个已加载的 Record 保持最新,并返回 IPlayServRecordSubscription<T>:
var pilot = await PlayServData.Records<Pilots>().LoadAsync(pilotId);
var live = await pilot.SubscribeAsync();
hud.SetLevel(pilot.Value.Level); // the state you loaded
live.Changed += change => hud.SetLevel(change.Record.Value.Level); // every change after that
| 成员 | 含义 |
|---|---|
Changed | Record 发生了变化。change.Record 是更新后的 Record;ChangedFields 列出变化的字段。 |
Conflict | 你在 Record 中还有未保存的编辑时,它在平台上被修改了。你会拿到两个版本:LocalValue 和 RemoteValue。 |
有未保存更改的 Record 不能开始订阅:请先保存或重新加载。部分 Record 会在订阅开始前被完整地重新加载。
会收到什么
| 时机 | 收到的内容 |
|---|---|
| 订阅开始时 | 当前状态,在 Items 中(或在你订阅的 Record 中)。Changed 不会触发。 |
| 匹配的 Record 被创建、修改或删除 | 集合新的完整状态,通过 Changed 送达。 |
通过 Include 关联的 Record 发生变化 | 同样是新的完整状态,其中关联的 Record 已更新。 |
单个 Record 订阅的事件在 Unity 主线程上送达,因此可以直接在处理器中更新 UI。
限制
| 项目 | 上限 |
|---|---|
| 实时集合中的 Record | 200 |
| 字段 | 64 |
| 过滤条件 | 16,每个 Or 组内也是 16 |
Or 组 | 8 |
Include 层级 | 6 |
让实时集合保持在 200 个 Record 以内
没有设置 WithLimit 的实时查询,如果匹配超过 200 个 Record,就会结束 —— 无论是一开始就超过,还是之后集合增长超过 200。请把 WithLimit 设为 200 或更小,或者收窄过滤条件。
订阅何时结束
出现以下情况时,订阅会永久结束:
- 它跟踪的 Record 被删除:此时
record.IsDeleted为 true; - 没有设置上限的集合增长超过 200 个 Record。
先触发 Failure 并给出原因,然后触发 Terminated。State 变为 Terminated,TerminalError 保存原因。你收到的最后一个状态仍保留在 Items 或 Record 中。要继续跟踪数据,请重新订阅。
停止订阅
不再需要订阅时调用 CloseAsync();如果无法等待,例如在 OnDestroy 中,则调用 Dispose()。State 变为 Closed,不会触发 Failure 或 Terminated。
void OnDestroy() => top?.Dispose();
相同的订阅会被共享
查询相同的多个订阅在平台上共用一个订阅。只有其中最后一个被关闭时,共享的订阅才会停止,所以你打开的每个订阅都要关闭。
重新连接
如果连接中断,State 会变为 Reconnecting;游戏恢复在线后,SDK 会重新打开所有未关闭的订阅,你无需写任何代码。随后订阅会收到当前状态,包括这段时间内发生的所有变化。参见连接与会话。
后续步骤
- 读取 Record —— 查询及其过滤条件
- 写入 Record —— 修改你正在跟踪 的 Record
- 连接与 Session —— 连接中断时会发生什么
更新于 2026年10月21日