Physics Schemas#
Physics behavior in a USD scene is described by schemas: typed sets of
attributes and relationships applied to prims. ovstage populates scenes authored
with these schemas into an ovstage.Stage; ovphysx attaches that stage and
simulates it. This page explains the schema layers ovphysx understands and how
to make the PhysX-specific ones available, both to ovstage when it populates a
scene and to a stock usd-core when you author or validate offline.
Schema Layers#
USD Physics Schema (
UsdPhysics) — the standard OpenUSD schema for annotating assets with physics:PhysicsScene,PhysicsRigidBodyAPI,PhysicsCollisionAPI,PhysicsMassAPI,PhysicsMaterialAPI, the joint types, and articulation APIs. It ships with stockusd-coreand has typed Python bindings, for exampleUsdPhysics.RigidBodyAPI.Apply(prim). Refer to the OpenUSD UsdPhysics reference.PhysX Schema (
Physx*, codeless) — extendsUsdPhysicswith PhysX-specific functionality and tuning:PhysxSceneAPI(solver, GPU settings),PhysxRigidBodyAPI(CCD, sleep, stabilization),PhysxCollisionAPI(contact and rest offsets),PhysxForceAPI, joint extensions such asPhysxJointAxisAPI(refer to Joints), deformable extensions (refer to Deformables), and more. ovphysx ships this schema as codeless artifacts (plugInfo.jsonplusgeneratedSchema.usda, no compiled library).Omni Physics Deformable Schema (codeless) — extends
UsdPhysicswith deformable bodies (OmniPhysicsDeformableBodyAPIand friends). Refer to Deformables.
The complete attribute set for each schema — types, defaults, and allowed values — is authoritative in the schema definitions themselves and is rendered in the Omni Physics documentation and the OpenUSD UsdPhysics reference. This guide describes intent, not full attribute definitions, so the two do not drift.
How ovphysx Ships the PhysX Schemas#
ovphysx exposes the PhysX USD schemas (PhysxSchema and
OmniUsdPhysicsDeformableSchema) as codeless artifacts: a root
plugInfo.json (with Includes: ["*/resources/"]) plus, per module, a
<Module>/resources/ directory holding a plugInfo.json (Type: resource) and
a generatedSchema.usda, with no compiled library. They live under
schemas/physx/ in the SDK and under ovphysx/schemas/physx/ in the wheel.
Codeless schemas carry no typed helper class — there is no
PhysxSchema.PhysxRigidBodyAPI binding. You apply them by identifier and author
their attributes generically.
ovphysx never modifies the environment (PXR_PLUGINPATH_NAME or any other
plugin-path variable) and leaves registration to the application; it verifies at
attach_ovstage that the registration happened before the first population and
refuses the attach otherwise. It tells the application where the schemas are:
C:
ovphysx_get_codeless_schema_root(ovphysx_string_t* out_root)returns the schema root directory. The string is NUL-terminated, owned by ovphysx, and valid until the calling thread calls the function again. It returnsOVPHYSX_API_INVALID_ARGUMENTfor a NULL argument andOVPHYSX_API_ERROR(details inovphysx_get_last_error()) when the schema tree is missing. It does not initialize ovphysx, load USD, acquire Carbonite, or modify the environment, and is safe to call beforeovphysx_create_instance().Python:
ovphysx.codeless_schema_root()returns the same root as apathlib.Path, andovphysx.codeless_schema_paths()returns the per-moduleresourcesdirectories. Both are pure Python and never trigger native loading.
Because they are codeless, the core UsdPhysics typed APIs (rigid body,
collider, mass, scene) work out of the box with stock usd-core, while
Physx* attributes require registering the codeless schemas first.
Making Schemas Available#
The application owns the USD runtime(s) in its process and registers the codeless schemas with each of them. There are two registration paths, depending on which USD runtime is in play.
Registering with ovstage#
ovstage ingests USD scenes through its own internal namespaced OpenUSD runtime,
and that runtime knows nothing about the PhysX schemas until the application
registers them. Register them once per process, before the first population call
(open_usd, apply_usd_changes, or an export), by passing the schema root to
ovstage.population.register_usd_schemas():
import ovphysx
import ovstage
ovstage.population.register_usd_schemas([str(ovphysx.codeless_schema_root())])
stage = ovstage.Stage("scene")
In C, obtain the root with ovphysx_get_codeless_schema_root() and pass it to
ovstage_population_register_usd_schemas():
#include <ovphysx/ovphysx.h>
#include <ovstage/ovstage.h>
#include <ovstage/ovstage_population.h>
static int register_physx_schemas(void)
{
ovphysx_string_t root;
if (ovphysx_get_codeless_schema_root(&root).status != OVPHYSX_API_SUCCESS)
{
return 0;
}
ovx_string_t path;
path.ptr = root.ptr;
path.length = root.length;
return ovstage_population_register_usd_schemas(&path, 1) == OVSTAGE_OK;
}
The bundled samples do exactly this: the Python samples call
register_usd_schemas() in their attach_scene helper right before creating
the ovstage.Stage, and the C samples call
ovphysx_sample_register_physx_schemas() from
tests/c_samples/common/ovstage_sample.h.
The ordering is not advisory. USD assembles its schema registry once, on first
read, and ignores plugins registered afterwards; a registration that arrives
after ovstage’s first schema read registers cleanly but contributes nothing,
and ovstage reports it as an error (OVSTAGE_ERROR_OP_FAILED, an
ovstage.OvstageError in Python). A registration that arrives after some other
USD consumer in the process read the schemas cannot be detected and fails
silently. No re-registration can repair the registry for the rest of the
process. Without the registration, population resolves only the properties
authored in the file rather than each prim’s full schema-declared property set.
Registration is process-scoped and irreversible; registering the same root
twice is a no-op.