Robot setup tips and best practices for Newton#

Tool Reference

Getting a robot asset working correctly under Newton involves three interconnected concerns: importing with the right parameters, authoring physics attributes into the correct USD layer, and selecting the actuator formulation that matches the Newton backend. This page walks through each concern in order, from first launch through migrating an existing PhysX asset.

For the full asset layer hierarchy, see Asset Structure. For the Newton physics backend reference, see Newton Physics Backend.

Launching Isaac Sim with Newton#

Start by launching Isaac Sim with the dedicated Newton application entry point. This activates Newton as the default physics backend and disables PhysX.

Linux

./isaac-sim.newton.sh

Windows

isaac-sim.newton.bat

For programmatic backend switching in standalone scripts, see Newton Physics Backend. Newton does not apply USD property edits while the simulation is playing; stop the simulation before modifying attributes. See Runtime change tracking.

Importing robot assets#

The source format you import from determines how much MuJoCo actuator configuration is preserved automatically.

MJCF assets#

The MJCF importer preserves native MuJoCo parameters — gain type, bias type, gain parameters, and bias parameters — directly in the imported asset. The resulting mujoco.usda layer already contains the actuator configuration needed for Newton, so no manual attribute authoring is required for MJCF sources. Use an MJCF source whenever you need the robot to retain its native MuJoCo actuator behavior.

See the MJCF importer reference for the complete attribute mapping.

URDF assets#

URDF does not carry native MuJoCo actuator parameters. The URDF importer derives compatible USD Physics, PhysX, and MuJoCo attributes during multi-physics conversion, producing physics.usd, physx.usda, and mujoco.usda layers in one pass. For the PhysX variant, use the Gain Tuner Extension to tune stiffness and damping. For the Newton variant, tune the USD Physics drive in the physics variant or set MuJoCo actuator attributes in the mujoco variant manually.

See the URDF importer reference for the complete conversion table.

If your asset was not imported through either importer — for example, it is a hand-authored or legacy PhysX asset — the mujoco.usda layer does not exist yet. In that case, run the Asset Transformer first; see Migrating a PhysX asset to Newton.

Understanding the layer model#

Isaac Sim stores physics attributes in separate layers so each backend sees only the opinions intended for it. Getting Newton attributes into the wrong layer is one of the most common authoring mistakes: the opinion either has no effect (it is overridden by a stronger layer) or it silently corrupts the PhysX variant.

Attribute category	Owner layer	Notes
USD Physics rigid body, joint, and drive definitions	`physics.usd`	Consumed by all backends. Do not duplicate in variant overlays.
PhysX-specific overrides (solver iterations, contact offsets, D6 joints)	`physx.usda`	Strongest sublayer; overrides `physics.usd` opinions in the PhysX variant.
MuJoCo actuator attributes (`mjc:gainType`, `mjc:gainPrm`, etc.)	`mujoco.usda`	Read only when Newton is the active physics backend.
`mjc:armature` and `mjc:frictionloss`	`physics.usd`	Joint-level physical properties shared by both backends. Author them alongside the joint definition, not in the MuJoCo overlay.
`NewtonMimicAPI` (`newton:mimicJoint`, `newton:mimicCoef0/1`)	`mujoco.usda`	Newton-only constraint; not consumed by the PhysX backend.

Knowing which layer to target is only half the problem. Because mujoco.usda is brought into the scene through reference or payload composition arcs, you cannot simply open it and edit it in isolation — it contains only delta opinions (attribute overrides on prims defined elsewhere), so opening it alone shows an empty stage. The next section explains how to set up the stage correctly for authoring.

Setting the edit target#

The correct authoring workflow is to open the full robot asset first, then temporarily add mujoco.usda as a root sublayer so it becomes writable while the full prim hierarchy is visible.

UI workflow

Open the robot interface stage (for example, franka.usd).
In the Layer panel (Window > Layers), click Add Existing Layer (the + button) and select payloads/Physics/mujoco.usda from the asset package. This inserts it as a root sublayer so its opinions are writable from this stage.
Right-click mujoco.usda in the Layer panel and select Set As Edit Target. The layer name turns bold to confirm it is active.
Author your attributes in the Property panel or apply schemas from the Add > Physics menus (see Adding MuJoCo and Newton schemas via the UI).
Right-click mujoco.usda and select Save Layer to write only that layer’s opinions to disk.
Restore the stage to its original composition by doing one of the following:
- Right-click mujoco.usda in the Layer panel and select Remove Layer, then save the interface stage.
- Close and reopen the interface stage without saving it. The sublayer arc is discarded and the stage reloads with the original payload composition.

Warning

Do not save the interface stage while mujoco.usda is still listed as a root sublayer — saving embeds a sublayer arc that conflicts with the existing payload arc and causes duplicate opinions on every subsequent load. Do not author attributes on the session layer either; session layer opinions are lost when the stage is closed or reloaded.

