Class Simulation

Namespace

BepuPhysics

Assembly

BepuPhysics.dll

Orchestrates the bookkeeping and execution of a full dynamic simulation.

public class Simulation : IDisposable

Inheritance

object

Simulation

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Properties

Awakener

Gets the system responsible for awakening bodies within the simulation.

public IslandAwakener Awakener { get; }

Property Value

IslandAwakener

Bodies

Gets the collection of bodies in the simulation.

public Bodies Bodies { get; }

Property Value

Bodies

BroadPhase

Gets the broad phase used by the simulation. Supports accelerated ray and volume queries.

public BroadPhase BroadPhase { get; }

Property Value

BroadPhase

BroadPhaseOverlapFinder

Gets the system used to find overlapping pairs within the simulation.

public CollidableOverlapFinder BroadPhaseOverlapFinder { get; }

Property Value

CollidableOverlapFinder

BufferPool

Gets the main memory pool used to fill persistent structures and main thread ephemeral resources across the engine.

public BufferPool BufferPool { get; }

Property Value

BufferPool

Deterministic

Gets or sets whether to use a deterministic time step when using multithreading. When set to true, additional time is spent sorting constraint additions and transfers. Note that this can only affect determinism locally- different processor architectures may implement instructions differently.

public bool Deterministic { get; set; }

Property Value

bool

NarrowPhase

Gets the system used to identify contacts in colliding pairs of shapes and to update contact constraint data.

public NarrowPhase NarrowPhase { get; }

Property Value

NarrowPhase

PoseIntegrator

Gets the integrator used to update velocities and poses within the simulation.

public IPoseIntegrator PoseIntegrator { get; }

Property Value

IPoseIntegrator

Profiler

Gets the simulation profiler. Note that the SimulationProfiler implementation only exists when the library is compiled with the PROFILE compilation symbol; if not defined, returned times are undefined.

public SimulationProfiler Profiler { get; }

Property Value

SimulationProfiler

Shapes

Gets or sets the collection of shapes used by the simulation.

public Shapes Shapes { get; set; }

Property Value

Shapes

Remarks

While Shapes instances can be shared between multiple Simulation instances, there are no guarantees of thread safety. Further, setting the Shapes property to another collection while there are any outstanding references in the simulation to shapes within the old collection will result in fatal errors if the simulation continues to be used.

Sleeper

Gets the system responsible for putting bodies to sleep within the simulation.

public IslandSleeper Sleeper { get; }

Property Value

IslandSleeper

Solver

Gets the solver used to solved constraints within the simulation.

public Solver Solver { get; }

Property Value

Solver

SolverBatchCompressor

Gets the batch compressor used to compact constraints into fewer solver batches.

public BatchCompressor SolverBatchCompressor { get; }

Property Value

BatchCompressor

Statics

Gets the collection of statics within the simulation.

public Statics Statics { get; }

Property Value

Statics

Timestepper

Gets the timestepper used to update the simulation state.

public ITimestepper Timestepper { get; }

Property Value

ITimestepper

Methods

Clear()

Clears the simulation of every object, only returning memory to the pool that would be returned by sequential removes. Other persistent allocations, like those in the Bodies set, will remain.

public void Clear()

CollisionDetection(float, IThreadDispatcher)

Updates the broad phase structure for the current body bounding boxes, finds potentially colliding pairs, and then executes the narrow phase for all such pairs. Generates contact constraints for the solver.

public void CollisionDetection(float dt, IThreadDispatcher threadDispatcher = null)

Parameters

dt float

Duration of the time step.

threadDispatcher IThreadDispatcher

Thread dispatcher to use for execution, if any.

Create<TNarrowPhaseCallbacks, TPoseIntegratorCallbacks>(BufferPool, TNarrowPhaseCallbacks, TPoseIntegratorCallbacks, SolveDescription, ITimestepper, SimulationAllocationSizes?, Shapes)

Constructs a simulation supporting dynamic movement and constraints with the specified narrow phase callbacks.

