SFXEmitter
An invisible 3D object that emits sound.
Media
Sound
bool
Whether playback of the emitter's sound should start as soon as the emitter object is added to the level.
bool
bool
Whether to use streamed playback for fileName.
The SFXSource to which to assign the sound of this emitter as a child.
float
Volume level to apply to the sound.
float
Pitch shift to apply to the sound. Default is 1 = play at normal speed.
float
Number of seconds to gradually fade in volume from zero when playback starts.
float
Number of seconds to gradually fade out volume down to zero when playback is stopped or paused.
3D Sound
float
Distance at which to start volume attenuation of the 3D sound.
float
Distance at which to stop volume attenuation of the 3D sound.
Point3F
Bounds on random offset to apply to initial 3D sound position.
int
Angle of inner volume cone of 3D sound in degrees.
int
Angle of outer volume cone of 3D sound in degrees.
float
Volume scale factor of outside of outer volume 3D sound cone.
Public Static Attributes
bool
Disables rendering of all instances of this type.
bool
Disables selection of all instances of this type.
ColorI
The color with which to render dots in the inner sound cone (Editor only).
ColorI
The color with which to render dots in the outer sound cone (Editor only).
ColorI
The color with which to render dots outside of the outer sound cone (Editor only).
ColorI
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.
ColorI
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.
ColorI
The color of the range sphere with which to render sound emitters in the editor.
ColorI
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.
ColorI
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.
bool
Whether to render enhanced range feedback in the editor on all emitters regardless of selection state.
float
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.
float
The stepping (in degrees) for the radial sweep along the axis of the XY plane sweep for sound emitter rendering in the editor.
float
The stepping (in degrees) for the radial sweep on the XY plane for sound emitter rendering in the editor.
Public Functions
Detailed Description
An invisible 3D object that emits sound.
Sound emitters are used to place sounds in the level. They are full 3D objects with their own position and orientation and when assigned 3D sounds, the transform and velocity of the sound emitter object will be applied to the 3D sound.
Sound emitters can be set up of in either of two ways:
By assigning an existing SFXTrack to the emitter's track property.
In this case the general sound setup (3D, streaming, looping, etc.) will be taken from track. However, the emitter's own properties will still override their corresponding properties in the track's SFXDescription.
By directly assigning a sound file to the emitter's fileName property.
In this case, the sound file will be set up for playback according to the properties defined on the emitter.
Using playOnAdd emitters can be configured to start playing immediately when they are added to the system (e.g. when the level objects are loaded from the mission file).
note:A sound emitter need not necessarily emit a 3D sound. Instead, sound emitters may also be used to play non-positional sounds. For placing background audio to a level, however, it is usually easier to use LevelInfo::soundAmbience.
Sound Emitters and Networking
It is important to be aware of the fact that sounds will only play client-side whereas SFXEmitter objects are server-side entities. This means that a server-side object has no connection to the actual sound playing on the client. It is thus not possible for the server-object to perform queries about playback status and other source-related properties as these may in fact differ from client to client.
Media
SFXTrack track
The track which the emitter should play.
note:If assigned, this field will take precedence over a fileName that may also be assigned to the emitter.
filename fileName
The sound file to play.
Use either this property or track. If both are assigned, track takes precendence. The primary purpose of this field is to avoid the need for the user to define SFXTrack datablocks for all sounds used in a level.
Sound
bool playOnAdd
Whether playback of the emitter's sound should start as soon as the emitter object is added to the level.
If this is true, the emitter will immediately start to play when the level is loaded.
bool useTrackDescriptionOnly
If this is true, all fields except for playOnAdd and track are ignored on the emitter object.
This is useful to prevent fields in the track's description from being overridden by emitter fields.
bool isLooping
Whether to play fileName in an infinite loop.
If a track is assigned, the value of this field is ignored.
bool isStreaming
Whether to use streamed playback for fileName.
If a track is assigned, the value of this field is ignored.
SFX_streamingSFXSource sourceGroup
The SFXSource to which to assign the sound of this emitter as a child.
note:This field is ignored if useTrackDescriptionOnly is true.
float volume
Volume level to apply to the sound.
note:This field is ignored if useTrackDescriptionOnly is true.
float pitch
Pitch shift to apply to the sound. Default is 1 = play at normal speed.
note:This field is ignored if useTrackDescriptionOnly is true.
float fadeInTime
Number of seconds to gradually fade in volume from zero when playback starts.
note:This field is ignored if useTrackDescriptionOnly is true.
float fadeOutTime
Number of seconds to gradually fade out volume down to zero when playback is stopped or paused.
note:This field is ignored if useTrackDescriptionOnly is true.
3D Sound
bool is3D
Whether to play fileName as a positional (3D) sound or not.
If a track is assigned, the value of this field is ignored.
float referenceDistance
Distance at which to start volume attenuation of the 3D sound.
note:This field is ignored if useTrackDescriptionOnly is true.
float maxDistance
Distance at which to stop volume attenuation of the 3D sound.
note:This field is ignored if useTrackDescriptionOnly is true.
Point3F scatterDistance
Bounds on random offset to apply to initial 3D sound position.
note:This field is ignored if useTrackDescriptionOnly is true.
int coneInsideAngle
Angle of inner volume cone of 3D sound in degrees.
note:This field is ignored if useTrackDescriptionOnly is true.
int coneOutsideAngle
Angle of outer volume cone of 3D sound in degrees.
note:This field is ignored if useTrackDescriptionOnly is true.
float coneOutsideVolume
Volume scale factor of outside of outer volume 3D sound cone.
note:This field is ignored if useTrackDescriptionOnly is true.
Public Static Attributes
bool isRenderable
Disables rendering of all instances of this type.
bool isSelectable
Disables selection of all instances of this type.
ColorI renderColorInnerCone
The color with which to render dots in the inner sound cone (Editor only).
ColorI renderColorOuterCone
The color with which to render dots in the outer sound cone (Editor only).
ColorI renderColorOutsideVolume
The color with which to render dots outside of the outer sound cone (Editor only).
ColorI renderColorPlayingInRange
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.
ColorI renderColorPlayingOutOfRange
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.
ColorI renderColorRangeSphere
The color of the range sphere with which to render sound emitters in the editor.
ColorI renderColorStoppedInRange
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.
ColorI renderColorStoppedOutOfRange
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.
bool renderEmitters
Whether to render enhanced range feedback in the editor on all emitters regardless of selection state.
float renderPointDistance
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.
float renderRadialIncrements
The stepping (in degrees) for the radial sweep along the axis of the XY plane sweep for sound emitter rendering in the editor.
float renderSweepIncrements
The stepping (in degrees) for the radial sweep on the XY plane for sound emitter rendering in the editor.
Public Functions
getSource()
Get the sound source object from the emitter.
The sound source used by the emitter or null.
note:This method will return null when called on the server-side SFXEmitter object. Only client-side ghosts actually hold on to SFXSources.
play()
Manually start playback of the emitter's sound.
If this is called on the server-side object, the play command will be related to all client-side ghosts.
stop()
Manually stop playback of the emitter's sound.
If this is called on the server-side object, the stop command will be related to all client-side ghosts.