Prerequisites#

While I will be doing all of my development on MacOS and Linux, DevKitPro supports Windows as well. All commands shown in this tutorial will be in bash, so Windows users will need to use the Git-Bash terminal to follow along.

Software#

Package Managers#

• Windows: Chocolatey, a package manager for Windows.
  • Install by following the instructions on the Chocolatey installation page.
• MacOS: Homebrew, a package manager for MacOS.
  • Install by running the following command in your terminal:
  • /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
• Linux: Your distribution's package manager (e.g. apt, dnf, pacman, etc.)

Development Tools#

Windows#

• DevKitPro, our toolchain for building GBA homebrew
  • Install by following the instructions on the DevKitPro Getting Started page.
  • During installation, make sure to select the gba-dev package from the list.
• Git for Windows, for version control and Git-Bash terminal
• Python, for running various scripts
  • I am using 3.12 for this series
• Make, a build automation tool
  • If you installed DevKitPro with the GUI installer, Make should already be included. If you find out it isn't when you run make, you can install it via Chocolatey with choco install make.

MacOS#

• DevKitPro, our toolchain for building GBA homebrew
  • Install by following the instructions on the DevKitPro Getting Started page.
  • After installation of the DevKitPro base system, run dkp-pacman -S gba-dev to install the gba-dev package.
• pyenv preferably for a Python version manager, or install Python via Homebrew
  • If using pyenv:
    • Install via Homebrew with brew install pyenv
    • install Python 3.12 with pyenv install 3.12.12 and set it as the global version with pyenv global 3.12.12
  • If installing Python via Homebrew, run brew install python to install the latest version of Python
• Make, a build automation tool
  • Included with Xcode Command Line Tools (xcode-select --install)
• git, for version control
  • Install via Homebrew with brew install git

Linux#

• DevKitPro, our toolchain for building GBA homebrew
  • Install by following the instructions on the DevKitPro Getting Started page.
  • After installation of the DevKitPro base system, run dkp-pacman -S gba-dev to install the gba-dev package.
    • Some distros using vanilla pacman: pacman -S gba-dev
• Python, for running various scripts
  • Install via your package manager, e.g. sudo apt install python3 on Debian-based systems
• Make, a build automation tool
  • Install via your package manager, e.g. sudo apt install build-essential on Debian-based systems
• git, for version control
  • Install via your package manager, e.g. sudo apt install git on Debian-based systems

All Platforms#

• mGBA, an emulator for testing our GBA homebrew.
  • Supports GDB debugging as well for breakpoints and memory inspection.

Optional / Alternative Tools#

To reduce the clutter of the main instructions, I have placed some optional or alternative tools in this expandable section.

If you're interested in alternatives to all these tools, click here!

Some flavorful alternatives for the experienced reader who wants to explore beyond the scope of this tutorial:

• Toolchains:
  • Wonderful Toolchain, an alternative GBA homebrew toolchain supported by Butano.
    • For Windows & Linux only!
• Emulators:
  • VisualBoyAdvance-M (VBA-M), a popular alternative emulator for GBA homebrew development.
    • It supports debugging with gdb like mGBA, which is very useful
  • Mesen, an alternative emulator that supports GBA, has a color mode that more closely matches the original screen, and has a great debugger.

Code Editor / IDE#

Finally, you will need a code editor. This is the most highly subjective part of the setup, so I will leave it up to you.

If you are a beginner, don't use a basic text editor or an IDE that requires extensive configuration unless you really know what you're doing. Beginners will fall into the trap of simple text editors or misconfigurations, and run into errors they don't know how to debug. IDEs are designed to help you with debugging and code management. Experienced developers may prefer text editors or highly configurable IDEs, but they also know how to debug issues that arise from using them.

I have included configurations for the following editors in the repository:

Editor	Pros	Cons	Notes
Visual Studio Code	Supports every OS Free and open source Extensive plugin ecosystem Supports many languages and frameworks Supports GDB debugging with the right extensions Integrated git support	Can be resource-intensive with many extensions Built on Electron and Chromium, which comes with its own set of trade-offs	Popular choice
Zed	Free and open source Fast and modern features Built on Rust for memory safety Good language support Integrated git support	Newer IDE with a smaller ecosystem	I like it a lot. I use it for my job.

Click here to see editors that I recommend but did not include configurations for in the repository

Editor	Pros	Cons	Notes
CLion	First-class C++ support with smart code analysis Integrated debugger Great refactoring tools	Paid product (free trial and free licenses for students and open source contributors) More resource-intensive than VS Code	My preferred IDE for C++ development
Visual Studio	Powerful IDE with extensive features Excellent debugging and profiling tools Strong C++ support	Primarily Windows-focused Can be resource-intensive	Great for Windows users
Vim / Neovim	Extremely lightweight and fast Highly customizable with plugins Powerful keyboard-centric editing	Steeper learning curve Requires configuration for optimal C++ support	Great for those who prefer terminal-based editors
Any editor that uses clangd for C++ LSP	Clangd provides smart code analysis, autocompletion, and error checking	Requires configuration to set up clangd and integrate with the editor	I actually included a mostly complete config for this

