Table of Contents

Class Env<TObs, TAct>

Namespace
Gym.Envs
Assembly
Gym.dll

The base class of every environment: an MDP driven through Step(TAct) and Reset(BigInteger?, IReadOnlyDictionary<string, object?>?), with spaces, metadata, a render mode, a lazily created generator and the attribute protocol (GetWrapperAttr(string), ...).

public abstract class Env<TObs, TAct> : IEnv, IDisposable, IDynamicAttributes

Type Parameters

TObs

The observation type: NDArray for array spaces, Discrete included (its elements are 0-d int64 arrays, DR-08); a tuple type for a composite space (Blackjack's object?[], DR-13).

TAct

The action type, likewise: every built-in env takes NDArray actions.

Inheritance
Env<TObs, TAct>
Implements
Derived
Inherited Members
Extension Methods

Remarks

Implementing an env: set ActionSpace, ObservationSpace and, when it renders, Metadata and RenderMode in the constructor; begin Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) with SeedNpRandom(BigInteger?) (Gymnasium's super().reset(seed=seed)), and draw every random number from NpRandom. Skipping the seeding call breaks reproducibility, which every parity test relies on.

Python attributes map to properties (port plan ยง3.8), which Gymnasium's attribute functions reach by their Python names through PyAttributes: np_random_seed is NpRandomSeed, and non-public state carries PyNameAttribute (_np_random). Like a Python instance, an env also holds attributes created at run time (set_wrapper_attr(name, value, force=True), env.x = 1 through SetAttr(object, string, object?)).

A deviation that follows from C#: Metadata is per instance (Python's class attribute is shared by every instance of the class, so mutating one env's changed all of them). The spaces are typed by the env's element types, Space<T> of TAct and TObs (DR-07).

Reference: gymnasium/core.py.

Properties

ActionSpace

The space every action must belong to (action_space), typed by the action type (DR-07): a Discrete or Box for NDArray actions. The env sets it in its constructor and owns it: Dispose() disposes it, so a space must not be shared between envs, and the setter refuses one that another env not yet disposed owns (DR-40). Replacing it lets the old space go undisposed, as in Python, where whoever still holds it keeps using it.

public virtual Space<TAct> ActionSpace { get; set; }

Property Value

Space<TAct>

Exceptions

AttributeError

Thrown by the getter while unset, as reading Python's annotated-only attribute does ('GenericTestEnv' object has no attribute 'action_space').

InvalidOperationException

Thrown by the setter for a space another env not yet disposed owns; the message names the fix (a new space, or DeepCopy()).

ClassMetadata

The class-level metadata, Python's class attribute metadata that make reads before the env exists to decide on HumanRendering or RenderCollection: {"render_modes": []} here, as on gymnasium.Env. An env class that renders declares its own with new (public new static Metadata ClassMetadata => ...) and sets its instance Metadata from it.

public static Metadata ClassMetadata { get; }

Property Value

Metadata

Remarks

A new dict on every read: Python shares one dict between the class and its instances, so editing it there edits every env; here each reader gets its own.

Metadata

The metadata (metadata), with Python key spelling: {"render_modes": ["human", "rgb_array"], "render_fps": 50}. Defaults to {"render_modes": []}, as Env.metadata does.

public virtual Metadata Metadata { get; set; }

Property Value

Metadata

Exceptions

ArgumentNullException

Thrown when assigning null.

NpRandom

The env's generator (np_random). The first read creates one from OS entropy, as Gymnasium does, which is why an unseeded env still draws reproducibly within itself; a seeded Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) replaces it. Assigning a generator shares it deliberately and makes NpRandomSeed -1, because a generator's seed cannot be recovered.

public virtual Generator NpRandom { get; set; }

Property Value

Generator

NpRandomSeed

The seed of NpRandom (np_random_seed): the seed of the last seeded reset, the 128-bit entropy of an entropy-seeded generator (created by this read if none exists yet), or -1 after a generator was assigned. Read-only: Python raises AttributeError on assignment, and SetAttr(object, string, object?) does too.

public virtual BigInteger NpRandomSeed { get; }

Property Value

BigInteger

ObservationSpace

The space every observation belongs to (observation_space), typed by the observation type. The env sets it in its constructor and owns it, like ActionSpace, the same refusal included.

public virtual Space<TObs> ObservationSpace { get; set; }

Property Value

Space<TObs>

Exceptions

AttributeError

Thrown by the getter while unset.

InvalidOperationException

Thrown by the setter for a space another env not yet disposed owns.

PythonClassName

The class name Python prints for this instance in messages: the class's own name (PyTypeName(Type)) unless an env whose Python class depends on the instance says otherwise (the merged MountainCar's Continuous_MountainCarEnv, DR-32). PyAttributes names it in its AttributeErrors.

protected virtual string PythonClassName { get; }

Property Value

string

RawNpRandom

