Add MuJoCo gravity compensation schema classes

Add MujocoRigidBodyPropertiesCfg with gravity_compensation_scale
(body-level, written to mjc:gravcomp) and MujocoJointDrivePropertiesCfg
with gravity_compensation (joint-level, written to mjc:actuatorgravcomp)
for the Newton/MuJoCo simulation backend.

Both classes use the _usd_namespace and _usd_attr_name_map metadata so
the modify functions handle them generically with no backend-specific
branching.

Also extends modify_rigid_body_properties to support _usd_attr_name_map,
matching the joint drive path, for backends with non-camelCase attribute
names.

Author: vidurv-nvidia

source/isaaclab/config/extension.toml

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

source/isaaclab/docs/CHANGELOG.rst

@@ -1,6 +1,27 @@
 Changelog
 ---------
 
+4.6.3 (2026-04-14)
+~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added :class:`~isaaclab.sim.schemas.MujocoRigidBodyPropertiesCfg` with
+  ``gravity_compensation_scale`` for body-level gravity compensation in the
+  Newton (MuJoCo) backend.
+* Added :class:`~isaaclab.sim.schemas.MujocoJointDrivePropertiesCfg` with
+  ``gravity_compensation`` for joint-level gravity compensation in the
+  Newton (MuJoCo) backend.
+
+Changed
+^^^^^^^
+
+* Extended :meth:`~isaaclab.sim.schemas.modify_rigid_body_properties` to support
+  ``_usd_attr_name_map`` metadata, matching the joint drive path. This enables
+  solver backends with non-camelCase attribute names (e.g. MuJoCo ``mjc:gravcomp``).
+
+
 4.6.2 (2026-04-14)
 ~~~~~~~~~~~~~~~~~~~
 

source/isaaclab/isaaclab/sim/__init__.pyi

