Scripting API

Home Scripting API Index Class Overview

com.nolimitscoaster

Class StaticSound

public final class StaticSound
extends Object

Represents a sound file. In contrast to stream sounds, static sounds are completely loaded in memory.

Field Summary
static final int E_ENVMODE_GLOBAL
Recommended for sounds that are located outside in the wide open. Accepted by setEnvironmentMode.
static final int E_ENVMODE_LOCAL
The environment will be computed based on the sound's position. Accepted by setEnvironmentMode.
static final int E_ENVMODE_PLAIN
No environmental effect. This is the default. Accepted by setEnvironmentMode.
static final int E_ENVMODE_SAME_AS_LISTENER
Same environmental effect as found in the listener's position.
static final int FLAG_MIXDOWN_MONO
When this flag is specified, the sound will be reduced to mono if it should be a stereo file. Stereo sounds cannot be spartialized properly using the position and distance parameters, while mono sounds can.
static final int FLAG_MUSIC
When this flag is specified, the sound's gain will be controlled by the music volume from the setup instead of the sound volume.
static final int FLAG_SHARED
When this flag is specified, the sound will be shared with other instances that use this flags, too.


Method Summary
double getLength()
  Returns the length of the sound
static StaticSound loadFromFile(String path, int flags)
  Load a static sound file using a file path and create a handle for playback.
static StaticSound loadFromResource(ResourcePath resourcePath, int flags)
  Load a static sound file handle using a resource path and create a handle for playback.
static StaticSound loadFromResourceId(String resourceId, int flags)
  Load a static sound file handle using a resourceId and create a handle for playback.
void play()
  Plays the sound (single shot)
void playLoop()
  Plays the sound (looped)
void setAmbientMode(bool enable)
  Set to true to change from normal mode to ambient mode.
void setDistanceParameters(float referenceDistance, float rolloffFactor)
  Sets the sound source's distance parameters that will affect the distance attenuation.
void setDopplerMode(bool enable)
  Enable or disable the doppler effect.
void setEnvironmentMode(int mode)
  Sets the environment mode for environmental effects.
void setGain(float gain)
  Sets the sound source's gain.
void setGainFaded(float gain, float fadeTime)
  Sets the sound source's target gain. Fades over time to the target gain from the current gain.
void setPitch(float pitch)
  Sets the sound's pitch (frequency) factor
void setPosition(nlvm.math3d.Vector3f p)
  Sets the sound source's position in world coordinates.
void stop()
  Stops playing the sound immediately.
void stopFaded(float fadeTime)
  Fades the sound and stops playing as soon as the volume has reached 0.


Field Detail

E_ENVMODE_GLOBAL

public static final int E_ENVMODE_GLOBAL

Recommended for sounds that are located outside in the wide open. Accepted by setEnvironmentMode.

E_ENVMODE_LOCAL

public static final int E_ENVMODE_LOCAL

The environment will be computed based on the sound's position. Accepted by setEnvironmentMode.

E_ENVMODE_PLAIN

public static final int E_ENVMODE_PLAIN

No environmental effect. This is the default. Accepted by setEnvironmentMode.

E_ENVMODE_SAME_AS_LISTENER

public static final int E_ENVMODE_SAME_AS_LISTENER

Same environmental effect as found in the listener's position.

Recommended for sounds that move together with the listener. Accepted by setEnvironmentMode.

FLAG_MIXDOWN_MONO

public static final int FLAG_MIXDOWN_MONO

When this flag is specified, the sound will be reduced to mono if it should be a stereo file. Stereo sounds cannot be spartialized properly using the position and distance parameters, while mono sounds can.

Accepted by the flags parameter of loadFromFile and loadFromResourceId

FLAG_MUSIC

public static final int FLAG_MUSIC

When this flag is specified, the sound's gain will be controlled by the music volume from the setup instead of the sound volume.

Accepted by the flags parameter of loadFromFile and loadFromResourceId

FLAG_SHARED

public static final int FLAG_SHARED

When this flag is specified, the sound will be shared with other instances that use this flags, too.

The sound will be played synchronized among all instances. This can be used to simulate ambient sounds or sounds from multiple speakers. The doppler effect is not available in shared mode. Accepted by the flags parameter of loadFromFile and loadFromResourceId

Method Detail

getLength

public final double getLength()

Returns the length of the sound

Returns:
    length of sound in seconds at pitch = 1

