PhysxSceneAPI#

PhysX tuning for a PhysicsScene prim: solver, broadphase, flags, friction thresholds, iteration bounds and GPU memory budgets. Read only when PhysxSceneAPI is listed in usd-schemas of a PhysicsScene prim. Two friction columns have units-scaled defaults that the raw schema fallback does not reproduce; the producer creates them even without the API.

  • Applies to: Typed

  • Read only when listed in usd-schemas.

  • Uses blocks: stage_units

What USD population writes#

Every declared attribute is published at its resolved value on a PhysicsScene prim that applies the API. Two columns are rewritten when unauthored and CREATED on every PhysicsScene prim even when this API is not applied: physxScene:frictionOffsetThreshold = 0.04 / metersPerUnit and physxScene:frictionCorrelationDistance = 0.025 / metersPerUnit. Those values equal the consumer’s absent-column defaults, so on a producer-populated stage the raw schema fallbacks never reach the consumer.

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

physxScene:timeStepsPerSecond

uint32

1/s

60

resolved USD value (authored, else raw fallback)

60

60 Hz. An absent or out-of-range value also lets newton:timeStepsPerSecond on the same prim take over (see PhysicsScene notes).

physxScene:solverType

uint64, TOKEN_ID

none

TGS

resolved USD value (authored, else raw fallback)

TGS

TGS. Accepted tokens: TGS, PGS. An unrecognised token leaves TGS.

physxScene:broadphaseType

uint64, TOKEN_ID

none

GPU

resolved USD value (authored, else raw fallback)

GPU

GPU. Accepted tokens: SAP, MBP, GPU. An unrecognised token leaves GPU. GPU broadphase falls back to PxBroadPhaseType::ePABP when no CUDA context manager exists (CPU-only process or CPU mode), with a warning.

physxScene:collisionSystem

uint64, TOKEN_ID

none

PCM

resolved USD value (authored, else raw fallback)

PCM

PCM. Only the token SAT is tested; PCM is the default and any other token is a no-op that leaves PCM.

physxScene:updateType

uint64, TOKEN_ID

none

Synchronous

resolved USD value (authored, else raw fallback)

Synchronous

Synchronous. Accepted tokens: Synchronous, Asynchronous, Disabled (capitalised, as the schema declares them). An unrecognised token leaves Synchronous.

physxScene:enableCCD

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off.

physxScene:enableStabilization

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off.

physxScene:enableGPUDynamics

bool8

none

true

resolved USD value (authored, else raw fallback)

true

On. The runtime honours it only when a CUDA context manager exists; on a CPU-only process the PhysX flag is forced off with a warning (silently when CPU mode was requested explicitly).

physxScene:enableEnhancedDeterminism

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off.

physxScene:enableExternalForcesEveryIteration

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off. Silently forced to off when physxScene:solverType is PGS (unsupported there).

physxScene:invertCollisionGroupFilter

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off: collision groups list the groups they do NOT collide with. On, physics:filteredGroups lists the groups a group DOES collide with, for every group in the scene.

physxScene:reportKinematicKinematicPairs

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off: kinematic-kinematic pairs are suppressed before the filter shader and never reported.

physxScene:reportKinematicStaticPairs

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off: kinematic-static pairs are suppressed before the filter shader and never reported.

physxScene:enableSceneQuerySupport

bool8

none

true

resolved USD value (authored, else raw fallback)

true

On. Off sets the scene query update mode to eBUILD_DISABLED_COMMIT_DISABLED: no scene query structure is built, raycasts and overlaps see nothing.

physxScene:solveArticulationContactLast

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off.

physxScene:disableSleeping

bool8

none

false

resolved USD value (authored, else raw fallback)

false

Off. The runtime also raises the PhysX flag on its own when GPU dynamics runs with readback suppressed.

physxScene:bounceThreshold

float32

length/s

0.0

resolved USD value (authored, else raw fallback)

