Top Five Mistakes for First Time GB Studio Users

Every piece of software has a learning curve. Some may be very steep, forcing you to absorb a lot before you can really dive into using it. Some, like GB Studio, have a fairly shallow curve, allowing a lot of people to dive right in and start creating. However, even with a user-friendly interface, there are common mistakes that befall beginners when using GB Studio. Here’s some of those mistakes to avoid if you’re just starting out. Checking these out beforehand will hopefully make your experience with the software more enjoyable.

Not Reading The Docs

GB Studio has a really awesome interface. Almost all the information about the software is provided to the user through the program itself with tool tips and warnings, but there’s still a lot of important aspects that need to be known about it before getting started with a project. It can be really tempting to just hit the ground running and start building your game, but chances are you will hit a snag when it comes to a specific detail, some are listed below. Software Documentation in general can be a slog to read through sometimes, but GB Studio has one of the best setup docs out there, broken up into the different areas of development quite well. I read through the entire documentation before I started playing with the software and it was quite advantageous.

It’s a great idea to give the docs at least a brief overview before starting to build a game. The documentation for GB Studio’s 2.0 Beta did not see an official release, and it may not happen due to development moving to 3.0 now, but you can still find an incomplete set of docs that goes over many of the new tools and features (like what the background size limits are) here: https://develop.gbstudio.dev/docs/ – we’ve listed this at the top of our Resources page for easy reference in the future.

Note: Viewing the docs is much better in a desktop browser thanks to the navigation sidebar.

Not Running The Latest Beta

This one could be a bit controversial. Beta builds are supposed to be software that’s in development and not fully released. They can have bugs and potentially leave you dissatisfied with a product, but GB Studio is different. GB Studio’s 2.0 Beta is actually quite stable and has lots of quality of life features and bug fixes that will make development easier compared to the latest official release of 1.2.1. Things like increased background size, a redesigned layout/UI, better music implementation (less slow down), and more triggers are super advantageous to have at your disposal even if you ignore all the color enhancements. What isn’t so obvious is that while GB Studio’s official Itch page hosts what is known as the 2.0 Beta 4 build, there is another more recent build, Beta 5, available through GitHub.

Beta 5 has a series of fixes that resolve many issues people were having with behaviour in game and introduces a new UI. Having Scenes, Custom Events and Variables listed in a sidebar is really handy to have when building your game, and little tweaks like Text previews are very nice. You can get the latest Beta for 2.0 here: https://github.com/chrismaltby/gb-studio/tree/v2beta#beta-builds – This will likely be the last build of 2.0 as development is now active on 3.0.

If you don’t see “beta5” in the “About” window, you’re missing out.

Not Using The Correct Colors

This personally tripped me up the first time I tried using GB Studio. The Game Boy uses 2-Bit Per Pixel color depth, which translates to 4 colors: White, Light Green, Dark Green and Black (technically they are all shades of Green, but we’ll use White and Black for simplicity). Backgrounds in any Game Boy game are able to use all four of these colors, but Sprites can only use 3 if they are to have transparency, and pretty much every sprite will have transparency. When developing with traditional Game Boy development tools, you can determine which of the 4 colors gets used to represent transparency, but with GB Studio you can’t. Sprites cannot show “Dark Green”, and instead use a “Bright Green” to determine what parts of the graphic are transparent (think Green Screens).

If you don’t take this into account when you start out, you may include colors in your sprite sheets that won’t render as you expect when you compile your game. In 3.0, the new meta-sprite tools will allow for 4 color sprites and you’ll be able to split sprites apart, but until then this continues to be a common problem seen for first time developers. Luckily, the docs have premade palettes to help you out. Check out these specific pages for more info: https://www.gbstudio.dev/docs/sprites/ and https://www.gbstudio.dev/docs/backgrounds/

I literally screenshot these from the docs – have you read them yet?

Mixing Local and Global Variables

This one can really creep up on you if you’re not aware of how variables work in GB Studio. GB Studio offers 512 Global Variables that can be accessed from anywhere in game. There are also 8 unique Local Variables that are available for every Scene and every Actor within your game in GB Studio 2.0. These Local Variables are great for tracking things like opened chests and dialogue with characters, but they are not accessible from any scripts or events outside of those specific Actors or Scenes.

The easiest way to avoid confusion is to commit to only using Global Variables, which for a while was the only option available anyways. If you’re having issues with one of your scripts, make sure to check which variables you are comparing, chances are you may have mixed up one of these by accident. Also, we wrote a Basics article on Variables, so that should help.

Getting Too Ambitious

Being introduced to GB Studio can be extremely freeing. Perhaps you have had this amazing idea for a game, and you want to try and implement every aspect of it. The problem is that unless you are an experienced game developer, it can be difficult to gauge exactly what can and can’t be done. It’s a really good idea to keep things super simple for your first game, or possibly just trying to build parts of it to test and see if it’s possible. We wrote a whole article about what to consider for your first game, and that mentality sticks true.


There are still many areas that can cause challenges for those both working with GB Studio for the first time and veterans alike. If you have something you need help figuring out, the community is super helpful and will often work with you to get to your goals. Check out the GB Studio Discord or SubReddit for great resources and awesome people.