环境要求

  • Python 3.11 或 3.12
  • FastSim 0.1.0a6
  • UniRoboSim Core 0.10.0
  • 这个纯编译示例不需要原生仿真器

配置

人类编写的 Run 声明 backend: pybullet。共享机械臂 component 有三个 backend variant：

  • PyBullet 选择 two_joint_arm.urdf；
  • MuJoCo 选择 two_joint_arm.urdf；
  • Isaac Lab 选择 two_joint_arm.usda。

override 会改变本次编译输入，所以不可变 plan digest 也会改变；它不会编辑 run.yaml。

关键代码逐行说明

python
project = load_project(RUN_FILE)                    # 查找受信任 demo Registry。
compiler = project.compiler()                       # 创建公共编译器。

fundamentals/.fastsim/ 下的 project 文件让每个 fundamentals 目录都能访问共享组件 registry。

python
for backend in ("pybullet", "mujoco", "isaaclab"):
    compiled = compiler.compile_file(
        RUN_FILE,
        backend_override=backend,                   # 只覆盖本次调用。
    )

每次循环都验证同一份 authoring，选择对应 backend variant，解析资源，并冻结一份 ExecutionPlan。

python
origin = compiled.explain("backend").origin

explain() 会证明有效 backend 来自 api_override，而不是源文件被静默修改。

运行

从本案例目录运行：

bash
cd demo/fundamentals/16_backend_selection
python main.py

等价 CLI 编译命令为：

bash
fastsim config validate run.yaml --backend pybullet --json
fastsim config validate run.yaml --backend mujoco --json
fastsim config validate run.yaml --backend isaaclab --json

如果要启动而不只是编译，同一个 CLI 参数也可用于 run：

bash
fastsim run run.yaml --backend isaaclab --duration 3

Adapter 兼容性是另一道门禁

编译成功只能证明 Run 和选中的 component variant 有效。原生启动还要求 provider 与已安装 UniRoboSim Core contract 匹配。本 FastSim 版本固定 Core 0.10.0，所以原生运行必须使用 兼容 Core 0.10 的 adapter。当前 Isaac adapter 0.10.1 与之匹配；已经发布的 PyBullet/MuJoCo 0.9.2 也与 FastSim 冻结的别名矩阵精确匹配。即使 plan 能编译， 其他 adapter 版本仍会在启动时被拒绝。

验证等级

纯编译已通过。 Python 语法、默认 Run，以及三个 backend_override 编译全部通过。 选择结果分别为 pybullet/URDF、mujoco/URDF、isaaclab/USD，plan digest 各不相同。 本例不启动任何原生 backend。

常见错误

  • 认为 backend_override 会修改 run.yaml：它只影响一次编译。
  • 对锁定 Run 使用 override：lock 会按设计拒绝更换 backend。
  • 把编译成功当成原生兼容：provider 加载属于独立 runtime 门禁。

下一步：17 · 液体。