1. What entities did FastSim create?
  2. What is their state at one committed simulation boundary?

The scene deliberately contains three different kinds of entity: a rigid object, a generic articulation, and a robot. A door is an articulation in exactly the same physical sense as a robot; the distinction does not change how joint state is read.

Prerequisites

Install FastSim and the Isaac Lab provider in the same Python environment. This Run uses Isaac Lab 3.0 / Isaac Sim 6.0 and requests a visible native window.

Files

  • run.yaml creates a red cube, a hinged door, and a two-joint arm.
  • main.py reads the public scene catalog and its matching live state.
  • ../../_shared/components/ contains the reusable component manifests.

Configuration, key by key

yaml
schema: fastsim/2                    # Select the FastSim vNext Run schema.
name: demo-scene-entities-and-state  # Stable name shown by Run inspection tools.
backend: isaaclab                    # Select the Isaac Lab component variants.

runtime:
  launch_profile: visible            # Open the simulator's native visible window.
  physics_hz: 60                     # Advance physics at 60 simulated steps/s.
  control_hz: 60                     # Admit control frames at 60 Hz.
  seed: 31                           # Make reset behaviour reproducible.

scenario:
  scene:
    objects:                         # Non-articulated physical objects.
      red_cube:                      # Human-friendly alias for this instance.
        use: object://fastsim/demo-cube
        pose:                        # World pose, always SI and quaternion XYZW.
          xyz_m: [0.0, -0.65, 0.5]
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]
    articulations:                   # Any jointed asset that is not a robot.
      door:
        use: articulation://fastsim/demo-door
        pose:
          xyz_m: [0.85, 0.0, 0.0]
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]
        initial_state:
          joints:
            door_hinge: 0.0          # Initial hinge angle in radians.
    robots:                          # Robot instances use the same joint model.
      arm:
        use: robot://fastsim/demo-two-joint-arm
        pose:
          xyz_m: [-0.85, 0.0, 0.0]
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]
        initial_state:
          joints:
            joint_1: 0.0
            joint_2: 0.0

use is a Registry identity, not a path. The shared Registry chooses each component's Isaac Lab resource and records the exact selection in the ExecutionPlan.

Python, line by line

  1. The module docstring states the observable result of the program.
  2. asyncio runs FastSim's asynchronous application API, math rejects non-finite state, and Path locates the Run independently of the current working directory.
  3. import fastsim uses only the package's public facade.
  4. RUN_FILE points to the adjacent run.yaml; VISIBLE_HOLD_SECONDS keeps the visible result on screen briefly.
  5. AUTHORED_ENTITY_IDS lists the three authored entities; EXPECTED_JOINT_NAMES and INITIAL_JOINT_TOLERANCE_RAD define the explicit initial-state gate without including provider-owned system entries.
  6. async def main() defines the asynchronous application flow.
  7. fastsim.app(..., planning_reads=True) opts into the scene/frame/geometry publication path. That path is disabled by default to avoid planning overhead in applications that only need control or cameras.
  8. async with owns cleanup even if a later query raises an exception.
  9. start() builds the real Isaac Lab world; pause() freezes it at a clear read boundary without destroying the world.
  10. scene.catalog() returns immutable structure: entity kinds, links, joints, frames, geometry IDs, and control resource groups.
  11. scene.state() returns live poses, twists, and joint values for one committed generation and tick.
  12. The dictionary comprehensions index immutable snapshots by stable IDs and build a stable-ID-to-authored-name joint map. They do not retain a simulator-native handle.
  13. The first loop rejects a non-finite root position, then prints each entity's kind, root position, and declared control groups.
  14. The second loop uses zip(..., strict=True) to pair joint IDs with positions, prints authored names, and requires the exact expected axes with every initial value finite and within +/-0.02 rad. Any mismatch exits non-zero.
  15. asyncio.sleep(...) leaves the paused visible scene available for inspection for three seconds while keeping the example non-interactive.
  16. The final two lines run main() only when this file is executed directly.

Acceptance gates

  • All three configured entity IDs must exist and every root position must be finite.
  • The door must publish door_hinge; the arm must publish joint_1 and joint_2.
  • Every initial joint value must be finite and within +/-0.02 rad of the authored zero state.
  • The visible Isaac Lab acceptance run on 2026-08-25 measured approximately 0, 0, and 0.0000041 rad for those three axes and exited with code 0.

Run it

From this case directory:

bash
cd demo/fundamentals/07_scene_entities_and_state
fastsim config validate run.yaml --json
python main.py

Expected output contains the canonical IDs objects.red_cube, articulations.door, and robots.arm, followed by door and arm joint values. A visible Isaac Lab window remains open briefly after the snapshots are printed.

Verification level

REAL VISIBLE ISAAC PASS. The native run satisfied every acceptance gate above, exited normally, and left no Isaac worker process behind.

Common errors

  • SERVICE_ACCESS_DENIED: keep planning_reads=True; scene publication is intentionally opt-in.
  • COMPONENT_NO_MATCHING_VARIANT: update the Isaac Lab provider and use the checked-in shared component manifests.
  • A missing visible window: confirm that the Run still contains runtime.launch_profile: visible and that a display is available.