Crate oxijolt_sys

Expand description

Unsafe bindings to Jolt Physics 5.6.0 through the joltc C wrapper.

Everything here is bindgen output over joltc’s include/joltc.h plus this fork’s native/joltc_ext/joltc_ext.h, and keeps their JPH_* names. The output is committed under src/bindings/, one file per ABI family and configuration, so building needs no libclang; the bindgen feature generates it at build time instead. The supported targets are the registry in build/targets.rs; 32-bit targets are not supported. The extension adds functions in joltc’s naming that are compiled into the joltc archive: a JPH_StateRecorder, JPH_CharacterVirtual_SaveState and RestoreState, JPH_CharacterVirtual_ExtendedUpdate2 and RefreshContacts2 with explicit gravity, filters and temp allocator, JPH_VehicleConstraint_AsConstraint, the Constraint base of a vehicle constraint, and for ragdolls JPH_RagdollSettings_SetPart, the typed JPH_RagdollSettings_SetPartToParentSwingTwist, _SetPartToParentHinge and _SetPartToParentSixDOF, JPH_RagdollSettings_CalculateConstraintPriorities, the swing-twist motor states (JPH_SwingTwistConstraint_SetSwingMotorState, _GetSwingMotorState, _SetTwistMotorState, _GetTwistMotorState), its SetTargetOrientationBS and GetRotationInConstraintSpace, and JPH_HingeConstraint_SetTargetOrientationBS, and materials with user data (JPH_PhysicsMaterial_Create2, JPH_PhysicsMaterial_GetUserData, JPH_ConvexShapeSettings_SetMaterial, JPH_HeightFieldShapeSettings_Create2), the sub-shape pair of a removed contact (JPH_SubShapeIDPair_GetBody1ID and its three siblings), a contact listener whose validate callback gets the collide result without faces (JPH_ContactListener2_*, JPH_PhysicsSystem_SetContactListener2) and a soft body contact listener (JPH_SoftBodyContactListener_*, JPH_PhysicsSystem_SetSoftBodyContactListener, JPH_SoftBodyManifold_*), and shapes saved to bytes with their children and materials and restored (JPH_Shape_SaveBinaryState, JPH_Shape_RestoreBinaryState, JPH_ShapeBinaryState_*). The safe API lives in the oxijolt crate.

§Features

asserts: compile Jolt with its debug assertions. joltc’s default handler prints a failed assertion and then executes a breakpoint (__debugbreak on MSVC), so raw users should install their own with JPH_SetAssertFailureHandler before JPH_Init. The handler is one process-global joltc slot, and the oxijolt crate installs its own.
double-precision: world positions (Real, JPH_RVec3, JPH_RMat4) use f64.
cross-platform-deterministic: build Jolt with its cross-platform deterministic floating point settings (slower; same results across compilers and platforms).
debug-renderer: compile Jolt’s debug renderer into the native libraries and bind joltc’s debug drawing functions.
bindgen: generate the bindings at build time with libclang instead of using the committed ones. It does not add supported targets.

§Native build and `JOLTC_LIB_DIR`

By default the build script builds joltc and Jolt from the vendor/ submodules with CMake, always in Release. Set JOLTC_LIB_DIR to an install prefix produced by an earlier build (OUT_DIR/joltc) to skip CMake: it holds lib/ with the joltc and Jolt static libraries, include/joltc.h, include/joltc_ext.h and oxijolt-sys-manifest.txt. A prefix is specific to the target, the C runtime, the crate features and the pinned joltc and Jolt commits; the build script validates all of these against the manifest and refuses a mismatch.

§Using the raw API

joltc’s own contract, as observed in its source:

