27 releases (7 breaking)

0.8.1 Nov 22, 2022
0.7.0 Oct 19, 2022
0.4.16 Dec 21, 2021
0.4.15 Aug 22, 2021
0.2.3+4.1.1 Nov 18, 2019

#3 in Simulation

Download history 163/week @ 2022-10-17 114/week @ 2022-10-24 89/week @ 2022-10-31 28/week @ 2022-11-07 16/week @ 2022-11-14 163/week @ 2022-11-21 101/week @ 2022-11-28 61/week @ 2022-12-05 82/week @ 2022-12-12 104/week @ 2022-12-19 51/week @ 2022-12-26 46/week @ 2023-01-02 73/week @ 2023-01-09 96/week @ 2023-01-16 113/week @ 2023-01-23 124/week @ 2023-01-30

410 downloads per month
Used in 2 crates

Custom license

174K SLoC

C++ 157K SLoC // 0.2% comments Rust 17K SLoC // 0.0% comments C 116 SLoC // 0.2% comments Shell 45 SLoC

🎳 physx-sys

Unsafe automatically-generated Rust bindings for NVIDIA PhysX 4.1 C++ API.

Build Status Crates.io Docs Contributor Covenant Embark Embark

Please also see the repository containing a work-in-progress safe wrapper.


Tomasz Stachowiak did a presentation at the Stockholm Rust Meetup on October 2019 about this project that goes through the technical details of how C++ to Rust bindings of physx-sys works:

An unholy fusion of Rust and C++ in physx-rs (Stockholm Rust Meetup, October 2019)

Basic usage

unsafe {
    let foundation = physx_create_foundation();
    let physics = physx_create_physics(foundation);

    let mut scene_desc = PxSceneDesc_new(PxPhysics_getTolerancesScale(physics));
    scene_desc.gravity = PxVec3 {
        x: 0.0,
        y: -9.81,
        z: 0.0,

    let dispatcher = PxDefaultCpuDispatcherCreate(2, null_mut());

    scene_desc.cpuDispatcher = dispatcher as *mut PxCpuDispatcher;
    scene_desc.filterShader = Some(PxDefaultSimulationFilterShader);

    let scene = PxPhysics_createScene_mut(physics, &scene_desc);

    // Your physics simulation goes here



A simple example to showcase how to use physx-sys. It can be run with cargo run --examples ball.



     o              oo         oo
                   o             o
      o           o               o
                 o                 oo
       o        o                    o
               o                                ooooooo
              o                       o       oo       oo
        o    o                         o    oo           oo
            o                           o  o               o    ooooooooo
         o                                o                 o oo         oooooooooo oo

How it works

The binding is generated using a custom C++ app written against clang's libtooling. It queries the compiler's abstract syntax tree, and maps the C++ PhysX functions and types to Rust using heuristics chosen specifically for this SDK. It is not a general C++ <-> Rust binding generator, and using it on other projects will likely crash and burn.

Since C++ does not have a standardized and stable ABI, it's generally not safe to call it from Rust code; since PhysX exposes a C++ interface, we can't use it directly. That's why physx-sys generates both a Rust interface as well as a plain C wrapper. The C code is compiled into a static library at build time, and Rust then talks to C.

In order to minimize the amount of work required to marshall data between the C wrapper and the original C++ API, we generate a bespoke C wrapper for each build target. The wrapper is based on metadata about structure layout extracted directly from compiling and running a tiny program against the PhysX SDK using the specific C++ compiler used in the build process.

The build process comprises a few steps:

  1. The pxbind utility uses clang to extract metadata about PhysX functions and types, and generates partial Rust and C bindings as physx_generated.hpp and physx_generated.rs. Those contain all function definitions, and a small subset of types. It also generates a C++ utility called structgen by emitting structgen.cpp.
  2. structgen is compiled against the PhysX SDK, and generates all the remaining type wrappers. For each struct, it queries the size and offset of its members, and generates structgen_out.hpp and structgen_out.rs. The types are "plain old data" structs which will perfectly match the memory layout of the C++ types.
  3. All the generated C types are compiled together to form physx_api, a static library for Rust to link with.
  4. The Rust wrapper is compiled, and linked with PhysX and the C wrapper.

Steps 2..4 are performed completely automatically from within build.rs, while step 1 is only necessary when upgrading the PhysX SDK or modifying the generator. As such, building and running pxbind is a manual task, and is currently only supported on *nix systems.

Since pxbind relies on unstable clang internals only specific clang/llvm versions are supported to build it. Currently supported versions are llvm-14 and libclang-14-dev. You may find it working with other versions but it's not guarenteed.


Licensed under either of

at your option.

Note that the PhysX C++ SDK has its own BSD 3 license and depends on additional C++ third party libraries.

If you use cargo deny, you can use this clarification in your configuration, at least until crates.io supports parentheses.

name = "physx-sys"
expression = "(MIT OR Apache-2.0) AND BSD-3-Clause"
license-files = [{ path = "LICENSE", hash = 0xe326546e }]


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

No runtime deps