Kautenja/gym-super-mario-bros

Gymnasium environments for NES Mario games, with task metadata, reward instrumentation, and reproducible evaluation interfaces.

What it solves

gym-super-mario-bros provides a standardized interface for training and testing AI agents in classic Nintendo Entertainment System (NES) Super Mario Bros. games. It transforms the game environment into a format compatible with the Gymnasium (formerly OpenAI Gym) API, allowing researchers and developers to use reinforcement learning (RL) algorithms to teach an agent to play the game.

How it works

The project uses the nes-py emulator to run the NES games. It wraps the game state and controls into a Gymnasium environment, where an agent can send actions (like moving right or jumping) and receive a state (the screen pixels) and a reward based on the game's internal RAM values.

To simplify training, the project provides pre-defined action sets (such as SIMPLE_MOVEMENT and COMPLEX_MOVEMENT) to limit the 256 possible NES action space to a more manageable set of controls.

Who it’s for

  • AI Researchers: Those studying reinforcement learning and agentic behavior in complex, visual environments.
  • ML Engineers: Developers building and testing RL agents for retro gaming.
  • Students: People learning how to apply AI to game-playing agents.

Highlights

  • Multi-game Support: Supports Super Mario Bros., Super Mario Bros. 2 (Lost Levels), Super Mario Bros. 2 (USA), and Super Mario Bros. 3.
  • Detailed Reward Function: Includes a shaped reward function that rewards progress, coin collection, and level completion while penalizing death.
  • Detailed Game State: The info dictionary provides deep access to RAM-based data like x/y position, coins, score, and power-up status.
  • Flexible Tasking: Allows for both full-game runs and targeted training on individual stages (e.g., World 1-1).
  • CLI Tooling: Includes a command-line interface for playing the game via keyboard or random movement for quick testing.

Related

  • Project
    microsoft/farmvibes-ai

    A multi-modal geospatial machine learning framework for agriculture and sustainability that fuses satellite imagery, weather data, and elevation maps to generate robust agricultural insights.

  • Project
    Project-MONAI/MONAILabel

    An intelligent open-source ecosystem for AI-assisted medical image annotation that uses a server-client architecture to enable interactive and automated labeling for radiology, pathology, and endoscopy.

  • Project
    pq-yang/MatAnyone2

    A human video matting framework that preserves fine details and avoids coarse boundaries to extract people from videos with high robustness in real-world conditions.

  • Project
    huawei-bayerlab/marigold-v2

    Marigold V2 is an open‑source research codebase that converts a frozen diffusion transformer (Qwen‑Image‑Edit‑2509) into fast, single‑step dense predictors for monocular depth, see‑through depth, surface normals, and albedo. It provides pretrained LoRA checkpoints, a lightweight fine‑tuning recipe (≈ 1 week on a single 32 GB GPU), CLI inference, benchmark evaluation scripts, and a modular YAML‑driven training framework that can be extended to new dense‑vision tasks.