Add NewtonJointAPI schema for joint solver configuration

andrewkaufman · andrewkaufman · commit e1fabb3cbdcb · 2026-06-26T02:21:03.000Z
Single-apply schema on PhysicsJoint prims providing six attributes that
broadcast uniformly to every DOF:

- newton:armature: artificial per-DOF inertia for solver stability
- newton:damping: passive velocity-proportional damping (always active)
- newton:friction: dry (Coulomb) friction effort opposing motion
- newton:velocityLimit: maximum DOF velocity (inf = unlimited)
- newton:limitStiffness: limit spring stiffness (-inf = engine default)
- newton:limitDamping: limit spring damping (-inf = engine default)

All attributes use degrees for angular DOFs. Hard minimum of 0 enforced
on armature, damping, friction, and velocityLimit. Limit spring
attributes activate when DOF position exceeds the range defined by the
joint limits; position-based solvers may ignore them.

Registered as NewtonPhysicsJointAPI in plugInfo.json with
apiSchemaCanOnlyApplyTo: ["PhysicsJoint"].
diff --git a/newton_usd_schemas/generatedSchema.usda b/newton_usd_schemas/generatedSchema.usda
@@ -368,6 +368,123 @@ class NewtonArticulationRootAPI "NewtonArticulationRootAPI" (
     )
 }
 
