Table of Contents

Class BepuSimulation

Namespace
Stride.BepuPhysics
Assembly
Stride.BepuPhysics.dll
[DataContract]
public sealed class BepuSimulation : IDisposable
Inheritance
BepuSimulation
Implements
Extension Methods

Constructors

BepuSimulation() 

public BepuSimulation()

Fields

CollisionMatrix

Defines how layers collide between each other.

public CollisionMatrix CollisionMatrix

Field Value

CollisionMatrix

Remarks

This structure is VERY large, prefer referencing it directly instead of passing it around.

Properties

AssociatedScene

The scene associated with this simulation.

public UrlReference<Scene>? AssociatedScene { get; set; }

Property Value

UrlReference<Scene>

Remarks

When this is set, entities spawning inside this scene will be automatically associated with this simulation as long as their SimulationSelector is set to SceneBasedSimulationSelector. See SceneBasedSimulationSelector for more info.

Deterministic

Whether to use a deterministic time step when using multithreading. When set to true, additional time is spent sorting constraint additions and transfers.

[Display(2, "Deterministic", null)]
public bool Deterministic { get; set; }

Property Value

bool

Remarks

This can only affect determinism locally- different processor architectures may implement instructions differently. There is also some performance cost

Enabled

Whether to update the simulation.

[Display(0, "Enabled", null)]
public bool Enabled { get; set; }

Property Value

bool

Remarks

False also disables contact processing but won't prevent re-synchronization of static physics bodies to their engine counterpart

FixedTimeStep

The amount of time between individual simulation steps/ticks, by default ~16.67 milliseconds which would run 60 ticks per second

public TimeSpan FixedTimeStep { get; set; }

Property Value

TimeSpan

Remarks

Larger values improve performance at the cost of stability and precision.

FixedTimeStepSeconds

The number of seconds per step to simulate. Lossy, prefer FixedTimeStep.

[Display(3, "Fixed Time Step (s)", "Time")]
public double FixedTimeStepSeconds { get; set; }

Property Value

double

Layer0 

[Display(null, "Collision Matrix")]
public CollisionMask Layer0 { get; set; }

Property Value

CollisionMask

Layer1 

[Display(null, "Collision Matrix")]
public CollisionMask Layer1 { get; set; }

Property Value

CollisionMask

Layer10 

[Display(null, "Collision Matrix")]
public CollisionMask Layer10 { get; set; }

Property Value

CollisionMask

Layer11 

[Display(null, "Collision Matrix")]
public CollisionMask Layer11 { get; set; }

Property Value

CollisionMask

Layer12 

[Display(null, "Collision Matrix")]
public CollisionMask Layer12 { get; set; }

Property Value

CollisionMask

Layer13 

[Display(null, "Collision Matrix")]
public CollisionMask Layer13 { get; set; }

Property Value

CollisionMask

Layer14 

[Display(null, "Collision Matrix")]
public CollisionMask Layer14 { get; set; }

Property Value

CollisionMask

Layer15 

[Display(null, "Collision Matrix")]
public CollisionMask Layer15 { get; set; }

Property Value

CollisionMask

Layer16 

[Display(null, "Collision Matrix")]
public CollisionMask Layer16 { get; set; }

Property Value

CollisionMask

Layer17 

[Display(null, "Collision Matrix")]
public CollisionMask Layer17 { get; set; }

Property Value

CollisionMask

Layer18 

[Display(null, "Collision Matrix")]
public CollisionMask Layer18 { get; set; }

Property Value

CollisionMask

Layer19 

[Display(null, "Collision Matrix")]
public CollisionMask Layer19 { get; set; }

Property Value

CollisionMask

Layer2 

[Display(null, "Collision Matrix")]
public CollisionMask Layer2 { get; set; }

Property Value

CollisionMask

Layer20 

[Display(null, "Collision Matrix")]
public CollisionMask Layer20 { get; set; }

Property Value

CollisionMask

Layer21 

[Display(null, "Collision Matrix")]
public CollisionMask Layer21 { get; set; }

Property Value

CollisionMask

Layer22 

[Display(null, "Collision Matrix")]
public CollisionMask Layer22 { get; set; }

Property Value

CollisionMask

Layer23 

[Display(null, "Collision Matrix")]
public CollisionMask Layer23 { get; set; }

Property Value

CollisionMask

Layer24 

[Display(null, "Collision Matrix")]
public CollisionMask Layer24 { get; set; }

Property Value

CollisionMask

Layer25 

[Display(null, "Collision Matrix")]
public CollisionMask Layer25 { get; set; }

Property Value

CollisionMask

Layer26 

[Display(null, "Collision Matrix")]
public CollisionMask Layer26 { get; set; }

Property Value

CollisionMask

Layer27 

