isaaclab-using-presets

# 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](../../../docs/source/concepts/backends_and_presets.rst) 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 1. Identify whether the task needs variants. Common reasons are physics backend differences, renderer differences, camera data types, event randomization differences, or play/train variants. 2. If there is only one supported behavior, keep the config simple and do not add `PresetCfg`. 3. 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,...]`. 4. 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. 5. Assign the preset wrapper to the owning environment config field, for example `sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg())`. 6. Keep backend-specific values inside preset classes rather than scattering runtime conditionals through task logic. 7. Use suffixless task names in commands. 8. List available preset names before using them in commands. 9. Smoke-test every preset with a small random-agent rollout before training. ## Validation Use this checklist: 1. Confirm a plain config would not be sufficient. 2. Confirm every preset variant has a clear reason to exist. 3. Confirm `default` points to a valid config. 4. Confirm selector names are discoverable through the task's preset help or environment list. 5. Run a small reset/step smoke test for every new preset. 6. Run training only after preset-specific shape, device, backend, and renderer behavior is stable. For skill changes, run: ```bash 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 - [Reference](reference.md) - [Examples](examples.md) - [Evaluations](evaluations.md) - [Backends and presets](../../../docs/source/concepts/backends_and_presets.rst) - [Preset utility source](../../../source/isaaclab_tasks/isaaclab_tasks/utils/hydra.py) - [Environment browser](../../../docs/source/setup/environments.rst) - [Quickstart](../../../docs/source/setup/quickstart.rst)