Class PhysicsWorld

Namespace: Box3D

Assembly: Box3D.NET.dll

A simulation world: the container for bodies, shapes and constraints, and the thing you step forward in time.

public sealed class PhysicsWorld : IDisposable

Examples

A ball falling onto the ground:

using var world = new PhysicsWorld(WorldSettings.Default with
{
    Gravity = new Vector3(0.0f, -9.81f, 0.0f),
});

Body ground = world.CreateBody(BodyDefinition.Static());
ground.AddBox(new Box(new Vector3(50.0f, 0.5f, 50.0f)));

Body ball = world.CreateBody(BodyDefinition.Dynamic(new Vector3(0.0f, 10.0f, 0.0f)));
ball.AddSphere(new Sphere(0.5f));

for (int frame = 0; frame < 120; frame++)
{
    world.Step(1.0f / 60.0f);
}

Console.WriteLine(ball.Position);

Remarks

Worlds are completely independent and may be stepped in parallel on separate threads. Up to Box3D.PhysicsWorld.MaxCount of them may exist at once.

This is the only type in the library that owns a native resource, and so the only one that is System.IDisposable. Bodies, shapes and joints are handles into a world and die with it. Dispose the world and everything in it goes with it.

A world is not thread-safe. One thread may step it, and no other thread may touch it or anything in it while that step is running.

Creating and disposing worlds is the exception: those are serialised process-wide and may be done from any thread. Box3D itself makes no such promise — its table of worlds is global and unguarded — so this class holds the mutex the engine asks callers to hold.

Constructors

PhysicsWorld(): Creates a world with the engine's default settings.
PhysicsWorld(WorldSettings): Creates a world with the given settings.
PhysicsWorld(WorldSettings, IDebugShapeFactory?): Creates a world that can draw its shapes, given something to build the drawables with.

Properties

AwakeBodyCount: Gets the number of bodies currently awake.
Bounds: Gets the bounding box covering the whole simulation.
ContinuousEnabled: Gets or sets a value indicating whether continuous collision is enabled.
Count: Gets the number of worlds currently alive in this process.
Events: Gets the events raised by the most recent Box3D.PhysicsWorld.Step(System.Single,System.Int32).
Gravity: Gets or sets the gravity vector, usually in metres per second squared.
IsDisposed: Gets a value indicating whether this world has been disposed.
MaxCount: Gets the maximum number of worlds that may exist at the same time.
Reference: Gets a reference identifying this world, for comparing against the World of a body, shape or joint.
SleepEnabled: Gets or sets a value indicating whether bodies may sleep.
UserData: Gets or sets the application identifier attached to this world.
WorkerCount: Gets the number of worker threads this world is using.

Methods

CastCapsule(Capsule, Vector3, Vector3, QueryFilter?): Sweeps a character capsule through the world and reports how far it got.
CollideCapsule<TCallback>(Capsule, Vector3, ref TCallback, QueryFilter?): Finds every surface a character capsule is touching, for the plane solver.
CreateBody(BodyDefinition): Creates a body in this world.
CreateBody(BodyType, Vector3): Creates a body with the default settings for its type.
CreateDistanceJoint(DistanceJointDefinition): Creates a distance joint, the basis for ropes and springs.
CreateDynamicBody(Vector3, Quaternion?): Creates a fully simulated body that responds to forces and collisions.
CreateFilterJoint(FilterJointDefinition): Creates a filter joint, stopping two bodies from colliding.
CreateKinematicBody(Vector3, Quaternion?): Creates a body the application moves itself, which pushes dynamic bodies without being pushed back.
CreateMotorJoint(MotorJointDefinition): Creates a motor joint, driving the relative pose and velocity of two bodies.
CreateParallelJoint(ParallelJointDefinition): Creates a parallel joint, keeping two frames' z axes aligned.
CreatePrismaticJoint(PrismaticJointDefinition): Creates a slider.
CreateRevoluteJoint(RevoluteJointDefinition): Creates a hinge.
CreateSphericalJoint(SphericalJointDefinition): Creates a ball-in-socket joint.
CreateStaticBody(Vector3, Quaternion?): Creates an immovable body, for level geometry.
CreateWeldJoint(WeldJointDefinition): Creates a weld joint, holding two bodies rigidly together.
CreateWheelJoint(WheelJointDefinition): Creates a wheel joint with suspension, spin and optional steering.
Dispose(): Destroys the world and everything in it.
Draw<T>(ref T, in DebugDrawOptions): Emits the world's debug geometry to a drawer.
Explode(Vector3, float, float, float, ulong): Applies a radial impulse to every shape within reach, scaled by how much of each shape faces the blast.
OverlapBounds<TCallback>(BoundingBox, ref TCallback, QueryFilter?): Finds every shape whose bounding box overlaps the given box.
OverlapBox<TCallback>(Vector3, Vector3, ref TCallback, QueryFilter?): Finds every shape whose bounding box overlaps a box centred on a point.
Raycast<TCallback>(Vector3, Vector3, ref TCallback, QueryFilter?): Casts a ray through the world, reporting every shape it reaches to a callback.
RaycastClosest(Vector3, Vector3, QueryFilter?): Casts a ray and returns the nearest shape it hits.
Step(float, int): Advances the simulation by one time step.

Table of Contents

Class PhysicsWorld

Inheritance

Implements

Inherited Members

Extension Methods

Examples

Remarks

Constructors

Properties

Methods