跳到主要内容
Data 与 Schema

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

实时 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
成员含义
ChangedRecord 发生了变化。change.Record 是更新后的 Record;ChangedFields 列出变化的字段。
Conflict你在 Record 中还有未保存的编辑时,它在平台上被修改了。你会拿到两个版本:LocalValue 和 RemoteValue。

有未保存更改的 Record 不能开始订阅:请先保存或重新加载。部分 Record 会在订阅开始前被完整地重新加载。


会收到什么

时机收到的内容
订阅开始时当前状态,在 Items 中(或在你订阅的 Record 中)。Changed 不会触发。
匹配的 Record 被创建、修改或删除集合新的完整状态,通过 Changed 送达。
通过 Include 关联的 Record 发生变化同样是新的完整状态,其中关联的 Record 已更新。

单个 Record 订阅的事件在 Unity 主线程上送达,因此可以直接在处理器中更新 UI。


限制

项目上限
实时集合中的 Record200
字段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 会重新打开所有未关闭的订阅,你无需写任何代码。随后订阅会收到当前状态,包括这段时间内发生的所有变化。参见连接与会话。


后续步骤

更新于 2026年10月21日