Since:
    2.5.5.0

loadFromFile

public static StaticSound loadFromFile(String path, int flags)

Load a static sound file using a file path and create a handle for playback.

The path should be a constant string expression so that the park package tool can detect used files. If the path is not a constant string expression, the compiler will show a warning and the file will not be detected by the package tool and will therefore not automatically be added to the park package. Will return null if the file could not be loaded. Set flags to 0 if no special features should be used.

Parameters:

path - path to file (relative to the classpath)
flags - bitwise or combination ( | ) of options. Use 0 for default. Valid options are FLAG_SHARED, FLAG_MUSIC, FLAG_MIXDOWN_MONO.

loadFromResource

public static StaticSound loadFromResource(ResourcePath resourcePath, int flags)

Load a static sound file handle using a resource path and create a handle for playback.

The resources can be specified in the script setup and can be obtained from the Script.getResourceForId method. Will return null if the resource path is null or the sound file could not be loaded. Set flags to 0 if no special features should be used.

Parameters:

resourcePath - The resource path that can be obtained from Script.getResourcePathForId
flags - bitwise or combination ( | ) of options. Use 0 for default. Valid options are FLAG_SHARED, FLAG_MUSIC, FLAG_MIXDOWN_MONO.

Returns:
    Handle to sound. Will return null if the resourceId is unknown or the sound file could not be loaded.

loadFromResourceId

public static StaticSound loadFromResourceId(String resourceId, int flags)

Load a static sound file handle using a resourceId and create a handle for playback.

The resourceId has to be specified in the script setup. Will return null if the resourceId is unknown or the sound file could not be loaded. Set flags to 0 if no special features should be used.

Parameters:

resourceId - The resource id as specified in the script description (nl2script) file
flags - bitwise or combination ( | ) of options. Use 0 for default. Valid options are FLAG_SHARED, FLAG_MUSIC, FLAG_MIXDOWN_MONO.

Returns:
    Handle to sound. Will return null if the resourceId is unknown or the sound file could not be loaded.

Note: Deprecated  since 2.5.7.0 Use loadFromResource instead because the resourceId might not be found in special listener states

play

public final void play()

Plays the sound (single shot)

playLoop

public final void playLoop()

Plays the sound (looped)

setAmbientMode

public final void setAmbientMode(bool enable)

Set to true to change from normal mode to ambient mode.

Default is false. In ambient mode, the sound will not be affected by the distance parameters. Will be ignored when it is a shared sound (It was loaded using FLAG_SHARED).

setDistanceParameters

public final void setDistanceParameters(float referenceDistance, float rolloffFactor)

Sets the sound source's distance parameters that will affect the distance attenuation.

The Inverse Distance Clamped Distance Attenuation Model is used internally, using the following formula to compute the final gain: distance = max(distance, referenceDistance); FinalGain = gain * referenceDistance / (referenceDistance + rolloffFactor * (distance - referenceDistance)); Default is 1.0f, 1.0f. Distance parameters will be ignored for ambient sounds.

setDopplerMode

public final void setDopplerMode(bool enable)

Enable or disable the doppler effect.

Default is true for non-ambient sounds. Doppler will be ignored for ambient and shared sounds.

setEnvironmentMode

public final void setEnvironmentMode(int mode)

Sets the environment mode for environmental effects.

Parameters:

mode - See E_ENVMODE_ constants for acceptable values

setGain

public final void setGain(float gain)

Sets the sound source's gain.

Parameters:

gain - 0..1

setGainFaded

public final void setGainFaded(float gain, float fadeTime)

Sets the sound source's target gain. Fades over time to the target gain from the current gain.

Parameters:

gain - 0..1
fadeTime - in seconds, must be >= 0

setPitch

public final void setPitch(float pitch)

Sets the sound's pitch (frequency) factor

Setting the pitch has no effect for sounds created with the FLAG_SHARED flag.

Parameters:

pitch - frequency factor of playback (1 = original frequency of sound file). Values will be clamped to 0.1f and 10.0f.

Since:
    2.1.0.4

setPosition

public final void setPosition(nlvm.math3d.Vector3f p)

Sets the sound source's position in world coordinates.

Default is 0,0,0

stop

public final void stop()

Stops playing the sound immediately.

stopFaded

public final void stopFaded(float fadeTime)

Fades the sound and stops playing as soon as the volume has reached 0.

Parameters:

fadeTime - in seconds, must be >= 0