{"id":18017008,"url":"https://github.com/fabmax/physx-jni","last_synced_at":"2025-04-05T20:07:28.172Z","repository":{"id":42893183,"uuid":"334187130","full_name":"fabmax/physx-jni","owner":"fabmax","description":"Java JNI bindings for Nvidia PhysX","archived":false,"fork":false,"pushed_at":"2025-03-25T22:17:30.000Z","size":67269,"stargazers_count":102,"open_issues_count":12,"forks_count":11,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-29T19:05:37.748Z","etag":null,"topics":["android","java","jni","physics","physics-engine","physics-simulation","physx"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-29T15:36:48.000Z","updated_at":"2025-03-25T21:05:34.000Z","dependencies_parsed_at":"2023-09-24T07:17:12.030Z","dependency_job_id":"e3310895-3f3c-47e5-9324-8bdcbe169da6","html_url":"https://github.com/fabmax/physx-jni","commit_stats":{"total_commits":168,"total_committers":3,"mean_commits":56.0,"dds":"0.023809523809523836","last_synced_commit":"d53aeaa55c8b4f42eb34e58d36f2eafd632a26a6"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabmax%2Fphysx-jni","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabmax%2Fphysx-jni/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabmax%2Fphysx-jni/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabmax%2Fphysx-jni/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabmax","download_url":"https://codeload.github.com/fabmax/physx-jni/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247393569,"owners_count":20931812,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","java","jni","physics","physics-engine","physics-simulation","physx"],"created_at":"2024-10-30T04:19:54.781Z","updated_at":"2025-04-05T20:07:28.148Z","avatar_url":"https://github.com/fabmax.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# physx-jni\n\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![Maven Central](https://img.shields.io/maven-central/v/de.fabmax/physx-jni.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22de.fabmax%22%20AND%20a:%22physx-jni%22)\n![Build](https://github.com/fabmax/physx-jni/workflows/Build/badge.svg)\n\nJava JNI bindings for Nvidia [PhysX 5.6.0](https://github.com/NVIDIA-Omniverse/PhysX).\n\nThe generated bindings contain most of the original documentation converted to javadoc. For further reading\nthere is also the official\n[PhysX documentation](https://nvidia-omniverse.github.io/PhysX/physx/5.6.0/index.html).\n\n## How to use\nThe library is published on maven central, so you can easily add this to your dependencies:\n\n### Desktop Java\n```\ndependencies {\n    // java bindings\n    implementation(\"de.fabmax:physx-jni:2.6.0\")\n    \n    // native libraries - you can add the one matching your system or all\n    runtimeOnly(\"de.fabmax:physx-jni:2.6.0:natives-windows\")\n    runtimeOnly(\"de.fabmax:physx-jni:2.6.0:natives-linux\")\n    runtimeOnly(\"de.fabmax:physx-jni:2.6.0:natives-macos\")\n    runtimeOnly(\"de.fabmax:physx-jni:2.6.0:natives-macos-arm64\")\n}\n```\n\n### Android\nThe Android version of the library is packaged as a single `aar` archive containing both java classes\nand native libs:\n```\ndependencies {\n    implementation(\"de.fabmax:physx-jni-android:2.6.0\")\n}\n```\n\n## Library Coverage\n\nThis is still work in progress, but the bindings already include most major parts of the PhysX SDK:\n- [x] Basics\n    - Static and dynamic actors\n    - All geometry types (box, capsule, sphere, plane, convex mesh, triangle mesh and height field)\n- [x] All joint types (revolute, spherical, prismatic, fixed, distance and D6)\n- [x] Articulations\n- [x] Vehicles\n- [x] Character controllers\n- [x] Scene serialization\n- [ ] CUDA support is removed from jni bindings, see [below](#cuda-support)\n\nFurthermore, I added bindings to [V-HACD](https://github.com/kmammou/v-hacd), which is not part of PhysX but fits\nin the context very well.\n\nThe detailed list of mapped functions is given by the [interface definition files](physx-jni/src/main/webidl).\nThe Java classes containing the actual bindings are generated from these files during build.\n\nAfter build (or after running the corresponding gradle task `generateJniBindings`) the generated Java\nclasses are located under `physx-jni/src/main/generated`.\n\n### Supported platforms:\n- Windows (x86_64)\n- Linux (x86_64)\n- MacOS (x86_64, and arm64)\n- Android (arm-v8 (aarch64) only for now)\n \nMoreover, there is also a version for javascript/webassembly:\n[physx-js-webidl](https://github.com/fabmax/physx-js-webidl).\n\n### Examples\nYou can take a look at [HelloPhysX.java](physx-jni/src/test/java/de/fabmax/physxjni/HelloPhysX.java) for a\nhello world example on how to use the library. There also are a few\n[tests](https://github.com/fabmax/physx-jni/tree/main/physx-jni/src/test/java/de/fabmax/physxjni) with slightly\nmore advanced examples (custom simulation callbacks, triangle mesh collision, custom filter shader, etc.).\n\nTo see a few real life demos you can take a look at my [kool](https://github.com/fabmax/kool) demos:\n\n- [Vehicle](https://fabmax.github.io/kool/kool-js/?demo=phys-vehicle): Vehicle demo with a racetrack and a few obstacles.\n- [Character](https://fabmax.github.io/kool/kool-js/?demo=phys-terrain): 3rd person character demo on an island.\n- [Ragdolls](https://fabmax.github.io/kool/kool-js/?demo=phys-ragdoll): Simple Ragdoll demo.\n- [Joints](https://fabmax.github.io/kool/kool-js/?demo=phys-joints): A chain running over two gears.\n- [Collision](https://fabmax.github.io/kool/kool-js/?demo=physics): Various collision shapes.\n\n\u003e *__Note:__ These demos run directly in the browser and obviously don't use this library, but the webassembly version mentioned\n\u003e above. However, the two are functionally identical, so it shouldn't matter too much. The JNI version is much faster\n\u003e though.*\n\n### Things to consider when working with native objects\nWhenever you create an instance of a wrapper class within this library, this also creates an object on the native\nside. Native objects are not covered by the garbage collector, so, in order to avoid a memory leak, you have to\nclean up these objects yourself when you are done with them.\n\nHere is an example:\n```java\n// create an object of PxVec3, this also creates a native PxVec3\n// object behind the scenes.\nPxVec3 vector = new PxVec3(1f, 2f, 3f);\n\n// do something with vector...\n\n// destroy the object once you are done with it\nvector.destroy();\n```\n\nThis approach has two potential problems: First, as mentioned, if you forget to call destroy(), the memory on the\nnative heap is not released resulting in a memory leak. Second, creating new objects on the native heap comes with\na lot of overhead and is much slower than creating a new object on the Java side.\n\nThese issues aren't a big problem for long living objects, which you create on start-up and use until you exit\nthe program. However, for short-lived objects like, in many cases, `PxVec3` this can have a large impact. Therefore,\nthere is a second method to allocate these objects: Stack allocation. To use this, you will need some sort of\nmemory allocator like LWJGL's MemoryStack. With that one the above example could look like this:\n```java\ntry (MemoryStack mem = MemoryStack.stackPush()) {\n    // create an object of PxVec3. The native object is allocated in memory\n    // provided by MemoryStack\n    PxVec3 vector = PxVec3.createAt(mem, MemoryStack::nmalloc, 1f, 2f, 3f);\n    \n    // do something with vector...\n    // no explicit destroy needed, memory is released when we leave the scope\n}\n```\nWhile the `PxVec3.createAt()` call looks a bit more complicated, this approach is much faster and comes without the\nrisk of leaking memory, so it should be preferred whenever possible.\n\n### Java Callbacks\n\nAt a few places it is possible to register callbacks, e.g., `PxErrorCallback` or\n`PxSimulationEventCallback`. In order to implement a callback, the corresponding Java callback class has to be\nextended. The implementing class can then be passed into the corresponding PhysX API.\n\nHere's an example how this might look:\n\n```java\n// implement callback\npublic class CustomErrorCallback extends PxErrorCallbackImpl {\n    @Override\n    public void reportError(PxErrorCodeEnum code, String message, String file, int line) {\n        System.out.println(code + \": \" + message);\n    }\n}\n\n// register / use callback\nCustomErrorCallback errorCb = new CustomErrorCallback();\nPxFoundation foundation = PxTopLevelFunctions.CreateFoundation(PX_PHYSICS_VERSION, new PxDefaultAllocator(), errorCb);\n```\n\n### User Data\n\nSeveral PhysX classes (e.g. `PxActor`, `PxMaterial`, ...) have a userData field, which can be used to store an arbitrary\nobject reference. Since the native userData field is a void pointer, a wrapper class `JavaNativeRef` is needed to store\na java object reference in it:\n\n```java\nPxRigidDynamic myActor = ...\n\n// set user data, can be any java object, here we use a String:\nmyActor.setUserData(new JavaNativeRef\u003c\u003e(\"Arbitrary data\"));\n\n// get user data. You need to specify the type yourself, here we expect it to be a String:\nJavaNativeRef\u003cString\u003e userData = JavaNativeRef.fromNativeObject(myActor.getUserData());\nSystem.out.println(userData.get());\n```\n\n### CUDA Support\n\nThis library used to support PhysX CUDA extensions (partially). However, with version `5.6.0`, building PhysX with\nCUDA support became a lot more complicated because now the CUDA toolkit needs to be installed separately, which is\nrelatively cumbersome to do (especially in the GitHub workflow environment, which builds the distribution version\nof this library).\n\nPersonally, I never really used the CUDA functions because the strict requirement to have an Nvidia GPU was to much\nof a limitation for me anyway (and, for typical scenes, the performance benefits where not even that great). I\ntherefore opted to remove CUDA support for now. If you absolutely need CUDA you can still use the last version with\nworking CUDA support which is [`v2.5.1`](https://github.com/fabmax/physx-jni/releases/tag/v2.5.1). And it might be\npossible that I bring back CUDA support some time in the future.\n\n## Building\nYou can build the bindings yourself. However, this requires `cmake`, `python3` and the C++ compiler appropriate to your\nplatform (Visual Studio 2022 (Community) on Windows, clang on Linux, and Xcode on MacOS):\n```\n# Clone this repo\ngit clone https://github.com/fabmax/physx-jni.git\n\n# Enter that directory\ncd physx-jni\n\n# Download submodule containing the PhysX source code\ngit submodule update --init\n\n# Optional, but might help in case build fails\n./gradlew generateNativeProject\n\n# Build native PhysX (requires Visual Studio 2022 (Community) on Windows, clang on Linux, and Xcode on MacOS)\n./gradlew buildNativeProject\n\n# Generate Java/JNI code and build library\n./gradlew build\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabmax%2Fphysx-jni","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabmax%2Fphysx-jni","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabmax%2Fphysx-jni/lists"}