Physics Schemas

A robot model needs more than geometry to simulate. Its links need mass, its shapes need collision properties, and its joints need physical constraints. USD stores these properties in schemas: named groups of attributes attached to objects in the scene. An object in a USD scene is called a prim; a robot link, collision mesh, or joint can each be a prim.

Isaac Lab’s schema configurations let you set these properties from Python when an asset is spawned. Use them to tune an existing asset or give a new shape its physical properties, without editing the source USD file by hand. An imported asset may already contain everything you need; override only the properties you want to change.

These are asset settings. Choose the simulation backend and its scene-wide solver settings separately through backends_and_presets.

What is a fragment?

A schema fragment is a small Python configuration object that sets properties from one USD schema or attribute namespace. For example, MassCfg(mass=0.5) sets a mass property, while UsdPhysicsCollisionCfg(collision_enabled=True) sets a collision property.

It is called a fragment because it describes just one part of an asset’s physics configuration. Combine fragments to describe the properties you need, then pass them to the appropriate spawner fields. A fragment is configuration data, not a separate USD file or a piece of geometry.

The distinction is:

• The schema defines the available properties and how they are stored in USD.
• The fragment supplies the values you want to set from Python.
• The spawner applies those values to the asset’s prims when it creates the asset.

Give an object physical properties

This configuration creates a small box with a mass of 0.5 kg and enabled collisions:

import isaaclab.sim as sim_utils
from isaaclab.sim.schemas import MassCfg, UsdPhysicsCollisionCfg, UsdPhysicsRigidBodyCfg
cuboid = sim_utils.CuboidCfg(
    size=(0.1, 0.1, 0.1),
    rigid_props=UsdPhysicsRigidBodyCfg(),
    mass_props=MassCfg(mass=0.5),
    collision_props=UsdPhysicsCollisionCfg(collision_enabled=True),
)

Pass this configuration to an asset’s spawn field, such as RigidObjectCfg(spawn=cuboid, ...). The spawner creates the geometry and applies the schema configurations; the physics backend then reads the resulting properties.

Each spawner field controls a different part of the asset:

For joints controlled by Isaac Lab actuators, also read actuators: actuator configuration can override drive settings after spawning.

A field set to None leaves the existing attribute unchanged. An empty fragment, such as UsdPhysicsRigidBodyCfg(), still requests the corresponding schema; it does not replace every attribute with a Python default.

Add backend-specific settings

A spawner field can accept a list of fragments for the same property family. Use a list to combine shared USD properties with settings for a particular backend:

import isaaclab.sim as sim_utils
from isaaclab.sim.schemas import MassCfg, UsdPhysicsCollisionCfg, UsdPhysicsRigidBodyCfg
from isaaclab_newton.sim.schemas import NewtonCollisionCfg
cuboid = sim_utils.CuboidCfg(
    size=(0.1, 0.1, 0.1),
    rigid_props=UsdPhysicsRigidBodyCfg(),
    mass_props=MassCfg(mass=0.5),
    collision_props=[UsdPhysicsCollisionCfg(collision_enabled=True), NewtonCollisionCfg(contact_margin=0.001)],
)

Here, UsdPhysicsCollisionCfg enables collisions and NewtonCollisionCfg sets a Newton contact margin of 1 mm. They describe the same collision shape, so they belong together in collision_props.

Import shared fragments from isaaclab.sim.schemas, PhysX fragments from isaaclab_physx.sim.schemas, and Newton or MuJoCo fragments from isaaclab_newton.sim.schemas. Material fragments live in the corresponding sim.spawners.materials modules.

You can store settings for several backends on one asset. This does not activate those backends or make their parameters interchangeable: a solver must support a property for it to affect the simulation. For example, MuJoCo gravity compensation settings apply to Newton’s MuJoCo solver, not to PhysX.

Configure an existing robot

