Principle:Haosulab ManiSkill Environment Registration

Field	Value
Page Type	Principle
Title	ManiSkill Environment Registration
Domain	Simulation, Robotics, Environment_Design
Related Implementation	Implementation:Haosulab_ManiSkill_Register_Env_Decorator
Date	2026-02-15
Repository	Haosulab/ManiSkill

Overview

Description

ManiSkill employs a dual registration system for custom task environments. When a developer creates a new task by subclassing BaseEnv, the environment must be registered in two separate registries simultaneously: the ManiSkill internal registry (REGISTERED_ENVS) and the Gymnasium global registry (gym.registry). This dual registration is handled transparently through a single decorator, @register_env, which ensures that custom environments are accessible both through ManiSkill's own make() function and through the standard gym.make() API.

The registration mechanism serves several purposes:

• Discovery: environments become accessible by a unique string identifier (e.g., "PushCube-v1") rather than requiring direct class imports.
• Asset management: the registration system tracks which downloadable asset packs each environment depends on. When an environment is instantiated, the system checks whether all required assets are present and prompts the user to download missing ones.
• Configuration defaults: default keyword arguments (such as the default robot to use) are stored at registration time and passed through to the environment constructor at instantiation.
• Time limit enforcement: the max_episode_steps parameter is wired into a custom TimeLimitWrapper that correctly handles batched (GPU-parallel) truncation signals as torch.Tensor values rather than scalar booleans.

The Gymnasium side of registration uses functools.partial to create an entry point that routes back through ManiSkill's own make() function. This ensures that asset checking and ManiSkill-specific initialization always occur, regardless of whether the user calls gym.make() or mani_skill.utils.registration.make().

Usage

Environment registration is the first step when creating a new custom task environment. The developer applies the @register_env decorator directly to their BaseEnv subclass, specifying at minimum a unique environment ID string. This must be done before any code attempts to instantiate the environment through gym.make().

A typical workflow:

1. Define a new class that inherits from BaseEnv.
2. Apply @register_env("MyTask-v1", max_episode_steps=100) as a class decorator.
3. The environment is now available via gym.make("MyTask-v1").

If the task depends on downloadable 3D model assets, the developer lists the asset IDs in the asset_download_ids parameter. If the task re-uses default keyword arguments (such as a specific robot UID), those can be baked into the registration as **kwargs.

Theoretical Basis

The environment registration pattern follows the Gymnasium environment registry design, which itself is modeled after the OpenAI Gym registry introduced in 2016. The core idea is a global dictionary mapping string identifiers to factory specifications (EnvSpec objects), enabling late binding and configuration-driven instantiation.

Key design principles:

• Decorator-based registration: Using a Python decorator ensures that registration is co-located with the class definition, reducing the chance of forgetting to register a new environment. The decorator pattern is a well-established approach in Python frameworks (e.g., Flask route decorators, pytest fixtures).
• Separation of specification and instantiation: The EnvSpec object holds metadata (class reference, episode limit, asset dependencies, default kwargs) without instantiating the environment. Instantiation is deferred until .make() is called, allowing lightweight enumeration of available environments.
• Version-suffixed identifiers: Following Gymnasium convention, environment IDs include a version suffix (e.g., -v1). This allows breaking changes to be introduced under a new version while preserving reproducibility of results obtained with older versions.
• Asset dependency declaration: Declaring asset dependencies at registration time decouples the asset download mechanism from the environment logic, following the dependency injection principle.

The dual-registry approach (ManiSkill + Gymnasium) is necessary because ManiSkill environments have capabilities beyond standard Gymnasium environments -- specifically GPU-parallelized simulation, batched observations, and custom time-limit handling -- that require ManiSkill-specific initialization paths.

Related Pages

• Implementation:Haosulab_ManiSkill_Register_Env_Decorator -- Concrete decorator implementation
• Principle:Haosulab_ManiSkill_Scene_Object_Loading -- Loading objects into the registered environment
• Principle:Haosulab_ManiSkill_Episode_Initialization -- Initializing episodes after environment creation
• Principle:Haosulab_ManiSkill_Environment_Testing -- Testing registered environments