Reviving Game Boy Magic with GBStudio

What I've learned, good things, and limitations of the GBStudio engine

The main picture of the post
*A screenshot from my minigame

In this article, you'll find a bit about my experience with retrogaming, why I've decided to learn how to make simple Game Boy games, an overview of the GBStudio engine, and an explanation of its limitations that I've discovered while building with it.

GBStudio is a little diamond, and I'm immensely grateful that skilled engineers put their time and knowledge into creating something unique.

A link to the GBStudio official website and its GitHub repository.

A bit of personal (skippable) background

I've spent most of my childhood playing Game Boy games and all their evolutions, first using the Pocket with Super Mario and Pokemon Red, the Color, the Advance, and the Advance SP, spending hundreds of hours playing Final Fantasy Tactics. I loved that game so much.

I remember that I was dreaming of being able to play (at that time) graphic-intensive games like Final Fantasy 7 and Final Fantasy 8 on a portable device like Game Boy.

Now in 2023, I could play demanding games on the Steam Deck or spend entire days playing Zelda on the Switch, but I still miss playing Game Boy games from time to time.

It is fascinating how game companies could fit entire stories, even entire worlds, and hours of genuine entertainment in a bunch of pixels stored on a chip that weighs less than a phone picture. Even more impressive is that there were no updates. Once the game cartridge was sold, it was it, no turning back, no fixes, no new content.

Some years ago, around 2015, while developing Android apps in my free time, I had the ambition of creating my own video game. I've made two of the most common errors possible:

  1. Wanting to do a game that was too complex to start
  2. Having no idea how to draw

So, in the end, I ended up frustrated and with nothing decent on my hands.

In 2021, I became passionate about pixel art while creating my own NFT collection to experiment with smart contracts. I've loved it for four main reasons:

  1. The amount of information per pixel is huge. A single pixel modification changes drastically the entire picture.
  2. Easier than high-resolution graphics, so even untalented graphics people like me could try and create something not utterly ugly.
  3. It reminds me of the "good old times," when I was happy seeing those few pixels moving on a screen, and my brain was filling out all the details.
  4. Little amount of pixels means a shorter time to draw them.

Some weeks ago, in 2023, I was scrolling Reddit, and suddenly I saw a post regarding retro gaming and the possibility of writing Game Boy games with an engine called GBStudio. I could not scroll further. I had to know more about it.


GBStudio is an open-source project; it gives you the possibility to create real Game Boy games and also to export them together with a web emulator to play them on the web (like I did here)

Sadly it does not provide a high-level programming language. It allows the developer to use a no-code interface or go directly low assembly-like level.

I've never been a fan of no-code or low-code platforms. I know it is a controversial take these days, so I might write a separate post about it, but I've decided to try this engine anyway.

How does it work?

It has 3 main concepts:

  1. Scenes: A "screen" of the game
  2. Actors: Whatever thing can move and change their state
  3. Triggers: Area of the game level that can have some logic attached which gets executed when the player enters that area

Limit: GBStudio can have only 20 actors per scene, but only 10 can be present in a single window (160x144px). It can also have a maximum of 10 Triggers per scene.


