SFX

Functions

sfxCreateDevice(string provider, string device, bool useHardware, int maxBuffers)

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:

note:

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

sfxCreateSource(SFXDescription description, string filename)

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:

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

sfxCreateSource(SFXDescription description, string filename, float x, float y, float z)

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:

// 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();

sfxCreateSource(SFXTrack track)

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:

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.

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

sfxCreateSource(SFXTrack track, float x, float y, float z)

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:

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.

// 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();

sfxDeleteDevice()

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.

sfxDeleteWhenStopped(SFXSource source)

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:

sfxDumpSources(bool includeGroups)

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:

sfxDumpSourcesToString(bool includeGroups)

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:

sfxGetActiveStates()

Return a newline-separated list of all active states.

stateName1 NL stateName2 NL stateName3 ...

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

sfxGetAvailableDevices()

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.

sfxGetDeviceInfo()

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.

sfxGetDistanceModel()

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

SFX_3d

sfxGetDopplerFactor()

Get the current global doppler effect setting.

sfxGetRolloffFactor()

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

sfxPlay(SFXSource source)

Start playback of the given source.

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

Parameters:

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

sfxPlay(SFXTrack track)

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

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

Parameters:

sfxPlay(SFXTrack track, float x, float y, float z)

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 @track and SFXSource::play() on the resulting source.

Parameters:

sfxPlayOnce(SFXDescription description, string filename)

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:

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

Play-Once Sources

sfxPlayOnce(SFXDescription description, string filename, float x, float y, float z, float fadeInTime)

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:

// 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

sfxPlayOnce(SFXTrack track)

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:

sfxPlayOnce(SFXTrack track, float x, float y, float z, float fadeInTime)

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:

// 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

sfxSetDistanceModel(SFXDistanceModel model)

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

Parameters:

note:

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

sfxSetDopplerFactor(float value)

Set the global doppler effect scale factor.

Parameters:

sfxSetRolloffFactor(float value)

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

Parameters:

note:

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

sfxStop(SFXSource source)

Stop playback of the given source.

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

Parameters:

sfxStopAndDelete(SFXSource source)

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: