Quickstart#

ovphysx is a self-contained SDK for USD-based physics simulation, available as a Python wheel and a C/C++ package. This guide shows how to get started with both. You learn the required SDK layout, CMake configuration, runtime setup, and where to go next.

Prerequisites#

For both Python and C:

  • Prepare a simple USD file such as scene.usda for the sample load call.

  • Install CUDA Toolkit and a compatible NVIDIA driver (recommended, but can be skipped if only CPU simulation is used).

Quick Start by Language#

Python#

Install the wheel:

pip install ovphysx

import ovphysx
from ovphysx import PhysX

physx = PhysX()
physx.add_usd("scene.usda")
physx.step(1.0 / 60.0, 0.0)
physx.release()

C/C++#

Download the ovphysx SDK package from the GitHub Releases page and extract it to a local path. You also need CMake 3.16 or newer and a C or C++ compiler.

SDK directory layout

ovphysx/
├── SKILLS.md             # Skills index
├── skills/               # Agent skills runbooks
├── include/ovphysx/     # Public headers (ovphysx.h, ovphysx_types.h, ...)
├── lib/                 # Shared libraries and CMake package config
│   └── cmake/ovphysx/   # find_package(ovphysx) support
├── plugins/             # Carbonite, PhysX, and USD runtime plugins
│   └── gpu/             # GPU-only plugins (loaded only when GPU is enabled)
├── samples/             # CI-tested C sample source + USD data
├── docs/                # Documentation (HTML + Markdown)
└── LICENSE.txt

Build Your First App

CMakeLists.txt

  1. Create a CMakeLists.txt file in your app directory.

    Add this minimal configuration:

cmake_minimum_required(VERSION 3.16)
project(MyApp C)

find_package(ovphysx REQUIRED)

add_executable(my_app main.c)
target_link_libraries(my_app PRIVATE ovphysx::ovphysx)

if(WIN32)
    ovphysx_copy_runtime_dlls(my_app)
endif()

Source#

  1. Create a source file for your executable.

    Minimal main() example with error checking on the most critical call:

#include "ovphysx/ovphysx.h"
#include <stdio.h>

int main() {
    ovphysx_create_args create_args = OVPHYSX_CREATE_ARGS_DEFAULT;
    ovphysx_handle_t handle = 0;
    ovphysx_result_t result = ovphysx_create_instance(&create_args, &handle);
    if (result.status != OVPHYSX_API_SUCCESS) {
        ovphysx_string_t err = ovphysx_get_last_error();
        if (err.ptr)
            fprintf(stderr, "Failed to create instance: %.*s\n", (int)err.length, err.ptr);
        return 1;
    }

    // Error handling omitted for brevity -- see samples/c_samples/ for production code.
    ovphysx_string_t prefix_str = {NULL, 0};
    ovphysx_usd_handle_t usd_handle = 0;
    ovphysx_add_usd(handle, ovphysx_cstr("scene.usda"), prefix_str, &usd_handle);
    ovphysx_step(handle, 1.0f / 60.0f, 0.0f);

    ovphysx_destroy_instance(handle);
    return 0;
}

Configure and Build

  1. Configure and build the app.

    Point CMAKE_PREFIX_PATH at the SDK root (the directory containing include/, lib/, and plugins/):

cmake -B build -DCMAKE_PREFIX_PATH=/path/to/ovphysx
cmake --build build

Runtime Libraries (C/C++)#

Linux#

The CMake config bakes RPATH into your executable automatically. No LD_LIBRARY_PATH manipulation is needed. Run the binary directly.

Windows#

Use the ovphysx_copy_runtime_dlls(<target>) helper provided by the CMake package (already shown in the CMakeLists.txt example). This copies the required DLLs and plugins next to your executable at build time.

Alternatively, ensure that the plugins/ directory is on your PATH at runtime.

Result#

You now have a minimal C or C++ application that links against ovphysx::ovphysx, loads a USD stage, and runs a simulation step.

Next Steps#