面向读者
验证等级
仅配置验证。 FastSim 会解析真实 URDF，并编译 object 实例。不会启动 PyBullet， 因此这不是物理或渲染验收。
文件说明
run.yaml放置并缩放一个组件实例。main.py断言组件 kind 和最终实体值。- Object manifest 是可复用目录条目。
../catalog/index.yaml发布其 stable 版本。
逐行阅读组件 manifest
yaml
schema: fastsim-component/1 # 必需的组件协议。
id: object://fastsim/component-demo-cube # 命名空间和稳定组件名称。
version: 1.0.0 # Registry 选择的发布版。
kind: object # 限制其用于 objects 场景分组。
semantics:
category: primitive # 可选的可移植元数据。
variants:
pybullet: # 本案例使用的后端表达。
resources:
model: # 该 variant 内的唯一名称。
uri: assets/cube.urdf
format: model/vnd.urdf+xml # 显式格式，不依赖文件名猜测。
role: simulation # 用于创建实体的资源。
编写自己的 object 组件时，复用这个外层结构，选择全局唯一的 object:// identity，
在不兼容修改时提升 version，并给每个后端 variant 指向适合的资产。然后在 Registry
index 中添加发布记录和 manifest SHA-256。不要把摆放位置写进 manifest：位置属于每个
Run 实例。
逐行阅读 run.yaml
yaml
schema: fastsim/2 # Run 编写协议。
name: object-component # 用于诊断和 lock 的名称。
backend: pybullet # 选择 URDF variant。
runtime:
physics_hz: 60 # 物理时钟声明。
control_hz: 30 # 控制时钟声明。
seed: 102 # 可复现随机种子。
scenario:
scene:
objects:
workpiece: # 实例别名，而非组件 identity。
use: object://fastsim/component-demo-cube
pose:
xyz_m: [0.35, -0.10, 0.20] # 每个实例的世界位置，单位米。
quat_xyzw: [0.0, 0.0, 0.0, 1.0] # 每个实例的方向。
scale: [0.25, 0.25, 0.25] # 正数 XYZ 缩放倍数。
enabled: true # 将该实体包含在场景中。
同一个组件可以在不同别名、位置、缩放和实例参数下出现多次。use 决定“它是什么”，
外围映射决定“这一次如何摆放”。
main.py 验证什么
脚本相对于 __file__ 找到 run.yaml，加载最近的 project，并通过公开
load_project API 编译。随后读取 plan.entities["objects.workpiece"] 并检查：
- manifest 声明了
kind: object； - 选择了 PyBullet variant；
- pose、scale 和
enabled原样进入不可变 plan； - 实例指向精确解析后的组件。
运行
bash
cd demo/components/02_object_component
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.objects.workpiece.scale
fastsim config lock run.yaml --output run.lock.yaml
fastsim config verify-lock run.lock.yaml --json
python main.py
预期输出
text
Entity: objects.workpiece
Component: object://fastsim/component-demo-cube@1.0.0
Pose xyz_m: (0.35, -0.1, 0.2)
Scale: (0.25, 0.25, 0.25)
Resource: model/vnd.urdf+xml
常见错误
- 把 object 放在
robots:或articulations:下会造成 kind 不匹配并被拒绝。 - scale 不可为零或负数，三个值都必须为正。
quat_xyzw必须是四个有限值，并使用 XYZW 顺序。- 资产路径相对于 manifest，而不是相对于
run.yaml。 - 修改已发布 manifest 时必须更新 Registry 摘要，通常还应发布新语义版本。