Two versions of GB Studio are available for Windows. The Squirrel Installer version just requires you to unzip, double click and then wait a few seconds while the application installs to your C:\ drive. Once installed a shortcut will be added to your desktop automatically and the application will start. The application will be installed to
%LocalAppData%\gb_studio, if you need to install to a different location use the Manual version.
The Manual version is a zip containing the application files, you can unzip this to any location. Once unzipped double click
gb-studio.exe to start.
For macOS unzip the downloaded file and move
GB Studio.app to your Applications folder. Double click to start.
If you’re having trouble building or running your game you may also need to install Apple’s Command Line Tools by opening
Applications/Terminal.app and entering the following command.
Ubuntu / Debian-based Linux
For Debian-based Linux distros, download the .deb version and run the following commands (Tested on Ubuntu 18.10)
> sudo apt-get update > sudo apt-get install build-essential > sudo dpkg -i gb-studio_1.0.0_amd64.deb > gb-studio
Fedora / RPM-based Linux
For RPM-based Linux distros, download the .rpm version and run the following commands (Tested on Fedora 29)
> sudo yum install libXScrnSaver make lsb > sudo rpm --ignoreos -i gb-studio-1.0.0.x86_64.rpm > gb-studio
When you first open GB Studio you will see the New Project window.
If you have an existing project you can open it from here by clicking Open and navigating to the
Give your project a name to get started (don’t worry, you can change this later) and choose a project template. If you’re new to GB Studio then I would recommend using the Sample Project template which contains a few example scenes and scripts already set up so you can get a small idea of what’s possible. Click Create Project and you’ll be taken to the Project Editor.
As soon as you see this screen you can click the Play button in the top right which will just take a few seconds to run the project. After playing the sample project you can try clicking around the editor to see how the project is set up. Select one of the people or signposts and edit the their dialogue using the sidebar on the right then try running the project again, you’ve just made your very own version of the game! Don’t worry if you break anything, you can always make a new project with the sample template later.
When playing your game inside GB Studio use the following keyboard controls:
Up - Up Arrow / W
Down - Down Arrow / S
Left - Left Arrow / A
Right - Right Arrow / D
A - Alt / Z / J
B - Ctrl / K / X
Start - Enter
Select - Shift
Navigating The Menus
Much of the functionality of GB Studio is accessible through the menu bar and many of the menu items contain keyboard shortcut labels. Try clicking around on the menus to discover all of the shortcuts but the following are a few you should find useful:
Save Project - Ctrl/Cmd + S
Open Project - Ctrl/Cmd + O
Switch View Mode - Ctrl/Cmd + 1-7
Run Game - Ctrl/Cmd + B
Export ROM file - Ctrl/Cmd + Shift + B
Setting the Player Starting Position
You can reset the player starting position by clicking into any scene and pressing the P key.
Saving and Loading
To save your project select
File > Save from the menu or press Ctrl/Cmd + S. If you try to close a project with unsaved changes GB Studio will warn you giving you a chance to save your project first. On macOS any unsaved changes in your project will be represented by a dot in the window close button.
To load your project again, either use the Open button on the New Project window or select
File > Open from the menu and navigate to your project’s folder then select the
The project folder layout and
.gbsproj file is designed to work well with version control systems such as Git with each change by the application taking place on a new line in the data file allowing history to be tracked easily. If you want to use version control on your project you can just create the repository at the project root folder.
It’s recommended to ignore the
build folder from your repository using a
.gitignore file or similar.
The Project Editor
The default view for the Project Editor, as shown below, is the Game World. This is where you can create your game by combining scenes, adding actors and triggers then building scripting events to add interactions.
Use the Editor Tools to switch between Select, Add, Erase and Collision Drawing modes.
In the Select mode clicking scenes, actors or triggers causes the Editor Sidebar to show editable fields specific to whatever was selected. Clicking in the background between scenes switches the sidebar back to the Project Editor where you can set the project name and choose the starting scene and position.
The Asset Viewer
Using the Project Navigator you can switch between the available views for your project. If you select Sprites, Backgrounds, UI Elements or Music you will be taken to the asset viewer where you can search and preview the assets available in your game.
See the documentation on Assets for more information on how to add new assets and the different requirements needed.
Adding a Scene
To add a scene to a scene click the + button in the Editor Tools and select Scene from the menu (alternatively press the S key), then click on any empty space in the Project Viewport where you wish to place the scene.
When a scene has been added you can use the Editor Sidebar to give the scene a name and to choose which background image from your project’s assets that you want to use. See the documentation for Backgrounds for more information on adding background images.
A scene script can be used to have events run as soon as the scene is loaded. When the scene is selected click the Add Event button in the Editor Sidebar to open the event menu and start building the script. For more information see the documentation for Scripting.
The player starting position is indicated in the game world view by the icon.
Clicking in the background between scenes switches the sidebar back to the Project Editor where you’ll have options to set the player starting scene, position, direction and sprite sheet.
You can also change the player start position by dragging the icon and can even drag between scenes.
Most actor script events can also be applied to the player. In addition you can use Set Player Sprite Sheet event to change the graphics used for the player character mid-game. Changing the sprite sheet will persist between scenes so remember to switch the sprite back if it was supposed to be temporary.
When switching between scenes the player will always become visible at the scene start location regardless of previous visibility options. if you want the player to be hidden on a scene e.g when showing a title screen or cutscene add a Player Hide event to the scene’s start script.
Actors are the characters and objects in your scene that you can interact with.
Adding an Actor
To add an actor to a scene click the + button in the Editor Tools and select Actor from the menu (alternatively press the A key), then click on the scene and position where you wish to place the actor.
The Editor Sidebar will switch to show the actor settings where you can give the actor a name for easier navigation later, reposition the actor (which you can also do with drag and drop), set the sprite sheet, initial direction, the movement type and create a script that will play when the player interacts with the actor.
There are a few different movement types available to choose, the one you should use will depend on how you want the actor to behave as the player is walking around the scene and interacting with it.
- Static - The actor will display a single frame from the selected spritesheet.
New in 1.1.0
If the sprite sheet contains more than one frame you will be given the option to choose which frame to display, this can be modified later using an Actor: Set Animation Frame event. Sprite sheets with multiple frames also enable the ability to optionally animate the actor by cycling through each of the frames at a specified speed, the speed can also be modified with an Actor: Set Animation Speed event.
The actor will only ever face in the initial direction (unless the direction is modified later using a script). If the player interacts with this actor it will not change direction. Useful for things like signposts or other stationary objects.
Face Interaction - The actor will start facing in the initial direction but when the player interacts with the actor it will turn to face the player before it’s script plays. Useful for simple characters to make them more responsive to the player’s actions.
Random Rotation - The actor will start in the initial direction but will randomly change direction at set intervals. Useful to show characters who are looking around their surroundings.
Random Movement - The actor will randomly change direction and move around the scene at set intervals. Useful for characters who are searching an area. Actors can block the player’s movement so be careful not to use this movement type around tight spaces where the player might get stuck waiting for the actor to move out of the way.
Note If the actor uses a static sprite sheet (i.e. containing only a single frame of animation) then the only movement type available will be static and the inputs for choosing the movement type and initial direction won’t appear.
Due to hardware limitations only 25 unique frames of animation can be allocated to actors in each scene. Where possible use static or non animated sprite sheets to decrease the number of frames used. Another way to reduce the frame count is to reuse the same sprite for multiple actors in the scene, reusing the same sprite sheet will not count towards the scene frame total.
When the actor is selected click the Add Event button in the Editor Sidebar to open the event menu and start building a script. For more information see the documentation for Scripting.
Triggers are areas in a scene that, when the player walks over them, will cause a script to play. They are useful for creating doorways between scenes and to start cutscenes when the player moves to a specific position.
Adding a Trigger
To add a trigger to a scene click the + button button in the Editor Tools and select Trigger from the menu (alternatively press the T key), then click and drag across the scene where you wish to place the trigger setting the desired width and height.
The Editor Sidebar will switch to show the trigger settings where you can give the trigger a name for easier navigation later, reposition and scale the trigger and create the script that will play when the player walks on the trigger.
When the trigger is selected click the Add Event button in the Editor Sidebar to open the event menu and start building the script. For more information see the documentation for Scripting.
Scripting events allow you to dynamically control parts of your game based on interactions from the player. Use them to connect scenes together, to give dialogue to your characters or to create cutscenes.
When either a scene, an actor or a trigger is selected in the World Editor, the Editor Sidebar will contain an Add Event button at the bottom right corner, click this to add new events. If any events have already been defined they will be listed here with the topmost event being the first that will be run.
When adding events to actors they will run when the player stands next to that actor and presses the interact button. Events on triggers run when the player stands on top of the trigger which is useful for creating doorways between scenes. Events on scenes run as soon as that scene is loaded which is useful for configuring the scene based on values of variables or to kick off a cutscene.
After clicking the Add Event button a menu will appear to choose the event to add. If you start typing you can filter this list or you can scroll through it to find what you’re looking for. Click an event or press the Enter key to add the highlighted event to your script.
Copy / Paste
Clicking the down arrow next to an event name in a script shows a dropdown menu where you can copy an event to your clipboard. Clicking this on another event allows you to paste the clipboard event either before or after the selected one or to just paste the values from the first event into the second.
Text: Display Dialogue
Show a dialogue box with up to three lines of text, 18 characters per line (16 on the third line), at the bottom of the game screen. This will likely be the most used script command for interacting with actors in your game.
When text is shown the dialogue box will slide up from the bottom of the screen and will slide down after it has been shown.
New in 1.1.0
- Using the + button you can create a dialogue sequence which will only close after the last message has been displayed.
- You can display any of the first 100 variables in a text box by using the variable’s identifier $00$ to $99$.
Text: Display Multiple Choice
Present two options to player allowing them to make a choice, will set the specified variable to true if the first option is chosen and to false if the second option is chosen.
Text: Set Animation Speed New in 1.1.0
Set the speed that dialogue boxes appear and disappear and how fast text appears within the box.
Scene: Switch Scene
Transition to a new scene with player at a specified position and direction. A connection line will be drawn between the source of the event and the destination scene with a icon appearing at the destination position. It’s possible to drag this icon around and between scenes to modify the event.
Scene: Store Current On Stack New in 1.1.0
Store the current scene and player state on to the scene stack, this allows you to return to this exact location later using the Scene Restore events. A common use of this event would be to include in a script just before a Switch Scene event to open a menu scene, in the menu scene you could wait for the player to press a close button and then use the Restore Previous From Stack event to return to where the player opened the menu.
Scene: Restore Previous From Stack New in 1.1.0
Transition to the last stored scene from the scene stack using the specified fade speed. The previous scene will then be removed from the stack so the next time this event is used it will transition to the scene before that.
Scene: Restore First From Stack New in 1.1.0
Transition the very first scene stored on the stack, for instance if you had multiple levels of menu scenes you could use this to imediately return to the game scene. This event will cause the scene stack to become empty.
Scene: Empty Scene Stack New in 1.1.0
Clears the scene stack so that no previous scenes can be restored.
Variable: Set To ‘True’
Set the value of the specified variable to true.
Variable: Set To ‘False’
Set the value of the specified variable to false.
Variable: Set To Value
Set the specified variable to a defined value.
Variable: Increment By 1
Increase the value of the specified value by one, up to a maximum of 255. If the value was previously false it will now be 1 (and also true), if it was previously true it will now be 2.
Variable: Decrement By 1
Decrease the value of the specified value by one, down to a minimum of 0. If the value was previously true it will now be 0 (and also false).
Variable: Math Functions New in 1.1.0
Allows you to perform various maths functions on a variable to add/subtract/multiply/divide/modulus a value/variable/random number.
Note: Variables have max values of 255 and will wrap if increased above 255 or below 0.
Variable: Reset All Variables To ‘False’
Reset all variables used by your project back to false.
Control Flow Events
If Variable Is ‘True’
Conditionally execute part of the script if the specified variable is set to true.
If Variable Is ‘False’
Conditionally execute part of the script if the specified variable is false.
If Variable Compare With Value
Conditionally execute part of the script if the specified variable matches a rule, such as “Equal To”, “Greater Than” or “Less Than” against a value.
If Variable Compare With Variable New in 1.1.0
Conditionally execute part of the script if the specified variable matches a rule, such as “Equal To”, “Greater Than” or “Less Than” against a second variable.
If Joypad Input Pressed
Conditionally execute part of the script if the specified joypad input is currently pressed. Will not wait for user input so use directly after a Joypad Input: Pause Script Until Pressed event if waiting is required. Event will only execute once, if you wish to run a script every time a button is pressed use Joypad Input: Attach Script To Button instead.
If Actor At Position
Conditionally execute part of the script if the specified actor is at a certain position in the scene.
If Actor Facing Direction New in 1.1.0
Conditionally execute part of the script if the specified actor is facing a certain direction.
If Game Data Saved New in 1.1.0
Conditionally execute part of the script if there is a saved game available.
Execute part of the script in a loop forever. Remember to break out of the loop otherwise the player will become stuck at this point. You can use a Stop Script or Switch Scene event to stop the loop.
Event Group New in 1.1.0
Provides no functionality but allows you to group a sequence of events together and give them a label (using the Rename Event option on the event menu) and collapse the events into a single block.
Stops the current script from running.
Camera: Move To
Move the camera to a specifed position in the scene.
Camera: Lock To Player
Move the camera back to focusing on the player, locking into position when the player moves.
Shake camera effect for up to 10 seconds.
Screen: Fade In
Fade the scene to a white screen.
Screen: Fade Out
Fade the scene in from a white screen.
Actor: Set Direction
Set the facing direction of the specified actor.
Actor: Set Position
Set the position in the scene of the specified actor.
Actor: Set Position Using Variables New in 1.1.0
Set the position in the scene of the specified actor from the values of two variables.
Actor: Set Relative Position New in 1.1.0
Set the position in the scene of the specified actor relative to their current position.
Actor: Move To
Make the actor walk to a specified position in the scene. Actor will ignore all collisions along path so combine multiple of these events if you need to specify an exact path avoiding obstacles in the scene.
Actor: Move Relative New in 1.1.0
Make the actor walk to a position relative to their current position.
Actor: Move To Using Variables New in 1.1.0
Make the actor walk to a position from the values of two variables.
Actor: Store Position In Variables New in 1.1.0
Store the current position of an actor into two variables.
Actor: Push Away From Player
Push an actor in the direction the player is currently facing. By default pushes by one tile, but can optionally slide until a collision occurs.
Actor: Emote Bubble
Display an emote bubble above the specified actor from one of Shock, Question, Love, Pause, Anger, Sweat, Music and Sleep. You can change the graphics used for these bubbles by editing the UI Elements of your game.
Actor: Set Animation Frame New in 1.1.0
Set the current animation frame of the specified actor.
Actor: Set Animation Speed New in 1.1.0
Set the animation speed of the specified actor.
Actor: Set Movement Speed New in 1.1.0
Set the movement speed of the specified actor.
Actor: Set Player Sprite Sheet
Change the player sprite sheet from the default defined in the Project Editor. Changes to the player sprite sheet will persist between scene transitions so make sure to change it back if the change was supposed to be temporary.
Actor: Invoke Script New in 1.1.0
Call the script on another actor in the scene as if the player had interacted with that actor.
Hide an actor so it is no longer visible. Hidden actors will no longer cause collisions and will not be able to be interacted with. You can hide the player on a Scene Start Script to make menu and title screens.
Unhide a previously hidden actor.
Sprites: Hide All
Hide all sprites in scene. Can be useful to create cutscenes where the player should not be visible by adding to a scene’s starting script.
Sprites: Show All
Show all sprites that were previously hidden.
Show either a black or white window over the top of the current game screen. Can be used to obscure and then reveal parts of the scene background for example on the sample project logo screen.
Hides the screen overlay.
Overlay: Move To
Moves the overlay to a new position on the screen.
Joypad Input: Pause Script Until Pressed
Pauses the script until one of the specified joypad inputs are pressed.
Joypad Input: Attach Script To Button New in 1.1.0
Execute the specified script any time a joypad input button is pressed. If you attach scripts to a direction button or the A button the scripts will override the default game actions.
Joypad Input: Remove Attached Script New in 1.1.0
Remove an attached script from a joypad input button restoring the default functionality of the button.
Music: Play Track
Plays a music file, optionally looping the file when finished.
Stops any currently playing music.
Pause script for up to 10 seconds.
Game Data Events
Game Data: Save New in 1.1.0
Save the current game data.
Game Data: Load New in 1.1.0
Load the previously saved game data.
Game Data: Clear New in 1.1.0
Remove any previously saved game data.
When your project was created an
assets folder was also made within the project containing a number of subfolders for each asset type in your game.
GBStudio doesn’t currently contain any ability to edit the graphics or music in your game directly, you instead can use your favourite existing applications and save files into these folders where they will instantly appear ready to use in your project. If you edit a sprite or background PNG file and save using an external image editor the change will be seen in your Project Window as soon as you switch back it.
While you can create graphics in any application that can output PNG files it is recommended to use Aseprite or Photoshop to create your sprites and UI elements then to use Tiled Map Editor to create your backgrounds. Each image asset type has a different set of requirements detailed over the new few sections of this documentation.
Sprites are the graphics used by playable or interactive characters in your scenes. Add sprites to your game by including PNG files in your project’s
Sprite PNGs must only contain the following four colors:
#65ff00 is used to represent a transparent background in game and will be invisible in-game and in the World Editor.
Colors that are not one of the above hex codes will be matched to the nearest color. Unlike backgrounds, the color
#306850 can not be used in sprites.
A sprite consists of one or more
16px frames laid out horizontally in file. A sprite with a single frame will be
16px while a sprite with three frames will be
For sprites that only need a single frame (e.g. static items such as signposts) create your PNG as a
16px image containing just the one frame required.
If you want to have sprites that play short animations you can make a PNG with between 2 frames at
16px and 25 frames at
16px. Using these sprites on an actor will enable you to select which frame you want to display by default and will allow an animation to be played at a specified speed.
To make sprites that can face in four directions turning towards the player, create a
16px PNG containing the three frames forward facing, upwards facing and right facing. The left facing sprite is automatically generated by flipping the right facing sprite horizontally so does not need to be created.
To make sprites that have animated movement, or that can be used as a player character, create a
16px PNG containing six frames, two forward facing, two upwards facing and two right facing animation frames.
As there are limits to how many sprites frames can be loaded into a single scene don’t use animated sprites unless you know your NPCs will need animated movement.
Each of your scenes requires a background image that defines how that scene should look. You can add backgrounds to your game by including PNG files in your project’s
Background PNGs must only contain the following four colors:
Colors that are not one of the above hex codes will be matched to the nearest color. Unlike sprites, the color
#65ff00 can not be used in backgrounds.
Backgrounds are divided into
8px tilesets so the total image size must be a multiple of
8px in both width and height. A background has a minimum size of
144px (the screen size) and currently a background can be no larger than
An image can contain no more than 192 unique
8px tiles at once due to memory limits. This means that even using the smallest background size possible you must repeat about half of your tiles. Where possible repeat tiles between images as they will be grouped together saving on total game size. It is recommended to use a tile map editor such as Tiled to ensure your backgrounds conform to the pixel grid.
Your project contains a number of files in
assets/ui with fixed file names that define parts of your game’s user interface. Editing these files allows you to change the default font, set the window frame and modify the selection cursor.
If you remove any of the files in the ui folder they will be replaced with the default assets the next time you build your game allowing you to revert any unwanted changes.
Edit this file to change the game’s font when talking to actors in your game.
The game engine uses 9-slice scaling of this image to create the frame around text boxes. Editing this image will allow you to change the frame design or set it to a solid color.
This image is used as a selection cursor when showing multiple choice options in your game.
This image used to define the look of the emote bubbles that can be shown above actors using scripting. Each bubble is
16px in size and the each bubble represents Shock, Question, Love, Pause, Anger, Sweat, Music and Sleep in that order left to right.
With the exception of
emotes.png which follows the standard sprite requirements, UI PNGs must only contain the following four colors:
GB Studio is internally using GBT Player, a driver which takes .MOD files and converts them to a format the Gameboy can understand. You can use software such as OpenMPT (Windows, though it works great with Wine) or MilkyTracker (works natively across multiple systems) to create .MOD tracker music. Of course, you can use other software that can edit .mod files like BassoonTracker (web based), ProTracker, and more.
- Create a blank GB Studio project, find the file
assets/music/template.modand open it with your tracker of choice.
- You must edit this file to get an accurate representation of the instruments you can use.
- MilkyTracker users should save this file as an
.XMfile. Saving a .mod file in MilkyTracker will corrupt it. Export your song as a .mod file every time you want to test your song in-game.
- You can remove the example song, but you MUST keep the instruments/sounds/samples intact.
- Use the instrument list shown later in this document to pick the sounds you want. Changing the samples in your tracker will not affect how they sound in-game.
When done, please add your .mod files to the
assets/music folder of your project. Test your song in-game often to keep track of any audible in-game differences. (NOT in the preview!)
We’re still dealing with a tracker. I’ll try to give you a quick rundown of how a tracker works:
C-5 01 v64 ... --- -- --- --- | | | | | | | +-- Effect column (Volume changes, arpeggios, panning, etc.) | | +------ Volume value, this is irrelevant in .MOD. (Most examples here omit this | | and instead display three dots in its place) | +--------- Instrument +------------- Note and octave (A C note in the 5th octave. The dash can be a #, which signifies a sharp note e.g. C#, D#)
This is what comprises of a channel’s row. Rows can be empty, or can only be partially filled (with just an effect, for example). There’s 4 of those columns in total.
Any part in this documentation where you see data that starts with
ModPlug Tracker MOD, you can copy that entire block into OpenMPT as-is. Any data copied from OpenMPT looks like that when you paste it into any text application.
There may be ONLY 4 channels in your .MOD file. Any less or more, and it will not convert properly.
This is a limitation imposed by the Gameboy itself, which has 4 channels of polyphony at all times.
On top of that, you may only use certain instruments on certain channels. There’s a table down here which documents where the instruments should go. This is also because the Gameboy assigns instruments based on the channel, this is hardwired into the very silicon of the chip and cannot be changed.
|Channel #||Sound type||Note Range1||Instruments||Effects|
|Channel 1 & 2||Pulses||C3 to B8||1-4||0, B, C, D, E8, EC, F|
|Channel 3||Waveform||C3 to B8||8-15||0, E8 and EC|
|Channel 4||Noise||Only C5||16-31||B, C, D, E8, EC, F|
1 This note range is for trackers that display its notes on a range from C1 to C8, like OpenMPT does. If you’re using a tracker that can go as low as C0 (like MilkyTracker), then the note ranges are one octave (number) lower (for instance, C3 to B8 in MPT sounds the same as C2 to B7 in Milky).
Channels 1, 2 and 4 only have a quarter of the volume range that trackers support. (which is from 0h to 40h). The supported volumes are as such:
00, 04, 08, 0C, 10, 14, 18, 1C, 20, 24, 28, 2C, 30, 34, 38, 3C
Any other volumes will just get clamped to the nearest value supported. (e.g. C40, the default volume value, gets clamped down to C3C)
Volumes above C40 aren’t supported, and they will behave abnormally once converted.
While in a tracker the volume resets on each new note, it will not upon conversion. Say you have this scenario:
ModPlug Tracker MOD |C-502...C40| |...........| |...........| |...........| |........C..| |...........| |E-502......|
In the tracker, the E-5 note will resume at full volume after the C00 effect.
In-game, you will not hear the E-5 note. This is because the C00 persists until another
Cxx effect is set. Basically, you have to do the following:
ModPlug Tracker MOD |C-502...C40| |...........| |...........| |...........| |........C..| |...........| |E-502...C40|
This applies to any instance of volume. If you have a note on C24 that gradually decreases to, say C18, you still need to reset each new note to C24 (or higher, or lower, depending on what you want to achieve).
Meanwhile, Channel 3 only gets a quarter of that, with a volume range of
00, 10, 20, 40. And beyond that, you’ll have to input the instrument and note for the volume change to have any effect, unless it’s a
C00 volume effect. For instance, again:
ModPlug Tracker MOD |C-511...C40| |...........| |...........| |...........| |........C20| |...........| |G-511...C40|
You will not hear any volume change from the C20 in-game, so what we have to do is add a note there to register the volume change.
ModPlug Tracker MOD |C-511...C40| |...........| |...........| |...........| |C-511...C20| |...........| |G-511...C40|
The pulse channels get 4 instruments (from 1 to 4):
- 25% pulse
- 50% pulse (sometimes called a square wave)
- 75% pulse (inverted 25% pulse)
- 12.5% pulse
Instruments 5 through 7 are intentionally left blank.
The wave channel gets 8 instruments (from 8 to 15):
- Buzzy (Source code calls this “random :P”)
- Ringy (useful for SFX)
- Sync Saw
- Ring Saw
- Octave Pulse + Triangle
The noise channels gets the most instruments, but that’s partly because of how the noise works on the Gameboy:
- 16 to 23 - Periodic (looped) noise at various pitches.
- 24 to 32 - (Pseudo)random noise at various pitches.
|Bxx||Jump||Jump to a specific position in the song,
|Cxx||Volume||Sets the volume to xx. See volume limitations for more info.|
|Dxx||Pattern break||Jumps to the next pattern early, where
|E8x||Pan||Set the panning to
|ECx||Note cut||Cut the note after
|Fxx||Set speed||Sets the song speed to
|Fxx Value (in tracker)||BPM (in tracker)||BPM (in game)|
|F011||750 BPM||900 BPM|
|F021||375 BPM||450 BPM|
|F031||250 BPM||300 BPM|
|F041||187.5 BPM||225 BPM|
|F05||150 BPM||150 BPM|
|F06||125 BPM||128.57 BPM|
|F07||107.14 BPM||112.50 BPM|
|F08||93.75 BPM||100 BPM|
|F09||83.33 BPM||90 BPM|
|F0A||75 BPM||81.82 BPM|
This is not a full table, it’s just the top few speeds. It’s here to highlight some of the speed discrepancies, albeit small to not be very noticeable, with the exception of the values marked with 1.
You might notice that the value of the F effect, when converted to decimal, is just the speed divisor. For instance, F03 divides the BPM by 3 (
750 / 3 = 250, or
900 / 3 = 300).
Because of how GB Studio is set up, a 60hz F05 effect, which would result in 180 BPM in-game, is impossible here.
While not in GB Studio, GBT has a flag called
-speed that will handle BPM differently, which would require F96 effects for every speed, as it won’t handle any internal conversions to get the speed closer. This is the reason why F01 to F04 require F96 in both modes, there’s no equivalent for it in tracker speed.
1. Values marked with 1 require an additional F96 effect for the song to sound closer in speed when converted, or setting the song BPM to 150. This F96 effect can be removed once you’re done with your song, there won’t be any difference as GBT ignores this – It’s only here to set the BPM to something closer to the in-game version.
This section will cover some tricks you can use with GBT to make it sound better than it should
1. High Speed
By using F01 to F04, you can achieve much higher granularity when it comes to changing volumes and creating sounds of sorts. This means that with a high enough speed, you can create more varied bodies for sounds, with sort-of envelopes, or elaborate effects (like 1 channel echos, which I’ll cover here in a moment).
This trick means you’re going from drums that sound flimsy and primitive to something more impressive.
Here’s an example of a Snare Drum, at speed F02, that might sound good for you.
ModPlug Tracker MOD |C-526...C40 |C-527...C28 |........C20 |........C18 |........C10 |........C08 |........C04 |........C.. (this is on the noise channel)
If this is longer than what you need, simply crop it starting from the bottom.
You can also use this for tones and stuff, like short staccato notes or flutes that fade in.
If you do this, keep in mind the GB Sound hardware has an annoying bug that resets the phase of each waveform on a volume set, meaning you can get scratchy noise in a few emulators and also the real GB.
2. One channel echoes
This works on most speeds. This is useful for when you need a melody on top of some sort of echoing ostinato, or phrase, or whatever.
To illustrate it, I’m going to try illustrating it like this, instead of a tracker layout:
A _ B _ C _ E _ G _ E _ C _ B _ Without 1ch Echo +-----+ +-----+ +-----+ A _ B a C b E c G e E g C e B c +-----+ +-----+ +-----+ +-----+ With 1ch Echo (lowercase notes are the echoes)
Notice how each lowercase letter takes the form of it’s 3 step behind louder cousin? That’s how the trick works. By having shorter notes that, on each step, has another quieter note that’s way behind, you get a cool echoing effect.
I can’t explain it very well via text, so I recommend you check out this video by explod2a03 covering how this trick works with a better example and actual audio: https://www.youtube.com/watch?v=6GI9gngTn_Y
The best way to do this in a tracker is to use a channel you’re not using temporarily, copy your note sequence to it, delay it by 3 (or however many you need) rows, then right clicking on the selection and clicking “Amplify…”, and setting the amplitude to something lower than 50%.
After that, you should have both channels “alternate”. Select the entirety of the channel with the echoes (from top to bottom), go to the channel you want to merge the echoes with, right click, go to “Paste special”, then click “Mix paste” (This should have a shortcut, might want to learn it as it can be fairly useful).
3. Quick volume envelopes
Are you in a hurry? No problem, this simple trick will create linear envelopes:
- Select two volume / C values of two separate notes (within the same channel), and everything in between
- Right click and hover over “Interpolate”
- Click on “Effect column”
- You’re done!
You might wonder how’s it going to sound in-game; well, it’ll sound as close as possible. The volumes it can’t play it’ll just clamp it to the nearest ones it can play.
Frequently Asked Questions
Q: Can I use mp3s with this?
Q: Can I use this .MOD file I found online?
A: Most likely, no. Your .MOD file has to be specifically formatted within what you get in
template.mod, with the limitations mentioned above.
Q: How do I stop a note from playing?
A: Either use another note entirely, or if you want to silence it, use a
Q: My song sounds all wrong upon building it! Why is that?
A: There’s multiple reasons why that might be. Please make sure your song is complying with everything above (in particular, make sure you’re only using the supported effects, are complying with the channel allocations, and aren’t going over or under certain frequencies).
If you’re using MilkyTracker, please be aware that it can break how a .mod file can sound. To get around this, save as
.XM, its natively supported format, and when you’re done with the song, export it as a .mod song and try it out in GB Studio.
Q: My song speed is wrong! It’s faster in-game than it is in the tracker!
A: If you’re using an
Fxx effect with the value higher than
F05, then you will need to keep 50hz to 60hz conversions in mind. The .mod format was originally developed for European computers, which ran at 50hz, while the Gameboy runs at 60. A way to mitigate this is to set your BPM to 150 instead of 125. If you’re using OpenMPT (which cannot set the BPM for whatever reasons), a
F96 effect in the song will do the trick (though use it as early as possible).
Q: Can I play back this voice clip/sound effect/whatever?
A: No, not on GBT.
LSDj and more advanced sound drivers available for the Gameboy do support playing back samples, but doing this requires a lot of data to be moved in a short amount of time (means only music can play at that time, really).
Q: Can I use a different tool to write my music?
A: If the tool can natively export to .mod, try it! If not, then you’ll need to transcribe what you’ve written to a tracker, that can save .mod files.
Q: Can I use MIDI files?
A: OpenMPT can open MIDI files, but you’ll have to do the hard work of truncating it into just 4 channels, with limited tones. It’s often easier to just input stuff manually because you have a lot more control over everything, and you have a better picture of everything going on if you do that.
Q: This is kinda cumbersome. What alternatives do I have?
A: As of the date of writing this, none that I know. It’s possible that in the future people might make custom tailored trackers or tools for GB Studio, but until then, this is the only way we can make music for GB Studio games.
You might want to start making a non-GB song with OpenMPT or your tracker of choice, as that’ll better teach you what a tracker really does, at least in my opinion…
There’s a link in the Tips section on how to get started with OpenMPT, I suggest giving it a read!
Q: I used a D00 effect on my last pattern to loop back to the first, but it’s playing glitched in game after it loops once?
A: Use a
Bxx effect. Using a D00 effect on the last frame will trip GBT into thinking there’s more data beyond the song, making it read garbage data.
Q: I’m using OpenMPT, and some notes appear as red and they sound way higher/lower than what they’re supposed to sound!
A: Go over to the “General” tab that’s under the New File, Open and Save buttons. Click the big button next to the “Name” field that says “MOD (ProTracker), 4 channels”. Once there, disable both ProTracker 1⁄2 Mode (MOD) and Amiga Frequency Limits. This is a thing because the format here is meant to be used with the Amiga line of computers (that’s where it was made), which has frequency limits.
Q: The song starts out with garbage noise.
A: If you’re not using the first two channels, mute them with a
Q: Can I play sound effects?
A: Not as of yet. The only way you can play sound effects is to play it as a music file, but that’ll kill the current music and you’ll have to restart it after the sound effect is done playing.
- Make sure you save frequently and also back-up your files. This is important in anything that you do and it’s worth mentioning here.
- If you’re stuck, please ask for help in the Discord server, in
#music-help. There’s usually a few handful of people who are willing to help out at most times.
- Frequently try out your music in your game. Things don’t sound 1:1, and the built in preview just plays the .mod file rather than building the music and previewing that.
- Keep it simple! Don’t jump into this, trying to emulate what several artists have done with LSDj or whatever other tools, you’ll just get stuck.
- Don’t be afraid of failure. I get this is kind of an unfitting tip, but it’s important. Your first song won’t be good, and that’s okay. You’ll fail, sure, but you’ll also gain knowledge on what you might’ve done wrong, or how you want to go on about with your next endeavor.
- OpenMPT has a manual to help you get started. Here’s a link, give it a read if you’re stuck (or just ask for help)
- Give the GBT Player documentation a read.
Building Your Game
Clicking the Play button in the top right of the Project Editor window will start a build of your game and once complete will open a new window where you can play your game. See Keyboard Shortcuts for details on how to play your game in the Play Window.
Clicking the Project Navigator and selecting Build & Run will take you to the Build Terminal where you can see a log of the project build. You also get to this screen by clicking the Play button while a build is taking place. This screen will show you if there’s any errors in your build to help you correct them.
Build as ROM
Clicking the Export button and clicking Export ROM will build your game and create a ROM file in your project’s build folder as
$PROJECT_ROOT/build/rom/game.gb. You can play this ROM file in any compatible emulator such as OpenEMU or KiGB.
Build and deploy for Web
Clicking the Export button and clicking Export Web will build your game and create a HTML5 web build in the folder
$PROJECT_ROOT/build/web. You can upload this folder to any web server and navigate to the
index.html file to play your game in a web browser. If you use a mobile or tablet web browser the game will also include touch controls.
If you zip the
build/web folder you can upload it to Itch.io as a HTML game. In this case the recommended viewport size to use is
On macOS if you’re having trouble building or running your game you may also need to install Apple’s Command Line Tools by opening
Applications/Terminal.app and entering the following command.
On Windows you may need to whitelist the application in your Anti Virus software to perform a build.