@@ -46,6 +46,8 @@ __all__ = [
     "JointDrivePropertiesCfg",
     "MassPropertiesCfg",
     "MeshCollisionPropertiesCfg",
+    "MujocoJointDrivePropertiesCfg",
+    "MujocoRigidBodyPropertiesCfg",
     "PhysxJointDrivePropertiesCfg",
     "PhysxRigidBodyPropertiesCfg",
     "RigidBodyPropertiesCfg",
@@ -212,6 +214,8 @@ from .schemas import (
     JointDrivePropertiesCfg,
     MassPropertiesCfg,
     MeshCollisionPropertiesCfg,
+    MujocoJointDrivePropertiesCfg,
+    MujocoRigidBodyPropertiesCfg,
     PhysxJointDrivePropertiesCfg,
     PhysxRigidBodyPropertiesCfg,
     RigidBodyPropertiesCfg,

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

@@ -34,6 +34,8 @@ __all__ = [
     "JointDrivePropertiesCfg",
     "MassPropertiesCfg",
     "MeshCollisionPropertiesCfg",
+    "MujocoJointDrivePropertiesCfg",
+    "MujocoRigidBodyPropertiesCfg",
     "PhysxJointDrivePropertiesCfg",
     "PhysxRigidBodyPropertiesCfg",
     "RigidBodyPropertiesCfg",
@@ -76,6 +78,8 @@ from .schemas_cfg import (
     JointDrivePropertiesCfg,
     MassPropertiesCfg,
     MeshCollisionPropertiesCfg,
+    MujocoJointDrivePropertiesCfg,
+    MujocoRigidBodyPropertiesCfg,
     PhysxJointDrivePropertiesCfg,
     PhysxRigidBodyPropertiesCfg,
     RigidBodyPropertiesCfg,

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

@@ -326,6 +326,7 @@ def modify_rigid_body_properties(
     # 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", {})
 
     # 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("_")}
@@ -335,14 +336,13 @@ def modify_rigid_body_properties(
         value = cfg_dict.pop(attr_name, None)
         safe_set_attribute_on_usd_schema(usd_rigid_body_api, attr_name, value, camel_case=True)
 
-    # set solver-specific properties using class metadata (namespace + applied schema)
+    # set solver-specific properties using class metadata (namespace + applied schema + attr name map)
     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"{namespace}:{to_camel_case(attr_name, 'cC')}", value, camel_case=False
-        )
+        usd_attr_name = attr_name_map.get(attr_name, to_camel_case(attr_name, "cC"))
+        safe_set_attribute_on_usd_prim(rigid_body_prim, f"{namespace}:{usd_attr_name}", value, camel_case=False)
     # success
     return True
 

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

@@ -143,6 +143,34 @@ class PhysxRigidBodyPropertiesCfg(RigidBodyPropertiesCfg):
     """The mass-normalized kinetic energy threshold below which an actor may participate in stabilization."""
 
 
+@configclass
+class MujocoRigidBodyPropertiesCfg(RigidBodyPropertiesCfg):
+    """MuJoCo-specific rigid body properties.
+
+    Extends :class:`RigidBodyPropertiesCfg` with properties that are only supported by the
+    Newton (MuJoCo) simulation backend.
+
+    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.
+    """
+
+    # -- Class metadata (not dataclass fields) --
+    # Prim attribute namespace for solver-specific fields.
+    _usd_namespace = "mjc"
+    # Mapping from cfg field names to USD attribute names.
+    _usd_attr_name_map = {"gravity_compensation_scale": "gravcomp"}
+
+    gravity_compensation_scale: float | None = None
+    """Scale factor for gravity compensation for the body [dimensionless]. Defaults to None
+    (attribute not written to USD).
+
+    In MuJoCo, ``0.0`` means no compensation and ``1.0`` means full compensation.
+    """
+
+
 @configclass
 class CollisionPropertiesCfg:
     """Properties to apply to colliders in a rigid body.
@@ -300,6 +328,32 @@ class PhysxJointDrivePropertiesCfg(JointDrivePropertiesCfg):
     """
 
 
+@configclass
+class MujocoJointDrivePropertiesCfg(JointDrivePropertiesCfg):
+    """MuJoCo-specific joint drive properties.
+
+    Extends :class:`JointDrivePropertiesCfg` with properties that are only supported by the
+    Newton (MuJoCo) simulation backend.
+
+    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.
+    """
+
+    # -- Class metadata (not dataclass fields) --
+    # Prim attribute namespace for solver-specific fields.
+    _usd_namespace = "mjc"
+    # Mapping from cfg field names to USD attribute names.
+    _usd_attr_name_map = {"gravity_compensation": "actuatorgravcomp"}
+
+    gravity_compensation: bool | None = None
+    """Whether to enable gravity compensation on the joint. Defaults to None
+    (attribute not written to USD).
+    """
+
+
 @configclass
 class FixedTendonPropertiesCfg:
     """Properties to define fixed tendons of an articulation.

source/isaaclab/test/sim/test_schemas.py

@@ -271,6 +271,76 @@ def test_multi_instance_schema_detection_on_tendon_joints(setup_simulation):
     assert result is False, "Prim without tendon root schema should return False"
 
 
+@pytest.mark.isaacsim_ci
+def test_mujoco_gravity_compensation_scale_on_rigid_body(setup_simulation):
+    """Test that gravity_compensation_scale is written as mjc:gravcomp on rigid body prims."""
+    sim, _, _, _, _, _ = setup_simulation
+    stage = sim_utils.get_current_stage()
+
+    sim_utils.create_prim("/World/cube", prim_type="Cube", translation=(0.0, 0.0, 0.62))
+    rigid_cfg = schemas.MujocoRigidBodyPropertiesCfg(gravity_compensation_scale=0.5)
+    schemas.define_rigid_body_properties("/World/cube", rigid_cfg)
+
+    prim = stage.GetPrimAtPath("/World/cube")
+    attr = prim.GetAttribute("mjc:gravcomp")
+    assert attr.IsValid(), "mjc:gravcomp attribute not found on rigid body prim"
+    assert attr.Get() == pytest.approx(0.5)
+
+
+@pytest.mark.isaacsim_ci
+def test_mujoco_gravity_compensation_scale_not_set_when_none(setup_simulation):
+    """Test that mjc:gravcomp is not written when gravity_compensation_scale is None."""
+    sim, _, _, _, _, _ = setup_simulation
+    stage = sim_utils.get_current_stage()
+
+    sim_utils.create_prim("/World/cube2", prim_type="Cube", translation=(1.0, 0.0, 0.62))
+    rigid_cfg = schemas.MujocoRigidBodyPropertiesCfg()
+    schemas.define_rigid_body_properties("/World/cube2", rigid_cfg)
+
+    prim = stage.GetPrimAtPath("/World/cube2")
+    attr = prim.GetAttribute("mjc:gravcomp")
+    assert not attr.IsValid(), "mjc:gravcomp should not be set when gravity_compensation_scale is None"
+
+
+@pytest.mark.isaacsim_ci
+def test_mujoco_joint_gravity_compensation_written(setup_simulation):
+    """Test that gravity_compensation is written as mjc:actuatorgravcomp on joint prims."""
+    sim, _, _, _, _, _ = setup_simulation
+    stage = sim_utils.get_current_stage()
+
+    sim_utils.create_prim("/World/jgc_test", prim_type="Xform")
+    sim_utils.create_prim("/World/jgc_test/body0", prim_type="Cube")
+    sim_utils.create_prim("/World/jgc_test/body1", prim_type="Cube")
+    UsdPhysics.RevoluteJoint.Define(stage, "/World/jgc_test/body1/joint0")
+
+    joint_cfg = schemas.MujocoJointDrivePropertiesCfg(gravity_compensation=True)
+    schemas.modify_joint_drive_properties("/World/jgc_test", joint_cfg)
+
+    joint_prim = stage.GetPrimAtPath("/World/jgc_test/body1/joint0")
+    attr = joint_prim.GetAttribute("mjc:actuatorgravcomp")
+    assert attr.IsValid(), "mjc:actuatorgravcomp not set on joint prim"
+    assert attr.Get() is True
+
+
+@pytest.mark.isaacsim_ci
+def test_mujoco_joint_gravity_compensation_not_set_when_none(setup_simulation):
+    """Test that mjc:actuatorgravcomp is not written when gravity_compensation is None."""
+    sim, _, _, _, _, _ = setup_simulation
+    stage = sim_utils.get_current_stage()
+
+    sim_utils.create_prim("/World/jgc_test2", prim_type="Xform")
+    sim_utils.create_prim("/World/jgc_test2/body0", prim_type="Cube")
+    sim_utils.create_prim("/World/jgc_test2/body1", prim_type="Cube")
+    UsdPhysics.RevoluteJoint.Define(stage, "/World/jgc_test2/body1/joint0")
+
+    joint_cfg = schemas.MujocoJointDrivePropertiesCfg()
+    schemas.modify_joint_drive_properties("/World/jgc_test2", joint_cfg)
+
+    joint_prim = stage.GetPrimAtPath("/World/jgc_test2/body1/joint0")
+    attr = joint_prim.GetAttribute("mjc:actuatorgravcomp")
+    assert not attr.IsValid(), "mjc:actuatorgravcomp should not be set when gravity_compensation is None"
+
+
 """
 Helper functions.
 """