Channels are individual properties of sound sources that may be animated over time.

See also:

SFXParameter

Interactive Audio

Enumerator:

Volume	Channel controls volume level of attached sound sources. See also: SFXDescription::volume
Pitch	Channel controls pitch of attached sound sources. See also: SFXDescription::pitch
Priority	Channel controls virtualizaton priority level of attached sound sources. See also: SFXDescription::priority
PositionX	Channel controls X coordinate of 3D sound position of attached sources.
PositionY	Channel controls Y coordinate of 3D sound position of attached sources.
PositionZ	Channel controls Z coordinate of 3D sound position of attached sources.
RotationX	Channel controls X rotation (in degrees) of 3D sound orientation of attached sources.
RotationY	Channel controls Y rotation (in degrees) of 3D sound orientation of attached sources.
RotationZ	Channel controls Z rotation (in degrees) of 3D sound orientation of attached sources.
VelocityX	Channel controls X coordinate of 3D sound velocity vector of attached sources.
VelocityY	Channel controls Y coordinate of 3D sound velocity vector of attached sources.
VelocityZ	Channel controls Z coordinate of 3D sound velocity vector of attached sources.
ReferenceDistance	Channel controls reference distance of 3D sound of attached sources. See also: SFXDescription::referenceDistance
MaxDistance	Channel controls max volume attenuation distance of 3D sound of attached sources. See also: SFXDescription::maxDistance
ConeInsideAngle	Channel controls angle (in degrees) of 3D sound inner volume cone of attached sources. See also: SFXDescription::coneInsideAngle
ConeOutsideAngle	Channel controls angle (in degrees) of 3D sound outer volume cone of attached sources. See also: SFXDescription::coneOutsideAngle
ConeOutsideVolume	Channel controls volume outside of 3D sound outer cone of attached sources. See also: SFXDescription::coneOutsideVolume
Cursor	Channel controls playback cursor of attached sound sources. Note: Be aware that different types of sound sources interpret play cursor positions differently or do not actually have play cursors (these sources will ignore the channel).
Status	Channel controls playback status of attached sound sources. The channel's value is rounded down to the nearest integer and interpreted in the following way: 1: Play 2: Stop 3: Pause
User0	Channel available for custom use. By default ignored by sources. Note: For FMOD Designer event sources (SFXFMODEventSource), this channel is used for event parameters defined in FMOD Designer and should not be used otherwise. See also: SFXSource::onParameterValueChange
User1	Channel available for custom use. By default ignored by sources. See also: SFXSource::onParameterValueChange
User2	Channel available for custom use. By default ignored by sources. See also: SFXSource::onParameterValueChange
User3	Channel available for custom use. By default ignored by sources. See also: SFXSource::onParameterValueChange

Type of volume distance attenuation curve.

The distance model determines the falloff curve applied to the volume of 3D sounds over distance.

Volume Attenuation

3D Audio

Enumerator:

Linear	Volume attenuates linearly from the references distance onwards to max distance where it reaches zero.
Logarithmic	Volume attenuates logarithmically starting from the reference distance and halving every reference distance step from there on. Attenuation stops at max distance but volume won't reach zero.

Playlist behavior when description is set to loop.

See also:

SFXDescription::isLooping

SFXPlayList::loopMode

Enumerator:

All	Loop over all slots, i.e. jump from last to first slot after all slots have played.
Single	Loop infinitely over the current slot. Only useful in combination with either states or manual playlist control.

Randomization pattern to apply to playlist slot playback order.

See also:

SFXPlayList::random

Enumerator:

NotRandom	Play slots in sequential order. No randomization.
StrictRandom	Play a strictly random selection of slots. In this mode, a set of numSlotsToPlay random numbers between 0 and numSlotsToPlay-1 (inclusive), i.e. in the range of valid slot indices, is generated and playlist slots are played back in the order of this list. This allows the same slot to occur multiple times in a list and, consequentially, allows for other slots to not appear at all in a given slot ordering.
OrderedRandom	Play all slots in the list in a random order. In this mode, the numSlotsToPlay slots from the list with valid tracks assigned are put into a random order and played. This guarantees that each slots is played exactly once albeit at a random position in the total ordering.

Behavior when hitting the play stage of a slot that is still playing from a previous cycle.

See also:

SFXPlayList::replay

Enumerator:

IgnorePlaying	Ignore any sources that may already be playing on the slot and just create a new source.
RestartPlaying	Restart all sources that was last created for the slot.
KeepPlaying	Keep playing the current source(s) as if the source started last on the slot was created in this cycle. For this, the sources associated with the slot are brought to the top of the play stack.
StartNew	Stop all sources currently playing on the slot and then create a new source.
SkipIfPlaying	If there are sources already playing on the slot, skip the play stage.

