Introduction.

In parts one, two and three of this guide, we learned all about how to edit the GB Studio engine and made an example Belt Scroller edit. In part four, we will learn how to package engine edits into engine plugins by using the Belt Scroller example again.

The official GB Studio docs have a section on creating engine plugins. This guide will cover most of what is in the docs in additional detail, but you may still find them useful.

Make the plugin folder.

The first step to making an engine plugin is to make a folder for your plugin. You can name it whatever you like.

For this example, we’ll name the folder for this plugin Belt Scroller Plugin.

Copy modified files from your engine to your plugin folder.

The next step is to copy only the modified files from your edited engine to your plugin folder. You also need to copy the folder structure from the engine including the engine folder.

For the Belt Scroller edit, we only modified adventure.c. We will copy adventure.c to Belt Scroller Plugin/engine/src/states/adventure.c.

Add an engine.json file.

You also need to copy engine.json from your edited engine to the engine folder of your plugin. For the Belt Scroller plugin, it will sit at Belt Scroller Plugin/engine/engine.json. You must modify engine.json so that it only contains the engine version. It will look like this, though your version may vary.

{ "version": "4.0.0-e0" }

At this point the plugin is ready to go! You can use it without any additional steps. That being said, there are a couple more useful features we can add to the plugin to make it even better.

Bonus- adding engine fields.

GB Studio allows you to add engine fields, variables within the engine that can be updated via project settings and the Engine Field Update event. These options allow us to modify engine variables at both compile time and run time respectively. There is a short explanation of how to add an engine field in the docs.

As an example, we are going to add an engine field to the Belt Scroller plugin called Toggle Up and Down Animation. This field will allow us to toggle between the modified and original animation behaviour.

First we will define the toggle variable in adventure.c, toggle_animation.

UBYTE toggle_animation = 0;

Next we will modify the animation code in adventure.c so that toggle_animation actually has a function.

if (new_dir != DIR_NONE) { if (toggle_animation == 0) { actor_set_dir(&PLAYER, belt_dir, player_moving); } else { actor_set_dir(&PLAYER, new_dir, player_moving); } } else { actor_set_anim_idle(&PLAYER); }

Now that the toggle variable is in the engine, we must add the associated engine field to the plugin. This is done by modifying engine.json in the root folder of the plugin. You can find examples of how to add fields in the engine.json file of the ejected engine.

• “key” must be the name of the associated variable in the engine, in this case “toggle_animation”.
• “label” is the name of the engine field displayed in the GB Studio editor.
• “group” is the name of the group the engine field is displayed under in the GB Studio editor.
• “type” is the type of selector used to update the engine field in the GB Studio editor. Depending on the type, you will have to define some additional values, so check the examples in the engine.json file of the ejected engine.
• “cType” must be the type of the associated variable in the engine, in this case “UBYTE”.

{ "version": "4.0.0-e0", "fields": [ { "key": "toggle_animation", "label": "Toggle Up and Down Animation", "group": "Belt Scroller", "type": "slider", "cType": "UBYTE", "defaultValue": 0, "min": 0, "max": 1 } ] }

You must restart GB Studio to apply your engine field changes, or the engine field will not show up in the editor.

Following these steps again, I also added an engine field to toggle the modified player movement in the Belt Scroller plugin. You can see both engine fields in the Github repo for this tutorial.

Bonus- adding a scene type.

As of 4.0, GB Studio also allows you to create your own scene types. There is a short explanation of how to add scene types in the docs.

As an example, we are going to split Belt Scroller into its own scene type separate from Adventure.

First we will add our new scene type to engine.json.

"sceneTypes": [ { "key": "beltscroller", "label": "Belt Scroller" } ]

Next we will rename adventure.c to beltscroller.c. Then we will rename the functions within beltscroller.c to beltscroller_init() and beltscroller_update() to match the key defined in engine.json.

Again, you must restart GB Studio for your scene type to appear in the editor.

That’s all that is required for this example. Again, if you want to check it out, the plugin is available in the Github repo for this tutorial.

Next steps.

That’s it for this guide series on how to edit the GB Studio engine. Hopefully you can dive into the engine and start learning on your own. Don’t forget the resources for engine editing I mentioned in part one of this guide, especially reading through and editing existing plugins! Every new plugin is an opportunity for you to learn something new too.

If you have any questions or feedback about this guide series, please leave a reply or DM at my Twitter. I’d like to update these guides further so they can be more useful.

Guide by Shin. Last updated 5/9/2024.