UsdFileCfg accepts the same property fields. Pass a fragment or list directly to update existing matching bodies, collisions, or joints throughout the imported asset. Use a dictionary when different parts need different settings:

import isaaclab.sim as sim_utils
from isaaclab.sim.schemas import UsdPhysicsDriveCfg, UsdPhysicsRigidBodyCfg
from isaaclab_newton.sim.schemas import MujocoRigidBodyCfg
from isaaclab_physx.sim.schemas import PhysxRigidBodyCfg
from isaaclab.utils.assets import ISAAC_NUCLEUS_DIR
spawn = sim_utils.UsdFileCfg(
    usd_path=f"{ISAAC_NUCLEUS_DIR}/Robots/Franka/franka_instanceable.usd",
    rigid_props={
        # every rigid body: universal + PhysX + MuJoCo attributes side by side
        "/.*": [
            UsdPhysicsRigidBodyCfg(rigid_body_enabled=True),
            PhysxRigidBodyCfg(max_depenetration_velocity=5.0),
            MujocoRigidBodyCfg(gravcomp=1.0),
        ],
        # hand links (and their subtrees) get a tighter depenetration limit
        "/.*_hand(/.*)?": [PhysxRigidBodyCfg(max_depenetration_velocity=1.0)],
    },
    joint_drive_props={
        "/.*": [UsdPhysicsDriveCfg(drive_type="force", stiffness=40.0, damping=4.0)],
    },
)

Dictionary keys are regular-expression suffixes appended to the spawn prim’s path. For example, if the robot is spawned at /World/Robot, "/.*" searches beneath /World/Robot. Rules apply in order, so a later rule can override an earlier one. In this example, the hand subtree receives a smaller PhysX depenetration limit.

For USD, URDF, and MJCF imports, the anchor is the spawn prim. Shape and mesh spawners use the geometry prim for collisions and the container prim for rigid-body and mass properties. Deformable settings use the spawn prim for every spawner type.

The search includes inactive and undefined prims as well as instance proxies. Patterns select candidate prims; the property family then filters them. For example, rigid-body settings apply to rigid bodies, and joint-drive settings apply to revolute or prismatic joints. A broad pattern does not normally turn every mesh into a body.

When a setting does not apply

First check that the selected backend supports the property and that the pattern matches the intended prim. Matching uses the whole path: .* can cross / boundaries, while [^/]+ matches just one path segment.

Most fragment writers modify prims that already have the relevant USD API, meaning the schema that identifies them as a body, collision shape, or other physics object. For mass, articulation, and joint-drive settings, the spawner flags mass_props_create_if_missing, articulation_props_create_if_missing, and joint_drive_props_create_if_missing can create missing APIs on matched targets.

Shape and mesh spawners create the APIs needed by their new geometry. With a bare fragment or list, file spawners search for existing schema carriers; if none exist for the family, they apply it at the spawn prim, treating the asset as a single body. Explicit dictionaries give you control over the target selection.

The writers warn when no valid targets are found or when a target is an instance proxy that cannot be edited. An empty fragment list makes no changes. Joint-drive patterns silently skip non-joint prims, since a subtree can contain both joints and meshes.

Gravity compensation with MuJoCo

Set body-level gravcomp to compute gravity compensation. Set joint-level actuatorgravcomp to route that force through the actuator channel, where actuator force limits apply; otherwise it goes through the passive-force channel.

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

gravcomp=1.0 provides full compensation. The joint fragment also enables full compensation on its child body if that body’s value is unset or zero; an existing nonzero value is kept. To disable compensation, turn off actuatorgravcomp as well as setting the body’s gravcomp to zero.

The older MujocoJointDrivePropertiesCfg also auto-enables body compensation when requested, unless an explicit body gravcomp value is supplied. Prefer the fragment example above for new configurations.

Deformable bodies

Choose volume_deformable_props for a solid deformable or surface_deformable_props for a cloth-like surface. Set only one of these fields on a spawner. Both accept OmniPhysicsDeformableBodyCfg for shared properties such as mass and kinematic behavior; PhysX also provides tuning fragments.

