Skip to main content

MOD Music

GBT Player is a legacy driver. By default, new projects use the built-in Music Editor.

You can enable GBT Player by setting Music Format in the Settings View to MOD (GBT Player).


Add music to your game by including .mod files in your project's assets/music folder. These files should be made for use with GBT Player. You can browse the GB Studio Community Assets to find free, GBT-compatible music under the MIT licence.

You can use software such as OpenMPT (for Windows or Linux using Wine), MilkyTracker (for Windows, Mac and Linux), ProTracker, and BassoonTracker (browser-based) to name a few.


It is recommended you read through your tracker's documentation:

Lastly, the GB Studio Discord also has a dedicated #music-help channel.

Getting Started

  1. Create a blank GB Studio project
  2. Find the file assets/music/template.mod and open it with your tracker of choice.
    • You must edit this file to get an accurate representation of the instruments you can use.
  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.
  4. Add a Play Music Track event to your game and select your song from the dropdown.
  5. Either click the Play button by the song name for an in-editor preview, or play the game for an in-game preview.

Because the .mod file format is not exclusively designed for gameboy, you should test your song in-game or in the Music preview window to catch audible differences between your tracker playback and GBT Player's output.

GBT Player's Channel Limitations

.mod files have 4 channels. Loading a copy of template.mod (included in every new project) will ensure this is set-up correctly.

Channel #Sound typeNote Range1InstrumentsEffects
Channel 1 & 2PulseC3 to B81-40, C, E8, EC, B, D, F
Channel 3WaveformC3 to B88-150, C, E8, EC 2
Channel 4NoiseOnly C516-31C, E8, EC, B, D, F

1 This range is for One-Indexed Trackers (C1 is the lowest-possible note). This is comparable to OpenMPT in default settings. Trackers that are Zero-Indexed by default (C0 is the lowest-possible note) should interpret these Note Ranges a full octave down. This is comparable to MilkyTracker in default settings.

Using default settings on OpenMPT and MilkyTracker, C3 to B8 in OpenMPT sounds the same as C2 to B7 in MilkyTracker.

2 Effects B, D, and F can be also used on Channel 3 if the same row isn't being used to set a note/instrument.


The nicknames and descriptions next to these instruments are not official for GBT Player, they are intended to help differentiate the instruments at a glance.

The pulse channels 1 and 2 have four instrument options:

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

Instruments 5 through 7 are intentionally left blank.

Channel 3, the wave channel, has 8 instrument options:

  1. Buzzy
  2. Ringy
  3. (A) Sync Saw
  4. (B) Ring Saw
  5. (C) Octave Pulse + Triangle
  6. (D) Sawtooth
  7. (E) Square
  8. (F) Sine

Instruments 16 to 23 use periodic noise at various pitches, while instruments 24 to 32 use pseudorandom noise at various pitches.

Periodic Noise:

  1. (10hx) "stutter" - A square plus a pulse at random pulse widths
  2. (11hx) "rumble" - The same waveform but faster
  3. (12hx) "engine" - The same waveform but even faster
  4. (13hx) "low tone" - Sounds like D5
  5. (14hx) "undertone" - Sounds like E5 + 50cents
  6. (15hx) "middletone" - Sounds like B5 + 50cents
  7. (16hx) "overtone" - Sounds like D6 + 50cents
  8. (17hx) "high tone" - Sounds like D7

Pseudorandom Noise:

  1. (18hx) "earthquake" - A square with a thin pulse at random pulse widths
  2. (19hx) "spaceship" - The same as 24 but faster
  3. (1Ahx) "ocean" - etc.
  4. (1Bhx) "scratch" - etc.
  5. (1Chx) "glitch" - A fairly clean white-noise sample, unrelated to other instruments
  6. (1Dhx) "volcano" - A pulse with rapidly changing pulse width
  7. (1Ehx) "scream" - The same as 29 but faster
  8. (1Fhx) "static" - etc.


Song effects

