Skip to content

AudioAsset Guide

Jump to bottom
Peter Robinson edited this page Jul 5, 2020 · 2 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: these methods are only available in C++, there are currently no TorqueScript bindings.

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

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"
/>
Clone this wiki locally