Modifying the GB Studio Engine

Let’s say there’s this feature that you really want to add but can’t because the engine doesn’t allow you to do it natively. Should you just drop that idea and not speak about it ever again? Well, have you considered modifying the engine to support that idea? Let me explain:

One of the cool features that GB Studio 2.0 supports is exporting the engine (it was in the trailer, after all)! For less tech-savvy users, this might sound like nonsense, “what’s this about exporting the engine? What is it for? Is it even useful?”

It can be extremely useful to those who are adventurous enough. You can modify the inner workings of the engine that makes your game work and customize it to an extent. You can change the physics (if you’re using a version prior to 2.5), you modify certain settings, you can even hide fading between scenes. You can explore many things that are beyond the scope of GB Studio, provided you know at least a bit of C and ASM.

That sounds cool, but… how do you do it? How do you export the engine in the first place?

Load up your game, and in the top-left corner, click Game > Advanced > Eject Engine.

Just click “Eject.”

After that’s done, there should be a new directory in the assets folder titled “engine.” This is what you just ejected. Open it, there should be a bunch of folders and files inside them.

The root of the engine folder.

Congratulations – you just ejected the engine! Now you can toy around with the files that make up your project. But first, let me explain what these two folders and this one .json file are for.

  • The include folder is not very important, it’s full of small .h (or “header”) files that are for the other folder, which is…
  • The src folder – this one has more meat on its bones, it’s basically what powers your game. This one has a lot of larger .c files. Pretty important and powerful stuff – make sure you handle this with care.
  • The engine.json file contains the version of the engine and the settings and fields that the game uses. Stuff like fading style, platformer physics, and other settings are included here. You might want to check this one out too.

In case you don’t want to change anything yourself because it’s too intimidating, you can find engine mods in the official Discord server. There’s a channel for this purpose, #plugins-help. Check the pinned messages for download links.

The one downside of ejecting and modifying the engine is that when GB Studio 3 is eventually released, the fact that it uses a completely different engine means it won’t be backwards compatible with work done with 2.0 engine modification. If you made a 2.0 mod, you will need to port it when the next version comes out if you wish for it to remain usable (Keep in mind GB Studio 2 wasn’t officially released – it will remain beta indefinitely).

Hopefully, this article helped you understand the basics of the GB Studio 2 engine and what you can do with it. Being able to customize stuff at the “core” level is a useful feature that allows the user to do more than what they can do on stock GB Studio. Maybe you can do something incredible that nobody believes is possible. You may run the risk of having compiling issues, but nothing ventured, nothing gained. This feature was added for users to try out, so go explore.

Note: Thanks to Constatin for pointing this out – if you make a mistake and your game no longer compiles (or you simply want to undo the changes you made), you can simply delete the “engine” folder in your project and it will revert to using the stock GB Studio project engine.