Prepare applied USD schema fallback precedence

CHANGELOG.md

@@ -36,6 +36,8 @@
 
 ### Changed
 
+- Detect applied but unauthored USD schema properties whose schema fallbacks will change resolver results in a future release, while retaining the current values during the compatibility period; pass ``use_applied_schema_fallbacks=True`` to opt into the future behavior.
+
 - Compile tiled camera render kernels with CUDA fast math by default for faster rendering; set `SensorTiledCamera.render_config.enable_fast_math = False` for bit-exact, IEEE-precise output.
 - Optimize raycast/raytrace queries by restructuring ray-shape intersection into local-space primitives and compile specialized depth/shadow variants that skip unused surface-normal work (mesh shadows also use any-hit queries).
 - Change experimental `SolverVBD` cable constraint slots from `[STRETCH=0, BEND=1]` to `[STRETCH=0, SHEAR=1, BEND=2, TWIST=3]`, allowing each stiffness and constraint mode to be configured independently. Existing cable calls using raw `slot=1` or `JointSlot.ANGULAR` now select shear; use `JointSlot.BEND` (now slot 2) to select bending.

docs/concepts/usd_parsing.rst

@@ -474,7 +474,19 @@ The attribute resolution process follows a three-layer fallback hierarchy to det
 
 1. **Authored Values**: Resolvers are queried in priority order; the first resolver that finds an authored value on the prim returns it and remaining resolvers are not consulted.
 2. **Importer Defaults**: If no authored value is found, Newton's importer uses a property-specific fallback (e.g. ``builder.default_joint_cfg.armature`` for joint armature). This takes precedence over schema-level defaults.
-3. **Approximated Schema Defaults**: If neither an authored value nor an importer default is available, Newton falls back to a hardcoded approximation of each solver's schema default, defined in Newton's resolver mapping. These approximations will be replaced by actual USD schema defaults in a future release.
+3. **Resolver Compatibility Defaults**: If neither an authored value nor an importer default is available, Newton falls back to the resolver mapping's compatibility default.
+
+This order is retained during a compatibility period. In the future, applying a
+schema will give it ownership of its properties: an unauthored property will use
+its schema fallback before a lower-priority resolver or importer default.
+Registered schema definitions supply fallbacks when available. Built-in
+resolvers provide equivalent fallback data for supported schemas without public
+plugins, so registration does not affect priority. Newton emits a
+:class:`DeprecationWarning` when the future rule would select a different value
+or source. Author the intended property value explicitly to preserve it across
+the transition, or pass
+``use_applied_schema_fallbacks=True`` to adopt the future behavior now without
+migration warnings.
 
 **Configuring Resolver Priority:**
 

newton/_src/sim/builder.py

