类型

Sora 的类型表达式在 schema 字段中以字符串形式书写。

原始类型

类型	含义
`bool`	布尔值。
`i8`	8 位有符号整数。
`u8`	8 位无符号整数。
`i16`	16 位有符号整数。
`u16`	16 位无符号整数。
`i32`	32 位有符号整数。
`u32`	32 位无符号整数。
`i64`	64 位有符号整数。
`f32`	32 位浮点数。
`f64`	64 位浮点数。
`string`	UTF-8 字符串。
`duration`	非负时长，写作 `500ms`、`30s`、`15m`、`2h`、`7d` 或 `1h 30m` 这类单位组合。单位必须按从大到小排列：`d`、`h`、`m`、`s`、`ms`。运行时数据存储为毫秒。
`text`	多语言文案 key。见多语言。

Sora 会在导出前校验整数宽度范围。部分目标语言没有 unsigned 小整数类型，生成代码可能使用更宽的 signed 类型承载，但 schema 范围语义仍然保留。

[[tables.fields]]
name = "level"
type = "u16"
range = [1, 100]

Named Types

Type	Example
Enum	`enum<ItemType>`
Struct	`struct<ResourceCost>`
Union	`union<RewardAction>`
Reference	`ref<Item.id>`

引用必须指向 mode = "map" 表的主键。容器可以包住引用，例如 list<ref<Item.id>>。

[[tables.fields]]
name = "item_type"
type = "enum<ItemType>"

[[tables.fields]]
name = "price"
type = "struct<ResourceCost>"
parser = { kind = "tuple" }

Collections

Type	Meaning
`list<T>`	有序重复值。
`set<T>`	唯一重复值。
`array<T,N>`	固定长度重复值。
`map<K,V>`	键值对。
`optional<T>`	可空或可缺省值。

[[tables.fields]]
name = "tags"
type = "set<string>"
parser = { kind = "json" }
default = "[\"misc\"]"

[[tables.fields]]
name = "attributes"
type = "map<string,i32>"
parser = { kind = "map" }

单元格示例

这些例子展示策划在 Excel 或 CSV cell 里会填写什么：

字段类型	Parser	Cell 值
`u16`	无	`1001`
`enum<ItemType>`	无	`Weapon`
`list<i32>`	无或 `split`	`1,2,3`
`duration`	无	`1h 30m`
`text`	无	`quest.1001.title`
`set<string>`	`json`	`["starter","melee"]`
`struct<ResourceCost>`	`tuple`	`Gold,0,100`
`struct<ResourceCost>`	`columns`	展开到 `cost_kind`、`cost_id`、`cost_count` 多列
`map<string,i32>`	`map`	`atk,10\|hp,20`
`union<EventCondition>`	`json`	`{"type":"QuestCompleted","quest_id":5002}`
`optional<ref<Item.id>>`	无	空 cell 或 `1001`

Field Rules

[[tables.fields]]、[[structs.fields]] 和 [[unions.variants.fields]] 共享通用字段属性。表字段额外拥有派生值相关属性；这些表专用属性不能写在 struct field 或 union variant field 上。表主键只在表本身用 key = "field_name" 声明一次。

字段是否可缺省由类型表达：optional<T> 表示值可以缺失或为空；其它类型都要求有值，除非 default 填充了缺失值。

对 TOML/JSON/YAML 这类 object 输入，字段可以不存在。对 Excel 和 CSV，表头列必须存在；某一行没有对应 cell、cell 为空，或者 CSV 行列数不够，都会按空 cell 处理。

Schema 字段	object 字段不存在	Excel/CSV cell 为空
`type = "i32"`	校验错误。	校验错误。
`type = "optional<i32>"`	`null`。	`null`。
`type = "i32"` 加 `default = "1"`	`1`。	`1`。
`type = "optional<i32>"` 加 `default = "1"`	`1`。	`null`。

Property	适用范围	作用
`name`	所有字段	字段名。用于源数据、校验错误、生成代码和导出的运行时数据。
`type`	所有字段	类型表达式，例如 `i32`、`struct<ResourceCost>` 或 `list<union<RewardAction>>`。
`default`	除派生字段外的所有字段	object 字段不存在，或 required Excel/CSV cell 为空时使用的字符串值。
`comment`	所有字段	用于生成 Excel 表头说明。
`range`	数值字段、`duration`，以及这些类型的集合元素	数值闭区间，写作 `[min, max]`。`duration` 的范围单位是毫秒。
`length`	`string`、`list`、`set`、`array`、`map`	长度闭区间，写作 `[min, max]`。
`parser`	单元格输入和 default	单元格 parser 提示。见单元格 Parser。
`scope`	所有字段	仅在选定 generation/export scope 下包含该字段。默认是 `all`。
`from`	仅表字段	可选的子表来源，用来声明派生字段。

default 写成字符串，因为它会走和源数据相同的类型感知转换路径。

from 用来描述从另一张表匹配行得到的派生字段，详见引用和派生字段。派生字段可以是 list<T>、T 或 optional<T>，且不能声明 default。

Keyboard shortcuts

Sora

类型

原始类型

Named Types

Collections

单元格示例

Field Rules