Schema Configuration Classes

Isaac Lab’s spawners author USD physics attributes onto prims via a layered set of configuration classes. The layering separates universal-physics parameters from backend-specific parameters, so the same asset cfg can be authored once and target any backend that supports it.

This page explains the class hierarchy, when to use each tier, and how parameters route to the underlying USD attributes.

Migrating from 2.x? See | set_joint_velocity_target | actuators.target_command.set_velocity_index | in the 3.0 migration guide.

Quick example

Add MuJoCo (MJC) gravity compensation to an articulated asset:

import isaaclab.sim as sim_utils
from isaaclab_newton.sim.schemas import (
    MujocoRigidBodyPropertiesCfg,
    MujocoJointDrivePropertiesCfg,
)
spawn = sim_utils.UsdFileCfg(
    usd_path=f"{ISAAC_NUCLEUS_DIR}/Robots/Franka/franka_instanceable.usd",
    rigid_props=MujocoRigidBodyPropertiesCfg(gravcomp=1.0),
    joint_drive_props=MujocoJointDrivePropertiesCfg(actuatorgravcomp=True),
)

The Mujoco-specific fields land under mjc:* on the prim; any RigidBodyBaseCfg / JointDriveBaseCfg fields you set on the same instance land under physics:*. See Mixed-namespace authoring on a single instance for the full routing rules.

Class hierarchy

For each property group (rigid body, joint drive, collision, articulation root, material, mesh collision), Isaac Lab defines a single base class in core isaaclab.sim.schemas and one subclass per backend in the corresponding extension package:

isaaclab.sim.schemas
├── RigidBodyBaseCfg
│   ├── isaaclab_physx.sim.schemas.PhysxRigidBodyPropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonRigidBodyPropertiesCfg
│       └── isaaclab_newton.sim.schemas.MujocoRigidBodyPropertiesCfg
│
├── JointDriveBaseCfg
│   ├── isaaclab_physx.sim.schemas.PhysxJointDrivePropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonJointDrivePropertiesCfg
│       └── isaaclab_newton.sim.schemas.MujocoJointDrivePropertiesCfg
│
├── CollisionBaseCfg
│   ├── isaaclab_physx.sim.schemas.PhysxCollisionPropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonCollisionPropertiesCfg
│       ├── isaaclab_newton.sim.schemas.NewtonMeshCollisionPropertiesCfg
│       └── isaaclab_newton.sim.schemas.NewtonSDFCollisionPropertiesCfg
│
├── ArticulationRootBaseCfg
│   ├── isaaclab_physx.sim.schemas.PhysxArticulationRootPropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonArticulationRootPropertiesCfg
│
├── MeshCollisionBaseCfg
│   ├── isaaclab_physx.sim.schemas.{PhysxConvexHull, PhysxConvexDecomposition,
│   │                                PhysxTriangleMesh, PhysxSDFMesh, ...}PropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonMeshCollisionPropertiesCfg
│       (also inherits NewtonCollisionPropertiesCfg — multi-namespace)
│
└── isaaclab.sim.spawners.materials.RigidBodyMaterialBaseCfg
    ├── isaaclab_physx.sim.spawners.materials.PhysxRigidBodyMaterialCfg
    └── isaaclab_newton.sim.schemas.NewtonMaterialPropertiesCfg

~isaaclab_newton.sim.schemas.NewtonMeshCollisionPropertiesCfg uses multiple inheritance: it extends both ~isaaclab_newton.sim.schemas.NewtonCollisionPropertiesCfg (for contact_margin / contact_gap) and ~isaaclab.sim.schemas.MeshCollisionBaseCfg (for mesh_approximation_name). This is the textbook case for the per-declaring- class MRO routing described under Mixed-namespace authoring on a single instance — each inherited field is written under the namespace of the class that declared it. ~isaaclab_newton.sim.schemas.NewtonSDFCollisionPropertiesCfg is collision-rooted, so it authors NewtonSDFCollisionAPI without also applying UsdPhysics.MeshCollisionAPI or setting physics:approximation.

The hierarchy is single-rooted per spawner slot: every spawner has a single field for each property group (rigid_props, joint_drive_props, collision_props, etc.), and Python’s polymorphism allows any subclass to be passed where the base type is expected.

When to use which class

The choice depends on which backends you target and which fields you need.

Use a base class (RigidBodyBaseCfg, JointDriveBaseCfg, etc.) when you only need universal-physics fields and you want your asset cfg to be backend-portable. Importing the base class does not pull in isaaclab_physx or isaaclab_newton.

Use a PhysX subclass (PhysxRigidBodyPropertiesCfg, etc.) when your asset uses PhysX-specific knobs (per-body damping, TGS solver iterations, sleep / stabilization thresholds, torsional patch friction, compliant-contact materials, etc.) and you target the PhysX backend. Inherits all base-class fields, so you can set both universal and PhysX fields on the same instance.

Use a Newton subclass (NewtonRigidBodyPropertiesCfg, etc.) when you target Newton and need Newton-native attributes (newton:contactMargin, newton:torsionalFriction, newton:selfCollisionEnabled, etc.). The empty Newton base classes (NewtonRigidBodyPropertiesCfg, NewtonJointDrivePropertiesCfg) reserve the newton:* namespace for future native fields and act as the parent for solver-specific subclasses.

