Configuration

FastSim supports three config formats: YAML, JSON, and .sim (a custom DSL). All three are semantically equivalent and parsed by ConfigManager based on file extension.

Config Blocks

Block	Top-level Key	Responsibility
Global	`general`	Project scanning, asset root paths, logging, profiling
Simulation	`simulation`	Backend selection, timestep, physics parameters
Scene	`scene`	Entity declarations: robots, objects, sensors, lights
Task	`task`	Action sequences and goal conditions
Extension	`extension`	Recording, teleoperation, benchmark, pipeline, snapshots, and more

Config Formats

Format	Extension	Notes
YAML	`.yaml` / `.yml`	Standard format
JSON	`.json`	Suitable for programmatic generation
`.sim`	`.sim`	FastSim DSL — concise syntax with variables, templates, and file references

.sim Config Format

.sim is a domain-specific language designed for robot simulation configs. It parses into the exact same Python dict structure as YAML, but with cleaner syntax.

Basic Syntax

Indentation: 4 spaces per level
Comments: # for inline comments
Assignment: key = value
Nested blocks: A line without = starts a child block; indent 4 more spaces
Value types: auto-detected — true/false, null/none, numbers, [...] lists, {...} JSON, "quoted strings", bare strings

Top-level Sections

text

general
    ...

simulation <stereotype>
    ...

scene <name>
    ...

task <name>
    ...

extension
    ...

Entity Declarations

Inside scene, task, and extension, entities use a declarative syntax:

text

scene my_scene
    robot <stereotype> <name>       # equivalent to robot_cfg_dict.<name>.stereotype
    object <stereotype> <name>
    sensor <stereotype> <name>
    light <stereotype> <name>
    base <stereotype> <name>

task my_task
    action <stereotype> <name>
    goal <stereotype> <name>

extension
    data_collect
        observer <stereotype> <name>

Variables

text

let base_path = /home/user/assets
let steps = $(30 * 2)              # arithmetic expression

simulation isaaclab
    initialize_steps = $steps

File References

text

let grasp_pose = file "poses/grasp.json"

task pick
    action pick pick_cube
        pose
            data = $grasp_pose

Also works inline: data = file "poses/grasp.json". Supports .json and .yaml files.

Templates

text

template default_camera
    width = 1280
    height = 720
    data_types = [rgb, depth]

scene my_scene
    sensor camera hand_cam
        use default_camera
        focal_length = 2.8

Inheritance

text

from "./base_config.yaml"

scene
    robot_cfg_dict
        arm
            position = [0.5, 0.0, 0.0]

Editor Support

Editor	Install
VS Code	`code --install-extension editors/vscode-sim/joysim-sim-0.1.0.vsix`
Vim / Neovim	`set runtimepath+=/path/to/fastsim/editors/vim`
JetBrains	Settings > Editor > TextMate Bundles > add `editors/vscode-sim`

Full Example

text

from "../../demo_root_paths.yaml"

simulation isaaclab
    launch_config
        device = cuda
        enable_cameras = true
        headless = false

scene pick_and_place
    base usd workspace
        source = local
        asset_path = asset://scenes/workspace.usd

    robot modular_robot Franka
        asset_path = asset://Franka/franka_robotiq.usd
        source = local
        arm_modules
            main_arm
                arm_actuator_name = franka_arm
                ee_link_name = gripper_center
                ee_type = gripper
                ee_actuator_name = gripper

    object rigid red_cube
        source = local
        asset_path = asset://objects/cube_red.usd
        position = [0.4, 0.0, 0.5]

    sensor camera wrist_cam
        width = 640
        height = 480
        data_types = [rgb, depth]
        attach_to
            target_name = Franka

task pick_and_place
    action pick pick_cube
        robot_name = Franka
        arm_name = main_arm
        target
            name = red_cube
    goal on_top cube_check
        object_A_name = red_cube
        object_B_name = tray

extension
    task_executor
        enable = true
    data_collect
        enable = true
        observer robot_observer Franka
            observe_joint_positions = true
            observe_ee_pose = true

Config Inheritance (FROM keyword)

FastSim supports config inheritance via the FROM keyword (YAML/JSON) or from "path" (.sim) — build on a base config with incremental overrides:

yaml

# override_config.yaml
FROM: ./base_config.yaml

scene:
  name: my_override_scene
  object_cfg_dict:
    cube:
      position: [0.5, 0.0, 0.1]

Rules: child fields deep-merge over base; lists are replaced (not appended); multi-level inheritance and circular detection are supported.

Loading and Validation

ConfigManager in FastSim.__init__() performs:

Read: Load config from file (auto-selects YAML / JSON / .sim parser by extension)
Resolve inheritance: If FROM (YAML/JSON) or from "path" (.sim) exists, recursively load and deep-merge
Validate: Each block maps to a *Config dataclass with type and constraint checks
Project scan: If general.scan_project: true, scan user code for custom stereotypes

bash

fastsim validate_configuration --config <config_file>
fastsim show_config --config <config_file>
fastsim diff_config <config_a> <config_b>
fastsim show-registry
fastsim inspect_scene --config <config_file>
fastsim inspect_task --config <config_file>
fastsim inspect_extension --config <config_file>