Reaction behavior when a state is changed incompatibly on a slot that has already started playing.

See also:

SFXPlayList::stateMode

Enumerator:

StopWhenDeactivated	Stop the sources playing on the slot when a state changes to a setting that is incompatible with the slot's state setting.
PauseWhenDeactivated	Pause all sources playing on the slot when a state changes to a setting that is incompatible with the slot's state setting. When the slot's state is reactivated again, the sources will resume playback.
IgnoreWhenDeactivated	Ignore when a state changes to a setting incompatible with the slot's state setting and just keep playing sources attached to the slot.

Playlist behavior when transitioning in and out of invididual slots.

Transition behaviors apply when the playback controller starts processing a playlist slot and when it ends processing a slot. Using transition behaviors, playback can be synchronized.

See also:

SFXPlayList::transitionIn

SFXPlayList::transitionOut

Enumerator:

None	No transition. Immediately move on to processing the slot or immediately move on to the next slot.
Wait	Wait for the sound source spawned last by this playlist to finish playing. Then proceed.
WaitAll	Wait for all sound sources currently spawned by the playlist to finish playing. Then proceed.
Stop	Stop the sound source spawned last by this playlist. Then proceed.
StopAll	Stop all sound sources spawned by the playlist. Then proceed.

Playback status of sound source.

Enumerator:

Playing	The source is currently playing.
Stopped	Playback of the source is stopped. When transitioning to Playing state, playback will start at the beginning of the source.
Paused	Playback of the source is paused. Resuming playback will play from the current playback position.

Try to create a new sound device using the given properties.

If a sound device is currently initialized, it will be uninitialized first. However, be aware that in this case, if this function fails, it will not restore the previously active device but rather leave the sound system in an uninitialized state.

Sounds that are already playing while the new device is created will be temporarily transitioned to virtualized playback and then resume normal playback once the device has been created.

In the core scripts, sound is automatically set up during startup in the sfxStartup() function.

Parameters:

	provider	The name of the device provider as returned by sfxGetAvailableDevices().
	device	The name of the device as returned by sfxGetAvailableDevices().
	useHardware	Whether to enabled hardware mixing on the device or not. Only relevant if supported by the given device.
	maxBuffers	The maximum number of concurrent voices for this device to use or -1 for the device to pick its own reasonable default.

Returns:

True if the initialization was successful, false if not.

Note:

This function must be called before any of the sound playback functions can be used.

See also:

sfxGetAvailableDevices

sfxGetDeviceInfo

sfxDeleteDevice

Providers and Devices

Create a new source that plays the given track.

The source will be returned in stopped state. Call SFXSource::play() to start playback.

In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

This function will automatically create the right SFXSource type for the given SFXTrack.

Parameters:

track

The track the source should play.

Returns:

A new SFXSource for playback of the given track or 0 if no source could be created from the given track.

Note:

Trying to create a source for a device-specific track type will fail if the currently selected device does not support the type. Example: trying to create a source for an FMOD Designer event when not running FMOD.

Example:

// Create and play a source from a pre-existing profile:
%source = sfxCreateSource( SoundFileProfile );
%source.play();

Create a new source that plays the given track and position its 3D sounds source at the given coordinates (if it is a 3D sound).

The source will be returned in stopped state. Call SFXSource::play() to start playback.

In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

This function will automatically create the right SFXSource type for the given SFXTrack.

Parameters:

	track	The track the source should play.
	x	The X coordinate of the 3D sound position.
	y	The Y coordinate of the 3D sound position.
	z	The Z coordinate of the 3D sound position.

Returns:

A new SFXSource for playback of the given track or 0 if no source could be created from the given track.

Note:

Trying to create a source for a device-specific track type will fail if the currently selected device does not support the type. Example: trying to create a source for an FMOD Designer event when not running FMOD.

Example:

// Create and play a source from a pre-existing profile and position it at (100, 200, 300):
%source = sfxCreateSource( SoundFileProfile, 100, 200, 300 );
%source.play();

Create a temporary SFXProfile from the given description and filename and then create and return a new source that plays the profile.

The source will be returned in stopped state. Call SFXSource::play() to start playback.

In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

Parameters:

	description	The description to use for setting up the temporary SFXProfile.
	filename	Path to the sound file to play.

Returns:

A new SFXSource for playback of the given track or 0 if no source or no temporary profile could be created.

Example:

// Create a source for a music track:
%source = sfxCreateSource( AudioMusicLoop2D, "art/sound/backgroundMusic" );
%source.play();

