Table of Contents

Interface IEnv

Namespace
Gym.Envs
Assembly
Gym.dll

The env contract over object: what code that holds envs of any observation and action type (wrappers over unknown envs, the registry, vector envs, the legacy adapter) programs against. Every env is an Env<TObs, TAct>, which implements it; its typed members are the ones to call when the types are known.

public interface IEnv : IDisposable
Inherited Members
Extension Methods

Remarks

Members follow Gymnasium's Env one to one with the port plan's naming (ยง3.8): step is Step(object?), np_random_seed is NpRandomSeed, get_wrapper_attr is GetWrapperAttr(string). Dispose() calls Close(), as leaving a Python with block does.

Not thread-safe: step, reset and render an instance from one thread at a time.

Reference: gymnasium/core.py.

Properties

ActionSpace

The space every action must belong to.

Space ActionSpace { get; set; }

Property Value

Space

Exceptions

AttributeError

Thrown by the getter while the env has not set one, as reading the missing Python attribute does.

Metadata

The env's metadata, {"render_modes": [...], "render_fps": ...} with Python key spelling. A wrapper returns its env's unless it was assigned its own.

Metadata Metadata { get; set; }

Property Value

Metadata

NpRandom

The env's generator (np_random): created from OS entropy on first use, replaced by a seeded Reset(BigInteger?, IReadOnlyDictionary<string, object?>?); assigning one makes NpRandomSeed -1. A wrapper forwards to the innermost env.

Generator NpRandom { get; set; }

Property Value

Generator

NpRandomSeed

The seed NpRandom was built from (np_random_seed): the seed of the last seeded reset, the entropy of an unseeded generator (creating it first if needed), or -1 after a generator was assigned. Read-only, as in Gymnasium.

BigInteger NpRandomSeed { get; }

Property Value

BigInteger

ObservationSpace

The space every observation belongs to.

Space ObservationSpace { get; set; }

Property Value

Space

Exceptions

AttributeError

Thrown by the getter while the env has not set one.

RenderMode

The render mode fixed at construction ("human", "rgb_array", ...), or null when the env does not render.

string? RenderMode { get; }

Property Value

string

Spec

The spec make attached, or null for an env built with its constructor. A wrapper's is its env's, extended with the wrapper (and read-only: assigning it raises AttributeError).

EnvSpec? Spec { get; set; }

Property Value

EnvSpec

Unwrapped

The innermost env, beneath every wrapper (unwrapped); an env that is not a wrapper returns itself.

IEnv Unwrapped { get; }

Property Value

IEnv

Methods

Close()

Releases what the env holds, windows included (close()); closing twice does nothing more.

void Close()

CloseEnvironment()

0.2's name for Close(), kept so 0.2 code holding an IEnv compiles until 2.0 (DR-58). The default calls Close(); Env<TObs, TAct>'s public method of the same name replaces it.

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

GetWrapperAttr(string)

Python's get_wrapper_attr(name): the attribute from the outermost layer that has it.

object? GetWrapperAttr(string name)

Parameters

name string

The attribute, in Python spelling.

Returns

object

The value, boxed.

Exceptions

AttributeError

Thrown when no layer has it (wrapper TimeLimit has no attribute 'x').

HasWrapperAttr(string)

Python's has_wrapper_attr(name): whether this env, or for a wrapper any env beneath it, has the Python attribute name ("gravity", "_disable_render_order_enforcing").

bool HasWrapperAttr(string name)

Parameters

name string

The attribute, in Python spelling.

Returns

bool

true when some layer has it.

Render()

Renders as RenderMode says (render()).

RenderResult Render()

Returns

RenderResult

A frame, text, collected frames, or None (human mode, no render mode).

Exceptions

NotImplementedError

Thrown by an env that does not render.

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

Starts an episode (reset(seed=seed, options=options)).

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

Parameters

seed BigInteger?

Reseeds NpRandom first when given (any non-negative integer); null keeps the generator, so a stream seeded once runs on across episodes.

options IReadOnlyDictionary<string, object>

Env-specific options (for example "low"/"high" in classic_control), or null.

Returns

ResetResult<object>

The first observation, boxed, and the info.

Exceptions

Error

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

SetWrapperAttr(string, object?, bool)

Python's set_wrapper_attr(name, value, force=force): assigns the attribute on the outermost layer that has it; when none has it, force creates it on this layer.

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

Create the attribute here when no layer has it (Gymnasium's default, true).

Returns

bool

true when some layer was assigned.

Exceptions

AttributeError

Thrown when the attribute is read-only (np_random_seed).

TypeError

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

Step(object?)

Runs one timestep with an action of any type; the env converts it to its action type first (a typed env's Step(TAct) takes it directly).

StepResult<object?> Step(object? action)

Parameters

action object

An element of ActionSpace.

Returns

StepResult<object>

The transition, its observation boxed.

Exceptions

Exception

Whatever the env raises for the action: an AssertionError for an invalid one, a ResetNeeded from OrderEnforcing, ....

StepAsync(object?, CancellationToken)

Steps asynchronously with an action of any type (see StepAsync(TAct, CancellationToken)): by default the step runs on the calling thread and the task completes synchronously; an action that cannot be converted, like any error of the step, faults the task.

ValueTask<StepResult<object?>> StepAsync(object? action, CancellationToken cancellationToken = default)

Parameters

action object

An element of ActionSpace.

cancellationToken CancellationToken

Checked before the step starts.

Returns

ValueTask<StepResult<object>>

A value task that completes with the transition, its observation boxed.