Principle:Haosulab ManiSkill Task Environment Definition

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

Overview

A task environment definition is a structured specification that binds scene geometry, robot agents, reward functions, success criteria, and observation extraction into a single Gymnasium-compatible environment class, enabling standardized training and evaluation of robot learning algorithms.

Description

Robotics simulation benchmarks require a consistent way to define tasks. The Task Environment Definition principle establishes a base environment class that implements the Gymnasium interface (reset, step, observation_space, action_space) while providing a structured set of hooks that task authors must implement. Each task environment inherits from this base class and is registered with a unique string identifier via a decorator, making it discoverable through the standard gym.make() API.

The key hooks a task environment must implement are: (1) _load_scene, which builds the non-robot objects in the scene (tables, cubes, goal markers); (2) _initialize_episode, which randomizes object positions and orientations at the start of each episode; (3) evaluate, which computes success conditions and returns an evaluation dictionary; (4) compute_dense_reward, which provides a shaped scalar reward for reinforcement learning; and (5) _get_obs_extra, which appends task-specific observations (goal positions, object states) to the standard proprioceptive and sensor observations.

This principle solves the problem of task standardization: every task in the benchmark follows the same lifecycle, exposes the same interface, and can be used interchangeably by training scripts. It also handles the complexity of GPU-parallelized simulation by ensuring that all task logic operates on batched tensors, allowing thousands of environment instances to run simultaneously on a single GPU.

Usage

This principle applies whenever:

• A new manipulation, locomotion, or interaction task must be added to the simulation benchmark.
• The task must be compatible with standard RL and IL training pipelines that expect the Gymnasium interface.
• GPU-parallelized rollout is needed, requiring all task logic to operate on batched tensors without Python loops over individual environments.
• Reproducible evaluation is required, with deterministic episode initialization controlled by seeds.
• Multiple reward modes (dense, sparse, normalized, none) must be offered for the same task.

Theoretical Basis

1. Environment Registration: Each task class is annotated with a registration decorator that assigns a unique string ID (e.g., "PickCube-v1"), a maximum episode length, and optionally overrides the default robot agent. This decorator inserts the environment into a global registry so that it can be instantiated by name. The registration pattern decouples task definition from task instantiation.

2. Scene Loading (_load_scene): This hook is called once during environment construction. It creates all non-robot actors (rigid bodies, articulations) and visual elements (goal markers, table surfaces). Scene loading is separate from episode initialization because the scene geometry is fixed across episodes -- only positions and configurations change.

3. Episode Initialization (_initialize_episode): Called at every reset(), this hook randomizes the initial state of all dynamic objects. It receives a batch of per-environment random number generators to ensure reproducibility. The randomization must be fully batched: no Python for-loops over environments, only tensor operations. Common patterns include sampling positions within bounds, sampling orientations, and ensuring objects do not overlap.

4. Evaluation (evaluate): Returns a dictionary containing at minimum a boolean success flag. May also include sub-metrics like is_grasped, is_close_to_goal, or distance_to_target. The evaluation function is called every step and is used both for reward computation and for determining episode termination.

5. Dense Reward (compute_dense_reward): Computes a scalar reward that provides a learning signal at every timestep. Dense rewards typically combine multiple terms: reaching rewards (distance from gripper to object), grasping rewards (binary or continuous grasp detection), placement rewards (distance from object to goal), and static rewards (penalizing unnecessary motion). Reward terms are often staged -- later terms only activate after earlier sub-goals are achieved -- to create a natural curriculum.

6. Observation Extraction (_get_obs_extra): Appends task-specific information to the observation dictionary. In "state" observation mode, this typically includes goal positions, object poses, and relative vectors. In sensor modes (RGBD, pointcloud), visual observations are handled automatically and _get_obs_extra adds only the non-visual components.

7. Lifecycle: reset() calls _initialize_episode then returns observations. step() applies the action, advances physics, calls evaluate and compute_reward, extracts observations, and returns the standard (obs, reward, terminated, truncated, info) tuple.

Related Pages