public static Simulation Create<TNarrowPhaseCallbacks, TPoseIntegratorCallbacks>(BufferPool bufferPool, TNarrowPhaseCallbacks narrowPhaseCallbacks, TPoseIntegratorCallbacks poseIntegratorCallbacks, SolveDescription solveDescription, ITimestepper timestepper = null, SimulationAllocationSizes? initialAllocationSizes = null, Shapes shapes = null) where TNarrowPhaseCallbacks : struct, INarrowPhaseCallbacks where TPoseIntegratorCallbacks : struct, IPoseIntegratorCallbacks

Parameters

bufferPool BufferPool

Buffer pool used to fill persistent structures and main thread ephemeral resources across the engine.

narrowPhaseCallbacks TNarrowPhaseCallbacks

Callbacks to use in the narrow phase.

poseIntegratorCallbacks TPoseIntegratorCallbacks

Callbacks to use in the pose integrator.

solveDescription SolveDescription

Describes how the solver should execute, including the number of substeps and the number of velocity iterations per substep.

timestepper ITimestepper

Timestepper that defines how the simulation state should be updated. If null, DefaultTimestepper is used.

initialAllocationSizes SimulationAllocationSizes?

Allocation sizes to initialize the simulation with. If left null, default values are chosen.

shapes Shapes

Collection of shapes to use in the simulation, if any. If null, a new Shapes collection will be created for this simulation.

Returns

Simulation

New simulation.

Type Parameters

TNarrowPhaseCallbacks

TPoseIntegratorCallbacks

Dispose()

Clears the simulation of every object and returns all pooled memory to the buffer pool. Leaves the simulation in an unusable state.

public void Dispose()

EnsureCapacity(SimulationAllocationSizes)

Increases the allocation size of any buffers too small to hold the allocation target.

public void EnsureCapacity(SimulationAllocationSizes allocationTarget)

Parameters

allocationTarget SimulationAllocationSizes

Allocation sizes to guarantee sufficient size for.

Remarks

The final size of the allocated buffers are constrained by the allocator. It is not guaranteed to be exactly equal to the target, but it is guaranteed to be at least as large.

This is primarily a convenience function. Everything it does internally can be done externally. For example, if only type batches need to be resized, the solver's own functions can be used directly.

IncrementallyOptimizeDataStructures(IThreadDispatcher)

Incrementally improves body and constraint storage for better performance.

public void IncrementallyOptimizeDataStructures(IThreadDispatcher threadDispatcher = null)

Parameters

threadDispatcher IThreadDispatcher

Thread dispatcher to use for execution, if any.

PredictBoundingBoxes(float, IThreadDispatcher)

Predicts the bounding boxes of active bodies by speculatively integrating velocity. Does not actually modify body velocities. Updates deactivation candidacy.

public void PredictBoundingBoxes(float dt, IThreadDispatcher threadDispatcher = null)

Parameters

dt float

Duration of the time step.

threadDispatcher IThreadDispatcher

Thread dispatcher to use for execution, if any.

RayCast<THitHandler>(Vector3, Vector3, float, ref THitHandler, int)

Intersects a ray against the simulation.

public void RayCast<THitHandler>(Vector3 origin, Vector3 direction, float maximumT, ref THitHandler hitHandler, int id = 0) where THitHandler : IRayHitHandler

Parameters

origin Vector3

Origin of the ray to cast.

direction Vector3

Direction of the ray to cast.

maximumT float

Maximum length of the ray traversal in units of the direction's length.

hitHandler THitHandler

callbacks to execute on ray-object intersections.

id int

User specified id of the ray.

Type Parameters

THitHandler

Type of the callbacks to execute on ray-object intersections.

Resize(SimulationAllocationSizes)

Increases the allocation size of any buffers too small to hold the allocation target, and decreases the allocation size of any buffers that are unnecessarily large.

public void Resize(SimulationAllocationSizes allocationTarget)

Parameters

allocationTarget SimulationAllocationSizes

Allocation sizes to guarantee sufficient size for.