EffectNameDescriptionUsable by
BxxJumpJump to a specific pattern in the song.1, 2, 31, 4
DxxPattern breakJumps to the next pattern early, starting the pattern at row xx. This is the only way to shorten a pattern's length.1, 2, 31, 4
FxxSet speedSets the song speed to xx, from 0x1 (fast) to 0x1F (slow). This is the intended alternative to adjusting song tempo. xx represents the number of ticks per row. See Speed Table for more info.1, 2, 31, 4
1 Cannot be used by Channel 3 on rows where Channel 3 is playing a new note.

Channel effects

Persists on the channel until the effect is set again. See Effect Persistence for more info.

EffectNameDescriptionUsable by
9veVolume EnvelopeSets the note's starting volume at v (0-F), and adds a volume fade envelope. Fade direction and speed is set by e. 1-7 decreases volume over time, with 1 being fast. 9-F increases volume over time, with 9 being fast. 8 removes the envelope. Using 9ve after Cxx overrides Cxx.1, 2, 4
CxxVolumeSets the channel volume to xx. See Cxx Volume Limitations for more info. Using Cxx after 9ve overrides the v value, but keeps e the same.1, 2, 3, 4
E8xPanSets the panning to one of three values. 0-3 = 100% Left, 4-B = Centre, C-F = 100% Right.1, 2, 3, 4

Note effects

Affects a note individually.

EffectNameDescriptionUsable by
0xyArpeggioRapidly cycles between 3 notes. x and y represent the # of semitones above the starting note.1, 2, 3, 4
1xxPitch slide upSlides the pitch up by xx ticks. Putting 100 after a previous 1xx setting uses the same value as the previous setting.1, 2, 3
2xxPitch slide downSlides the pitch down by xx ticks. Putting 200 after a previous 2xx setting uses the same value as the previous setting.1, 2, 3
ECxNote cutCuts the note after x frames. Must be below the Fxx speed to be heard.1, 2, 3, 4

Effect Persistence

Once set, a channel effect will persist on that channel's notes until the same effect is set again.

In most trackers, if a note is played without a volume command, the note's volume is reset to the maximum. When a .mod file is converted by GBT Player, notes without a volume effect will play at the same volume as the previous Cxx effect.


ModPlug Tracker MOD

In any .mod 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. To make this note heard in-game, the volume must be set again:

ModPlug Tracker MOD

You can use EC0 as an alternative to C00 to cut notes and preserve the last volume effect.

Cxx Volume Limitations

Cxx sets the volume of a channel until Cxx effect or 9ve is used.

The Gameboy has 16 unique volume settings for Channels 1, 2 and 4. Although .mod files allow for volumes between 0 and 40hx, GBT Player will round-down these values effects to multiples of 4 to maintain compatibility. Here are the valid volume values for each of the channels:

Cxx Settings for Channels 1, 2 and 4:

00, 04, 08, 0C, 10, 14, 18, 1C, 20, 24, 28, 2C, 30, 34, 38, 3C

Any Cxx value that's not a multiple of 4 will be rounded-down to one of the above numbers.

Example: Entering C01, C02 and C03 will sound the same as entering C00.

Example: Entering C40 will sound the same as entering C3C.

Unique Volume Settings for Channel 3:

Channel 3 is an exception, with only 4 unique volume settings:

00, 10, 20, 40

GBT Player will round Cxx effects on Channel 3 toward the nearest number listed above.

Example: Entering C30 will round the volume up to C40.

Speed Table

This table assumes the -speed flag is not set in the Music window for each song.

Fxx Value (in most .mod trackers)BPM (in any . mod trackers)BPM (in game)
F011750 BPM900 BPM
F021375 BPM450 BPM
F031250 BPM300 BPM
F041187.5 BPM225 BPM
F05150 BPM150 BPM
F06125 BPM128.57 BPM
F07107.14 BPM112.50 BPM
F0893.75 BPM100 BPM
F0983.33 BPM90 BPM
F0A75 BPM81.82 BPM