Sandtable

主题

配置与公式引擎 ​

原则 ​

核心原则

配置描述数据,代码 / 脚本描述复杂行为。 不要让 YAML 成为编程语言。

yaml
# 数据与简单规则进配置
stats:
  attack: 100
  defense: 80
formula:
  damage: "max(1, attack - defense)"

涉及流程控制、多步状态的复杂行为,走 System 扩展机制(见下文),不往 YAML 里塞逻辑。

格式 ​

格式角色
YAML人类编辑的主格式
JSON机器交换与规范化权威格式(config_hash 以 canonical JSON 计算)
TOMLCLI / 工程配置,可选

YAML 库选型(决策记录) ​

  • serde_yaml:维护者已于 2024 年 3 月归档,声明不再维护,不采用;
  • serde_yml:此后出现的热门分支,现已同样停止维护且社区对其实现质量有争议,不采用;
  • 采用 serde_yaml_ng(serde_yaml 的维护分支,API 兼容)。

YAML 本身有隐式类型陷阱(如未加引号的 no / on 解析为布尔、1.10 解析为浮点)。约定:语义上非布尔的字符串一律加引号;机器间交换与哈希一律走 JSON。

参数注册表 ​

warrior.attack 这类点路径寻址需要中央注册表,否则 sweep 与 override 无从校验:

text
参数注册表:路径 → 类型 / 取值范围 / 默认值 / 说明
  • 加载时校验:未知路径报错、类型不符报错、越界报错;
  • 参数扫描的寻址、推荐的输出都基于注册表;
  • 注册表随 Model 编译生成,运行期零字符串查找;
  • 非数值槽(时长 Dur、公式 Expr、逐层表 Table)注册在案供校验与提示,但不进数值通道——不可扫描、不进参数表;
  • 遗留字段(如拆分前的 model.dungeon.reward_growth)只放行 YAML 加载并按旧语义映射,同样不进数值通道——旧配置载入结果不变,新写法显式给出时优先。

规范化与 config_hash ​

同一配置必须得到同一 hash

config_hash 的输入是规范化配置:键按字典序排序、去除注释与空白、数字统一表示,序列化为 canonical JSON 后取 SHA-256。键书写顺序不同、注释不同的两份 YAML,只要语义相同,hash 必须一致。

配置根节点带 schema_version 字段,用于配置结构演进时的兼容判断与迁移。

公式引擎 ​

能力范围(MVP) ​

受控表达式,不是通用语言:

text
算术 · 比较 · 布尔 · 内置函数(min / max / clamp / floor / ceil / abs / round) · 条件

示例:damage = max(1, attack * skill_ratio - defense)。

表查找(lookup)不在表达式层——它列在下方「后续扩展」;函数语义、运算符优先级与常用曲线形态(图由真实求值器采样生成)见25 章。

执行模型:加载期编译 ​

伤害这类公式在一次实验中要求数十亿次求值,是热点路径,必须编译执行:

text
加载期:解析 AST → 变量名解析为索引 → 编译为闭包 / 扁平指令
运行期:按索引取值求值,零字符串查找

现成方案评估(决策记录) ​

方案结论
evalexpr实现活跃,但自 13.x 起许可证为 AGPL-3.0,与本项目 Apache-2.0 不兼容,排除;旧 MIT 版本已停止维护,不采纳
rhaiApache-2.0 / MIT 双许可,维护活跃,提供 no-float 整数模式利于确定性。作为复杂行为脚本扩展的候选,留待后续阶段评估引入
内置最小求值器MVP 采用:能力范围有界(上文五类),加载期编译,无外部依赖

注意:内置最小求值器是有界的表达式求值实现,不是通用脚本引擎;需要图灵完备脚本时,应评估 rhai,而不是扩权表达式语法。

后续扩展 ​

函数、表查找、曲线(Curve)、分段(Piecewise)、分布采样,按 MVP 内置系统的实际需要逐步加入。

复杂行为扩展接口 ​

MVP 内置系统以 Rust 硬编码实现于 sandtable-core 的 systems 模块(crate 划分)。扩展接口的最小形态:

text
System trait
├── name()            系统标识
├── 订阅的事件类型     只响应声明过的事件
├── update(world, event)  状态变更入口
└── 确定性约束         状态遍历必须有序容器;随机消费必须带键

外部脚本(如 rhai)属于"自定义 System 实现"的一种载体,接口形态先定,载体后选。

载体拍板(2026-10-08)

复杂行为脚本的载体定为 Python(简单库多、仿真分析生态成熟),rhai 缓议。嵌入形态、三形态边界、性能红线与脚本安全策略见设计文档 scripts/scripting-design.md(已定稿待分期实施);脚本不进仿真热路径的量级论证见时间模型。

MVP 范围 ​

MVP 的最小 RPG 以硬编码数值跑通闭环(MVP),公式引擎与参数注册表在闭环验证后接入(见路线图 Phase 2)。

以 Apache-2.0 许可证发布

Sandtable Contributors