simulo.Prop

The prop authoring contract — a rigid body whose pose you can read and write.

This is the surface authoring code may rely on when it creates a prop, adds it to a scene, and moves it: the shape it was built from, its identity in the scene, its live state, its spawn pose, and the pose / velocity writes an episodic reset needs.

Real usage, from the shipped franka_lift training app. A bare shape handed to scene.add(...) is authoring data with no runtime handle; wrapping it in a Prop is what gives the task a pose it can read back and write — which is what makes an episodic manipulation task possible at all:

self.block = simulo.Prop(
    simulo.Cuboid(
        name="Block",
        size=(0.05, 0.05, 0.05),
        pose=simulo.Pose(position=[0.5, 0.0, 0.025]),
        physics=simulo.Physics.rigid(mass=0.05),
    )
)
scene.add(self.block, at="/World/Block")

Then, in reset_idx, re-randomise the block for only the environments that finished — default_pose is the spawn pose in the world frame, with each environment’s origin already applied:

count = len(env_ids)
pose = self.block.default_pose[env_ids].clone()
pose[:, 0] += torch.empty(count, device=self.device).uniform_(-0.10, 0.10)
pose[:, 1] += torch.empty(count, device=self.device).uniform_(-0.20, 0.20)
self.block.set_pose(pose, env_ids=env_ids)
self.block.set_velocity(torch.zeros(count, 6, device=self.device), env_ids=env_ids)

prop.state (pose, linear_velocity, angular_velocity) is the supported, typed way to read live state back — batched across environments, in the world frame, exactly like robot.state. Reading the block’s height out of prop.state.pose[:, 2] is how franka_lift scores a lift: a parallel gripper reports the same finger state whether it closed on the block or on empty air, so the object’s own pose is the only honest evidence that a grasp happened.

shape

Prop.shape: PrimitiveShape

The primitive shape this prop spawns, carrying its size, material, and rigid physics. The shape’s own pose is where the prop spawns.

name

Prop.name: Optional[str]

property

Prop name — taken from the shape, or set by the scene when added.

path

Prop.path: Optional[str]

property

Scene path — set by the scene when the prop is added.

state

Prop.state: PropStateProtocol

property

The grouped live prop state — the supported, typed state surface.

Always available (the accessor is the same object on every access); its members read straight through to the simulation’s state buffers and raise RuntimeError until the simulation runtime has attached the prop — read them from on_start onward.

default_pose

Prop.default_pose: TensorLike

property

The prop’s spawn pose in the world frame, (num_envs, 7).

The pose the prop was authored at, already offset by each environment’s own origin — so it is directly comparable with state.pose and directly usable as the base for a randomised reset. Index it with the environments being reset (prop.default_pose[env_ids]), perturb, and write it back with set_pose().

Raises RuntimeError until the simulation runtime has attached the prop.

set_pose()

Prop.set_pose(pose: TensorLike, env_ids: Optional[TensorLike] = ...) -> None

Write the prop’s pose directly (teleport, not control), world frame.

Args:

pose — (num_envs, 7) — or (len(env_ids), 7) when env_ids is given — as [x, y, z, qw, qx, qy, qz].
env_ids — Environment indices to write; None writes every environment. Passing the subset being reset is what makes a partial episodic reset possible: the environments that did not finish keep the pose they had.

set_velocity()

Prop.set_velocity(velocity: TensorLike, env_ids: Optional[TensorLike] = ...) -> None

Write the prop’s velocity directly (teleport, not control), world frame.

Args:

velocity — (num_envs, 6) — or (len(env_ids), 6) when env_ids is given — as [vx, vy, vz, wx, wy, wz].
env_ids — Environment indices to write; None writes every environment.

A reset that moves a prop should zero its velocity too, or the body arrives at its new pose still carrying the momentum it had at the end of the previous episode.

reset()

Prop.reset(env_ids: Optional[TensorLike] = ...) -> None

Return the prop to its spawn pose with zero velocity.

Args:

env_ids — Environment indices to reset; None resets every environment.

Declared as:

@runtime_checkable
class PropProtocol(Protocol)