PhysxSurfaceVelocityAPI

Conveyor-belt surface velocity on a rigid body: contacts against the body behave as if its surface moved with the given linear and angular velocity while the body itself stays put. Read only on dynamic bodies and articulation links (parseDynamicBody); a static body ignores it.

• Applies to: Xformable

• Requires on the same prim: PhysicsRigidBodyAPI

• Read only when listed in usd-schemas.

• Uses blocks: prim

What USD population writes

Every declared attribute is published at its resolved value. Nothing is rewritten or created by the producer.

Columns

Raw fallback is the USD schema value. Producer writes is what ovstage population puts in the column for a USD stage. Parser default applies on the consumer when the column is absent, in stage units. diverges means writing the raw fallback literally parses differently from omitting the column (the parser default): USD population may well publish that very value for an unauthored attribute, so the marker is about the column being present, not about its value.

Column	Type	Units	Raw fallback	Producer writes	Parser default	If absent
physxSurfaceVelocity:surfaceVelocityEnabled	bool8	none	true	resolved USD value (authored, else raw fallback)	true	On: applying the API with nothing authored enables surface velocity (with zero velocities, i.e. a body whose contacts are solved as if its surface were static).
physxSurfaceVelocity:surfaceVelocityLocalSpace	bool8	none	true	resolved USD value (authored, else raw fallback)	true	On: physxSurfaceVelocity:surfaceVelocity is in the body’s local frame and the per-axis world scale is folded into it at parse time.
physxSurfaceVelocity:surfaceVelocity	float32[3], VECTOR	length/s	(0, 0, 0)	resolved USD value (authored, else raw fallback)	(0, 0, 0)	Zero linear surface velocity. When surfaceVelocityLocalSpace is true the parser multiplies each component by the matching component of the prim’s decomposed world scale (no rotation); the pre-fold value is kept separately because the fold is not invertible (a zero scale component loses the axis).
physxSurfaceVelocity:surfaceAngularVelocity	float32[3], VECTOR	deg/s (deg_to_rad)	(0, 0, 0)	resolved USD value (authored, else raw fallback)	(0, 0, 0)	Zero angular surface velocity. Authored in deg/s, converted to rad/s by the parser; no scale fold. The pivot is the body’s global pose at creation.

Interactions

• PhysicsRigidBodyAPI: Legacy promotion: a body with physics:kinematicEnabled true and a non-zero physics:velocity or physics:angularVelocity is treated as a surface-velocity body (enabled, world space, velocities copied) even without this API. When this API is applied it runs afterwards and fully overrides that promotion; the API is not restricted to kinematic bodies.

• prim: With surfaceVelocityLocalSpace true the decomposed world scale of this prim is folded component-wise into surfaceVelocity. Rotation is never applied at parse time.

• PhysxSplinesSurfaceVelocityAPI: Mutually exclusive: when both surfaceVelocityEnabled and the splines surfaceVelocityEnabled are true, the splines one is forced off.