Overview

SFXSources are the interface to sound playback. They are created through the SFXSystem and control all aspects of playback. The SFX system can be interfaced through a number of console methods.


Note: Do not create SFXSources directly through object declarations (i.e. new or singleton). This is inhibited by the SFX system.


SFXSources are either created from SFXProfiles or directly from SFXStreams. The latter method is only available internally from within the engine and not exposed to script.


SFXProfiles are created by the user. They combine sound files with SFXDescriptions that describe how to play back the particular file.


SFXDescriptions are datablocks with a series of properties that describe aspects of sound playback.


SFXSources create SFXVoices (playback controllers) and SFXBuffers (sample data buffers) on SFXDevices. This happens internally.


SFXStreams are used to load sample data into SFXBuffers. For streaming buffers, this is a continuous process. This happens internally.


An SFXListener instance is coupled to the SFXSystem and defines the location and velocity of the listener in 3D space. This is used for volume attenuation of 3D sounds. This happens internally. The listener is automatically updated from the game's control object.


Channels

To allow volume level adjustment to a whole batch of sounds, sounds are grouped into logical volume channels. Music can thus be separated from sound effects or voices and have its volume adjusted independently.


Volume channels are numbered from 0 onwards. There is a maximum of 32 channels. The core scripts currently define and use three separate channels (defined in core/scripts/client/audio.cs):


  • $GuiAudioType = 1;
    • Use for sounds relating to the interface.
  • $SimAudioType = 2;
    • Use for in-game sound effect and environmental sounds.
  • $MessageAudioType = 3;
    • Use for notifications (such as from chat) and possibly voices.
  • $MusicAudioType = 4;
    • Use for background music.

Note: The master volume set on the SFX system simultaneously scales all of the volume channels.


A set of SFXDescriptions preset to this set of channels is made available through core/scripts/client/audio.cs. These should best be used as copy-sources for custom SFXDescriptions.

  • AudioGui
  • AudioSim
  • AudioMessage
  • AudioMusic

Descriptions

Playback setups are described in SFXDescriptions. These are defined in art/datablocks/audioProfiles.cs. Some useful examples are below:

*3D Sounds
   o Single-Shot Sounds
             + AudioDefault3D
                # is3D = true
                # referenceDistance = 20.0
                # maxDistance = 100.0
                # channel = $SimAudioType
             + AudioClose3D
                # is3D = true
                # referenceDistance = 10.0
                # maxDistance = 60.0
                # channel = $SimAudioType
             + AudioClosest3D
                # is3D = true
                # referenceDistance = 5.0
                # maxDistance = 30.0
                # channel = $SimAudioType
   o Looping Sounds
             + AudioDefaultLoop3D
                # is3D = true
                # isLooping = true
                # referenceDistance = 20.0
                # maxDistance = 100.0
                # channel = $SimAudioType
             + AudioCloseLoop3D
                # is3D = true
                # isLooping = true
                # referenceDistance = 10.0
                # maxDistance = 60.0
                # channel = $SimAudioType
             + AudioClosestLoop3D
                # is3D = true
                # isLooping = true
                # referenceDistance = 5.0
                # maxDistance = 30.0
                # channel = $SimAudioType
*2D Sounds
   o Audio2D
             + channel = $SimAudioType

   o AudioStream2D
             + isStreaming = true
             + channel = $SimAudioType

   o AudioLoop2D
             + isLooping = true
             + channel = $SimAudioType

   o AudioStreamLoop2D
             + isLooping = true
             + isStreaming = true
             + channel = $SimAudioType

*Music
   o AudioMusic2D
             + isStreaming = true
             + channel = $MusicAudioType

   o AudioMusicLoop2D
             + isStreaming = true
             + isLooping = true
             + channel = $MusicAudioType

   o AudioMusic3D
             + isStreaming = true
             + is3D = true
             + channel = $MusicAudioType

   o AudioMusicLoop3D
             + isStreaming = true
             + isLooping = true
             + is3D = true
             + channel = $MusicAudioType

Configuring 3D Playback

There are multiple options available for configuring volume attenuation of 3D sounds on the device. The settings are exposed as script variables and must be set in script (either from the console or add them to scripts/client/prefs.cs).


$pref::SFX::distanceModel

The distance model determines the rolloff function for 3D sounds, i.e. the way the volume attenuates as you move away from a 3D sound. The chosen model affects distance attenuation of all 3D sounds. Currently, there are two models available:


"linear"

Starting from a sound's reference distance, the volume fades linearly towards its set maximum distance at which point it reaches zero.


Notes:

  • Linear rolloff is not supported with DirectSound.
  • Linear rolloff is unaffected by the rolloff factor set on the device.


