Printable Documentation



Installation

Go to the GB Studio website and click the download button or choose your preferred version from the downloads page.

Windows

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.

macOS

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.

xcode-select --install

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

Getting Started

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 .gbsproj file.

New Project

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.


Keyboard Shortcuts

Play Window

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

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

Saving

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.

Loading

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 .gbsproj file.

Version Control

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.


Scenes

A scene is a single screen of your game, it can contain multiple actors and triggers. Your game will typically be made up of many scenes connected together with triggers using the Switch Scene event.

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.

Scripting

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

Start Position

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.

Scripting

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

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.

Movement Type

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.

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.

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.

Frame Limits

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.

Scripting

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

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.

Scripting

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

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.

Add Events

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 Events

Scene Events

Variable Events

Control Flow Events

Camera Events

Screen Events

Actor Events

Sprite Events

Overlay Events

Input Events

Music Events

Timing Events

Game Data Events


Assets

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.

For music you must create new tracks as MOD files with only four channels. You can create these files with OpenMPT or MilkyTracker.


Sprites

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 assets/sprites folder.

Requirements

Sprite PNGs must only contain the following four colors:

#071821
#86c06c
#e0f8cf
#65ff00
Download the GB Studio Palette Swatches for:
Adobe Photoshop
Aseprite

The color #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 x 16px frames laid out horizontally in file. A sprite with a single frame will be 16px x 16px while a sprite with three frames will be 48px x 16px.

Static sprites

For sprites that only need a single frame (e.g. static items such as signposts) create your PNG as a 16px x 16px image containing just the one frame required.

Animated sprites

If you want to have sprites that play short animations you can make a PNG with between 2 frames at 32px x 16px and 25 frames at 400px x 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.

Actor

To make sprites that can face in four directions turning towards the player, create a 48px x 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.

Animated Actor

To make sprites that have animated movement, or that can be used as a player character, create a 96px x 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.


Backgrounds

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 assets/backgrounds folder.

Requirements

Background PNGs must only contain the following four colors:

#071821
#306850
#86c06c
#e0f8cf
Download the GB Studio Palette Swatches for:
Adobe Photoshop
Aseprite

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 8pxx 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 160px x 144px (the screen size) and currently a background can be no larger than 256px x 256px.

An image can contain no more than 192 unique 8px x 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.


UI Elements

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.

ascii.png

Edit this file to change the game’s font when talking to actors in your game.

frame.png

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.

cursor.png

This image is used as a selection cursor when showing multiple choice options in your game.

emotes.png

This image used to define the look of the emote bubbles that can be shown above actors using scripting. Each bubble is 16px x 16px in size and the each bubble represents Shock, Question, Love, Pause, Anger, Sweat, Music and Sleep in that order left to right.

Requirements

With the exception of emotes.png which follows the standard sprite requirements, UI PNGs must only contain the following four colors:

#071821
#306850
#86c06c
#e0f8cf
Download the GB Studio Palette Swatches for:
Adobe Photoshop
Aseprite

Music

GB Studio is internally using GBT Player (GameBoy Tracker). Additional documentation and sample MOD files can be found in its own repository.

If you’re unfamiliar with making tracker music, you can follow a video series like Y_VE_Squared’s OpenMPT tutorial, Gruber’s MilkyTracker tutorial, wasp amiga’s ProTracker tutorial and many others. These videos cover how to navigate a tracker program and are well-designed for tracker beginners.

For Windows and Linux (WINE) users, OpenMPT is the most functional of the trackers for loading and creating .mod files. Alternatively, MilkyTracker, 8bitbubsy’s ProTracker/FastTracker II Clones and the browser-based BassoonTracker work on all platforms and can be used to create .mod files for GBT Player.

Getting Started

  1. Create a blank GB Studio project, find the file assets/music/template.mod and open it with your tracker.
    • You must edit this file to hear accurate Gameboy instruments in your tracker.
    • MilkyTracker users should save this file as an .xm file. 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.
  2. Keeping the instrument data, delete/modify template.mod’s song data.
  3. 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, 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.

Important Limitations

