跳到主要内容
Data 与 Schema

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

构建游戏 Schema

Schema 在 Schema 页面中构建,每项变更都通过迁移上线。 创建对象或编辑字段并不会立即生效,而是先暂存起来。准备好之后,把暂存的变更作为一次迁移来审阅并应用。在侧边栏 Engineering 下的 Schema 中打开它;它作用于顶栏所选的 Environment。

页面有三个标签页:Diagram 以图的形式展示整个 schema;Table view 展示单个对象及其字段;History 列出迄今为止已应用的迁移。在图中点击某个对象,会在 Table view 中打开它。对象和字段类别的说明见 Schema Object Reference。


先规划结构

动手创建之前,先梳理游戏要存储什么:哪些事物独立存在(Entity),哪些字段组会重复出现(Part),哪些值来自固定列表(Enum)。按这个顺序创建,先建 Enum 和 Part,这样在添加使用它们的字段时就可以直接选择。

常见错误正确做法
用 Relationship 链接一个属于父对象的结构用 Inclusion 嵌入它:ship 的 stats 属于这艘 ship。
用 Inclusion 嵌入一个独立存在的事物用 Relationship 链接它:pilot 指向一艘可被许多 pilot 共享的 ship。
在多个 Entity 中重复同一组字段把这组字段放进一个 Part,并在各处包含它。
用自由文本字段存放来自固定列表的值使用 Enum reference。

创建对象

选择类型

点击 New ▾,选择 Entity、Part 或 Enum。

填写内容

为它命名;如果是 Enum,还要填写取值。如果是 Entity,还要选择其设置:单例、访问权限和 Player 所有权。显示字段要等 Entity 有了字段之后再设置。

暂存

点击 Stage entity、Stage part 或 Stage enum。该对象会出现在 schema 中并标记为未保存,变更等待审阅。


添加字段

打开对象

在 Table view 中选择 Entity 或 Part,然后点击 Add field。

选择类别

选择 Primitive 及其类型、Enum reference 及对应的 Enum、Relationship → entity 及目标 Entity,或 Inclusion ↳ part 及对应的 Part。对于 Relationship 或 Inclusion,选择 1-to-1 或 1-to-many。

完成设置

为字段命名,可以选填 Default,并设置 Required、Unique 和 Indexed 约束。见字段设置。

添加

点击 Add field。和其他编辑一样,它在应用之前都处于暂存状态。

在 Table view 中,每个对象还会显示它在哪里被使用:Entity 显示 Referenced by,Part 显示 Included in,Enum 显示 Used by。


审阅并应用变更

暂存的变更会作为一次迁移一起上线。 只要有暂存内容,页头就会显示 Discard 和 Review migration;暂存的对象超过一个时,还会显示数量。

打开审阅

点击 Review migration。对话框会列出每项变更及其对现有数据的影响。

检查影响

影响含义
Backward compatible 或 Breaks backward compatibility现有的读写是否仍能正常工作。
Requires backfill现有 Record 需要为该变更补上一个值,例如新增了一个没有默认值的必填字段。
Rows affected (estimate)迁移会涉及多少条现有 Record。
Warnings会丢失的数据或仍在使用的值,见下文。

应用

点击 Apply migration。完成后,对话框会提示 schema 已是最新,或者迁移失败。Cancel 会关闭审阅,变更仍保持暂存。

Discard 会丢弃所有暂存内容。

暂存的变更保存在你的浏览器中

你暂存的变更会针对当前 Project 保存在这个浏览器中,直到你应用或丢弃它们。队友看不到这些变更,换一个浏览器也不会跟过去。

变更注意事项
把字段设为必填,且没有默认值现有 Record 需要一个值:迁移需要回填。
修改字段类型现有值必须能够转换;迁移需要回填。
在已有 Record 的 Entity 上把字段设为唯一现有 Record 之间不能有重复值。
移除字段其数据会被删除,见移除字段并找回。
移除 Enum 取值Record 可能仍在使用它;审阅时会发出警告。

删除对象

对象编辑器中的 Delete entity、Delete part 或 Delete enum 会立即删除该对象,不经过迁移。仍被引用、包含或使用的对象,要等到没有任何地方指向它之后才能删除。删除带有 Record 的 Entity 时需要输入其名称。删除 Part 时,所有包含它的 Entity 中存储的相应行也会一并删除。

删除对象不会暂存

与其他变更不同,删除在你确认的那一刻就生效,没有可以撤回的审阅步骤。


移除字段并找回

当迁移移除一个可选字段时,其数据会保留 7 天。在此期间,该字段仍可读取,但不能写入。要找回它,在新的迁移中添加一个名称和类型都相同的字段;类型不同会被拒绝。7 天之后,数据将被永久删除。

必填字段或 Entity 的键没有这样的保留期:迁移应用时,其数据即被删除。


历史记录

History 列出该 Project 的迁移,按时间从新到旧排列,并用徽章标出每次迁移的风险程度:Safe、Caution 或 Breaking。从未应用的迁移不显示版本号,而是显示其状态:Draft、Planned、Applying、Failed 或 Cancelled。可以按时间范围筛选列表。


后续步骤

更新于 2026年10月16日