How farama-foundation/gymnasium works
Main Components
• Core API Layer
– gymnasium/core.py: defines the Env interface, make(), register(), EnvSpec, etc.
– gymnasium/registration.py: maintains the environment registry.
• Environment Implementations
– gymnasium/envs/…: folders for classic_control, box2d, mujoco, toy_text, atari (third-party).
– Each env module implements Env subclasses, assets, rendering, physics-engine bindings.
• Space Definitions
– Describes state/action spaces for environments.
• Vectorization
– gymnasium/vector: AsyncVectorEnv, SyncVectorEnv, shared-memory utils.
– Enables parallel/multi-process rollouts.
• Wrappers
– gymnasium/wrappers + gymnasium/wrappers/vector: pre/post processors for observations, actions, rewards, rendering.
• Utilities
– gymnasium/utils: seeding, recording, performance checks, conversions, passive/environment checker, video save.
• External Engine Integrations
– Box2D (PyGame-based physics), MuJoCo (mujoco-py bindings), Atari (ALE emulator), JAX (functional environments), Torch conversions.
• CLI / Packaging
– bin/docker_entrypoint, Dockerfiles: containerization.
– setup.py / pyproject.toml: packaging/publishing.
• Documentation & Tutorials
• Testing & CI/CD
– tests/: unit/integration tests for every component.
– .github/workflows: pre-commit, pytest, docs-build, PyPI publish.
Relationships and Data Flows
• User Code → Gymnasium API → Registration → Environment Instance →
• (Action) → Wrapper Chain → (Action) → Underlying Env Implementation → Physics/RL Engine →
• (Observation/Reward) ← Wrapper Chain ← Underlying Env.
• VectorEnv multiplexes multiple Env Instances, merging/separating batched obs/actions via shared memory or IPC.
• Spaces are referenced by both API and Env Implementations to validate inputs/outputs.
• Utils modules are invoked at various points (seeding at reset, recording during step, environment checker on make).
• CI/CD pipeline monitors code, runs tests, builds docs, publishes to PyPI; docs-build uses docs/_scripts for asset generation.
Architectural Patterns
• Factory/Registry for environment creation (gym.make)
• Decorator Pattern for wrappers (wrappers wrap Env subclasses)
• Adapter Pattern for external engine bindings (MuJoCoEnv, Box2DEnv, ALEEnv)
• Parallelism via vectorization (strategy pattern: sync vs. async)
• Modular plugin-style structure: new env families or wrappers drop into gymnasium/envs or gymnasium/wrappers.