See also:

SFXProfile

Create a temporary SFXProfile from the given description and filename and then create and return a new source that plays the profile. Position the sound source at the given coordinates (if it is a 3D sound).

The source will be returned in stopped state. Call SFXSource::play() to start playback.

In contrast to play-once sources, the source object will not be automatically deleted once playback stops. Call delete() to release the source object.

Parameters:

	description	The description to use for setting up the temporary SFXProfile.
	filename	Path to the sound file to play.
	x	The X coordinate of the 3D sound position.
	y	The Y coordinate of the 3D sound position.
	z	The Z coordinate of the 3D sound position.

Returns:

A new SFXSource for playback of the given track or 0 if no source or no temporary profile could be created.

Example:

// Create a source for a music track and position it at (100, 200, 300):
%source = sfxCreateSource( AudioMusicLoop3D, "art/sound/backgroundMusic", 100, 200, 300 );
%source.play();

See also:

SFXProfile

Delete the currently active sound device and release all its resources.

SFXSources that are still playing will be transitioned to virtualized playback mode. When creating a new device, they will automatically transition back to normal playback.

In the core scripts, this is done automatically for you during shutdown in the sfxShutdown() function.

See also:

sfxCreateDevice

Providers and Devices

Mark the given source for deletion as soon as it moves into stopped state.

This function will retroactively turn the given source into a play-once source (see Play-Once Sources).

Parameters:

source

A sound source.

Dump information about all current SFXSource instances to the console.

The dump includes information about the playback status for each source, volume levels, virtualization, etc.

Parameters:

includeGroups

If true, direct instances of SFXSources (which represent logical sound groups) will be included. Otherwise only instances of subclasses of SFXSources are included in the dump.

See also:

SFXSource

sfxDumpSourcesToString

Dump information about all current SFXSource instances to a string.

The dump includes information about the playback status for each source, volume levels, virtualization, etc.

Parameters:

includeGroups

If true, direct instances of SFXSources (which represent logical sound groups) will be included. Otherwise only instances of subclasses of SFXSources are included in the dump.

Returns:

A string containing a dump of information about all currently instantiated SFXSources.

See also:

SFXSource

sfxDumpSources

Return a newline-separated list of all active states.

Returns:

A list of the form

stateName1 NL stateName2 NL stateName3 ...

where each element is the name of an active state object.

Example:

// Disable all active states.
foreach$( %state in sfxGetActiveStates() )
   %state.disable();

Get a list of all available sound devices.

The return value will be a newline-separated list of entries where each line describes one available sound device. Each such line will have the following format:

provider TAB device TAB hasHardware TAB numMaxBuffers

• provider: The name of the device provider (e.g. "FMOD").
• device: The name of the device as returned by the device layer.
• hasHardware: Whether the device supports hardware mixing or not.
• numMaxBuffers: The maximum number of concurrent voices supported by the device's mixer. If this limit limit is exceeded, i.e. if there are more active sounds playing at any one time, then voice virtualization will start culling voices and put them into virtualized playback mode. Voice virtualization may or may not be provided by the device itself; if not provided by the device, it will be provided by Torque's sound system.

Returns:

A newline-separated list of information about all available sound devices.

See also:

sfxCreateDevice

sfxGetDeviceInfo

$SFX::DEVICE_INFO_PROVIDER

$SFX::DEVICE_INFO_NAME

$SFX::DEVICE_INFO_USEHARDWARE

$SFX::DEVICE_INFO_MAXBUFFERS

Providers and Devices

Return information about the currently active sound device.

The return value is a tab-delimited string of the following format:

provider TAB device TAB hasHardware TAB numMaxBuffers TAB caps

• provider: The name of the device provider (e.g. "FMOD").
• device: The name of the device as returned by the device layer.
• hasHardware: Whether the device supports hardware mixing or not.
• numMaxBuffers: The maximum number of concurrent voices supported by the device's mixer. If this limit limit is exceeded, i.e. if there are more active sounds playing at any one time, then voice virtualization will start culling voices and put them into virtualized playback mode. Voice virtualization may or may not be provided by the device itself; if not provided by the device, it will be provided by Torque's sound system.
• caps: A bitfield of capability flags.

Returns:

A tab-separated list of properties of the currently active sound device or the empty string if no sound device has been initialized.

See also:

sfxCreateDevice

sfxGetAvailableDevices

$SFX::DEVICE_INFO_PROVIDER

$SFX::DEVICE_INFO_NAME

$SFX::DEVICE_INFO_USEHARDWARE

$SFX::DEVICE_INFO_MAXBUFFERS

