[major fix]update the code base to avoid isaacsim shutdown issue, add auto-skill scripts, update task import order issue, skip task scanning if not using (#761)

Author: geng-haoran

docs/source/metasim/concept/task.md

@@ -87,9 +87,11 @@ env = task_cls(scenario=scenario, device=device)
 `make_vec` provides a standardized helper that wraps task instantiation in a **Gym‑compatible API**. It is the recommended entry point for creating environments.
 
 ```python
-import metasim # triggering the registration of tasks with Gymnasium
+import metasim
 from gymnasium import make_vec
 
+metasim.register_gym_envs()  # register RoboVerse/* with Gymnasium before make_vec
+
 env = make_vec(
     env_id,                      # e.g., "example.my_task"
     num_envs=args.num_envs,
@@ -109,15 +111,17 @@ env = make_vec(
 
 ---
 
-## 4. Task Registration & Auto‑Import
+## 4. Task Registration & Discovery
 
-### 4.1 Auto‑import paths
+### 4.1 Discovery paths
 
-Task modules under the following directories are **auto‑imported and registered** at runtime:
+Task modules under these packages are found when discovery runs (not on every `import metasim`):
 
 * `metasim/example/example_pack/tasks`
 * `roboverse_pack/tasks`
 
+Discovery is triggered by `get_task_class`, `list_tasks`, or `metasim.register_gym_envs()`.
+
 > For new project tasks, place modules under **`roboverse_pack/tasks`**.
 
 ### 4.2 How to register a task

get_started/0_static_scene.py

@@ -119,6 +119,11 @@ def __post_init__(self):
     ]
 
     log.info(f"Using simulator: {args.sim}")
+    if args.sim == "isaacsim":
+        # Enable timeout-guarded close in IsaacSim handler for one-shot script usage.
+        # GUI mode can also hang on SimulationApp.close() on some systems.
+        os.environ["METASIM_FORCE_EXIT_ON_CLOSE"] = "1"
+        os.environ.setdefault("METASIM_CLOSE_TIMEOUT_SEC", "8")
     handler = get_handler(scenario)
     init_states = [
         {

get_started/9_cfg_task.py

@@ -21,7 +21,9 @@
 import torch
 from gymnasium import make_vec
 
-import metasim  # noqa: F401
+import metasim
+
+metasim.register_gym_envs()
 from metasim.scenario.cameras import PinholeCameraCfg
 from metasim.utils import configclass
 from metasim.utils.obs_utils import ObsSaver

get_started/dexhands/0_control_dexhands.py

@@ -20,7 +20,9 @@
 import torch
 from gymnasium import make_vec
 
-import metasim  # noqa: F401
+import metasim
+
+metasim.register_gym_envs()
 
 # Ensure the new env class is imported so its @register_task decorators run.
 # Adjust the import path if you place xhand_env.py elsewhere.

get_started/rl/0_ppo_gym_style.py

@@ -26,7 +26,9 @@
 # from metasim.task.gym_registration import make_vec
 from gymnasium import make_vec
 
-import metasim  # noqa: F401
+import metasim
+
+metasim.register_gym_envs()
 from metasim.scenario.cameras import PinholeCameraCfg
 from metasim.utils.obs_utils import ObsSaver
 

metasim/__init__.py

@@ -1,13 +1,14 @@
-"""All metasim packages.
-
-Importing this top-level package ensures tasks are discovered and registered
-with Gymnasium (single and vector) so users can call gymnasium.make and
-gymnasium.make_vec without manual registration calls.
-"""
-
-# Trigger task discovery and Gymnasium registration on package import.
-try:  # pragma: no cover
-    import metasim.task  # noqa: F401
-except Exception:
-    # Best-effort; individual scripts can still register on-demand if needed.
-    pass
+"""All metasim packages."""
+
+from __future__ import annotations
+
+
+def register_gym_envs() -> None:
+    """Discover task modules and register ``RoboVerse/<task>`` with Gymnasium.
+
+    Call this before ``gymnasium.make`` / ``make_vec`` with RoboVerse env ids.
+    Sim-only code paths do not need this.
+    """
+    from metasim.task.gym_registration import register_all_tasks_with_gym
+
+    register_all_tasks_with_gym()

metasim/queries/contact_force.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 try:
     import isaacgym
 except ImportError:
@@ -11,7 +13,9 @@
 import torch
 
 from metasim.queries.base import BaseQueryType
-from metasim.sim.base import BaseSimHandler
+
+if TYPE_CHECKING:
+    from metasim.sim.base import BaseSimHandler
 
 try:
     import mujoco

metasim/sim/isaacsim/isaacsim.py

@@ -5,6 +5,7 @@
 import argparse
 import math
 import os
+import threading
 from copy import deepcopy
 
 import numpy as np
@@ -74,6 +75,10 @@ def __init__(self, scenario_cfg: ScenarioCfg, optional_queries: list[BaseQueryTy
         self._is_closed = False
         self.render_interval = self.scenario.decimation  # TODO: fix hardcode
         self._manual_pd_on = []
+        self._owns_simulation_app = False
+        self.simulation_app = None
+        self.scene = None
+        self.sim = None
 
         if self.headless:
             self._render_viewport = False
@@ -94,8 +99,10 @@ def _init_scene(self, simulation_app=None, args=None) -> None:
             args.headless = self.headless
             app_launcher = AppLauncher(args)
             self.simulation_app = app_launcher.app
+            self._owns_simulation_app = True
         else:
             self.simulation_app = simulation_app
+            self._owns_simulation_app = False
 
         # physics context
         from isaaclab.scene import InteractiveScene, InteractiveSceneCfg
@@ -216,7 +223,44 @@ def launch(self, simulation_app=None, simulation_args=None) -> None:
     def close(self) -> None:
         log.info("close Isaacsim Handler")
         if not self._is_closed:
-            self.simulation_app.close()
+            force_exit_on_close_hang = os.getenv("METASIM_FORCE_EXIT_ON_CLOSE", "0") == "1"
+            close_timeout_s = float(os.getenv("METASIM_CLOSE_TIMEOUT_SEC", "8"))
+            simulation_app = getattr(self, "simulation_app", None)
+            owns_simulation_app = getattr(self, "_owns_simulation_app", False)
+
+            if simulation_app is not None and force_exit_on_close_hang and owns_simulation_app:
+                close_error: dict[str, Exception] = {}
+
+                def _close_sim_app() -> None:
+                    try:
+                        # Isaac Sim may hang on shutdown waiting for Replicator workers.
+                        simulation_app.close(wait_for_replicator=False)
+                    except TypeError:
+                        # Backward compatibility with versions where close() has no kwargs.
+                        simulation_app.close()
+                    except Exception as err:
+                        close_error["error"] = err
+
+                close_thread = threading.Thread(target=_close_sim_app, daemon=True)
+                close_thread.start()
+                close_thread.join(timeout=close_timeout_s)
+                if close_thread.is_alive():
+                    log.warning(
+                        f"SimulationApp.close() exceeded {close_timeout_s:.1f}s. "
+                        "Forcing process exit to avoid shutdown hang."
+                    )
+                    import sys
+
+                    sys.stdout.flush()
+                    sys.stderr.flush()
+                    os._exit(0)
+                if "error" in close_error:
+                    raise close_error["error"]
+            elif simulation_app is not None:
+                try:
+                    simulation_app.close(wait_for_replicator=False)
+                except TypeError:
+                    simulation_app.close()
             if self.scene is not None:
                 del self.scene
             if self.sim is not None:

metasim/task/__init__.py

@@ -1,19 +1,8 @@
-"""Auto-import all submodules in the tasks package.
+"""Task registry, base env types, and optional Gymnasium integration.
 
-This ensures that all tasks decorated with @register_task are registered
-when the package is imported.
+Submodules here are not bulk-imported on package load. Discovery runs only when
+you call ``get_task_class`` / ``list_tasks`` or ``register_all_tasks_with_gym``
+(see ``metasim.register_gym_envs``), so sim-only scripts stay lightweight.
 """
 
 from __future__ import annotations
-
-# After tasks are discoverable, automatically register all tasks with Gymnasium
-# so users can call gymnasium.make / gymnasium.make_vec without manual steps.
-try:
-    from .gym_registration import register_all_tasks_with_gym as _register_all_tasks_with_gym
-    from .registry import _discover_task_modules
-
-    _discover_task_modules()
-    _register_all_tasks_with_gym()
-except Exception:
-    # Best-effort: scripts can still call register_task_with_gym on-demand.
-    pass

metasim/task/registry.py

@@ -86,7 +86,7 @@ def _discover_task_modules() -> None:
                 try:
                     import_module(module_name)
                 except Exception as e:
-                    log.error(f"Task discovery: failed to import module '{module_name}': {e}")
+                    log.debug(f"Task discovery: skip module '{module_name}': {e}")
         except Exception as e:
             log.error(f"Task discovery: error scanning package '{pkg_name}': {e}")