面向读者

验证等级

仅配置验证。 本案例为 isaaclab variant 编译真实 USD 资源，并校验解析摘要。 不会启动 Isaac Lab，因此不声称通过原生加载、渲染、碰撞或铰接行为验证。

文件说明

  • run.yaml 在场景唯一的 environment 位置选择一个环境。
  • main.py 检查 kind、后端 variant、USD 格式和实例 scale。
  • Environment manifest 封装 USD 场景。
  • 最小 USD 资产 是最终解析的资源。

逐行阅读组件 manifest

yaml
schema: fastsim-component/1
id: scene://fastsim/component-demo-room  # 稳定的场景组件 identity。
version: 1.0.0                           # 不可变发布版。
kind: environment                        # 静态环境契约。
semantics:
  category: room                         # 可移植描述性元数据。
variants:
  isaaclab:                              # 仅声明已支持的后端。
    resources:
      model:
        uri: assets/minimal_room.usda    # 相对于本 manifest。
        format: model/vnd.usd            # 显式 USD 媒体类型。
        role: simulation                 # 根场景表达。

该 manifest 故意不提供 PyBullet 或 MuJoCo variant。使用未声明后端编译时会明确失败， 而不是把不兼容文件静默交给后端。只有在对应表达已通过测试后才添加新 variant。

大型环境可包含场景几何、材质、纹理、碰撞数据或资源依赖关系。后端无关含义放到 semantics，后端专用文件放在各自 variant 中。

逐行阅读 run.yaml

yaml
schema: fastsim/2
name: environment-component
backend: isaaclab                         # 选择 manifest 的 USD variant。

runtime:
  physics_hz: 60                          # 期望物理频率。
  control_hz: 30                          # 期望控制频率。
  seed: 105                               # 可复现随机种子。

scenario:
  scene:
    environment:                          # 唯一环境，没有额外别名层。
      use: scene://fastsim/component-demo-room
      static: true                        # 保留碰撞支撑，不求解环境私有动态实体。
      pose:
        xyz_m: [0.0, 0.0, 0.0]          # 环境世界原点。
        quat_xyzw: [0.0, 0.0, 0.0, 1.0] # 单位方向。
      scale: [0.1, 0.2, 0.15]           # 正数、非等比 XYZ 缩放。

与 objects、robots 或 sensors 不同，environment 是单个实体映射，而不是具名 别名映射。其他实体围绕它组合，同时环境组件不与某个特定任务耦合。

static 默认是 true。对于 composite Environment，它会冻结没有显式暴露为 FastSim object/articulation 的物理实体，但仍保留地面、墙体、桌面和家具碰撞。因此放在桌上的 动态物体仍会被支撑。只有当 Environment 资产内部 authored 机构必须保持动态时，才设置 static: false；显式声明的 robot、object、articulation 和 embedded entity 在两种模式下 都保持可交互。

main.py 验证什么

公开编译器从任意当前目录解析 Run，并断言：

  • isaaclab 后端选择 isaaclab variant；
  • 组件 kind 为 environment；
  • model 资源明确为 model/vnd.usd；
  • 不可变环境实体引用精确组件，并保留非等比 XYZ scale。

脚本只读取元数据；导入 fastsim.config 不会启动 Isaac Sim。

运行

bash
cd demo/components/05_environment_component
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.environment.component.identity
fastsim config lock run.yaml --output run.lock.yaml
fastsim config verify-lock run.lock.yaml --json
python main.py

与案例 01 相同，explain 读取编译后的有效 Plan。源配置中的 use 选择器已经变为 component.identity、component.version 和 component.variant。

预期输出

text
Entity: environment
Component: scene://fastsim/component-demo-room@1.0.0
Backend variant: isaaclab
Scene resource: model/vnd.usd
Resolved file: minimal_room.usda

常见错误

  • 不要在 environment 下增加一层别名，直接写 environment: {use: ...}。
  • COMPONENT_VARIANT_NOT_FOUND 表示所选后端没有声明 variant。
  • USD 编译成功不代表每个 USD Prim 都具有正确物理 schema；仍需独立原生资产验收。
  • 非等比 scale 适合静态 USD 几何；若复合场景含刚体或铰接体，通常应使用等比 scale， 或先把资产烹制为目标尺寸。
  • manifest 中的资产路径相对于 manifest，而非 Run。
  • 含嵌入实体的复合 USD 应遵循专用 composite scene 契约，而不是把层级一律看作 扁平静态环境。
  • static: true 不代表删除碰撞，支撑面仍必须参与碰撞。

下一步

上一个：Robot 组件 · 下一个：Sensor 与 Light 组件