+class NewtonJointAPI "NewtonJointAPI" (
+    doc = """`NewtonJointAPI` applies on top of a `PhysicsJoint`, providing
+    joint configuration for solver behavior, passive dynamics, and limit spring response.
+
+    All scalar attributes broadcast uniformly to every DOF of the joint.
+    Angular attributes use degrees."""
+)
+{
+    float newton:armature = 0 (
+        doc = """Artificial inertia added to each degree of freedom for solver stability.
+
+        In reduced-coordinate solvers this augments the joint-space mass
+        matrix diagonal. In maximal-coordinate solvers it regularizes the
+        constraint system along the joint's DOF directions.
+
+        The value is broadcast to all DOFs of the joint.
+
+        Range: [0, inf)
+        Units: mass * distance * distance (angular DOFs) or mass (linear DOFs)."""
+        limits = {
+            dictionary hard = {
+                float minimum = 0
+            }
+        }
+    )
+
+    float newton:damping = 0 (
+        doc = """Passive velocity-proportional damping applied to each DOF.
+
+        Produces a resistive effort proportional to joint velocity:
+        `effort = -damping * velocity`. This damping is always active,
+        regardless of whether limits are violated or drive targets are set.
+
+        The value is broadcast to all DOFs of the joint.
+
+        Range: [0, inf)
+        Units: effort * seconds / degrees (angular DOFs) or effort * seconds / distance (linear DOFs)."""
+        limits = {
+            dictionary hard = {
+                float minimum = 0
+            }
+        }
+    )
+
+    float newton:friction = 0 (
+        doc = """Dry (Coulomb) friction effort opposing joint motion.
+
+        A constant resistive effort that opposes the direction of motion,
+        independent of velocity magnitude. The joint must be moving for
+        this effort to apply.
+
+        The value is broadcast to all DOFs of the joint.
+
+        Range: [0, inf)
+        Units: effort."""
+        limits = {
+            dictionary hard = {
+                float minimum = 0
+            }
+        }
+    )
+
+    float newton:velocityLimit = inf (
+        doc = """Maximum allowable DOF velocity.
+
+        The solver clamps each DOF's velocity to the range
+        `[-velocityLimit, +velocityLimit]` at every time step.
+        A value of `inf` means no velocity clamping is applied.
+
+        The value is broadcast to all DOFs of the joint.
+
+        Range: (0, inf]
+        Units: degrees / seconds (angular DOFs) or distance / seconds (linear DOFs)."""
+        limits = {
+            dictionary hard = {
+                float minimum = 0
+            }
+        }
+    )
+
+    float newton:limitStiffness = -inf (
+        doc = """Stiffness of the joint limit spring.
+
+        When a DOF's position exceeds the range defined by the joint limits,
+        a restoring effort is applied: `effort = limitStiffness * penetration`,
+        where penetration is the signed distance beyond the limit boundary.
+
+        Not all solvers use soft limit springs. Position-based solvers may
+        enforce limits as hard positional constraints and ignore this attribute.
+
+        A value of `-inf` means the engine's own default stiffness is used.
+
+        The value is broadcast to all DOFs of the joint.
+
+        Range: [0, inf) when authored (sentinel `-inf` defers to engine default).
+        Units: effort / degrees (angular DOFs) or effort / distance (linear DOFs)."""
+    )
+
+    float newton:limitDamping = -inf (
+        doc = """Damping of the joint limit spring.
+
+        When a DOF's position exceeds the range defined by the joint limits,
+        a velocity-dependent dissipative effort is applied:
+        `effort = -limitDamping * velocity`.
+
+        Not all solvers use soft limit springs. Position-based solvers may
+        enforce limits as hard positional constraints and ignore this attribute.
+
+        A value of `-inf` means the engine's own default damping is used.
+
+        The value is broadcast to all DOFs of the joint.
+
+        Range: [0, inf) when authored (sentinel `-inf` defers to engine default).
+        Units: effort * seconds / degrees (angular DOFs) or effort * seconds / distance (linear DOFs)."""
+    )
+}
+
 class NewtonMassAPI "NewtonMassAPI" (
     apiSchemas = ["PhysicsMassAPI"]
     doc = """`NewtonMassAPI` applies on top of an `Xformable`, providing extra mass attributes for Newton.
diff --git a/newton_usd_schemas/plugInfo.json b/newton_usd_schemas/plugInfo.json
@@ -56,6 +56,20 @@
               ],
               "schemaKind": "singleApplyAPI"
             },
+            "NewtonPhysicsJointAPI": {
+              "schemaIdentifier": "NewtonJointAPI",
+              "alias": {
+                "UsdSchemaBase": "NewtonJointAPI"
+              },
+              "autoGenerated": false,
+              "bases": [
+                "UsdAPISchemaBase"
+              ],
+              "schemaKind": "singleApplyAPI",
+              "apiSchemaCanOnlyApplyTo": [
+                "PhysicsJoint"
+              ]
+            },
             "NewtonPhysicsMassAPI": {
               "schemaIdentifier": "NewtonMassAPI",
               "alias": {
diff --git a/tests/test_joint.py b/tests/test_joint.py
@@ -0,0 +1,157 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 The Newton Developers
+# SPDX-License-Identifier: Apache-2.0
+
+import math
+import unittest
+
+from pxr import Plug, Usd, UsdPhysics
+
+import newton_usd_schemas  # noqa: F401
+
+USD_HAS_LIMITS = Usd.GetVersion() >= (0, 25, 11)
+
+
+class TestNewtonJointAPI(unittest.TestCase):
+    def setUp(self):
+        self.stage: Usd.Stage = Usd.Stage.CreateInMemory()
+        self.revolute: Usd.Prim = UsdPhysics.RevoluteJoint.Define(self.stage, "/Revolute").GetPrim()
+
+    def test_api_registered(self):
+        plug_type = Plug.Registry().FindTypeByName("NewtonPhysicsJointAPI")
+        self.assertEqual(plug_type.typeName, "NewtonPhysicsJointAPI")
+        schema_type = Usd.SchemaRegistry().GetSchemaTypeName("NewtonPhysicsJointAPI")
+        self.assertEqual(schema_type, "NewtonJointAPI")
+
+    def test_api_application(self):
+        self.assertFalse(self.revolute.HasAPI("NewtonJointAPI"))
+        self.revolute.ApplyAPI("NewtonJointAPI")
+        self.assertTrue(self.revolute.HasAPI("NewtonJointAPI"))
+
+        self.assertTrue(self.revolute.HasAttribute("newton:armature"))
+        self.assertTrue(self.revolute.HasAttribute("newton:damping"))
+        self.assertTrue(self.revolute.HasAttribute("newton:friction"))
+        self.assertTrue(self.revolute.HasAttribute("newton:velocityLimit"))
+        self.assertTrue(self.revolute.HasAttribute("newton:limitStiffness"))
+        self.assertTrue(self.revolute.HasAttribute("newton:limitDamping"))
+
+    def test_api_application_prismatic(self):
+        prismatic = UsdPhysics.PrismaticJoint.Define(self.stage, "/Prismatic").GetPrim()
+        self.assertTrue(prismatic.CanApplyAPI("NewtonJointAPI"))
+        prismatic.ApplyAPI("NewtonJointAPI")
+        self.assertTrue(prismatic.HasAPI("NewtonJointAPI"))
+
+    def test_api_application_spherical(self):
+        spherical = UsdPhysics.SphericalJoint.Define(self.stage, "/Spherical").GetPrim()
+        self.assertTrue(spherical.CanApplyAPI("NewtonJointAPI"))
+        spherical.ApplyAPI("NewtonJointAPI")
+        self.assertTrue(spherical.HasAPI("NewtonJointAPI"))
+
+    def test_api_application_d6(self):
+        d6 = UsdPhysics.Joint.Define(self.stage, "/D6").GetPrim()
+        self.assertTrue(d6.CanApplyAPI("NewtonJointAPI"))
+        d6.ApplyAPI("NewtonJointAPI")
+        self.assertTrue(d6.HasAPI("NewtonJointAPI"))
+
+    def test_api_limitations(self):
+        xform: Usd.Prim = self.stage.DefinePrim("/NotJoint", "Xform")
+        self.assertFalse(xform.CanApplyAPI("NewtonJointAPI"))
+
+    def test_armature(self):
+        self.revolute.ApplyAPI("NewtonJointAPI")
+        attr = self.revolute.GetAttribute("newton:armature")
+        self.assertIsNotNone(attr)
+        self.assertFalse(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 0.0)
+
+        success = attr.Set(0.01)
+        self.assertTrue(success)
+        self.assertTrue(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 0.01)
+
+        if USD_HAS_LIMITS:
+            hard = attr.GetHardLimits()
+            self.assertTrue(hard.IsValid())
+            self.assertAlmostEqual(hard.GetMinimum(), 0.0)
+            self.assertIsNone(hard.GetMaximum())
+
+    def test_damping(self):
+        self.revolute.ApplyAPI("NewtonJointAPI")
+        attr = self.revolute.GetAttribute("newton:damping")
+        self.assertIsNotNone(attr)
+        self.assertFalse(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 0.0)
+
+        success = attr.Set(5.0)
+        self.assertTrue(success)
+        self.assertTrue(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 5.0)
+
+        if USD_HAS_LIMITS:
+            hard = attr.GetHardLimits()
+            self.assertTrue(hard.IsValid())
+            self.assertAlmostEqual(hard.GetMinimum(), 0.0)
+            self.assertIsNone(hard.GetMaximum())
+
+    def test_friction(self):
+        self.revolute.ApplyAPI("NewtonJointAPI")
+        attr = self.revolute.GetAttribute("newton:friction")
+        self.assertIsNotNone(attr)
+        self.assertFalse(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 0.0)
+
+        success = attr.Set(0.5)
+        self.assertTrue(success)
+        self.assertTrue(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 0.5)
+
+        if USD_HAS_LIMITS:
+            hard = attr.GetHardLimits()
+            self.assertTrue(hard.IsValid())
+            self.assertAlmostEqual(hard.GetMinimum(), 0.0)
+            self.assertIsNone(hard.GetMaximum())
+
+    def test_velocity_limit(self):
+        self.revolute.ApplyAPI("NewtonJointAPI")
+        attr = self.revolute.GetAttribute("newton:velocityLimit")
+        self.assertIsNotNone(attr)
+        self.assertFalse(attr.HasAuthoredValue())
+        self.assertEqual(attr.Get(), math.inf)
+
+        success = attr.Set(360.0)
+        self.assertTrue(success)
+        self.assertTrue(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 360.0)
+
+        if USD_HAS_LIMITS:
+            hard = attr.GetHardLimits()
+            self.assertTrue(hard.IsValid())
+            self.assertAlmostEqual(hard.GetMinimum(), 0.0)
+            self.assertIsNone(hard.GetMaximum())
+
+    def test_limit_stiffness(self):
+        self.revolute.ApplyAPI("NewtonJointAPI")
+        attr = self.revolute.GetAttribute("newton:limitStiffness")
+        self.assertIsNotNone(attr)
+        self.assertFalse(attr.HasAuthoredValue())
+        self.assertEqual(attr.Get(), -math.inf)
+
+        success = attr.Set(174.5)
+        self.assertTrue(success)
+        self.assertTrue(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 174.5)
+
+    def test_limit_damping(self):
+        self.revolute.ApplyAPI("NewtonJointAPI")
+        attr = self.revolute.GetAttribute("newton:limitDamping")
+        self.assertIsNotNone(attr)
+        self.assertFalse(attr.HasAuthoredValue())
+        self.assertEqual(attr.Get(), -math.inf)
+
+        success = attr.Set(0.1745)
+        self.assertTrue(success)
+        self.assertTrue(attr.HasAuthoredValue())
+        self.assertAlmostEqual(attr.Get(), 0.1745)
+
+
+if __name__ == "__main__":
+    unittest.main()
