一次运行是一份产品资产
- 需要启动前验证、展开与 explain
- 需要把资产和插件锁到确定资源
- 需要模型、规则、遥操作或回放共享控制边界
VNEXT / CONCEPTS & QUICKSTART
先理解一次 Run，再开始写代码。
FastSim 是面向可复现机器人仿真的配置驱动应用运行时。它将人编写的 Run 配置编译成不可变执行计划，通过 UniRoboSim 启动一个后端，并向独立安装的插件授予范围明确的服务。
vNext 是全新实现
当前版本是 0.1.0a36 Alpha。它不读取旧版 FastSim 配置，也不提供旧运行时的兼容导入。请以 schema: fastsim/2 和本文档为准。
01
何时使用 FastSim
把 FastSim 看作仿真应用的组织层，而不是新的物理引擎。它最适合需要配置化、可检查、可锁定资源、可组合控制来源和可追溯输出的运行。
只需要轻量可移植 API
- 应用自己拥有完整生命周期
- 不需要插件组合与控制仲裁
- 只希望屏蔽后端实体与传感器差异
02
从源码安装
当前文档不假定相关包已发布到 PyPI。下面使用 Python 3.11 和 PyBullet Provider 构建最轻量的开发环境。
git clone https://github.com/GitHofee/UniRoboSim.git
git clone https://github.com/GitHofee/UniRoboSim-pybullet.git
git clone https://github.com/FastSim-Benchmark/FastSim.git
python3.11 -m venv fastsim-dev
source fastsim-dev/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ./UniRoboSim
python -m pip install -e ./UniRoboSim-pybullet
python -m pip install -e './FastSim[dev]'
fastsim --version
fastsim doctor --json关于 doctor
doctor 的 backend_integration 当前会保守地显示 unverified；它不能替代一次真实的原生后端启动检查。
03
快速开始
仓库自带的最小示例从本地 Registry 解析一个红色方块。不下载机器人、不安装插件，也能完整检查配置、资源与后端生命周期。
schema: fastsim/2
name: quickstart
backend: pybullet
runtime:
launch_profile: headless
physics_hz: 60
control_hz: 30
seed: 7
scenario:
scene:
objects:
cube:
use: object://fastsim/quickstart-cube
pose:
xyz_m: [0.0, 0.0, 0.5]
quat_xyzw: [0.0, 0.0, 0.0, 1.0]1. 不启动仿真器，先检查
fastsim config validate examples/quickstart/run.yaml --json
fastsim config expand examples/quickstart/run.yaml
fastsim config explain examples/quickstart/run.yaml runtime.physics_hz2. 生成内容寻址 Lock
fastsim config lock examples/quickstart/run.yaml \
--output quickstart.lock --json
fastsim config verify-lock quickstart.lock --json3. 运行两秒
fastsim run examples/quickstart/run.yaml --duration 2 --json04
Run 配置模型
顶层字段刻意保持精简。Project 负责 Registry、可信资源根目录、缓存与插件权限上限；Run 只描述这一次应用。
schema全新配置契约，当前为 fastsim/2
name稳定且对人可读的 Run 名称
backend本次编译选择的 UniRoboSim Provider ID
runtime频率、启动模式与随机种子策略
scenario必选 scene 与插件拥有的 behavior / evaluation 数据
control默认控制对象与控制源插件优先级
plugins本次 Run 选择的已安装插件实例
overrides带来源记录的显式配置覆盖
05
平台架构
FastSim 位于应用意图和可移植仿真能力之间。CLI 是 Core 的一部分；浏览器控制台、TUI、Server 和调试器属于可选插件。
编译器将 Run 与 Project、Registry、资源摘要组合成不可变计划。
运行时拥有生命周期、服务代理与 ControlChunk 仲裁，不拥有任务语义。
UniRoboSim 提供 World、Entity、Articulation、Sensor 和 Control 契约。
Record 将运行证据写入 FSR；Viewer 与 Replay 保持明确分离。
06
插件拥有能力，Core 守住边界
pick、place、抓取位姿、Action 列表、规划器、模型推理和遥操作设备都属于插件。Core 只提供它们共同依赖的生命周期、观测、场景查询、规划读取和异步控制边界。
RULE-BASEDMODELTELEOPAGENTRECORDREPLAYTUIWEBSERVERMCP
Planning reads are opt-in
完整碰撞几何读取成本较高。只有确实需要 Scene、Frame 或规划几何 API 时，才以 planning_reads=True 构建 Application。
07
后端与 Python 版本
FastSim 支持 Python 3.11 和 3.12；实际环境必须遵循选定 Provider 的 Python 与原生依赖要求。
包版本Python说明
fastsim0.1.0a363.11 / 3.12unirobosim == 0.10.5unirobosim-isaaclab0.10.163.12Isaac Lab 3.0 / Isaac Sim 6.0unirobosim-mujoco0.9.43.12MuJoCo 3.11.0unirobosim-pybullet0.9.43.11PyBullet 3.2.708
Application API
需要自行编写完整仿真应用时，可以直接使用异步 FastSimApplication，不必先实现 Plugin。操作是异步资源：提交后显式读取状态、等待结果并释放。
import asyncio
import fastsim
async def main() -> None:
async with fastsim.app("run.yaml") as simulation:
await simulation.start()
targets = await simulation.control.targets()
operation = await simulation.control.submit_joints(
actor="droid",
group="arm",
path=[[0.0, -0.4, 0.0, -2.0, 0.0, 1.6, 0.8]],
dt=1.0 / 60.0,
timeout=10.0,
)
result = await operation.result()
await operation.release()
print(result.status)
asyncio.run(main())09
HTTP Server
可选的 fastsim-plugin-server 将同一 Application API 暴露为 fastsim-http/1。控制请求返回 202 Accepted 与 operation ID，因此 HTTP 调用保持异步。
pip install fastsim-plugin-server
fastsim-server run.yaml --host 127.0.0.1 --port 8000公网监听要求
非本机监听必须同时启用 HTTPS 与 Bearer Token 鉴权。浏览器前端不会、也不应导入仿真器 SDK。
10
Record、Viewer 与 Replay
Record 负责把被选择的运行证据写入密封 FSR。Viewer 只读已记录字节，不启动仿真、不重新施加控制；Replay 会启动一个新的仿真，并重新应用记录的控制。
11
版本与公开状态
本页对应 FastSim 0.1.0a36 与仓库当前的 fastsim/2 契约。Alpha 表示公共接口仍可能演进；任何后端、插件或数据能力是否可用，都应以安装包 Manifest、版本约束和真实运行检查为准。
0.1.0a36 / ALPHA阅读变更记录 ↗