993 views

 

75% Opilion

::|CONTENTS

1. Capabilities
2. Quick set-up
3. Expert tricks
4. Links for further development
5. See also

Krawall is a sound engine for the Game Boy Advance that can add music and sound effects to a ROM from .s3m and .xm modules.

It was used in commercial games like The Lord of the Rings, Spider-Man, and The Sims. Its source code has been available on GitHub since 2013.

Capabilities

---

A detailed list of Krawall's capabilities can be found here

as well as in the Krawall documentation

.

Quick set-up

---

Download the source code of Krawall from GitHub:
https://github.com/sebknzl/krawall/tree/master

To compile Krawall, you will need the devkitPro framework. To install this, follow the instructions corresponding to your operating system on this page:
https://devkitpro.org/wiki/Getting_Started

devkitPro has various components related to making games on different consoles. To use Krawall, you will only need the Game Boy Advance component.

devkitPro comes bundled with Maxmod, another Game Boy Advance sound engine. We will setup Kramwall with a similar method, but the process will be harder than it is with Maxmod, so you are encouraged to set up Maxmod first before trying Krawall.

For Windows users, there is a gentle introduction to the MSYS2 shell in the Maxmod lyceum page. We will assume here that you already know all the shell commands that were presented in this article.

Setting up MSYS2 (Windows)
You will need a C++ compiler to build Krawall, but it's not something you have on the default MSYS2 installation from devkitPro.

Enter the following command to install one called g++:

pacman -S gcc

Setting up your environment variables (Linux)
On Linux, you need to set up some devkitPro path variables. Assuming devkitPro is installed under /opr/devkitpro, add the following lines to your .bashrc:

export DEVKITPRO=/opt/devkitpro


export DEVKITARM=/opt/devkitpro/devkitARM


export DEVKITPPC=/opt/devkitpro/devkitPPC

In addition, you need to use:

source /etc/profile.d/devkit-env.sh

This command needs to be used for each shell session, before compiling Krawall. It can be convenient to set up an alias like this one:

alias setdevkitenv="source /etc/profile.d/devkit-env.sh"

Obtaining an old version of CMake (Windows/Linux)
In order to build Krawall, a program called CMake is required. You can check if it's installed on your computer with the command:

cmake --version

Pay attention to the command output, if your CMake version is lower than 4.0 you can skip this step. More recent versions won't be compatible with Krawall, so if you have a too recent CMake version or if it's not installed at all, you will have to download an old CMake release.

On Linux
Old CMake releases are archived on the CMake GitHub Releases page

, find version 3.31.6 and download the tar.gz archive corresponding to your processor architecture. Create an empty directory called cmake-3.31.6 (for instance in the Krawall main directory, alongside build.sh), then move the tar.gz archive into it and extract the files with:

tar xf <your archive name>.tar.gz

Then edit the build.sh script, replacing the line cmake .. by:

<full path to cmake-3.31.6>/bin/cmake ..

For instance, this could be:

~/Downloads/krawall/cmake-3.31.6/bin/cmake ..

On Windows
Since it depends on MSYS2, building Krawall on Windows requires a version of CMake specially made for MSYS2. Unfortunately the CMake version on the main MSYS2 repo is too recent

and older releases aren't archived (to be precise only the PKGBUILD scripts are archived

, not the binaries).

However old versions of CMake are still available on MSYS2 mirrors, like the extreme-ix.org mirror

. You can get CMake 3.31.5 from here, this should be working at least with the 64-bit (x86_64) version - please give us feedback on the discussion page if you were able to use the 32-bit (i686) version)! Here are direct download links for you comfort:
- CMake 3.31.5 - 32-bit (i686)

- CMake 3.31.5 - 64-bit (x86_64)

Just in case, these two files are now mirrored on Google Drive

.

Once you got one of the .zst files, put it in a folder, access it from MSYS2 and install CMake with:

pacman -U <your file name>.zst

If a more recent version of CMake was installed, it will be downgraded. If you need to switch back to a recent CMake version, you can reinstall the latest version available on MSYS2 with:

pacman -S cmake

Configuration
Krawall comes with some example programs that show its capabilities and can be used to learn how to use the API.

We will modify one of these programs to play a custom .s3m/.xm module file.

You will find a directory called examples just under the Krawall top folder. It is structured like this:

examples/


├── CMakeLists.txt


├── callback.c


├── crt0


│   ├── crt0.s


│   ├── lnkscript


│   └── readme.txt


├── interrupt.c


├── jinglesong.c


├── modules


│   ├── CMakeLists.txt


│   ├── secondpm.s3m


│   ├── sfx.xm


│   └── tf_iesc.xm


└── simple.c

It contains the source code of four different programs: callback, interrupt, jinglesong and simple. Each one will produce its own ROM when Krawall will be compiled.

They use sounds from the module files located in the directory modules: secondpm.s3m, sfx.xm and tf_iesc.xm.

Compiling the example roms
We will first compile Krawall with no modification to see if everything is set up correctly.

Go to the top directory top directory from your shell, it contains a file called build.sh. This is a script (ie: a recipe) to automatically build Krawall from its source code. Use from the command line with:

./build.sh

If everything went correctly, Krawall is now compiled in a directory called build. The ROM produced by the examples programs are .bin files bundled in a directory called examples. Its location can vary depending on your system but it will always be in the build directory, it can be for instance:

• build/krawall/examples on Linux
• build\krawall\src\krawall-cross-gba-build\examples on Windows

Now you can open any of the .bin files on an emulator.

Notes:
- on Windows, you may get error messages at the end of the process, after the .bin ROMs are generated. If you manage to get .bin files, you should probably not worry too much about these.
- you should remove any existing build folder before using build.sh again, else it will complain about it and do nothing.