• Implementation:Haosulab_ManiSkill_BaseEnv_Step_Reset -- The base environment class implementing the Gymnasium lifecycle.
• Implementation:Haosulab_ManiSkill_Register_Env_Decorator -- The @register_env decorator for task registration.
• Implementation:Haosulab_ManiSkill_PickCube -- Baseline pick-and-place tabletop task.
• Implementation:Haosulab_ManiSkill_StackCube -- Cube stacking tabletop task.
• Implementation:Haosulab_ManiSkill_StackPyramid -- Pyramid stacking tabletop task.
• Implementation:Haosulab_ManiSkill_PegInsertionSide -- Peg insertion (side approach) task.
• Implementation:Haosulab_ManiSkill_PlugCharger -- Charger plugging precision task.
• Implementation:Haosulab_ManiSkill_LiftPegUpright -- Peg lifting and reorientation task.
• Implementation:Haosulab_ManiSkill_PokeCube -- Tool-use cube poking task.
• Implementation:Haosulab_ManiSkill_PullCube -- Cube pulling task.
• Implementation:Haosulab_ManiSkill_PullCubeTool -- Tool-use cube pulling task.
• Implementation:Haosulab_ManiSkill_RollBall -- Ball rolling task.
• Implementation:Haosulab_ManiSkill_PlaceSphere -- Sphere placement task.
• Implementation:Haosulab_ManiSkill_PickSingleYCB -- YCB single object pick-and-place task.
• Implementation:Haosulab_ManiSkill_PickClutterYCB -- YCB cluttered picking task.
• Implementation:Haosulab_ManiSkill_AssemblingKits -- Kit assembly task.
• Implementation:Haosulab_ManiSkill_TurnFaucet -- Faucet turning articulated object task.
• Implementation:Haosulab_ManiSkill_TwoRobotPickCube -- Cooperative two-robot pick task.
• Implementation:Haosulab_ManiSkill_TwoRobotStackCube -- Cooperative two-robot stacking task.
• Implementation:Haosulab_ManiSkill_PushT -- T-shape pushing task.
• Implementation:Haosulab_ManiSkill_FMBAssembly -- Functional Manipulation Benchmark assembly task.
• Implementation:Haosulab_ManiSkill_AntEnv -- Ant quadruped locomotion task.
• Implementation:Haosulab_ManiSkill_CartPole -- CartPole balance and swing-up control tasks.
• Implementation:Haosulab_ManiSkill_Hopper -- Hopper locomotion tasks.
• Implementation:Haosulab_ManiSkill_HumanoidEnv -- MuJoCo humanoid locomotion tasks.
• Implementation:Haosulab_ManiSkill_HumanoidStand -- Humanoid standing balance task.
• Implementation:Haosulab_ManiSkill_HumanoidPickPlace -- Humanoid pick-and-place task.
• Implementation:Haosulab_ManiSkill_TransportBox -- Humanoid box transport task.
• Implementation:Haosulab_ManiSkill_QuadrupedReach -- Quadruped locomotion reach task.
• Implementation:Haosulab_ManiSkill_QuadrupedSpin -- Quadruped spinning task.
• Implementation:Haosulab_ManiSkill_RotateSingleObjectInHand -- Dexterous in-hand object rotation task.
• Implementation:Haosulab_ManiSkill_RotateValveEnv -- Dexterous valve rotation task.
• Implementation:Haosulab_ManiSkill_RotateCube -- TriFinger cube rotation task.
• Implementation:Haosulab_ManiSkill_InsertFlower -- Dexterous flower insertion task.
• Implementation:Haosulab_ManiSkill_Draw -- Free-form drawing task.
• Implementation:Haosulab_ManiSkill_DrawSVG -- SVG path drawing task.
• Implementation:Haosulab_ManiSkill_DrawTriangle -- Triangle drawing task.
• Implementation:Haosulab_ManiSkill_OpenCabinetDrawer -- Mobile manipulation cabinet drawer task.
• Implementation:Haosulab_ManiSkill_RoboCasaKitchen -- RoboCasa kitchen manipulation task.
• Implementation:Haosulab_ManiSkill_EmptyEnv -- Minimal empty environment for testing.
• Implementation:Haosulab_ManiSkill_PutOnInScene -- Bridge dataset evaluation task.
• Implementation:Haosulab_ManiSkill_SceneManipulationEnv -- Base environment for scene-based manipulation tasks.
• Implementation:Haosulab_ManiSkill_BaseDigitalTwinEnv -- Base environment for digital twin tasks.
• Implementation:Haosulab_ManiSkill_Evaluate_Dense_Reward -- Reward evaluation utility pattern.
• Implementation:Haosulab_ManiSkill_Initialize_Episode_Pattern -- Episode initialization pattern reference.
• Implementation:Haosulab_ManiSkill_Get_Obs_Extra_CameraConfig -- Observation and camera configuration pattern.