Table of Contents

Class BipedalWalkerEnv

Namespace
Gym.Environments.Envs.Box2D
Assembly
Gym.Environments.dll

BipedalWalker-v3 and BipedalWalkerHardcore-v3 in one class, as in Gymnasium: a four-joint walker (a hull, two legs of two segments each) that must cross 200 terrain steps to the right. Actions are the four motors' commands in Box(-1, 1, (4,), float32) (hip, knee, hip, knee): the sign picks the motor's direction at full speed, the magnitude its torque. The observation is 24 float32 values: the hull's angle and velocities, each joint's angle and speed, each lower leg's ground contact, and ten lidar distances. Step for step and frame for frame what Gymnasium's BipedalWalker computes on Box2D 2.3, errors included.

[PyName("BipedalWalker")]
public class BipedalWalkerEnv : Env<NDArray, NDArray>, IEnv, IDisposable, IDynamicAttributes
Inheritance
BipedalWalkerEnv
Implements
Inherited Members
Extension Methods

Remarks

The physics runs on b2World, Gym.NET's managed Box2D 2.3.0 (D5), through the same pybox2d-shaped calls Gymnasium makes in the same order. Unlike LunarLander, the env keeps one world for its whole life, as Gymnasium does: each reset destroys the last episode's bodies in Gymnasium's order and creates the new ones, so the broad phase reuses its freed nodes exactly as pybox2d's does, which decides the order contacts are created and solved.

Footgun, Gymnasium's own: reset(seed) does not alone decide an episode. The freed tree nodes order the new contacts, and with them the contact listener's begin and end events, which set the lower legs' ground contact (and, through the solver's order, the bodies' last bits). An env that ran other episodes first can drift from a fresh one after the same reset: Gymnasium's BipedalWalker-v3, used once by check_environments_match and then compared with a fresh one, differs at step 96 of the seed-0 loop. Gym.NET matches Gymnasium step for step when both envs have the same past; to reproduce an episode exactly, start from a new env.

The terrain is grass with gentle random slopes; the hardcore variant adds stumps, stairs and pits, each drawing its sizes from the generator. The reward is the hull's progress (130 per metre over Scale) minus 5 per radian of hull tilt, less 0.028 per unit of torque spent; -100 and the end when the hull touches the ground or the walker leaves the left edge; the episode also ends past the far end's grass. The reward's precision is the action's, as NumPy 2 computes it (NEP 50): float32 actions (the action space's samples) give a float32 reward, float64 actions (the heuristic's) a float64 one; Gym.NET returns either as the double it equals.

Gymnasium's quirks are kept: reset runs one step with the int64 action [0, 0, 0, 0] (no torque at all) and returns its observation; the lidar ignores the walker's own fixtures by category and keeps the closest hit; human mode blits the scrolling frame at the truncated scroll offset onto a window it never clears, so while the walker stands left of its start the window's left columns keep the previous frames' pixels, as pygame's do.

Python's attributes are properties under their names (terrain_x is TerrainX); the ones Gymnasium hangs on Box2D bodies (color1, color2, the lower legs' ground_contact) live beside them (TerrainColors, LegGroundContact). The class prints as Gymnasium's BipedalWalker (DR-32); its contact listener is a private nested ContactDetector (DR-28) and its lidar callbacks a private nested class, as Python's is local to reset.

Not thread-safe; each env owns its world, so envs on different threads do not interfere. Reference: gymnasium/envs/box2d/bipedal_walker.py.

Its info is always {}, as Gymnasium's, so it has no typed info record (DR-95).

Constructors

BipedalWalkerEnv(BipedalWalkerEnvOptions)

Builds the instance from its options record: the properties set, the constructor's defaults for the rest.

public BipedalWalkerEnv(BipedalWalkerEnvOptions options)

Parameters

options BipedalWalkerEnvOptions

The options.

Exceptions

ArgumentNullException

Thrown when options is null.

BipedalWalkerEnv(RenderMode, bool, EnvViewerFactory?)

Builds the env with the render mode given as the RenderMode enum (DR-84, DR-93), as BipedalWalkerEnv(string?, bool, EnvViewerFactory?) builds it from the mode's string: new BipedalWalkerEnv(RenderMode.RgbArray) builds what new BipedalWalkerEnv(renderMode: "rgb_array") builds, the member reaching the env as Gymnasium's string (Name(RenderMode)), which its RenderMode property then holds.