Python's _np_random: the generator as it is, null before first use, without creating one. Gymnasium's tests read it to check laziness; a wrapper raises AttributeError instead.

[PyName("_np_random")]
protected virtual Generator? RawNpRandom { get; set; }

Property Value

Generator

RawNpRandomSeed

Python's _np_random_seed: the recorded seed as it is, null before first use.

[PyName("_np_random_seed")]
protected virtual BigInteger? RawNpRandomSeed { get; set; }

Property Value

BigInteger?

RenderMode

The render mode given to the constructor (render_mode), null (the default) when the env should not render. Fixed for the env's life: rendering another way means building another env.

public virtual string? RenderMode { get; protected set; }

Property Value

string

Spec

The spec make attached (spec), or null (the default) for an env built with its constructor.

public virtual EnvSpec? Spec { get; set; }

Property Value

EnvSpec

Unwrapped

The innermost env (unwrapped): the env itself; wrappers override it to walk down their stack.

public virtual IEnv Unwrapped { get; }

Property Value

IEnv

Methods

Close()

Releases what the env holds (close()): windows, native handles, connections. Calling it on a closed env does nothing more. The base holds nothing.

public virtual void Close()

CloseEnvironment()

0.2's name for Close(), kept so 0.2's teardown line compiles until 2.0 (DR-58): it calls Close(), the env's own override included.

[Obsolete("Close() is Gymnasium's name (or Dispose(), through using); CloseEnvironment is 0.2's. Removed in 2.0 with Gym.Legacy.")]
public void CloseEnvironment()

ConvertAction(object?)