Python workflow

import omni.usd
from pxr import Usd, Sdf

stage = omni.usd.get_context().get_stage()
root_layer = stage.GetRootLayer()

mujoco_path = root_layer.ComputeAbsolutePath("payloads/Physics/mujoco.usda")
mujoco_layer = Sdf.Layer.FindOrOpen(mujoco_path)
if mujoco_layer is None:
    raise RuntimeError(f"Could not open {mujoco_path}. "
                       "Run the Asset Transformer first.")

# Add mujoco.usda as the strongest root sublayer so it is writable.
root_layer.subLayerPaths.insert(0, mujoco_path)
stage.SetEditTarget(Usd.EditTarget(mujoco_layer))

# --- author your attributes here ---

# Save only the mujoco layer, then remove it to restore composition integrity.
mujoco_layer.Save()
root_layer.subLayerPaths.remove(mujoco_path)

With the edit target set correctly, you can apply schemas and set attribute values on the correct layer.

Adding MuJoCo and Newton schemas via the UI#

To apply a MuJoCo schema, select a compatible prim on the stage, then choose Add > Physics > Mujoco and select the API. The menu only shows APIs that support the selected prim type.

To add Newton APIs (such as NewtonMimicAPI or joint properties), right-click the robot link prim and select Add > Physics > Newton, then choose the API you want.

Stage context menu showing Newton APIs available to add on a robot prim

The Mujoco menu filters entries as follows:

Menu entry	Valid selected prim
Scene	`PhysicsScene`
Joint	Any `PhysicsJoint`
Collider	Any `Gprim`
Mesh Collider	`Mesh`
Site	Any `Gprim`
Equality Connect	`PhysicsSphericalJoint`
Equality Weld	`PhysicsFixedJoint`
Equality Joint	`PhysicsRevoluteJoint` or `PhysicsPrismaticJoint`

The generic Edit API Schema dialog does not list MuJoCo or Newton physics schemas. The physics property UI owns these schemas and exposes them through the type-filtered Physics > Mujoco and Physics > Newton menus.

Creating MuJoCo prims#

A few MuJoCo schemas are concrete prim types rather than applied API schemas and must be created as their own prims. Use Create > Physics > Mujoco — available from the main Create menu, the viewport context menu, and the Stage window context menu — to instantiate them:

Menu entry	Prim type created
Mujoco actuator	`MjcActuator`
Mujoco keyframe	`MjcKeyframe`
Mujoco tendon	`MjcTendon`

The new prim is parented under the currently selected prim, or under the stage root when nothing is selected.

Editing numeric array attributes#

MuJoCo numeric array attributes — the MjcKeyframe state vectors (mjc:qpos, mjc:qvel, mjc:ctrl, …) and the actuator/tendon parameter vectors — are edited through a pop-up window. Click the Edit button next to the attribute to open a window that shows the attribute name and description and lists every value in a vertical, index-ordered list where entries can be added, removed, and changed. Click OK to commit your changes as a single undoable step, or Cancel to discard them.

Newton and MuJoCo attribute reference#

Once the edit target is set to mujoco.usda, the following tables describe what to author and where.

Joint-level attributes#

Author these on the joint prim (for example, /Robot/panda_joint1). The exception is mjc:armature and mjc:frictionloss, which are physical properties of the joint itself and belong in physics.usd so both backends see them.

Attribute	Type	Description
`mjc:armature`	`float`	Effective rotor inertia reflected at the joint. Author in `physics.usd`. Improves solver stability for externally-driven joints and matches real hardware with high gear ratios. See Tips for the gear-ratio formula.
`mjc:frictionloss`	`float`	Dry friction loss applied at the joint. Author in `physics.usd`. Positive values only.
`mjc:ref`	`float`	Reference (zero-point) position for the joint in radians or meters. The MuJoCo solver measures displacement relative to this value. Author in `mujoco.usda`.
`mjc:forceRange`	`float2`	Minimum and maximum force/torque limits `(min, max)` applied by the actuator. Author in `mujoco.usda`. Equivalent to `UsdPhysics.DriveAPI.maxForce` for the symmetric case where `abs(min) == max`. PhysX does not support asymmetric force ranges.

Actuator attributes#

Newton uses a different force equation than the USD Physics PD drive:

Backend	Force equation
USD Physics (`physics` / `physx` variants)	`Stiffness × position_error + Damping × velocity_error`
MuJoCo / Newton (`mujoco` variant)	`gain × control + bias`

The following attributes control the MuJoCo formulation. Author all of them on the joint prim in mujoco.usda. The automatic conversion from USD Physics drives applies only when gainType = "fixed" and biasType = "affine"; any other combination requires manual authoring.

