{"id":27372,"library":"sapien","title":"SAPIEN","description":"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.","status":"active","version":"3.0.3","language":"python","source_language":"en","source_url":"https://github.com/sapien-sim/sapien","tags":["simulation","robotics","3D","physics","render"],"install":[{"cmd":"pip install sapien","lang":"bash","label":"Install from PyPI"},{"cmd":"pip install sapien>=3.0.0","lang":"bash","label":"Install with minimum version"}],"dependencies":[{"reason":"Required for array operations and math utilities","package":"numpy","optional":false}],"imports":[{"note":"Avoid star imports; use explicit imports to prevent namespace pollution.","wrong":"from sapien import *","symbol":"sapien","correct":"import sapien"},{"note":"Engine is a class under sapien, not a module.","wrong":"import sapien.Engine","symbol":"Engine","correct":"from sapien import Engine"},{"note":"Correct import as above.","wrong":"sapien.Scene","symbol":"Scene","correct":"from sapien import Scene"}],"quickstart":{"code":"import sapien\nengine = sapien.Engine()\nrenderer = sapien.VulkanRenderer()\nscene = engine.create_scene(renderer=renderer)\nscene.set_ambient_light([0.5, 0.5, 0.5])\nscene.add_ground(altitude=0)\n\n# Add a box\nbuilder = scene.create_actor_builder()\nbuilder.add_box_shape(half_size=[0.5, 0.5, 0.5])\nbuilder.add_visual_from_file('path/to/visual_mesh.obj')\nbox = builder.build(name='box')\n\n# Step simulation\nfor _ in range(100):\n    scene.step()\n    scene.update_render()\n    # Render is via viewer or offscreen; see docs","lang":"python","description":"Create a simple scene with a box and step the simulation."},"warnings":[{"fix":"Refer to the migration guide: https://sapien.ucsd.edu/docs/latest/user_guide/migration.html","message":"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`).","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Use `sapien.VulkanRenderer(offscreen_only=True)` for headless setups.","message":"The `VulkanRenderer` is the default renderer; `PhysxRenderer` is no longer supported. Offscreen rendering now requires `VulkanRenderer` with `offscreen_only=True`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Pass a list of three floats: `scene.set_ambient_light([0.5,0.5,0.5])`.","message":"`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.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Always call `builder.build(name='actor_name')` after setting up shapes and visuals.","message":"The `create_actor_builder()` method returns an `ActorBuilder` that must be built with `.build()`. Forgetting to call `build()` results in no actor added.","severity":"gotcha","affected_versions":"all"},{"fix":"Add a loop calling `scene.step()` and `scene.update_render()` each frame.","message":"Simulation requires explicit `scene.step()` calls; no automatic physics stepping. Running without stepping leads to static scenes.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"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","cause":"SAPIEN 3.0 removed non-Vulkan renderers; the pip package requires system Vulkan drivers.","error":"RuntimeError: VulkanRenderer is not available. Please install the sapien package with Vulkan support."},{"fix":"Replace `sapien.utils` with `sapien.physx` for PhysX-related utils or `sapien.render` for render. Check the migration guide.","cause":"In SAPIEN 3.0, the `sapien.utils` module was removed; functionality moved elsewhere.","error":"AttributeError: module 'sapien' has no attribute 'utils'"},{"fix":"Use `scene.set_ambient_light([0.5, 0.5, 0.5])`.","cause":"In SAPIEN 3.0 `set_ambient_light` expects a list of three floats, not separate arguments or a single float.","error":"TypeError: set_ambient_light(): incompatible function arguments"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}