Authoring

Start with scene & entities: every build(scene) gets a Scene, adds a Robot and any Entity / AssetEntity props to it, each placed with a Pose (or grouped under a Transform). Add world & terrain and lights once per scene, not per environment — Terrain.plane(...) for a flat floor, Terrain.rough(...) for locomotion, World.usd(...) to load a prebuilt scene instead. The five primitives (Cuboid, Sphere, Cylinder, Cone, and their shared base PrimitiveShape) build simple props; materials and physics control how they look and behave; markers are non-physical visualization you move every step, for tracking a target or waypoint. Sensors (Camera, IMU, ContactSensor, …) read the simulation back; actuators & controllers command a robot’s joints beyond its own low-level set_joint_*_target setters.

Scene & entities

Every Task and Scenario starts with build(self, scene: simulo.Scene). A Scene is what exists, not what happens — you write it once, however many environments you run. Entity is the base for anything you add that isn’t a robot: a primitive prop, a debug marker, or a file loaded from disk (AssetEntity). See Scene, Robot & World for the full picture, including per_environment and how a Scene spawns num_envs live environments.

• simulo.Scene — The scene authoring contract — add robots, terrain, lights, and entities at logical paths.
• simulo.Entity — Base scene object — a name, a pose, and optional material/physics.
• simulo.AssetEntity — An Entity loaded from a USD/URDF asset — what Entity.from_asset(...) returns.
• simulo.Robot — The robot authoring contract — configuration, joint/body queries, commands, state, reset.
• simulo.Prop — A movable scene object whose pose you can read and write — wrap a primitive shape in one when a task needs to know where the object is, or to put it somewhere.

Placement

Pose is position + orientation — every Entity, Robot, Terrain, and World takes one. Transform is a coordinate frame you can add entities to and then place in the scene as a group.

• simulo.Pose — 6-DOF pose — position (xyz) and orientation (quat_wxyz, w-first quaternion).
• simulo.Transform — A named coordinate frame — group entities under it, then place the group in the scene.

World & terrain

Terrain is ground you generate. World is a place you bring. Terrain.plane(...) and Terrain.rough(...) are the common cases; World.usd(...) loads a prebuilt USD scene — a warehouse, a factory floor — as is. See Scene, Robot & World for the full comparison.

• simulo.World — World factory — World.usd(...) loads a prebuilt USD scene as-is.
• simulo.USDWorld — A prebuilt USD world — what World.usd(...) returns.
• simulo.Terrain — Terrain factory — Terrain.plane(...) and Terrain.rough(...) generate ground.
• simulo.GroundPlane — An infinite flat ground plane — what Terrain.plane(...) returns.
• simulo.RoughTerrain — Procedurally generated rough terrain for locomotion training — what Terrain.rough(...) returns.
• simulo.TerrainConfig — Base terrain configuration — a name and a pose. GroundPlane and RoughTerrain extend it.
• simulo.SubTerrainConfig — One sub-terrain type in a RoughTerrain’s grid — e.g. "pyramid_stairs", "random_rough".

Primitives

Entity.primitive.cone(...) / .cuboid(...) / .sphere(...) / .cylinder(...) are the usual way to build one of these (see Scene & entities); each dataclass below is what that factory returns, and is just as constructible directly.

• simulo.PrimitiveShape — Base class for the primitive shapes below — a name, pose, material, and physics.
• simulo.Cuboid — A box primitive, sized (width, depth, height).
• simulo.Sphere — A sphere primitive.
• simulo.Cylinder — A cylinder primitive.
• simulo.Cone — A cone primitive.

Sensors

Sensors attach to a Robot via robot.add_sensor(sensor, attach_to=...), before the robot is added to the scene:

self.robot.add_sensor(
    simulo.Camera(width=640, height=480, data_types=["rgb"]),
    attach_to="slider/side_cam",
)

attach_to is a path relative to the robot root — its trailing segment (side_cam above) becomes the sensor’s name. simulo.Camera is the RGB-D camera sensor; every camera also provides the base sensor contract shared by every sensor type — identity, enabled, update_period, lifecycle. The other concrete sensors in this section — ContactSensor, IMU, RayCaster, ForceTorqueSensor, FrameTransformer — attach the same way, and each takes an offset: simulo.SensorOffset to place it relative to attach_to, on top of the attachment point itself.

• simulo.Camera — RGB-D camera sensor — configured at authoring time, read after the simulation steps.
• simulo.SensorOffset — Position + orientation offset for mounting a sensor relative to its attachment point.
• simulo.CameraSpawnConfig — Camera optics — focal length, focus distance, aperture, and clipping range.
• simulo.ContactSensor — Contact force sensor using PhysX contact reporting — net forces and air time, commonly for foot contact detection.
• simulo.IMU — Inertial measurement unit — linear acceleration, angular velocity, and orientation.
• simulo.RayCaster — GPU ray-casting distance sensor — commonly a height scanner for locomotion.
• simulo.RayPattern — Ray distribution configuration for RayCaster — pattern type, resolution, and size.
• simulo.ForceTorqueSensor — 6-DOF force/torque sensor for a joint or link — commonly an end-effector or wrist.
• simulo.FrameTransformer — Computes the relative pose from a source frame to one or more target frames — for tracking objects and links relative to each other.
• simulo.FrameTransformerTarget — One target frame for a FrameTransformer — a prim path, optional name, and offset.

Actuators & controllers

Actuators and controllers command a Robot’s joints from task-space or high-level intent, complementing the low-level set_joint_*_target calls on Robot itself.

Grippers share one command-and-state vocabulary: drive either with set_command / set_commands, taking a GripperCommand (OPEN / IDLE / CLOSE) when you know the intent or a raw float when a policy is emitting it; read back with get_state(), which returns GripperState values. They differ only in how they attach, because they are different mechanisms: SurfaceGripperActuator is a physics constraint, so it is added to the scene like an Entity (scene.add(gripper, at=...)); ParallelGripperActuator is two finger joints a robot already has, so it is constructed against an already-built Robot and never added to the scene.

DifferentialIKController and OperationalSpaceController are constructed directly against an already-built Robot (typically in on_start) and driven every step with move_to(target) — they compute and apply joint commands themselves, so you don’t call the robot’s own joint-target setters while one is active. ActuatorGainsConfig configures PD gains per actuator group via Robot’s own actuator_gains= constructor argument.

• simulo.ActuatorGainsConfig — Per-actuator-group PD gains (stiffness/damping) — passed via Robot(actuator_gains={...}).
• simulo.SurfaceGripperActuator — A physics-constraint gripper added to the scene at a prim path and driven with set_command.
• simulo.ParallelGripperActuator — A two-finger gripper driven by finger-joint position targets — same command and state contract as SurfaceGripperActuator.
• simulo.GripperState — State a gripper REPORTS — OPEN, CLOSING, or CLOSED.
• simulo.GripperCommand — Command a gripper ACCEPTS — OPEN, IDLE, or CLOSE.
• simulo.DifferentialIKController — Differential inverse kinematics — moves an end-effector to a target pose by computing joint position commands.
• simulo.OperationalSpaceController — Task-space impedance control with optional simultaneous force control — for_compliant_motion() / for_force_control() build the common cases.

Lights

Lights are added to the scene the same way as terrain and entities: scene.add(simulo.Light.dome(name="light", intensity=2000.0), at="/", per_environment=False). Light.dome(...) and Light.distant(...) are the common cases; each returns the matching config dataclass below.

• simulo.Light — Light factory — Light.distant(...) and Light.dome(...) build the two light types.
• simulo.LightConfig — Base light configuration — a name, intensity, color, and pose.
• simulo.DistantLight — Distant (directional) light — parallel rays from infinity, like sunlight. What Light.distant(...) returns.
• simulo.DomeLight — Dome light for ambient illumination. What Light.dome(...) returns.

Markers

Markers are non-physical visualization elements: build one with a simulo.Visual factory method, add it to the scene once, then call .set_pose(...) on it every step to move it — the common pattern for tracking a target, waypoint, or moving body during a rollout. Every marker type shares the set_pose / set_visibility contract declared on VisualMarkerBase.

• simulo.Visual — Marker factory — Visual.axes(...), .sphere(...), .arrow(...), and .point(...) build the four marker types.
• simulo.VisualMarkerBase — Base class every marker type extends — a name, and the set_pose/set_visibility contract.
• simulo.AxesMarker — XYZ coordinate-axes marker (red/green/blue) — for visualizing frames, end-effector poses, or targets. What Visual.axes(...) returns.
• simulo.SphereMarker — Sphere marker — for visualizing targets, waypoints, or collision points. What Visual.sphere(...) returns.
• simulo.ArrowMarker — Directional arrow marker — for visualizing forces, velocities, or normals. What Visual.arrow(...) returns.
• simulo.PointMarker — Lightweight point marker — for visualizing many points at once. What Visual.point(...) returns.

Materials

Entity and every primitive take a material: Optional[simulo.Material] — visual appearance only, separate from physics (see Physics). SurfaceMaterial is the one concrete material type today.

• simulo.Material — Base material — the color/opacity every concrete material carries.
• simulo.SurfaceMaterial — Surface material — Material plus roughness. The one concrete material type today.
• simulo.DeformableMaterial — Material properties for a deformable body — Young’s modulus, Poisson’s ratio, damping.

Physics

Entity and every primitive take a physics: Optional[RigidPhysics | DeformablePhysics] — Physics.rigid(...) and Physics.deformable(...) build the two. RigidPhysics.collision takes a Collision, which turns collision on or off independently of the body’s other physics properties.

• simulo.Physics — Physics factory — Physics.rigid(...) and Physics.deformable(...) build the two kinds.
• simulo.RigidPhysics — Rigid-body physics — mass, collision, kinematic, and contact-sensor activation.
• simulo.DeformablePhysics — Deformable-body physics — wraps an optional DeformableMaterial.
• simulo.Collision — Collision on/off, independent of a body’s other physics properties.