Shape creators such as JPH_BoxShape_Create return a shape that holds one reference, and JPH_Shape_Destroy releases one. Bodies keep their own reference, so the creator releases its reference once it no longer needs the shape.
JPH_PhysicsSystem_Destroy deletes the broad-phase layer interface and both layer filters passed in JPH_PhysicsSystemSettings. Do not destroy them yourself.
JPH_Init is guarded by a plain bool, and creating or destroying a physics system writes an unsynchronised global map. Call JPH_Init once, and create and destroy systems from one thread at a time.
JPH_PhysicsSystem_Update uses one global temp allocator. Use JPH_PhysicsSystem_Update2 with a per-world JPH_TempAllocator instead.
joltc’s JPH_CharacterVirtual_Update, ExtendedUpdate, RefreshContacts, WalkStairs, StickToFloor and SetShape use joltc’s one global temp allocator and are not thread-safe. Use JPH_CharacterVirtual_ExtendedUpdate2 and JPH_CharacterVirtual_RefreshContacts2 with a per-world allocator instead.
JPH_CharacterVirtualSettings_Init (and JPH_CharacterSettings_Init) create an empty shape and its settings on every call, each holding a reference nobody releases. Fill the settings field by field instead.
A recorder passed to JPH_CharacterVirtual_RestoreState must hold a complete stream written by JPH_CharacterVirtual_SaveState.
JPH_JobSystemThreadPool_Create maps numThreads <= 0 to “as many as there are hardware threads”, so pass a positive worker count when the count matters.
joltc’s object-layer, body and shape filters (JPH_ObjectLayerFilter_*, JPH_BodyFilter_*, JPH_ShapeFilter_*) call one process-global proc table per filter type. The oxijolt crate installs those tables once and owns them. Code that links both crates must not call JPH_*Filter_SetProcs for these three types, and must not pass filters it created with JPH_*Filter_Create to queries, because the callbacks of oxijolt would receive their userData.
joltc’s body activation and character contact listeners and the extension’s contact listener (JPH_ContactListener2_*) and soft body contact listener also call one process-global proc table each. The oxijolt crate installs them once and owns them: code that links both crates must not call JPH_ContactListener2_SetProcs, JPH_BodyActivationListener_SetProcs, JPH_CharacterContactListener_SetProcs or JPH_SoftBodyContactListener_SetProcs, nor create listeners of these types, whose userData the callbacks of oxijolt would receive. joltc’s own contact listener (JPH_ContactListener_*) is not used by oxijolt and is free for other code.
A vehicle constraint must be registered both as a constraint (JPH_PhysicsSystem_AddConstraint with JPH_VehicleConstraint_AsConstraint) and as a step listener (JPH_PhysicsSystem_AddStepListener with JPH_VehicleConstraint_AsPhysicsStepListener), and its collision tester must be set before the first step. Remove it from both before its last reference is released (JPH_Constraint_Destroy on the AsConstraint pointer) and before its body is destroyed.
JPH_VehicleEngineSettings_Init allocates a JPH_LinearCurve for normalizedTorque that the caller must destroy with JPH_LinearCurve_Destroy.
The JPH_Wheel_GetContact* getters are meaningful only while JPH_Wheel_HasContact returns true.
JPH_RagdollSettings_CreateRagdoll dereferences null when the world cannot hold every part. Check JPH_PhysicsSystem_GetNumBodies() + parts <= JPH_PhysicsSystem_GetMaxBodies() first, with no body created concurrently. The skeleton must list parents before their children.
A ragdoll destroys its bodies through its physics system when its last reference is released: remove it from the system (JPH_Ragdoll_RemoveFromPhysicsSystem) before that, and release it before the system is destroyed.
JPH_Ragdoll_DriveToPoseUsingMotors drives only swing-twist and hinge parts (any other constraint is a Jolt assertion) and needs JPH_RagdollSettings_CalculateBodyIndexToConstraintIndex to have run.
JPH_RagdollSettings_SetPartToParent handles swing-twist only and drops the constraint base settings, the spring modes and the motor torque limits; the typed JPH_RagdollSettings_SetPartToParent* functions of the extension keep every field.
A motor state other than JPH_MotorState_Off needs valid motor settings (Jolt MotorSettings::IsValid).
These joltc functions are not bound: JPH_RagdollSettings_DisableParentChildCollisions, JPH_Ragdoll_SetPose2, JPH_Ragdoll_GetPose2, JPH_SkeletonMapper_Initialize, JPH_SkeletonMapper_LockAllTranslations, JPH_SkeletonMapper_LockTranslations, JPH_SkeletonMapper_Map and JPH_SkeletonMapper_MapReverse. They reinterpret a 4-aligned JPH_Mat4 array as Jolt’s 16-aligned Mat44, which is undefined behaviour for most arrays a caller can pass.
The debug drawing functions (JPH_DebugRenderer_*, JPH_BodyDrawFilter_*, JPH_PhysicsSystem_Draw*, JPH_Shape_Draw) exist only with the debug-renderer feature, which also compiles Jolt’s debug renderer into the native libraries.
Jolt’s DebugRenderer is a process singleton and joltc’s JPH_DebugRenderer_SetProcs sets one global proc table. With the debug-renderer feature of oxijolt, that crate installs the table and creates a renderer during PhysicsWorld::debug_lines; code that links both crates must not call JPH_DebugRenderer_SetProcs or keep its own JPH_DebugRenderer alive.