Using Presets
When To Use
Use this skill when a user needs to define, select, or debug Isaac Lab PresetCfg variants for environments, physics backends, renderers, sensors, events, or task-specific configuration options.
Read the Backends and Presets concept for the authoritative selector behavior and resolution order.
Do not use presets for simple one-backend tasks with no meaningful configuration variants. Prefer a plain config until the task needs a real selectable alternative.
Workflow
- Identify whether the task needs variants. Common reasons are physics backend differences, renderer differences, camera data types, event randomization differences, or play/train variants.
- If there is only one supported behavior, keep the config simple and do not add
PresetCfg.
- If variants are needed, choose the selector category:
- Use a
PhysicsCfg(PresetCfg) field for physics backend variants selected by physics=NAME.
- Use a renderer preset for renderer variants selected by
renderer=NAME.
- Use task/domain presets for environment-specific variants selected by
presets=NAME[,NAME,...].
- Define a
default variant. Add explicit named variants such as physx, newton_mjwarp, newton_kamino, ovphysx, rgb, or depth only when the task supports them.
- Assign the preset wrapper to the owning environment config field, for example
sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg()).
- Keep backend-specific values inside preset classes rather than scattering runtime conditionals through task logic.
- Use suffixless task names in commands.
- List available preset names before using them in commands.
- Smoke-test every preset with a small random-agent rollout before training.
Validation
Use this checklist:
- Confirm a plain config would not be sufficient.
- Confirm every preset variant has a clear reason to exist.
- Confirm
default points to a valid config.
- Confirm selector names are discoverable through the task's preset help or environment list.
- Run a small reset/step smoke test for every new preset.
- Run training only after preset-specific shape, device, backend, and renderer behavior is stable.
For skill changes, run:
uv run --no-project python tools/skills/cli.py check
Maintenance
Keep this skill synchronized with docs/source/concepts/backends_and_presets.rst, source/isaaclab_tasks/isaaclab_tasks/utils/hydra.py, the environment catalog, and maintained preset examples under source/isaaclab_tasks/isaaclab_tasks/. If preset selector behavior changes, update the source docs or examples first and keep this skill as a routing checklist.
References
1---2name: isaaclab-using-presets3description: Defines and uses Isaac Lab preset configurations for multi-backend tasks. Use when adding PhysX/Newton variants, renderer variants, domain presets, or deciding whether a task needs PresetCfg.4audience: user5status: experimental6owners:7 - isaaclab-maintainers8metadata:9 source: https://skillmd.com/skills/isaac-sim/isaaclab-using-presets10---1112# Using Presets1314## When To Use1516Use this skill when a user needs to define, select, or debug Isaac Lab `PresetCfg` variants for environments, physics backends, renderers, sensors, events, or task-specific configuration options.1718Read the [Backends and Presets concept](../../../docs/source/concepts/backends_and_presets.rst) for the authoritative selector behavior and resolution order.1920Do not use presets for simple one-backend tasks with no meaningful configuration variants. Prefer a plain config until the task needs a real selectable alternative.2122## Workflow23241. Identify whether the task needs variants. Common reasons are physics backend differences, renderer differences, camera data types, event randomization differences, or play/train variants.252. If there is only one supported behavior, keep the config simple and do not add `PresetCfg`.263. If variants are needed, choose the selector category:27 - Use a `PhysicsCfg(PresetCfg)` field for physics backend variants selected by `physics=NAME`.28 - Use a renderer preset for renderer variants selected by `renderer=NAME`.29 - Use task/domain presets for environment-specific variants selected by `presets=NAME[,NAME,...]`.304. Define a `default` variant. Add explicit named variants such as `physx`, `newton_mjwarp`, `newton_kamino`, `ovphysx`, `rgb`, or `depth` only when the task supports them.315. Assign the preset wrapper to the owning environment config field, for example `sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg())`.326. Keep backend-specific values inside preset classes rather than scattering runtime conditionals through task logic.337. Use suffixless task names in commands.348. List available preset names before using them in commands.359. Smoke-test every preset with a small random-agent rollout before training.3637## Validation3839Use this checklist:40411. Confirm a plain config would not be sufficient.422. Confirm every preset variant has a clear reason to exist.433. Confirm `default` points to a valid config.444. Confirm selector names are discoverable through the task's preset help or environment list.455. Run a small reset/step smoke test for every new preset.466. Run training only after preset-specific shape, device, backend, and renderer behavior is stable.4748For skill changes, run:4950```bash51uv run --no-project python tools/skills/cli.py check52```5354## Maintenance5556Keep this skill synchronized with `docs/source/concepts/backends_and_presets.rst`, `source/isaaclab_tasks/isaaclab_tasks/utils/hydra.py`, the environment catalog, and maintained preset examples under `source/isaaclab_tasks/isaaclab_tasks/`. If preset selector behavior changes, update the source docs or examples first and keep this skill as a routing checklist.5758## References5960- [Reference](reference.md)61- [Examples](examples.md)62- [Evaluations](evaluations.md)63- [Backends and presets](../../../docs/source/concepts/backends_and_presets.rst)64- [Preset utility source](../../../source/isaaclab_tasks/isaaclab_tasks/utils/hydra.py)65- [Environment browser](../../../docs/source/isaaclab/environments.rst)66- [Quickstart](../../../docs/source/isaaclab/quickstart.rst)