[Display(null, "Collision Matrix")]
public CollisionMask Layer27 { get; set; }

Property Value

CollisionMask

Layer28 

[Display(null, "Collision Matrix")]
public CollisionMask Layer28 { get; set; }

Property Value

CollisionMask

Layer29 

[Display(null, "Collision Matrix")]
public CollisionMask Layer29 { get; set; }

Property Value

CollisionMask

Layer3 

[Display(null, "Collision Matrix")]
public CollisionMask Layer3 { get; set; }

Property Value

CollisionMask

Layer30 

[Display(null, "Collision Matrix")]
public CollisionMask Layer30 { get; set; }

Property Value

CollisionMask

Layer31 

[Display(null, "Collision Matrix")]
public CollisionMask Layer31 { get; set; }

Property Value

CollisionMask

Layer4 

[Display(null, "Collision Matrix")]
public CollisionMask Layer4 { get; set; }

Property Value

CollisionMask

Layer5 

[Display(null, "Collision Matrix")]
public CollisionMask Layer5 { get; set; }

Property Value

CollisionMask

Layer6 

[Display(null, "Collision Matrix")]
public CollisionMask Layer6 { get; set; }

Property Value

CollisionMask

Layer7 

[Display(null, "Collision Matrix")]
public CollisionMask Layer7 { get; set; }

Property Value

CollisionMask

Layer8 

[Display(null, "Collision Matrix")]
public CollisionMask Layer8 { get; set; }

Property Value

CollisionMask

Layer9 

[Display(null, "Collision Matrix")]
public CollisionMask Layer9 { get; set; }

Property Value

CollisionMask

MaxStepPerFrame

Represents the maximum number of steps per frame to avoid a death loop

[Display(5, "Max steps/frame", "Time")]
public int MaxStepPerFrame { get; set; }

Property Value

int

ParallelUpdate

Allow entity synchronization to occur across multiple threads instead of just the main thread

[Display(1, "Parallel Update", null)]
public bool ParallelUpdate { get; set; }

Property Value

bool

PoseAngularDamping

Controls angular damping, how fast object loose their angular velocity

[Display(9, "Angular Damping", "Forces")]
public float PoseAngularDamping { get; set; }

Property Value

float

PoseGravity

Global gravity settings. This gravity will be applied to all bodies in the simulations that are not kinematic.

[Display(7, "Gravity", "Forces")]
public Vector3 PoseGravity { get; set; }

Property Value

Vector3

PoseLinearDamping

Controls linear damping, how fast object loose their linear velocity

[Display(8, "Linear Damping", "Forces")]
public float PoseLinearDamping { get; set; }

Property Value

float

Simulation

Accessing and altering this object is inherently unsupported and unsafe, this is the internal bepu simulation.

public Simulation Simulation { get; }

Property Value

Simulation

SoftStartDuration

The duration for the SoftStart; when the simulation starts up, more SolverSubStep run to improve constraints stability and let them come to rest sooner.

[Display(12, "SoftStart Duration", "Constraints")]
public TimeSpan SoftStartDuration { get; set; }

Property Value

TimeSpan

Remarks

Negative or 0 disables this feature.

SoftStartSubstepFactor

Multiplier over SolverSubStep during Soft Start

[Display(13, "SoftStart Substep factor", "Constraints")]
public int SoftStartSubstepFactor { get; set; }

Property Value

int

SolverIteration

The number of iterations for the solver

[Display(10, "Solver Iteration", "Constraints")]
public int SolverIteration { get; init; }

Property Value

int

Remarks

Smaller values improve performance at the cost of stability and precision.

SolverSubStep

The number of sub-steps used when solving constraints

[Display(11, "Solver SubStep", "Constraints")]
public int SolverSubStep { get; init; }

Property Value

int

Remarks

Smaller values improve performance at the cost of stability and precision.

TimeScale

The speed of the simulation compared to real-time.

[Display(4, "Time Scale", "Time")]
public float TimeScale { get; set; }

Property Value

float

Remarks

This stacks with GameTime.Factor, changing that one already affects the simulation speed.

UsePerBodyAttributes

Allows for per-body features like Gravity at a cost to the simulation's performance

[Display(6, "Per Body Attributes", "Forces")]
public bool UsePerBodyAttributes { get; set; }

Property Value

bool

Remarks

Gravity will be ignored if this is false.

Methods

AfterUpdate()

Yields execution until right after the next physics tick

public BepuSimulation.TickAwaiter AfterUpdate()

Returns

BepuSimulation.TickAwaiter

Task that will resume next tick.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetComponent(BodyHandle) 

public BodyComponent GetComponent(BodyHandle handle)

Parameters

handle BodyHandle

Returns

BodyComponent

GetComponent(CollidableReference) 

