Table of Contents

Class EnvSpec

Namespace
Gym.Envs.Registration
Assembly
Gym.dll

Everything make needs to build an env and the wrappers it adds (time limit, order enforcing, env checker), plus the wrappers applied since. An env built by make carries it as Spec; a wrapper's Spec is a copy extended with the wrapper, so editing one never changes another.

public sealed record EnvSpec : IEquatable<EnvSpec>
Inheritance
EnvSpec
Implements
Inherited Members
Extension Methods

Remarks

Like the dataclass, every field is settable, and Namespace, Name and Version are parsed from Id once, at construction (__post_init__): assigning Id later does not re-parse them, and neither does a with expression, as editing a deep-copied spec in Python does not.

Equality is the dataclass's, over every field in declaration order, Kwargs compared as Python dicts. An entry point given as a class equals the "Namespace:Class" string that names it, the form ToJson() writes, so a spec read back with FromJson(string) equals the original.

Reference: gymnasium/envs/registration.py.

Constructors

EnvSpec(string, object?, double?, bool, long?, bool, bool, Info?, IEnumerable<WrapperSpec>?, object?)

Creates a spec; the namespace, name and version are parsed from id, as post_init does.

public EnvSpec(string id, object? entryPoint = null, double? rewardThreshold = null, bool nondeterministic = false, long? maxEpisodeSteps = null, bool orderEnforce = true, bool disableEnvChecker = false, Info? kwargs = null, IEnumerable<WrapperSpec>? additionalWrappers = null, object? vectorEntryPoint = null)

Parameters

id string

The id make takes: namespace/[-v(version)], for example "CartPole-v1".

entryPoint object

The env's location, a "Namespace:Class" string, or an EnvCreator; null when the spec only describes an env.

rewardThreshold double?

The return at which the task counts as solved, or null.

nondeterministic bool

Whether the same seed and actions can still give different observations.

maxEpisodeSteps long?

The step limit a TimeLimit enforces, or null for none.

orderEnforce bool

Whether make adds OrderEnforcing (reset before step and render).

disableEnvChecker bool

Whether make leaves out the passive env checker.

kwargs Info

The keyword arguments the env is constructed with; null is an empty dict (the dataclass's default_factory).

additionalWrappers IEnumerable<WrapperSpec>

The wrappers applied on top, in order; null is none.

vectorEntryPoint object

The location of a vectorized implementation, or null.

Exceptions

ArgumentNullException

Thrown when id is null.

Error

Thrown for a malformed id, with Gymnasium's message (see ParseEnvId(string)).

Properties

AdditionalWrappers

The wrappers applied on top of the env, in order (Python's tuple: replace it, do not edit it).

public IReadOnlyList<WrapperSpec> AdditionalWrappers { get; set; }

Property Value

IReadOnlyList<WrapperSpec>

DisableEnvChecker

Whether make leaves out the passive env checker.

public bool DisableEnvChecker { get; set; }

Property Value

bool

EntryPoint

A "Namespace:Class" string, an EnvCreator, or null.

public object? EntryPoint { get; set; }

Property Value

object

Id

The id, namespace/[-v(version)].

public string Id { get; set; }

Property Value

string

Kwargs

The keyword arguments the env is constructed with, a Python dict.

public Info Kwargs { get; set; }

Property Value

Info

MaxEpisodeSteps

The step limit a TimeLimit enforces, or null for none.

public long? MaxEpisodeSteps { get; set; }

Property Value

long?

Name

The name parsed from Id at construction.

public string Name { get; set; }

Property Value

string

Namespace

The namespace parsed from Id at construction, or null.

public string? Namespace { get; set; }

Property Value

string

Nondeterministic

Whether the same seed and actions can still give different observations.

public bool Nondeterministic { get; set; }

Property Value

bool

OrderEnforce

Whether make adds OrderEnforcing; true by default.

public bool OrderEnforce { get; set; }

Property Value

bool

RewardThreshold

The return at which the task counts as solved, or null.

public double? RewardThreshold { get; set; }

Property Value

double?

VectorEntryPoint

The location of a vectorized implementation (a string or a creator), or null.

public object? VectorEntryPoint { get; set; }

Property Value

object

Version

The version parsed from Id at construction, or null for an unversioned id.

public long? Version { get; set; }

Property Value

long?

Methods

DeepCopy()

copy.deepcopy(spec): a spec with the same fields whose kwargs and wrapper specs are copies, so a wrapper can edit the copy (TimeLimit sets MaxEpisodeSteps) without touching the original.

public EnvSpec DeepCopy()

Returns

EnvSpec

The copy; entry points are shared, as Python's deepcopy shares functions.

Equals(EnvSpec?)

The dataclass equality: every field equal, in declaration order, Kwargs as Python dicts.

public bool Equals(EnvSpec? other)

Parameters

other EnvSpec

The other spec; may be null.

Returns

bool

true when all fields are equal.

FromJson(string)

Reads a spec back from ToJson()'s text (Python's from_json): the wrapper specs first, then the spec from the remaining fields by name, as EnvSpec(**fields).

public static EnvSpec FromJson(string jsonEnvSpec)

Parameters

jsonEnvSpec string

The JSON text.

Returns

EnvSpec

The spec; its entry points are the strings the JSON holds.

Remarks

Exceptions

ValueError

Thrown for malformed JSON, or fields that do not make a spec: An issue occurred when trying to make {...} an EnvSpec (or a WrapperSpec), with the cause as the inner exception.

KeyError

Thrown when the JSON has no additional_wrappers field.

AttributeError

Thrown when the JSON is not an object.

TypeError

Thrown when additional_wrappers is not a list.

GetHashCode()

A hash consistent with Equals(EnvSpec?): the id and the counts of kwargs and wrappers.

public override int GetHashCode()

Returns

int

The hash.

Make(object?, long?, bool?)

Builds the env this spec describes with make's wrappers (Python's spec.make(**kwargs)).

