Skip to content

AudioAsset Guide

Jump to bottom
Peter Robinson edited this page Jul 18, 2026 · 4 revisions

Introduction

All assets are known engine types that allow instances to be created at runtime. The "AudioAsset", like all assets, is derived from a base type of "AssetBase". That means it includes all the fields from that type as well as adding its own fields specific to itself.

The AudioAsset provides a way to refer to a single audio file and deliver background music or sound effects for use within the engine.

For an AudioAsset to be valid, it must contain an audio file in the WAV format with a sample rate of 44100 Hz or lower, 16 bits, and in either stereo or mono. Windows and MacOSX also support OGG format.

TorqueScript Bindings

Exposed Fields

The AudioAsset type exposes the following fields in addition to those it inherits. Shown are the equivalent methods available that perform the same action in setting and getting the respective field:

Note: AudioAsset exposes no callable script methods — the setX/getX names listed below are the underlying C++ accessors. From TorqueScript you use these as persistent fields instead: set them by field assignment (e.g. %asset.Volume = 0.8;) or declare them in the asset's .asset.taml file (see the examples below).

  • AudioFile
  • setAudioFile(string)
  • getAudioFile()
  • Volume
  • setVolume(float)
  • getVolume()
  • VolumeChannel
  • setVolumeChannel(integer)
  • getVolumeChannel();
  • Looping
  • setLooping(bool)
  • getLooping()
  • Streaming
  • setStreaming(bool)
  • getStreaming()
  • Priority
  • setPriority(bool)
  • getPriority()

In the list above, only "AudioFile" is mandatory, all others are completely optional. Here's an example of the most basic form of an AudioAsset where only the mandatory field "AudioFile" is specified:

<AudioAsset
 AssetName="level1Music"
 AudioFile="TD_Medieval_GameplayAudio.wav"
/>

This will produce an asset known as "level1Music" from the audio file specified, which it expects to be located in the same folder as the XML AudioAsset file. As seen in this example, there is no need to make the asset name match the audio name, but having matching names can make keeping the revelent files together on disk easier with an alphabetic file sort.

The following is a complete description of each of these fields.

AudioFile (string)

This is the only mandatory field for the type. It should refer to an audio file that the engine can load.

You can refer to sub-folders here but using a format like:

<AudioAsset
 AssetName="level1Music"
 AudioFile="music/TD_Medieval_GameplayAudio.wav"
/>

Do not use the "." to indicate the current folder as this is already implicitly assumed. You can however use ".." to indicate a parent folder but it is highly discouraged to store audio in parent folders.

Volume (float)

This field controls the volume level of the audio file. This value must be given as a floating point number between 0.0 (no volume) and 1.0 (full volume).

The default volume value is 1.0. If no channel is specified, the volume field will modify the default channel 0.

VolumeChannel (integer)

Torque 2D has 32 available volume channels (from 0 to 31) that you can assign to your audio file. A typical usage scenario is to split the background music and sound effects onto different channels so the volume on each channel can be controlled independently.

If left unassigned, the audio file will be assigned to channel 0.

Looping (bool)

By default, an audio file will not loop if this field is left undefined. If you wish to have your audio file repeat when it reaches the end of the track, you can set this field to "true", as shown below:

<AudioAsset
 AssetName="level1Music"
 AudioFile="TD_Medieval_GameplayAudio.wav"
 Looping="true"
/>

Streaming (bool)

To stream the audio file from the disk instead of loading the entire file into memory first, set this field to "true". Recommended for larger audio files.

<AudioAsset
 AssetName="level1Music"
 AudioFile="TD_Medieval_GameplayAudio.wav"
 Streaming="true"
/>

Priority (bool)

Only so many sounds can play at once — see Multiple Sounds in the Audio Guide (the default limit is 16). When that limit is reached and a new sound needs a voice, the engine stops ("culls") the quietest sound that is currently playing to make room. A quiet, non-positional looping sound such as background music is an easy target, and a looping sound that gets culled restarts from the beginning the next time a voice frees up — so a busy scene can make your music jump back to the start mid-track.

Set this field to "true" to protect a sound from that: a priority sound is only culled when every other playing sound is also a priority sound. Background music is the usual case.

<AudioAsset
 AssetName="level1Music"
 AudioFile="TD_Medieval_GameplayAudio.wav"
 Looping="true"
 Streaming="true"
 Priority="true"
/>

Clone this wiki locally