Attribute	Type	Description
`mjc:gainType`	`token`	Gain computation mode. Use `"fixed"` for a constant scalar gain. Other types (`"affine"`, `"muscle"`) are not automatically mapped from USD Physics drives.
`mjc:gainPrm`	`float[]`	Gain parameters. For `gainType = "fixed"`: `gainPrm[0]` is the scalar multiplier (equivalent to `DriveAPI.stiffness` for position control).
`mjc:biasType`	`token`	Bias computation mode. Use `"affine"` for a linear position/velocity-dependent bias.
`mjc:biasPrm`	`float[]`	Bias parameters. For `biasType = "affine"`: `biasPrm[1]` maps to `-DriveAPI.stiffness` and `biasPrm[2]` maps to `-DriveAPI.damping`.

Warning

Do not author gains on UsdPhysics.DriveAPI for a joint that is actuated by a MuJoCo actuator. Both systems apply forces independently under Newton and the combined result is undefined.

Mimic joint attributes (`NewtonMimicAPI`)#

Mimic joints enforce a linear constraint between a follower joint and a leader joint:

follower_position = newton:mimicCoef0 + newton:mimicCoef1 × leader_position

Author NewtonMimicAPI on the follower joint prim in mujoco.usda. The PhysX variant uses a D6 joint retyping pass instead; NewtonMimicAPI is not consumed by the PhysX backend.

Attribute	Type	Description
`newton:mimicJoint`	relationship	Targets the leader joint prim. Must be a `PhysicsRevoluteJoint` or `PhysicsPrismaticJoint`.
`newton:mimicCoef0`	`float`	Constant offset term (radians or meters).
`newton:mimicCoef1`	`float`	Scale factor applied to the leader position. Use `1.0` for a 1:1 mimic, `-1.0` to mirror.

Newton actuators#

Beyond the MuJoCo formulation, Newton also supports Newton actuators — devices that provide direct torque or force control for robot joints, bypassing the USD Physics drive entirely. Newton actuators are authored as separate prims on the stage and are suited to advanced control algorithms that produce raw effort commands. For setup and usage, see Newton Actuators.

To create a Newton actuator on the stage, right-click and select Create > Physics > Newton > Newton Actuator.

Stage context menu path Create > Physics > Newton > Newton actuator

Migrating a PhysX asset to Newton#

If your robot was built for PhysX only, it has no mujoco.usda layer. All actuator configuration lives as UsdPhysics.DriveAPI stiffness and damping on the joint prims. To add Newton support you need to create mujoco.usda and populate it with the equivalent MuJoCo actuator attributes. The Asset Transformer automates the conversion; the subsections below cover both the automated path and manual mapping for cases that fall outside automatic conversion.

Quick guide: Asset Transformer for multi-physics conversion#

The Asset Transformer’s MjcToPhysxConversionRule (MJCF-sourced assets) and UrdfToMjcPhysxConversionRule (URDF-sourced assets) create mujoco.usda and populate it from the existing USD Physics drive attributes automatically.

Open the asset in Isaac Sim.
Go to Tools > Robotics > Asset Editors > Asset Transformer.
In the Input section, select Active Stage or pick the asset file.
Set the Output Directory to a location outside the source tree.
Click Load Preset, select the Isaac Sim profile, and verify the relevant conversion rule is present:
- isaacsim.asset.transformer.rules.isaac_sim.mjc_to_physx_conversion.MjcToPhysxConversionRule for MJCF-sourced assets, or
- isaacsim.asset.transformer.rules.isaac_sim.urdf_to_mjc_physx_conversion.UrdfToMjcPhysxConversionRule for URDF-sourced assets.
Click Run and wait for the pipeline to complete.

Verify the output. A correctly transformed asset contains:

<robot>/
  <robot>.usd              # Interface layer (variant sets, payloads)
  payloads/
    Physics/
      physics.usd          # Shared USD Physics joints and rigid bodies
      mujoco.usda          # MuJoCo actuator attributes (Newton backend)
      physx.usda           # PhysX drive overrides and D6 retyping

See Asset Transformer Tutorials for step-by-step transformer walkthroughs and Asset Transformer Rules Reference for the complete rule reference.

Quick guide: manually mapping DriveAPI gains to MuJoCo attributes#

When automatic conversion is not available — for example, when the actuator uses a non-standard gain or bias type — use the following table to derive the MuJoCo attribute values from the existing USD Physics drive. Set the edit target to mujoco.usda first (see Setting the edit target).

