repository·master·Indexed 25 days ago
https://github.com/bepu/bepuphysics2A high-performance, C#-based 3D rigid body physics engine targeting .NET 8. It features a wide range of collision shapes (spheres, capsules, boxes, triangles, cylinders, convex hulls, compounds, and meshes), linear and angular continuous collision detection (CCD), and efficient scene-wide ray and sweep queries. The engine is designed for extreme speed, utilizing SIMD intrinsics via System.Numerics.Vectors and System.Runtime.Intrinsics for optimal performance on compatible hardware.
BepuPhysics v2 provides the following capabilities:
BepuPhysics/Constraints/ directory.BepuPhysics2 is a low-level physics engine designed for maximum performance. It prioritizes performance over safety and ease of use, which means it exposes much of its underlying data directly to the user.
Key characteristics to be aware of:
struct), ref semantics, pointers, and SIMD instructions.Developers using this engine should be comfortable with value type semantics, performance-oriented C# features, and memory management.
In v2, there is no explicit Body type. Instead, bodies are managed through Simulation.Bodies.
Simulation.Bodies.Add to create a body. This returns a handle that uniquely identifies the body.Simulation.Bodies.HandleToLocation to find the current memory location of a body.Pose or Velocity, create a BodyReference from the body handle. Alternatively, you can manually perform lookups into the Simulation.Bodies sets and their raw property buffers for performance.BepuPhysics v2 does not follow semantic versioning. When upgrading to a newer version, you should expect breaking changes.
If your simulation exhibits unusual oscillations, bouncing, or explosions, it is likely due to constraint instability. This usually stems from either incomplete force propagation or excessive constraint stiffness.
Manifests as bouncing or mild wiggling, often in tall stacks of bodies. The solver fails to converge for all constraints simultaneously.
Simulation.Solver.IterationCount (set this via Simulation.Create) or increase the frequency of Simulation.Timestep calls with a smaller dt.Occurs when constraint frequency is too high relative to the solver update rate.
Simulation.Timestep calls.To build the library, use the latest version of Visual Studio with the .NET desktop development workload installed. Open and build the Library.sln file.
Requirements:
BepuPhysics.csproj uses T4 templates. If you modify these templates, you must use a build pipeline capable of processing them (such as Visual Studio).To create a simulation, use Simulation.Create. This method requires two callback parameters that must be implemented as structs (not classes) to allow the compiler to inline them and avoid virtual dispatch overhead:
TNarrowPhaseCallbacks: Handles collision-related logic such as collision filtering, contact manifolds, and materials. Implement INarrowPhaseCallbacks within this struct.TPoseIntegratorCallbacks: Controls per-body velocity integration (e.g., implementing gravity or damping). Implement IPoseIntegratorCallbacks within this struct.Additionally, you must provide a SolveDescription to configure the solver, which allows you to set the number of velocity iterations and substeps. Using more substeps is often more efficient for stabilizing difficult constraints than increasing velocity iterations.
Optional parameters include initial allocation sizes for the resource pool and an ITimestepper (defaults to DefaultTimestepper).
To ensure that a simulation produces the same physical results on a single machine given the same inputs, you must:
IThreadDispatcher to the time step function).Simulation.Deterministic property to true.Note: The Deterministic property defaults to false and may impact performance in large or chaotic simulations.
There are two primary ways to include BepuPhysics v2 in your project:
To run a high-coverage subset of performance tests, use the -f filter flag with the following benchmark patterns. This is useful for a quicker execution of core components like collision batching, constraints, and shape tests.
-f *CollisionBatcherTaskBenchmarks.* *GroupedCollisionTesterBenchmarks.* *GatherScatterBenchmarks.* *OneBodyConstraintBenchmarks.* *TwoBodyConstraintBenchmarks.* *ThreeBodyConstraintBenchmarks.* *FourBodyConstraintBenchmarks.* *SweepBenchmarks.* *ShapeRayBenchmarks.* *ShapePileBenchmark.* *RagdollTubeBenchmark.*When increasing the full simulation update rate (Simulation.Timestep) is too expensive, use the solver's substepping feature to increase the frequency of the solver and integrator without increasing the frequency of collision detection.
To implement substepping, pass a SolveDescription with the desired number of substeps when calling Simulation.Create.
Example behavior: If Simulation.Timestep is called at 60Hz and you configure 4 substeps, the solver and integrator will effectively run at 240Hz.
Optimization Tip: When using high substep counts, you can often reduce the number of solver velocity iterations to save performance. Using 1 velocity iteration with substepping is often a 'sweet spot'.