Unlike most rigid-body writers, deformable writers create the deformable setup if it is missing. Set deformable mass with OmniPhysicsDeformableBodyCfg.mass; UsdPhysics.MassAPI does not control it.

This example creates a volume deformable with PhysX tuning, a collision offset on its simulation mesh, and material settings for both PhysX and Newton:

import isaaclab.sim as sim_utils
from isaaclab_physx.sim.schemas import PhysxCollisionCfg, PhysxDeformableBodyCfg
from isaaclab.sim.spawners.materials import OmniPhysicsDeformableMaterialCfg
from isaaclab_newton.sim.spawners.materials import NewtonVolumeDeformableMaterialCfg
sim_utils.MeshCuboidCfg(
    size=(0.2, 0.2, 0.2),
    volume_deformable_props=[
        sim_utils.schemas.OmniPhysicsDeformableBodyCfg(mass=0.5),
        PhysxDeformableBodyCfg(solver_position_iteration_count=32),
    ],
    collision_props={"/sim_mesh": [PhysxCollisionCfg(contact_offset=0.01)]},
    physics_material=[
        OmniPhysicsDeformableMaterialCfg(youngs_modulus=1.0e6, poissons_ratio=0.45),
        NewtonVolumeDeformableMaterialCfg(k_mu=1.0e5),
    ],
)

The simulation mesh is a child named sim_mesh by default. Target it through collision_props to set collision offsets. Deformable and simulation-mesh collision patterns are relative to the spawn prim.

physics_material accepts deformable material fragments and lists that mix rigid and deformable material settings. Each fragment applies its own material schema; a material used only by deformables does not need the rigid-body material API.

Using the property configuration classes

You will also see classes such as RigidBodyBaseCfg and PhysxRigidBodyPropertiesCfg in existing tasks. These combine a property group’s shared and backend-specific fields in one object. They are deprecated compatibility classes. Existing configurations still work in the same spawner fields, but use fragments for new code. Pass a compatibility object directly, rather than placing it in a fragment list.

• Base classes in isaaclab.sim.schemas contain shared fields and do not import a backend package.
• PhysX subclasses add fields such as damping and solver iterations.
• Newton subclasses add Newton settings; MuJoCo subclasses add solver-specific fields such as gravity compensation.

When updating an existing task, split its compatibility object into fragments for the shared and backend-specific fields. See the fragment migration examples for examples.

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,
    ),
)

This example writes both PhysX and MuJoCo settings into the asset. Each backend uses the fields it supports. For a full list of classes and fields, expand the reference sections below.

Schema reference and implementation

The sections below explain how configuration fields become USD attributes. You do not need these details for the examples above.

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

from isaaclab_physx.sim.schemas import PhysxTendonAxisCfg, PhysxTendonAxisRootCfg
fixed_tendons_props = {
    "/joints/index_root": [
        PhysxTendonAxisRootCfg(instance_names="index_finger", stiffness=10.0),
        PhysxTendonAxisCfg(instance_names="index_finger", gearing=[1.0], joint_axis=["rotX"]),
    ],
    "/joints/index_distal": [
        PhysxTendonAxisCfg(instance_names="index_finger", gearing=[-0.5], joint_axis=["rotX"]),
    ],
}

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
)

Where to go next

• /source/how-to/write_articulation_cfg — configure a complete robot asset.
• actuators — understand how actuators resolve joint drive properties.
• | set_joint_velocity_target | actuators.target_command.set_velocity_index | — migrate older schema configurations to 3.0.
• /source/api/lab/isaaclab.sim.schemas — shared configurations and writers.
• /source/api/lab_physx/isaaclab_physx.sim.schemas — PhysX configurations.
• /source/api/lab_newton/isaaclab_newton.sim.schemas — Newton and MuJoCo configurations.