Implementation:Isaac sim IsaacGymEnvs Isaacgym Task Map Registration

Knowledge Sources	IsaacGymEnvs Isaac Gym Docs
Type	Pattern Doc
Domains	Architecture, Registration
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete code pattern for registering a custom task class in the isaacgym_task_map dictionary so that it can be discovered and instantiated by name from the CLI or API.

Description

The isaacgym_task_map dictionary in isaacgymenvs/tasks/__init__.py (L88-114) is the central task registry for IsaacGymEnvs. It maps string task names to Python classes (or resolver functions). The training pipeline looks up this dictionary when instantiating environments. Registering a new task requires adding an import statement and a dictionary entry.

Usage

After implementing a VecTask subclass and creating its YAML configuration files, add the registration entries to make the task available for training.

Code Reference

Source Location

• Repository: NVIDIA-Omniverse/IsaacGymEnvs
• File: isaacgymenvs/tasks/__init__.py (L88-114)

Registration Pattern

Step 1: Add Import

At the top of isaacgymenvs/tasks/__init__.py, add an import for your task class:

# isaacgymenvs/tasks/__init__.py — imports section

from isaacgymenvs.tasks.cartpole import Cartpole
from isaacgymenvs.tasks.ant import Ant
from isaacgymenvs.tasks.humanoid import Humanoid
from isaacgymenvs.tasks.shadow_hand import ShadowHand
# ... existing imports ...

# Add your new task import:
from isaacgymenvs.tasks.my_task import MyTask

Step 2: Add Dictionary Entry

Add your task to the isaacgym_task_map dictionary:

# isaacgymenvs/tasks/__init__.py — registry dictionary

isaacgym_task_map = {
    "AllegroHand": AllegroHand,
    "AllegroKuka": AllegroKuka,
    "AllegroKukaTwoArms": AllegroKukaTwoArms,
    "Ant": Ant,
    "Anymal": Anymal,
    "AnymalTerrain": AnymalTerrain,
    "BallBalance": BallBalance,
    "Cartpole": Cartpole,
    "FactoryTaskGears": FactoryTaskGears,
    "FactoryTaskInsertion": FactoryTaskInsertion,
    "FactoryTaskNutBoltPick": FactoryTaskNutBoltPick,
    "FactoryTaskNutBoltPlace": FactoryTaskNutBoltPlace,
    "FactoryTaskNutBoltScrew": FactoryTaskNutBoltScrew,
    "FrankaCubeStack": FrankaCubeStack,
    "Humanoid": Humanoid,
    "HumanoidAMP": HumanoidAMP,
    "Ingenuity": Ingenuity,
    "Quadcopter": Quadcopter,
    "ShadowHand": ShadowHand,
    "Trifinger": Trifinger,

    # Add your new task entry:
    "MyTask": MyTask,
}

How the Registry is Consumed

The registry is consumed by the get_rlgames_env_creator() function, which is called during training setup:

# Simplified flow from isaacgymenvs/utils/rlgames_utils.py

def get_rlgames_env_creator(seed, task_config, task_name, sim_device,
                             rl_device, graphics_device_id, headless, ...):
    """Create an environment creator function for rl_games."""

    def create_rlgpu_env():
        # Look up the task class in the registry
        task_class = isaacgym_task_map[task_name]

        # Instantiate the task with full configuration
        env = task_class(
            cfg=task_config,
            rl_device=rl_device,
            sim_device=sim_device,
            graphics_device_id=graphics_device_id,
            headless=headless,
            virtual_screen_capture=...,
            force_render=...,
        )
        return env

    return create_rlgpu_env

Resolver Functions for Task Variants

For tasks with multiple variants (e.g., different observation modes), a resolver function can be used instead of a direct class reference:

# Example: ShadowHand has multiple variants based on observation type

def resolve_shadow_hand(cfg, *args, **kwargs):
    """Resolve the correct ShadowHand class based on obs_type config."""
    obs_type = cfg["env"].get("observationType", "full")
    if obs_type == "openai":
        return ShadowHandOpenAI(cfg, *args, **kwargs)
    elif obs_type == "full_no_vel":
        return ShadowHandNoVel(cfg, *args, **kwargs)
    else:
        return ShadowHand(cfg, *args, **kwargs)

isaacgym_task_map = {
    # ... other entries ...
    "ShadowHand": resolve_shadow_hand,  # function instead of class
}

Complete Registration Checklist

Step	File	Action	Verification
1	isaacgymenvs/tasks/my_task.py	Create VecTask subclass	Class imports without errors
2	isaacgymenvs/tasks/__init__.py	Add import statement	No ImportError on module load
3	isaacgymenvs/tasks/__init__.py	Add isaacgym_task_map entry	Key exists in dict
4	cfg/task/MyTask.yaml	Create task config	File exists with correct name: field
5	cfg/train/MyTaskPPO.yaml	Create train config	File exists with correct config.name
6	CLI test	Run python train.py task=MyTask num_envs=4	Task instantiates and runs

I/O Contract

Inputs

Name	Type	Required	Description
Task class import	Python import	Yes	Import statement for the VecTask subclass
Task name string	str	Yes	Dictionary key used to look up the task (must match CLI task= argument)
Task class or resolver	class or callable	Yes	The VecTask subclass or a function that returns an instance

Outputs

Name	Type	Description
Registered task	dict entry	Task discoverable by get_rlgames_env_creator() and isaacgymenvs.make()

Related Pages

• Isaac_sim_IsaacGymEnvs_Task_Registration - implements - Principle defining the Service Locator pattern for task discovery.
• Isaac_sim_IsaacGymEnvs_VecTask_Subclass_Pattern - prerequisite - Task class must be implemented before registration.
• Isaac_sim_IsaacGymEnvs_Hydra_Task_Train_YAML - prerequisite - YAML configs must exist for the task name.
• Isaac_sim_IsaacGymEnvs_Train_Py_Task_Execution - next step - Run the registered task via the training pipeline.

Principle:Isaac_sim_IsaacGymEnvs_Task_Registration