Implementation:Haosulab ManiSkill Actor

Knowledge Sources	Haosulab_ManiSkill
Domains	Robotics, Simulation, Physics
Last Updated	2026-02-15 08:00 GMT

Overview

Concrete tool for managing batched rigid-body actors (sapien.Entity) across parallel simulation environments.

Description

The Actor dataclass is a wrapper around sapien.Entity objects with additional properties inherited from PhysxRigidDynamicComponentStruct. It provides a unified interface for querying and setting physics properties of actors across both CPU and GPU simulation backends.

Key features:

Batched pose access: Query and set poses for actors across all parallel environments simultaneously.
Velocity access: Get linear and angular velocities on both CPU and GPU.
Body type tracking: Tracks whether the actor is "kinematic", "static", or "dynamic" via px_body_type.
Initial pose: Stores the initial pose as defined by the ActorBuilder, useful for environment resets.
Merge support: Multiple actors can be merged into a single Actor struct via Actor.merge(), creating a view over multiple actors with padded data.
Collision mesh access: Provides get_collision_meshes() to retrieve trimesh objects for collision geometry.
Visibility control: set_visible() and hide_visual() control rendering visibility.

The class factory method create_from_entities() constructs an Actor from a list of sapien.Entity objects, automatically detecting body type and setting up internal data structures.

Usage

Actor objects are typically created by the environment's scene builder (via ActorBuilder.build()) and accessed through env.scene. They are the primary interface for interacting with rigid bodies in ManiSkill tasks.

Code Reference

Source Location

Repository: Haosulab_ManiSkill
File: mani_skill/utils/structs/actor.py

Signature

@dataclass
class Actor(PhysxRigidDynamicComponentStruct[sapien.Entity]):
    px_body_type: Literal["kinematic", "static", "dynamic"] = None
    hidden: bool = False
    initial_pose: Pose = None
    name: str = None
    merged: bool = False

    @classmethod
    def create_from_entities(
        cls,
        entities: list[sapien.Entity],
        scene: ManiSkillScene,
        scene_idxs: torch.Tensor,
        shared_name: Optional[str] = None,
    ) -> "Actor": ...

    @staticmethod
    def merge(actors: list["Actor"], name: str = None) -> "Actor": ...

    def set_pose(self, pose: Pose) -> None: ...
    def get_collision_meshes(self) -> list[trimesh.Trimesh]: ...

Import

from mani_skill.utils.structs.actor import Actor

I/O Contract

Inputs

Name	Type	Required	Description
entities	list[sapien.Entity]	Yes	The SAPIEN entity objects to wrap (one per parallel env)
scene	ManiSkillScene	Yes	The scene managing sub-scenes
scene_idxs	torch.Tensor	Yes	Indices mapping entities to their sub-scenes
shared_name	str	No	Name for the actor (auto-derived if not provided)

Outputs

Name	Type	Description
Actor	Actor	A batched actor struct managing entities across parallel envs
pose	Pose	Batched pose of shape (N, 7)

Usage Examples

Basic Usage

# Actors are typically accessed from the scene, not created directly
actor = env.scene["target_cube"]

# Get pose across all parallel environments
pose = actor.pose  # Pose object with .p (N, 3) and .q (N, 4)

# Set a new pose
from mani_skill.utils.structs.pose import Pose
new_pose = Pose.create_from_pq(p=torch.zeros(N, 3), q=torch.tensor([[1, 0, 0, 0]]).expand(N, -1))
actor.set_pose(new_pose)

# Merge multiple actors for batch operations
merged = Actor.merge([actor1, actor2], name="merged_actors")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment