Newton Schema

The Newton USD Schema (newton-usd-schemas) defines physics attributes using the Newton naming conventions. When a prim has both Newton and PhysX schemas applied, the PhysX runtime resolves attribute values using a well-defined priority order, allowing scenes authored with Newton schemas to simulate correctly under PhysX.

The Newton schema is a codeless schema — it has no generated C++ classes. Attributes are read at runtime via generic UsdAttribute lookups using TfToken names from the generated NewtonSchemaTokens.h header.

Supported API Schemas

The following Newton API schemas are recognized by the PhysX runtime:

NewtonSceneAPI

Applies on top of a PhysicsScene prim.

Attribute	Default	Description
newton:timeStepsPerSecond	1000	Simulation time step frequency in Hz.
newton:gravityEnabled	true	Whether gravity is enabled for the entire scene.
newton:maxSolverIterations	-1	Maximum solver iterations. Not mapped to PhysX (different semantics).

NewtonXpbdSceneAPI / NewtonKaminoSceneAPI

Extend NewtonSceneAPI with solver-specific parameters (XPBD or Kamino). These attributes are not currently mapped to PhysX equivalents and are reserved for Newton-native simulation.

NewtonArticulationRootAPI

Applies on top of a prim with PhysicsArticulationRootAPI.

Attribute	Default	Description
newton:selfCollisionEnabled	true	Whether self-collisions are enabled for the articulation.

NewtonCollisionAPI

Applies on top of a Gprim with collision.

Attribute	Default	Description
newton:contactMargin	0	Outward surface inflation for collision detection (distance units).
newton:contactGap	-inf	Additional contact detection gap, additive on top of contactMargin. The total contact detection distance from the shape surface is contactMargin + contactGap. -inf means use the solver default.

NewtonMeshCollisionAPI

Applies on top of a Mesh with collision.

Attribute	Default	Description
newton:maxHullVertices	-1	Maximum vertices in convex hull approximation. -1 means no limit.

NewtonMaterialAPI

Applies on top of a Material prim.

Attribute	Default	Description
newton:torsionalFriction	0.25	Torsional friction coefficient. Not mapped to PhysX.
newton:rollingFriction	0.0005	Rolling friction coefficient. Not mapped to PhysX.

NewtonMimicAPI

Single-apply schema applied on top of a PhysicsJoint prim that is part of an articulation. Enforces a linear relationship between the follower joint (the prim this API is applied to) and a leader joint:

\[\text{joint}_0 = \text{coef}_0 + \text{coef}_1 \cdot \text{joint}_1\]

The PhysX runtime implements this via PxArticulationMimicJoint as a hard constraint. Only single-DOF joints are supported as follower and leader (PhysicsRevoluteJoint with a finite limit set, or PhysicsPrismaticJoint). Multi-DOF joints (spherical, D6, fixed, distance, gear, rack-and-pinion) are rejected at parse time with an error message — use multiple PhysxMimicJointAPI instances, one per axis, if you need that.

Attribute	Default	Description
newton:mimicEnabled	true	Whether the mimic constraint is active. When false, the follower joint moves independently, as though the schema was not applied.
newton:mimicJoint	(none)	Relationship to the leader joint. Must reference exactly one PhysicsJoint prim in the same articulation.
newton:mimicCoef0	0.0	Offset term in the mimic equation. Units match the follower joint: a distance (stage linear units) for a prismatic follower, or degrees for a revolute follower.
newton:mimicCoef1	1.0	Scale factor on the leader’s position. A value of 1.0 makes the follower track the leader exactly (plus mimicCoef0); negative values reverse the direction. Units depend on the follower/leader pairing: revolute follower + revolute leader: dimensionless (degrees / degrees) prismatic follower + prismatic leader: dimensionless (distance / distance) revolute follower + prismatic leader: degrees per unit distance prismatic follower + revolute leader: distance per degree

Both the follower and the leader must participate in the same articulation (i.e. excludeFromArticulation = false) and must be enabled (jointEnabled = true). Toggling newton:mimicEnabled or changing newton:mimicJoint at runtime triggers a structural re-parse; changes to newton:mimicCoef0 / newton:mimicCoef1 are applied in-place without a re-parse.

Attribute Resolution Priority

When both Newton and PhysX schemas are applied to the same prim, the runtime resolves attribute values using the following priority (highest to lowest):

Priority	Source	Description
1	PhysX Schema (authored)	If the PhysX attribute has an explicitly authored value, it is always used.
2	Newton Schema (authored)	If the PhysX attribute is not authored but the corresponding Newton attribute has an authored value, the Newton value is used as a fallback.
3	PhysX Default	The PhysX schema default value (set during setToDefault()).
4	Newton Default	The Newton schema default. In practice this is never reached because the PhysX default (priority 3) is always set before Newton fallback is checked.

This means:

• Users who author only Newton schemas get correct PhysX behavior via fallback.

• Users who author both schemas always get the PhysX value when it is authored.

• Existing scenes with only PhysX schemas are completely unaffected.

Newton to PhysX Attribute Mapping

Newton Attribute	PhysX Attribute	Notes
newton:timeStepsPerSecond	physxScene:timeStepsPerSecond	Direct mapping.
newton:gravityEnabled	(scene gravity magnitude)	When false, gravity magnitude is set to 0 for the entire scene. When true (default), per-body physxRigidBody:disableGravity flags are still respected.
newton:selfCollisionEnabled	physxArticulation:enabledSelfCollisions	Direct mapping.
newton:contactMargin	physxCollision:restOffset	Direct mapping. Both represent the outward surface inflation distance.
newton:contactGap	physxCollision:contactOffset	Not a direct mapping. Newton contactGap is additive on top of contactMargin, whereas PhysX contactOffset is measured from the original shape surface. The runtime computes: contactOffset = contactMargin + contactGap. Newton’s -inf sentinel is ignored (PhysX default is used instead).
newton:maxHullVertices	physxConvexHullCollision:hullVertexLimit / physxConvexDecompositionCollision:hullVertexLimit	Applies to both convex hull and convex decomposition approximations. Newton’s -1 sentinel (no limit) is ignored.
newton:mimicCoef1	physxMimicJoint:gearing (negated)	Newton’s equation joint0 = coef0 + coef1 * joint1 is rewritten into PhysX’s joint0 + gearing * joint1 + offset = 0 form, so the PhysX gearing is -coef1.
newton:mimicCoef0	physxMimicJoint:offset (negated)	Similarly, the PhysX offset is -coef0. The Newton equation is implemented as a hard constraint (physxMimicJoint:naturalFrequency = 0, physxMimicJoint:dampingRatio = 0).
newton:mimicEnabled	(presence of the mimic constraint)	When false the mimic constraint is not created. Toggling this attribute at runtime triggers a structural re-parse.
newton:mimicJoint	physxMimicJoint:referenceJoint	Relationship to the leader joint. Changing this relationship at runtime triggers a structural re-parse.

Deprecated PhysX Attributes

The following PhysX attributes are deprecated in favor of their Newton equivalents. The NewtonMigrationChecker validation rule in omni.physx.asset_validator detects authored deprecated attributes and offers an auto-fix that migrates the value to the Newton schema and removes the PhysX attribute.

Note that the migration of collision offsets involves a conversion: newton:contactGap = physxCollision:contactOffset - physxCollision:restOffset, because Newton’s gap is additive on top of margin while PhysX’s contactOffset is measured from the shape surface.

Deprecated PhysX Attribute	Replacement Newton Attribute	Newton API
physxScene:timeStepsPerSecond	newton:timeStepsPerSecond	NewtonSceneAPI
physxCollision:contactOffset	newton:contactGap	NewtonCollisionAPI
physxCollision:restOffset	newton:contactMargin	NewtonCollisionAPI
physxArticulation:enabledSelfCollisions	newton:selfCollisionEnabled	NewtonArticulationRootAPI