Class Box2DSimulation

Namespace

Stride.CommunityToolkit.Box2D

Assembly

Stride.CommunityToolkit.Box2D.dll

High-level integration facade between Box2D.NET and Stride entities. Wraps a reusable PhysicsWorld2D plus an entity/body bridge and exposes a simplified stepping, query and event API, mirroring the role BepuSimulation plays for Bepu physics in Stride.

public sealed class Box2DSimulation : IDisposable

Inheritance

object

Box2DSimulation

Implements

IDisposable

Constructors

Box2DSimulation(PhysicsStepSettings?)

Creates a new simulation instance with a fresh Box2D world.

public Box2DSimulation(PhysicsStepSettings? settings = null)

Parameters

settings PhysicsStepSettings

Optional stepping and threading configuration; defaults to PhysicsStepSettings defaults.

Properties

EnableContactEvents

Enable dispatch of begin/end contact events.

public bool EnableContactEvents { get; set; }

Property Value

bool

EnableHitEvents

Enable dispatch of hit (post-solve / impact style) events.

public bool EnableHitEvents { get; set; }

Property Value

bool

EnableSensorEvents

Enable dispatch of sensor overlap events.

public bool EnableSensorEvents { get; set; }

Property Value

bool

Enabled

Whether simulation stepping and event processing should occur.

public bool Enabled { get; set; }

Property Value

bool

Gravity

World gravity applied to dynamic bodies.

public Vector2 Gravity { get; set; }

Property Value

Vector2

Joints

Joint factories with world-space anchors, for body ids or the entities this simulation created bodies for. See Joints2D for the joint types and their options.

public SimulationJoints2D Joints { get; }

Property Value

SimulationJoints2D

MaxStepsPerFrame

Maximum number of fixed steps processed per frame, to avoid the spiral of death.

public int MaxStepsPerFrame { get; set; }

Property Value

int

TargetHz

Target simulation frequency in hertz used to derive the fixed step size.

public int TargetHz { get; set; }

Property Value

int

TimeScale

Multiplier applied to incoming delta time before fixed-step accumulation.

public float TimeScale { get; set; }

Property Value

float

Methods

CastCircleClosest(Vector2, float, Vector2, B2QueryFilter)

Sweeps a circle (or a point, when radius is zero) along translation and returns the closest thing it strikes.

public ShapeCastHit? CastCircleClosest(Vector2 center, float radius, Vector2 translation, B2QueryFilter filter)

Parameters

center Vector2

World-space centre of the circle at the start of the sweep.

radius float

Circle radius; zero casts a point.

translation Vector2

The sweep, as a world-space displacement.

filter B2QueryFilter

Category and mask bits the struck shapes must satisfy.

Returns

ShapeCastHit?

The closest hit, or null when the sweep is clear.

CastSegmentClosest(Vector2, Vector2, Vector2, B2QueryFilter)

Sweeps a line segment along translation and returns the closest thing it strikes.

public ShapeCastHit? CastSegmentClosest(Vector2 a, Vector2 b, Vector2 translation, B2QueryFilter filter)

Parameters

a Vector2

One end of the segment at the start of the sweep, in world space.

b Vector2

The other end.

translation Vector2

The sweep, as a world-space displacement.

filter B2QueryFilter

Category and mask bits the struck shapes must satisfy.

Returns

ShapeCastHit?

The closest hit, or null when the sweep is clear.

CreateDynamicBody(Vector3, float)

Creates a dynamic body without an associated entity at a world position.

public B2BodyId CreateDynamicBody(Vector3 position, float rotation = 0)

Parameters

position Vector3

Initial world position (Z is ignored).

rotation float

Initial rotation in radians about the Z axis.

Returns

B2BodyId

The id of the created body.

CreateDynamicBody(Entity, Vector3, float)

Creates a dynamic body associated with the given entity at a world position.

public B2BodyId CreateDynamicBody(Entity entity, Vector3 position, float rotation = 0)

Parameters

entity Entity

The entity driven by the body.

position Vector3

Initial world position (Z is ignored).

rotation float

Initial rotation in radians about the Z axis.

Returns

B2BodyId

The id of the created body.

CreateKinematicBody(Vector3, float)

Creates a kinematic body without an associated entity at a world position.

public B2BodyId CreateKinematicBody(Vector3 position, float rotation = 0)

Parameters

position Vector3

Initial world position (Z is ignored).

rotation float

Initial rotation in radians about the Z axis.

Returns

B2BodyId

The id of the created body.

CreateKinematicBody(Entity, Vector3, float)

Creates a kinematic body associated with the given entity at a world position.

public B2BodyId CreateKinematicBody(Entity entity, Vector3 position, float rotation = 0)

Parameters

entity Entity

The entity driven by the body.

position Vector3

Initial world position (Z is ignored).

rotation float

Initial rotation in radians about the Z axis.

Returns

B2BodyId

The id of the created body.

CreateStaticBody(Vector3, float)

Creates a static body without an associated entity at a world position.

public B2BodyId CreateStaticBody(Vector3 position, float rotation = 0)

Parameters

position Vector3

Initial world position (Z is ignored).

rotation float

Initial rotation in radians about the Z axis.

Returns

B2BodyId

The id of the created body.

CreateStaticBody(Entity, Vector3, float)

Creates a static body associated with the given entity at a world position.

public B2BodyId CreateStaticBody(Entity entity, Vector3 position, float rotation = 0)

Parameters

entity Entity

The entity driven by the body.

position Vector3

Initial world position (Z is ignored).

rotation float

Initial rotation in radians about the Z axis.

Returns

B2BodyId

The id of the created body.

