What is GBVM?
Each built-in event in GB Studio generates GBVM instructions. These GBVM instructions are sent to the GBVM virtual machine to make things happen in your game, which is part of the GB Studio engine. For example, a default ‘Display Dialogue’ event that says ‘Hello world!’ sends the following instructions to make the dialogue appear:
; Text Dialogue VM_LOAD_TEXT 0 .asciz "Hello world!" VM_OVERLAY_CLEAR 0, 0, 20, 4, .UI_COLOR_WHITE, ^/(.UI_AUTO_SCROLL | .UI_DRAW_FRAME)/ VM_OVERLAY_MOVE_TO 0, 14, .OVERLAY_IN_SPEED VM_DISPLAY_TEXT VM_OVERLAY_WAIT UI_MODAL, ^/(.UI_WAIT_WINDOW | .UI_WAIT_TEXT | .UI_WAIT_BTN_A)/ VM_OVERLAY_MOVE_TO 0, 18, .OVERLAY_OUT_SPEED VM_OVERLAY_WAIT .UI_MODAL, ^/(.UI_WAIT_WINDOW | .UI_WAIT_TEXT)/
Wow, that’s a lot to take in. Each line has an instruction written in red, followed by some parameters for the instruction. First we load some text ‘Hello world!’ with VM_LOAD_TEXT, then we clear the overlay and move it to the correct position to display dialogue. Then we display the text on the overlay with VM_DISPLAY_TEXT, and wait for an A press to close it. This is just an example so it isn’t important that you know what each instruction does, but you should understand that these instructions are the steps in executing a ‘Display Dialogue’ event.
When you change the fields of an event, you change the GBVM it generates. To give us even more control over our game, we can write our own GBVM instructions instead of using events to generate them.
Be careful with formatting!
GBVM is particular about formatting and getting it wrong will cause errors when compiling. There is always a line break after every instruction. Text after a semicolon is commented out and will not be included in your instructions.
Okay, what can I use GBVM for?
GB Studio’s built in events usually generate several GBVM instructions each, and the GBVM can’t be modified. Using a ‘GBVM Script’ event, you can write your own GBVM instructions. This gives you more control over your game than using built in events. It’s worth noting that GBVM is not a programming language, but rather a set of instructions. I often see people unfamiliar with GBVM expecting it to be a programming language like C that allows them access to a variety of object types and easy control flow. This is not the case. Even a simple ‘Loop’ event may become quite confusing when converted to GBVM instructions and isn’t practical to write.
So, GBVM is good for when you want more granular control over events and want to execute individual parts of events or modify their behaviour. It is best used in combination with built in events, as they tend to be more human readable and offer simpler options for control flow. GBVM guides on GB Studio Lab will mostly focus on simple GBVM operations that give more control over existing events, though it is worth mentioning that GBVM can provide some complex and powerful functionality especially for math and calling engine functions. Here is the official docs page that lists GBVM commands and some of their uses. Here is the Github page that provides an up to date list of all GBVM commands and their parameters.
Now choose a section to read below based on the headings.
That sounds confusing, do you have anything easier?
You’re right, it is confusing. GBVM is not too well documented at this time. That’s the purpose of the GBVM guides on GB Studio Lab, to provide GBVM tutorials that anyone can use, even if they don’t understand anything in the above paragraphs. Ultimately, all you need to know is that GBVM lets you write instructions that give you more control than the built in events in GB Studio. Check out the recommended guides at the bottom of this page to get started. They include premade GBVM scripts you can use with minimal changes if you don’t want to dig too deeply into GBVM.
I get it, I want to learn more on my own.
If you’re up for a challenge, you can teach yourself how to use GBVM. The best way to learn GBVM is by looking at how the built in events use it. After you have written some scripts using built in events in a GB Studio project, you can export the source of the project and read the raw GBVM generated by the events. Select the Export Project Source item from the top menu, then look in [ProjectName]/build/src/src/data to find the GBVM generated by your scripts. It’s often helpful to export the GBVM of an event, copy it back into a GBVM script and modify it from there.
Use the Export Project Source option to generate text files containing the GBVM generated by your scripts.
Even if you do try to learn some GBVM on your own, check out the recommended GBVM guides below to get familiar with some common commands and practical things you can do with them.
Guide by Shin. Last updated 7/12/2023.
