Pure-Rust reinforcement learning environments library — a faithful port of Gymnasium with zero-cost abstractions, native rendering, and no unsafe code in user-facing APIs.

gmgn provides a generic Env trait with associated types for compile-time monomorphization, a dynamic DynEnv trait with a global make("CartPole-v1") registry, 14 built-in environments across three categories (classic control, toy text, Box2D), 21 composable wrappers, vectorized execution, and real-time graphical rendering via tiny-skia + minifb — all without leaving Rust.

Add to your Cargo.toml:

[dependencies]
gmgn = "0.4"

use gmgn::prelude::*;
use gmgn::envs::classic_control::{CartPoleEnv, CartPoleConfig};

let mut env = CartPoleEnv::new(CartPoleConfig::default()).unwrap();
let _reset = env.reset(Some(42)).unwrap();

for _ in 0..200 {
    let action = env.action_space().sample(&mut gmgn::rng::create_rng(None));
    let step = env.step(&action).unwrap();
    if step.terminated {
        break;
    }
}

use gmgn::registry::{self, DynValue};

registry::register_builtins();
let mut env = registry::make("CartPole-v1").unwrap();
env.reset_dyn(Some(42)).unwrap();
let step = env.step_dyn(&DynValue::Discrete(1)).unwrap();

use gmgn::prelude::*;
use gmgn::envs::classic_control::{CartPoleEnv, CartPoleConfig};
use gmgn::vector::SyncVectorEnv;

let envs: Vec<_> = (0..4)
    .map(|_| CartPoleEnv::new(CartPoleConfig::default()).unwrap())
    .collect();
let mut vec_env = SyncVectorEnv::new(envs).unwrap();
let reset = vec_env.reset(Some(0)).unwrap();
assert_eq!(reset.obs.len(), 4);

use gmgn::env::{Env, RenderMode};
use gmgn::envs::classic_control::{CartPoleEnv, CartPoleConfig};
use gmgn::space::Space;

let mut env = CartPoleEnv::new(CartPoleConfig {
    render_mode: RenderMode::Human,
    ..CartPoleConfig::default()
}).unwrap();

let mut rng = gmgn::rng::create_rng(Some(42));
env.reset(None).unwrap();

for _ in 0..500 {
    let action = env.action_space().sample(&mut rng);
    let s = env.step(&action).unwrap();
    env.render().unwrap(); // opens a native OS window at 50 FPS
    if s.terminated { break; }
}

gmgn uses a dual-track design that mirrors Gymnasium while leveraging Rust's type system:

• Static track — The generic Env trait uses associated types (Obs, Act, ObsSpace, ActSpace) for full monomorphization. No boxing, no vtables, no runtime dispatch. Wrappers compose via generic nesting (TimeLimit<ClipAction<CartPoleEnv>>).
• Dynamic track — The DynEnv trait + global registry enables make("CartPole-v1") style creation with type-erased DynValue observations and actions. Auto-wraps with TimeLimit and OrderEnforcing per registered EnvSpec.
• Spaces — 10 space types (Discrete, BoundedSpace, MultiDiscrete, MultiBinary, Dict, Tuple, OneOf, Sequence, Graph, Text) each implement the Space trait with sample(), contains(), flatdim(), and flatten().
• Rendering — Feature-gated Canvas (2D drawing surface over tiny-skia Pixmap) + RenderWindow (native OS window via minifb). Supports RenderMode::Human (live window) and RenderMode::RgbArray (pixel buffer).
• Vectorized — SyncVectorEnv and AsyncVectorEnv with configurable AutoresetMode (NextStep / SameStep / Disabled), plus VecRecordEpisodeStatistics wrapper.

All environments are rigorously validated against the official Gymnasium Python implementations for observation spaces, reward shaping, physics parameters, and termination conditions.

21 composable wrappers mirroring Gymnasium wrappers:

# Default (classic control + toy text + rendering)
cargo add gmgn

# With Box2D environments
cargo add gmgn --features box2d

# Minimal (no rendering, no Box2D)
cargo add gmgn --no-default-features

# Classic control with rendering
cargo run --example cartpole
cargo run --example mountain_car
cargo run --example continuous_mountain_car
cargo run --example pendulum
cargo run --example acrobot

# Toy text
cargo run --example frozen_lake
cargo run --example taxi
cargo run --example cliff_walking
cargo run --example blackjack

# Box2D (requires feature flag)
cargo run --example lunar_lander --features box2d
cargo run --example bipedal_walker --features box2d

gmgn aims to be a faithful Rust port of Gymnasium (Farama Foundation). Every environment is implemented by line-by-line comparison with the official Python source, including:

• Identical physics parameters, constants, and coordinate systems
• Matching observation and action space definitions
• Equivalent reward shaping formulas and termination conditions
• Aligned RNG consumption order for seed-reproducible trajectories
• Pixel-accurate rendering matching Gymnasium's pygame output

The following divergences are by design, leveraging Rust's strengths:

Rust edition 2024 (nightly or stable 1.85+).

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be dual-licensed as above, without any additional terms or conditions.