butano

GBT Player is a music creation environment designed for the Game Boy family of consoles (GB, GBC, and GBA). It follows a workflow where you take a standard tracker file (MOD or S3M), convert it into the GBT (GameBoy Tracker) format, and then play it using the library.

The ecosystem consists of three main components:

1. GBT Player: The library used to play GBT format files on GB, GBC, or GBA.
2. s3m2gbt: A converter that transforms S3M files into GBT format (GBA only).
3. mod2gbt: A converter that transforms legacy MOD files into GBT format.

Note that S3M support is exclusive to the GBA version; GB/GBC versions only support the GBT format via MOD conversion.

The Apex Audio System (AAS) is a sound library designed for the Game Boy Advance (GBA). It provides a highly efficient mixer, support for up to 16 channels, and MOD playing routines. It is optimized for GCC-based development environments and supports the following input formats:

• RAW audio
• WAV files
• Tracker 1-16 channel MOD files

libugba is a C library designed for GBA game development. It supports two primary targets:

1. GBA ROMs: Build actual game ROMs to run on hardware or emulators.
2. PC (Linux/Windows/macOS): Build a dynamic library and executable to debug game logic on a PC using tools like GDB, or to run unit tests.

Most of the library is optional; developers should focus on the core interfaces described in the project's interface documentation. Note that the PC version behaves differently than the GBA version.

Maxmod is a library designed for playing music on the Game Boy Advance (GBA) and Nintendo DS. It provides support for several audio formats, including:

• MOD
• XM
• S3M
• IT
• WAV

The stdgba library is organized into several functional modules located under the gba/ namespace:

• Math: gba/fixed_point, gba/angle (deterministic arithmetic types).
• Display & Registers: gba/video, gba/sprite, gba/color, gba/peripherals.
• Hardware Control: gba/dma, gba/timer, gba/interrupt (scheduling and primitives).
• Validation: gba/testing, gba/benchmark (ROM-native validation and cycle measurement).
• Pipelines: gba/music, gba/format, gba/embed (compile-time authoring).
• Memory & Storage: gba/save, gba/overlay, gba/memory (cartridge persistence and memory helpers).

When using the MOD template for mod2gbt conversion, you must adhere to specific sample assignments for each channel. You are not allowed to change the default volume or the tuning of these samples.

Valid Sample Assignments:

• Channels 1 and 2: Samples 1 to 4
• Channel 3: Samples 8 to 15
• Channel 4: Samples 16 to 31. Note: You should always use C5 in your MOD song; changing the note in the MOD song will not change the sound.

While MOD files support a volume range of 0 to 64, the GBA hardware uses different constraints. The converter will automatically map your MOD volume to the closest valid GBA value.

Frequencies:

• Use notes from C3 to B8.

Volume Constraints:

• Channels 1, 2, and 4: Range of 0 to 15.
• Channel 3: Supports specific levels: 0%, 25%, 50%, 75%, and 100%.

Frequencies

• Use notes from C3 to B8.
• Note cuts using ^^ are supported.

Volumes

S3M uses a 0-64 volume range, but the GBA hardware uses different scales:

• Channels 1, 2, and 4: Range of 0 to 15.
• Channel 3: Discrete levels of 0%, 25%, 50%, 75%, and 100%.

The converter automatically maps your S3M volume to the closest valid value for the specific channel.

Channel Sample Rules

• Channels 1 and 2: Use Samples 1 to 4.
• Channel 3: Use Samples 8 to 15. These are modifiable.
• Channel 4: Use Samples 16 to 31. Note: Always use C5 in your S3M song; changing the note in S3M has no effect on the GBA sound.

Customizing Instruments

You can replace the samples for Channel 3. If the resulting sample is exactly 32 or 64 samples long, you can use the --instruments flag during conversion to export all valid instruments along with your song patterns. These will replace the default GBT Player instruments for the duration of the song.

Warning: You may change the default volume of samples, but do not modify the tuning of the samples.

To cross-build libagbabi.a into a build/ directory using Meson (version 0.56.2+), use the provided AGB cross-file.

meson setup build --cross-file=cross/agb.ini
meson compile -C build

To build gba-modern, you must use a Linux-based environment (use WSL if you are on Windows). The project requires g++ with C++17 support and the freetype library.

Before building, ensure all submodules are initialized. The build process uses a Makefile to generate assembly files for resources (tilesets, maps, and sprites) and compile the C++17 game source code. Upon successful completion, the ROM is generated at bin/game.gba.

git submodule update --init
make