https://github.com/julesbobeuf/super-mario-land-qlearning

University Project in which we created an AI for Super Mario Land
https://github.com/julesbobeuf/super-mario-land-qlearning

mario python3 qlearning

Last synced: 23 days ago
JSON representation

University Project in which we created an AI for Super Mario Land

• Host: GitHub
• URL: https://github.com/julesbobeuf/super-mario-land-qlearning
• Owner: JulesBobeuf
• License: mit
• Created: 2025-09-21T15:20:39.000Z (27 days ago)
• Default Branch: main
• Last Pushed: 2025-09-21T15:29:10.000Z (27 days ago)
• Last Synced: 2025-09-21T17:37:23.985Z (27 days ago)
• Topics: mario, python3, qlearning
• Language: Python
• Homepage:
• Size: 5.09 MB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Super-Mario-Land-QLearning

**Super-Mario-Land-QLearning** is a university project in which we created an AI to play **Super Mario Land** using reinforcement learning techniques.

## About The Project

The goal of this project was to design an AI capable of playing Super Mario Land effectively. The AI is trained using Q-learning and is able to navigate levels autonomously.

## Built With

[![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)  

[![MongoDB](https://img.shields.io/badge/MongoDB-47A248?style=for-the-badge&logo=mongodb&logoColor=white)](https://www.mongodb.com/)

## Getting Started

### Folder Structure

```markdown

Super-Mario-Land-QLearning/

├── 📁 src/                         # Source code for AI and game logic

│   ├── 📁 qLearning/               # Q-learning implementation

│   ├── 📄 constants.py             # Project constants and settings

│   ├── 📄 database.py              # Database for storing training data

│   ├── 📄 main_random_inputs.py    # Run AI with random inputs

│   ├── 📄 main_run_qlearning.py    # Run AI using Q-learning

│   ├── 📄 main_stats_qlearning.py  # Generate statistics from Q-learning runs

│   └── 📄 main_train_qlearning.py  # Train the Q-learning agent

├── 📄 requirements.txt             # Python dependencies

├── 📄 sml.gb                       # Super Mario Land game ROM

├── 📄 marioooooo.mp4               # Demo video of the AI playing

├── 📄 ARTICLE_SUPER_MARIO.pdf      # Project report

└── 📄 LICENSE                      # MIT License

```

### Prerequisites

Ensure you have Python 3.10+ installed.

```sh

python -m venv .venv

source .venv/bin/activate

pip install -r requirements.txt

```

### Running the AI

1. Activate the virtual environment:

```sh

source .venv/bin/activate

```

2. Run the Q-learning AI:

```sh

python src/main_run_qlearning.py

```

3. Observe the AI playing Super Mario Land autonomously.

## Usage

The AI will interact with the ROM and display gameplay while learning optimal moves using Q-learning. 

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Contact

Jules Bobeuf  

[LinkedIn](https://www.linkedin.com/in/bobeuf-jules/)  

bobeuf.jules@gmail.com

Valentin Devisme  

[LinkedIn](https://www.linkedin.com/in/valentin-devisme-42003728b/)