public IEnv Make(object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

kwargs object

The env's constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env; the caller owns it.

Remarks

Exceptions

TypeError

Thrown when the env cannot be built from the kwargs.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

NotImplementedError

Thrown when HumanRendering would be needed.

Make<TObs, TAct>(object?, long?, bool?)

Builds the env this spec describes as an Env<TObs, TAct> (DR-10); see Make(object?, long?, bool?).

public Env<TObs, TAct> Make<TObs, TAct>(object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

kwargs object

The env's constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have.

TAct

The action type the env must have.

Exceptions

TypeError

Thrown when the env is not an Env<TObs, TAct> or cannot be built from the kwargs.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

NotImplementedError

Thrown when HumanRendering would be needed.

Pprint(bool, bool, bool)

The spec as key=value lines: the id always, the other fields when they differ from their defaults (or always with printAll).

public string? Pprint(bool disablePrint = false, bool includeEntryPoints = false, bool printAll = false)

Parameters

disablePrint bool

Return the text instead of writing it to the console.

includeEntryPoints bool

Also print the entry points of the env and of each wrapper.

printAll bool

Print every field, including those at their default values.

Returns

string

The text when disablePrint is set, otherwise null (it was printed).

Remarks

ToJson()

The spec as JSON (Python's to_json): dataclasses.asdict without the fields parsed from the id, written by Python's json.dumps, so the text is Gymnasium's byte for byte where the fields agree.

public string ToJson()

Returns

string

The JSON text.

Remarks

An entry point given as a class is written as its "Namespace:Class" string (Python would refuse a class as a callable), the one field where Gym.NET's JSON differs from Gymnasium's by design: it names a .NET class. Reference: gymnasium/envs/registration.py.

Exceptions

ValueError

Thrown when an entry point is a function (an EnvCreator), which JSON cannot carry: Callable found in CartPole-v1 for entry_point attribute with value=... Currently, Gymnasium does not support serialising callables.

TypeError

Thrown when a kwarg cannot be serialized (Object of type ndarray is not JSON serializable).

ToString()

The dataclass repr, fields in declaration order: EnvSpec(id='CartPole-v1', entry_point=..., ..., additional_wrappers=(), vector_entry_point=None). Wrapper and warning messages embed it.

public override string ToString()

Returns

string

The text.