Butano: modern C++ on hardware that predates shared_ptr

Modern C++ concepts on a 2001 handheld

Butano is a modern C++ high level engine for the Game Boy Advance, and the interesting part of that sentence is the tension between the two halves.

The convenience claim is specific: create and display sprites, backgrounds, text, raster effects and more with only one line of C++ code. That is the pitch any engine makes, but on a Game Boy Advance it means something different, because the hardware has none of the conveniences a desktop language assumes.

The design decisions underneath are what make it more than a wrapper. The engine is based on modern C++ concepts like shared ownership and RAII, so objects clean up themselves and lifetimes are handled by the type system. Custom standard library without heap allocations nor exceptions, based on ETL, is the constraint that shapes everything else. Pool containers come from ETL as well, which is how you get dynamic-feeling containers without a general heap.

Put those together and you get an engine where the language you use at your call site looks like modern C++ and the machinery underneath is static allocation, which is what the hardware requires. A developer coming from desktop C++ can read Butano's examples without learning a different mental model, and that is not a small thing when the alternative is a hardware abstraction layer written as a set of C functions.

Unique type ID generation without RTTI is provided by CTTI, which is a specific and telling detail: you get type identification for serialisation-style needs without paying for runtime type information the platform does not provide.

The repository is not archived, the last push was on 2026-10-15, and the licence is zlib, which is short and permissive.

Two toolchains, and the platforms are host platforms

Butano is built on top of devkitARM or the Wonderful Toolchain, and the supported platforms are Windows, macOS and Unix-like systems.

That sentence is easy to misread, so it is worth being precise. The listed platforms are the platforms you can build the game on, not the platforms the game runs on. The output is a Game Boy Advance binary either way. Anyone expecting a portable engine will find nothing portable here, and that is not a criticism: the target is fixed and the abstraction stops there.

Two toolchains rather than one is a real choice. devkitARM is the long-established DevKitPro toolchain, and the Wonderful Toolchain is a different implementation of the same job. Having both supported means you are not locked into one vendor's build system, and it is also a maintenance cost the project carries.

The README does not give the installation commands. It points to a download, install and start using Butano guide in the documentation, which is the correct call for a tool whose setup involves a toolchain, a project template and asset tooling. If you are evaluating this, that guide is where the actual steps are and the README will not get you there.

What the README does give is the intended path afterwards: play with the examples, since they cover most of what the engine offers, then learn how to import your own assets, then read the FAQ, which it says answers most of the initial questions. That ordering is deliberate and sensible, because the examples are the documentation for a system where the unit of knowledge is a subsystem rather than a function.

For what changed recently, the README directs you to a changelog in the documentation rather than summarising it. With releases numbered like 21.7.1, 21.8.0 and 21.9.0, the numbering is calendar-based and the changelog is where you find out what a given upgrade actually did.

The third-party list explains most of the engine's shape

The README credits its dependencies by function, and reading it as a list of capabilities is more informative than reading it as a credits page.

Hardware access is shared out among four projects: Tonclib, the Universal GBA Library, agbabi and stdgba. Two independent GBA homebrew ecosystems contributing here is a good sign, since it means Butano is not tied to one person's hardware layer.

Audio support comes from Maxmod, the Apex Audio System, GBT Player and advgm. That is a lot of options for one subsystem, and it suggests audio is a place where the hardware imposes real constraints.

Then the small, specific pieces, which are the ones that tell you what a GBA engine actually needs. Fast number to string conversion from posprintf, because integer formatting is slow when you have a small CPU. Fast math routines from gba-modern and the Universal GBA Library. Fast decompression from the Cult-of-GBA BIOS. Multiplayer support from gba-link-connection. Pool containers from ETL. A stateless random number generator from whisky. Cohen-Sutherland line clipping from scivision.

Each of those is a problem a desktop developer never thinks about and a GBA developer cannot avoid. Decompression is on the list because sprite and audio data has to fit in a cartridge and be expanded at runtime. Line clipping is on the list because drawing primitives have to be clipped against a screen. A stateless random number generator is there because a game may need randomness without a source of entropy.