Remarks

The final size of the allocated buffers are constrained by the allocator. It is not guaranteed to be exactly equal to the target, but it is guaranteed to be at least as large.

This is primarily a convenience function. Everything it does internally can be done externally. For example, if only type batches need to be resized, the solver's own functions can be used directly.

Sleep(IThreadDispatcher)

Executes the sleep stage, moving candidate

public void Sleep(IThreadDispatcher threadDispatcher = null)

Parameters

threadDispatcher IThreadDispatcher

Thread dispatcher to use for the sleeper execution, if any.

Solve(float, IThreadDispatcher)

Updates the broad phase structure for the current body bounding boxes, finds potentially colliding pairs, and then executes the narrow phase for all such pairs. Generates contact constraints for the solver.

public void Solve(float dt, IThreadDispatcher threadDispatcher = null)

Parameters

dt float

Duration of the time step.

threadDispatcher IThreadDispatcher

Thread dispatcher to use for execution, if any.

Sweep<TShape, TSweepHitHandler>(TShape, in RigidPose, in BodyVelocity, float, BufferPool, ref TSweepHitHandler, float, float, int)

Sweeps a shape against the simulation.

public void Sweep<TShape, TSweepHitHandler>(TShape shape, in RigidPose pose, in BodyVelocity velocity, float maximumT, BufferPool pool, ref TSweepHitHandler hitHandler, float minimumProgression, float convergenceThreshold, int maximumIterationCount) where TShape : unmanaged, IConvexShape where TSweepHitHandler : ISweepHitHandler

Parameters

shape TShape

Shape to sweep.

pose RigidPose

Starting pose of the sweep.

velocity BodyVelocity

Velocity of the swept shape.

maximumT float

Maximum length of the sweep in units of time used to integrate the velocity.

pool BufferPool

Pool to allocate any temporary resources in during execution.

hitHandler TSweepHitHandler

Callbacks executed when a sweep impacts an object in the scene.

minimumProgression float

Minimum amount of progress in terms of t parameter that any iterative sweep tests should make for each sample.

convergenceThreshold float

Threshold in terms of t parameter under which iterative sweep tests are permitted to exit in collision.

maximumIterationCount int

Maximum number of iterations to use in iterative sweep tests.

Type Parameters

TShape

Type of the shape to sweep.

TSweepHitHandler

Type of the callbacks executed when a sweep impacts an object in the scene.

Remarks

Simulation objects are treated as stationary during the sweep.

Sweep<TShape, TSweepHitHandler>(in TShape, in RigidPose, in BodyVelocity, float, BufferPool, ref TSweepHitHandler)

Sweeps a shape against the simulation.

public void Sweep<TShape, TSweepHitHandler>(in TShape shape, in RigidPose pose, in BodyVelocity velocity, float maximumT, BufferPool pool, ref TSweepHitHandler hitHandler) where TShape : unmanaged, IConvexShape where TSweepHitHandler : ISweepHitHandler

Parameters

shape TShape

Shape to sweep.

pose RigidPose

Starting pose of the sweep.

velocity BodyVelocity

Velocity of the swept shape.

maximumT float

Maximum length of the sweep in units of time used to integrate the velocity.

pool BufferPool

Pool to allocate any temporary resources in during execution.

hitHandler TSweepHitHandler

Callbacks executed when a sweep impacts an object in the scene.

Type Parameters

TShape

Type of the shape to sweep.

TSweepHitHandler

Type of the callbacks executed when a sweep impacts an object in the scene.

Remarks

Simulation objects are treated as stationary during the sweep.

Timestep(float, IThreadDispatcher)

Performs one timestep of the given length.

public void Timestep(float dt, IThreadDispatcher threadDispatcher = null)

Parameters

dt float

Duration of the time step.

threadDispatcher IThreadDispatcher

Thread dispatcher to use for execution, if any.

Remarks

Be wary of variable timesteps. They can harm stability. Whenever possible, keep the timestep the same across multiple frames unless you have a specific reason not to.