面向读者

验证等级

仅配置编译通过。 程序通过公开 Registry 选择结果和编译计划检查三层配置，不启动 PyBullet，也不宣称原生物理行为通过。

文件说明

  • run.yaml 创建可调方块，并覆盖尺寸与密度。
  • main.py 对比 Manifest 默认值、PyBullet Variant 默认值和最终 Run 实例。
  • ../catalog/tunable_box.yaml 定义默认值、Variant、资源与参数 Schema。

合并顺序

对一个实体，FastSim 按以下顺序应用配置：

  1. manifest.defaults 提供跨后端基础值（密度 500、标签与尺寸）。
  2. variants.pybullet.defaults 只替换它声明的字段（密度 750）。
  3. run.yaml 中的实体最后生效（密度 900、实例尺寸）。

深度合并会保留后续层没有提到的字段，因此最终标签仍是 default-box。Variant 由 Run 最终选择的 backend 决定。

Manifest 与 Run

Manifest 只校验 params：

yaml
config_schema:
  type: object
  properties:
    density_kg_m3: {type: number, minimum: 1.0}
    label: {type: string}
  required: [density_kg_m3, label]
  additionalProperties: false

config_schema 不会校验 pose、scale、enabled 或 initial_state 等标准实例 字段；这些由 FastSim Run Schema 校验。Run 只覆盖本实例不同的值：

yaml
box:
  use: object://fastsim/component-demo-tunable-box
  scale: [0.3, 0.2, 0.1]
  params:
    density_kg_m3: 900.0

运行

bash
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.objects.box.params.label
python main.py

预期 Python 输出显示密度 500.0 → 750.0 → 900.0，以及继承的标签 default-box。

常见错误

  • 把 scale 放进 params：scale 是标准实体字段。
  • 期待 config_schema 校验整个 Run：它只约束本组件的 params Mapping。
  • 写入未知参数：additionalProperties: false 会拒绝拼写错误。
  • 在每份 Run 中重复所有默认值：只需覆盖真正不同的部分。

上一节：08 — Scenario 组件 · 下一节：10 — 版本与稳定版本