The documentation directory and the examples directory are large: examples exist for affine backgrounds, blending, cameras, date and time, DMG audio, direct bitmap backgrounds, dynamic backgrounds, DMA-driven backgrounds and palettes, HDMA, keypad input, link cable, logging, map collision, mode 7, mosaic, palette manipulation, polygons, and more. Each of those is a GBA hardware feature that needed a usable interface.

Multiple development tools are built in rather than bolted on: asserts, emulator logging and code profiling. On a console target where you may not have a debugger, asserts and a profiler are the difference between shipping and guessing.

Two complete games are the documentation that counts

Butano ships two full games with their source, and for an engine this is the most useful thing in the repository.

Butano Fighter is a shoot-em-up, described as staying alive while shooting at everything that moves. Its full source code and creative commons assets are in the project's own folder in the repository, and the latest ROM is published on itch.io.

Varooom 3D is the more interesting one technically, and the README's description of it, an action-packed game with 60FPS 3D technology and 3D glasses not included, should be read with the engine's feature list in mind. A mode 7 example is one directory in the examples tree, and a full game built on mode 7 is a completely different claim from an example that draws a scrolling background.

Two games in one engine also means two styles of code to compare. Where the examples show you how to call an API, a game shows you how that API behaves when you have to structure a whole program around it, including the decisions the engine does not make for you.

The rest of the community evidence is a list of games made with Butano, linked on itch.io: GBA Microjam '23, a spooky microgame collection made by members of the gbadev.net community, Demons of Asteborg DX, described as a GBA remake of a Mega Drive game, BeatBeast, a rhythmic world, Discrete Orange, a turn-based puzzle-platformer with discrete movement, Feline, an exploration game whose working source code is linked on GitHub, A Betty and Claude Cartoon, and Symbol Merged.

Feline matters more than the others for an engine evaluation, because its source is available. The rest are links, but the README also links a public Feline source tree under the same GValiente account.

The repository structure supports the same idea: `games/`, `examples/`, `butano/` for the engine itself, `template/` for a starting project, `tests/` and `docs/`.

What the zlib licence covers and what it does not

The licensing is stated in three layers, and the distinction matters more than usual for an engine with this many dependencies.

Butano itself is under the zlib licence, with details in the LICENSE file at the root. The zlib licence permits use, modification and distribution, including in closed-source products. It prohibits misrepresenting the software’s origin, requires altered source versions to be marked, and preserves the notice in source distributions; product documentation attribution is appreciated but not required. The software is provided without a warranty. For an engine, that is about as unrestricted a grant as you will find, and it means there is no reason a commercial GBA game cannot use it.

Third-party libraries are licensed under other licences, with details in a `licenses` folder in the repository. This is where the real terms live, because the dependency list is long and the licences are not uniform. The engine's permissiveness does not automatically extend to what it vendors.

Assets are a third layer with the same warning. Assets used in games, examples and other projects are licensed under other licences, with details in `credits` folders. The Butano Fighter and Varooom 3D assets are described as creative commons, and other games in the community list will have their own terms.

The practical consequence for a team is that the check you need to do is not on Butano but on the `licenses` folder and on the `credits` folders of any asset you take. This is the ordinary state of affairs for a project built on a dozen other people's libraries, but it is worth doing deliberately rather than assuming the root licence answers it.

The engine's own defaults are also worth restating in a licence context: no heap allocation and no exceptions means your game's failure modes are visible in its types and its asserts, which is a design choice that costs you dynamic flexibility and buys you a program whose memory use you can reason about on a constrained device.

Editorial conclusion

Butano suits someone who wants to write GBA software in ordinary modern C++ rather than in C with manual memory, and who is willing to accept the GBA's constraints as fixed. Do not adopt it if you need dynamic allocation, exceptions or a general-purpose standard library, since the custom library excludes them by design, and do not treat it as portable to other targets, because the supported platforms named are host platforms for the build, not targets for the game. Verify first that you have devkitARM or Wonderful Toolchain available, since the engine is built on one of them, that you follow the documented download and install guide rather than building from source blind, and that the version you take matches the changelog entry you rely on, since releases are frequent and follow a calendar-style scheme.

Frequently asked questions

Official sources

1. GValiente/butano on GitHub
2. Issues
3. License: Zlib
4. README
5. Releases