::|CONTENTS
- Capabilities
- Quick set up
- Links for further development
- See also
GBT Player is a set of libraries and converter tools to make music on the
Game Boy (GB) and the
GameBoy Advance (GBA).
Anything related to the GBA is written in C, while the GB part of the project uses assembly language and relies on
RGBDS. As of version 4.0.0, there is a split between the GBA and GB versions. The GBA branch is ahead of development, changes are meant to be included later in the GB version.
Note that there is a legacy version of the GB branch relying on
GBDK instead of RGBDS.
Capabilities
Converting .mod and .s3m files
GBT Player is constituted of three core elements:
- GBT Player: a library to play GBT files on the GB and GBA
- s3m2gbt: a tool to convert .s3m modules to GBT (only compatible with the GBA)
- mod2gbt: a tool to convert .mod modules to GBT (GB only)
GBT Player features scripts that can be used from the command line to convert your .mod/.s3m modules directly to GB/GBA roms.
Note: GBT Player also has a legacy mod2gbt converter for the GBA, it was used as the sole GBA converter before s3m2gbt was introduced. mod2gbt doesn't support any feature introduced afterward. If you really want to use the .mod format, you might as well convert your module to .s3m using for instance OpenMPT, then use the s3m2gbt converter.
Using it with a sound engine (GBA)
Concerning the GBA, GBT Player by itself can only use the PSG channels. However, it can be used in combination with a sound engine like
Maxmod or
Krawall so that you can make music using both the PSG and the Direct Sound units.
There is an example called
combined_maxmod that you can reuse as a template. It lets you use the same .s3m file to make music using both GBT Player and Maxmod!
However, there is no such example regarding Krawall. Hence you will have to program it by yourself to use GBT Player with this sound engine.
If you are able to do this or if you find an example online, please consider adding a link to it on this page!
Wave channel capabilities
The GB and the PSG unit of the GBA have a channel capable of playing short samples, which is often called the "wave channel" or "channel 3". All GBT Player templates share a same set of wave samples, meant to be played on this channel.
When making GB music, you cannot change these default wave samples.
When making music for the GBA, you can replace any of these sample by a custom sample that is exactly 32 or 64 samples long. In addition, you are allowed to change the default volume of the samples. However keep in mind that:
- you can't change the default tuning of any sample
- you can have wave samples only in the samples slot 8 to 15 of your .s3m module
Quick set up
You can get GBT Player on the dedicated
GitHub page! No installation is required, just put the whole gbt-player folder in a convenient location.
The content of gbt-player should look like this:
gbt-player
├── changelog.rst
├── gb
├── gba
├── LICENSE
└── readme.rst
The directory called "gb" contains the Game Boy version of GBT Player, while "gba" contains the Game Boy Advance branch.
Configuration
Game Boy
Open the gb folder from gbt-player. It will contain these two directories:
- legacy_gbdk: the old GBDK-based version of GBT Player
- rgbds: the current version, relying on RGBDS
These are two libraries used to develop GB games. As the newest features of GBT Player were only added to the RGBDS branch, we will focus on using this library. Open the directory called rgbds, inside you will find two directories:
- mod2gbt: contains the mod2gbt convertor and its related files
- rgbds_example: it's were you will be converting your .mod modules to GB ROMS
Compiling the mod2gbt convertor
Open the mod2gbt folder. You may notice it doesn't contain any executable file called mod2gbt. You will have to generate it by compiling its source code!
Linux
GCC and GNU Make are probably already installed on your system. You simply have open a shell, go to the mod2gbt folder and use:
make
You should now see an executable file called mod2gbt, try running it to see if it works:
./mod2gbt
macOS
It seems you can install GCC from the
Homebrew package manager, you will find more details on the
GCC Homebrew page.
If you are a macOS user, please consider adding content to this part!
Windows
We will see how to compile mod2gbt using
MSYS2, which provide an environment similar to Linux inside Windows.
If you also intend to make music for the GBA, installing devktiPro will suffice as it comes with its custom version of MSYS2 (see the second part of this "Configuration" section, related to the GBA). Else, you can install the regular version of MSYS2 by following the
installation tutorial.
Note: if you never used MSYS2 or Unix shell commands before, you can read the Maxmod lyceum page for a more gentle introduction.
Open a MSYS2 window, see if GCC is already installed by using the command:
gcc --version
If instead of returning the current version of GCC, it shows you an error like this one, it means you will have to install GCC:
bash: gcc: command not found
Install GCC with this command:
pacman -S gcc
It will show you a message like this:
resolving dependencies...
looking for conflicting packages...
Packages (8) binutils-2.43.1-1 isl-0.27-1 mpc-1.3.1-1 msys2-runtime-devel-3.5.4-2
msys2-w32api-headers-12.0.0.r0.g819a6ec2e-2 msys2-w32api-runtime-12.0.0.r0.g819a6ec2e-2
windows-default-manifest-6.4-2 gcc-13.3.0-1
Total Download Size: 51.84 MiB
Total Installed Size: 411.24 MiB
:: Proceed with installation? [Y/n]
Enter Y to continue the installation.
Once it's done, you should be able to use the command gcc --version ! Now you will have to use the command line to go to mod2gbt directory. Assuming you extracted the GBT Player .zip archive in your Downloads folder, you can do it with a command like this one:
cd Downloads/gbt-player-4.4.1/gbt-player-4.4.1/gb/rgbds/mod2gbt/
Now use this command to compile mod2gbt:
make
See the content of the mod2gbt directory with:
ls
If everything went well, you will see a program called mod2gbt.exe, run it from the command line to test if it works fine:
./mod2gbt.exe
Obtaining RGBDS
You will need RGBDS to make GB ROMs. However, the latest version of RGBDS won't work with GBT Player. RGBDS 0.5.2 is compatible with all GBT Player versions starting from 3.1.0, go to the RGBDS 0.5.2
release page and download the archive corresponding to your operating system.
In the downloaded archive, you will find among other things three executable files called: rgbasm, rgbfix and rgblink. Copy them in the gb/rgbds folder, alongside the directories mod2gbt and rgbds_example:
gb
└── rgbds
├── mod2gbt
├── rgbasm
├── rgbds_example
├── rgbfix
└── rgblink
Compiling your first ROM
Open the directory named rgbds_example, it contains three noticeable files:
- template.mod: the .mod song that will be used by the GB ROM
- make_rom.sh: the program you will use on macOS and Linux to generate the ROM, it can also be used on Windows with MSYS2
- make_rom.bat: a program to generate the ROM on Windows, it doesn't require MSYS2 and it can be used directly from the file explorer (without using the command line!)
Making the ROM with make_rom.sh
You first have to modify make_rom.sh, open it in a text editor and search for this line:
../../mod2gbt/mod2gbt template.mod song
Replace it by this:
../mod2gbt/mod2gbt template.mod song
Open either a shell on macOS/Linux or a MSYS2 session on Windows and go to the rgbds_example directory. To compile the ROM, you just need to run make_rom.sh:
./make_rom.sh
You should now see a GB ROM called gbt_test.gb in the rgbds_example directory. Open it in an emulator to see if it works!
Making the ROM with make_rom.bat
You first need to modify make_rom.bat, open it in a text editor like Notepad and find this line:
..\..\mod2gbt\mod2gbt template.mod song
Replace it by:
..\mod2gbt\mod2gbt template.mod song
Then, open the rgbds_example directory using the file explorer. Run make_rom.bat by double-clicking on it. This will open a cmd window, once it's done, it will leave this message:
Press any key to continue . . .
Look again in the rgbds_example directory, you should now see a GB ROM called gbt_test.gb. Open it in an emulator to see if it works well!
Note: if you are confident with using the command line, you can also run make_rom.bat directly from cmd (aka Command Prompt), without using the file explorer.
Troubleshooting on Windows
If Visual C++ isn't installed on your system, you may encounter one of these two errors:
- When using make_rom.sh: the program seems to run well but no GB ROM is actually produced
- When using make_rom.bat: no ROM is made either and you get this kind of error message:
The code execution cannot proceed because VCRUNTIME140.Dll was not found.
If that's the case, you can try to fix this by installing the latest version of Visual C++ Redistributable from its
download page.
Try to run either make_rom.sh or make_rom.bat again to see if it solved the problem!
What's next?
The ROM you compiled with make_rom.sh (or .bat) is a minimal GB game that simply plays the music from template.mod.
In order to play your own songs, you just need to edit template.mod and run make_rom.sh or make_rom.bat again. See the section "Composing" of this page for more information about how to make .mod songs with GBT Player.
Note: don't rename template.mod with a different name or you won't be able to run the make_rom programs. To change the default template.mod name, you can edit the make_rom program you want to use (make_rom.sh or make_rom.bat) and replace "template.mod" by a new name.
Game Boy Advance
You will need to install
devkitPro, follow the instructions for your operating system on the
Getting Started page. devkitPro is a bundle of numerous libraries to make games on various consoles. In order to use GBT Player, you only need the GBA related components.
At this point, if you are not familiar with the command line, you will probably want to read the
Maxmod lyceum page, which is targeted to people with no prior experience. We will assume in this section that you are able to use the commands that were introduced in the Maxmod page.
Note: as Maxmod is a part of devkitPro, you can try to make a GBA ROM with Maxmod first so as to get more familiar both with using the command line and devkitPro
Compiling the basic example
This will prove to be useful to see if dekitPro was correctly installed and also to learn how to use GBT Player.
File structure
Open either MSYS2 if you are on Windows or a shell if you are on macOS or Linux. Using the command line, go to the location of the gbt-player folder you downloaded earlier. Then go to the gba directory:
cd gbt-player
cd gba
Using the command ls, you can see that gba contains a directory called examples. Go to this directory:
cd examples
examples contains multiple directories, these are all the GBT Player examples. As we are interested in the basic example, go to its directory:
cd basic
Each GBT Player example contains two noticeable files:
- a .s3m module used to compose music (here it's called template.s3m)
- a shell script called make_rom.sh that can generate a GBA ROM from the .s3m module
Preparatory work (Windows)
If you are not running Windows, skip directly to the part called "Making the ROM".
As s3m2gbt is actually a python script, we'll first need to install python within MSYS2. To do this, use the command pacman as follows:
pacman -S python
It will show you a message like this one:
resolving dependencies...
looking for conflicting packages...
Packages (2) mpdecimal-4.0.0-1 python-3.12.7-1
Total Download Size: 22.46 MiB
Total Installed Size: 182.13 MiB
:: Proceed with installation? [Y/n]
Enter Y pursue the installation.
Now open a file explorer window and go to the directory of the basic example. Alongside template.s3m and make_rom.sh, you will find a folder called source. Open it.
It contains a file called gbt_player. This is supposed to be a Unix symbolic link, something a bit similar to shortcuts on Windows. The problem is that symbolic links don't work at all on Windows, so we will have to replace it by a copy of the folder it was meant to redirect to.
Delete the gbt_player file. Now search in the gba directory for a directory called gbt_player:
gba
├── docs
├── examples
├── gbt_player
├── mod2gbt
├── readme.rst
├── s3m2gbt
├── s3msplit
└── tests
Copy this directory and paste it in source, replacing the file you deleted.
Making the ROM
Run the make_rom.sh script to generate the GBA ROM of the basic example:
./make_rom.sh
If everything went well, you should now see a file called basic.gba in the basic folder. Check this using ls:
ls
This file is a GBA ROM, you can open it in a GBA emulator and it should play the music from template.s3m!
Troubleshooting on Linux/macOS
On Linux or macOS, you may encounter an error like this when you run make_rom.sh:
Makefile:7: *** "Please set DEVKITARM in your environment. export DEVKITARM=<path to>devkitARM. Stop.
or
/opt/devkitpro/devkitARM//gba_rules:2: *** "Please set DEVKITPRO in your environment. export DEVKITPRO=<path to>devkitPro. Stop.
As it is told by the error messages, you will resolve this by setting the environment variables DEVKITARM and DEVKITPRO to their related path.
export DEVKITARM=/opt/devkitpro/devkitARM/
export DEVKITPRO=/opt/devkitpro/
This should be correct on most devkitPro installations, adapt these paths to your system if you didn't install devkitPro under /opt. You can add these two lines to your .bashrc if you don't want to type it each time you want to use GBT Player.
What's next?
Once you are able to compile the basic example, you can start making music for the GBA simply by modifying the template.s3m module. See the section "Composing" of this page for further information.
Although you can make music this way, you will probably find it quite limited as the basic example is only able to use the PSG channels. You will have to use the combined_maxmod example in order to use the Direct Sound unit.
Compiling the combined_maxmod example
The process is identical to compiling the basic example. If you were able to generate a GBA ROM in the previous section, this should go smoothly!
Remember that all the GBA examples of GBT Player are located under:
gbt-player/gba/examples
Go to the directory called combined_maxmod. If you are using Windows, open the source folder from the file explorer and replace the file called gbt_player, as you did for the basic example.
Then compile the example using:
./make_rom.sh
You should see a GBA ROM called combined_maxmod.gba, open it in a GBA emulator to see if it works!
You can compose your own music by editing template_combined.s3m, see the section "Composing" of this page for more details!
Composing
You will need a music software capable of editing .mod modules if you are targeting the GB, or .s3m modules for the GBA.
Schism Tracker and
MODPlug Tracker are two trackers you can use with both of these formats. See the
s3xmodit (format) page in the lyceum for more details regarding .mod and .s3m modules.
Game Boy
Open template.mod from the rgbds_example directory.
Each channel of the .mod module is mapped to a GB channel:
- Channel 1 <-> Pulse 1
- Channel 2 <-> Pulse 2
- Channel 3 <-> Wave
- Channel 4 <-> Noise
You can see that template.mod already have default samples, their names indicate in which channel they can be used. The samples are used by the mod2gbt convertor to set different parameters influencing how a note should be played.
- Channel 1 & 2 samples (Pulse) let you choose a duty cycle when playing square waves
- Channel 3 samples (Wave) let you choose between different wave forms
- Channel 4 samples (Noise) let you choose between all the sounds that can be produced with the GB's noise generator
Note: in the channel 4, the sound of a note is only defined by its sample. Hence for a given sample, all notes played in the channel 4 will be converted to a same sound by mod2gbt! You should set all the notes to C5 in this channel to get a sound that will be the closest to what you will hear on the GB.
You should neither reorder nor modify any sample in template.mod! As mentioned in the section "Capabilities", it is currently impossible to use custom wave samples on the GB when using GBT Player.
Some of the .mod effects are compatible with the .mod2gbt convertor, a full list is available in the
mod2gbt documentation. The documentation also includes additional information on using .mod modules with GBT Player, so it's worth to check it out!
Note: the mod2gbt documentation can also be read offline, open the file mod_instructions.txt in the mod2gbt directory.
Game Boy Advance
Open a .s3m template from the GBT Player examples.
Using the PSG
Composing music for the PSG is done through the channels 1 to 4 of your .s3m module. Each one is associated to a channel of the PSG:
- Channel 1 <-> Pulse 1
- Channel 2 <-> Pulse 2
- Channel 3 <-> Wave
- Channel 4 <-> Noise
.s3m templates have default samples, their names mention in which channel they can be used. They serve to indicate to the s3m2gbt convertor different parameters influencing how a note should be played.
- Channel 1 & 2 samples (Pulse) let you choose a duty cycle when playing square waves
- Channel 3 samples (Wave) let you choose between different wave forms
- Channel 4 samples (Noise) let you choose between all the sounds that can be produced with the PSG's noise generator
Note that in the channel 4, the sound of a note is only defined through its sample. Hence for a given sample, all notes played in the channel 4 will be converted to a same sound by s3m2gbt! You should set all the notes to C5 in this channel to get a sound that will be the closest to what you will hear on the GBA.
You should neither reorder nor modify the samples associated to the channels 1, 2 and 4. Samples for the channel 3 can be reordered, but they have to fit in the sample slots 8 to 15. They can also be modified if they are replaced by samples that are exactly 32 or 64 samples long.
Some of the .s3m effects are compatible with GBT Player, see the
s3m2gbt documentation to know how to use them. In addition, consulting the documentation is really worthwhile to learn about other s3m2gbt quirks that couldn't fit on this page.
Note: this documentation is also available offline in the file readme.rst, located in gbt-player/gba/s3m2gbt.
Using the Direct Sound unit
In this specific case, you will need to use the .s3m template from the combined_maxmod example.
A .s3m modules has 16 available PCM channels. As seen before, the 4 first channels are used by the PSG. You can use the other 12 channels to compose sample based music that will be played on the Direct Sound unit using Maxmod.
All the samples used on channels 5 to 16 have to be located in the slot 32 or greater, as the samples 1 to 31 will not be sent to Maxmod. Furthermore, the GBA only supports 8-bit mono samples. Maxmod will automatically convert 16-bit samples to 8-bit but using stereo samples will result in an error when making the ROM.
There are two important quirks you need to know about before you start making music!
Enabling all the PCM channels
Even though GBT Player combined with Maxmod is capable of using 12 PCM channels, only for 4 channels are actually enabled in the default configuration of the combined_maxmod example. Let's see how to get all the 12 channels enabled!
Open the directory of the combined_maxmod example. Inside, along with the .s3m template and the make_rom.sh script, you should find a directory called source. Open it, it will contain a file called main.c.
main.c contains the source code of the GBA ROM you are building each time you use make_rom.sh. Open it using a text editor (such as the Notepad application on Windows).
Search for these two lines (you will find them near the end of the file):
// Initialize maxmod with soundbank and 4 channels
mmInitDefault((mm_addr)soundbank_bin, 4);
You simply have to replace the value 4 by the number of PCM channels you want to use. So in our case:
// Initialize maxmod with soundbank and 12 channels
mmInitDefault((mm_addr)soundbank_bin, 12);
From now on, all the GBA ROM you create with make_rom.sh will have all their 12 PCM channels enabled!
Note: the more PCM channel you use, the more the GBA will use CPU resources to handle the audio mixing. When making music for a game, you will probably have to enable a lower number of channels.
File split and .s3m effects
First we need to see how GBT Player is able to work alongside Maxmod.
When you run make_rom.sh, the script uses a GBT Player tool called s3msplit to divide your .s3m template into two smaller .s3m modules.
- One contains the pattern data from the channels 1 to 4, as well as the samples 1 to 31. It is then transmitted to s3m2gbt to make music for the PSG.
- The other one contains the pattern data from the channels 5 to 16, as well as all samples starting from sample 32. It is sent to Maxmod to make music for the Direct Sound unit
Finally the source code in main.c is written in a careful way, so that the music coming from the PSG and the Direct Sound units is played synchronously.
That being said, it is important to notice that any effect affecting your whole .s3m module, such as Axx (set song speed) or Cxx (break to row xx of next pattern), needs to be applied twice! Indeed, you have to use it once in channels 1 to 4 and once in channels 4 to 16, both times on the same row. If you don't, it won't be applied on one of the .s3m modules generated by s3msplit, thus leading to some unexpected behaviors when playing the GBA ROM.
For further information about using GBT Player with Maxmod, see the related GBT Player
documentation. It is also available offline, in the file readme.rst located in gbt-player/gba/examples/combined_maxmod.
Links for further development
The development of GBT Player is still active, you can visit the project's
GitHub page for further information!
See also
All related Lyceum articles:
referencing to:
-
Game Boy
-
GameBoy Advance
-
Krawall
-
Maxmod
-
MODPlug Tracker
-
s3xmodit (format)
-
Schism Tracker
referenced from:
-
GameBoy (format)
-
GameBoy Advance
-
gba (format)