Art Tools#

* What we will be using in this series.

• Visual Asset Options:

  • Aseprite (paid)*, a pixel art tool for creating sprites and animations.
    • Paid software, but worth the investment. I have bought this software 3 times across different computers because I use it so much.
  • Aseprite (source), the open source version of Aseprite that you can compile yourself.
    • Lacks some features of the paid version, but still very capable.
  • GIMP, a free and open source image editor.
    • More general-purpose than Aseprite, but can be used for pixel art as well.
  • Krita, another free and open source image editor.
    • Also more general-purpose, but has good support for pixel art.

• Audio Assets Options:

  • OpenMPT*, a free and open source tracker for creating music.
    • Supports exporting to formats compatible with GBA homebrew.
    • Windows "only" software, but can be run on MacOS & Linux with Wine (requires wine).
      • MacOS
        • Install Homebrew if you haven't already with /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
        • Run brew install --cask wine-stable to install Wine.
      • Linux
        • Install Wine via your package manager, e.g. sudo apt install wine on Debian-based systems.
  • Furnace Tracker, a free and open source tracker designed for chiptune music.
    • Cross-platform and lightweight.
    • "Supports" making GBA music, but the only format it can export that is compatible is VGM, which means you can only make Game Boy / Color music. Luckily, the GBA is backwards compatible with GB/C audio, but you cannot take advantage of the GBA's 2 PCM channels.
      • This could be a misunderstanding on my part; please correct me if I'm wrong!

Getting the starter repository#

From here on out, if you are on Windows, "terminal" means the Git-Bash terminal. It is important to use Git-Bash because many commands will not work correctly in Command Prompt or PowerShell. If you are using the terminal in Visual Studio Code, make sure it is set to use Git-Bash as well.

Open your terminal, navigate to your desired directory, and run the following commands to clone the starter repository and navigate into it:

# Clone the repository and navigate into it
git clone https://github.com/breadbored/butano-tutorial-series.git butano-tutorial-series
cd butano-tutorial-series

# Initialize git submodules, which includes Butano itself and an extension for Fonts
git submodule update --init --recursive

In this directory you will find:

butano-tutorial-series/
├─ butano/
├─ butano-ext-scripts/
├─ chapter-1-getting-started/ - Our starting point for this series
├─ chapter-2-assets/
├─ chapter-xx-.../
├─ raw-assets/                - The raw assets used in the series
├─ .gitignore
├─ LICENSE.md
├─ README.md

You can follow along with the tutorial series in its entirety by using the corresponding chapter directory. For the purposes of this tutorial, we will be working in the chapter-1-getting-started directory, and you can reference the other chapters as needed.

cd chapter-1-getting-started

Now let's build and run our starter project to ensure everything is working correctly.

make

To start the game in mGBA (without debugging with gdb) you can run:

make run

Once you see the mGBA window pop up with our starter project running, congratulations! Your development environment is set up correctly!

What's Next?#

Next we will begin working with assets in Butano. This includes creating and importing sprites, backgrounds, and audio into our project. We will also explore ways to use those assets.

Chapter Overview#

0. Introductions and Overview
1. Setting Up Your Development Environment - you are here
   1. Environment FAQ
2. Sprites

---

---

Communities#

Discord#

• Please remember this is not my server, so do not dominate the conversation with questions about this series. The topics are more broad than this series or even Butano itself, so please be respectful of that.
• If you need help, the thing that helps everyone involved is providing your full source code, or if you are unwilling to do that, a "Minimally Reproducible Example" that demonstrates your issue. Not only might you find your problem along the way, but this is a good practice in general when asking for help with programming.
• Please be respectful to @GValiente, the author of Butano, as well as other volunteers who are volunteering their time to help you. You are not entitled to their time or labor. I have had people break this rule many times in many projects. This is a hobby for everyone involved.
• Please search the channels for your question before asking it. Chances are, someone else has had the same question before you.
• Follow the server rules.

Reddit#

r/Homebrew - A general homebrew community for all consoles. r/RetroGameDev - A community for retro game development, including homebrew.

BSky#

@Bread.Codes - My Bluesky profile. Many of the people I follow are into homebrew and retro game development.

Support the Community#

Want there to be Jams? Want more resources, tutorials, and tools? Support the community by donating to the OpenCollective for GBADev! Your donations help fund events like GBAGameJam and support the work of volunteers who create tools and resources for the community.

---

Support the Series#

---

License#

This series is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

The purpose of this license is to allow you to share this series freely, as long as you attribute BreadCodes as the original author, and do not commercialize the content through paid courses, books, or other means.

The project repository for this series is almost entirely licensed under the same license. The exception is chapter-1-getting-started/LICENSE, which is licensed under the MIT License to allow for more flexibility when using the starter code for your own projects. This project uses 3rd party assets which may have different licenses; please refer to the LICENSE file in that directory for more information.

Additional Information#

You can find this project's repository on CodeBerg, and on GitHub (mirrored).