Refactor schema cfgs to separate solver-common from PhysX-specific fields

Split RigidBodyPropertiesCfg and JointDrivePropertiesCfg into
solver-common base classes and PhysX-specific subclasses
(PhysxRigidBodyPropertiesCfg, PhysxJointDrivePropertiesCfg).

Each solver-specific cfg declares _usd_applied_schema, _usd_namespace,
and _usd_attr_name_map metadata so that modify_rigid_body_properties
and modify_joint_drive_properties write attributes generically without
backend-specific branching. This prepares the schema layer for adding
additional solver backends (e.g. MuJoCo) without modifying the modify
functions.

Author: vidurv-nvidia

source/isaaclab/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "4.6.1"
+version = "4.6.2"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

source/isaaclab/docs/CHANGELOG.rst

@@ -1,6 +1,33 @@
 Changelog
 ---------
 
+4.6.2 (2026-04-14)
+~~~~~~~~~~~~~~~~~~~
+
+Changed
+^^^^^^^
+
+* Refactored :class:`~isaaclab.sim.schemas.RigidBodyPropertiesCfg` to contain only
+  solver-common properties (``rigid_body_enabled``, ``kinematic_enabled``). PhysX-specific
+  properties are now in :class:`~isaaclab.sim.schemas.PhysxRigidBodyPropertiesCfg`.
+
+  - **Migration:** Replace ``RigidBodyPropertiesCfg(disable_gravity=True, ...)`` with
+    ``PhysxRigidBodyPropertiesCfg(disable_gravity=True, ...)``.
+
+* Refactored :class:`~isaaclab.sim.schemas.JointDrivePropertiesCfg` to contain only
+  solver-common properties (``drive_type``, ``max_effort``, ``stiffness``, ``damping``,
+  ``ensure_drives_exist``). The PhysX-specific ``max_velocity`` field is now in
+  :class:`~isaaclab.sim.schemas.PhysxJointDrivePropertiesCfg`.
+
+  - **Migration:** Replace ``JointDrivePropertiesCfg(max_velocity=5.0, ...)`` with
+    ``PhysxJointDrivePropertiesCfg(max_velocity=5.0, ...)``.
+
+* Refactored :meth:`~isaaclab.sim.schemas.modify_rigid_body_properties` and
+  :meth:`~isaaclab.sim.schemas.modify_joint_drive_properties` to use class-level
+  metadata (``_usd_applied_schema``, ``_usd_namespace``) from the cfg for writing
+  solver-specific attributes, eliminating backend-specific branching.
+
+
 4.6.1 (2026-04-14)
 ~~~~~~~~~~~~~~~~~~
 

source/isaaclab/isaaclab/sim/__init__.pyi

