Global configuration

The general block controls FastSim's global behavior: project scanning (auto-register user-defined stereotypes), asset root path mapping (resolves root_key:// paths), cache directory (remote / platform asset cache), logging system (terminal output, file logging, rotation), and profiling.

Source: fastsim/configs/general_cfg.py (GeneralConfig)

Field reference

Validation rule: Each path in root_paths must be an existing local directory; validate_root_paths() raises on startup otherwise.

Asset path resolution

Path fields in configs (asset_path, hdf5_path, backend_root_path, etc.) are resolved through Asset.resolve_url_path() (source: fastsim/utils/asset.py). Five formats are supported:

root_key:// is the most recommended pattern — it centralizes machine-specific paths in general.root_paths, leaving the rest of the config purely logical and easy to share across machines and users.

platform:// provides a unified entry point for cross-team asset sharing, with auth and on-demand download handled by joysim/utils/platform/. See the dedicated section below.

Asset platform remote access (platform://)

The FastSim asset platform (default https://assets.fastsim.hofee.cn) is a centralized remote asset repository with version-managed storage of five asset categories: objects, robots, scenes, workspaces, and materials. The platform:// protocol is the unified entry point — at runtime it handles authentication, streaming download, and local caching automatically.

Source: joysim/utils/platform/ (PlatformClient + PlatformFetcher)

URL format

platform:// supports two reference forms:

• <category>: asset category — must be one of object / robot / scene / workspace / material
• <asset_ref>: asset name (e.g. can_016) or UUID
• <subpath>: file inside the asset directory; if omitted, the whole asset folder is returned
• For path form, <cfs_relative_path> is the full path under the platform CFS root (default: cfs://cfs-1205-dongjiang-bt/simstudio/assets/)

Authentication

Configure auth via env vars (choose one):

Option 1: direct Token (recommended)

export FASTSIM_TOKEN=<your-token>

Suitable for CI/CD and Docker images. Get the token from the platform's "Profile" page.

Option 2: username + password (auto-renewing)

export JOYSIM_PLATFORM_USERNAME=<your-username>
export JOYSIM_PLATFORM_PASSWORD=<your-password>

Auto-logs in on each simulation start; on token expiry (401 response), automatically re-authenticates.

Optional environment variables

Env var takes precedence over general.cache_dir.

YAML usage

To load an entity from the asset platform, set its source to platform and asset_path to a platform:// URL:

scene:
  name: pick_and_place
  base_config:
    name: workspace
    stereotype: usd
    source: platform
    asset_path: platform://scenes/kujiale/827310_home/workspace_00.usd

  object_cfg_dict:
    can_016:
      stereotype: rigid
      source: platform
      asset_path: platform://objects/omni6DPose/can/can_016/Aligned.usd
      scale: [0.001, 0.001, 0.001]
      position: [0.0, -3.79, 0.5]

    plug_001:
      stereotype: rigid
      source: platform
      asset_path: platform://objects/omni6DPose/plug/plug_001/Aligned.usd

How it works

1. First request: calls GET /assets/{category}/{asset_id} to fetch metadata (uuid / cfs_uri / size), then streams the entire asset directory as a zstd-compressed tar via GET /files/tar?uri=<cfs_uri> and extracts it into the local cache.
2. Cache hit: subsequent loads of the same asset read from local cache — zero network requests.
3. Integrity check: a .joysim_complete sentinel file marks complete downloads, and .joysim_meta.json records metadata. Interrupted downloads are detected on next start and re-fetched.
4. Concurrency-safe: when multiple processes request the same asset, only one downloads it; others wait for completion and read from cache — no duplicate downloads.

Cache directory layout

~/.joysim_cache/
└── platform/
    ├── object/
    │   └── <uuid>/
    │       ├── .joysim_complete         # download-complete sentinel
    │       ├── .joysim_meta.json        # metadata (asset_id / cfs_uri / mtime)
    │       ├── Aligned.usd
    │       ├── textures/
    │       └── materials/
    ├── robot/
    │   └── <uuid>/...
    ├── scene/
    └── files/                            # path-form URL cache
        └── <md5(folder_uri)>/...

Asset-form URLs are indexed by UUID; path-form URLs by MD5 of the folder URI. Each asset directory is downloaded as one tar, so USD relative-path references resolve naturally inside.

Troubleshooting

Configuration example

general:
  scan_project: true
  root_paths:
    assets: /home/user/robot_assets
    datasets: /home/user/datasets
  cache_dir: /var/cache/joysim
  log_to_terminal: true
  log_terminal_level: INFO
  log_output_dir: ./logs
  enable_profiling: false

Resolution effect:

# assets://robots/ur5.usd → /home/user/robot_assets/robots/ur5.usd
# datasets://runs/run001  → /home/user/datasets/runs/run001
robot_cfg_dict:
  arm:
    asset_path: assets://robots/ur5.usd

extension:
  extension_cfg_dict:
    record:
      backend_root_path: datasets://runs/run001

Profiling

When enable_profiling is true, FastSim records per-step time consumption (command execution, physics step, post-process callbacks, etc.) and prints a summary at simulation end, including average step time and any frame exceeding profiling_outlier_threshold_ms.