public BipedalWalkerEnv(RenderMode renderMode, bool hardcore = false, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode RenderMode

The render mode, which the env must list in its metadata["render_modes"] as for the string; it behaves exactly as its Gymnasium string does in the other constructor.

hardcore bool

Gymnasium's hardcore: stumps, stairs and pits in the terrain (BipedalWalkerHardcore-v3); read by every reset.

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode; null uses Gymnasium.HumanViewerFactory.

Remarks

The mode is required and comes first, so new BipedalWalkerEnv() keeps meaning the other constructor, without a mode; leave the mode out there for no rendering. Every other parameter means what it means there.

Exceptions

ArgumentOutOfRangeException

Thrown for a value RenderMode does not declare (a cast integer such as (RenderMode)99).

BipedalWalkerEnv(string?, bool, EnvViewerFactory?)

Creates the env, in either mode.

public BipedalWalkerEnv(string? renderMode = null, bool hardcore = false, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode string

Gymnasium's render_mode: null, "human" or "rgb_array"; not validated, as in Gymnasium (make checks it).

hardcore bool

Gymnasium's hardcore: stumps, stairs and pits in the terrain (BipedalWalkerHardcore-v3); read by every reset.

viewerFactory EnvViewerFactory

Gym.NET's viewer_factory (DR-20) for human mode; null uses Gymnasium.HumanViewerFactory.

Fields

Fps

Gymnasium's FPS: steps per simulated second (the world steps 1/50 s) and the human frame rate.

public const int Fps = 50

Field Value

int

Friction

Gymnasium's FRICTION: the terrain's friction.

public const double Friction = 2.5

Field Value

double

InitialRandom

Gymnasium's INITIAL_RANDOM: the reset's sideways push on the hull is uniform in ±5 N.

public const int InitialRandom = 5

Field Value

int

LegDown

Gymnasium's LEG_DOWN: the hips' anchor below the hull's centre, in metres (-8 px).

public const double LegDown = -0.26666666666666666

Field Value

double

LegH

Gymnasium's LEG_H: each leg segment's length in metres (34 px).

public const double LegH = 1.1333333333333333

Field Value

double

LegW

Gymnasium's LEG_W: an upper leg's width in metres (8 px); the lower legs are 0.8 of it.

public const double LegW = 0.26666666666666666

Field Value

double

LidarRange

Gymnasium's LIDAR_RANGE: each lidar ray's length in metres (160 px).

public const double LidarRange = 5.333333333333333

Field Value

double

MotorsTorque

Gymnasium's MOTORS_TORQUE: each motor's torque at a full command, and the energy cost's factor.

public const int MotorsTorque = 80

Field Value

int

Scale

Gymnasium's SCALE: pixels per metre; also divides every geometry constant below that is given in pixels.

public const double Scale = 30

Field Value

double

SpeedHip

Gymnasium's SPEED_HIP: the hip motors' speed (rad/s) and the observation's hip speed scale.

public const int SpeedHip = 4

Field Value

int

SpeedKnee

Gymnasium's SPEED_KNEE: the knee motors' speed (rad/s) and the observation's knee speed scale.

public const int SpeedKnee = 6

Field Value

int

TerrainGrass

Gymnasium's TERRAIN_GRASS: grass stretches last from half of this to this many steps.

public const int TerrainGrass = 10

Field Value

int

TerrainHeight

Gymnasium's TERRAIN_HEIGHT: the grass's resting height in metres (a quarter of the frame).

public const double TerrainHeight = 3.3333333333333335

Field Value

double

TerrainLength

Gymnasium's TERRAIN_LENGTH: the terrain's number of steps.

public const int TerrainLength = 200

Field Value

int

TerrainStartpad

Gymnasium's TERRAIN_STARTPAD: the flat steps the walker starts on.

public const int TerrainStartpad = 20

Field Value

int

TerrainStep

Gymnasium's TERRAIN_STEP: one terrain step's width in metres (14 px).

public const double TerrainStep = 0.4666666666666667

Field Value

double

ViewportH

Gymnasium's VIEWPORT_H: the frame's height in pixels (13.3 m).

public const int ViewportH = 400

Field Value

int

ViewportW

Gymnasium's VIEWPORT_W: the frame's width in pixels (20 m).

public const int ViewportW = 600

Field Value

int

Properties

ClassMetadata

Gymnasium's class attribute metadata: {"render_modes": ["human", "rgb_array"], "render_fps": 50}. Every env starts with a copy as its instance metadata.

public static Metadata ClassMetadata { get; }

Property Value

Metadata

Remarks

A new dict on every read, so editing one env's metadata never reaches another (Python's is one shared dict).

Clock

Gymnasium's clock: paces human rendering, created by the first render.

public Clock? Clock { get; }

Property Value

Clock

CloudPoly

Gymnasium's cloud_poly: the ten clouds' pentagons in metres with their leftmost and rightmost x; empty before the first reset.

public IReadOnlyList<(IReadOnlyList<(double X, double Y)> Poly, double X1, double X2)> CloudPoly { get; }

Property Value

IReadOnlyList<(IReadOnlyList<(double X, double Y)> Poly, double X1, double X2)>

Drawlist

Gymnasium's drawlist: the terrain, the four leg segments, then the hull; empty before the first reset.

public IReadOnlyList<b2Body> Drawlist { get; }

Property Value

IReadOnlyList<b2Body>

FdEdge

Gymnasium's fd_edge: the terrain segments' fixture definition (friction 2.5, category 1), holding the last segment's vertices.

public b2FixtureDef FdEdge { get; }

Property Value

b2FixtureDef

FdPolygon

Gymnasium's fd_polygon: the obstacles' fixture definition (friction 2.5), whose polygon each obstacle overwrites before its body is made; it holds the last obstacle's vertices.

public b2FixtureDef FdPolygon { get; }

Property Value

b2FixtureDef

GameOver

Gymnasium's game_over: set by the contact listener when the hull touches the ground; ends the episode at the step's check.

public bool GameOver { get; set; }

Property Value

bool

Hardcore

Gymnasium's hardcore: whether the next reset's terrain has stumps, stairs and pits.

public bool Hardcore { get; set; }

Property Value

bool

Hull

Gymnasium's hull: the walker's body, null before the first reset; stepping requires it.

public b2Body? Hull { get; }

Property Value

b2Body

HullPoly

Gymnasium's HULL_POLY: the hull's vertices in pixels.

public static IReadOnlyList<(int X, int Y)> HullPoly { get; }

Property Value

IReadOnlyList<(int X, int Y)>

IsOpen

Gymnasium's isopen: true until Close() shuts a human window down.

[PyName("isopen")]
public bool IsOpen { get; set; }

Property Value

bool

Joints

Gymnasium's joints: the left hip, the left knee, the right hip, the right knee, as the actions drive them.

public IReadOnlyList<b2RevoluteJoint> Joints { get; }

Property Value

IReadOnlyList<b2RevoluteJoint>

LegGroundContact

Gymnasium's legs[i].ground_contact, index for index with Legs: whether each lower segment touches the ground, as the contact listener last saw it, and null for the upper segments, which have no such attribute in Python.

public IReadOnlyList<bool?> LegGroundContact { get; }

Property Value

IReadOnlyList<bool?>

Legs

Gymnasium's legs: the left leg's upper and lower segments, then the right's; empty before the first reset.

public IReadOnlyList<b2Body> Legs { get; }

Property Value

IReadOnlyList<b2Body>

LidarRender

Gymnasium's lidar_render: which lidar ray the next frames draw (one per frame, sweeping out and back, then 80 frames without).

public int LidarRender { get; set; }

Property Value

int

PrevShaping

Gymnasium's prev_shaping: the last step's shaping term, null right after a reset began.

public double? PrevShaping { get; set; }

Property Value

double?

PythonClassName

The Python class this instance stands for: Gymnasium's BipedalWalker (DR-32).

protected override string PythonClassName { get; }

Property Value

string

Screen

Gymnasium's screen: the human window's surface, created by the first human render and never cleared; null otherwise.

public Surface? Screen { get; }

Property Value

Surface

Scroll

Gymnasium's scroll: the view's left edge in metres (the hull's x minus 4), which places the clouds, picks the drawn terrain and offsets the human blit.

public double Scroll { get; set; }

Property Value

double

Exceptions

AttributeError

Thrown before the first reset, as Python's attribute does not exist yet.

Surf

Gymnasium's surf: the last frame drawn, flipped, as wide as the scrolled world so far (600 + 30 * scroll pixels); null until the first render.

public Surface? Surf { get; }

Property Value

Surface

Terrain

Gymnasium's terrain: the static terrain bodies in Python's order, the segments' edges last to first, then the obstacles last to first (the list is built forward and reversed). Empty before the first reset.

public IReadOnlyList<b2Body> Terrain { get; }

Property Value

IReadOnlyList<b2Body>

TerrainColors

Gymnasium's terrain[i].color1 and color2, index for index with Terrain: green segments (alternating shades), white obstacles outlined grey.

public IReadOnlyList<(Color Color1, Color Color2)> TerrainColors { get; }

Property Value

IReadOnlyList<(Color Color1, Color Color2)>

TerrainPoly

Gymnasium's terrain_poly: for each of the 199 segments, the ground polygon down to y = 0 (as Python's float64 tuples) and its colour; empty before the first reset.

public IReadOnlyList<(IReadOnlyList<(double X, double Y)> Poly, Color Color)> TerrainPoly { get; }

Property Value

IReadOnlyList<(IReadOnlyList<(double X, double Y)> Poly, Color Color)>

TerrainX

Gymnasium's terrain_x: the 200 steps' x in metres; empty before the first reset.

public IReadOnlyList<double> TerrainX { get; }

Property Value

IReadOnlyList<double>

TerrainY

Gymnasium's terrain_y: the 200 steps' heights in metres; empty before the first reset.

public IReadOnlyList<double> TerrainY { get; }

Property Value

IReadOnlyList<double>

World

Gymnasium's world: the Box2D world (gravity (0, -10)), one for the env's whole life; resets destroy and recreate the bodies in it.

public b2World World { get; }

Property Value

b2World

Methods

Close()

Shuts the human window down once one was opened, and marks the env closed (IsOpen), as Gymnasium's does.

public override void Close()

Remarks

Render()

Draws Gymnasium's frame with the same primitives in the same order on a surface as wide as the scrolled world: the sky, the visible clouds and ground polygons, one lidar ray (sweeping one per frame), every terrain body, leg segment and the hull (filled, anti-aliased and outlined; segments as anti-aliased lines), and the start flag, in a y-up world flipped at the end.

public override RenderResult Render()

Returns

RenderResult

rgb_array: the (400, 600, 3) uint8 frame, the surface's right-most 600 columns, a new array the caller owns. human and any other mode: nothing.

Remarks

Each frame advances LidarRender, so rendering changes what the next frame shows, as in Gymnasium. Gymnasium's discarded pygame.transform.scale(self.surf, (SCALE, SCALE)) draws nothing and is left out. Reference: gymnasium/envs/box2d/bipedal_walker.py.

Exceptions

AssertionError

Thrown without a render mode when the env has no spec (assert self.spec is not None).

AttributeError

Thrown before the first reset ('BipedalWalker' object has no attribute 'scroll'), after the human window opened.

KeyError

Thrown in human mode when metadata["render_fps"] was removed.

DependencyNotInstalled

Thrown on the first human render when no viewer factory is set (DR-20).

Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)

