一、简介

Genesis World 是一个面向机器人与具身智能的通用物理仿真平台。可进行 GPU 物理仿真、相机渲染和仿真数据生成。

核心能力：

• 多物理求解器：刚体、MPM、PBD（布料/弹性体）、FEM、SPH，并支持相互耦合
• 大规模并行：单卡可同时仿真上万个环境
• 无头 GPU 渲染：基于 EGL 离屏输出 RGB / 深度 / 分割图与 mp4 视频，无需桌面或 RDP
• 开箱即用：预置 Franka 抓取数据生成示例、v1.4.5 官方示例全集和一键回归脚本

典型使用场景：

• 批量生成机器人操作数据（关节状态、动作、相机图像），用于模仿学习或 VLA 模型训练
• 大规模并行强化学习训练
• 软体、布料、流体等可变形物体的交互仿真

二、快速开始

步骤 1：环境准备与开发机创建

推荐硬件配置

1.1 创建开发机

登录百舸控制台，进入 开发机 → 【创建开发机】。

基本信息：

访问配置 & 高级配置：

• 保持默认即可

点击【确定】，等待创建完成。

1.2 登录开发机

在开发机列表中找到刚创建的实例，状态变为「运行中」后点击【登录】，进入终端。默认工作目录为 /root/workspace。

步骤 2：激活环境

每打开一个新终端，执行一次：

1# 1. 激活 Genesis 运行环境（Python 虚拟环境 + 无头 EGL 渲染配置）
2source /opt/genesis/env.sh
3
4# 2. 进入交付目录
5cd /root/workspace/genesis

注意：/opt/genesis 下的 Python 环境路径是写死的，请勿移动或重命名该目录。

步骤 3：运行抓取数据生成示例

该示例在 GPU 上仿真 Franka 机械臂抓起方块，同时用相机录制视频，并逐步记录关节状态、动作和图像。

1python gs_smoke.py

示例（自定义输出目录、分辨率与帧率），将上述命令替换为：

1python gs_smoke.py --out ./out/run01 --res 1280 720 --fps 50

预期运行时间：约 15 秒。如果内核编译缓存被删除，首次运行需要额外约 2 分钟重新编译，之后会恢复正常。

运行效果

终端最后一行打印 SMOKE_RESULT {...}，其中 "lifted": true 表示方块已被成功抬起。产出保存在 out/smoke/：

读取数据示例：

1import numpy as np
2d = np.load("out/smoke/episode.npz")
3print({k: d[k].shape for k in d.files})  # qpos: (410, 9)，rgb: (103, 480, 640, 3) ……

步骤 4：运行官方示例

examples/ 目录是 Genesis World v1.4.5 的官方示例原版，未做任何改动。部分官方示例写死了打开可视化窗口（show_viewer=True），开发机没有显示器，需要先开启 pyglet 的无头开关，窗口会改为在 GPU 上离屏创建。

1# 1. 激活环境（新终端需执行）
2source /opt/genesis/env.sh
3
4# 2. 开启无头模式（无显示器时必加，否则会报 No display detected）
5export PYGLET_HEADLESS=1
6
7# 3. 进入官方示例目录（示例产出会写到 examples/out/）
8cd /root/workspace/genesis/examples
9
10# 4. 运行官方快速开始示例
11python tutorials/hello_genesis.py

示例（GPU 运行 Franka 并录制视频），将上述 #4 替换为：

1python rigid/single_franka_envs.py -g -r

注意：带 -g/--gpu 参数的示例默认走 CPU，请务必加上 -g。

运行效果

终端会持续打印仿真帧率，如 Running at 795.57 FPS，示例结束后自动退出。录像类示例的视频保存在 examples/out/ 下。

提示：开启可视化窗口的示例会按实时速率运行（dt=0.01 时约 100 FPS），这是正常现象，不是性能问题。

三、进阶功能

3.1 并行环境批量生成数据

构建场景时指定环境数量，即可在一张 GPU 上同时仿真多个环境，所有状态张量的第一维为环境编号：

1source /opt/genesis/env.sh
2mkdir -p /root/workspace/genesis/out && cd /root/workspace/genesis
3
4cat > parallel_demo.py <<'EOF'
5import time
6
7import genesis as gs
8
9gs.init(backend=gs.gpu, logging_level="warning")
10scene = gs.Scene(show_viewer=False)
11scene.add_entity(gs.morphs.Plane())
12franka = scene.add_entity(gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"))
13scene.build(n_envs=256)  # 256 个并行环境
14
15t0 = time.time()
16for _ in range(1000):
17    scene.step()
18dt = time.time() - t0
19print("qpos 形状:", tuple(franka.get_qpos().shape))  # (256, 9)
20print(f"吞吐: {256 * 1000 / dt:,.0f} env-step/s")
21EOF
22
23python parallel_demo.py

建议：可以先用 speed_benchmark/franka.py 测出您机器上的吞吐，再确定环境数量。

3.2 相机渲染与录像

默认无界面运行，通过相机出图和录像：

1source /opt/genesis/env.sh
2mkdir -p /root/workspace/genesis/out && cd /root/workspace/genesis
3
4cat > camera_demo.py <<'EOF'
5import genesis as gs
6
7gs.init(backend=gs.gpu, logging_level="warning")
8scene = gs.Scene(sim_options=gs.options.SimOptions(dt=0.01), show_viewer=False)
9scene.add_entity(gs.morphs.Plane())
10scene.add_entity(gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"))
11cam = scene.add_camera(res=(640, 480), pos=(2.0, -1.2, 1.3), lookat=(0.5, 0.0, 0.2), fov=40)
12scene.build()  # 相机必须在 build 之前添加
13
14cam.start_recording(save_to_filename="out/demo.mp4", fps=25)
15for i in range(300):
16    scene.step()
17    if i % 4 == 0:  # dt=0.01、fps=25 → 每 4 步出一帧
18        rgb, depth, seg, normal = cam.render(rgb=True, depth=True)
19cam.stop_recording()
20print("rgb:", rgb.shape, "depth:", depth.shape)  # (480, 640, 3) (480, 640)
21EOF
22
23python camera_demo.py

注意：v1.4.5 中视频文件名和帧率要传给 start_recording，stop_recording() 不带参数。帧率需满足 1/(fps×dt) 为整数，dt=0.01 时可选 10 / 20 / 25 / 50 / 100，其他值会被自动调整。

四、关键参数说明

抓取数据生成示例参数（gs_smoke.py）

环境变量

官方示例常用参数

五、常用示例列表

以下命令均在 /root/workspace/genesis/examples 目录下运行，需先执行 source /opt/genesis/env.sh 和 export PYGLET_HEADLESS=1。 入门教程：

刚体：

可变形体与耦合：

传感器与性能：

六、常见问题（FAQ）

Q1：运行报错 GenesisException: No display detected，怎么办？

示例写死了打开可视化窗口，而开发机没有显示器。执行 export PYGLET_HEADLESS=1 后重新运行即可，无需修改示例源码。

Q2：部分 tutorials 示例（如 mpm.py、pbd_cloth.py、sph_liquid.py）一直跑不完？

这几个官方示例在源码中写死了 CPU 后端，CPU 上不到 2 FPS。请改用同类求解器、支持 -g 参数的示例，如 coupling/rigid_mpm_attachment.py -g、coupling/cloth_on_rigid.py -g。

Q3：开启可视化窗口的示例只有约 100 FPS，是性能问题吗？

不是。打开窗口时 Genesis 按实时速率运行（dt=0.01 即每秒 100 步）。需要全速运行时，请在脚本中设置 show_viewer=False。

Q4：首次运行很慢，卡在编译阶段？

Genesis 首次运行会编译 GPU 内核，约 2 分钟。镜像已预置编译缓存（/opt/genesis/cache），正常情况下约 15 秒即可启动。如果删除了该目录，首次运行会重新编译，之后恢复正常。

Q5：录像时报错 TypeError: Camera.stop_recording() got an unexpected keyword argument？

v1.4.5 的录像接口有变化：文件名和帧率需传给 cam.start_recording(save_to_filename=..., fps=...)，cam.stop_recording() 不带参数。网上部分旧教程的写法已不适用。

Q6：可以安装其他 Python 包吗？

可以。执行 uv pip install -p /opt/genesis/venv/bin/python <包名>。请勿升级 torch、genesis-world 等核心依赖，完整版本清单见 /root/workspace/genesis/requirements.lock。

Q7：目录里都有什么？