项目配置

项目清单既可以只是 schema root，也可以是完整的构建描述。它可以写成 TOML、YAML、JSON 或 Lua；本页示例使用 TOML。

package = "game_config"
includes = ["schema/items.toml"]

[parsers]
scripts = ["tools/parsers.lua"]

[type_mappings]
scripts = ["tools/type_mappings.lua"]

[build]
default_source_format = "xlsx"
data_root = "data"
schema_lock = "generated/schema.lock"
excel_templates = "generated/excel"

[[build.codegen]]
target = "rust"
out = "rust/src/generated"
format = "auto"

[[build.exports]]
format = "binary"
out = "generated/config.sora"

运行所有配置好的输出：

sora build --project project.toml

data_root 和 excel_templates 的用途不同。data_root 是 export 和 build 读取的输入目录，里面放已经填写过行数据的文件。excel_templates 是生成 workbook 模板的输出目录，schema 变更后可以删除并重新生成。不要把 excel_templates 指向已经编辑过的数据目录，除非你明确想替换那些 workbook。

[parsers].scripts 列出 CLI 读取该 project 时使用的自定义 Lua 单元格 parser 脚本。路径相对 project 文件所在目录。脚本 API 见单元格 Parser。

[type_mappings].scripts 列出用于自定义生成语言类型的 Lua 脚本。路径相对 project 文件所在目录。类型映射只影响 codegen：schema 仍然使用 struct<Vec3> 这类语言无关的 Sora 类型，映射脚本可以把这个命名类型映射到目标语言自己的类型。

多语言通过 project root 的 [localization] 声明。它的 sources 独立于普通 [[tables]]；见多语言。

只运行一个配置好的 codegen target：

sora build --project project.toml --target rust

Target Options

语言相关选项放在 [codegen.<target>] 下：

[codegen.rust]
runtime_format = "sora"

[codegen.typescript]
runtime_format = "json"
enum_repr = "string"

[codegen.lua]
runtime_format = "cbor"
lua_version = "5.4"

这些选项由对应生成器消费。归一化 IR 保持语言无关。

类型映射脚本返回带 type_mappings 的 table。每条映射对应一个目标语言和一个命名 schema 类型：

return {
  type_mappings = {
    {
      target = "csharp",
      schema_type = "Vec3",
      type_name = "Vector3",
      nullable_type_name = "Vector3?",
      decode = "GameMappings.ToVector3({value})",
      value_decode = "GameMappings.ToVector3({value})",
      imports = { "UnityEngine" },
    },
  },
}

nullable_type_name 是可选字段。当 optional<schema_type> 需要不同于后端默认 nullable wrapper 的目标语言类型表达式时使用它。

decode 包裹默认的 binary runtime decode 表达式，value_decode 包裹 JSON/CBOR/protobuf 风格的 value decode 表达式。{value} 会替换成生成器默认生成的表达式。

C target 使用写入目标指针的 decode 函数，所以 C 映射应使用 decode_into，而不是 decode。{target} 会替换成输出指针表达式。C 映射也可以提供 free，其中 {target} 会替换成需要释放的指针：

{
  target = "c",
  schema_type = "Vec3",
  type_name = "game_vector3",
  decode_into = "game_vector3_decode(reader, {target})",
  free = "game_vector3_free({target});",
  imports = { "#include \"vector3.h\"" },
}

imports 是目标语言相关的，只由需要它的语言生成器输出。C#、Java、Kotlin、Scala 期望不带关键字的 namespace/path；Go 期望类似 "example.com/game/vector" 的 import spec；Python、TypeScript、JavaScript、Dart、Godot、C、C++、Rust 期望完整 import/include/use/preload 行。

runtime_format 可以是 sora、json、cbor 或 sora-protobuf，但不是每个 target 都支持所有 runtime format。支持矩阵见运行时格式。

内置 Target Options

包含多种语言选项的示例：

[codegen.rust]
runtime_format = "sora"
map_type = "fx_hash_map"
string_storage = "arc"

[codegen.cpp]
runtime_format = "sora"
cpp_standard = "c++20"
namespace = "game::config"

[codegen.javascript]
runtime_format = "json"
enum_repr = "integer"
emit_dts = true