1e-06

1e-6, effectively every contact bounces. NOT units-scaled: the same 1e-6 on a meter and on a centimeter stage (PhysX’s own default would be 0.2 * tolerances speed). The raw fallback 0 is clamped up to the same 1e-6, so writing it literally is harmless.

physxScene:frictionOffsetThreshold

float32

length

0.04

when unauthored: 0.04 / metersPerUnit (column created even without the API)

0.04 / metersPerUnit diverges

Units-scaled default: 0.04 on a meter stage, 4 on a centimeter stage. Writing the raw fallback 0.04 on a centimeter stage makes friction anchors 100 times too short-lived. The producer writes the scaled value and creates the column even without PhysxSceneAPI applied; the consumer ignores it unless PhysxSceneAPI is in usd-schemas.

physxScene:frictionCorrelationDistance

float32

length

0.025

when unauthored: 0.025 / metersPerUnit (column created even without the API)

0.025 / metersPerUnit diverges

Units-scaled default: 0.025 on a meter stage, 2.5 on a centimeter stage. Writing the raw fallback literally on a non-meter stage diverges the same way as frictionOffsetThreshold. Created by the producer even without PhysxSceneAPI applied.

physxScene:maxBiasCoefficient

float32

none

inf

resolved USD value (authored, else raw fallback)

FLT_MAX

FLT_MAX, no cap on the constraint bias. +inf clamps to FLT_MAX, so writing the raw fallback literally is harmless.

physxScene:minPositionIterationCount

uint32

none

1

resolved USD value (authored, else raw fallback)

0 diverges

0: no lower bound on a body’s solverPositionIterationCount. The raw fallback is 1, so a producer-populated stage clamps bodies authored with 0 position iterations up to 1 while an omitted column does not. Silently clamped down to physxScene:maxPositionIterationCount when it exceeds it.

physxScene:maxPositionIterationCount

uint32

none

255

resolved USD value (authored, else raw fallback)

255

255: no upper bound in practice.

physxScene:minVelocityIterationCount

uint32

none

0

resolved USD value (authored, else raw fallback)

0

0. Silently clamped down to physxScene:maxVelocityIterationCount when it exceeds it.

physxScene:maxVelocityIterationCount

uint32

none

255

resolved USD value (authored, else raw fallback)

255

255.

physxScene:gpuTempBufferCapacity

uint64

none

16777216

resolved USD value (authored, else raw fallback)

16777216

16777216. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuMaxRigidContactCount

uint32

none

524288

resolved USD value (authored, else raw fallback)

524288

524288. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuMaxRigidPatchCount

uint32

none

81920

resolved USD value (authored, else raw fallback)

81920

81920. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuHeapCapacity

uint32

none

67108864

resolved USD value (authored, else raw fallback)

67108864

67108864. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuFoundLostPairsCapacity

uint32

none

262144

resolved USD value (authored, else raw fallback)

262144

262144. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuFoundLostAggregatePairsCapacity

uint32

none

1024

resolved USD value (authored, else raw fallback)

1024

1024. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuTotalAggregatePairsCapacity

uint32

none

1024

resolved USD value (authored, else raw fallback)

1024

1024. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuMaxDeformableVolumeContacts

uint32

none

1048576

resolved USD value (authored, else raw fallback)

1048576

1048576. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuMaxDeformableSurfaceContacts

uint32

none

1048576

resolved USD value (authored, else raw fallback)

1048576

1048576. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuMaxParticleContacts

uint32

none

1048576

resolved USD value (authored, else raw fallback)

1048576

1048576. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuCollisionStackSize

uint32

none

67108864

resolved USD value (authored, else raw fallback)

67108864

67108864. Read unclamped and written unconditionally (the schema fallback lands in the descriptor when the column is absent).

physxScene:gpuMaxNumPartitions

uint32

none

8

resolved USD value (authored, else raw fallback)

8

