SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsisaaclab-migrating-2x-to-3x

isaaclab-migrating-2x-to-3x

Coding & development

View repository

Updated 11-10 06:24

About this skill

Migrating 2.x To 3.x

When To Use

Use this skill when migrating a downstream Isaac Lab 2.x project to Isaac Lab 3.0 or diagnosing migration errors after an upgrade.

Do not copy migration tables into answers from memory. Read the official migration guide first, then inspect the current source or examples for the specific API involved.

Workflow

  1. Read the official migration guide in docs/source/isaaclab/migrating.rst.
  2. Identify which migration area applies: installation, backend packages and presets, asset and actuator APIs, sensors, quaternion order, ProxyArray, RL entrypoints, visualizers and recording, importers, Isaac Sim extension enablement, or project-specific scripts.
  3. Search the downstream project for old API symbols before editing.
  4. For user code that imports Isaac Sim extension modules directly:
    • Prefer an Isaac Lab in-tree API when the migration guide lists one.
    • If the direct Isaac Sim import is still needed, add from isaaclab.sim.utils import enable_extension and call enable_extension("<extension_name>") after the Kit application starts and before the first import from that extension.
    • Do not import enable_extension from isaacsim.core.experimental.utils.app; that module may not be importable until its extension is already enabled.
    • For custom .kit files, either list every direct Isaac Sim extension dependency explicitly or enable each extension before importing its Python module.
    • Do not add extension enables to plain Python modules that can be imported before Kit starts unless the code is guarded so it runs only inside a launched Kit app.
  5. Apply the smallest focused migration change.
  6. Run a targeted smoke test or import test. For direct Isaac Sim imports, ensure the script enters isaaclab.app.launch_simulation (tests: isaaclab.test.utils.launch_test_simulation) before enabling extensions. For example, run an app-launching test with uv run --extra isaacsim --with pytest python -m pytest PATH_TO_TEST.
  7. If the official docs are missing a recurring migration issue, update docs/source/isaaclab/migrating.rst instead of expanding this skill with standalone documentation.

Validation

Use this feedback loop:

uv run --with pytest python -m pytest PATH_TO_DOWNSTREAM_TEST

For quaternion migrations, use the repository quaternion tooling documented in the official migration guide.

For skill changes, run:

uv run --no-project python tools/skills/cli.py check

Maintenance

Keep this skill synchronized with docs/source/isaaclab/migrating.rst, docs/source/isaaclab/installation.rst, source/isaaclab_rl/isaaclab_rl/rsl_rl/rl_cfg.py, and the uv-based train and play entry points. If code changes invalidate migration guidance, update the official migration document first and keep this skill as a router plus checklist.

References