sapien

library3.0.3pypypi✓ verified 85d ago

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.

ai-ml web-framework data

pip install sapien

package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · SAPIEN

sapien

ai-mlpythonv3.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sapien

✓ import sapien

✗ from sapien import *

Avoid star imports; use explicit imports to prevent namespace pollution.

Engine

✓ from sapien import Engine

✗ import sapien.Engine

Engine is a class under sapien, not a module.

Scene

✓ from sapien import Scene

✗ sapien.Scene

Correct import as above.

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

Debug

Known issues

breakingSAPIEN 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

affects: <3.0.0

breakingThe `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.

affects: >=3.0.0

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])`.

affects: >=3.0.0

gotchaThe `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.

affects: all

gotchaSimulation 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.

affects: all

Errors

Common errors & fixes

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

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

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

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.

TypeError: set_ambient_light(): incompatible function arguments

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])`.

Upgrade

Version history

3.0.3latest on PyPI · released Mar 10, 2026

Audit

Dependencies

numpyrequiredRequired for array operations and math utilities

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/sapien/ ↗

homepagehttps://sapien.ucsd.edu ↗

docshttps://sapien.ucsd.edu/docs ↗