public CollidableComponent GetComponent(CollidableReference collidable)

Parameters

collidable CollidableReference

Returns

CollidableComponent

GetComponent(StaticHandle) 

public StaticComponent GetComponent(StaticHandle handle)

Parameters

handle StaticHandle

Returns

StaticComponent

NextUpdate()

Yields execution until right before the next physics tick

public BepuSimulation.TickAwaiter NextUpdate()

Returns

BepuSimulation.TickAwaiter

Task that will resume next tick.

OverlapInfo<TShape>(in TShape, in RigidPose, Span<OverlapInfoStack>, CollisionMask)

Enumerates all overlap info for any shape and sub-shapes found to be overlapping with shape

public ConversionEnum<ManagedConverter, OverlapInfoStack, OverlapInfo> OverlapInfo<TShape>(in TShape shape, in RigidPose pose, Span<OverlapInfoStack> buffer, CollisionMask collisionMask = CollisionMask.Everything) where TShape : unmanaged, IConvexShape

Parameters

shape TShape

The shape used to test for overlap

pose RigidPose

Position the shape is on for this test

buffer Span<OverlapInfoStack>

A temporary buffer which is used as a backing array to write to, its length defines the maximum amount of info you want to read. It is used by the returned enumerator as its backing array from which you read

collisionMask CollisionMask

Which layer should be hit

Returns

ConversionEnum<ManagedConverter, OverlapInfoStack, OverlapInfo>

Type Parameters

TShape

A bepu BepuPhysics.Collidables.IConvexShape representing the shape that will be used when testing for overlap

Remarks

Multiple info may come from the same CollidableComponent when it is a compound shape

Overlap<TShape>(in TShape, in RigidPose, ICollection<OverlapInfo>, CollisionMask)

Appends any physics object into collection if it was found to be overlapping with shape

public void Overlap<TShape>(in TShape shape, in RigidPose pose, ICollection<OverlapInfo> collection, CollisionMask collisionMask = CollisionMask.Everything) where TShape : unmanaged, IConvexShape

Parameters

shape TShape

The shape used to test for overlap

pose RigidPose

Position the shape is on for this test

collection ICollection<OverlapInfo>

The collection used to store overlapped shapes into. Note that the collection is not cleared before items are added to it

collisionMask CollisionMask

Which layer should be hit

Type Parameters

TShape

Remarks

The collection is not cleared before appending items into it

Overlap<TShape>(in TShape, in RigidPose, Span<CollidableStack>, CollisionMask)

Enumerates any physics object found to be overlapping with shape

public ConversionEnum<ManagedConverter, CollidableStack, CollidableComponent> Overlap<TShape>(in TShape shape, in RigidPose pose, Span<CollidableStack> buffer, CollisionMask collisionMask = CollisionMask.Everything) where TShape : unmanaged, IConvexShape

Parameters

shape TShape

The shape used to test for overlap

pose RigidPose

Position the shape is on for this test

buffer Span<CollidableStack>

A temporary buffer which is used as a backing array to write to, its length defines the maximum amount of info you want to read. It is used by the returned enumerator as its backing array from which you read

collisionMask CollisionMask

Which layer should be hit

Returns

ConversionEnum<ManagedConverter, CollidableStack, CollidableComponent>

Type Parameters

TShape

A bepu BepuPhysics.Collidables.IConvexShape representing the shape that will be used when testing for overlap

RayCast(in Vector3, in Vector3, float, out HitInfo, CollisionMask)

Finds the closest intersection between this ray and shapes in the simulation.

public bool RayCast(in Vector3 origin, in Vector3 dir, float maxDistance, out HitInfo result, CollisionMask collisionMask = CollisionMask.Everything)

Parameters

origin Vector3

The start position for this ray

dir Vector3

The normalized direction the ray is facing

maxDistance float

The maximum from the origin that hits will be collected

result HitInfo

An intersection in the world when this method returns true, an undefined value when this method returns false

collisionMask CollisionMask

Which layer should be hit

Returns

bool

True when the given ray intersects with a shape, false otherwise

RayCastPenetrating(in Vector3, in Vector3, float, ICollection<HitInfo>, CollisionMask)

Collect intersections between the given ray and shapes in this simulation. Hits are NOT sorted.

public void RayCastPenetrating(in Vector3 origin, in Vector3 dir, float maxDistance, ICollection<HitInfo> collection, CollisionMask collisionMask = CollisionMask.Everything)

Parameters

origin Vector3

The start position for this ray

dir Vector3

The normalized direction the ray is facing

maxDistance float

The maximum from the origin that hits will be collected

collection ICollection<HitInfo>

The collection used to store hits into, the collection is not cleared before usage, hits are appended to it

collisionMask CollisionMask

Which layer should be hit