USD Physics DriveAPI attribute	MuJoCo attribute	Notes
`DriveAPI.stiffness`	`mjc:gainPrm[0]`	Set `mjc:gainType = "fixed"`. Positive values only.
`DriveAPI.damping`	`-mjc:biasPrm[2]`	Set `mjc:biasType = "affine"`. The sign is negated.
`DriveAPI.stiffness` (via bias)	`-mjc:biasPrm[1]`	Alternative path when stiffness is encoded in the bias term.
`DriveAPI.maxForce`	`mjc:forceRange` `(min, max)`	Use symmetric values `(-F, F)` where `F = DriveAPI.maxForce`. Asymmetric ranges are not representable in USD Physics.
`DriveAPI.targetPosition` (default)	`mjc:ref`	Reference position offset. Typically zero for imported assets.

After mapping, remove the DriveAPI from the same joint in mujoco.usda with a delete operand. Keep the drive definition in physics.usd — the MuJoCo overlay overrides it under Newton while it remains available for PhysX and other solvers.

Quick guide: migrating mimic joints#

Identify mimic joints in the source asset. In MJCF, look for <joint> elements with mimicJoint and mimicCoef attributes. In URDF-sourced assets, mimic joints appear as <mimic joint="..."> tags.
Set the edit target to mujoco.usda following the workflow in Setting the edit target.

Select the follower joint prim on the stage and apply NewtonMimicAPI:

UI: Right-click Add > Physics > Newton > Newton Mimic Joint.

Python:

import omni.usd
from isaacsim.physics.newton.schemas import NewtonMimicAPI

stage = omni.usd.get_context().get_stage()
follower_prim = stage.GetPrimAtPath("/Robot/follower_joint")
leader_prim = stage.GetPrimAtPath("/Robot/leader_joint")

mimic_api = NewtonMimicAPI.Apply(follower_prim)
mimic_api.GetMimicJointRel().AddTarget(leader_prim.GetPath())
mimic_api.GetMimicCoef1Attr().Set(1.0)   # scale
mimic_api.GetMimicCoef0Attr().Set(0.0)   # offset (radians or meters)

Save mujoco.usda and remove it from the root sublayer list as described in Setting the edit target.
For the PhysX variant, run MjcToPhysxConversionRule via the Asset Transformer. Its post-processing pass retypes the follower joint to a D6 joint and redirects the mimic relationship automatically. See MJCF Importer Extension for details.
Validate: switch the stage variant to mujoco, launch with ./isaac-sim.newton.sh, and confirm the constraint is enforced.

Validating the migration#

After converting or manually authoring Newton attributes:

Open the transformed asset with ./isaac-sim.newton.sh.
Locate the robot’s variant set (typically Physics) on the stage. Switch between the physics, physx, and mujoco variants and confirm the robot behaves as expected under each backend.
Run the Asset Validator (Tools > Robotics > Asset Validators > Robot Validator) to check for missing physics layers, incorrect opinion placement, and schema issues. See Asset Validation for the full rule set.
If the robot exhibits unexpected behavior in the Newton variant, open the Layer panel and confirm that mujoco.usda holds the mjc:* opinions and physics.usd holds the joint definitions. Use the Layer Stack column in the Property panel to inspect the winning opinion for any attribute.

Common pitfalls#

Mixing USD Physics drives and MuJoCo actuators on the same joint: Under Newton, do not author both a non-zero DriveAPI.stiffness or DriveAPI.damping and a MuJoCo actuator on the same joint. The two systems apply forces independently and the result is undefined behavior. Remove or zero the DriveAPI gains in mujoco.usda for joints controlled by a MuJoCo actuator.
Editing attributes while the simulation is running: Newton does not apply USD property edits while the simulation is playing. Always stop the simulation before authoring. See Runtime change tracking.
Gains authored on the wrong layer: MuJoCo actuator attributes in physics.usd or the session layer have no effect under Newton and may corrupt the PhysX variant. Always verify the active edit target before authoring.
Treating PhysX and MuJoCo gain values as equivalent: A stiffness value tuned for the physx variant does not produce the same behavior when entered as mjc:gainPrm[0]. The formulations differ in units and sign conventions. Tune each variant independently; use the Gain Tuner Extension for physics and physx, and author MuJoCo gains manually or derive them from the importer mapping table.
Authoring mjc:armature in mujoco.usda: mjc:armature is a physical property shared by both backends. Author it in physics.usd alongside the joint definition. Placing it only in mujoco.usda means the PhysX variant runs without armature, causing solver instability in that variant.
Running the Asset Transformer on an already-transformed asset: A second transformer run on an asset that already has mujoco.usda can duplicate opinions or overwrite manual edits. Back up the asset before re-running, or use Load Preset to apply only the specific rules needed.
Mimic joints not redirected in the PhysX variant: NewtonMimicAPI is consumed only by Newton. If you author it by hand (rather than through the MJCF importer), run MjcToPhysxConversionRule to produce the corresponding D6 representation in physx.usda.