Implementation:Haosulab ManiSkill BaseStruct

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

Overview

Concrete tool for base dataclass hierarchy that manages batched SAPIEN physics objects across parallel simulation environments.

Description

The base.py module defines the foundational dataclass hierarchy used by all ManiSkill struct types (Actor, Link, Articulation, ArticulationJoint, Drive, RenderCamera). These base classes provide the common infrastructure for managing lists of SAPIEN objects distributed across parallel sub-scenes.

BaseStruct[T] -- The root generic dataclass:

_objs: list[T] -- The managed SAPIEN objects (one per sub-scene).
_scene_idxs: torch.Tensor -- Maps each object to its sub-scene index.
scene: ManiSkillScene -- Reference to the parent scene.
Provides device, _num_objs, px properties.
Implements a stable hash based on the immutable object list.

PhysxRigidBaseComponentStruct[T] -- Extends BaseStruct for rigid body components:

_bodies: list[PhysxRigidBaseComponent] -- The physics body components.
Provides collision shape access, AABB computation.

PhysxRigidBodyComponentStruct[T] -- Extends for dynamic/kinematic bodies:

Adds _body_data_name and _body_data_index for GPU-accelerated data access.
Provides batched pose, linear_velocity, angular_velocity properties.
set_pose(), set_linear_velocity(), set_angular_velocity() methods.

PhysxRigidDynamicComponentStruct[T] -- Extends for fully dynamic bodies:

Adds mass, inertia, center-of-mass access and modification.
Enables/disables gravity per body.

PhysxJointComponentStruct[T] -- Extends BaseStruct for joint/drive components:

pose_in_child / pose_in_parent -- Joint frame poses.

The @before_gpu_init decorator is used on methods that can only be called before the GPU simulation system is initialized.

Usage

These base classes are not typically instantiated directly. They are subclassed by Actor, Link, Articulation, ArticulationJoint, Drive, and RenderCamera. Understanding the hierarchy is important for advanced users who need to extend ManiSkill's struct system.

Code Reference

Source Location

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

Signature

@dataclass
class BaseStruct(Generic[T]):
    _objs: list[T]
    _scene_idxs: torch.Tensor
    scene: ManiSkillScene

    @property
    def device(self) -> torch.device: ...
    @property
    def _num_objs(self) -> int: ...

@dataclass
class PhysxRigidBaseComponentStruct(BaseStruct[T], Generic[T]):
    _bodies: list[physx.PhysxRigidBaseComponent]

@dataclass
class PhysxRigidBodyComponentStruct(PhysxRigidBaseComponentStruct[T], Generic[T]):
    @property
    def pose(self) -> Pose: ...
    def set_pose(self, pose: Pose) -> None: ...
    @property
    def linear_velocity(self) -> torch.Tensor: ...
    @property
    def angular_velocity(self) -> torch.Tensor: ...

@dataclass
class PhysxRigidDynamicComponentStruct(PhysxRigidBodyComponentStruct[T], Generic[T]):
    @property
    def mass(self) -> torch.Tensor: ...

@dataclass
class PhysxJointComponentStruct(BaseStruct[T], Generic[T]):
    pose_in_child: Pose
    pose_in_parent: Pose

Import

from mani_skill.utils.structs.base import (
    BaseStruct,
    PhysxRigidBaseComponentStruct,
    PhysxRigidBodyComponentStruct,
    PhysxRigidDynamicComponentStruct,
    PhysxJointComponentStruct,
)

I/O Contract

Inputs

Name	Type	Required	Description
_objs	list[T]	Yes	List of SAPIEN objects to manage (one per sub-scene)
_scene_idxs	torch.Tensor	Yes	Tensor mapping objects to sub-scene indices
scene	ManiSkillScene	Yes	The parent scene reference

Outputs

Name	Type	Description
pose	Pose	Batched pose of the managed objects
linear_velocity	torch.Tensor	Linear velocities of shape (N, 3)
angular_velocity	torch.Tensor	Angular velocities of shape (N, 3)

Usage Examples

Basic Usage

# BaseStruct is not used directly; it is the parent of Actor, Link, etc.
# Access common properties through subclasses:
actor = env.scene["my_actor"]

# Properties inherited from BaseStruct
print(actor.device)        # torch.device
print(actor._num_objs)     # number of parallel objects

# Properties from PhysxRigidBodyComponentStruct
pose = actor.pose           # Pose object
vel = actor.linear_velocity # torch.Tensor (N, 3)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment