# Genesis 物理引擎：Hello, Genesis World 第一个仿真场景

> 原文链接：https://robotics.hellobike.com/tutorials/genesis-sim-quickstart
> 频道：tutorials | 更新日期：2026-10-22 | 标签：Genesis World, 物理仿真, Franka, MJCF, 机器人仿真
> 核心摘要：本教程整理 Genesis World 官方 Hello 示例，完成一个最小仿真程序：初始化后创建场景，加入地面与 Franka 机械臂，构建仿真并循环步进，让机器人在重力下运动。

# Genesis 物理引擎：Hello, Genesis World 第一个仿真场景

> 本文依据以下官方文档整理：[genesis-world.readthedocs.io/en/latest/user_guide/getting_st](https://genesis-world.readthedocs.io/en/latest/user_guide/getting_started/hello_genesis.html)。命令与版本以文档当前版本为准。

## 前置条件

- Genesis World 程序可使用 import genesis as gs
- gs.cpu runs anywhere
- GPU-accelerated parallel simulation 可使用 gs.cuda、gs.amdgpu、gs.metal，或用 gs.gpu 自动选择
- 相对路径会在 working directory 和 bundled asset directory（genesis/assets）中解析

## 1. 1. 准备最小完整脚本

官方完整脚本位于 examples/tutorials/hello_genesis.py。它包含所有 Genesis World 仿真的通用流程：initialize、create a scene、add entities、build、step。

```python
import genesis as gs

gs.init(backend=gs.cpu)

scene = gs.Scene()

plane = scene.add_entity(gs.morphs.Plane())
franka = scene.add_entity(
    gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"),
)

scene.build()
for i in range(1000):
    scene.step()

```

## 2. 2. 初始化 Genesis World

在触碰 API 其他部分前，必须先运行 gs.init() 一次。最重要的参数是 compute backend；这里使用可在任意环境运行的 CPU 后端。

```python
gs.init(backend=gs.cpu)

```

## 3. 3. 创建仿真场景

所有 object、robot、camera、light 都存在于 scene 中。scene 拥有 simulator 和 visualizer。默认 scene 是 headless；如需交互窗口，可按文档传入 show_viewer=True 和 options。

```python
scene = gs.Scene()

```

## 4. 4. 可选：配置时间步、重力与相机

如果需要打开 viewer 并设置物理与相机参数，可使用 SimOptions 和 ViewerOptions。dt 是仿真时间步，gravity 沿 -Z 向下，相机参数设置初始视角。

```python
scene = gs.Scene(
    sim_options=gs.options.SimOptions(dt=0.01, gravity=(0, 0, -10.0)),
    viewer_options=gs.options.ViewerOptions(
        camera_pos=(3.5, 0.0, 2.5),
        camera_lookat=(0.0, 0.0, 0.5),
        camera_fov=40,
    ),
    show_viewer=True,
)

```

## 5. 5. 添加地面与 Franka 机械臂

objects 和 robots 都是 entities。add_entity 的第一个参数是 morph，用于描述几何和初始位姿；这里加入 Plane，并从 MJCF 文件加载 Franka。

```python
plane = scene.add_entity(gs.morphs.Plane())
franka = scene.add_entity(
    gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"),
)

```

## 6. 6. 构建并步进仿真

scene.build() 是必需的显式步骤，会分配 device memory、创建 simulation data fields，并触发 just-in-time compilation。随后每次 scene.step() 都让仿真前进一个 dt。

```python
scene.build()
for i in range(1000):
    scene.step()

```

## 验证是否跑通

脚本完成 scene.build() 后进入 for i in range(1000) 循环，每次 scene.step() 推进一个 dt；该示例会加载 ground plane 上方的 Franka arm，并让它在 gravity 下下落。若使用 show_viewer=True，viewer window 会在 scene built 后打开。

## 文档里点名的注意事项

- gs.init() must run once before you touch any other part of the API.
- Genesis World uses 32-bit floats by default. Pass precision="64" when you need double precision.
- With performance_mode=True, Genesis World bakes static tensor shapes into its compiled kernels for roughly 30% faster simulation, at the cost of recompiling whenever the scene changes.
- File paths may be absolute or relative. Genesis World resolves a relative path against your working directory and against the bundled asset directory (genesis/assets).
- An MJCF file specifies the joint connecting the robot’s base to the world; a URDF does not. A URDF base is therefore free unless you pass fixed=True. The same applies to gs.morphs.Mesh.
- The first build with a new scene configuration compiles kernels on the fly, which is slow. Genesis World caches compiled kernels as long as the first run exits normally or via Ctrl-C, not Ctrl-\.

## 原始参考来源 (Sources)

- [genesis-world.readthedocs.io/en/latest/user_guide/getting_started/hello_genesis.html](https://genesis-world.readthedocs.io/en/latest/user_guide/getting_started/hello_genesis.html)