Class EnvRegistry
- Namespace
- Gym.Envs.Registration
- Assembly
- Gym.dll
Gymnasium's gymnasium.envs.registration module: the id grammar, the process-wide Registry,
Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?), Spec(string), Make(string, object?, long?, bool?) and
PprintRegistry(IReadOnlyDictionary<string, EnvSpec>?, int, IEnumerable<string?>?, bool). The top-level Gymnasium class re-exports them, as
gymnasium.make re-exports gymnasium.envs.registration.make.
public static class EnvRegistry
- Inheritance
-
EnvRegistry
- Inherited Members
Remarks
Reference: gymnasium/envs/registration.py.
Properties
CurrentNamespace
The namespace Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?) puts ids in, overriding the id's own (Python's module global
current_namespace); null keeps each id's namespace. Set it through
Namespace(string), which restores it.
public static string? CurrentNamespace { get; set; }
Property Value
Remarks
Unlike Python's module global, the value belongs to the current thread and async flow (an AsyncLocal<T>, DR-57): two threads registering inside scopes of their own at the same moment each get their own namespace, where one global would hand both the namespace opened last. A thread, task or async continuation started inside a scope inherits its value as it was at the start. On one thread it behaves as Gymnasium's global does. Footgun: a value set inside an async method does not flow back to its caller once the method returns (how AsyncLocal<T> works), so open the scope in the code that registers rather than in a helper it awaits.
Registry
The global registry (Python's gymnasium.registry): every id make knows, in registration order. Env
assemblies fill it from their module initializers (DR-12); Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?) adds to it.
public static EnvSpecRegistry Registry { get; }
Property Value
Methods
EntryPointName(Type)
The "Namespace:Class" string that names a class as an entry point, the form load_env_creator reads
back: "Gym.Environments.Envs.Classic:CartPoleEnv", a generic class without its arity
("Gym.Wrappers:TimeLimit"). A spec's JSON writes a class entry point this way.
public static string EntryPointName(Type type)
Parameters
typeTypeThe class.
Returns
- string
The entry-point string.
Exceptions
- ArgumentNullException
Thrown when
typeis null.
FindHighestVersion(string?, string)
The highest registered version of name in ns (Python's
find_highest_version), which make uses for an id given without a version.
public static long? FindHighestVersion(string? ns, string name)
Parameters
Returns
Remarks
Reference: gymnasium/envs/registration.py.
GetEnvId(string?, string, long?)
Joins a namespace, name and version into an id, the inverse of ParseEnvId(string):
("ALE", "Pong", 5) is "ALE/Pong-v5".
public static string GetEnvId(string? ns, string name, long? version)
Parameters
Returns
- string
The id.
Remarks
Reference: gymnasium/envs/registration.py.
LoadEnvCreator(string)
The class a "Namespace:Class" entry point names (Python's load_env_creator, which imports
module and reads its attribute): a class of that name in that namespace among the loaded assemblies,
after loading the assembly named by the namespace (or a prefix of it) when none declares it yet.
public static Type LoadEnvCreator(string name)
Parameters
namestringThe entry point,
"Gym.Wrappers:TimeLimit"; a generic class is named without its arity.
Returns
- Type
The class (an open generic definition for a generic one).
Remarks
Reference: gymnasium/envs/registration.py.
Exceptions
- ArgumentNullException
Thrown when
nameis null.- ValueError
Thrown when the string has no colon or more than one (Python's unpacking:
not enough values to unpack (expected 2, got 1)).- ModuleNotFoundError
Thrown when no loaded or loadable assembly declares the namespace:
No module named 'X'.- AttributeError
Thrown when the namespace has no such class:
module 'X' has no attribute 'Y'.
Make(EnvSpec, object?, long?, bool?)
Builds the env a spec describes, with make's wrappers (Python's make(env_spec)); see Make(string, object?, long?, bool?).
public static IEnv Make(EnvSpec spec, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)
Parameters
specEnvSpecThe spec, registered or not (one read back from JSON, for example).
kwargsobjectThe env's constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- IEnv
The env; the caller owns it.
Exceptions
- TypeError
Thrown when
specis null, or as Make(string, object?, long?, bool?) does.- 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
ClassMetadatais not a dict.- ValueError
Thrown when a recorded wrapper cannot be re-created.
Make(string, object?, long?, bool?)
Builds the env registered under id with make's wrappers (Python's make): the
env, then PassiveEnvChecker (unless disabled), OrderEnforcing (when the spec enforces order),
TimeLimit (when a step limit applies), the spec's additional wrappers, and RenderCollection for a
*_list render mode the env does not provide itself.
public static IEnv Make(string id, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)
Parameters
idstringThe id:
"CartPole-v1", an unversioned"CartPole"(the latest version, with a warning), or"Assembly:Id", which first loads the assembly and runs its registration, as Python imports the module.kwargsobjectThe env's constructor arguments by Python name, over the spec's: a dictionary, an options record, or an anonymous object (
new { render_mode = "rgb_array" }).maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimitat all.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- IEnv
The env, through its untyped view; the caller owns it.
Remarks
The env and every wrapper are built through Construct(Type, IReadOnlyDictionary<string, object?>), which binds keywords by Python name and closes the generic wrappers over the env's types. When a step after the env's construction fails (a wrapper refusing the env), the env built so far is disposed before the error propagates.
Where an env lists both rgb_array and rgb_array_list and human is asked for, Python picks
either by its set order; Gym.NET always renders rgb_array for the HumanRendering wrapper.
Reference: gymnasium/envs/registration.py.
Exceptions
- TypeError
Thrown when
idis null, when the env's constructor rejects the kwargs (CartPoleEnv.init() got an unexpected keyword argument 'x' was raised from the environment creator for CartPole-v1 with kwargs ({'x': 1})), or when the entry point does not build an env.- Error
Thrown when the id is not registered or has no entry point, with Gymnasium's messages.
- NamespaceNotFound
Thrown when the id's namespace is unknown.
- NameNotFound
Thrown when the name is unknown.
- VersionNotFound
Thrown when the version is newer than any registered.
- DeprecatedEnv
Thrown when the version is older than the latest.
- ModuleNotFoundError
Thrown when an
"Assembly:Id"or 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
ClassMetadatais not a dict.- ValueError
Thrown when a recorded wrapper cannot be re-created, or a pre-applied wrapper disagrees with the spec.
MakeVec(EnvSpec, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)
Builds a vector env from a spec (gymnasium.make_vec(env_spec)); see MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?).
public static IVectorEnv MakeVec(EnvSpec spec, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)
Parameters
specEnvSpecThe spec: a registered one, or one a previous
MakeVecrecorded (itsnum_envs, mode, vector kwargs and wrappers win).numEnvsintThe number of sub-envs.
vectorizationModeobjectThe vectorization mode, or null.
vectorKwargsobjectThe vector env's constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's constructor arguments by Python name.
Returns
- IVectorEnv
The vector env; the caller owns it.
Exceptions
- TypeError
Thrown when
specis null, or the env cannot be built.- ValueError
Thrown for an unknown vectorization mode.
- Error
Thrown when the spec has no (vector) entry point, or the vector entry point is asked for with vector kwargs or wrappers.
- RuntimeError
Thrown when a sub-env's spaces do not fit the batch (sync and async modes).
MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)
Builds a vector env of numEnvs copies of a registered env (gymnasium.make_vec): its own
vectorized class when the spec has a vector_entry_point (CartPoleVectorEnv), else a
SyncVectorEnv of Make's stacks. The result is untyped (observations and actions as
objects); MakeVec<TObs, TAct>(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?) types it.
public static IVectorEnv MakeVec(string id, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)
Parameters
idstringThe id.
numEnvsintThe number of sub-envs; a spec made by
MakeVecrecords its own, which wins.vectorizationModeobjectA VectorizeMode or its value (
"sync","async","vector_entry_point"); null picks the vector entry point when the spec has one, else sync.vectorKwargsobjectThe vector env's constructor arguments by Python name (
autoreset_mode,copy,observation_mode; for async alsoshared_memory,max_concurrency,execution_mode,thread_count); sync and async only.wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env after
Make, innermost first; sync and async only.kwargsobjectThe env's constructor arguments by Python name, over the spec's.
Returns
- IVectorEnv
The vector env, its spec recording how it was made; the caller owns it.
Remarks
Reference: gymnasium/envs/registration.py.
Exceptions
- TypeError
Thrown when
idis null, or the env cannot be built from the kwargs.- ValueError
Thrown for an unknown vectorization mode, with Gymnasium's message.
- Error
Thrown when the id is not registered, has no (vector) entry point, or the vector entry point is asked for with vector kwargs or wrappers.
- RuntimeError
Thrown when a sub-env's spaces do not fit the batch (sync and async modes).
MakeVec<TObs, TAct>(EnvSpec, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)
The spec form of MakeVec<TObs, TAct>(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?).
public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(EnvSpec spec, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)
Parameters
specEnvSpecThe spec.
numEnvsintThe number of sub-envs.
vectorizationModeobjectThe vectorization mode, or null.
vectorKwargsobjectThe vector env's constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's constructor arguments by Python name.
Returns
- VectorEnv<TObs, TAct>
The vector env; the caller owns it.
Type Parameters
TObsThe batched observation type.
TActThe batched action type.
Exceptions
- TypeError
Thrown when
specis null or the batched types differ.- ValueError
Thrown for an unknown vectorization mode.
- Error
Thrown when the spec has no (vector) entry point.
- RuntimeError
Thrown when a sub-env's spaces do not fit the batch (sync and async modes).
MakeVec<TObs, TAct>(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)
MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?) typed (DR-21): the vector env
comes back as VectorEnv<TObs, TAct> of the batched types, a sync one built as
SyncVectorEnv<TObs, TAct>.
public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(string id, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)
Parameters
idstringThe id.
numEnvsintThe number of sub-envs.
vectorizationModeobjectThe vectorization mode, or null.
vectorKwargsobjectThe vector env's constructor arguments by Python name.
wrappersIEnumerable<Func<IEnv, IEnv>>Wrappers applied to every sub-env.
kwargsobjectThe env's constructor arguments by Python name.
Returns
- VectorEnv<TObs, TAct>
The vector env; the caller owns it.
Type Parameters
TObsThe batched observation type (NDArray for array spaces).
TActThe batched action type.
Exceptions
- TypeError
Thrown when the vector env's batched types are not the ones asked for, or as the untyped form throws.
- ValueError
Thrown for an unknown vectorization mode.
- Error
Thrown when the id is not registered or has no (vector) entry point.
- RuntimeError
Thrown when a sub-env's spaces do not fit the batch (sync and async modes).
Make<TObs, TAct>(EnvSpec, object?, long?, bool?)
Make(EnvSpec, object?, long?, bool?) typed (DR-10); see Make<TObs, TAct>(string, object?, long?, bool?).
public static Env<TObs, TAct> Make<TObs, TAct>(EnvSpec spec, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)
Parameters
specEnvSpecThe spec.
kwargsobjectThe env's constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have.
TActThe action type the env must have.
Exceptions
- TypeError
Thrown when
specis null or the env is not anEnv<TObs, TAct>.- 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
ClassMetadatais not a dict.- ValueError
Thrown when a recorded wrapper cannot be re-created.
Make<TObs, TAct>(string, object?, long?, bool?)
Make(string, object?, long?, bool?) typed (DR-10): the env comes back as
Env<TObs, TAct>. An env class of other types is refused before it is built; a stack whose recorded
wrappers change the types is checked once built.
public static Env<TObs, TAct> Make<TObs, TAct>(string id, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)
Parameters
idstringThe id.
kwargsobjectThe env's constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have (
NDArrayfor CartPole).TActThe action type the env must have (
NDArrayfor aDiscreteaction, DR-08).
Exceptions
- TypeError
Thrown when the env is not an
Env<TObs, TAct>, or as Make(string, object?, long?, bool?) does.- Error
Thrown when the id is not registered or has no entry point.
- NamespaceNotFound
Thrown when the id's namespace is unknown.
- NameNotFound
Thrown when the name is unknown.
- VersionNotFound
Thrown when the version is newer than any registered.
- DeprecatedEnv
Thrown when the version is older than the latest.
- ModuleNotFoundError
Thrown when a module named by the id or the entry point does not exist.
- AttributeError
Thrown when a string entry point's namespace has no such class.
- InvalidMetadata
Thrown when the env class's
ClassMetadatais not a dict.- ValueError
Thrown when a recorded wrapper cannot be re-created.
Namespace(string)
Sets CurrentNamespace until the returned scope is disposed (Python's namespace context
manager): using (EnvRegistry.Namespace("MyPlugin")) Register("Env-v0", ...); registers
MyPlugin/Env-v0. Inside the scope every id lands in ns, even one that names a
namespace of its own, as in Gymnasium.
public static IDisposable Namespace(string ns)
Parameters
nsstringThe namespace.
Returns
- IDisposable
The scope; disposing it restores the namespace that was current before, once.
Remarks
The scope applies to the thread and async flow that opened it, and to the threads and tasks started inside it (DR-57); other threads keep their own namespace. Reference: gymnasium/envs/registration.py.
ParseEnvId(string)
Splits an id into its namespace, name and version, the inverse of GetEnvId(string?, string, long?).
"ALE/Pong-v5" is ("ALE", "Pong", 5); "CartPole" is (null, "CartPole", null).
public static (string? Namespace, string Name, long? Version) ParseEnvId(string envId)
Parameters
envIdstringThe id.
Returns
- (string Namespace, string Name, long? Version)
The namespace (or null), the name, and the version (or null).
Remarks
Reference: gymnasium/envs/registration.py.
Exceptions
- ArgumentNullException
Thrown when
envIdis null.- Error
Thrown when the id does not match, with Gymnasium's message:
Malformed environment ID: {env_id}. (Currently all IDs must be of the form namespace/-v(version). (namespace is optional)).- OverflowException
Thrown for a version beyond long, which Python's unbounded int would hold.
PprintRegistry(IReadOnlyDictionary<string, EnvSpec>?, int, IEnumerable<string?>?, bool)
Prints (or returns) every registered id grouped by namespace (Python's pprint_registry): a
===== namespace ===== header, then the ids sorted, numCols to a line.
public static string? PprintRegistry(IReadOnlyDictionary<string, EnvSpec>? printRegistry = null, int numCols = 3, IEnumerable<string?>? excludeNamespaces = null, bool disablePrint = false)
Parameters
printRegistryIReadOnlyDictionary<string, EnvSpec>numColsintHow many ids per line.
excludeNamespacesIEnumerable<string>Namespaces to leave out, or null.
disablePrintboolReturn the text instead of writing it to the console.
Returns
Remarks
An id without a namespace is grouped by its entry point, as in Gymnasium: a string
"gymnasium.envs.classic_control.cartpole:CartPoleEnv" by its third dotted part (classic_control),
else its second, else the env's name; a function by None. A class entry point, which Python groups under
None too, is grouped here by the last part of its namespace, the env family (Classic for
Gym.Environments.Envs.Classic), so Gym.NET's own ids print in families.
Reference: gymnasium/envs/registration.py.
Exceptions
- ZeroDivisionError
Thrown when
numColsis 0 (Python'sZeroDivisionError).
Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?)
Registers an env under id for make (Python's register). The id's namespace is
replaced by CurrentNamespace when one is set; re-registering an id replaces it with a warning.
public static void Register(string id, object? entryPoint = null, double? rewardThreshold = null, bool nondeterministic = false, long? maxEpisodeSteps = null, bool orderEnforce = true, bool disableEnvChecker = false, IEnumerable<WrapperSpec>? additionalWrappers = null, object? vectorEntryPoint = null, object? kwargs = null)
Parameters
idstringThe id,
namespace/[-v(version)].entryPointobjectWhat builds the env: its class (
typeof(CartPoleEnv)), an EnvCreator, or a"Namespace:Class"string resolved when the env is made.rewardThresholddouble?The return at which the task counts as solved.
nondeterministicboolWhether the same seed and actions can still give different observations.
maxEpisodeStepslong?The step limit
make'sTimeLimitenforces, or null for none.orderEnforceboolWhether
makeaddsOrderEnforcing.disableEnvCheckerboolWhether
makeleaves outPassiveEnvChecker.additionalWrappersIEnumerable<WrapperSpec>Wrappers
makeapplies on top, in order.vectorEntryPointobjectWhat builds a vectorized version (for
make_vec).kwargsobjectThe env's constructor arguments by Python name: a dictionary (an Info is kept as the spec's own, as Python keeps the dict passed), an options record, or an anonymous object.
Remarks
Reference: gymnasium/envs/registration.py.
Exceptions
- ValueError
Thrown when neither entry point is given:
Either.entry_pointorvector_entry_point(or both) must be provided- Error
Thrown for a malformed id.
- RegistrationError
Thrown when a versioned and an unversioned id of the same name would both be registered, with Gymnasium's messages.
- TypeError
Thrown when
kwargsis not a mapping.
RegisterEnvs(object?)
A no-op that marks a module as used (Python's register_envs), kept so code written against Gymnasium reads
the same. Registering an env assembly's ids is its Register()'s job, which a module initializer calls
(DR-12, DR-17).
public static void RegisterEnvs(object? envModule)
Parameters
envModuleobjectAnything; ignored.
Remarks
Reference: gymnasium/envs/registration.py.
Spec(string)
The spec registered under envId (Python's spec), without the version and namespace
fallbacks of make: the id must be registered exactly.
public static EnvSpec Spec(string envId)
Parameters
envIdstringThe id.
Returns
- EnvSpec
The registered spec itself (not a copy).
Remarks
Reference: gymnasium/envs/registration.py.
Exceptions
- ArgumentNullException
Thrown when
envIdis null.- Error
Thrown for a malformed id, or one that is not registered (
No registered env with id: X).- NamespaceNotFound
Thrown when the id's namespace is unknown (with a suggestion when one is close).
- NameNotFound
Thrown when the name is unknown in its namespace.
- VersionNotFound
Thrown when the version is newer than any registered.
- DeprecatedEnv
Thrown when the version is older than the latest, or only an unversioned id exists.