Sound tags are used for things that make sound or play music.


OGG dll files: Link

These are required to compile non-crashing OGG encoded sound tags.

Xbox ADPCM Codec: Link

You'll need to install this to be able to compile Xbox codec encoded sound tags.

Note: The Xbox codec is also used in the PC and Custom Edition version of the game.


To store audio in our maps we use sound tags. Sound tags are compiled from wave files into either the xbox codec or the ogg codec.


tool sounds <source-file/folder> <compression> <quality>

This command is used to create a single sound tag file. From either a single wav file or a folder of wav files. A folder of wav files will be turned into a single sound tag with multiple permutations. If you give tool a source-folder that has sub-folders the sub-folders will be turned into sound tags with the same name in the respective path in the tags folder.

The compression can be either xbox, ogg, or wav.

Note: wav compressed sounds will not play in-game.

The quality should be a number from 0 to 1. 1 being the highest quality and 0 being the lowest. This value is usually left at 1.

Example: You have a set of wav files in data/foo/bar, a set of wav files in the data/foo/beef, and these sound tags will be encoded using the xbox codec.

An example tool command would be :

tool sounds "foo" xbox 1

This would create the files bar.sound and beef.sound in the folder tags/foo

Encoding and format

The encoding that you use for a sound tag should be determined by it's usage. A few examples: music and voice should always be OGG encoded, but things like weapon sounds can be either Xbox or OGG encoded.

Sample rate

This is determined by the sample rate of the input wav file(s).


The amount of audio channels this sound tag has. This can be either mono or stereo.

What compression, encoding, and sample rate to use

Music, environmental background loops: 44kHz, stereo, OGG.

Voice/dialog: 22kHz, mono, OGG.

Anything else: 22kHz, mono, OGG or Xbox.

Tag fields

These are fields you can edit in Guerilla to alter the behavior of your sound tag.


  • flags:
    • fit to adpcm blocksize
    • split long sound into permutations: (Tag needs to be recompiled using tool for this setting to have effect) This is used primarily for music and long loops to improve loading time and playback performance.This is particularly useful for OGG compressed sounds as the game has a small decompression buffer it uses when playing the sounds ingame. If that buffer fills up sounds may not properly go to the next permutation or cut out. Splitting a long sound into permutations lowers their individual size and allows for more sounds in the sound decompression buffer.
  • class: This is used for things like determining when to skip this sound if the game is running out of resources and the default volume and distance of the sound.
  • sample rate: This is used to determine how fast the sound should be read.
  • minimum distance: The maximum distance in which the sound can be heard at full volume.
  • maximum distance: The distance after which the sound can not be heard anymore.
  • skip fraction: A 0 to 1 chance of the sound not being played.


  • random pitch bounds: Two multipliers that specify what the range is of how far the sound can be slowed down or sped up. Defaults to 1 and 1 on map compile if left at 0 and 0.
  • inner cone angle: Defaults to 360 when compiling a map if left at 0.
  • outer cone angle: Defaults to 360 when compiling a map if left at 0.
  • gain modifier: Defaults to 1 when compiling a map if left at 0.
  • maximum bend per second

When scale is ZERO

When scale is ONE

Import properties

  • Encoding: Specifies if the sounds are in either mono or Stereo.
  • Compression: Specifies the format in which the sound is stored.
  • Promotion sound: When this sound has been played the amount of times specified in the promotion count it will play the sound tag referenced in here instead. (Used for things like shotgun shells)
  • Promotion count: The amount of times this sound tag needs to be called before the promotion sound is used instead.

Pitch ranges and permutations

Permutations are the different versions of the sound that get either at random or for music in sequence.

Pitch ranges specify one or more sets of permutations for when something like an object is controlling the sound. (For instance a warthog would use this for it's engine sound)

Pitch ranges


  • name: The name of the wav file that became this permutation.
  • skip fraction: The 0 to 1 chance that when playing this sound it will skip this permutation.
  • gain: The volume multiplier for this permutation.
  • compression: The compression format for this permutation. (Ignored by the game?)
  • next permutation index: This is used for long sounds that are split into multiple permutations so the game knows what permutation to play next.
  • samples: The raw audio data for this permutation.
  • mouth data: The data for how far the biped's mouth should be opened for each tick that this sound plays. Only used for dialog classed sounds, this data does not get generated when the sound class is not dialog.
  • subtitle data: (Unused?)


  • Write about how vehicle engine sounds are created. (Also explain pitch ranges)
  • Explain the ZERO and ONE scales.
  • Make a list of tool errors.