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
optionsBipedalWalkerEnvOptionsThe options.
Exceptions
- ArgumentNullException
Thrown when
optionsis 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
renderModeRenderModeThe 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.hardcoreboolGymnasium's
hardcore: stumps, stairs and pits in the terrain (BipedalWalkerHardcore-v3); read by every reset.viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
renderModestringGymnasium's
render_mode: null,"human"or"rgb_array"; not validated, as in Gymnasium (makechecks it).hardcoreboolGymnasium's
hardcore: stumps, stairs and pits in the terrain (BipedalWalkerHardcore-v3); read by every reset.viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
Friction
Gymnasium's FRICTION: the terrain's friction.
public const double Friction = 2.5
Field Value
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
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
LegH
Gymnasium's LEG_H: each leg segment's length in metres (34 px).
public const double LegH = 1.1333333333333333
Field Value
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
LidarRange
Gymnasium's LIDAR_RANGE: each lidar ray's length in metres (160 px).
public const double LidarRange = 5.333333333333333
Field Value
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
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
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
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
TerrainGrass
Gymnasium's TERRAIN_GRASS: grass stretches last from half of this to this many steps.
public const int TerrainGrass = 10
Field Value
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
TerrainLength
Gymnasium's TERRAIN_LENGTH: the terrain's number of steps.
public const int TerrainLength = 200
Field Value
TerrainStartpad
Gymnasium's TERRAIN_STARTPAD: the flat steps the walker starts on.
public const int TerrainStartpad = 20
Field Value
TerrainStep
Gymnasium's TERRAIN_STEP: one terrain step's width in metres (14 px).
public const double TerrainStep = 0.4666666666666667
Field Value
ViewportH
Gymnasium's VIEWPORT_H: the frame's height in pixels (13.3 m).
public const int ViewportH = 400
Field Value
ViewportW
Gymnasium's VIEWPORT_W: the frame's width in pixels (20 m).
public const int ViewportW = 600
Field Value
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
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
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
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
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
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
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
Hardcore
Gymnasium's hardcore: whether the next reset's terrain has stumps, stairs and pits.
public bool Hardcore { get; set; }
Property Value
Hull
Gymnasium's hull: the walker's body, null before the first reset; stepping requires it.
public b2Body? Hull { get; }
Property Value
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
[PyName("isopen")]
public bool IsOpen { get; set; }
Property Value
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
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
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
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
PrevShaping
Gymnasium's prev_shaping: the last step's shaping term, null right after a reset began.
public double? PrevShaping { get; set; }
Property Value
PythonClassName
The Python class this instance stands for: Gymnasium's BipedalWalker (DR-32).
protected override string PythonClassName { get; }
Property Value
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
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
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
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
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
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
TerrainY
Gymnasium's terrain_y: the 200 steps' heights in metres; empty before the first reset.
public IReadOnlyList<double> TerrainY { get; }
Property Value
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
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
Reference: gymnasium/envs/box2d/bipedal_walker.py.
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.humanand 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
seedBigInteger?The seed of a fresh
Generator(PCG64(SeedSequence(seed))), or null to keep the generator.optionsIReadOnlyDictionary<string, object>Ignored, as in Gymnasium.
Returns
- ResetResult<NDArray>
The zero-action step's float32 observation and an empty info.
Remarks
Reference: gymnasium/envs/box2d/bipedal_walker.py.
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
actionNDArrayThe 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=Falseand{}.
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'sAssertionErrorgives 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.signhas 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).