Scene configuration

The scene block declaratively describes what makes up the simulation world — you list which entities exist, their types and parameters, and SceneManager handles instantiation and injection into the simulator at runtime.

Source: fastsim/configs/scene_cfg.py (SceneConfig)

Top-level structure

Field	Type	Description
`name`	`str`	Scene name
`position`	`list[3]`	Scene base position `[x, y, z]`
`rotation`	`list[4]`	Scene base rotation, quaternion `[w, x, y, z]` (must be normalized)
`base_config`	`BaseConfig`	Ground/environment config (optional)
`object_cfg_dict`	`dict[str, ObjectConfig]`	Object dict, key is the instance name
`robot_cfg_dict`	`dict[str, RobotConfig]`	Robot dict
`sensor_cfg_dict`	`dict[str, SensorConfig]`	Sensor dict
`light_cfg_dict`	`dict[str, LightConfig]`	Light dict

Except for base_config, the other four are dicts whose keys are the unique names of entities. Use this name to access the entity at runtime (e.g. SceneManager.get_robot("arm")).

Stereotype mapping

Each entity uses its stereotype field to bind to a concrete config + runtime model class (see fastsim/annotations/stereotype.py):

Entity type	Common stereotypes
Base	`ground_plane` / `usd` / `mesh` / `empty`
Object	`rigid` / `articulated` / `soft`
Robot	`general_robot` / `modular_robot`
Sensor	`camera`
Light	`general_light`

Entity configuration details

Base — ground / environment

Each scene has at most one Base. Defines the physical ground or loads a complex environment.

Stereotype	Key fields	Notes
`ground_plane`	`ground_plane_size`	Infinite extending plane base
`usd`	`asset_path`	Load environment from a USD file (room, factory, etc.)
`mesh`	`asset_path`, `enable_collision`	Static mesh (OBJ / STL / GLB / FBX)
`empty`	—	No ground; suitable for fully custom physics scenes

Object — scene objects

Stereotype	Key fields	Notes
`rigid`	`mass`, `density`, `static_friction`, `dynamic_friction`, `restitution`, `asset_path`	Rigid body; supports primitive shapes via `source: primitive`
`articulated`	`asset_path`	Articulated body
`soft`	`soft_body_type`, `youngs_modulus`, `poissons_ratio`	Soft / deformable body (cloth, volumetric, inflatable)

Robot

Common fields for all robot stereotypes:

Field	Notes
`asset_path`	Robot USD asset path
`ee_link_name`	End-effector link name
`ik_joint_names`	Subset of joints used in IK (default: all joints)
`use_planner`	Whether to attach a motion planner (CuRobo / OMPL)
`planner_cfg`	Planner config

modular_robot extra fields: base_module, arm_modules (per-arm config), extra_modules — see Library API → ModularRobot for details.

Sensor

Field	Description
`data_types`	Capture types, e.g. `[rgb, depth, semantic_segmentation]`
`width` / `height`	Image resolution
`clip_range`	Depth clip range `[near, far]` (meters)
`attach_to`	Mount on a target entity (robot or link name)
`look_at`	Aim camera at a target point or entity
`convention`	Coordinate convention: `world` / `opengl` / `ros`

Light

Field	Description
`light_type`	`distant` (parallel) / `sphere` (point) / `disk` (area)
`intensity`	Light intensity
`color`	Color `[r, g, b]`, range 0–1
`temperature`	Color temperature (K), mutually exclusive with `color`

Configuration example

yaml

scene:
  name: pick_and_place_scene
  position: [0.0, 0.0, 0.0]
  rotation: [1.0, 0.0, 0.0, 0.0]

  base_config:
    stereotype: ground_plane
    name: base
    position: [0.0, 0.0, 0.0]
    rotation: [1.0, 0.0, 0.0, 0.0]
    ground_plane_size: [10.0, 10.0]

  robot_cfg_dict:
    arm:
      stereotype: modular_robot
      asset_path: assets://robots/franka_with_gripper.usd
      use_planner: true
      arm_modules:
        main_arm:
          arm_actuator_name: arm
          ee_link_name: tool0
          ee_type: gripper
          ee_actuator_name: gripper

  object_cfg_dict:
    cube:
      stereotype: rigid
      asset_path: assets://objects/cube_red.usd
      mass: 0.2
      static_friction: 0.8
      dynamic_friction: 0.8

  sensor_cfg_dict:
    wrist_cam:
      stereotype: camera
      width: 640
      height: 480
      data_types: [rgb, depth]
      attach_to:
        target_name: arm
        is_articulation_part: true
        articulation_part_name: panda_link8
      convention: ros

  light_cfg_dict:
    main_light:
      stereotype: general_light
      light_type: distant
      intensity: 3000
      color: [1.0, 1.0, 1.0]

Asset paths

asset_path in entity configs uses the root_key:// protocol resolved by general.root_paths. Also supports platform:// for FastSim asset platform downloads. See Global config → Asset paths.