Hacking an example program
Using a text editor, open the source code file named simple.c from before.

Replace its content with this code:

/*


 * Krawall, XM/S3M Modplayer Library


 * Copyright (C) 2001-2005, 2013 Sebastian Kienzl


 * 


 * This library is free software; you can redistribute it and/or


 * modify it under the terms of the GNU Lesser General Public


 * License as published by the Free Software Foundation; either


 * version 2.1 of the License, or (at your option) any later version.


 * 


 * This library is distributed in the hope that it will be useful,


 * but WITHOUT ANY WARRANTY; without even the implied warranty of


 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU


 * Lesser General Public License in COPYING for more details.


 */





/*





Example "simple" (hacked - minimal version):





Just play a song.





*/





#include <gba.h>


#include "krawall.h"


#include "modules/modules.h"


#include "modules/samples.h"


#include "modules/instruments.h"








int main()


{


	ihandle engine = 0;





	irqInit();


	irqSet( IRQ_TIMER1, kradInterrupt );


	// not really needed, as kragInit also enables IRQ_TIMER1


	irqEnable( IRQ_TIMER1 );


	REG_IME = 1;





	SetMode( MODE_0 | BG0_ON );





	kragInit( KRAG_INIT_STEREO );                   // init krawall


	krapPlay( &mod_secondpm, KRAP_MODE_LOOP, 0 );   // play a .s3m module


	// krapPlay( &mod_tf_iesc, KRAP_MODE_LOOP, 0 );    // play a .xm module





	// Edit modules/CMakeLists.txt to add new modules:


	// krapPlay( &mod_mycoolsong, KRAP_MODE_LOOP, 0 );








	while( 1 ) {


		// wait for line 0


		while( !REG_VCOUNT );


		while( REG_VCOUNT );





		kramWorker();        // do the stuff


		


	}





	return 0;


}

Delete your build directory and compile Krawall again using the same process. Then open the ROM called simple.bin, now it should simply be playing music with a black screen.

Playing your own songs
In the directory examples, open the sub-directory called modules (see the tree above).

If your song is a .s3m module, delete the file named secondpm.s3m and replace it by a copy of your song called secondpm.s3m.
If your song is a .xm module, do the same thing with the module tf_iesc.xm.

Have a look at these two lines from the source code file simple.c:

krapPlay( &mod_secondpm, KRAP_MODE_LOOP, 0 );   // play a .s3m module


//krapPlay( &mod_tf_iesc, KRAP_MODE_LOOP, 0 );    // play a .xm module 

As it is now, it's configured to play the module secondpm.s3m. If your module has the .xm extension, edit it this way:

//krapPlay( &mod_secondpm, KRAP_MODE_LOOP, 0 );   // play a .s3m module


krapPlay( &mod_tf_iesc, KRAP_MODE_LOOP, 0 );    // play a .xm module

Save your modifications, then delete your build directory and recompile Krawall as explained before.

Open the ROM file simple.bin in an emulator, it should now play your song!

Composing
The GBA only supports mono 8-bit samples, Krawall can convert 16-bit samples to 8-bit for you but don't use stereo samples! You can use for instance Audacity

or MODPlug Tracker to convert all you samples beforehand.

The maximum number of channels you are allowed to used is:

• 16 for a .s3m module
• 32 for a .xm module

The documentation features a Musician's Guide

with advice on composing music with Krawall.

You can also read the chapter called "Effects" in the Developer's Handbook

for a complete reference of the .s3m/.xm effects you can use in your modules.

Note: if you already downloaded Krawall, you will find these guides in the directory called "docs".

Expert tricks

---

You can use custom names for your song modules instead of secondpm.s3m or tf_iesc.xm.

Let's assume your song is a module called vombot.xm, look at the following lines:

//krapPlay( &mod_secondpm, KRAP_MODE_LOOP, 0 );   // play a .s3m module


krapPlay( &mod_tf_iesc, KRAP_MODE_LOOP, 0 );    // play a .xm module





// Edit modules/CMakeLists.txt to add new modules:


// krapPlay( &mod_mycoolsong, KRAP_MODE_LOOP, 0 );

Edit them this way:

//krapPlay( &mod_secondpm, KRAP_MODE_LOOP, 0 );   // play a .s3m module


//krapPlay( &mod_tf_iesc, KRAP_MODE_LOOP, 0 );    // play a .xm module





// Edit modules/CMakeLists.txt to add new modules:


krapPlay( &mod_vombot, KRAP_MODE_LOOP, 0 );

Note that we have changed the position of a double slash // and renamed &mod_tf_iesc with this convention: &mod_ followed by the name of your module file without the extension.

Add vombot.xm to the folder named modules and modify the content of the file CMakeLists.txt from the same directory. This is the original CMakeLists.txt:

include( KrawerterHelpers )





# calls krawerter on these mods and creates a "modules" target


build_module_library( secondpm.s3m tf_iesc.xm sfx.xm )

Add your song to the list of songs to convert:

include( KrawerterHelpers )





# calls krawerter on these mods and creates a "modules" target


build_module_library( secondpm.s3m tf_iesc.xm sfx.xm vombot.xm )

You can now delete your build directory and recompile Krawall.

Links for further development

---

Krawall was uploaded on GitHub by its developer Sebastian Kienzl, it is no longer developed since 2013.

You can check both the GitHub page

and the post

made by Sebastian Kienzl on his website regarding the upload and the work he made on Krawall at the same time.

See also

---

- GameBoy Advance
- Maxmod
- s3xmodit (format)
- UnkrawerterGBA