8. Clamped to [1, 32], then any value that is not a power of two is silently reset to 8.

physxScene:envIdInBoundsBitCount

int32

none

not written

-1

-1, the unset sentinel: the GPU broadphase environment-id bit layout is left at the PhysX default. Read ONLY when the resolved broadphase is GPU, and then regardless of whether PhysxSceneAPI is applied; under SAP or MBP the column is ignored.

Interactions#

  • PhysicsScene: Enumeration is by the PhysicsScene prim type (see that component); this API only adds columns to a scene that already exists. The gravity columns stay on PhysicsScene.

  • PhysxRigidBodyAPI: min/max position and velocity iteration counts bound every body’s physxRigidBody:solverPositionIterationCount / solverVelocityIterationCount in this scene.

  • PhysicsCollisionGroup: physxScene:invertCollisionGroupFilter flips the meaning of physics:filteredGroups for every group; the per-group physics:invertFilteredGroups is not read.

  • stage_units: frictionOffsetThreshold and frictionCorrelationDistance default to 0.04 and 0.025 times the tolerances length (1 / metersPerUnit). bounceThreshold does not scale.

Known divergences#

  • fragile (consumer) physxScene:bounceThreshold: The consumer default 1e-6 is not units-scaled while every neighbouring length default is, and the raw schema fallback 0 is clamped up to it. A centimeter stage therefore bounces on contacts 100 times slower (relative to its units) than a meter stage would.

  • note (consumer) physxScene:minPositionIterationCount: Raw schema fallback 1 versus consumer absent default 0: only bodies authored with 0 position iterations observe the difference. When min exceeds max (either pair) min is silently clamped down to max; the diagnostic is emitted by the USD schema parser only, so an ovstage-populated stage gets no warning.

  • note (consumer) physxScene:enableExternalForcesEveryIteration: Silently cleared when solverType is PGS; the warning exists only on the USD path.

  • note (consumer) physxScene:gpuMaxNumPartitions: A value in [1, 32] that is not a power of two is silently replaced by 8 rather than rounded.

  • fragile (consumer) physxScene:timeStepsPerSecond: The authored-bit gates (readClampedIfAuthored, readBoolIfAuthored) are no-ops on ovstage where every column reads as authored, so the resolved value always wins and a value equal to the raw fallback is indistinguishable from unauthored. This is what makes the newton:timeStepsPerSecond fallback unreachable on a producer-populated stage: the published 60 counts as authored.

  • fragile (consumer) physxScene:maxBiasCoefficient: Whether the authored value takes effect depends on the solver configuration, not on the stage: PhysX applies PxSceneDesc::maxBiasCoefficient in the PGS and GPU dynamics contexts but the CPU TGS context constructs with PX_MAX_F32 (physx DyTGSDynamics.cpp), so with solverType TGS and enableGPUDynamics false the column is silently ignored and PxScene::getMaxBiasCoefficient returns FLT_MAX. Observed in the population contract test (authored 10, read FLT_MAX).

Notes#

  • physxScene:frictionType (token, fallback patch) is declared by the schema and prefetched by the walker but never read: PhysX has a single friction model now and the attribute is deprecated. It is not a column of this contract.

  • Token columns (solverType, broadphaseType, collisionSystem, updateType) carry no verify block because the generator turns a sample into a numeric literal; the PhysX observation for each is given in the column notes so a later generator extension can pick them up.

  • The contract test scene runs on CPU: enableGPUDynamics is observed as forced off and broadphaseType GPU resolves to ePABP there. Samples that require a GPU (GPU broadphase, GPU dynamics on) are deliberately not given.

  • physxScene:maxIterationCount does not exist in the schema or the consumer.

  • Process-wide runtime settings (solver type override, GPU pipeline override, suppress readback, multi-GPU mode) can override solverType, broadphaseType, enableGPUDynamics, enableCCD and disableSleeping after parsing; the contract describes the un-overridden path.