Audience

Verification level

Configuration only. The example compiles the actual USD resource for the isaaclab variant and verifies its resolved digest. Isaac Lab is not launched, so this case does not claim native loading, rendering, collision, or articulation behavior.

Files

  • run.yaml selects one environment at the scene's singular environment slot.
  • main.py checks kind, backend variant, USD format, and instance scale.
  • Environment manifest packages the USD scene.
  • Minimal USD asset is the resolved resource.

Component manifest, line by line

yaml
schema: fastsim-component/1
id: scene://fastsim/component-demo-room  # Stable scene component identity.
version: 1.0.0                           # Immutable release.
kind: environment                        # Static environment contract.
semantics:
  category: room                         # Portable descriptive metadata.
variants:
  isaaclab:                              # Only the supported backend is declared.
    resources:
      model:
        uri: assets/minimal_room.usda    # Relative to this manifest.
        format: model/vnd.usd            # Explicit USD media type.
        role: simulation                 # Root scene representation.

This manifest intentionally has no PyBullet or MuJoCo variant. Compiling it for an undeclared backend fails clearly rather than silently feeding an incompatible file to that backend. Add another variant only when you have a tested representation for it.

For a large environment, resources may include scene geometry, materials, textures, collision data, or dependency relationships. Keep backend-independent meaning in semantics and backend-specific files under their variants.

run.yaml, line by line

yaml
schema: fastsim/2
name: environment-component
backend: isaaclab                         # Select the manifest's USD variant.

runtime:
  physics_hz: 60                          # Intended physics frequency.
  control_hz: 30                          # Intended control frequency.
  seed: 105                               # Reproducible run seed.

scenario:
  scene:
    environment:                          # One singular environment, no alias level.
      use: scene://fastsim/component-demo-room
      static: true                        # Keep collision support; do not simulate private actors.
      pose:
        xyz_m: [0.0, 0.0, 0.0]          # Environment world origin.
        quat_xyzw: [0.0, 0.0, 0.0, 1.0] # Identity orientation.
      scale: [0.1, 0.2, 0.15]           # Positive, non-uniform XYZ scale.

Unlike objects, robots, or sensors, environment is a single entity mapping, not a mapping of named aliases. Other scene entities can then be composed around it without coupling the environment component to a particular task.

static defaults to true. On composite environments this freezes physical actors that were not explicitly exposed as FastSim objects or articulations, while preserving floor, wall, table, and furniture collision. A dynamic object placed on a table is therefore still supported. Set static: false only when authored mechanisms inside the environment must remain physically active; explicitly declared robots, objects, articulations, and embedded entities are interactive in either mode.

What main.py proves

The public compiler resolves the Run from any current directory and asserts:

  • backend isaaclab selected variant isaaclab;
  • the component kind is environment;
  • resource model is explicitly model/vnd.usd;
  • the immutable environment entity refers to the exact component and preserves its non-uniform XYZ scale.

The script reads metadata only; importing fastsim.config does not boot Isaac Sim.

Run it

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

As in case 01, explain reads the compiled effective plan. The source use selector has become component.identity, component.version, and component.variant.

Expected output

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

Common errors

  • Do not add an extra alias below environment; write environment: {use: ...}.
  • COMPONENT_VARIANT_NOT_FOUND means the selected backend has no declared variant.
  • USD compilation does not prove that every USD prim has suitable physics schemas; native asset acceptance remains a separate gate.
  • Non-uniform scale is suitable for static USD geometry. A composite scene containing rigid bodies or articulations generally requires uniform scale or a pre-cooked asset.
  • Asset paths in a manifest are relative to the manifest, not the Run.
  • For composite USD scenes with embedded entities, follow the dedicated composite scene contract rather than treating every hierarchy as a flat static environment.
  • Do not use static: true as collision removal: support surfaces remain collidable.

Next

Previous: robot component · Next: sensor and light components