Table of Contents

Class LunarLanderEnv

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

LunarLander-v3 and LunarLanderContinuous-v3 in one class, as in Gymnasium: a lander dropped from the top of the screen with a random push, which must touch down on the pad between the flags. Discrete actions fire nothing, the left engine, the main engine or the right engine (0 to 3); continuous actions throttle the main engine and the side engines (Box(-1, 1, (2,), float32)). Step for step and frame for frame what Gymnasium's LunarLander computes on Box2D 2.3, errors included.

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

Remarks

The physics runs on b2World, Gym.NET's managed Box2D 2.3.0 (D5), which matches pybox2d 2.3.10 bit for bit, through the same pybox2d-shaped calls Gymnasium makes in the same order: a new world per reset, the terrain's edges, the hull with its random push, the legs on motorized, limited revolute joints, and every step's engine impulses at dispersed points. The observation is computed in float64 from the float32 bodies, then stored as float32; the reward is the change of a shaping term minus the fuel spent, -100 when the hull touches the ground or the lander leaves the screen sideways, +100 when the lander comes to rest (falls asleep).

Gymnasium's quirks are kept: reset runs one no-op Step(NDArray) (drawing two dispersion values and stepping the world) and returns its observation; the side engines push from a point 17 rather than SideEngineHeight pixels to the side, so their torque depends on the lander's angle; particles are bodies in the world, created only when a render mode is set, which never touch the lander; the flags are redrawn once per drawn fixture, which deepens their anti-aliased edges as particles accumulate.

Python's attributes are properties under their names (helipad_y is HelipadY); the ones Gymnasium hangs on Box2D bodies (legs[i].ground_contact, particles[i].ttl, the colours) live beside them here (LegGroundContact, ParticleTtl). The class prints as Gymnasium's LunarLander (DR-32), and its contact listener is a private nested ContactDetector (DR-28).

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

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

Constructors

LunarLanderEnv(LunarLanderEnvOptions)

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

public LunarLanderEnv(LunarLanderEnvOptions options)

Parameters

options LunarLanderEnvOptions

The options.

Exceptions

ArgumentNullException

Thrown when options is null.

LunarLanderEnv(RenderMode, bool, double, bool, double, double, EnvViewerFactory?)

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

public LunarLanderEnv(RenderMode renderMode, bool continuous = false, double gravity = -10, bool enableWind = false, double windPower = 15, double turbulencePower = 1.5, 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.

continuous bool

Gymnasium's continuous: two throttles (LunarLanderContinuous-v3) instead of four discrete actions.

gravity double

Gymnasium's gravity, in (-12, 0) m/s².

enableWind bool

Gymnasium's enable_wind: a non-periodic sideways force and torque while no leg touches the ground.

windPower double

Gymnasium's wind_power: the wind force's magnitude (0 to 20 recommended).

turbulencePower double

Gymnasium's turbulence_power: the wind torque's magnitude (0 to 2 recommended).

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 LunarLanderEnv() 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).

AssertionError

Thrown for a gravity outside (-12, 0), with Gymnasium's message.

LunarLanderEnv(string?, bool, double, bool, double, double, EnvViewerFactory?)

Creates the env, in either mode.

public LunarLanderEnv(string? renderMode = null, bool continuous = false, double gravity = -10, bool enableWind = false, double windPower = 15, double turbulencePower = 1.5, EnvViewerFactory? viewerFactory = null)

Parameters

renderMode string

Gymnasium's render_mode: null, "human" or "rgb_array"; not validated, as in Gymnasium (make checks it). Any mode but null also makes the engines emit particles.

continuous bool

Gymnasium's continuous: two throttles (LunarLanderContinuous-v3) instead of four discrete actions.

gravity double

Gymnasium's gravity, in (-12, 0) m/s².

enableWind bool

Gymnasium's enable_wind: a non-periodic sideways force and torque while no leg touches the ground.

windPower double

Gymnasium's wind_power: the wind force's magnitude (0 to 20 recommended).

turbulencePower double

Gymnasium's turbulence_power: the wind torque's magnitude (0 to 2 recommended).

viewerFactory EnvViewerFactory

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

Remarks

A wind or turbulence power outside the recommended range warns through Warn(string, WarningCategory, string, int), as Gymnasium does, and is kept. Footgun: the gravity in the message prints as a float (-13.0) where Python prints an int passed as such (-13), since the parameter is a double.

