Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

FeaturesHow To UseRelated PapersMissing FeaturesCopyrights

Robin Baumgarten A* agent

Current Framework Version: 0.8.0

The Mario AI framework is a framework for using AI methods with a version of Super Mario Bros.

This is an updated version for the Mario AI Framework. As the first version was released in 2009, this is the tenth anniversary edition, integrating features from all previous versions and adding several new features. This new code includes a better interface for playing the game with planning algorithms (the planning track of the competition), generating levels (the level generation track), and possibly will support the learning track in the future . The framework comes with multiple different planning agents, level generators and thousands of levels including generated levels from diffeent generators as well as the original Mario levels. Also, the framework is compatible with Video Game Level Corpus (VGLC) processed notations.

If you want to access the old framework, feel free to check out the old websites for the previous competitions (2015 - 2012 - 2011 - 2009).


  • Better Interface for the framework
  • Faster framework
  • Using the original mario art
  • Eleven different playing agents
  • Agents now have a forward model, no more hacks for that
  • Observation grids can be centered around mario or can reflect the current screen.
  • Helper classes to check the observation grid instead of comparing integers
  • Five different level generators
  • Level generator have a forward model to test the levels
  • Thousands of generated levels from winners of the level generation track
  • Fifteen levels from the original mario bros
  • Support event history for major game events
  • A human readable level files

How To Use

Planning Track

Download the repo and run the file. It will run robinBaumgarten A* agent on the first Mario level from the original Super Mario Bros. The game will run for 20 seconds (in-game time) and with Mario starting as small Mario and visuals appearing. To change the agent just change the package name of the agent in the following code

printResults(game.runGame(new agents.robinBaumgarten.Agent(), getLevel("levels/original/lvl-1.txt"), 20, 0, true));

to any of the package names that are found in src/agents/ folder, feel free to use any in your work. If you want to play a level yourself uncomment the following code in file

//printResults(game.playGame(getLevel("levels/original/lvl-1.txt"), 200, 0));

and comment the agent running line from before. This code will run the framework to play the first mario level of the original Super Mario Bros with 200 tick on the game clock and with Mario starting as small mario. Feel free to change the 0 to 1 to start as Large Mario or 2 to start as Fire Mario.

Level Generation Track

Download the repo and run the from the src/ folder to test the framework. It will run the notch generator to generate a level then it will run robinBaumgarten A* agent to play that generated level. Feel free to try another generators by changing the package name of generator in the following line

MarioLevelGenerator generator = new levelGenerators.notch.LevelGenerator();

to any of the other package names of the other generator that can be found in in src/levelGenerators/ folder, feel free to use any in your work. The generators runs for maximum time of 5 hours to generate a level of 150x16 tiles using the following line:

String level = generator.getGeneratedLevel(new MarioLevelModel(150, 16), new MarioTimer(5*60*60*1000));

If you want to play the level by yourself or change the AI playing agent check the Planning Track subsection.

Related Papers

The following paper describes the original Mario AI Benchmark:

The following list show all the papers that talk mainly about playing the game in the Mario AI framework:

The following is a list of papers about level generation in Mario AI Framework:

The following list includes papers that do not fit in the previous categories but still use the Mario AI Framework:

We are aware that this list is not complete. If you want your paper added, please contact us and we will add it to the list.

Missing Features

  • The MarioAI framework core engine
  • Implementing a forward model and multiple different observations (based around mario/based around the screen center)
  • Implementing the original SMB graphics instead of Mario world graphics
  • Adding multiple agents from the previous competition
  • Isolating particle effects from game sprites
  • Only using the first SMB action set (no more shell carrying/wall jumping)
  • Documenting the interface
  • Adding Generated Levels
  • Adding the level generator interface
  • Adding the level generators to the framework
  • Better way to check the observation grid Using TileType and SpriteType
  • Adding event history for the game and agent to MarioResults
  • Modifying the original Mario levels to include more details
  • Adding Punishing Model to the Engine where the player dies when certain basic event fires
  • Allow the punishing model to tackle more complex events that need to be infered
  • Allow Agent debugging by drawing the searched trajectories like the Robin A* video
  • Adapt more agents to the new Mario-Framework
  • Adapt more level generator to the new Mario-Framework
  • Add more stats to MarioResult class similar to Gameplay Metrics
  • Mix the TileType and TileFeature class
  • Adding a simple MCTS agent and simple A* agent
  • Koopa shells can come back to life after stomping on it
  • Adding Monte Mario agent
  • Multiple different backgrounds/palettes that the user can select from.
  • Documenting the whole engine
  • Mimicking the original SMB physics instead of SMW physics
  • Adding the learning track interface


This framework is not endorsed by Nintendo and is only intended for research purposes. Mario is a Nintendo character which the authors don't own any rights to. Nintendo is also the sole owner of all the graphical assets in the game. Any use of this framework is expected to be on a non-commercial basis. This framework was created by Ahmed Khalifa, based on the original Mario AI Framework by Sergey Karakovskiy, Noor Shaker, and Julian Togelius, which in turn was based on Infinite Mario Bros by Markus Persson.


10th Anniversary Edition (Not endorsed by Nintendo)



No releases published


No packages published