Skip to main content
`Ctrl`+`K`

# SDK 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 (currently required; this requirement will be lifted in a future version).

Additionally, if building a C/C++ app:

- Obtain the ovphysx SDK package from the Github release page and extract it to a local path.

- Install CMake 3.16 or newer and a C or C++ compiler.

## Quick Start by Language

Python

If you are using the Python wheel, getting started is simple:

    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++

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
    ├── 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

2. 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) {
            fprintf(stderr, "Failed to create instance\n");
            if (result.error.ptr) ovphysx_destroy_error(result.error);
            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

3. 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

- Full C API reference: see the C API Reference

- More tutorials: Hello World: Load USD and Step, Tensor Bindings: Read and Write Simulation Data, Cloning: Replicate Environments