Dispose()

Disposes underlying world resources.

public void Dispose()

Explode(Vector2, float, float, float, ulong)

A radial blast: every shape within radius of position receives an impulse away from it.

public void Explode(Vector2 position, float radius, float impulsePerLength, float falloff = 0, ulong maskBits = 18446744073709551615)

Parameters

position Vector2

World-space centre of the blast.

radius float

Full-strength radius, in metres.

impulsePerLength float

Impulse per metre of shape perimeter facing the blast, in newton-seconds per metre. A broad flat body therefore takes more than a small round one of the same mass, which is what makes the effect read as a pressure wave rather than a point kick.

falloff float

Distance beyond the radius over which the impulse fades to nothing, in metres.

maskBits ulong

Collision category mask of the shapes affected; everything by default.

GetAllBodyIds()

Returns a snapshot list of all body ids tracked by the bridge.

public List<B2BodyId> GetAllBodyIds()

Returns

List<B2BodyId>

A new list with every tracked body id.

GetEntity(B2BodyId)

Gets the entity previously registered for the given body id (or null).

public Entity? GetEntity(B2BodyId bodyId)

Parameters

bodyId B2BodyId

The body to look up.

Returns

Entity

The associated entity, or null when the body has none.

GetWorldId()

Gets the underlying Box2D world id.

public B2WorldId GetWorldId()

Returns

B2WorldId

The native world id.

OverlapAABB(Vector2, Vector2)

Overlaps an AABB and returns all bodies within it.

public List<B2BodyId> OverlapAABB(Vector2 lowerBound, Vector2 upperBound)

Parameters

lowerBound Vector2

Lower corner of the AABB.

upperBound Vector2

Upper corner of the AABB.

Returns

List<B2BodyId>

List of body ids (no duplicates).

OverlapCircle(Vector2, float)

Overlaps a circle and returns all bodies within it.

public List<B2BodyId> OverlapCircle(Vector2 center, float radius)

Parameters

center Vector2

World-space circle center.

radius float

Circle radius.

Returns

List<B2BodyId>

List of body ids (no duplicates).

OverlapCircle(Vector2, float, B2QueryFilter)

Overlaps a circle and returns all bodies within it whose shapes pass filter.

public List<B2BodyId> OverlapCircle(Vector2 center, float radius, B2QueryFilter filter)

Parameters

center Vector2

World-space circle center.

radius float

Circle radius.

filter B2QueryFilter

Category and mask bits the overlapped shapes must satisfy.

Returns

List<B2BodyId>

List of body ids (no duplicates).

OverlapPoint(Vector2, float)

Tests if a point overlaps with any physics shape in the world.

public B2BodyId? OverlapPoint(Vector2 point, float querySize = 0.1)

Parameters

point Vector2

The point to test.

querySize float

Half-extent of the query box around the point.

Returns

B2BodyId?

The body id that was hit, or null if nothing was hit.

Raycast(Vector2, Vector2, float)

Performs a raycast and returns the first hit.

public RaycastHit? Raycast(Vector2 origin, Vector2 direction, float maxDistance)

Parameters

origin Vector2

Ray origin.

direction Vector2

Ray direction (normalized).

maxDistance float

Maximum distance to cast.

Returns

RaycastHit?

First hit or null if no hit.

RaycastAll(Vector2, Vector2, float)

Performs a raycast and returns all hits along the ray.

public List<RaycastHit> RaycastAll(Vector2 origin, Vector2 direction, float maxDistance)

Parameters

origin Vector2

Ray origin.

direction Vector2

Ray direction (normalized).

maxDistance float

Maximum distance to cast.

Returns

List<RaycastHit>

List of all hits along the ray.

RegisterContactEventHandler(IContactEventHandler)

Registers a contact event handler.

public void RegisterContactEventHandler(IContactEventHandler handler)

Parameters

handler IContactEventHandler

The handler to receive contact events.

RegisterSensorEventHandler(ISensorEventHandler)

Registers a sensor event handler.

public void RegisterSensorEventHandler(ISensorEventHandler handler)

Parameters

handler ISensorEventHandler

The handler to receive sensor events.

RegisterSimulationUpdate(IBox2DSimulationUpdate)

Registers a handler whose SimulationUpdate(Box2DSimulation, float) runs before and AfterSimulationUpdate(Box2DSimulation, float) after every fixed step; a handler is only registered once.

public void RegisterSimulationUpdate(IBox2DSimulationUpdate handler)

Parameters

handler IBox2DSimulationUpdate

The handler to invoke around each fixed step.

RemoveBody(Entity)

Removes the body associated with entity from the world if present.

public void RemoveBody(Entity entity)

Parameters

entity Entity

The entity whose body should be removed.

UnregisterContactEventHandler(IContactEventHandler)

Unregisters a contact event handler.

public void UnregisterContactEventHandler(IContactEventHandler handler)

Parameters

handler IContactEventHandler

The handler to remove.

UnregisterSensorEventHandler(ISensorEventHandler)

Unregisters a sensor event handler.

public void UnregisterSensorEventHandler(ISensorEventHandler handler)

Parameters

handler ISensorEventHandler

The handler to remove.

UnregisterSimulationUpdate(IBox2DSimulationUpdate)

Unregisters a simulation update handler.

public void UnregisterSimulationUpdate(IBox2DSimulationUpdate handler)

Parameters

handler IBox2DSimulationUpdate

The handler to remove.

Update(TimeSpan)

Advances the simulation by the elapsed real time, executing zero or more fixed steps.

public void Update(TimeSpan elapsed)

Parameters

elapsed TimeSpan

Frame time delta.