Table of Contents

Class b2World

Namespace
Gym.Box2D
Assembly
Gym.Environments.dll

The physics world: bodies, joints and contacts, stepped with Step(float, int, int). Not thread-safe: one world belongs to one thread at a time (each env instance owns its own world).

public class b2World
Inheritance
b2World
Inherited Members
Extension Methods

Remarks

Constructors

b2World(b2Vec2?, bool)

A world, as pybox2d's b2World(gravity=(0, -10), doSleep=True): Box2D's world with the given gravity; doSleep is only recorded, in DoSleep.

public b2World(b2Vec2? gravity = null, bool doSleep = true)

Parameters

gravity b2Vec2?

The gravity; null for pybox2d's default (0, -10).

doSleep bool

Recorded in DoSleep; it does not stop bodies sleeping.

Remarks

Footgun, kept from pybox2d 2.3.10 for parity: doSleep never reaches the engine. pybox2d's constructor runs self.allowSleeping = doSleep, and its world has no allowSleeping property (only GetAllowSleeping/SetAllowSleeping), so the value lands in a plain attribute and bodies fall asleep either way (measured against live pybox2d). Call SetAllowSleeping(bool) to turn sleeping off.

Properties

AutoClearForces

Whether forces are cleared after each step (pybox2d's autoClearForces, on by default).

public bool AutoClearForces { get; set; }

Property Value

bool

Bodies

Every body, newest first (pybox2d's bodies); a new list on each read.

public IReadOnlyList<b2Body> Bodies { get; }

Property Value

IReadOnlyList<b2Body>

BodyCount

The number of bodies.

public int BodyCount { get; }

Property Value

int

ContactCount

The number of contacts (touching or not).

public int ContactCount { get; }

Property Value

int

ContactFilter

The contact filter (pybox2d's contactFilter); null reads back until one is set, while Box2D's default filter keeps filtering.

public b2ContactFilter? ContactFilter { get; set; }

Property Value

b2ContactFilter

ContactListener

The contact listener (pybox2d's contactListener). Gymnasium's envs set a ContactDetector here; its callbacks run inside Step(double, int, int).

public b2ContactListener? ContactListener { get; set; }

Property Value

b2ContactListener

Contacts

Every contact, newest first (pybox2d's contacts); a new list on each read.

public IReadOnlyList<b2Contact> Contacts { get; }

Property Value

IReadOnlyList<b2Contact>

ContinuousPhysics

Whether continuous collision runs (pybox2d's continuousPhysics).

public bool ContinuousPhysics { get; set; }

Property Value

bool

DoSleep

The constructor's doSleep, as pybox2d keeps it in its plain allowSleeping attribute: a record no engine code reads (see GetAllowSleeping() for the engine's flag).

public bool DoSleep { get; }

Property Value

bool

Gravity

The gravity (pybox2d's gravity); changing it does not wake sleeping bodies.

public b2Vec2 Gravity { get; set; }

Property Value

b2Vec2

JointCount

The number of joints.

public int JointCount { get; }

Property Value

int

Joints

Every joint, newest first (pybox2d's joints); a new list on each read.

public IReadOnlyList<b2Joint> Joints { get; }

Property Value

IReadOnlyList<b2Joint>

Locked

Whether the world is stepping (pybox2d's locked): creating or destroying anything then fails.

public bool Locked { get; }

Property Value

bool

ProxyCount

The number of broad-phase proxies.

public int ProxyCount { get; }

Property Value

int

SubStepping

Whether each step stops after one time-of-impact sub-step (pybox2d's subStepping; for debugging).

public bool SubStepping { get; set; }

Property Value

bool

WarmStarting

Whether the solvers warm-start from the last step's impulses (pybox2d's warmStarting).

public bool WarmStarting { get; set; }

Property Value

bool

Methods

ClearForces()

Zeroes every body's accumulated force and torque (needed only when AutoClearForces is off).

public void ClearForces()

CreateBody(b2BodyDef)

Creates a body from a definition, then its fixtures in order (pybox2d's CreateBody(defn)): each of Fixtures, then each of Shapes with ShapeFixture.

public b2Body CreateBody(b2BodyDef def)

Parameters

def b2BodyDef

The definition.

Returns

b2Body

The body.

Exceptions

AssertionError

Thrown while the world is stepping, or for an invalid definition or shape.

CreateDynamicBody(b2FixtureDef, b2Vec2?, double, object?)

Creates a dynamic body with one fixture (pybox2d accepts a single fixture definition for fixtures).

public b2Body CreateDynamicBody(b2FixtureDef fixtures, b2Vec2? position = null, double angle = 0, object? userData = null)

Parameters

fixtures b2FixtureDef

The fixture.

position b2Vec2?

The body origin's world position.

angle double

The angle in radians.

userData object

The user data.

Returns

b2Body

The body.

Exceptions

AssertionError

Thrown while the world is stepping, or for an invalid shape.

OverflowError

Thrown for a scalar beyond the float32 range.

CreateDynamicBody(b2Vec2?, double, IEnumerable<b2FixtureDef>?, IEnumerable<b2Shape>?, b2FixtureDef?, b2Vec2?, double, double, double, bool, bool, bool, bool, bool, double, object?)

Creates a dynamic body (pybox2d's CreateDynamicBody(**kwargs)): a b2BodyDef of these arguments, then its fixtures in order.

public b2Body CreateDynamicBody(b2Vec2? position = null, double angle = 0, IEnumerable<b2FixtureDef>? fixtures = null, IEnumerable<b2Shape>? shapes = null, b2FixtureDef? shapeFixture = null, b2Vec2? linearVelocity = null, double angularVelocity = 0, double linearDamping = 0, double angularDamping = 0, bool allowSleep = true, bool awake = true, bool fixedRotation = false, bool bullet = false, bool active = true, double gravityScale = 1, object? userData = null)

Parameters

position b2Vec2?

The body origin's world position.

angle double

The angle in radians.

fixtures IEnumerable<b2FixtureDef>

The fixtures to create, in order.

shapes IEnumerable<b2Shape>

Shapes to create fixtures of with shapeFixture's material, after fixtures.

shapeFixture b2FixtureDef

The material for shapes (Box2D's defaults when null).

linearVelocity b2Vec2?

The initial linear velocity.

angularVelocity double

The initial angular velocity.

linearDamping double

The linear damping.

angularDamping double

The angular damping.

allowSleep bool

Whether the body may sleep.

awake bool

Whether it starts awake.

fixedRotation bool

Whether it may not rotate.

bullet bool

Whether it is a bullet.

active bool

Whether it starts active.

gravityScale double

The gravity scale.

userData object

The user data.

Returns

b2Body

The body.

Exceptions

AssertionError

Thrown while the world is stepping, or for an invalid definition or shape.

OverflowError

Thrown for a scalar beyond the float32 range.

TypeError

Thrown for a vector coordinate beyond the float32 range.

CreateJoint(b2JointDef)

Creates a joint (pybox2d's CreateJoint(defn)), refusing a definition without both bodies first, as pybox2d does before Box2D sees it.

public b2Joint CreateJoint(b2JointDef def)

Parameters

def b2JointDef

The definition.

Returns

b2Joint

The joint.

Exceptions

ValueError

Thrown when bodyA or bodyB is unset: bodyA and bodyB must be set.

AssertionError

Thrown while the world is stepping, for one body twice, or for a joint type this port lacks.

CreateKinematicBody(b2Vec2?, double, IEnumerable<b2FixtureDef>?, b2Vec2?, double, object?)

Creates a kinematic body (pybox2d's CreateKinematicBody(**kwargs)).

public b2Body CreateKinematicBody(b2Vec2? position = null, double angle = 0, IEnumerable<b2FixtureDef>? fixtures = null, b2Vec2? linearVelocity = null, double angularVelocity = 0, object? userData = null)

Parameters

position b2Vec2?

The body origin's world position.

angle double

The angle in radians.

fixtures IEnumerable<b2FixtureDef>

The fixtures to create, in order.

linearVelocity b2Vec2?

The linear velocity.

angularVelocity double

The angular velocity.

userData object

The user data.

Returns

b2Body

The body.

Exceptions

AssertionError

Thrown while the world is stepping, or for an invalid shape.

OverflowError

Thrown for a scalar beyond the float32 range.

CreateStaticBody(b2FixtureDef, b2Vec2?, double, object?)

Creates a static body with one fixture.

public b2Body CreateStaticBody(b2FixtureDef fixtures, b2Vec2? position = null, double angle = 0, object? userData = null)

Parameters

fixtures b2FixtureDef

The fixture.

position b2Vec2?

The body origin's world position.

angle double

The angle in radians.

userData object

The user data.

Returns

b2Body

The body.

Exceptions

AssertionError

Thrown while the world is stepping, or for an invalid shape.

OverflowError

Thrown for a scalar beyond the float32 range.

CreateStaticBody(b2Shape, b2Vec2?, double)

Creates a static body with one shape and Box2D's default material (pybox2d's CreateStaticBody(shapes=shape)).

public b2Body CreateStaticBody(b2Shape shapes, b2Vec2? position = null, double angle = 0)

Parameters

shapes b2Shape

The shape.

position b2Vec2?

The body origin's world position.

angle double

The angle in radians.

Returns

b2Body

The body.

Exceptions

AssertionError

Thrown while the world is stepping, or for an invalid shape.

OverflowError

Thrown for a scalar beyond the float32 range.

CreateStaticBody(b2Vec2?, double, IEnumerable<b2FixtureDef>?, IEnumerable<b2Shape>?, b2FixtureDef?, object?)

Creates a static body (pybox2d's CreateStaticBody(**kwargs)).

public b2Body CreateStaticBody(b2Vec2? position = null, double angle = 0, IEnumerable<b2FixtureDef>? fixtures = null, IEnumerable<b2Shape>? shapes = null, b2FixtureDef? shapeFixture = null, object? userData = null)

Parameters

position b2Vec2?

The body origin's world position.

angle double

The angle in radians.

fixtures IEnumerable<b2FixtureDef>

The fixtures to create, in order.

shapes IEnumerable<b2Shape>

Shapes to create fixtures of with shapeFixture's material, after fixtures.

shapeFixture b2FixtureDef

The material for shapes (Box2D's defaults when null).

userData object

The user data.

Returns

b2Body

The body.

Exceptions

AssertionError

Thrown while the world is stepping, or for an invalid shape.

OverflowError

Thrown for a scalar beyond the float32 range.

DestroyBody(b2Body)

Destroys a body with its joints (said goodbye to), contacts and fixtures (said goodbye to, proxies destroyed).

public void DestroyBody(b2Body b)

Parameters

b b2Body

The body.

Exceptions

AssertionError

Thrown while the world is stepping or when it has no bodies.

DestroyJoint(b2Joint)

Destroys a joint, waking its bodies; their contacts are re-filtered when the joint forbade collision.

public void DestroyJoint(b2Joint j)

Parameters

j b2Joint

The joint.

Exceptions

AssertionError

Thrown while the world is stepping.

GetAllowSleeping()

Whether bodies may fall asleep (pybox2d's GetAllowSleeping); true unless SetAllowSleeping(bool) turned it off.

public bool GetAllowSleeping()

Returns

bool

The flag.

RayCast(b2RayCastCallback, b2Vec2, b2Vec2)

Casts a ray from point1 to point2, telling the callback about each fixture hit (in tree order); the callback's return value clips or stops the ray.

public void RayCast(b2RayCastCallback callback, b2Vec2 point1, b2Vec2 point2)

Parameters

callback b2RayCastCallback

The callback.

point1 b2Vec2

The ray's start.

point2 b2Vec2

The ray's end.

Exceptions

AssertionError

Thrown for a ray of zero length: r.LengthSquared() > 0.0f.

SetAllowSleeping(bool)

Allows or forbids sleeping (pybox2d's SetAllowSleeping, the only way it turns sleeping off); forbidding wakes every body.

public void SetAllowSleeping(bool flag)

Parameters

flag bool

True to allow sleeping.

Step(double, int, int)

Steps the world (pybox2d's Step(timeStep, velocityIterations, positionIterations)): the time step is rounded to float32 first, as SWIG converts it, so 1.0 / 50 becomes 0.02f.

public void Step(double timeStep, int velocityIterations, int positionIterations)

Parameters

timeStep double

The time step in seconds.

velocityIterations int

The velocity iterations (Gymnasium's envs use 6 * 30).

positionIterations int

The position iterations (Gymnasium's envs use 2 * 30).

Exceptions

OverflowError

Thrown for a time step beyond the float32 range.

AssertionError

Thrown on an internal inconsistency, leaving the world locked as pybox2d does.