Converts an action given to the untyped Step(object?) to TAct: an instance of it as is; for an integer or enum action type, any .NET integer, bool, enum member or 0-d integer array (what Discrete.Sample() returns); for a floating-point action type, any number or 0-d array; for an NDArray action type, what np.asarray makes of it: a .NET integer (or bool, Python's int subclass) a 0-d int64 array, a double or float a 0-d float64 or float32 array, a .NET array an array of its element type.

protected virtual TAct ConvertAction(object? action)

Parameters

action object

The action as given.

Returns

TAct

The typed action.

Remarks

Python has no such step: an env receives whatever it is given and validates it itself. Envs whose Python source asserts on the action override this to assert first, so an unconvertible action fails with the source's message (CartPole: 'x' (<class 'str'>) invalid) rather than this one.

Exceptions

TypeError

Thrown when the action cannot denote a TAct.

OverflowException

Thrown when an integer does not fit an integer action type.

Dispose()

Calls Close(), so using plays the role of Python's with statement (exit), then releases the spaces this env owns (D19). Idempotent in effect: a second call closes again, which every env's Close() tolerates, and finds the spaces already released.

public void Dispose()

Dispose(bool)

What Dispose() does: Close(), then the env's own action and observation spaces. A wrapper overrides it to release its own spaces and the env it wraps.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true from Dispose(); envs have no finalizers.

GetKeysToAction()

The keyboard mapping play uses when the caller gives none (get_keys_to_action()): key combinations to the actions they trigger, MountainCar's {(): 1, (276,): 0, (275,): 2, (275, 276): 1}. Absent until an env overrides it (DR-45): this base raises Python's AttributeError, as calling a method the class lacks does, and PyAttributes reports the attribute only on an env that overrides it.

[PyName("get_keys_to_action")]
public virtual IReadOnlyDictionary<KeyCombination, TAct> GetKeysToAction()

Returns

IReadOnlyDictionary<KeyCombination, TAct>

A new mapping the caller owns, its actions included: an override builds fresh actions on every call.

Remarks

Wrappers inherit this absent base: Gymnasium 1.x's wrappers forward no attributes, and play asks the layers beneath through has_wrapper_attr. An override whose presence depends on the instance also overrides HasPythonAttribute(string), so hasattr answers as Python's would for that state.

Reference: gymnasium/utils/play.py.

Exceptions

AttributeError

Thrown by this base ('CartPoleEnv' object has no attribute 'get_keys_to_action'), and by an override in a state that has no mapping (MountainCar's continuous mode).

GetWrapperAttr(string)

The Python attribute name of this env, as Python's getattr(self, name) reads it.

public virtual object? GetWrapperAttr(string name)

Parameters

name string

The attribute, in Python spelling.

Returns

object

The value, boxed.

Remarks

Reference: gymnasium/core.py.

Exceptions

ArgumentNullException

Thrown when name is null.

AttributeError

Thrown when the env has no such attribute ('CartPoleEnv' object has no attribute 'x').

HasPythonAttribute(string)

Whether this instance has the Python attribute name, for attributes whose presence varies by instance (DR-45): PyAttributes asks it before reporting a PyNameAttribute method that the env overrides. The default leaves the answer to that override check.

protected virtual bool HasPythonAttribute(string name)

Parameters

name string

The attribute, in Python spelling (get_keys_to_action).

Returns

bool

false to hide the attribute on this instance; true here.

HasWrapperAttr(string)

Whether this env has the Python attribute name (Python's hasattr: declared members by Python name, then run-time attributes).

public virtual bool HasWrapperAttr(string name)

Parameters

name string

The attribute, in Python spelling.

Returns

bool

true when reading it would succeed.

Remarks

Reference: gymnasium/core.py.

Exceptions

ArgumentNullException

Thrown when name is null.

Render()

Renders as RenderMode says (render()): rgb_array returns a frame, ansi text, human draws to a window during Step(TAct) and returns None. The base raises NotImplementedError, as Env.render does.

public virtual RenderResult Render()

Returns

RenderResult

The rendering.

Exceptions

NotImplementedError

Thrown unless the env overrides it.

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

Starts an episode (reset(seed=seed, options=options)). Implementations call SeedNpRandom(BigInteger?) first, then draw the initial state from NpRandom.

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

Parameters

seed BigInteger?

Reseeds NpRandom with Gymnasium's Generator(PCG64(SeedSequence(seed))) when given (any non-negative integer); null keeps the current generator. Seed once, right after construction, then reset without a seed.

options IReadOnlyDictionary<string, object>

Env-specific reset options, or null.

Returns

ResetResult<TObs>

The first observation and the info.

Remarks

As with Step(TAct), the observation and info must be new objects, not a buffer a previous call returned and this one mutated in place. Reference: gymnasium/core.py.

Exceptions

Error

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

SeedNpRandom(BigInteger?)

The first line of every Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) (Gymnasium's super().reset(seed=seed)): reseeds NpRandom and records NpRandomSeed when a seed is given; without one, the generator, and with it the random stream, carries on.

protected void SeedNpRandom(BigInteger? seed)

Parameters

seed BigInteger?

The seed passed to Reset(BigInteger?, IReadOnlyDictionary<string, object?>?), or null.

Remarks

Reference: gymnasium/core.py.

Exceptions

Error

Thrown for a negative seed: Seed must be greater or equal to zero, actual value: -1.

SetWrapperAttr(string, object?, bool)

Assigns the Python attribute name when force is set or the env has it, creating a run-time attribute for a new name.

public virtual bool SetWrapperAttr(string name, object? value, bool force = true)

Parameters

name string

The attribute, in Python spelling.

value object

The value; numbers convert to a numeric attribute's type.

force bool

Assign even when the env does not have the attribute yet.

Returns

bool

true when the attribute was assigned.

Remarks

Reference: gymnasium/core.py.

Exceptions

ArgumentNullException

Thrown when name is null.

AttributeError

Thrown for a read-only attribute (property 'np_random_seed' of 'CartPoleEnv' object has no setter).

TypeError

Thrown when the value does not fit the attribute's type.

Step(TAct)

Runs one timestep of the dynamics with action (step(action)). Once the result is terminated or truncated, call Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) before stepping again.

public abstract StepResult<TObs> Step(TAct action)

Parameters

action TAct

An element of ActionSpace.

Returns

StepResult<TObs>

The observation, reward, terminated, truncated and info.

Remarks

Every call must return a new observation and a new info, never a buffer an earlier call returned and this one mutated: callers commonly keep every timestep (a replay or rollout buffer), and a reused buffer silently rewrites the history they kept. Gymnasium's check_env and PassiveEnvChecker enforce this since v1.4.0. Reference: gymnasium/core.py.

Exceptions

AssertionError

Thrown by Gym's envs for an invalid action or a step before the first reset, where Gymnasium's envs fail an assert.

StepAsync(TAct, CancellationToken)

Steps asynchronously: completes with what Step(TAct) returns. The default runs Step(TAct) on the calling thread and completes synchronously, with no thread-pool hop and no allocation; an env whose dynamics are genuinely asynchronous (a remote simulator, a batched GPU step) overrides it.

public virtual ValueTask<StepResult<TObs>> StepAsync(TAct action, CancellationToken cancellationToken = default)

Parameters

action TAct

An element of ActionSpace.

cancellationToken CancellationToken

Checked before the step starts; a step that has started runs to completion.

Returns

ValueTask<StepResult<TObs>>

A value task that completes with the transition, is faulted with what Step(TAct) threw, or is canceled when cancellationToken was already canceled.

Remarks

Exceptions surface when the task is awaited, never from this call, as for any asynchronous method. Wrappers inherit this default, so awaiting a wrapper runs the wrapper's own Step(TAct) (and, through it, the env beneath, synchronously); a wrapper that must keep an asynchronous env asynchronous overrides StepAsync as well. Not thread-safe, like Step(TAct): await each call before issuing the next on the same env.

ToString()

The env's description: <CartPoleEnv instance> without a spec, <CartPoleEnv<CartPole-v1>> with one; wrapper descriptions embed it.

public override string ToString()

Returns

string

The text, the same as Gymnasium prints for the env.

Remarks

Reference: gymnasium/core.py.