engine.sound Functions

This set of functions controls the general sound settings.

int SOUND_NUM_SOURCES

Description

The number of sound channels (it is equal to 32).

int SOUND_REVERB_DISABLED

Description

Reverberation of sound is disabled.

int SOUND_REVERB_MULTIPLE

Description

Sound sources reverberate between each other. That is, the sound from a sound source can reverberate inside one reverberation zone and then reverberate together with its early reflections, reverberation and echo in another reverberation zone before it reaches the player.

int SOUND_REVERB_SINGLE

Description

Reverberation is calculated only when both the player is inside the reverberation zone. Sounds sources do not reverberate between reverberation zones even when the sound passes through a number of them. Instead, all reverb parameters are interpolated and then applied as, as if there is only one reverberation zone around the player.

float engine.sound.getAdaptation ()

Returns the current time set for sound adaptation, that is used when the sound source becomes occluded or other way round.

Return value

Time for sound adaptation to a filter.

float engine.sound.getDoppler ()

Returns the current Doppler factor.

Return value

Doppler factor.

float engine.sound.getScale ()

Returns the current time scale for the sound playing.

Return value

Sound time scale.

int engine.sound.getSourceLimit (int source)

Returns the current number of simultaneously played sound sources per one sound channel.

Arguments

• int source - ID number of the sound channel (from 0 to 31).

Return value

The maximum number of sound sources that can be played simultaneously.

float engine.sound.getSourceVolume (int source)

Returns the current volume of the specified sound channel.

Arguments

• int source - ID number of the sound channel (from 0 to 31).

Return value

Channel volume.

float engine.sound.getTotalTime ()

Returns the total time of the sound playing.

Return value

The total time value, milliseconds.

float engine.sound.getVelocity ()

Returns the current sound velocity.

Return value

Sound velocity.

float engine.sound.getVolume ()

Returns the current sound volume.

Return value

Volume. 0 means muted, 1 means maximum volume.

int engine.sound.isEnabled ()

Returns a value indicating if the sound is enabled.

Return value

1 if the sound is enabled; otherwise, 0.

int engine.sound.loadSettings (string name)

Load sound settings from the file with specified name.

Arguments

• string name - Sound settings file name.

Return value

1 if the sound settings are loaded successfully; otherwise, 0.

void engine.sound.renderWorld (int force)

Forces update of the sound system: all sound settings will be applied at once (such as play, stop events and change of parameters). A sound system has its own fixed frame rate (30 fps), while a script update rate can be much higher, which sometimes cause commands being skipped, unless a forced update is used.

Arguments

• int force - 1 to force update of the sound system; otherwise, 0.

int engine.sound.saveSettings (string name)

Save sound settings to the file with specified name.

Arguments

• string name - Sound settings file name.

Return value

1 if the sound settings are saved successfully; otherwise, 0.

void engine.sound.setAdaptation (float adaptation)

Sets sound occlusion with specified adaptation time. The default is 0.01.

Arguments

• float adaptation - Time for sound adaptation to a filter, used when the sound source becomes occluded or other way round.

void engine.sound.setDoppler (float doppler)

Set the Doppler effect. The default is 1.

Arguments

• float doppler - The Doppler factor.

void engine.sound.setEnabled (int enable)

Enables or disables the sound.

Arguments

• int enable - Positive integer to enable the sound; otherwise, 0.

void engine.sound.setScale (float scale)

Set the time scale for the sound playing. The default is 1.

Arguments

• float scale - Sound time scale. The provided value is saturated in the range [0; 2].

void engine.sound.setSourceLimit (int source, int limit)

Limits the number of simultaneously played sound sources per one sound channel.

Arguments

• int source - ID number of the sound channel (from 0 to 31).
• int limit - The maximum number of sound sources that can be played simultaneously.

void engine.sound.setSourceVolume (int source, float volume)

Sets the volume for the specified sound channel.

Arguments

• int source - ID number of the sound channel (from 0 to 31).
• float volume - Channel volume. The provided value is saturated within [0;1] range, where 0 means muted sound and 1 is the maximum volume.

void engine.sound.setVelocity (float velocity)

Sets the sound velocity. The default is 343.3 units per second.

Arguments

• float velocity - Sound velocity.

void engine.sound.setVolume (float volume)

Sets the sound volume. The default is 1.

Arguments

• float volume - Volume. 0 means muted, 1 means maximum volume.