You can select different kinds of premade configurations like "Top Down 2D" or "Platformer" (the one that I've used), which already takes care of some things like physics.

A scene is always attached to a background image that can be bigger than the Game Boy screen. In that case, it will be like you have a camera centered on the player that moves around the scene depending on the player's position.

It might seem that 20 "movable graphical things" per scene would be more than enough, but remember that it's not only players and enemies but also every kind of UI element.

For example, let's say that you decide to have a life counter at the top of the screen:


If you would like all the letters to move, then be prepared to not have much else changing state on the screen since it will take 8 Actors just to write that, almost the maximum limit of concurrent actors on a screen.

A way to optimize this is to write "LIVES:" directly on the background image of the scene and have "1" and "3" represented by two actors, each having the possibility to display all numbers from 0 to 9. By doing that, you'll have used only 2 actors.

Limit: GBstudio accepts only 4 different specific colors for the background images


Every actor is always attached to a Sprite. A Sprite has one or more 16x16px images that can create a static image or an animation.

Sprites must be composed of rectangular images with a height of 16px and a width of a multiple of 16px. If you want to create characters that are bigger than 16px, like the characters towards the end of my minigame, you need to cut the image to 16x16px:


And then put them together in a sequence of 32x32px images to create the idle animation of the dragon:


Limit: every scene has a limit of 96 16x16px sprites on simple backgrounds and 64 on more complex backgrounds. In the above case, we already have 12 16x16px sprites, leaving us with 84 other 16x16 sprites to play with. With those sprites, we can create as many animation frames as we want. It will not impact the sprite number limit.

Limit: GBStudio accepts only three colors for Sprites and one color to indicate transparency. All those three colors will already be present in the four available colors for the background, so making your sprites stand out from the background can be challenging and requires some planning.

This last limitation was beneficial for me. Since I'm partially colorblind, having a small but very diverse color palette lets me clearly recognize the colors I have to use.

No-Code Engine

This is the main screen of GBStudio that you will look at:


You can find information about the selected element in the right column. As you can see on the right, you have a loop and an if condition. You can notice that those instructions take plenty of vertical space, so do not expect to write complex logic with this system.

Limit: the no-code editor makes writing complex and maintainable logic difficult.

The only way to sort out your logic is to create reusable scripts. You can see the list of all the scripts in the left column. A script is nothing more than a function that can be called from everywhere, and it accepts input parameters.

Limit: there is no folder structure to organize your scripts, so you'll have to play with some custom naming convention to have similar scripts close to each other

Sometimes you'll find yourself creating scripts even when not strictly necessary just to make the right column more readable.

Limit: The alternative is to write directly assembly-like code. There is nothing in between

On the left column, you can also see a section called "Variables" for each actor, trigger, or script you have:

  • 6 local variables
  • 2 temporary variables
  • 512 global variables shared with every actor, trigger, and script

Remember to name global variables well and use them only when necessary since they come in a limited number.

Melee Combat

A special mention for melee combat. I struggled with this one. There is no out-of-the-box mechanism to make your player attack with a sword. The closest thing that I've found (and also recommended around) is to create a player animation where the character attacks with a sword:


Limit: As you can see from the little light-blue box, the collision box cannot be changed during an attack, so it will be the same collision box of the idle, running, and jumping animation.

Then, create an invisible projectile with a very short lifespan to hit the enemy:


Limit: It works quite well when the horizontal velocity of the player is 0. When the player moves horizontally, the projectile has its own velocity, not the player velocity added on top of it. That makes it impossible to find a timing and speed of the projectile that will work well in every condition. I've got the impression that, when shooting the projectile while moving, the calculation for collision skips some frames from time to time, which might make the player miss the target.

Suggestion: Try to avoid melee combat in your game if you can.

If you find better methods, please reach out to me. I'll be glad to learn about them!


As said at the beginning, this engine is a little diamond that gives everyone (even not only developers to a certain extent) the possibility to create their own Game Boy game.

The documentation is detailed, straightforward, and small enough to learn the engine in hours.

The available prebaked logic functions are long enough to give you enough tools to bring something live and small enough to not feel overwhelmed by the number of possibilities.

I loved creating my minigame and mixing Super Mario, Zelda, Pokemon, and Zell's Limit Break Attacks from Final Fantasy 8.

As the melee combat is a core functionality of my minigame, and as I want to add more complex features, I'll continue this minigame in Godot and drop the Game Boy compatibility. I might come back occasionally to see what the new releases will bring and continue from there.

In short, I suggest that everyone who likes retro games should try building something with GBStudio. It's open source, it's free, and it's fun!

For any corrections or suggestions, feel free to reach out to me. I'll appreciate it a lot.

Many thanks for reading. It means a lot to me.