Design Book › Robot description checklist

Robot description checklist

What a designer must do

  1. Run this checklist on every model before you tune anything. A bad model looks like a bad solver [1].
  2. Block on any must failure.
  3. Run the static checks on each commit. Run the sim and measure checks when the model or the robot changes.
  4. Record each waiver with a reason in the model's own documentation [2].

This is the checklist for a robot model. It covers URDF, SDF, MJCF and USD: model format and units, mass and inertia, collision geometry, and joints. Each row is one check, so a linter can report the check, its level, the element and a message.

How to read the checklist

The Kind column comes from the guideline's check field.

How to read the checklist
KindMeaningNeeds
lintmodel-lint: read or compile the modelThe file
simLoad or step the modelA simulator
measureCompare with the robotThe real robot
reviewA person checks a recordA reviewer

Each format's source, as the guidelines state it:

How to read the checklist
FormatSpec the guidelines citeSection
URDFROS wiki URDF joint and link specs, unversioned, captured 2026-11-08URDF
SDFSDFormat spec 1.12SDF
MJCFMuJoCo 4.0.0 docsMJCF
USDOpenUSD release alias, captured 2026-11-08; Isaac Lab 3.0.0 docsUSD
FramesREP 103, REP 105, REP 120; REP 199 is a draftFrames
CAD exportonshape-to-robot docs, latest alias, no version shownCAD export

Units

Units
LevelKindFormatConditionSource
mustlintURDF, ROSLength in metres, mass in kilograms, time in seconds, angle in radians. Reject other units[3]
shouldreviewAllThe model README names each departure from REP 103 and its reason[2]
shouldlintMJCFGravity, geometry size and density agree with one unit system. Prefer MKS[4]
mustlintAllTotal mass and bounding box match the measured robot. Catches millimetre-for-metre errors[5]
guidelintMJCFcompiler/angle is set explicitly. MJCF defaults to degrees; URDF input always reads radians[6]
mustlintUSDJoint limits equal source limits after radian-to-degree conversion. The schema reads one-dimensional angles in degrees[7]
shouldlintUSDRead metersPerUnit and kilogramsPerUnit from each composed layer. Each can differ[8]

Frames

Frames
LevelKindFormatConditionSource
mustlintAllEach rotation matrix in the frame tree has determinant +1[9]
shouldreviewROSBody frame: x forward, y left, z up[10]
mustlintROSEach camera has an _optical child frame: z forward, x right, y down[11]
shouldreviewAllPrefer quaternions or matrices. No Euler field lacks a stated order[12]
mustlintMobilebase_link has no movable joint between it and the base body[13]
shouldreviewMobileNo long-horizon goal is expressed in odom. It drifts[14]
shouldreviewMobileNo local control loop reads pose in map. It can jump[15]
guidelintArmFlange +X points away from the parent link. Draft REP, treat as a convention[16]
guidemeasureArmtool0 matches the controller's all-zeros TCP. Draft REP[17]
guidelintArmThe flange link has no visual or collision child. Draft REP[18]
shouldlintHumanoidUnder REP 120, sole frame Z is normal to the foot contact face[19]

URDF

URDF
LevelKindConditionSource
mustlintForward kinematics at zero matches CAD joint locations. The joint sits at the child link origin[20]
mustlintConversion code reads rpy as fixed-axis roll, pitch, yaw, in radians[21]
shouldlintEach revolute, continuous and prismatic joint has an axis element. Omitted means x[22]
shouldlintAxis vector norm equals one[23]
mustlintReject a revolute or prismatic joint with no limit element[24]
mustlintEach limit holds effort and velocity[25]
guidelintOn revolute and prismatic joints, lower and upper are set, with lower below upper. Each omitted bound defaults to zero. Omit them for continuous joints[26]
mustlintNo duplicate joint names[27]
guidelintEach non-fixed child link has an inertial element. The element is optional; omitted means zero mass and zero inertia[28]
mustlintInertia is about the link's center of mass. Recompute from the mesh and compare[29]
shouldlintEach actuated joint has a dynamics element. Damping and friction default to zero[30]

CAD export

These rows cover onshape-to-robot, from its docs under the latest alias, with no version shown. See also Format conversion.

CAD export
LevelKindConditionSource
mustreviewExported joint count equals intended degrees of freedom. A mate without the special prefix is ignored[31]
shouldreviewExport log holds no orphaned-link warning. That link becomes fixed to the base[32]
shouldmeasureJog each real joint positive and compare with the model. Use the inv suffix to flip it[33]
shouldreviewExported limits match the CAD mates. ignore_limits drops them[34]

SDF

SDF
LevelKindConditionSource
guidelintResolve expressed_in on each axis before comparing with CAD. The default is the joint frame[35]
shouldreviewMetadata names the spec version. It can differ from the libsdformat release[36]
mustlintCheck ixy sign against a point-mass test. The spec uses -m x y[37]
mustlintFlag negative effort. SDF does not enforce a negative limit[38]

MJCF

MJCF
LevelKindConditionSource
mustlintCompiled world poses match CAD. MJCF poses are local to the parent[39]
mustlintNames are unique per element type. Code lookups use the exact case[40]
shouldreviewNo literal element index in code that reads model data[41]
guidelintNo massless moving body. MJCF needs no dummy bodies for sensors[42]
mustlintEach body has an inertial element, or a geom mass or density chosen for its material. The default assumes water density[43]
mustlintinertiagrouprange or density=0 excludes either visual or collision geoms from inertia[44]
shouldlintList bodies whose mass came from geom inference[45]
shouldsimThin 2D or non-watertight meshes set the mesh inertia attribute to shell. Compile and read body mass[46]
mustlintPrincipal inertias satisfy A + B >= C in all permutations[47]
guidelintbalanceinertia is false in the released file. It silently replaces bad inertias with their average[48]
shouldreviewCorrect unrealistic inertias in the CAD or URDF file. Where you cannot edit an imported model, bound mass and inertia when it compiles, with boundmass and boundinertia[49]
guidelintboundmass is unset in a finished model[50]
shouldlintThe compiler does not set settotalmass. The MuJoCo 4.0.0 docs mark it deprecated[51]
shouldlintReport the largest mass and inertia ratio across each joint and expected contact. Keep it below about 1000:1[52]
shouldlintFlag links with inertia near 1e-6 and no geometry[53]
mustlintctrlrange lies inside joint range, except a gripper that must close past pad contact[54]
shouldlintEach position actuator sets kv or dampratio, and forcerange. The defaults are kv zero and unlimited force[55]
shouldlintCompare armature with link inertia about the joint axis on wrists, fingers and ankles[56]
mustsimBacklash uses two coaxial hinges with armature on the driven one. Compile and step[57]
shouldsimLight links with force-limited actuators have armature and passive damping. Step the largest command on the lightest link[58]
shouldreviewEach frictionloss value has a measured stiction reason[59]
mustsimmargin is zero, or paired with a matching gap. Measure the rest height of a known box[60]
mustsimMesh collides as its convex hull. Toggle the hull view. A concave part needs a decomposition[61]
shouldlintReport the share of mesh collision geoms. Prefer primitives[62]
shouldlintNo high-polygon visual geom has a nonzero contype or conaffinity[63]
shouldsimpriority is set on the geom whose contact values must win. Slide test against the measured angle[64]
shouldlintFingertip, grasp-pad and settling curved-object geoms have condim 4 or 6. Keep 3 elsewhere[65]
shouldlintNo near-zero friction under pyramidal cones. Use condim 1[66]
mustmeasureGripper force times friction well exceeds object weight, before you tune slip[67]
shouldlintThe flag element does not disable multiccd or nativeccd[68]
shouldsimLoad paused and count contacts at the initial state[69]
mustsimSpeculative contacts only on supported geometry. Not height fields, SDFs or flexes[70]
shouldsimRerun the tunneling regression after each MuJoCo upgrade. The docs say the behaviour may still change[71]

USD and Isaac Lab

USD and Isaac Lab
LevelKindConditionSource
mustreviewRecord articulation root, fixed-base form, joint merging, joint types, axes and limits against the source robot[72]
shouldlintList all per-body gravity overrides and justify each[73]
mustsimLoad the asset and fail on any placeholder inertia warning[74]
shouldlintReport bodies that author both mass and density. Mass wins[75]
mustreviewEach armature value has a physical source or a response test. It is not a patch for bad mass, units or resets[76]
mustsimCompare collision and visual views per link. Visual parity is not collision parity[77]
mustsimRun the overlap check across the full reset distribution[78]
mustsimSize nconmax and njmax separately from a measured worst case, plus task-specific headroom[79]
shouldreviewEach capacity change cites an overflow in the diagnostics[80]
shouldsimRun once with actuator_value_resolution_debug_print on. A config override replaces the USD value per joint and property[81]
shouldlintFail when all joints share one effort value on a robot with mixed actuators[82]
mustlintMimic followers have zero stiffness and damping on multi-backend assets[83]
shouldreviewThe actuator model is the simplest that meets the requirements[84]
guidesimUse DCMotor where the model needs a four-quadrant torque-speed envelope, not a fixed effort clip. Compare torque against the motor curve at peak speed[85]
shouldsimLog the share of time that targets sit at a joint limit[86]
mustsimCommand past the limit under MJWarp and record the speed. MJWarp drops joint_velocity_limit[87]
mustreviewHardware speed limits live on the robot controller, not only in simulation config[88]
shouldreviewactuator_velocity_limit and joint_velocity_limit are both set on purpose per joint[89]
shouldsimRetune damping after increasing armature, then rerun the step response[90]

PhysX and Newton

PhysX and Newton
LevelKindDocConditionSource
mustsimPhysX SDK 5.8.0Step once from the reset state. Fail on any contact not intended. Overlapping bodies may explode, so limit the de-penetration velocity[91]
shouldsimOmni Physics guideList contact pairs at rest. Filter by pair, not all self-collision[92]
guidesimOmni Physics guideCompare stability with self-collision on and off, as a diagnostic only[93]
shouldsimOmni Physics guideInspect link masses and inertias in OmniPVD. Avoid large ratios[94]
mustlintNewton 1.7.0Mass above zero and inertia positive definite for each dynamic body[95]
shouldlintNewton 1.7.0No zero-mass body is used as a fixed support. Use is_kinematic[96]
shouldlintNewton 1.7.0Measured links carry lock_inertia=True[97]
shouldsimNewton 1.7.0Build with validate_inertia_detailed on. Fail on any corrected body[98]
mustlintOmni Physics guideCompute sqrt(stiffness/inertia) * dt per drive. Avoid values much greater than 1[99]
guidelintOmni Physics guideReport damping / (2 * sqrt(stiffness * inertia)) with the smallest relevant inertia[100]
shouldsimOmni Physics guideAdd feed-forward such as gravity compensation before very high stiffness[101]
shouldsimOmni Physics guideApply a step target and log peak joint force. Bound it with a force limit or a rate limiter[102]
shouldlintOmni Physics guideEach joint effort limit matches the cited datasheet value[103]
shouldlintOmni Physics guideArmature equals rotor inertia times ratio squared[104]
guidesimOmni Physics guideTest a stiff grasp with and without mimic compliance[105]
guidesimOmni Physics guideFor RL, consider a generous 200-300 deg/s limit on revolute joints. Count unstable resets[106]

Real parts and the SO-101

The first row compares the model with the built robot. No file check can replace it. The second is specific to the SO-101.

Real parts and the SO-101
LevelKindConditionSource
guidemeasureWeigh each removable link and compare with the model. CAD mass is not a measurement[107]
guidelintLeader model armature differs by joint gear ratio. The SO-101 leader uses several gear ratios; the follower uses 1/345 gearing[108]

Worked example: SO-101

The database holds SO-ARM101 limits from the upstream MJCF. The source marks them as simulation model values, not a maker datasheet.

Worked example: SO-101
JointRange (rad)Actuator force range (N·m)
shoulder_pan-1.91986 to 1.91986-2.94 to 2.94
shoulder_lift-1.7453293 to 1.7453293-2.94 to 2.94
elbow_flex-1.69 to 1.69-2.94 to 2.94
wrist_flex-1.658063 to 1.658063-2.94 to 2.94
wrist_roll-2.7438473 to 2.8412063-2.94 to 2.94
gripper-0.174533 to 1.7453292-2.94 to 2.94

Compare this with the 12 V servo. These are reviews of database values. Nobody ran a linter on the files.

Where the database is thin

Sources

Each guideline in this chapter with its source, the date it was read and the exact words of the source. Level: must means breaking it causes failure or harm, should is good practice, guide is a rule of thumb.

  1. Load the MuJoCo model paused and rule out modeling bugs before tuning parameters. Level: should. mujoco.readthedocs.io 2026-11-08
  2. Write down the reason for any departure from the REP 103 units or axes in the model's own documentation. Level: should. ros.org 2026-11-08“choosing different conventions should be well justified and well documented.”
  3. In a ROS-facing model, state length in metres, mass in kilograms, time in seconds and angle in radians. Level: must. ros.org 2026-11-08“We have chosen to standardize on SI units.”
  4. MuJoCo fixes no unit system, so choose one consistent system for each MJCF file, and prefer MKS because the engine's defaults assume it. Level: should. mujoco.readthedocs.io 2026-11-08
  5. Before any tuning, check mesh scale and total mass to catch a millimetre-for-metre mistake. Level: must. mujoco.readthedocs.io 2026-11-08
  6. MJCF angles default to degrees, while URDF input is always parsed as radians. Level: guide. mujoco.readthedocs.io 2026-11-08
  7. In USD physics, convert radian limits and angular values to degrees, because the schema reads one-dimensional angles in degrees. Level: must. openusd.org 2026-11-08
  8. Check the unit metadata of every USD file composed into a robot stage, because each referenced file can carry different units. Level: should. openusd.org 2026-11-08
  9. Every frame must be right handed. Level: must. ros.org 2026-11-08“All systems are right handed.”
  10. Align a ROS robot body frame with x forward, y left and z up. Level: should. ros.org 2026-11-08“x forward y left z up”
  11. Give a camera a second frame with the _optical suffix, with z forward, x right and y down. Level: must. ros.org 2026-11-08“z forward x right y down”
  12. Store rotations as quaternions or matrices where you can, and name the convention whenever Euler angles appear. Level: should. ros.org 2026-11-08“Euler angles are generally discouraged due to having 24 'valid' conventions”
  13. Attach base_link rigidly to the mobile base; do not place it on a moving part. Level: must. ros.org 2026-11-08“The coordinate frame called base_link is rigidly attached to the mobile robot base.”
  14. Do not use the odom frame as a long-term reference, because it drifts. Level: should. ros.org 2026-11-08“drift makes it a poor frame for long-term reference.”
  15. Do not use the map frame for local sensing and acting, because its pose can jump. Level: should. ros.org 2026-11-08“discrete jumps in position estimators make it a poor reference frame for local sensing and acting.”
  16. On a serial arm, point flange +X away from the last link. This comes from a draft REP, so treat it as a convention, not a settled standard. Level: guide. gavanderhoorn.github.io 2026-11-08“Positive X (x+) must always point away from the last link”
  17. Make tool0 equal the controller's all-zeros TCP. This comes from a draft REP. Level: guide. gavanderhoorn.github.io 2026-11-08“shall match exactly an all-zeros TCP as defined by the robot controller.”
  18. Keep geometry off the flange frame so end effectors attach cleanly. This comes from a draft REP. Level: guide. gavanderhoorn.github.io 2026-11-08“flange shall not have any geometry associated with it.”
  19. On a humanoid using REP 120, make the sole frame's XY plane coplanar with the contact surface. Level: should. ros.org 2026-11-08“frame must be coplanar with the support body contact surface.”
  20. Author a URDF joint origin as the parent-to-child transform; the joint sits at the child link origin. Level: must. wiki.ros.org 2026-11-08“The joint is located at the origin of the child link”
  21. Read URDF rpy as fixed-axis rotations in radians: roll about x, then pitch about y, then yaw about z. Level: must. wiki.ros.org 2026-11-08“first roll around x, then pitch around y and finally yaw around z. All angles are specified in radians.”
  22. Write the axis on every moving URDF joint, because an omitted axis silently becomes the x axis. Level: should. wiki.ros.org 2026-11-08“<axis> (optional: defaults to (1,0,0))”
  23. Normalize every URDF joint axis. Level: should. wiki.ros.org 2026-11-08“The vector should be normalized.”
  24. Every revolute and prismatic URDF joint needs a limit element. Level: must. wiki.ros.org 2026-11-08“<limit> (required only for revolute and prismatic joint)”
  25. Every URDF limit element needs both effort and velocity values. Level: must. wiki.ros.org 2026-11-08“velocity (required)”
  26. URDF lower and upper bounds each default to zero when omitted; omit them for continuous joints. Level: guide. wiki.ros.org 2026-11-08“lower (optional, defaults to 0)”
  27. Give each URDF joint a unique name. Level: must. wiki.ros.org 2026-11-08“Specifies a unique name of the joint”
  28. A URDF link's inertial element is optional; if left out, it defaults to zero mass and zero inertia. Level: guide. wiki.ros.org 2026-11-08“<inertial> (optional: defaults to a zero mass and zero inertia if not specified)”
  29. Author URDF inertia about the link's center of mass, not about the link origin. Level: must. wiki.ros.org 2026-11-08“about Co (the link’s center of mass)”
  30. Write URDF dynamics values on purpose, because damping and friction default to zero, in units that depend on the joint type. Level: should. wiki.ros.org 2026-11-08“damping (optional, defaults to 0)”
  31. When exporting with onshape-to-robot, name every kinematic mate with its special prefix, because other mates are ignored. Level: must. onshape-to-robot.readthedocs.io 2026-11-08
  32. Treat an orphaned-link warning from onshape-to-robot as an error to resolve, because that link becomes fixed to the base. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
  33. Verify each exported joint direction; use the onshape-to-robot inv suffix when a joint must turn opposite to the CAD mate. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
  34. Set the ignore_limits export option only on purpose, because it drops the CAD joint limits from the model. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
  35. An SDF joint axis uses the joint frame unless expressed_in names another frame. Level: guide. sdformat.org 2026-11-08“The axis is expressed in the joint frame unless a different frame is expressed in the expressed_in attribute.”
  36. Record the SDF specification version apart from the libsdformat release, because the two numbers can differ. Level: should. sdformat.org 2026-11-08“This version number may be different from the release version of libsdformat”
  37. Check the sign of products of inertia when moving data into SDF, because the spec uses the -m x y convention. Level: must. sdformat.org 2026-11-08“the product of inertia convention -m x y (not +m x y) is used”
  38. Do not write a negative SDF effort value unless you want no limit, because SDF then does not enforce it. Level: must. sdformat.org 2026-11-08“Limit is not enforced if value is negative.”
  39. Treat MJCF positions and orientations as local to the parent, not as world values. Level: must. mujoco.readthedocs.io 2026-11-08
  40. Keep MJCF names unique within each element type, and treat them as case-sensitive. Level: must. mujoco.readthedocs.io 2026-11-08
  41. Look up MuJoCo elements by name in control and test code, not by a hard-coded index. Level: should. mujoco.readthedocs.io 2026-11-08
  42. Native MJCF sensors do not require massless dummy mounting bodies. Level: guide. mujoco.readthedocs.io 2026-11-08
  43. Do not rely on inferred mass for hollow printed shells or dense metal links, because MuJoCo assumes water density. Level: must. mujoco.readthedocs.io 2026-11-08
  44. When inferring inertia from geoms, count either visual or collision geoms, not both. Level: must. mujoco.readthedocs.io 2026-11-08
  45. Check whether each MJCF body has an inertial element, because the auto setting infers mass from geoms only when it is missing. Level: should. mujoco.readthedocs.io 2026-11-08
  46. For thin 2D or non-watertight meshes, set mesh inertia to shell so compile-time volume computation does not fail. Level: should. mujoco.readthedocs.io 2026-11-08
  47. Each body's principal inertias must satisfy A+B>=C in all permutations, or MuJoCo rejects the model. Level: must. mujoco.readthedocs.io 2026-11-08
  48. With MuJoCo balanceinertia enabled, invalid principal inertias are silently replaced by their average. Level: guide. mujoco.readthedocs.io 2026-11-08
  49. This guideline is held back: its source does not allow us to publish it yet.
  50. Treat boundmass as a quick fix for massless moving bodies, and not as a modeling method. Level: guide. mujoco.readthedocs.io 2026-11-08
  51. Do not build on compiler settotalmass in MuJoCo 4.0.0, because the docs mark it as deprecated. Level: should. mujoco.readthedocs.io 2026-11-08
  52. Keep mass and inertia ratios across contacts and joints below about 1000:1, or expect worse MuJoCo solver accuracy. 1000 ratio Level: should. mujoco.readthedocs.io 2026-11-08
  53. This guideline is held back: its source does not allow us to publish it yet.
  54. Keep position command ranges inside joint ranges, except for a gripper that must close past pad contact. Level: must. mujoco.readthedocs.io 2026-11-08
  55. Set damping and a force bound on every MuJoCo position actuator, because kv defaults to zero and force is unlimited. Level: should. mujoco.readthedocs.io 2026-11-08
  56. Add realistic armature on wrists, fingers and ankles, because reflected rotor inertia often exceeds their link inertia. Level: should. mujoco.readthedocs.io 2026-11-08
  57. Model MuJoCo backlash with two coaxial hinges, and put armature on the driven one, or the joint-space inertia matrix is singular. Level: must. mujoco.readthedocs.io 2026-11-08
  58. Add armature and passive damping on light links with force-limited MuJoCo actuators, because saturation removes implicit damping. Level: should. mujoco.readthedocs.io 2026-11-08
  59. Use MuJoCo frictionloss only where Coulomb stiction matters, because each joint adds a constraint row; use damping otherwise. Level: should. mujoco.readthedocs.io 2026-11-08
  60. Leave MuJoCo margin at zero unless you pair it with a matching gap, or objects hover by margin minus gap. Level: must. mujoco.readthedocs.io 2026-11-08
  61. Assume a MuJoCo mesh collides as its convex hull; a concave part needs a decomposition. Level: must. mujoco.readthedocs.io 2026-11-08
  62. Prefer primitives to meshes for collision in MuJoCo, because they improve both speed and contact normals. Level: should. mujoco.readthedocs.io 2026-11-08
  63. Put MuJoCo visual meshes in a default class with contype and conaffinity at zero, so that they do not collide. Level: should. mujoco.readthedocs.io 2026-11-08
  64. Set MuJoCo priority on the geom whose contact parameters must win, because equal-priority geoms take the larger friction. Level: should. mujoco.readthedocs.io 2026-11-08
  65. Use condim 4 or 6 on MuJoCo fingertips, grasp pads and curved objects that should settle rather than roll indefinitely; keep 3 elsewhere. Level: should. mujoco.readthedocs.io 2026-11-08
  66. For a frictionless MuJoCo contact use condim 1, not near-zero friction, which ill-conditions pyramidal cones. Level: should. mujoco.readthedocs.io 2026-11-08
  67. Ensure that maximum gripper force times sliding friction well exceeds the object's weight before you tune slip in MuJoCo. Level: must. mujoco.readthedocs.io 2026-11-08
  68. For flat contacts, keep multiccd enabled; keep nativeccd enabled for accurate, efficient convex collision detection. Level: should. mujoco.readthedocs.io 2026-11-08
  69. Load a MuJoCo model paused and check for intersecting geoms before you tune contacts. Level: should. mujoco.readthedocs.io 2026-11-08
  70. This guideline is held back: its source does not allow us to publish it yet.
  71. Recheck speculative-contact behaviour when you upgrade MuJoCo, because the docs call the feature new and subject to change. Level: should. mujoco.readthedocs.io 2026-11-08
  72. Before simulating a new USD asset, verify its articulation root, fixed-base form, joint merging, joint types, axes and limits. Level: must. isaac-sim.github.io 2026-11-08“Verify the articulation root, fixed-base representation, fixed-joint merging, nested rigid bodies, joint types, axes, and limits.”
  73. Set each per-body gravity override on purpose, because a stale override can make a task differ from scene gravity. Level: should. isaac-sim.github.io 2026-11-08“A stale override can make a task differ from scene gravity.”
  74. An importer warning about placeholder inertia means the model is wrong; fix it before any further work. Level: must. isaac-sim.github.io 2026-11-08“Treat a placeholder inertia warning as a modeling failure”
  75. In USD, remember that an authored mass overrides density, so a density edit has no effect on a body with explicit mass. Level: should. openusd.org 2026-11-08
  76. Armature is a physical term; do not use it as a patch for wrong mass, inertia, units or a penetrating reset. Level: must. isaac-sim.github.io 2026-11-08“do not use it to hide bad body mass, inertia, units, reset penetration, or contact capacity.”
  77. Apply a collision API only to geometry that you intend to collide, and do not treat a good visual match as proof of collision correctness. Level: must. isaac-sim.github.io 2026-11-08“visual parity is not collision parity.”
  78. Reject resets with robot-object or robot-support penetration before the first physics step. Level: must. isaac-sim.github.io 2026-11-08“Reject robot-object and robot-support penetration, impossible mimic states, and invalid randomized geometry before the first physics step.”
  79. Size MJWarp nconmax and njmax separately from the measured worst case plus task-specific headroom; do not derive njmax from nconmax. Level: must. isaac-sim.github.io 2026-11-08“Do not derive njmax directly from nconmax.”
  80. Do not raise capacity to repair bad collision geometry, material or convergence, because it cannot fix them. Level: should. isaac-sim.github.io 2026-11-08“Capacity cannot fix incorrect collision geometry, contact material, or convergence.”
  81. Print the resolved Isaac Lab actuator values, because a config override replaces the USD value per joint and per property. Level: should. isaac-sim.github.io 2026-11-08“actuator_value_resolution_debug_print”
  82. Derive each joint's effort limit from its own motor and gearbox; a single large value across the robot is not acceptable. Level: should. isaac-sim.github.io 2026-11-08“choosing both from the motor and gearbox rather than using one oversized value for the whole robot.”
  83. With Newton and PhysX on one asset, drive only the mimic leader; give the follower zero stiffness and damping. Level: must. isaac-sim.github.io 2026-11-08“Zero stiffness and damping are what disable the second PD drive.”
  84. Choose the simplest actuator model that meets your requirements. Level: should. isaac-sim.github.io 2026-11-08“Choose the simplest model that meets your requirements.”
  85. Use DCMotor when the actuator model needs a four-quadrant torque-speed envelope rather than a fixed effort clip. Level: guide. isaac-sim.github.io 2026-11-08“Same PD torque, clipped to a four-quadrant torque-speed envelope.”
  86. During policy transfer, stop targets short of the hard limits of each joint. Level: should. isaac-sim.github.io 2026-11-08“keep targets away from hard joint stops”
  87. Do not count on joint_velocity_limit under MJWarp, because MJWarp drops it; bound speed in task or control logic. Level: must. isaac-sim.github.io 2026-11-08“MJWarp drops that field, while Kamino honors it.”
  88. Do not treat Isaac Lab joint_velocity_limit as a safety clamp, because its enforcement depends on the backend. Level: must. isaac-sim.github.io 2026-11-08“is not a backend-independent safety clamp”
  89. Keep the physical actuator_velocity_limit distinct from the solver joint_velocity_limit when you transfer a policy. Level: should. isaac-sim.github.io 2026-11-08“distinguish the physical actuator_velocity_limit from the solver joint_velocity_limit”
  90. Retune damping after increasing armature, because the effective natural frequency and damping ratio change. Level: should. isaac-sim.github.io 2026-11-08“Retune damping after increasing armature because the effective natural frequency and damping ratio change.”
  91. PhysX rigid bodies created overlapping may explode, because the SDK resolves penetration in one step; limit the de-penetration velocity. Level: must. nvidia-omniverse.github.io 2026-11-08
  92. Filter unintended contact between non-adjacent PhysX links by pair, instead of turning off all self-collision. Level: should. docs.omniverse.nvidia.com 2026-11-08
  93. To diagnose unexplained instability, disable self-collision once as a test, and then find the offending pair. Level: guide. docs.omniverse.nvidia.com 2026-11-08
  94. In PhysX articulations, avoid large mass and inertia ratios, because an impulse can give a light body very large velocity. Level: should. docs.omniverse.nvidia.com 2026-11-08
  95. Give each dynamic body positive mass and a physically meaningful inertia tensor. Level: must. newton-physics.github.io 2026-11-08“Every dynamic rigid body in Newton needs positive mass and a physically meaningful inertia tensor for stable simulation.”
  96. In Newton, make a body immovable with is_kinematic, not with zero mass. Level: should. newton-physics.github.io 2026-11-08“do not rely on zero mass to make a body immovable.”
  97. In Newton, set lock_inertia=True on bodies with measured mass properties, so that later shapes cannot change them. Level: should. newton-physics.github.io 2026-11-08“Use lock_inertia=True to protect hand-specified mass properties from subsequent shape additions.”
  98. During Newton model development, turn on validate_inertia_detailed and read the per-body corrections. Level: should. newton-physics.github.io 2026-11-08“to get per-body warnings for any mass or inertia values that were corrected.”
  99. Avoid drive gains where natural frequency times timestep is much greater than 1, mainly on mimic and gripping joints. 1 dimensionless Level: must. docs.omniverse.nvidia.com 2026-11-08
  100. Estimate angular drive damping ratio as damping over 2 sqrt(stiffness times inertia), with the smallest relevant inertia. Level: guide. docs.omniverse.nvidia.com 2026-11-08
  101. Improve position tracking with feed-forward such as gravity compensation before raising stiffness to very high values. Level: should. docs.omniverse.nvidia.com 2026-11-08
  102. Bound large drive forces with a force limit or a rate limiter on drive targets. Level: should. docs.omniverse.nvidia.com 2026-11-08
  103. Set each simulated joint's maximum force from the actuator specification when one exists. Level: should. docs.omniverse.nvidia.com 2026-11-08
  104. Set armature for a geared actuator from rotor inertia and ratio, as J times G squared, where G is motor speed over output speed. Level: should. docs.omniverse.nvidia.com 2026-11-08
  105. Add compliance to mimic joints in PhysX when they compete with contacts and stiff drives. Level: guide. docs.omniverse.nvidia.com 2026-11-08
  106. For PhysX RL training, consider a generous maximum joint velocity of 200-300 deg/s on revolute joints to reduce early instability. 200-300 deg/second Level: guide. docs.omniverse.nvidia.com 2026-11-08
  107. This guideline is held back: its source does not allow us to publish it yet.
  108. The SO-101 leader uses several gear ratios, while the follower uses 1/345 gearing. Level: guide. huggingface.co 2026-11-08
  109. A servo's stall torque is its maximum momentary output and differs from its continuous rating. Real-world output is generally closer to the performance-graph measurements. Level: guide. emanual.robotis.com 2026-11-08
  110. In continuous operation keep motor torque below the thermally set continuous limit, not the peak or stall value. Level: must. hades.mech.northwestern.edu 2026-11-08
  111. Fit armature, damping, friction, gains, inertia and delay to hardware logs with optimization, rather than hand-tuning, when matching a specific robot in MuJoCo. Level: should. mujoco.readthedocs.io 2026-11-08
  112. The URDF importer's default collision_type is Convex Hull. Level: guide. raw.githubusercontent.com 2026-11-09
  113. USD drive gains on actuated joints are zeroed automatically so the implicit drive does not fight the actuator; joints without an actuator keep their drive gains. Level: must. raw.githubusercontent.com 2026-11-09
  114. Zero-gain USD drives select effort mode in ImplicitActuatorCfg; a gain set to None keeps the USD value, so pick each on purpose. Level: guide. raw.githubusercontent.com 2026-11-09“A gain set to ``None`` keeps”
  115. The stated preset for position-controlled teleoperation is a position drive with stiffness 800 and damping 40. Level: guide. raw.githubusercontent.com 2026-11-09
  116. The stated preset for an RL agent that commands torques is drive type none with stiffness and damping 0. Level: guide. raw.githubusercontent.com 2026-11-09