Starts an episode, as Gymnasium's does in its order: reseeds the generator when a seed is given, destroys the last episode's bodies, installs a new contact listener, draws the terrain (grass slopes, and the hardcore obstacles' kinds and sizes) and the ten clouds, creates the hull with its random push and the legs on their motorized, limited joints, renders in human mode, then runs a step with the int64 action [0, 0, 0, 0] and returns its observation.

public override ResetResult<NDArray> Reset(BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)

Parameters

seed BigInteger?

The seed of a fresh Generator(PCG64(SeedSequence(seed))), or null to keep the generator.

options IReadOnlyDictionary<string, object>

Ignored, as in Gymnasium.

Returns

ResetResult<NDArray>

The zero-action step's float32 observation and an empty info.

Remarks

Exceptions

Error

Thrown for a negative seed, with Gymnasium's message.

DependencyNotInstalled

Thrown in human mode by the first render when no viewer factory is set (DR-20).

Step(NDArray)

One step, in Gymnasium's order: each joint's motor speed (the command's sign times the joint's rated speed) and maximum torque (its clipped magnitude times 80), one 1/50 s world step (180 velocity and 60 position iterations), the ten lidar ray casts from the hull, then the observation, the scroll, the shaped reward less the energy spent, and the termination checks. Renders in human mode.

public override StepResult<NDArray> Step(NDArray action)

Parameters

action NDArray

The four motor commands, normally a float32 array of Box(-1, 1, (4,), float32); any 1-d numeric array is read as NumPy indexes it (beyond ±1 the torque is clipped, NaN propagates into the physics). Elements past the fourth add to the energy cost only. Read, never kept.

Returns

StepResult<NDArray>

The float32 observation, the reward (a float32 value for float32 actions, float64 otherwise, -100 on a fall), whether the episode ended (a fall, the left edge, or past the far end), truncated=False and {}.

Remarks

The reward is returned as a double always: the float32, float64 or int value Gymnasium's step returns, widened exactly. Reference: gymnasium/envs/box2d/bipedal_walker.py.

Exceptions

AssertionError

Thrown before the first reset (Python's bare assert, with its empty message, which NumSharp's AssertionError gives since 0.81.0).

IndexError

Thrown for a 0-d action or one of fewer than four elements, with NumPy's message; the joints before the missing element have their new motor settings by then, as in Gymnasium.

TypeError

Thrown for an action of more than one dimension (float() of a row) or of booleans (np.sign has no boolean loop), with NumPy's messages, before anything changes.

NotSupportedException

Thrown for a float16 action, whose half-precision energy cost is not modelled.

DependencyNotInstalled

Thrown in human mode by the first render when no viewer factory is set (DR-20).