<center>
 <a href="https://buymeacoffee.com/breadcodes" target="_blank">
 <img src="/assets/buymeacoffee.png" alt="Buy Me A Coffee" style="width: 200px;" />
 </a>
</center>

## Editor FAQ

### I don't see error squiggles or IntelliSense in my C++ files

#### Visual Studio Code IntelliSense Setup

Make sure you have the C/C++ extension installed from Microsoft. You can find it in the Extensions Marketplace by searching for "C/C++". 
![C/C++ Extension](https://code.visualstudio.com/assets/docs/languages/cpp/cpp-extension.png) 
(source: [Visual Studio Code Documentation](https://code.visualstudio.com/docs/languages/cpp))

#### Zed Editor IntelliSense Setup

C/C++ IntelliSense is supported natively in Zed Editor. Ensure that your paths match your setup in the `.clangd` file.

The configuration I included in the `.clangd` file is for Linux and macOS. If you're using Windows, you may need to adjust the paths accordingly.

## Chapter Overview

###### ButanoSeriesNav "1.1","1.1"

---
---

### 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.

[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/ctGSNxRkg2)

#### Reddit

[r/Homebrew](https://www.reddit.com/r/Homebrew/) - A general homebrew community for all consoles.
[r/RetroGameDev](https://www.reddit.com/r/RetroGameDev/) - A community for retro game development, including homebrew.

#### BSky

[@Bread.Codes](https://bsky.app/profile/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](https://opencollective.com/gbadev) for GBADev! Your donations help fund events like [GBAGameJam](https://itch.io/jam/gbagamejam) and support the work of volunteers who create tools and resources for the community.

[![OpenCollective](https://img.shields.io/badge/Support-GBADev-blue?style=for-the-badge&logo=opencollective&logoColor=white)](https://opencollective.com/gbadev)


---

### Support the Series

<center>
 <a href="https://buymeacoffee.com/breadcodes" target="_blank">
 <img src="/assets/buymeacoffee.png" alt="Buy Me A Coffee" style="width: 200px;" />
 </a>
</center>

---

### License

This series is licensed under a [Creative Commons Attribution-NonCommercial 4.0 International License](https://creativecommons.org/licenses/by-nc/4.0/).

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](https://opensource.org/licenses/MIT) 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](https://codeberg.org/breadcodes/butano-tutorial-series), and on [GitHub](https://github.com/breadbored/butano-tutorial-series) (mirrored).

<center>
 <a href="https://buymeacoffee.com/breadcodes" target="_blank">
 <img src="/assets/buymeacoffee.png" alt="Buy Me A Coffee" style="width: 200px;" />
 </a>
</center>

## Preface

Welcome to my tutorial series on Butano, a modern C++ high-level engine for Game Boy Advance homebrew development. This will begin with introductions, then getting our environment setup, and then we will move into building a simple game over the course of several chapters.

If you'd like to skip introductions and get straight to the setup, you can jump to [Chapter 1](/posts/butano-series-1).

### About Me

My name is Brad, aka "Bread" (as the baristas at coffee shops often call me). I am a hobbyist of many things. Professionally I am a Lead Data Engineer, though most of my experience was in Backend Software Engineering and Database Administration. My favorite language overall is SQL, because I love data transformation and declarative puzzles. My favorite imperative language is probably Rust, though there's such a small gap between Rust and C++ that it's hard to say definitively.

18 years ago I was gifted Mario Galaxy for the Nintendo Wii, and I was so blown away by the physics of a planetary system that 11 year old me wanted ***nothing*** more than to do that myself. Not just on PC, but on the Wii itself. I remember the day I published my first project for PC: March 14th 2009. My goal was always homebrew for consoles, but I wouldn't start seriously pursing that as my primary hobby until around COVID-19 in 2020.

### Intended Audience

While I will try to keep things as beginner-friendly as possible, I will be writing for an audience that has at least a basic understanding of C++ and minimal game development concepts. Butano is less of a game engine and more of a framework for asset management. As you'll come to find in this series, Butano simplifies most - but not all - aspects of developing a game for the Game Boy Advance.

This is intended for people who are interested in the hobby and it is supposed to be a fun use of your time. This series is for people who are driven by the high of making cool stuff.

Game Dev - and especially Homebrew Game Dev - is largely art, so I want to make this clear sooner rather than later: the use of GenAI tools is discouraged. I know people - including myself - are opinionated on the subject. The use of GenAI is not allowed in GBA Game Jams, and I feel that this is a good standard to uphold for learning and hobby purposes. Not only is this supposed to be fun, but copyright infringement is a valid concern for artists.

### What We Will Be Building

Over the course of this series, we will be building a simple puzzle game based on [Klotski](https://en.wikipedia.org/wiki/Klotski), which is often referred to as "sliding block puzzle." The goal of the game is to move - as I call it - "inconveniently" arranged rectangular blocks, which impede each other's paths, to free the target block. I recommend [this video](https://www.youtube.com/watch?v=YGLNyHd2w10) about Klotski for a handful of reasons, only one of which is relevant to this series (how the game works). This game will lay a great foundation for understanding Butano's core features, game loops, entity management, collision, and other game development concepts. For Butano specifically, we'll cover the following major features:

- Sprites
 - Regular
 - Affine
 - Fonts
- Backgrounds
 - Regular
 - Affine
 - Tiles
- Inputs
- Audio
 - Music
 - Sound Effects

### Chapter Overview

###### ButanoSeriesNav 0

---

### 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.

[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/ctGSNxRkg2)

#### Reddit

[r/Homebrew](https://www.reddit.com/r/Homebrew/) - A general homebrew community for all consoles.
[r/RetroGameDev](https://www.reddit.com/r/RetroGameDev/) - A community for retro game development, including homebrew.

#### BSky

[@Bread.Codes](https://bsky.app/profile/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](https://opencollective.com/gbadev) for GBADev! Your donations help fund events like [GBAGameJam](https://itch.io/jam/gbagamejam) and support the work of volunteers who create tools and resources for the community.

[![OpenCollective](https://img.shields.io/badge/Support-GBADev-blue?style=for-the-badge&logo=opencollective&logoColor=white)](https://opencollective.com/gbadev)


---

### Support the Series

<center>
 <a href="https://buymeacoffee.com/breadcodes" target="_blank">
 <img src="/assets/buymeacoffee.png" alt="Buy Me A Coffee" style="width: 200px;" />
 </a>
</center>

---

### License

This series is licensed under a [Creative Commons Attribution-NonCommercial 4.0 International License](https://creativecommons.org/licenses/by-nc/4.0/).

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](https://opensource.org/licenses/MIT) 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](https://codeberg.org/breadcodes/butano-tutorial-series), and on [GitHub](https://github.com/breadbored/butano-tutorial-series) (mirrored).

Butano Series

Introductions and Overview

<center>
 <a href="https://buymeacoffee.com/breadcodes" target="_blank">
 <img src="/assets/buymeacoffee.png" alt="Buy Me A Coffee" style="width: 200px;" />
 </a>
</center>

## 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](https://chocolatey.org/install), a package manager for Windows.
 - Install by following the instructions on the [Chocolatey installation page](https://chocolatey.org/install).
- MacOS: [Homebrew](https://brew.sh/), 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](https://devkitpro.org/wiki/Getting_Started), our toolchain for building GBA homebrew
 - Install by following the instructions on the [DevKitPro Getting Started page](https://devkitpro.org/wiki/Getting_Started).
 - During installation, make sure to select the `gba-dev` package from the list.
- [Git for Windows](https://gitforwindows.org/), for version control and Git-Bash terminal
- [Python](https://www.python.org/downloads/windows/), for running various scripts
 - I am using [3.12](https://www.python.org/downloads/release/python-31212/) for this series
- [Make](https://www.gnu.org/software/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](https://chocolatey.org/) with `choco install make`.

##### MacOS

- [DevKitPro](https://devkitpro.org/wiki/Getting_Started), our toolchain for building GBA homebrew
 - Install by following the instructions on the [DevKitPro Getting Started page](https://devkitpro.org/wiki/Getting_Started).
 - After installation of the DevKitPro base system, run `dkp-pacman -S gba-dev` to install the `gba-dev` package.
- [pyenv](https://github.com/pyenv/pyenv) preferably for a Python version manager, or install Python via [Homebrew](https://brew.sh/)
 - 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](https://www.gnu.org/software/make/), a build automation tool
 - Included with Xcode Command Line Tools (`xcode-select --install`)
- `git`, for version control
 - Install via [Homebrew](https://brew.sh/) with `brew install git`

##### Linux

- [DevKitPro](https://devkitpro.org/wiki/Getting_Started), our toolchain for building GBA homebrew
 - Install by following the instructions on the [DevKitPro Getting Started page](https://devkitpro.org/wiki/Getting_Started).
 - 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](https://www.python.org/downloads/), for running various scripts
 - Install via your package manager, e.g. `sudo apt install python3` on Debian-based systems
- [Make](https://www.gnu.org/software/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](https://mgba.io/downloads.html), 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.

<details>

<summary>If you're interested in alternatives to all these tools, click here!</summary>

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

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

</details>

##### 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](https://code.visualstudio.com/)|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](https://zed.dev/)|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.|

<details>

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

|**Editor**|**Pros**|**Cons**|**Notes**|
|:---:|:---:|:---:|:---:|
|[CLion](https://www.jetbrains.com/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](https://visualstudio.microsoft.com/)|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](https://neovim.io/)|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|

</details>

#### Art Tools

\* What we will be using in this series.

- Visual Asset Options:
 - [Aseprite (paid)](https://www.aseprite.org/)\*, 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)](https://github.com/aseprite/aseprite/releases), the open source version of Aseprite that you can compile yourself.
 - Lacks some features of the paid version, but still very capable.
 - [GIMP](https://www.gimp.org/), a free and open source image editor.
 - More general-purpose than Aseprite, but can be used for pixel art as well.
 - [Krita](https://krita.org/en/), another free and open source image editor.
 - Also more general-purpose, but has good support for pixel art.

- Audio Assets Options:
 - [OpenMPT](https://openmpt.org/)\*, 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](https://brew.sh/) 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](https://tildearrow.org/furnace/), 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:

```bash
# 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:

```text
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.

```bash
cd chapter-1-getting-started
```

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

```bash
make
```

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

```bash
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

###### ButanoSeriesNav "1","1"

---
---

### 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.

[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/ctGSNxRkg2)

#### Reddit

[r/Homebrew](https://www.reddit.com/r/Homebrew/) - A general homebrew community for all consoles.
[r/RetroGameDev](https://www.reddit.com/r/RetroGameDev/) - A community for retro game development, including homebrew.

#### BSky

[@Bread.Codes](https://bsky.app/profile/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](https://opencollective.com/gbadev) for GBADev! Your donations help fund events like [GBAGameJam](https://itch.io/jam/gbagamejam) and support the work of volunteers who create tools and resources for the community.

[![OpenCollective](https://img.shields.io/badge/Support-GBADev-blue?style=for-the-badge&logo=opencollective&logoColor=white)](https://opencollective.com/gbadev)


---

## Support the Series

<center>
 <a href="https://buymeacoffee.com/breadcodes" target="_blank">
 <img src="/assets/buymeacoffee.png" alt="Buy Me A Coffee" style="width: 200px;" />
 </a>
</center>

---

### License

This series is licensed under a [Creative Commons Attribution-NonCommercial 4.0 International License](https://creativecommons.org/licenses/by-nc/4.0/).

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](https://opensource.org/licenses/MIT) 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](https://codeberg.org/breadcodes/butano-tutorial-series), and on [GitHub](https://github.com/breadbored/butano-tutorial-series) (mirrored).

Setting Up Your Development Environment

Environment FAQ

<center>
 <a href="https://buymeacoffee.com/breadcodes" target="_blank">
 <img src="/assets/buymeacoffee.png" alt="Buy Me A Coffee" style="width: 200px;" />
 </a>
</center>

## Assets in Aseprite

My program of choice for creating pixel art is [Aseprite](https://www.aseprite.org/). It is a fantastic tool with a lot of features specifically geared towards pixel art and animation. If you don't have it yet, you can purchase it from the official website or from [Steam](https://store.steampowered.com/app/431730/Aseprite/).

In the root of the repository, you will find the file `raw-assets/klotski_blocks.aseprite` which contains the sprite we will be using in this chapter. You can open this file in Aseprite to view and edit the sprite.

## Adding the Sprite to Our Project

Butano expects a specific Bitamp format and a JSON metadata file for each sprite to be added to the `graphics/` directory of the project. However, I have provided a Python script to automate the conversion process from a PNG sprite sheet to the required format, with the necessary metadata.

You can add your PNG sprite sheet to the `sprites/` directory of your chapter, and any time you run `make` in the terminal, the script will automatically convert the PNG to the required format and place it in the `graphics/` directory, which then can be used in the Butano project.

To add the sprite to our project, follow these steps:

1. Open the Klotski Blocks Aseprite file located at `raw-assets/klotski_blocks.aseprite`
2. You will see multiple frames in the timeline at the bottom. Each frame represents a different block in the Klotski puzzle.
3. You can export as a Sprite Sheet by going to `File > Export Sprite Sheet`, or using the shortcut `Ctrl + E` (or `Cmd + E` on Mac).
4. In the Export Sprite Sheet dialog, set the following options:
 - Layout
 - Sheet Type: By Columns (this is important because all sprites ***must*** be 1 tile wide and any number of rows tall)
 - Constraints: None
 - Output
 - File: `<chapter-directory>/sprites/klotski_blocks.png`
 - replace `<chapter-directory>` with the actual path to your chapter directory
 - Make sure to set the file extension to `.png`
 - Do not include any spaces or special characters in the file name. Only use letters and underscores (or numbers, as long as the file name does not start with a number).
 - Click Export to generate the sprite sheet.
5. Now, when you run `make` in the terminal while in your chapter directory, the script will convert the PNG sprite sheet to the required Butano format and place it in the `graphics/` directory. This also makes your sprite available for use in the Butano project.

## Using the Sprite in Butano

Now that we have our sprite in the correct format, we can use it in our Butano project!

It is time to open your code editor (IDE) of choice. In your IDE, open the folder of your chapter (e.g., `chapter-1-getting-started/` if you are following along, or `chapter-2-sprites/` for referencing this chapter's code). You should now see the hierarchy of the project in your IDE's file explorer.

### Visual Studio Code

![VS Code Explorer](/assets/butano/chapter-2/vscode.png)

### Zed Editor

![Zed Editor Explorer](/assets/butano/chapter-2/zed.png)

### Adding the Sprite to main.cpp

You will find the `main.cpp` file in the `src/` directory of your chapter. For now, this is where we will be adding our code to use the sprite. In later chapters, the `main.cpp` file will act as an entrypoint rather than a master file with all our code, but for now, it is fine to keep everything here.

Before we move on, make sure you've run `make` in the terminal to ensure that the sprite has been converted and is available to Butano. You can confirm the Bitmap and JSON files exist in the `graphics/` directory of your chapter. If not, please revisit the previous section to ensure the sprite was exported and converted correctly.

In `main.cpp`, we will need to import the sprite header file generated by Butano. At the top of the file, add the following include statement:

```cpp
#include "bn_sprite_items_klotski_blocks.h"
```

This gives us access to the sprite data in this file. Inside the `main()` function, **before** the `while (true)` line, add the following code:

```cpp
bn::sprite_item block_sprite_item = bn::sprite_items::klotski_blocks;
```

If your editor is configured correctly with the C++ language server, you should see an error here (see [Chapter 1.1](/series/butano/1.1#i-don-t-see-error-squiggles-or-intellisense-in-my-c---files) for the editor FAQ). The error is saying that `bn::sprite_item` is an incomplete type. This is because we need to include the appropriate Butano header file for sprites. At the top of the file, add the following include statement:

```cpp
#include "bn_sprite_item.h"
```

This will resolve the error! You'll notice this pattern a lot if you are new to writing code. Whenever you see an error about an incomplete type, it usually means you need to include the appropriate header file for that type.

Now, we can create a sprite instance using the sprite item we just created. Immediately below the line where we created the `block_sprite_item`, add the following code:

```cpp
bn::sprite_ptr block_sprite = bn::sprite_items::klotski_blocks.create_sprite(0, 48);
```

Oh no! Another error! We know what to do here. We need to include the header file for `bn::sprite_ptr`. Add the following include statement in the usual place at the top of the file:

```cpp
#include "bn_sprite_ptr.h"
```

At this point, we now have a pointer (aka `ptr`) which points to the sprite we created, using our Klotski blocks sprite item. The `create_sprite(0, 48)` function creates the sprite at the coordinates (0, 48) on the screen. In Butano, the origin (0, 0) is at the center of the screen. This is typical for graphics programming. The top left is (-120, -80) and the bottom right is (120, 80) for the GBA's 240x160 resolution. This means that (0, 48) is centered horizontally and 48 pixels down from the center vertically, so it is at the bottom-center of the screen.

You should now be able to build and then run your code!

```bash
make
make run
```

You should now see one of the Klotski blocks in the bottom-center of the screen!

### Manipulating the Sprite

Now that we have our sprite on the screen, let's manipulate it a bit. We will be moving the sprite and changing the frame it is displaying. Let's do this by showing all variations of the block in a loop.

Remove the two lines of code you added with the sprite item and sprite pointer. Instead, add the following code **before** the `while (true)` line in the `main()` function:

```cpp
// To manage multiple pointers, we put them in a vector (a list)
bn::vector<bn::sprite_ptr, 5> block_list; // this is a list that can hold up to 5 sprite pointers

// Loop to create and configure each block sprite
for (int sprite_index = 0; sprite_index < block_list.max_size(); sprite_index++) {

 // I want to arrange the blocks in a row centered on the screen,
 // so I need to calculate the adjusted x position for each block.
 // The range is from `-(number_of_blocks / 2)` to `+(number_of_blocks / 2)`,
 // so I calculate half the size of the list to use as an offset.
 const u8 half_size = block_list.max_size() / 2;
 const s8 adjusted_x_position = -half_size + sprite_index;

 // create a new block in the list
 block_list.push_back( // `push_back` is how we add a new item to the end of the list
 block_sprite_item.create_sprite( // this is the function we called earlier to create a sprite pointer
 adjusted_x_position * 40, // we multiply by 40 to space the blocks out nicely
 48 // y position remains the same as before
 )
 );

 // To set the frame of the sprite we want to display,
 // we tell the sprite to use the tile at `sprite_index`
 block_list.at(sprite_index).set_tiles(
 block_sprite_item.tiles_item().create_tiles(sprite_index)
 );
}
```

Once you tun `make` and `make run` again, you should see all 5 Klotski block variations arranged in a row at the bottom of the screen.

#### Brief Intro to Game Loops

We will be covering Game Loops in more detail in the next chapter, but for now, think of it like this:

```cpp
// `while (condition)` is a loop that runs as long as `condition` is true
while (true) { // this loop will run forever because `true` is always true

 // Every time this runs, I will be referring to it as a "frame"
 // The GBA runs at slightly less than 60 frames per second (~59.7fps)
 // This means that this loop runs about 60 times every second

 bn::core::update(); // this function tells butano we are ready to render the frame
}
```

To manipulate our sprites over time, we will add code inside this loop. Let's try changing the position of each block to create a waving movement animation. The simplest way I know how to do this is to use a sine wave function. Replace your current `while` Game Loop with the following code:

```cpp
// add these includes to the top of the file
#include "bn_math.h"
#include "bn_fixed.h"

// ... inside main() function ...

// Frames don't "know" about data defined in previous frames.
// This has to do with scopes, which we will cover in the next chapter as well.
// For now, just know we must define `wave` outside of the loop to keep track of its value.
bn::fixed wave = 0;

while (true) {
 // Loop through each block in the list
 for (u16 i = 0; i < block_list.size(); i++) {
 auto fit = block_list.at(i); // Get the sprite at position `i` in the list
 wave += bn::fixed(0.0025); // Increment the wave value slightly each frame
 const auto h = bn::sin(wave + (bn::fixed(0.05) * i)); // Calculate the sine value for this block
 fit.set_y(48 + (h * 5)); // Set the y position based on the sine value
 }

 // Update Butano to render the frame
 bn::core::update();
}
```

Now with a little `make` & `make run`, you should see the blocks gently waving up and down at the bottom of the screen!

#### Manipulating Text Sprites

You may notice the text that still says "Chapter 1" and "Getting Started" at the top of the screen. This is because we haven't modified the text sprites that were created in Chapter 1. Much like our list of block sprites, text is typically stored in a list of sprite pointers, where each character has a pointer in the list.

We can change the text by simply changing the value in the following strings:

```cpp
bn::string<15> title_message_string = "Getting Started";
// ...
bn::vector<bn::sprite_ptr, 15> title_message_sprites;
// ...
bn::string<9> subtitle_message_string = "Chapter 1";
// ...
bn::vector<bn::sprite_ptr, 9> subtitle_message_sprites;
```

You may notice the `15` & `9` in the angle brackets (`<` & `>`). This indicates the maximum length of the string and the list of sprites. If you try to set a string longer than this length, you will get an error. You can increase these values if you want to use longer strings. The same applies to the list of sprite pointers for the text sprites. Keep in mind that the GBA has limited memory and a limited number of sprites that can be rendered (128), so using excessively long strings and lists will become problematic.

I will be changing the above lines to the following to reflect that we are now in Chapter 2:

```cpp
bn::string<7> title_message_string = "Sprites"; // changed from 15 to 7
// ...
bn::vector<bn::sprite_ptr, 7> title_message_sprites; // changed from 15 to 7
// ...
bn::string<9> subtitle_message_string = "Chapter 2"; // changed from "Chapter 1" to "Chapter 2"
// ...
bn::vector<bn::sprite_ptr, 9> subtitle_message_sprites;
```

## Conclusion

Congratulations on completing this chapter! You have successfully created and imported a sprite into Butano, and manipulated it in various ways. In the next chapter, we will explore how to handle user input to move the blocks around the screen.

## Chapter Overview

###### ButanoSeriesNav "2","2"

---
---

### 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.

[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/ctGSNxRkg2)

#### Reddit

[r/Homebrew](https://www.reddit.com/r/Homebrew/) - A general homebrew community for all consoles.
[r/RetroGameDev](https://www.reddit.com/r/RetroGameDev/) - A community for retro game development, including homebrew.

#### BSky

[@Bread.Codes](https://bsky.app/profile/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](https://opencollective.com/gbadev) for GBADev! Your donations help fund events like [GBAGameJam](https://itch.io/jam/gbagamejam) and support the work of volunteers who create tools and resources for the community.

[![OpenCollective](https://img.shields.io/badge/Support-GBADev-blue?style=for-the-badge&logo=opencollective&logoColor=white)](https://opencollective.com/gbadev)


---

## Support the Series

<center>
 <a href="https://buymeacoffee.com/breadcodes" target="_blank">
 <img src="/assets/buymeacoffee.png" alt="Buy Me A Coffee" style="width: 200px;" />
 </a>
</center>

---

### License

This series is licensed under a [Creative Commons Attribution-NonCommercial 4.0 International License](https://creativecommons.org/licenses/by-nc/4.0/).

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](https://opensource.org/licenses/MIT) 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](https://codeberg.org/breadcodes/butano-tutorial-series), and on [GitHub](https://github.com/breadbored/butano-tutorial-series) (mirrored).

bread.codes

code stuff

Chapter 1.1

Environment FAQ

Editor FAQ#

I don't see error squiggles or IntelliSense in my C++ files#

Visual Studio Code IntelliSense Setup#

Zed Editor IntelliSense Setup#

Chapter Overview#

Communities#

Discord#

Reddit#

BSky#

Support the Community#

Support the Series#

License#

Additional Information#