The .mod filetype only allows 4 channels of audio. For GBT Player, each channel has its own limits when composing.

Channel # Sound Note Range* Instrument Range Effects Allowed
Channel 1 Pulse C3 to B8 1-4 All listed effects
Channel 2 Pulse C3 to B8 1-4 All listed effects
Channel 3 Wave C3 to B8 8-15 0, E8 and EC
Channel 4 Noise Only C5 16-31 B, C, D, EC, E8 and F

*This note range is for trackers that display notes between C1 and C8 such as OpenMPT. Trackers that display notes between C0 and C7 such as MilkyTracker should use transpose these guidelines an octave down (as in, C3 to B8 in MilkyTracker becomes C2 to B7).

Instrument List

These instruments are listed by their hexadecimal numbers.

The pulse channels use 4 instruments from 1 to 4:

# Waveform
1. 25% pulse
2. 50% pulse (square wave)
3. 75% pulse (inverted 25% pulse)
4. 12.5% pulse

The wave channel uses 8 instruments from 8 to F in hexadecimal:

# Waveform
8. Buzzy
9. Ringy Buzz
A. Sync Saw
B. Ring Saw
C. Octave Pulse + Triangle
D. Sawtooth
E. Square
F. Sine

The noise channel uses 16 instruments from 10 in hexadecimal to 20 in hexadecimal:

Inst. Range Waveforms
10hx to 17hx Periodic (looped) noise at various pitches
18hx to 20hx Pseudorandom noise at various pitches

Tempo/Speed

Project tempo is not carried over to GBT Player. Effect F is read as your song’s speed. F defines how many in-game frames should pass before the next note of the .mod file is played. F01 is the fastest speed and plays 1 tick every frame. F1F is the slowest speed and plays 1 tick every 32 frames. All trackers are compatible with this effect and they will change the project’s speed to match effect F.

For faster speed settings between F01 and F04 the Project BPM should be set to 150 BPM to emulate the Gameboy’s refresh rate. This data is only read in the tracker software and can be adjusted if needed.

Effect F can be set on any channel except channel 3. Channels 2 or 4 are best used to set speed since channel 1 will automatically start the song by playing at full volume unless it has effect C00 added to silence it.

Volume Limitations

Channel 4 has full volume range from 0 to 40 in hexadecimal. Channel 3 will only display volume changes of 00, 10, 20 and 40.

Channels 1 and 2 only have a quarter of the full volume range, and only volume changes in steps of 4 are registered. Here are all the volumes they will register in hexadecimal:

0, 4, 8, C, 10, 14, 18, 1C, 20, 24, 28, 2C, 30, 34, 38, 3C, 40

Full List of Effects

EFFECT NAME NOTES
0xy Arpeggio Plays 3 notes rapidly. x and y’s values represent the number of semitones above the original note. x is for the 2nd note, y is for the 3rd note. You should set the instrument when using this effect.
Bxx Jump Jump to specific pattern xx. Put this on the last heard note of a pattern.
Cxx Volume Set the volume of a note to xx from 00 to 40. A volume effect should be set on each new note since note volume is not reset in-game unlike most trackers’ global volume setting.
Dxx Pattern break Jumps to the next pattern early, where xx is the position (row) it should jump to in the next pattern.
E8x Pan Set the panning to x. 0-3 = Hard Left, 4-B = Center, C-F = Hard Right
ECx Note cut Cut the note after x ticks. 0 < x < speed-1
Fxx Set speed Sets the song speed to xx. Valid values are 01 to 1F. The value represents how many frames the game should wait before moving on to the next note of the song.

General Tips

OpenMPT Keyboard shortcuts: For the default keyboard layout.

Change the selected note, instrument, or effect, value using Crtl +, Crtl - or Crtl & Scroll wheel

Change your current instrument using CRTL & Arrow Up or Down

Move between patterns with CRTL & Arrow Left or Right


Building Your Game

Play

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.

Build Terminal

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 480px x 432px.

Troubleshooting

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.

xcode-select --install

On Windows you may need to whitelist the application in your Anti Virus software to perform a build.