Exceptions

AssertionError

Thrown for a gravity outside (-12, 0), with Gymnasium's message.

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

INITIAL_RANDOM

0.2's name for InitialRandom, as 0.2's float constant, kept until 2.0 (DR-58).

[Obsolete("0.2's constant name: use LunarLanderEnv.InitialRandom (a double). Removed in 2.0 with Gym.Legacy.")]
public const float INITIAL_RANDOM = 1000

Field Value

float

InitialRandom

Gymnasium's INITIAL_RANDOM: each component of the reset's push is uniform in ±1000 N.

public const double InitialRandom = 1000

Field Value

double

LegAway

Gymnasium's LEG_AWAY: the legs' horizontal offset from the hull's centre, in pixels.

public const int LegAway = 20

Field Value

int

LegDown

Gymnasium's LEG_DOWN: the legs' joint anchor below the hull's centre, in pixels (also the observation's y offset).

public const int LegDown = 18

Field Value

int

LegH

Gymnasium's LEG_H: a leg's half-height, in pixels.

public const int LegH = 8

Field Value

int

LegSpringTorque

Gymnasium's LEG_SPRING_TORQUE: the legs' motor torque, holding them against their limits.

public const int LegSpringTorque = 40

Field Value

int

LegW

Gymnasium's LEG_W: a leg's half-width, in pixels.

public const int LegW = 2

Field Value

int

MAIN_ENGINE_POWER

0.2's name for MainEnginePower, as 0.2's float constant, kept until 2.0 (DR-58).

[Obsolete("0.2's constant name: use LunarLanderEnv.MainEnginePower (a double). Removed in 2.0 with Gym.Legacy.")]
public const float MAIN_ENGINE_POWER = 13

Field Value

float

MainEnginePower

Gymnasium's MAIN_ENGINE_POWER: the main engine's impulse factor.

public const double MainEnginePower = 13

Field Value

double

MainEngineYLocation

Gymnasium's MAIN_ENGINE_Y_LOCATION: the main engine below the hull's centre, in pixels.

public const int MainEngineYLocation = 4

Field Value

int

SCALE

0.2's name for Scale, as 0.2's float constant, kept until 2.0 (DR-58).

[Obsolete("0.2's constant name: use LunarLanderEnv.Scale (a double). Removed in 2.0 with Gym.Legacy.")]
public const float SCALE = 30

Field Value

float

SIDE_ENGINE_POWER

0.2's name for SideEnginePower, as 0.2's float constant (0.6f, which is not exactly the double 0.6 the env computes with), kept until 2.0 (DR-58).

[Obsolete("0.2's constant name: use LunarLanderEnv.SideEnginePower (a double). Removed in 2.0 with Gym.Legacy.")]
public const float SIDE_ENGINE_POWER = 0.6

Field Value

float

Scale

Gymnasium's SCALE: pixels per metre; also divides every geometry constant below, which are in pixels.

public const double Scale = 30

Field Value

double

SideEngineAway

Gymnasium's SIDE_ENGINE_AWAY: the side engines' horizontal offset, in pixels.

public const int SideEngineAway = 12

Field Value

int

SideEngineHeight

Gymnasium's SIDE_ENGINE_HEIGHT: the side engines' height above the hull's centre, in pixels.

public const int SideEngineHeight = 14

Field Value

int

SideEnginePower

Gymnasium's SIDE_ENGINE_POWER: the side engines' impulse factor.

public const double SideEnginePower = 0.6

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

Continuous

Gymnasium's continuous, fixed at construction: which action space and which action handling.

public bool Continuous { get; }

Property Value

bool

ContinuousMode

0.2's name for Continuous, kept so 0.2 code compiles until 2.0 (DR-58).

[Obsolete("0.2's property name: use LunarLanderEnv.Continuous. Removed in 2.0 with Gym.Legacy.")]
public bool ContinuousMode { get; }

Property Value

bool

Drawlist

Gymnasium's drawlist: the hull then the legs, drawn after the particles; empty before the first reset.

public IReadOnlyList<b2Body> Drawlist { get; }

Property Value

IReadOnlyList<b2Body>

EnableWind

Gymnasium's enable_wind: whether resets draw wind indices and steps apply wind; read at both.

public bool EnableWind { get; set; }

Property Value

bool

GameOver

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

public bool GameOver { get; set; }

Property Value

bool

Gravity

Gymnasium's gravity: the world's downward acceleration, read again by every reset's new world.

public double Gravity { get; set; }

Property Value

double

HelipadX1

Gymnasium's helipad_x1: the pad's left flag, in metres.

public double HelipadX1 { get; }

Property Value

double

HelipadX2

Gymnasium's helipad_x2: the pad's right flag, in metres.

public double HelipadX2 { get; }

Property Value

double

HelipadY

Gymnasium's helipad_y: the pad's height, in metres (H / 4).

public double HelipadY { get; }

Property Value

double

IsOpen

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

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

Property Value

bool

Lander

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

public b2Body? Lander { get; }

Property Value

b2Body

LanderPoly

Gymnasium's LANDER_POLY: the hull's vertices in pixels, counter-clockwise from the top left.

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

Property Value

IReadOnlyList<(int X, int Y)>

LegGroundContact

Gymnasium's legs[i].ground_contact: whether each leg touches the ground, as the contact listener last saw it.

public IReadOnlyList<bool> LegGroundContact { get; }

Property Value

IReadOnlyList<bool>

LegJoints

Gymnasium's legs[i].joint: each leg's revolute joint to the hull, or null before the first reset.

public IReadOnlyList<b2RevoluteJoint?> LegJoints { get; }

Property Value

IReadOnlyList<b2RevoluteJoint>

Legs

Gymnasium's legs: the left and right leg bodies, empty before the first reset.

public IReadOnlyList<b2Body> Legs { get; }

Property Value

IReadOnlyList<b2Body>

Moon

Gymnasium's moon: the static terrain body, null before the first reset.

public b2Body? Moon { get; }

Property Value

b2Body

ParticleTtl

Gymnasium's particles[i].ttl: each particle's remaining life, which every render shortens by 0.15.

public IReadOnlyList<double> ParticleTtl { get; }

Property Value

IReadOnlyList<double>

Particles

Gymnasium's particles: the exhaust particle bodies, oldest first; a new list on each read.

public IReadOnlyList<b2Body> Particles { get; }

Property Value

IReadOnlyList<b2Body>

PrevReward

Gymnasium's prev_reward: always null (Python sets it to None and never reads it).

public double? PrevReward { get; }

Property Value

double?

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 LunarLander (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; null otherwise.

public Surface? Screen { get; }

Property Value

Surface

SkyPolys

Gymnasium's sky_polys: the polygon above each terrain segment, in metres, as Python's float64 tuples.

public IReadOnlyList<IReadOnlyList<(double X, double Y)>> SkyPolys { get; }

Property Value

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

Exceptions

AttributeError

Thrown before the first reset, when the attribute does not exist yet.

Surf

Gymnasium's surf: the last frame drawn, flipped; null until the first render.

public Surface? Surf { get; }

Property Value

Surface

TorqueIdx

Gymnasium's torque_idx: the turbulence function's position, advanced by every windy step.

public long TorqueIdx { get; set; }

Property Value

long

Exceptions

AttributeError

Thrown until a reset with wind enabled has drawn it.

TurbulencePower

Gymnasium's turbulence_power: the wind torque's magnitude, read every windy step.

public double TurbulencePower { get; set; }

Property Value

double

WindIdx

Gymnasium's wind_idx: the wind function's position, advanced by every windy step.

public long WindIdx { get; set; }

Property Value

long

Exceptions

AttributeError

Thrown until a reset with wind enabled has drawn it, as Python's attribute does not exist before.

WindPower

Gymnasium's wind_power: the wind force's magnitude, read every windy step.

public double WindPower { get; set; }

Property Value

double

World

Gymnasium's world: the Box2D world, a new one per reset (Gymnasium's workaround for issue 728); before the first reset, the constructor's empty one.

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

ConvertAction(object?)

The untyped step's action conversion, with LunarLander's own assert first in discrete mode: an action outside Discrete(4) fails with Python's message for exactly the value given.

protected override NDArray ConvertAction(object? action)

Parameters

action object

The action as given to Step(object?).

Returns

NDArray

The action as an array: the one given, or a new one for a plain .NET value.

Exceptions

AssertionError

Thrown in discrete mode for anything Discrete(4).contains rejects.

DemoHeuristicLander(IEnv, BigInteger?, bool)

Gymnasium's demo_heuristic_lander(env, seed, render): plays one episode with Heuristic(IEnv, NDArray), printing the observation and the running reward every 20 steps and at the end, and returns the total reward.

