Class b2World
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
Reference: Box2D/Dynamics/b2World.cpp.
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
gravityb2Vec2?The gravity; null for pybox2d's default
(0, -10).doSleepboolRecorded 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
Bodies
Every body, newest first (pybox2d's bodies); a new list on each read.
public IReadOnlyList<b2Body> Bodies { get; }
Property Value
BodyCount
The number of bodies.
public int BodyCount { get; }
Property Value
ContactCount
The number of contacts (touching or not).
public int ContactCount { get; }
Property Value
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
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
Contacts
Every contact, newest first (pybox2d's contacts); a new list on each read.
public IReadOnlyList<b2Contact> Contacts { get; }
Property Value
ContinuousPhysics
Whether continuous collision runs (pybox2d's continuousPhysics).
public bool ContinuousPhysics { get; set; }
Property Value
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
Gravity
The gravity (pybox2d's gravity); changing it does not wake sleeping bodies.
public b2Vec2 Gravity { get; set; }
Property Value
JointCount
The number of joints.
public int JointCount { get; }
Property Value
Joints
Every joint, newest first (pybox2d's joints); a new list on each read.
public IReadOnlyList<b2Joint> Joints { get; }
Property Value
Locked
Whether the world is stepping (pybox2d's locked): creating or destroying anything then fails.
public bool Locked { get; }
Property Value
ProxyCount
The number of broad-phase proxies.
public int ProxyCount { get; }
Property Value
SubStepping
Whether each step stops after one time-of-impact sub-step (pybox2d's subStepping; for debugging).
public bool SubStepping { get; set; }
Property Value
WarmStarting
Whether the solvers warm-start from the last step's impulses (pybox2d's warmStarting).
public bool WarmStarting { get; set; }
Property Value
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
defb2BodyDefThe 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
fixturesb2FixtureDefThe fixture.
positionb2Vec2?The body origin's world position.
angledoubleThe angle in radians.
userDataobjectThe 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
positionb2Vec2?The body origin's world position.
angledoubleThe angle in radians.
fixturesIEnumerable<b2FixtureDef>The fixtures to create, in order.
shapesIEnumerable<b2Shape>Shapes to create fixtures of with
shapeFixture's material, afterfixtures.shapeFixtureb2FixtureDefThe material for
shapes(Box2D's defaults when null).linearVelocityb2Vec2?The initial linear velocity.
angularVelocitydoubleThe initial angular velocity.
linearDampingdoubleThe linear damping.
angularDampingdoubleThe angular damping.
allowSleepboolWhether the body may sleep.
awakeboolWhether it starts awake.
fixedRotationboolWhether it may not rotate.
bulletboolWhether it is a bullet.
activeboolWhether it starts active.
gravityScaledoubleThe gravity scale.
userDataobjectThe 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
defb2JointDefThe definition.
Returns
- b2Joint
The joint.
Exceptions
- ValueError
Thrown when
bodyAorbodyBis 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
positionb2Vec2?The body origin's world position.
angledoubleThe angle in radians.
fixturesIEnumerable<b2FixtureDef>The fixtures to create, in order.
linearVelocityb2Vec2?The linear velocity.
angularVelocitydoubleThe angular velocity.
userDataobjectThe 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
fixturesb2FixtureDefThe fixture.
positionb2Vec2?The body origin's world position.
angledoubleThe angle in radians.
userDataobjectThe 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
shapesb2ShapeThe shape.
positionb2Vec2?The body origin's world position.
angledoubleThe 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
positionb2Vec2?The body origin's world position.
angledoubleThe angle in radians.
fixturesIEnumerable<b2FixtureDef>The fixtures to create, in order.
shapesIEnumerable<b2Shape>Shapes to create fixtures of with
shapeFixture's material, afterfixtures.shapeFixtureb2FixtureDefThe material for
shapes(Box2D's defaults when null).userDataobjectThe 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
bb2BodyThe 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
jb2JointThe 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
callbackb2RayCastCallbackThe callback.
point1b2Vec2The ray's start.
point2b2Vec2The 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
flagboolTrue 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
timeStepdoubleThe time step in seconds.
velocityIterationsintThe velocity iterations (Gymnasium's envs use
6 * 30).positionIterationsintThe 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.