$SFX::DEVICE_INFO_CAPS

$SFX::DEVICE_CAPS_REVERB

$SFX::DEVICE_CAPS_VOICEMANAGEMENT

$SFX::DEVICE_CAPS_OCCLUSION

$SFX::DEVICE_CAPS_DSPEFFECTS

$SFX::DEVICE_CAPS_MULTILISTENER

$SFX::DEVICE_CAPS_FMODDESIGNER

Providers and Devices

Get the falloff curve type currently being applied to 3D sounds.

Returns:

The current distance model type.

Volume Attenuation

3D Audio

Get the current global doppler effect setting.

Returns:

The current global doppler effect scale factor (>=0).

See also:

sfxSetDopplerFactor

Doppler Effect

Get the current global scale factor applied to volume attenuation of 3D sounds in the logarithmic model.

Returns:

The current scale factor for logarithmic 3D sound falloff curves.

See also:

sfxGetDistanceModel

SFXDistanceModel

Volume Attenuation 3D Audio

Start playback of the given source.

This is the same as calling SFXSource::play() directly.

Parameters:

source

The source to start playing.

Returns:

source.

Example:

// Create and play a source from a pre-existing profile:
%source = sfxCreateSource( SoundFileProfile );
%source.play();

Create a new play-once source for the given track and start playback of the source.

This is equivalent to calling sfxCreateSource() on and SFXSource::play() on the resulting source.

Parameters:

track

The sound datablock to play.

Returns:

The newly created play-once source or 0 if the creation failed.

Play-Once Sources

Create a new play-once source for the given track, position its 3D sound at the given coordinates (if the track's description is set up for 3D sound) and start playback of the source.

This is equivalent to calling sfxCreateSource() on and SFXSource::play() on the resulting source.

Parameters:

	track	The sound datablock to play.
	x	The X coordinate of the 3D sound position.
	y	The Y coordinate of the 3D sound position.
	z	The Z coordinate of the 3D sound position.

Returns:

The newly created play-once source or 0 if the creation failed.

Play-Once Sources

Create a play-once source for the given track.

Once playback has finished, the source will be automatically deleted in the next sound system update.

Parameters:

track

The sound datablock.

Returns:

A newly created temporary source in "Playing" state or 0 if the operation failed.

Play-Once Sources

Create a play-once source for the given given track and position the source's 3D sound at the given coordinates only if the track's description is set up for 3D sound).

Once playback has finished, the source will be automatically deleted in the next sound system update.

Parameters:

	track	The sound datablock.
	x	The X coordinate of the 3D sound position.
	y	The Y coordinate of the 3D sound position.
	z	The Z coordinate of the 3D sound position.
	fadeInTime	If >=0, this overrides the SFXDescription::fadeInTime value on the track's description.

Returns:

A newly created temporary source in "Playing" state or 0 if the operation failed.

Example:

// Immediately start playing the given track.  Fade it in to full volume over 5 seconds.
sfxPlayOnce( MusicTrack, 0, 0, 0, 5.f );

Play-Once Sources

Create a new temporary SFXProfile from the given description and filename, then create a play-once source for it and start playback.

Once playback has finished, the source will be automatically deleted in the next sound system update. If not referenced otherwise by then, the temporary SFXProfile will also be deleted.

Parameters:

	description	The description to use for playback.
	filename	Path to the sound file to play.

Returns:

A newly created temporary source in "Playing" state or 0 if the operation failed.

Example:

// Play a sound effect file once.
sfxPlayOnce( AudioEffects, "art/sound/weapons/Weapon_pickup" );

Play-Once Sources

Create a new temporary SFXProfile from the given description and filename, then create a play-once source for it and start playback. Position the source's 3D sound at the given coordinates (only if the description is set up for 3D sound).

Once playback has finished, the source will be automatically deleted in the next sound system update. If not referenced otherwise by then, the temporary SFXProfile will also be deleted.

Parameters:

	description	The description to use for playback.
	filename	Path to the sound file to play.
	x	The X coordinate of the 3D sound position.
	y	The Y coordinate of the 3D sound position.
	z	The Z coordinate of the 3D sound position.
	fadeInTime	If >=0, this overrides the SFXDescription::fadeInTime value on the track's description.

Returns:

A newly created temporary source in "Playing" state or 0 if the operation failed.

Example:

// Play a sound effect file once using a 3D sound with a default falloff placed at the origin.
sfxPlayOnce( AudioDefault3D, "art/sound/weapons/Weapon_pickup", 0, 0, 0 );

Play-Once Sources

Set the falloff curve type to use for distance-based volume attenuation of 3D sounds.

Parameters:

model

The distance model to use for 3D sound.

Note:

This setting takes effect globally and is applied to all 3D sounds.

Set the global doppler effect scale factor.

Parameters:

value

The new doppler shift scale factor.

Precondition:

value must be >= 0.

See also:

sfxGetDopplerFactor

Doppler Effect

Set the global scale factor to apply to volume attenuation of 3D sounds in the logarithmic model.

Parameters:

value

The new scale factor for logarithmic 3D sound falloff curves.

Precondition:

value must be > 0.

Note:

This function has no effect if the currently distance model is set to SFXDistanceModel::Linear.

See also:

sfxGetDistanceModel

SFXDistanceModel

Volume Attenuation 3D Audio

Stop playback of the given source.

This is equivalent to calling SFXSource::stop().

Parameters:

source

The source to put into stopped state.

Stop playback of the given source (if it is not already stopped) and delete the source.

The advantage of this function over directly calling delete() is that it will correctly handle volume fades that may be configured on the source. Whereas calling delete() would immediately stop playback and delete the source, this functionality will wait for the fade-out to play and only then stop the source and delete it.

Parameters:

source

A sound source.

Volume Fades

Milliseconds spent on the last ambient audio update.

Sound System Updates

Ambient Audio

Sound device capability flag indicating that the sound device supports adding DSP effect chains to sounds.

See also:

sfxGetDeviceInfo

Note:

This is not yet used by the sound system.

See also:

sfxGetDeviceInfo

Sound device capability flag indicating that the sound device supports FMOD Designer audio projects.

Note:

This is exclusive to FMOD. If the FMOD Event DLLs are in place and could be successfully loaded, this flag will be set after initializating an FMOD audio device.

See also:

sfxGetDeviceInfo

FMOD Designer Audio

Sound device capability flag indicating that the sound device supports multiple concurrent listeners.

Note:

Currently only FMOD implements this.

See also:

sfxGetDeviceInfo

Sound device capability flag indicating that the sound device implements sound occlusion.

Note:

This is not yet used by the sound system.

See also:

sfxGetDeviceInfo

Sound device capability flag indicating that the sound device supports reverb.

Note:

Currently only FMOD implements this.

See also:

sfxGetDeviceInfo

Audio Reverb

Sound device capability flag indicating that the sound device implements its own voice virtualization.

For these devices, the sound system will deactivate its own voice management and leave voice virtualization entirely to the device.

Note:

Currently only FMOD implements this.

See also:

sfxGetDeviceInfo

Sounds and Voices

Index of device capability flags in device info string.

See also:

sfxGetDeviceInfo

sfxGetAvailableDevices

Index of buffer limit number in device info string.

See also:

sfxGetDeviceInfo

sfxGetAvailableDevices

Index of device name field in device info string.

See also:

sfxGetDeviceInfo

sfxGetAvailableDevices

Index of sound provider field in device info string.

See also:

sfxGetDeviceInfo

sfxGetAvailableDevices

Index of use hardware flag in device info string.

See also:

sfxGetDeviceInfo

sfxGetAvailableDevices

Number of SFXSounds that are currently in virtualized playback mode.

Sounds and Voices

Number of SFXSources that are currently in playing state.

Number of SFXSound type objects (i.e. actual single-file sounds) that are currently instantiated.

Number of SFXSource type objects that are currently instantiated.

Number of voices that are currently allocated on the sound device.

Milliseconds spent on the last SFXParameter update loop.

Sound System Updates

Interactive Audio

The color with which to render dots in the inner sound cone (Editor only).

The color with which to render dots in the outer sound cone (Editor only).

The color with which to render dots outside of the outer sound cone (Editor only).

The color with which to render a sound emitter's marker cube in the editor when the emitter's sound is playing and in range of the listener.

The color with which to render a sound emitter's marker cube in the editor when the emitter's sound is playing but out of the range of the listener.

The color of the range sphere with which to render sound emitters in the editor.

The color with which to render a sound emitter's marker cube in the editor when the emitter's sound is not playing but the emitter is in range of the listener.

The color with which to render a sound emitter's marker cube in the editor when the emitter's sound is not playing and the emitter is out of range of the listener.

Whether to render enhanced range feedback in the editor on all emitters regardless of selection state.

The distance between individual points in the sound emitter rendering in the editor as the points move from the emitter's center away to maxDistance.

The stepping (in degrees) for the radial sweep along the axis of the XY plane sweep for sound emitter rendering in the editor.

The stepping (in degrees) for the radial sweep on the XY plane for sound emitter rendering in the editor.

Milliseconds spent on the last SFXSource update loop.

Sound System Updates