public static double DemoHeuristicLander(IEnv env, BigInteger? seed = null, bool render = false)

Parameters

env IEnv

The env (Gymnasium's demo makes LunarLander-v3 with render_mode="rgb_array").

seed BigInteger?

The reset seed, or null.

render bool

Whether to render every step and close the env at the end.

Returns

double

The episode's total reward.

Remarks

Prints to Out in Python's format (observations: +0.01 -0.02 ..., step 20 total_reward -12.34). Reference: gymnasium/envs/box2d/lunar_lander.py.

Exceptions

ArgumentNullException

Thrown when env is null.

Heuristic(IEnv, NDArray)

Gymnasium's heuristic(env, s): the hand-written controller that lands the lander, from an observation. It steers toward an angle pointing at the pad and a hover height proportional to the horizontal offset, and after touchdown only slows the fall.

public static NDArray Heuristic(IEnv env, NDArray s)

Parameters

env IEnv

The env, wrapped or not: its unwrapped env's continuous attribute picks the action form.

s NDArray

The observation: 8 values (float32 as the env returns them; other dtypes are read as their values).

Returns

NDArray

Discrete: a 0-d int64 action, 0 to 3 (Python returns an int). Continuous: two throttles clipped to [-1, 1], a float32 array, or float64 after touchdown (where Python's array mixes a float32 with the int 0).

Remarks

The arithmetic follows NumPy's on a float32 observation (NEP 50): every product and difference with Python's floats stays float32, and the comparisons with 0.4 and 0.05 are float32 comparisons, so the action is the one Gymnasium's heuristic returns for the same observation. Reference: gymnasium/envs/box2d/lunar_lander.py.

Exceptions

ArgumentNullException

Thrown when env or s is null.

AttributeError

Thrown when the unwrapped env has no continuous attribute.

Render()

Draws Gymnasium's frame with the same primitives in the same order: white, the black sky polygons above the terrain, the particles (circles fading by life) and the hull and legs (filled, anti-aliased and outlined), each followed by the two flags, in a y-up world flipped at the end. Shortens every particle's life by 0.15 first and destroys the expired ones at the front, as Gymnasium's does, so rendering changes the world.

public override RenderResult Render()

Returns

RenderResult

rgb_array: the (400, 600, 3) uint8 frame, a new array the caller owns. human and any other mode: nothing.

Remarks

Gymnasium's discarded pygame.transform.scale(self.surf, (SCALE, SCALE)) draws nothing and is left out. Reference: gymnasium/envs/box2d/lunar_lander.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 ('LunarLander' object has no attribute 'sky_polys'), 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 old bodies, makes a new world with the contact listener, draws the terrain (12 heights), creates the moon, the hull and its random push (2 draws), the wind indices when wind is enabled (2 draws), and the legs, renders in human mode, then runs a no-op Step(NDArray) (2 more draws) 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 no-op 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: the wind and turbulence when enabled and no leg touches the ground, the action's check (discrete) or clipping (continuous), two dispersion draws, the main engine's impulse, the side engine's, one 1/50 s world step (180 velocity and 60 position iterations), then the observation, the shaped reward and the termination checks. Renders in human mode.

public override StepResult<NDArray> Step(NDArray action)

Parameters

action NDArray

Discrete: an element of Discrete(4) (a 0-d integer array; the untyped step also takes a .NET integer). Continuous: an array of two throttles, clipped to [-1, 1] as float64; the main engine fires above 0 (50% to 100%), the left or right engine beyond ±0.5. Read, never kept.

Returns

StepResult<NDArray>

The float32 observation (position, velocity, angle and angular velocity in Gymnasium's units, and each leg's contact), the reward, whether the episode ended (crash, out of the screen, or at rest), truncated=False and {}.

Remarks

The reward is a float64 here always, where Gymnasium's is an np.float64, and the int -100 or +100 on termination (equal values). Reference: gymnasium/envs/box2d/lunar_lander.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), and in discrete mode for an action outside the space, with Gymnasium's message (5 (<class 'int'>) invalid , trailing space included).

IndexError

Thrown in continuous mode for an action without a first or second element, with NumPy's message; the wind, the dispersion draws and (for a one-element action) the main engine have happened by then, as in Gymnasium.

NotSupportedException

Thrown in continuous mode for an action of more than one dimension (NumPy's truth-value error is not modelled).

DependencyNotInstalled

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