本页尚未翻译,当前显示英文版本。
读取 Record
游戏通过 PlayServData.Records<T>() 以强类型 C# Record 的形式读取数据。 Schema 中的每个 Entity 都对应一个 C# 类;你可以按 ID 加载单个 Record,也可以用过滤、排序和分页查询多个 Record。示例使用 Sky Arena 的 Schema:Ships、Pilots、MatchResults 和单例 ArenaConfig。
using Playserv.Data;
using Playserv.Wrapper;
using UnityEngine;
var ships = PlayServData.Records<Ships>();
// One record by ID
PlayServRecord<Ships> ship = await ships.LoadAsync(shipId);
Debug.Log(ship.Value.Name);
// Ships up to 500, cheapest first, 20 per page
var page = await ships.QueryAsync(
new PlayServRecordQuery<Ships>()
.Where(s => s.Price <= 500)
.OrderBy(s => s.Price),
new PlayServPagination(limit: 20));
Entity 对应的 C# 类型
每个 Entity 都需要一个名称和字段都与之一致的 C# 类。 这些类可以从 Schema 生成,也可以自己编写。
| 方式 | 做法 |
|---|---|
| 从 Schema 生成 | 在 Tools ▸ PlayServ ▸ Settings 的 Schema Workflows 下选择 Import JSON & Generate。类文件写入 Assets/Shared/Generated/Models,每次生成都会覆盖。 |
| 自己编写 | 普通 C# 类,无需基类。配合本地 Schema 工具,同样的类还可以用来定义 Schema,参见访问控制。 |
public class Ships
{
public string Name;
public ShipClass Class;
public Stats Stats; // an included part
public int Price;
}
public class Stats { public double Speed; public int Armor; public int Damage; }
public class Pilots
{
public string Callsign;
public int Level;
public PlayServRecordRef<Ships> Ship; // a relation
public Loadout Loadout;
}
| 规则 | 原因 |
|---|---|
| 类名与 Entity 名完全一致。 | Records<Ships>() 按类名查找 Entity。如果两者不同,请用 Records<T>("ent_…") 并传入 Entity 的 ID。 |
| 字段名与 Schema 完全一致,包括大小写。 | 字段以 C# 名称发送。[PlayServField("name")] 可映射为其他名称,[PlayServIgnore] 可排除某个成员。 |
| 包含的 Part 是嵌套类或列表。 | 它们存储在 Record 内部。 |
关联使用 PlayServRecordRef<T>(SDK 0.6.4 及以上),或像生成的类那样,用字符串保存目标的 ID。 | Record 只存储 ID;参见关联。 |
加载得到的 Record 类型为 PlayServRecord<T>:字段在 Value 中,Record 还带有 Id、Owner、CreatedAt 和 UpdatedAt。ID 永远不需要你自己设置,由 PlayServ 生成。
加载单个 Record
| 调用 | 返回 |
|---|---|
LoadAsync(id) | 具有该 ID 的 Record。如果不存在,抛出 PlayServRecordNotFoundException。 |
LoadByNaturalKeyAsync(PlayServNaturalKey<T>.For(x => x.Name, "Falcon")) | 唯一字段为该值的 Record。该字段必须在 Schema 中标记为 Unique。 |
LoadManyAsync(ids) | 按 ID 加载多个 Record,顺序与请求一致,每个 ID 对应一个结果。 |
var falcon = await ships.LoadByNaturalKeyAsync(PlayServNaturalKey<Ships>.For(s => s.Name, "Falcon"));
查询
QueryAsync(query, pagination) 返回一页与 PlayServRecordQuery<T> 匹配的 Record。
| 方法 | 作用 |
|---|---|
Where(x => …) · And(x => …) | 用 C# 条件过滤:==、!=、>、>=、<、<=、空值检查、&&,以及 list.Contains(x.Field)。 |
Where(x => x.Field, PlayServQueryOperator.…, value) | 用运算符过滤:Eq、Neq、Gt、Gte、Lt、Lte、In、Nin、Between、Contains、StartsWith、EndsWith、IsNull、IsNotNull、IsEmpty、IsNotEmpty,以及用于列表长度的 Count…。 |
OrderBy(x => …) · OrderByDescending(x => …) | 排序。 |
Search("text") | 对 Entity 做全文搜索。 |
SelectFields(...) · Hide(...) | 只加载部分字段,参见下文。 |
| 分页 | 作用 |
|---|---|
new PlayServPagination(limit: 20) | 每页 Record 数:默认 50,最多 200。 |
page.Records · page.HasMore · page.NextCursor | 本页 Record、是否还有更多,以及下一页的游标:以 new PlayServPagination(page.NextCursor, 20) 的形式传入。 |
LoadAllAsync(query) | 自动逐页读取,默认最多 1000 条 Record;IsTruncated 表示是否还有剩余。 |
按名称过滤 Enum 字段
要按 Enum 字段过滤,请与取值的名称比较:Where("Class", PlayServQueryOperator.Eq, "Fighter")。对 Enum 使用 C# 条件,例如 x.Class == ShipClass.Fighter,可能匹配不到结果。
关联与 Part
Part 是 Record 的一部分:它们随 Record 一起加载,你可以用嵌套路径按其字段过滤,例如 .Where(s => s.Stats.Speed > 10)。
关联只存储目标的 ID。要获取目标 Record:
| 调用 | 作用 |
|---|---|
await pilot.Value.Ship.LoadAsync() | 加载关联的飞船。如果它已不存在,返回 null,不会抛出异常。 |
在查询上使用 .Include(p => p.Ship) | 把关联的 Record 与本页一起加载:飞船的字段随后就在 pilot.Value.Ship.Value 中,无需额外调用。查询只能包含直接关联;实时 Record 可以包含嵌套关联。 |
只加载部分字段
SelectFields 只加载你列出 的字段,Hide 则加载除这些之外的所有字段;两者只能选其一。这样加载的 Record 是部分 Record:IsPartial 为 true,在调用 ReloadAsync() 之前无法保存。
部分 Record 无法保存
SDK 会拒绝保存,并抛出 InvalidOperationException。请先重新加载 Record,或者不使用 SelectFields 加载。
单例
单例 Entity 只有一个 Record,用 GetSingletonAsync<T>() 读取:
PlayServSingleton<ArenaConfig> config = await PlayServData.GetSingletonAsync<ArenaConfig>();
int maxPlayers = config.Value.MaxPlayers;
单例没有 ID,不能删除,也不能订阅。
错误
| 异常 | 何时出现 |
|---|---|
PlayServRecordNotFoundException | 没有具有该 ID 或自然键的 Record。 |
PlayServDataAccessDeniedException | 游戏无权读取该 Entity,参见访问控制。 |
PlayServQueryCapabilityException | 查询用到了该调用不支持的功能,参见实时 Record。 |
PlayServDataException | 其他所有情况:StatusCode、BackendCode 和 IsNetworkError 说明发生了什么。 |
Player 只能看到自己在 Player 所有的 Entity 中的 Record
对于归 Player 所有、读取权限为 Owner 的 Entity,查询只返回当前登录 Player 的 Record。参见 Player 所有的 Entity。
后续步骤
更新于 2026年10月21日