Introduction.
Sometimes GB Studio’s built in events and GBVM commands aren’t enough for you to realise your game’s vision. You might want to modify how the player moves or controls, or something more complicated you can’t achieve in the editor. This is where engine edits come in handy, from small tweaks to big overhauls. This guide explains how to get started with basic engine editing for modifying player movement.
You probably won't need a wrench at any stage of this process.
What is the GB Studio engine?
The engine is the underlying C code that controls everything that happens in your game, from basic player movement to scripts written in the editor. It’s written in C using GBDK libraries. The repository for the engine can be found here, although the repo is usually several commits ahead of the currently shipped GB Studio engine.
You must be comfortable working with C to continue!
While you don’t necessarily need to be a C master, you will need basic programming skills and the ability to match C syntax in the engine to modify it. Personally I only had experience with C# and other languages before jumping into the engine. This page of the GBDK docs summarises what you need to know for editing the GB Studio engine. I highly recommend reading this page up to and including Code Structure before continuing. If you understood most of what you read, you should be good to go.
You do not need to know how to use GBDK tools or compile the engine, since GB Studio handles that for you. If you want to learn about pure GBDK and carry some skills over to GB Studio, you can also check out the great tutorials over at Larold's Jubilant Junkyard.
Ejecting the engine from GB Studio.
First, choose your version of GB Studio. This guide only covers version 3.0 and up. GB Studio 3.0 and 3.1 engine edits are mostly compatible with each other. From GB Studio 3.2 and up, some of the engine structure was changed, so engine edits from 3.1 and below require modification to migrate to 3.2 and up. GB Studio 3.2 and 4.0 engine edits are also mostly compatible with each other.
In the top menu, select Game -> Advanced -> Eject Engine -> Eject. The ejected engine should automatically be opened in your file explorer.
The ejected engine can be found at Your Project/assets/engine/. You should see the folders include and src, as well as the file engine.json.
Your ejected engine should look like this.
The src folder contains three folders.
- The states folder contains the functions for each scene type, eg platformer, shmup etc. It mostly controls the player and camera behaviour for each scene type. Editing these files is very useful and relatively simple. This is where I do most of my engine edits, and what I will discuss in detail in part two of this guide.
- The core folder contains all of the core functions of the engine, such as actor and projectile behaviour. Editing these files can be very useful but is beyond the scope of this guide.
- The data folder doesn’t contain anything to edit by default and can be ignored unless you are adding to it.
The include folder contains all of the header files for the files in the src folder. They define which function and variable definitions are shared between files. You may or may not need to modify them when editing the engine.
engine.json defines a few things about your engine such as engine version and engine fields. We will come back to it when we need these things later.
Exploring engine plugins.
Some of the best resources for engine editing are engine plugins. Engine plugins are basically just edited engine files packaged in a folder. You can look through engine plugins to see how people modified the engine, or you could use them as a starting point and edit them further. If you want to make your own engine plugins from your engine edits, I plan on uploading a separate guide for that soon.
I highly recommend taking a look at the Platformer Plus plugin by Hauntology. Not only does it add a lot of great functionality to the Platformer scene, it’s also well organised and easy to read. It replaces the regular platformer code with a state machine that manages player state. It’s a great base for your own engine edits.
I used Platformer Plus with some additional edits to make What Friends Are For. Have you played it yet?
Next steps.
Now you know how to prepare for engine editing, but what parts of the code should you actually edit, and how? Part two of this guide covers the structure of the state files, and how you can edit them for your game to modify player movement.
Guide by Shin. Last updated 14/8/2024.