@@ -3395,6 +3395,7 @@ def add_usd(
         parse_mujoco_options: bool = True,
         mesh_maxhullvert: int | None = None,
         schema_resolvers: list[SchemaResolver] | None = None,
+        use_applied_schema_fallbacks: bool = False,
         force_position_velocity_actuation: bool = False,
         convert_mjc_equality_constraints: bool = True,
         override_root_xform: bool = False,
@@ -3519,7 +3520,15 @@ def add_usd(
 
                 .. experimental::
 
-                    The ``schema_resolvers`` argument may change without prior notice.
+                    The ``schema_resolvers`` and ``use_applied_schema_fallbacks``
+                    arguments may change without prior notice.
+            use_applied_schema_fallbacks: True uses an applied schema's USD fallback
+                before importer defaults and lower-priority resolvers, opting into the
+                future behavior without migration warnings. Registered schema
+                definitions supply fallbacks when available; built-in resolvers may
+                supply them for schemas without public plugins. False explicitly
+                retains legacy resolution and is the default during the compatibility
+                period.
             force_position_velocity_actuation: If True and both stiffness (kp) and damping (kd)
                 are non-zero, joints use :attr:`~newton.JointTargetMode.POSITION_VELOCITY` actuation mode.
                 If False (default), actuator modes are inferred per joint via :func:`newton.JointTargetMode.from_gains`:
@@ -3639,6 +3648,7 @@ def add_usd(
             parse_mujoco_options=parse_mujoco_options,
             mesh_maxhullvert=mesh_maxhullvert,
             schema_resolvers=schema_resolvers,
+            use_applied_schema_fallbacks=use_applied_schema_fallbacks,
             force_position_velocity_actuation=force_position_velocity_actuation,
             convert_mjc_equality_constraints=convert_mjc_equality_constraints,
             override_root_xform=override_root_xform,

newton/_src/usd/_missing_schema_fallbacks.py

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 The Newton Developers
+# SPDX-License-Identifier: Apache-2.0
+
+"""Fallbacks for USD schemas without public schema packages."""
+
+from __future__ import annotations
+
+import struct
+from typing import Any
+
+
+def _f32(value: float) -> float:
+    return struct.unpack("f", struct.pack("f", value))[0]
+
+
+_PHYSX_LIMIT_AXES = ("linear", "angular", "transX", "transY", "transZ", "rotX", "rotY", "rotZ")
+_JOINT_STATE_AXES = ("linear", "angular", "rotX", "rotY", "rotZ")
+
+
+# Subset of physx-usd-schemas 25.11.1 used by SchemaResolverPhysx.
+_PHYSX_SCHEMA_FALLBACKS: dict[str, dict[str, Any]] = {
+    "PhysxSceneAPI": {
+        "physxScene:maxVelocityIterationCount": 255,
+        "physxScene:timeStepsPerSecond": 60,
+    },
+    "PhysxRigidBodyAPI": {
+        "physxRigidBody:disableGravity": False,
+        "physxRigidBody:linearDamping": 0.0,
+        "physxRigidBody:angularDamping": _f32(0.05),
+    },
+    "PhysxJointAPI": {
+        "physxJoint:armature": 0.0,
+        "physxJoint:maxJointVelocity": float("inf"),
+    },
+    "PhysxConvexHullCollisionAPI": {
+        "physxConvexHullCollision:hullVertexLimit": 64,
+    },
+    "PhysxCollisionAPI": {
+        "physxCollision:contactOffset": float("-inf"),
+        "physxCollision:restOffset": float("-inf"),
+    },
+    "PhysxMaterialAPI": {
+        "physxMaterial:compliantContactStiffness": 0.0,
+        "physxMaterial:compliantContactDamping": 0.0,
+    },
+    "PhysxArticulationAPI": {
+        "physxArticulation:enabledSelfCollisions": True,
+    },
+    **{
+        f"PhysxLimitAPI:{axis}": {
+            f"physxLimit:{axis}:stiffness": 0.0,
+            f"physxLimit:{axis}:damping": 0.0,
+        }
+        for axis in _PHYSX_LIMIT_AXES
+    },
+    **{
+        f"PhysicsJointStateAPI:{axis}": {
+            f"state:{axis}:physics:position": 0.0,
+            f"state:{axis}:physics:velocity": 0.0,
+        }
+        for axis in _JOINT_STATE_AXES
+    },
+}
+
+
+# MJC does not yet publish its USD schema resources.
+_MJC_SCHEMA_FALLBACKS: dict[str, dict[str, Any]] = {
+    "MjcSceneAPI": {
+        "mjc:option:iterations": 100,
+        "mjc:option:timestep": 0.002,
+        "mjc:flag:gravity": True,
+    },
+    "MjcJointAPI": {
+        "mjc:armature": 0.0,
+        "mjc:frictionloss": 0.0,
+        "mjc:solreflimit": [0.02, 1.0],
+    },
+    "MjcMeshCollisionAPI": {
+        "mjc:maxhullvert": -1,
+    },
+    "MjcCollisionAPI": {
+        "mjc:margin": 0.0,
+        "mjc:gap": 0.0,
+        "mjc:shellinertia": False,
+        "mjc:solref": [0.02, 1.0],
+    },
+    "MjcMaterialAPI": {
+        "mjc:torsionalfriction": 0.005,
+        "mjc:rollingfriction": 0.0001,
+    },
+    "MjcActuator": {
+        "mjc:ctrlRange:min": 0.0,
+        "mjc:ctrlRange:max": 0.0,
+        "mjc:forceRange:min": 0.0,
+        "mjc:forceRange:max": 0.0,
+        "mjc:actRange:min": 0.0,
+        "mjc:actRange:max": 0.0,
+        "mjc:lengthRange:min": 0.0,
+        "mjc:lengthRange:max": 0.0,
+        "mjc:gainPrm": [1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+        "mjc:gainType": "fixed",
+        "mjc:biasPrm": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+        "mjc:biasType": "none",
+        "mjc:dynPrm": [1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+        "mjc:dynType": "none",
+        "mjc:gear": [1.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+    },
+}