@@ -46,6 +46,8 @@ __all__ = [
     "JointDrivePropertiesCfg",
     "MassPropertiesCfg",
     "MeshCollisionPropertiesCfg",
+    "PhysxJointDrivePropertiesCfg",
+    "PhysxRigidBodyPropertiesCfg",
     "RigidBodyPropertiesCfg",
     "SDFMeshPropertiesCfg",
     "SpatialTendonPropertiesCfg",
@@ -210,6 +212,8 @@ from .schemas import (
     JointDrivePropertiesCfg,
     MassPropertiesCfg,
     MeshCollisionPropertiesCfg,
+    PhysxJointDrivePropertiesCfg,
+    PhysxRigidBodyPropertiesCfg,
     RigidBodyPropertiesCfg,
     SDFMeshPropertiesCfg,
     SpatialTendonPropertiesCfg,

source/isaaclab/isaaclab/sim/schemas/__init__.pyi

@@ -34,6 +34,8 @@ __all__ = [
     "JointDrivePropertiesCfg",
     "MassPropertiesCfg",
     "MeshCollisionPropertiesCfg",
+    "PhysxJointDrivePropertiesCfg",
+    "PhysxRigidBodyPropertiesCfg",
     "RigidBodyPropertiesCfg",
     "SDFMeshPropertiesCfg",
     "SpatialTendonPropertiesCfg",
@@ -74,6 +76,8 @@ from .schemas_cfg import (
     JointDrivePropertiesCfg,
     MassPropertiesCfg,
     MeshCollisionPropertiesCfg,
+    PhysxJointDrivePropertiesCfg,
+    PhysxRigidBodyPropertiesCfg,
     RigidBodyPropertiesCfg,
     SDFMeshPropertiesCfg,
     SpatialTendonPropertiesCfg,

source/isaaclab/isaaclab/sim/schemas/schemas.py

@@ -280,14 +280,16 @@ def define_rigid_body_properties(
 def modify_rigid_body_properties(
     prim_path: str, cfg: schemas_cfg.RigidBodyPropertiesCfg, stage: Usd.Stage | None = None
 ) -> bool:
-    """Modify PhysX parameters for a rigid body prim.
+    """Modify parameters for a rigid body prim.
 
-    A `rigid body`_ is a single body that can be simulated by PhysX. It can be either dynamic or kinematic.
-    A dynamic body responds to forces and collisions. A `kinematic body`_ can be moved by the user, but does not
-    respond to forces. They are similar to having static bodies that can be moved around.
+    A `rigid body`_ is a single body that can be simulated by a physics engine. It can be either dynamic
+    or kinematic. A dynamic body responds to forces and collisions. A `kinematic body`_ can be moved by
+    the user, but does not respond to forces. They are similar to having static bodies that can be moved
+    around.
 
-    The schema comprises of attributes that belong to the `RigidBodyAPI`_ and `PhysxRigidBodyAPI`_.
-    schemas. The latter contains the PhysX parameters for the rigid body.
+    The function handles solver-common properties from :class:`~schemas_cfg.RigidBodyPropertiesCfg`
+    (written via the `RigidBodyAPI`_) and, when the cfg is a :class:`~schemas_cfg.PhysxRigidBodyPropertiesCfg`,
+    also sets PhysX-specific properties (written via the `PhysxRigidBodyAPI`_).
 
     .. note::
         This function is decorated with :func:`apply_nested` that sets the properties to all the prims
@@ -300,7 +302,9 @@ def modify_rigid_body_properties(
 
     Args:
         prim_path: The prim path to the rigid body.
-        cfg: The configuration for the rigid body.
+        cfg: The configuration for the rigid body. Can be
+            :class:`~schemas_cfg.RigidBodyPropertiesCfg` for solver-common properties or
+            :class:`~schemas_cfg.PhysxRigidBodyPropertiesCfg` for PhysX-specific properties.
         stage: The stage where to find the prim. Defaults to None, in which case the
             current stage is used.
 
@@ -318,21 +322,26 @@ def modify_rigid_body_properties(
         return False
     # retrieve the USD rigid-body api
     usd_rigid_body_api = UsdPhysics.RigidBodyAPI(rigid_body_prim)
-    # ensure PhysX rigid body API is applied
-    applied_schemas = rigid_body_prim.GetAppliedSchemas()
-    if "PhysxRigidBodyAPI" not in applied_schemas:
-        rigid_body_prim.AddAppliedSchema("PhysxRigidBodyAPI")
 
-    # convert to dict
-    cfg = cfg.to_dict()
-    # set into USD API
+    # read solver-specific metadata from the cfg instance
+    namespace = getattr(cfg, "_usd_namespace", None)
+    applied_schema = getattr(cfg, "_usd_applied_schema", None)
+
+    # convert to dict, filtering out class metadata (underscore-prefixed keys)
+    cfg_dict = {k: v for k, v in cfg.to_dict().items() if not k.startswith("_")}
+
+    # set into USD API (solver-common properties)
     for attr_name in ["rigid_body_enabled", "kinematic_enabled"]:
-        value = cfg.pop(attr_name, None)
+        value = cfg_dict.pop(attr_name, None)
         safe_set_attribute_on_usd_schema(usd_rigid_body_api, attr_name, value, camel_case=True)
-    # set into PhysX API (prim attributes under physxRigidBody:*)
-    for attr_name, value in cfg.items():
+
+    # set solver-specific properties using class metadata (namespace + applied schema)
+    if applied_schema:
+        if applied_schema not in rigid_body_prim.GetAppliedSchemas():
+            rigid_body_prim.AddAppliedSchema(applied_schema)
+    for attr_name, value in cfg_dict.items():
         safe_set_attribute_on_usd_prim(
-            rigid_body_prim, f"physxRigidBody:{to_camel_case(attr_name, 'cC')}", value, camel_case=False
+            rigid_body_prim, f"{namespace}:{to_camel_case(attr_name, 'cC')}", value, camel_case=False
         )
     # success
     return True
@@ -615,15 +624,16 @@ def activate_contact_sensors(prim_path: str, threshold: float = 0.0, stage: Usd.
 def modify_joint_drive_properties(
     prim_path: str, cfg: schemas_cfg.JointDrivePropertiesCfg, stage: Usd.Stage | None = None
 ) -> bool:
-    """Modify PhysX parameters for a joint prim.
+    """Modify parameters for a joint prim.
 
     This function checks if the input prim is a prismatic or revolute joint and applies the joint drive schema
     on it. If the joint is a tendon (i.e., it has the `PhysxTendonAxisAPI`_ schema applied on it), then the joint
     drive schema is not applied.
 
-    Based on the configuration, this method modifies the properties of the joint drive. These properties are
-    based on the `UsdPhysics.DriveAPI`_ schema. For more information on the properties, please refer to the
-    official documentation.
+    The function handles solver-common properties from :class:`~schemas_cfg.JointDrivePropertiesCfg`
+    (written via the `UsdPhysics.DriveAPI`_) and, when the cfg is a
+    :class:`~schemas_cfg.PhysxJointDrivePropertiesCfg`, also sets PhysX-specific properties
+    (written via the `PhysxJointAPI`_).
 
     .. caution::
 
@@ -633,10 +643,13 @@ def modify_joint_drive_properties(
 
     .. _UsdPhysics.DriveAPI: https://openusd.org/dev/api/class_usd_physics_drive_a_p_i.html
     .. _PhysxTendonAxisAPI: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/104.2/class_physx_schema_physx_tendon_axis_a_p_i.html
+    .. _PhysxJointAPI: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/104.2/class_physx_schema_physx_joint_a_p_i.html
 
     Args:
         prim_path: The prim path where to apply the joint drive schema.
-        cfg: The configuration for the joint drive.
+        cfg: The configuration for the joint drive. Can be
+            :class:`~schemas_cfg.JointDrivePropertiesCfg` for solver-common properties or
+            :class:`~schemas_cfg.PhysxJointDrivePropertiesCfg` for PhysX-specific properties.
         stage: The stage where to find the prim. Defaults to None, in which case the
             current stage is used.
 
@@ -672,52 +685,55 @@ def modify_joint_drive_properties(
     usd_drive_api = UsdPhysics.DriveAPI(prim, drive_api_name)
     if not usd_drive_api:
         usd_drive_api = UsdPhysics.DriveAPI.Apply(prim, drive_api_name)
-    # ensure PhysX joint API is applied
-    if "PhysxJointAPI" not in applied_schemas_str:
-        prim.AddAppliedSchema("PhysxJointAPI")
 
-    # mapping from configuration name to USD attribute name
+    # read solver-specific metadata from the cfg instance
+    namespace = getattr(cfg, "_usd_namespace", None)
+    applied_schema = getattr(cfg, "_usd_applied_schema", None)
+    attr_name_map = getattr(cfg, "_usd_attr_name_map", {})
+
+    # mapping from configuration name to USD attribute name (for solver-common fields)
     cfg_to_usd_map = {
-        "max_velocity": "max_joint_velocity",
         "max_effort": "max_force",
         "drive_type": "type",
     }
-    # convert to dict
-    cfg = cfg.to_dict()
+    # convert to dict, filtering out class metadata (underscore-prefixed keys)
+    cfg_dict = {k: v for k, v in cfg.to_dict().items() if not k.startswith("_")}
 
     # ensure_drives_exist: if both stiffness and damping are zero on the authored drive,
     # set a minimal stiffness so that backends like Newton recognise the drive as active.
-    ensure_drives = cfg.pop("ensure_drives_exist", False)
-    if ensure_drives and cfg["stiffness"] is None and cfg["damping"] is None:
+    ensure_drives = cfg_dict.pop("ensure_drives_exist", False)
+    if ensure_drives and cfg_dict["stiffness"] is None and cfg_dict["damping"] is None:
         # read the current values from the drive
         cur_stiffness = usd_drive_api.GetStiffnessAttr().Get()
         cur_damping = usd_drive_api.GetDampingAttr().Get()
         if (cur_stiffness is None or cur_stiffness == 0.0) and (cur_damping is None or cur_damping == 0.0):
-            cfg["stiffness"] = 1e-3
+            cfg_dict["stiffness"] = 1e-3
 
     # check if linear drive
     is_linear_drive = prim.IsA(UsdPhysics.PrismaticJoint)
     # convert values for angular drives from radians to degrees units
     if not is_linear_drive:
-        if cfg["max_velocity"] is not None:
+        if cfg_dict.get("max_velocity") is not None:
             # rad / s --> deg / s
-            cfg["max_velocity"] = cfg["max_velocity"] * 180.0 / math.pi
-        if cfg["stiffness"] is not None:
+            cfg_dict["max_velocity"] = cfg_dict["max_velocity"] * 180.0 / math.pi
+        if cfg_dict["stiffness"] is not None:
             # N-m/rad --> N-m/deg
-            cfg["stiffness"] = cfg["stiffness"] * math.pi / 180.0
-        if cfg["damping"] is not None:
+            cfg_dict["stiffness"] = cfg_dict["stiffness"] * math.pi / 180.0
+        if cfg_dict["damping"] is not None:
             # N-m-s/rad --> N-m-s/deg
-            cfg["damping"] = cfg["damping"] * math.pi / 180.0
-
-    # set into PhysX API (prim attributes under physxJoint:*)
-    for attr_name in ["max_velocity"]:
-        value = cfg.pop(attr_name, None)
-        usd_attr_name = cfg_to_usd_map[attr_name]
-        safe_set_attribute_on_usd_prim(
-            prim, f"physxJoint:{to_camel_case(usd_attr_name, 'cC')}", value, camel_case=False
-        )
-    # set into USD API
-    for attr_name, attr_value in cfg.items():
+            cfg_dict["damping"] = cfg_dict["damping"] * math.pi / 180.0
+
+    # set solver-specific properties using class metadata (namespace + applied schema + attr name map)
+    if applied_schema:
+        if applied_schema not in applied_schemas_str:
+            prim.AddAppliedSchema(applied_schema)
+    for attr_name in list(attr_name_map):
+        value = cfg_dict.pop(attr_name, None)
+        usd_attr_name = attr_name_map[attr_name]
+        safe_set_attribute_on_usd_prim(prim, f"{namespace}:{usd_attr_name}", value, camel_case=False)
+
+    # set into USD API (solver-common properties)
+    for attr_name, attr_value in cfg_dict.items():
         attr_name = cfg_to_usd_map.get(attr_name, attr_name)
         safe_set_attribute_on_usd_schema(usd_drive_api, attr_name, attr_value, camel_case=True)
 

source/isaaclab/isaaclab/sim/schemas/schemas_cfg.py

@@ -55,13 +55,18 @@ class ArticulationRootPropertiesCfg:
 
 @configclass
 class RigidBodyPropertiesCfg:
-    """Properties to apply to a rigid body.
+    """Solver-common properties to apply to a rigid body.
+
+    Contains only properties from the `UsdPhysics.RigidBodyAPI`_ that are common across all
+    simulation backends. For PhysX-specific properties, use :class:`PhysxRigidBodyPropertiesCfg`.
 
     See :meth:`modify_rigid_body_properties` for more information.
 
     .. note::
         If the values are None, they are not modified. This is useful when you want to set only a subset of
         the properties and leave the rest as-is.
+
+    .. _UsdPhysics.RigidBodyAPI: https://openusd.org/dev/api/class_usd_physics_rigid_body_a_p_i.html
     """
 
     rigid_body_enabled: bool | None = None
@@ -76,6 +81,28 @@ class RigidBodyPropertiesCfg:
     For more information on kinematic bodies, please refer to the `documentation <https://openusd.org/release/wp_rigid_body_physics.html#kinematic-bodies>`_.
     """
 
+
+@configclass
+class PhysxRigidBodyPropertiesCfg(RigidBodyPropertiesCfg):
+    """PhysX-specific rigid body properties.
+
+    Extends :class:`RigidBodyPropertiesCfg` with properties from the `PhysxRigidBodyAPI`_ schema.
+
+    See :meth:`modify_rigid_body_properties` for more information.
+
+    .. note::
+        If the values are None, they are not modified. This is useful when you want to set only a subset of
+        the properties and leave the rest as-is.
+
+    .. _PhysxRigidBodyAPI: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/104.2/class_physx_schema_physx_rigid_body_a_p_i.html
+    """
+
+    # -- Class metadata (not dataclass fields) --
+    # USD schema to apply on the prim before writing solver-specific attributes.
+    _usd_applied_schema = "PhysxRigidBodyAPI"
+    # Prim attribute namespace for solver-specific fields.
+    _usd_namespace = "physxRigidBody"
+
     disable_gravity: bool | None = None
     """Disable gravity for the actor."""
 
@@ -185,13 +212,18 @@ class MassPropertiesCfg:
 
 @configclass
 class JointDrivePropertiesCfg:
-    """Properties to define the drive mechanism of a joint.
+    """Solver-common properties to define the drive mechanism of a joint.
+
+    Contains only properties from the `UsdPhysics.DriveAPI`_ that are common across all
+    simulation backends. For PhysX-specific properties, use :class:`PhysxJointDrivePropertiesCfg`.
 
     See :meth:`modify_joint_drive_properties` for more information.
 
     .. note::
         If the values are None, they are not modified. This is useful when you want to set only a subset of
         the properties and leave the rest as-is.
+
+    .. _UsdPhysics.DriveAPI: https://openusd.org/dev/api/class_usd_physics_drive_a_p_i.html
     """
 
     drive_type: Literal["force", "acceleration"] | None = None
@@ -204,15 +236,6 @@ class JointDrivePropertiesCfg:
     max_effort: float | None = None
     """Maximum effort that can be applied to the joint (in kg-m^2/s^2)."""
 
-    max_velocity: float | None = None
-    """Maximum velocity of the joint.
-
-    The unit depends on the joint model:
-
-    * For linear joints, the unit is m/s.
-    * For angular joints, the unit is rad/s.
-    """
-
     stiffness: float | None = None
     """Stiffness of the joint drive.
 
@@ -244,6 +267,39 @@ class JointDrivePropertiesCfg:
     """
 
 
+@configclass
+class PhysxJointDrivePropertiesCfg(JointDrivePropertiesCfg):
+    """PhysX-specific joint drive properties.
+
+    Extends :class:`JointDrivePropertiesCfg` with properties from the `PhysxJointAPI`_ schema.
+
+    See :meth:`modify_joint_drive_properties` for more information.
+
+    .. note::
+        If the values are None, they are not modified. This is useful when you want to set only a subset of
+        the properties and leave the rest as-is.
+
+    .. _PhysxJointAPI: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/104.2/class_physx_schema_physx_joint_a_p_i.html
+    """
+
+    # -- Class metadata (not dataclass fields) --
+    # USD schema to apply on the prim before writing solver-specific attributes.
+    _usd_applied_schema = "PhysxJointAPI"
+    # Prim attribute namespace for solver-specific fields.
+    _usd_namespace = "physxJoint"
+    # Mapping from cfg field names to USD attribute names (already in camelCase).
+    _usd_attr_name_map = {"max_velocity": "maxJointVelocity"}
+
+    max_velocity: float | None = None
+    """Maximum velocity of the joint.
+
+    The unit depends on the joint model:
+
+    * For linear joints, the unit is m/s.
+    * For angular joints, the unit is rad/s.
+    """
+
+
 @configclass
 class FixedTendonPropertiesCfg:
     """Properties to define fixed tendons of an articulation.