Recreation of the turn-based battle system from the first two Paper Mario games
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Mario performing Multibounce.

Paper Mario Battle System (PMBS for short) is an open source recreation of the turn-based battle system from the first two Paper Mario games. The goal is to create a modular, flexible battle system that is customizable and can be used in game projects. The inspiration for this project came from the lack of open source battle systems that closely resemble Paper Mario.

More information can be found on the wiki, including potential improvements, documentation, and examples for using PMBS.


  • Turn-based Battles
  • All Status Effects from PM and TTYD
  • Action Commands
  • Items
  • Badges
  • Battle Menus
  • Dialogue Bubbles with Control Codes
  • Move Sequences
  • Accurate and modular Damage Formula
  • And more!

PMBS contains most of the core features from the battle system of Paper Mario and Paper Mario: The Thousand-Year Door, and it supports all interactions between characters found in the original games. It's extensible; you can create new interactions not seen in the original games, including, but not limited to, an attack that forces Mario to swap out his Partner or a ranged attack that suffers from Payback damage. This makes it a viable tool for Paper Mario enthusiasts to test out builds and new abilities.


  1. Clone the repository
  2. Install MonoGame or later.
  3. Install Visual Studio 2017, though earlier versions may work as well. On non-Windows platforms, install JetBrains Rider, MonoDevelop, or Xamarin Studio. On OSX you can also use Visual Studio for Mac. The project targets DesktopGL and .NET 4.7.1, and it uses the latest minor C# version (7.3).
  4. Install NuGet or open the Package Manager Console in Visual Studio.
  5. Run nuget restore -PackagesDirectory PaperMarioBattleSystem in a terminal or the Package Manager Console to restore all NuGet packages in the project. HtmlAgilityPack is currently used to help parse Control Codes for the dialogue system.


Cross-platform builds can be made using Mono's mkbundle. You can find a great tutorial for setting up and using the tool on Windows here. Something overlooked in the tutorial is that you will need to extract the runtime you want to build for. To do so, rename the runtime file's extension to ".zip" then extract it.

For native non-Windows builds to run, you may need to comment out code involving the System.Windows.Forms namespace. The only code in the project using System.Windows.Forms are the debug functions that take screenshots and dump logs, so it doesn't affect the battle system itself.


Contributions are encouraged and appreciated! Feel free to file an issue for any bugs, missing features, or suggestions for improving the battle system. Pull requests are highly encouraged.

For any significant changes, please open an issue first to discuss your ideas. As of the 1.0 release, PMBS follows standard GitHub Flow.

For ideas on what needs work, take a look at the issues as well as the improvements listed on the wiki.


  • Thomas Deeb (aka Kimimaru)


This project is licensed under the MIT License - see the file for details.