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
optionsLunarLanderEnvOptionsThe options.
Exceptions
- ArgumentNullException
Thrown when
optionsis 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
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.continuousboolGymnasium's
continuous: two throttles (LunarLanderContinuous-v3) instead of four discrete actions.gravitydoubleGymnasium's
gravity, in (-12, 0) m/s².enableWindboolGymnasium's
enable_wind: a non-periodic sideways force and torque while no leg touches the ground.windPowerdoubleGymnasium's
wind_power: the wind force's magnitude (0 to 20 recommended).turbulencePowerdoubleGymnasium's
turbulence_power: the wind torque's magnitude (0 to 2 recommended).viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
renderModestringGymnasium's
render_mode: null,"human"or"rgb_array"; not validated, as in Gymnasium (makechecks it). Any mode but null also makes the engines emit particles.continuousboolGymnasium's
continuous: two throttles (LunarLanderContinuous-v3) instead of four discrete actions.gravitydoubleGymnasium's
gravity, in (-12, 0) m/s².enableWindboolGymnasium's
enable_wind: a non-periodic sideways force and torque while no leg touches the ground.windPowerdoubleGymnasium's
wind_power: the wind force's magnitude (0 to 20 recommended).turbulencePowerdoubleGymnasium's
turbulence_power: the wind torque's magnitude (0 to 2 recommended).viewerFactoryEnvViewerFactoryGym.NET's
viewer_factory(DR-20) for human mode; null usesGymnasium.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
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
InitialRandom
Gymnasium's INITIAL_RANDOM: each component of the reset's push is uniform in ±1000 N.
public const double InitialRandom = 1000
Field Value
LegAway
Gymnasium's LEG_AWAY: the legs' horizontal offset from the hull's centre, in pixels.
public const int LegAway = 20
Field Value
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
LegH
Gymnasium's LEG_H: a leg's half-height, in pixels.
public const int LegH = 8
Field Value
LegSpringTorque
Gymnasium's LEG_SPRING_TORQUE: the legs' motor torque, holding them against their limits.
public const int LegSpringTorque = 40
Field Value
LegW
Gymnasium's LEG_W: a leg's half-width, in pixels.
public const int LegW = 2
Field Value
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
MainEnginePower
Gymnasium's MAIN_ENGINE_POWER: the main engine's impulse factor.
public const double MainEnginePower = 13
Field Value
MainEngineYLocation
Gymnasium's MAIN_ENGINE_Y_LOCATION: the main engine below the hull's centre, in pixels.
public const int MainEngineYLocation = 4
Field Value
SCALE
[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
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
Scale
Gymnasium's SCALE: pixels per metre; also divides every geometry constant below, which are in pixels.
public const double Scale = 30
Field Value
SideEngineAway
Gymnasium's SIDE_ENGINE_AWAY: the side engines' horizontal offset, in pixels.
public const int SideEngineAway = 12
Field Value
SideEngineHeight
Gymnasium's SIDE_ENGINE_HEIGHT: the side engines' height above the hull's centre, in pixels.
public const int SideEngineHeight = 14
Field Value
SideEnginePower
Gymnasium's SIDE_ENGINE_POWER: the side engines' impulse factor.
public const double SideEnginePower = 0.6
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
Continuous
Gymnasium's continuous, fixed at construction: which action space and which action handling.
public bool Continuous { get; }
Property Value
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
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
EnableWind
Gymnasium's enable_wind: whether resets draw wind indices and steps apply wind; read at both.
public bool EnableWind { get; set; }
Property Value
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
Gravity
Gymnasium's gravity: the world's downward acceleration, read again by every reset's new world.
public double Gravity { get; set; }
Property Value
HelipadX1
Gymnasium's helipad_x1: the pad's left flag, in metres.
public double HelipadX1 { get; }
Property Value
HelipadX2
Gymnasium's helipad_x2: the pad's right flag, in metres.
public double HelipadX2 { get; }
Property Value
HelipadY
Gymnasium's helipad_y: the pad's height, in metres (H / 4).
public double HelipadY { get; }
Property Value
IsOpen
[PyName("isopen")]
public bool IsOpen { get; set; }
Property Value
Lander
Gymnasium's lander: the hull, null before the first reset; stepping requires it.
public b2Body? Lander { get; }
Property Value
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
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
Legs
Gymnasium's legs: the left and right leg bodies, empty before the first reset.
public IReadOnlyList<b2Body> Legs { get; }
Property Value
Moon
Gymnasium's moon: the static terrain body, null before the first reset.
public b2Body? Moon { get; }
Property Value
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
Particles
Gymnasium's particles: the exhaust particle bodies, oldest first; a new list on each read.
public IReadOnlyList<b2Body> Particles { get; }
Property Value
PrevReward
Gymnasium's prev_reward: always null (Python sets it to None and never reads it).
public double? PrevReward { get; }
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 LunarLander (DR-32).
protected override string PythonClassName { get; }
Property Value
Screen
Gymnasium's screen: the human window's surface, created by the first human render; null otherwise.
public Surface? Screen { get; }
Property Value
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
TorqueIdx
Gymnasium's torque_idx: the turbulence function's position, advanced by every windy step.
public long TorqueIdx { get; set; }
Property Value
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
WindIdx
Gymnasium's wind_idx: the wind function's position, advanced by every windy step.
public long WindIdx { get; set; }
Property Value
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
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
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/lunar_lander.py.
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
actionobjectThe 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).containsrejects.
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
envIEnvThe env (Gymnasium's demo makes
LunarLander-v3withrender_mode="rgb_array").seedBigInteger?The reset seed, or null.
renderboolWhether 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
envis 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
envIEnvThe env, wrapped or not: its unwrapped env's
continuousattribute picks the action form.sNDArrayThe 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
envorsis null.- AttributeError
Thrown when the unwrapped env has no
continuousattribute.
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.humanand 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
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 no-op step's float32 observation and an empty info.
Remarks
Reference: gymnasium/envs/box2d/lunar_lander.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: 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
actionNDArrayDiscrete: 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=Falseand{}.
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'sAssertionErrorgives 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).