SAPIEN

3.0.3 verified Mon Apr 27 auth: no python

SAPIEN is a SimulAted Parted-based Interactive ENvironment for physically realistic simulation of articulated rigid-body systems. It is designed for embodied AI and robotics research, providing high-fidelity rendering (including ray tracing) and efficient simulation. Current version is 3.0.3, with active development and monthly releases.

pip install sapien

Common errors

error RuntimeError: VulkanRenderer is not available. Please install the sapien package with Vulkan support. ↓

cause SAPIEN 3.0 removed non-Vulkan renderers; the pip package requires system Vulkan drivers.

fix

Install Vulkan drivers (e.g., sudo apt install libvulkan1 mesa-vulkan-drivers on Ubuntu) or use sapien.HeadlessRenderer (if available via sapien.wxPython? - not recommended). Check https://sapien.ucsd.edu/docs/latest/user_guide/installation.html

error AttributeError: module 'sapien' has no attribute 'utils' ↓

cause In SAPIEN 3.0, the `sapien.utils` module was removed; functionality moved elsewhere.

fix

Replace sapien.utils with sapien.physx for PhysX-related utils or sapien.render for render. Check the migration guide.

error TypeError: set_ambient_light(): incompatible function arguments ↓

cause In SAPIEN 3.0 `set_ambient_light` expects a list of three floats, not separate arguments or a single float.

fix

Use scene.set_ambient_light([0.5, 0.5, 0.5]).

Warnings

breaking SAPIEN 3.0 has breaking API changes compared to 2.x. Key changes include: removed `sapien.utils`, updated renderer API, renamed many classes (e.g., `RenderBodyComponent` → `RenderComponent`). ↓

fix Refer to the migration guide: https://sapien.ucsd.edu/docs/latest/user_guide/migration.html

breaking The `VulkanRenderer` is the default renderer; `PhysxRenderer` is no longer supported. Offscreen rendering now requires `VulkanRenderer` with `offscreen_only=True`. ↓

fix Use `sapien.VulkanRenderer(offscreen_only=True)` for headless setups.

deprecated `set_ambient_light` is deprecated in favor of `scene.set_ambient_light([r,g,b])` with a list; the old scalar argument no longer works. ↓

fix Pass a list of three floats: `scene.set_ambient_light([0.5,0.5,0.5])`.

gotcha The `create_actor_builder()` method returns an `ActorBuilder` that must be built with `.build()`. Forgetting to call `build()` results in no actor added. ↓

fix Always call `builder.build(name='actor_name')` after setting up shapes and visuals.

gotcha Simulation requires explicit `scene.step()` calls; no automatic physics stepping. Running without stepping leads to static scenes. ↓

fix Add a loop calling `scene.step()` and `scene.update_render()` each frame.

Install

pip install sapien>=3.0.0

Imports

sapien
wrong
```
from sapien import *
```
correct
```
import sapien
```
Avoid star imports; use explicit imports to prevent namespace pollution.
Engine
wrong
```
import sapien.Engine
```
correct
```
from sapien import Engine
```
Engine is a class under sapien, not a module.
Scene
wrong
```
sapien.Scene
```
correct
```
from sapien import Scene
```
Correct import as above.

Quickstart

Create a simple scene with a box and step the simulation.

import sapien
engine = sapien.Engine()
renderer = sapien.VulkanRenderer()
scene = engine.create_scene(renderer=renderer)
scene.set_ambient_light([0.5, 0.5, 0.5])
scene.add_ground(altitude=0)

# Add a box
builder = scene.create_actor_builder()
builder.add_box_shape(half_size=[0.5, 0.5, 0.5])
builder.add_visual_from_file('path/to/visual_mesh.obj')
box = builder.build(name='box')

# Step simulation
for _ in range(100):
    scene.step()
    scene.update_render()
    # Render is via viewer or offscreen; see docs