Remarks

There are no guarantees as to the order hits are returned in.

RayCastPenetrating(in Vector3, in Vector3, float, Span<HitInfoStack>, CollisionMask)

Collect intersections between the given ray and shapes in this simulation.

public ConversionEnum<ManagedConverter, HitInfoStack, HitInfo> RayCastPenetrating(in Vector3 origin, in Vector3 dir, float maxDistance, Span<HitInfoStack> buffer, CollisionMask collisionMask = CollisionMask.Everything)

Parameters

origin Vector3

The start position for this ray

dir Vector3

The normalized direction the ray is facing

maxDistance float

The maximum from the origin that hits will be collected

buffer Span<HitInfoStack>

A temporary buffer which is used as a backing array to write to, its length defines the maximum amount of info you want to read. It is used by the returned enumerator as its backing array from which you read

collisionMask CollisionMask

Which layer should be hit

Returns

ConversionEnum<ManagedConverter, HitInfoStack, HitInfo>

Remarks

When there are more hits than buffer can accomodate, returns only the closest hits.
There are no guarantees as to the order hits are returned in.

ResetSoftStart()

Reset the SoftStart to SoftStartDuration.

public void ResetSoftStart()

ShouldPerformPhysicsTest(CollisionMask, CollidableReference)

Whether a physics test with mask against collidable should be performed or entirely ignored

public bool ShouldPerformPhysicsTest(CollisionMask mask, CollidableReference collidable)

Parameters

mask CollisionMask
collidable CollidableReference

Returns

bool

True when it should be performed, false when it should be ignored

SweepCastPenetrating<TShape>(in TShape, in RigidPose, in BodyVelocity, float, ICollection<HitInfo>, CollisionMask)

Finds contacts between shape and other shapes in the simulation when thrown in velocity direction.

public void SweepCastPenetrating<TShape>(in TShape shape, in RigidPose pose, in BodyVelocity velocity, float maxDistance, ICollection<HitInfo> collection, CollisionMask collisionMask = CollisionMask.Everything) where TShape : unmanaged, IConvexShape

Parameters

shape TShape

The shape thrown at the scene

pose RigidPose

Initial position for the shape

velocity BodyVelocity

Velocity used to throw the shape

maxDistance float

The maximum distance, or amount of time along the path of the velocity

collection ICollection<HitInfo>

The collection used to store hits into, the collection is not cleared before usage, hits are appended to it

collisionMask CollisionMask

Which layer should be hit

Type Parameters

TShape

Remarks

There are no guarantees as to the order hits are returned in.

SweepCastPenetrating<TShape>(in TShape, in RigidPose, in BodyVelocity, float, Span<HitInfoStack>, CollisionMask)

Finds contacts between shape and other shapes in the simulation when thrown in velocity direction.

public ConversionEnum<ManagedConverter, HitInfoStack, HitInfo> SweepCastPenetrating<TShape>(in TShape shape, in RigidPose pose, in BodyVelocity velocity, float maxDistance, Span<HitInfoStack> buffer, CollisionMask collisionMask = CollisionMask.Everything) where TShape : unmanaged, IConvexShape

Parameters

shape TShape

The shape thrown at the scene

pose RigidPose

Initial position for the shape

velocity BodyVelocity

Velocity used to throw the shape

maxDistance float

The maximum distance, or amount of time along the path of the velocity

buffer Span<HitInfoStack>

A temporary buffer which is used as a backing array to write to, its length defines the maximum amount of info you want to read. It is used by the returned enumerator as its backing array from which you read

collisionMask CollisionMask

Which layer should be hit

Returns

ConversionEnum<ManagedConverter, HitInfoStack, HitInfo>

Type Parameters

TShape

Remarks

When there are more hits than buffer can accomodate, returns only the closest hits
There are no guarantees as to the order hits are returned in.

SweepCast<TShape>(in TShape, in RigidPose, in BodyVelocity, float, out HitInfo, CollisionMask)

Finds the closest contact between shape and other shapes in the simulation when thrown in velocity direction.

public bool SweepCast<TShape>(in TShape shape, in RigidPose pose, in BodyVelocity velocity, float maxDistance, out HitInfo result, CollisionMask collisionMask = CollisionMask.Everything) where TShape : unmanaged, IConvexShape

Parameters

shape TShape

The shape thrown at the scene

pose RigidPose

Initial position for the shape

velocity BodyVelocity

Velocity used to throw the shape

maxDistance float

The maximum distance, or amount of time along the path of the velocity

result HitInfo

The resulting contact when this method returns true, an undefined value when this method returns false

collisionMask CollisionMask

Which layer should be hit

Returns

bool

True when the given ray intersects with a shape, false otherwise

Type Parameters

TShape
Edit this page