验证等级

仅配置。 本例只编译和检查 Run，不会启动仿真器，也不需要 GPU。

前置条件

  • Python 3.11 或 3.12 环境中的 FastSim 0.1.0a6。
  • 完整保留此 demo/ 目录及其 _shared/ 内容的源码检出。

文件

  • run.yaml 选择 PyBullet、60 Hz 物理频率和一个红色方块。
  • main.py 从 Python 调用同一套编译器，并打印不可变计划的身份信息。
  • ../.fastsim/project.yaml 告诉 FastSim 到哪里查找共享 Registry。

逐行理解配置

yaml
schema: fastsim/2          # 使用干净的 FastSim vNext 配置协议。
name: demo-config-validation
backend: pybullet          # 为每个组件解析 PyBullet 变体。

runtime:
  physics_hz: 60           # 每模拟秒执行 60 个物理步。
  control_hz: 30           # 以 30 Hz 接纳控制帧；本例不会发送控制。
  seed: 7                  # 让 reset 可复现。

scenario:
  scene:
    objects:
      red_cube:            # 当前 Scenario 内方便人阅读的别名。
        use: object://fastsim/demo-cube  # 从 Registry 解析稳定组件。
        pose:
          xyz_m: [0.0, 0.0, 0.5]        # 世界坐标，单位是米。
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]  # 单位四元数，顺序为 XYZW。

use 不是文件路径。项目 Registry 会把它映射到固定的 component manifest， manifest 再选择当前后端接受的资产。

逐步理解 Python

  1. Path(__file__).with_name("run.yaml") 找脚本同目录下的 Run，不依赖终端当前目录。
  2. load_project(RUN_FILE) 向上寻找 .fastsim/project.yaml，加载 Registry 和可信资产根目录。
  3. project.compiler().compile_file(RUN_FILE) 完成验证、解析、规范化和冻结。
  4. compiled.execution_plan 是后端可执行的不可变计划。有效仿真语义改变时，它的 SHA-256 digest 也会改变。

main.py 没有任何一行会创建仿真器 session。

运行

在本案例目录执行：

bash
cd demo/fundamentals/01_config_validation_and_compilation
fastsim config validate run.yaml --json
fastsim config expand run.yaml
python main.py

预期看到 "ok": true、pybullet、1 个已解析组件和 64 位 plan digest。 expand 会显示 runtime.rate_policy: exact 等默认值，但不会修改 run.yaml。

常见错误

  • PROJECT_CONFIG_NOT_FOUND：运行仓库内文件或传 --project；不要只复制 run.yaml。
  • COMPONENT_NOT_FOUND：检查 use URI 和 Registry index。
  • RESOURCE_OUTSIDE_TRUSTED_ROOT：把资产根目录明确加入 project，不要全局关闭检查。
  • physics_hz/control_hz must be an integer：默认 exact 策略下使用整数比，例如 60/30。

下一步

继续阅读 02 — 启动应用并读取状态。