Use a MuJoCo subclass (MujocoRigidBodyPropertiesCfg, MujocoJointDrivePropertiesCfg) when you specifically use Newton’s MuJoCo solver and need MuJoCo-only knobs (gravity compensation via mjc:gravcomp / mjc:actuatorgravcomp). Inherits from the Newton base, so isinstance(cfg, NewtonRigidBodyPropertiesCfg) is True.

What parameters live where

Universal physics (declared on the base class)

Lives on the base class. Most fields write to physics:* (the standard UsdPhysics.*API namespace), but a small set of “exception” fields are declared on the base for backend-portability yet route to a non-physics:* namespace because that is the only USD path honored today (e.g., disable_gravity writes physxRigidBody:disableGravity because both PhysX and Newton’s importer consume the PhysX attribute). The “USD attribute” column below is the actual emitted attribute, not the namespace family.

PhysX-specific (physx*:* namespace, Physx*API schemas)

PhysX-specific (physx*:* namespace, Physx*API schemas)

Lives on the PhysX subclass. Only authored when the user opts in by setting the field on a PhysX cfg.

Newton-targeted (newton:* namespace, Newton*API schemas)

Newton-targeted (newton:* namespace, Newton*API schemas)

Lives on the Newton subclass. Authored only when the user opts in.

MuJoCo-solver-specific (mjc:* namespace)

MuJoCo-solver-specific (mjc:* namespace)

Lives on a MuJoCo subclass that extends a Newton subclass. Only consumed when running Newton’s MuJoCo solver.

Mixed-namespace authoring on a single instance

Because each cfg field is routed to its declaring class’s namespace (not the instance’s class), a subclass instance can author attributes across multiple namespaces on the same prim. For example:

from isaaclab_newton.sim.schemas import MujocoRigidBodyPropertiesCfg
cfg = MujocoRigidBodyPropertiesCfg(
    rigid_body_enabled=True,        # declared on RigidBodyBaseCfg → physics:rigidBodyEnabled
    disable_gravity=True,            # declared on RigidBodyBaseCfg (exception) → physxRigidBody:disableGravity
    gravcomp=1.0,                    # declared on MujocoRigidBodyPropertiesCfg → mjc:gravcomp
)

The writer applies each field to the namespace of the class where the field is declared. The applied schemas (PhysxRigidBodyAPI for disable_gravity, none for the Mjc raw attribute) are added only when the corresponding fields are non-None.

Spawner usage

Spawners (UsdFileCfg, MeshCuboidCfg, MeshSphereCfg, …) accept the base class type for each slot and use polymorphism to dispatch to the correct subclass at write time:

import isaaclab.sim as sim_utils
from isaaclab_physx.sim.schemas import PhysxRigidBodyPropertiesCfg
from isaaclab_newton.sim.schemas import MujocoJointDrivePropertiesCfg
spawn = sim_utils.UsdFileCfg(
    usd_path="...",
    rigid_props=PhysxRigidBodyPropertiesCfg(disable_gravity=True, linear_damping=0.1),
    joint_drive_props=MujocoJointDrivePropertiesCfg(
        drive_type="acceleration",
        stiffness=10.0,
        damping=0.1,
        actuatorgravcomp=True,
    ),
)

Gravity compensation (MuJoCo solver)

Gravity compensation has two halves and you typically need both:

• Body-level: isaaclab_newton.sim.schemas.MujocoRigidBodyPropertiesCfg.gravcomp on each rigid body (writes mjc:gravcomp). This is what computes the compensation force.
• Joint-level: isaaclab_newton.sim.schemas.MujocoJointDrivePropertiesCfg.actuatorgravcomp on each joint (writes mjc:actuatorgravcomp). This routes the compensation force through the actuator channel (qfrc_actuator) so it counts against actuatorfrcrange; otherwise it goes to qfrc_passive.

actuatorgravcomp=True alone is a no-op — without body-level gravcomp there are no forces to route. To prevent this footgun, the spawner auto-enables MujocoRigidBodyPropertiesCfg(gravcomp=1.0) whenever joint_drive_props is a Mujoco cfg with actuatorgravcomp=True and rigid_props is not already a Mujoco cfg. If you want a different gravcomp value (or want to disable the auto-enable), pass an explicit MujocoRigidBodyPropertiesCfg in rigid_props.

Naming convention

Cfg field names use snake_case; the writer converts them to camelCase USD attribute names (contact_margin → newton:contactMargin). For single-token fields (gravcomp, actuatorgravcomp), the conversion is identity, which matches MuJoCo’s lowercase convention.

Field renames preserve backward compatibility via deprecation aliases. Two such aliases live on JointDriveBaseCfg today:

• max_velocity → max_joint_velocity (USD attribute is physxJoint:maxJointVelocity)
• max_effort → max_force (USD attribute is drive:<axis>:physics:maxForce)

The old names remain as real dataclass fields (so dataclasses.fields() sees them), defaulting to None. __post_init__ runs deprecate_field_alias which, when the old field is set: emits a DeprecationWarning, copies the value into the canonical field if the canonical is None, then nulls the old field. Setting both in the same constructor is silent — the canonical wins; the old name’s value is discarded. Both aliases are scheduled for removal in 4.0.

See also

• Schema Fragments — single-namespace fragments and expression-driven targeting
• /source/migration/migrating_to_isaaclab_3-0 — migration guide
• /source/api/lab/isaaclab.sim.schemas — solver-common base class API
• /source/api/lab_physx/isaaclab_physx.sim.schemas — PhysX subclass API
• /source/api/lab_newton/isaaclab_newton.sim.schemas — Newton/MuJoCo subclass API