"logarithmic"

Starting from a sound's reference distance, the volume halves every reference distance steps. This is the more realistic behavior for distance attenuation. In this model, the maximum distance only determines at which distance volume no longer decreases.


Instead, attenuation simply stops at the set maximum distance. Attenuation can be scaled by the rolloff factor to be faster or slower.


$pref::SFX::dopplerFactor

The doppler shift to apply to 3D sounds based on the relative velocity to the listener. Higher values give more pronounced doppler effects. Default is 0.5.


$pref::SFX::rolloffFactor

The rolloff factor scales the reference distance of a sound to determine how fast attenuation decreases a sound's volume. At 1.0, every reference distance steps will halve the volume of a sound. At 0.5, every reference distance steps will have the quarter of the previous step's volume.


Note: The rolloff factor only affects logarithmic distance attenuation.


Script Classes


SFXDescription

Description

SFXDescriptions tell the sound system how to play back a sound, i.e. they provide the parameters when setting up playback for a sound on the device.

Properties

  • volume [float]: Base volume level for the sound. This will be the starting point for volume attenuation on the sound. Must be between 0 (min) and 1 (max). Default is 1.
  • pitch [float]: Pitch scale. This speeds up or slows down playback. Must be greater than 0. Default is 1.
  • isLooping [bool]: If true, the sound will be played in an endless loop. Default is false.
  • isStreaming [bool]: If true, the sound will be progressively streamed; if false, the sound will be buffered in whole. Default is false.
  • is3D [bool]: If true, the sound is positional and mixed according to its spatial properties. Default is false.
  • referenceDistance [float]: Distance at which volume attenuation begins. Up to this distance, the sound retains its base volume. Also, in the exponential distance model, the reference distance determine how fast the sound volume decreases with distance. Each referenceDistance steps (scaled by the rolloff factor), the volume halves. A rule of thumb is that for sounds that require you to be close to hear them in the real world, set the reference distance to small values whereas for sounds that are widely audible set it to larger values. Only for 3D sounds.
  • maxDistance [float]: The distance at which attenuation stops. In the linear distance model, the attenuated volume will be zero at this distance. In the logarithmic model, attenuation will simply stop at this distance and the sound will keep its attenuated volume from there on out. Only for 3D sounds.
  • coneInsideAngle [float]: Specifies the angle of the inside cone in degrees. Valid values are from 0 to 360. Must be less than coneOutsideAngle. Default is 360. Only for 3D sounds.
  • coneOutsideAngle [float]: Specifies the angle of the outside cone in degrees. Valid values are from 0 to 360. Default is 360. Only for 3D sounds.
  • coneOutsideVolume [float]: Determines the volume scale factor applied to a source's base volume level outside of the outer cone. In the outer cone, starting from outside the inner cone, the scale factor smoothly interpolates from 1.0 (within the inner cone) to this value. At the moment, the allowed range is 0.0 (silence) to 1.0 (no attenuation) as amplification is only supported on XAudio2 but not on the other devices. Only for 3D sound.
  • channel [int]: Volume channel that the sound will get assigned to. The base volume level of the sound will be scaled by the channel's volume level. Default is 0.
  • fadeInTime [float]: Number of seconds to gradually fade in volume from zero when playback starts.
  • fadeOutTime [float]: Number of seconds to gradually fade out volume to zero before playback stops.
  • streamPacketSize [int]: Number of seconds of sample data to read per streaming packet. Only for streamed sounds and only when SFX's own streaming system is used.
  • streamReadAhead [int]: Number of stream packets to keep buffered ahead of time. A number of packets (usually three) will generally be kept immediately on the SFX device for playback. This number controls how many more packets are read ahead of time in addition to this. Higher numbers allow to better cope with lagging stream sources but for good resource consumption, this should be kept reasonably low. Only for streamed sounds and only when SFX's own streaming system is used.

SFXProfile

Description

An SFXProfile combines a sound file with an SFXDescription that tells how to play back the sound. SFXProfiles are datablocks, so when you define server-side SFXProfiles use the datablock keyword. For client-side only profiles, use new or singleton.


For non-streamed sounds, the SFXProfile will keep a reference to the SFXBuffer on the device once the sound has been loaded. This will allow simultaneous playbacks of the same profile to share a single SFXBuffer. A profile's sound will automatically reload when its file on disk changes. This will also update all sources that are currently using the profile.


By default, the sound data contained in an SFXProfile will be loaded into the SFX device when the sound is first played. This will incur a short delay on the first use. To load the sound data ahead of time independent on the first use, set the "preload" property to true. This will cause sound data to be loaded when the profile object is