跳到主要内容
Data 与 Schema

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

Schema 对象参考

Schema 由三类对象构成,对象又由字段构成。 Entity 存放游戏的 Record,Part 是 Entity 内部可复用的字段组,Enum 是固定的取值列表。本页是它们的参考说明;如何创建它们,见 Building a Game Schema。


Entity、Part 与 Enum

对象是什么有无自己的 Record示例
Entity独立对象:游戏读写的一张 Record 表。有,列在 Data 中Ships、Pilots、MatchResults
Part可复用的字段组,只存在于 Entity 或另一个 Part 内部。没有,其值存放在包含它的 Record 中Stats、Loadout
Enum字段允许取值的固定列表。没有ShipClass:Fighter、Bomber、Scout

字段类别

每个字段都有一个类别,它决定字段存储什么。

类别存储内容目标基数
Primitive直接存储一个值,类型为某种基本类型。—单个值
Enum referenceEnum 中的一个值。一个 Enum单个值
Relationship → entity通过 ID 链接到另一个 Entity 的 Record。一个 Entity一对一或一对多
Inclusion ↳ part嵌入到当前 Record 中的 Part 字段。一个 Part一对一或一对多

Relationship 和 Inclusion 都用于连接对象,但方式不同。Relationship 指向一条独立存在、可以共享的 Record:一个 pilot 指向一艘 ship,许多 pilot 可以指向同一艘 ship。Inclusion 嵌入的结构属于其父对象,没有独立的生命周期:一艘 ship 的 Stats 只作为这艘 ship 的一部分存在。

Relationship —— 链接到独立的 RecordPilotsShips外键Inclusion —— 嵌入的结构ShipsStats (part)

基本类型

类型存储内容
Text短字符串
Long text多行字符串
Integer整数
Number浮点数
Decimal定点精度数
Booleantrue 或 false
Date & timeISO 时间戳
Date日期,YYYY-MM-DD
UUID唯一标识符
JSON结构化对象
Email经过校验的邮箱地址
URL链接

字段设置

设置含义
Name由字母、数字和下划线组成,以字母开头,最多 64 个字符。Id、CreatedAt 和 UpdatedAt 为保留名称。
Default新 Record 未提供值时使用的值。
Required没有值的 Record 无法保存。
Unique任意两条 Record 不能有相同的值。
Indexed加快按该字段筛选和排序的速度。

Entity 设置

除了字段,Entity 还有几项设置。 它们在 Entity 编辑器中设置:新建时使用 New ▾ → Entity,已有的则点击名称旁的铅笔图标。

设置作用
Singleton entity该 Entity 恰好只有一条 Record,没有自己的业务键;引用它时无需 ID。适用于比赛规则这类全局配置。在 Data 中显示为单个表单,而不是列表。
Display field在任何引用 Record 的地方代表该 Record 的字段:关联单元格、Record 面板、Record 选择器。Auto 会自动选择一个。
Access control谁可以读写该 Entity 的 Record。见 Access Control。
Owned by player每条 Record 属于一个 Player,在 Player 创建它时由服务器标记。见 Player 拥有的 Entity。
Read access用于 Player 拥有的 Entity:Owner 表示每个 Player 只能读取自己的 Record,Public 表示所有人都能读取全部 Record。
On player delete用于 Player 拥有的 Entity,必填:Player 被删除时,其 Record 如何处理。
On player delete该 Player 的 Record
cascade-delete随 Player 一起删除。
anonymise保留,所有者替换为一个固定的匿名标记。
restrict保留;只要还存在这样的 Record,就无法删除该 Player。

原始字段

默认情况下,Record 只能包含其 Entity 声明的字段。Entity 也可以改为允许原始字段:这样 Record 就可以携带 schema 中未定义的额外键,用于存放你不想建模的自由格式数据。原始字段不能被筛选、排序或建立索引,只能通过读取 Record 获得。它们通过 API 或 MCP 开启;Backoffice 中没有对应的设置。

原始字段以结构换取灵活性

声明的字段经过校验、带有类型,并且可以查询;原始字段这些都不具备。只把它们用于总是整体读回的数据,需要搜索的内容都应建模。

从代码推送的 schema

Entity 或 Part 也可以来自游戏代码,而不是 Backoffice,通过 SDK 的 schema 工具推送。这样的对象带有 CODE 标签:其结构在 Backoffice 中只读,变更来自代码,而其 Record 在 Data 中仍可编辑。从代码推送无法接管在 Backoffice 中创建的同名对象。


后续步骤

更新于 2026年10月16日