全局配置

general 块控制 FastSim 的全局行为：项目扫描（自动注册用户定义的 stereotype）、资产根路径映射（解析 root_key:// 路径）、缓存目录（远端/平台资产缓存）、日志系统（终端输出、文件记录与轮转）以及性能分析。

源码：fastsim/configs/general_cfg.py（GeneralConfig）

字段说明

校验规则：root_paths 中每个路径值必须是已存在的本地目录，否则 validate_root_paths() 在启动时抛出错误。

资产路径解析

配置文件中的 asset_path、hdf5_path、backend_root_path 等路径字段均通过 Asset.resolve_url_path() 统一解析（源码：fastsim/utils/asset.py）。支持五种格式：

root_key:// 是最推荐的用法——它将具体机器路径集中在 general.root_paths 中管理，其余配置文件只使用逻辑路径，便于在不同机器和用户间共享配置。

platform:// 协议则提供了跨团队共享资产的统一入口，由 joysim/utils/platform/ 模块处理鉴权和按需下载，详见下文。

资产平台远程资源访问（platform://）

FastSim 资产平台（默认 https://assets.fastsim.hofee.cn）是一个集中式的远端资产仓库，支持物体、机器人、场景、工作空间和材质等五类资产的版本化管理。platform:// 协议是访问平台资产的统一入口，运行时会自动鉴权、流式下载、本地缓存。

源码：joysim/utils/platform/（PlatformClient + PlatformFetcher）

URL 协议格式

platform:// 支持两种引用形式：

• <category>：资产类别，必须为 object / robot / scene / workspace / material 之一
• <asset_ref>：资产名称（如 can_016）或 UUID
• <subpath>：资产目录下的具体文件，省略则返回整个资产目录
• 路径形式下的 <cfs_relative_path> 是平台 CFS 根目录下的完整相对路径（默认 CFS 根：cfs://cfs-1205-dongjiang-bt/simstudio/assets/）

鉴权配置

通过环境变量配置鉴权信息，二选一：

方式一：直接使用 Token（推荐）

export FASTSIM_TOKEN=<your-token>

适合 CI/CD、Docker 镜像等场景。Token 可在资产平台的"个人中心"页面获取。

方式二：用户名 + 密码（自动续 Token）

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

每次启动仿真时自动登录获取 Token；Token 失效（401 响应）时会自动重新登录。

可选环境变量

环境变量的优先级高于 general.cache_dir。

YAML 中使用

要让某个实体从资产平台加载，将其 source 设为 platform、asset_path 设为 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

工作机制

1. 首次请求：调用 GET /assets/{category}/{asset_id} 拿到资产元信息（uuid / cfs_uri / size），随后通过 GET /files/tar?uri=<cfs_uri> 流式拉取整个资产目录的 zstd 压缩 tar 包，解压到本地缓存。
2. 缓存命中：之后再加载同一资产时直接读取本地缓存，0 网络请求。
3. 完整性检查：缓存目录下放置 .joysim_complete 哨兵文件标识下载完整性，.joysim_meta.json 记录元数据；中途崩溃的下载会在下次启动时重新拉取。
4. 并发安全：多个进程同时请求同一资产时，只有一个执行下载，其余进程等待完成后读取缓存，避免重复下载。

缓存目录结构

~/.joysim_cache/
└── platform/
    ├── object/
    │   └── <uuid>/
    │       ├── .joysim_complete         # 下载完成哨兵
    │       ├── .joysim_meta.json        # 元数据（asset_id / cfs_uri / mtime）
    │       ├── Aligned.usd
    │       ├── textures/
    │       └── materials/
    ├── robot/
    │   └── <uuid>/...
    ├── scene/
    └── files/                            # 路径形式 URL 的缓存
        └── <md5(folder_uri)>/...

资产形式按 UUID 索引，路径形式按文件夹 URI 的 MD5 索引。整个资产目录作为一个整体下载，因此 USD 内部的相对路径引用可以直接解析。

常见问题

配置示例

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

使用效果：

# 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

性能分析

启用 enable_profiling 后，FastSim 会记录每帧各阶段（命令执行、物理步进、后处理回调等）的耗时，并在仿真结束时输出统计报告，包括平均耗时与超过 profiling_outlier_threshold_ms 的异常帧。