Principle:Isaac sim IsaacGymEnvs Task Registration

Field	Value
Principle Name	Task Registration
Overview	Registration pattern for making custom RL environments discoverable by the training pipeline through a name-to-class mapping.
Domains	Architecture, Registration
Related Implementation	Isaac_sim_IsaacGymEnvs_Isaacgym_Task_Map_Registration
Last Updated	2026-02-15 00:00 GMT

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

Description

IsaacGymEnvs uses a dictionary-based task registry (isaacgym_task_map) that maps string task names to their corresponding Python task classes or resolver functions. This registry is the central mechanism through which the training pipeline discovers and instantiates RL environments at runtime.

When a user specifies task=MyTask on the command line (or via the API), the following chain occurs:

1. Hydra loads cfg/task/MyTask.yaml and cfg/train/MyTaskPPO.yaml.
2. The training pipeline calls get_rlgames_env_creator() with the task name.
3. get_rlgames_env_creator() looks up isaacgym_task_map["MyTask"] to find the class.
4. The class is instantiated with the composed configuration and device parameters.

Registration requires two changes in isaacgymenvs/tasks/__init__.py:

1. Import the task class at the top of the file.
2. Add an entry to the isaacgym_task_map dictionary mapping the task name string to the class.

Theoretical Basis

This pattern is a form of the Service Locator design pattern:

• String names decouple task selection from class instantiation: The training pipeline does not need to import every task class directly. It only needs to know the task name string, and the registry resolves it to the appropriate class.
• Dynamic discovery without import dependencies: New tasks can be added without modifying the training loop code. Only the registry file (__init__.py) needs to be updated.
• Support for resolver functions: For tasks with sub-variants (e.g., different observation modes), the registry can map a name to a resolver function that returns the appropriate class based on configuration. This adds a level of indirection that supports complex task families.
• Convention over configuration: The naming convention (task=TaskName maps to cfg/task/TaskName.yaml, cfg/train/TaskNamePPO.yaml, and isaacgym_task_map["TaskName"]) creates a predictable, discoverable system.

When to Use

Use this principle when:

• Making a newly created task class available for training via the CLI (python train.py task=MyTask).
• Making a task available via the programmatic API (isaacgymenvs.make(task="MyTask")).
• Understanding why a task is not found when trying to train it (likely missing registration).
• Adding a task variant that uses a resolver function instead of a direct class reference.

Structure

The registration process involves three components:

1. Task class file (isaacgymenvs/tasks/my_task.py): Contains the VecTask subclass.
2. Registry file (isaacgymenvs/tasks/__init__.py): Contains the import and the isaacgym_task_map dictionary entry.
3. Configuration files (cfg/task/MyTask.yaml, cfg/train/MyTaskPPO.yaml): Must exist with the correct task name.

The task name string must be consistent across all three:

Component	Name Convention	Example
Task class	Python class name	class Cartpole(VecTask)
Registry key	String in isaacgym_task_map	"Cartpole": Cartpole
CLI argument	task= parameter	task=Cartpole
Task YAML	cfg/task/{name}.yaml	cfg/task/Cartpole.yaml
Train YAML	cfg/train/{name}PPO.yaml	cfg/train/CartpolePPO.yaml

Common Issues

Issue	Cause	Fix
KeyError: 'MyTask'	Task not in isaacgym_task_map	Add import and dict entry in __init__.py
ModuleNotFoundError	Import path incorrect	Verify module path matches file location
MissingMandatoryValue	YAML file missing or misnamed	Ensure cfg/task/MyTask.yaml exists
Task runs but with wrong config	Task name mismatch between YAML and registry	Verify name: field in YAML matches registry key

Related Pages

• Isaac_sim_IsaacGymEnvs_Isaacgym_Task_Map_Registration - implements - Concrete code pattern for adding registry entries.
• Isaac_sim_IsaacGymEnvs_VecTask_Subclass_Creation - prerequisite - The task class must exist before it can be registered.
• Isaac_sim_IsaacGymEnvs_Task_Configuration_Files - prerequisite - YAML configs must exist for the registered task name.
• Isaac_sim_IsaacGymEnvs_Train_Py_Task_Execution - consumer - The training pipeline that consumes the registry.

Implementation:Isaac_sim_IsaacGymEnvs_Isaacgym_Task_Map_Registration