Skyline Lua API  Version 1.0 RC1
Lua Script Reference for Skyline Game Engine.
sound Class Reference

#include <LUA_API_Sound.h>

Public Member Functions

void setLooped (int enableState)
 Set the looped state of the sound. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound(). More...
 
void setVolume (float volume)
 Set the Volume of the new sound to create. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound(). More...
 
void setPitch (float pitch)
 Set the Pitch of the new sound to create. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound(). More...
 
void setSoundFile (string soundFilename)
 Set the Soundfile to use. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound(). More...
 
void setIsStreamed (int enableState)
 Set whether the Soundfile is streamed from the hard drive. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound(). More...
 
int createSound ()
 Create a new 2D Sound using the Properties you set by calling the previous functions. This will return a sound ID that you can use to identify the sound. More...
 
void play2DSound (int soundID)
 Play the Specified sound by passing this function a Sound ID. More...
 
void play3DSound (int soundID, float posX, float posY, float posZ)
 Play the Specified sound in 3D space by passing this function a Sound ID. This will play the sound at a location in world space. When the camera moves closer to the sound, then the volume increases. If the camera moves away from the sound, then the volume decreases. More...
 
void stopSound (int soundID)
 Stop a sound that is currently playing. More...
 
int isPlaying (int soundID)
 Check whether a sound is being played. Looped sounds are automatically stopped, so their playing flag changes to 0 when the loop stops. More...
 
void changePosition (int soundID, float posX, float posY, float posZ)
 Change the location in world space of a 3D sound that is playing. The 3D sound can be accessed by passing the sound ID through the function. More...
 
void changeVolume (int soundID, float volume)
 Change the Volume of a sound without stopping and playing the effect. It also works on sounds that loop and can be lengthy. More...
 
void changePitch (int soundID, float pitch)
 Change the Pitch of a sound without stopping and restarting the effect. It also works on sounds that loop and sounds that are lengthy. More...
 
void setRolloff (int soundID, float rolloff)
 Sets the sounds attenuation fall off amount ie how quicly the sound fades out. More...
 
void setMaxDistance (int soundID, float distance)
 Sets the sounds max attenuation distance. At this distance the sound will be at its lowest volume or zero based on an exponential equation. Use the rolloff the change the attenuation curve. More...
 
void setMinDistance (int soundID, float distance)
 Sets the sounds min attenuation distance. This is where the sound will be at its loudest before attenuation begins based on an exponential equation. More...
 
void freeSound (int soundID)
 Frees the sound for reuse. It also works on sounds that loop and sounds that are lengthy. More...
 
sound distanceAttenuation (int soundID, float minDistance, float maxDistance, float minimum, float maximum)
 add to an update() to give an spawned sound distance attenuation. More...
 

Detailed Description

The following ui functions can be used to display basic game play data, very light weight and handy when prototyping a game idea.
Use as sound.function()
For more information on how these functions can be used please visit the User Manual - http://www.chi-ad.com/Skyline/SDN/

Here is a Global Example of how to create and use a Sound:

function onInit(objID)
    sound.setLooped( 1 );
    sound.setVolume( 1 );
    sound.setSoundFile( "My_Sound.ogg" );
    sound.setIsStreamed( 0 );
    sound_ID = sound.createSound();
    sound.play2DSound( sound_ID );
end

Member Function Documentation

void sound::changePitch ( int  soundID,
float  pitch 
)

Change the Pitch of a sound without stopping and restarting the effect. It also works on sounds that loop and sounds that are lengthy.

Parameters
soundID: The sound the ID represents will be played.
pitch: How loud the sound is. 0 - low pitch(0 is no sound), 1 - normal pitch. >1 higher pitch.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.changePitch( sound_ID, 0.5 );
end
void sound::changePosition ( int  soundID,
float  posX,
float  posY,
float  posZ 
)

Change the location in world space of a 3D sound that is playing. The 3D sound can be accessed by passing the sound ID through the function.

Parameters
soundID: The sound the ID represents will be played.
posX: The position on the X axis in world space to play this sound.
posY: The position on the Y axis in world space to play this sound.
posZ: The position on the Z axis in world space to play this sound.

The following is a Small Example on how to use this function:

function onInit(objID)
    x,y,z = entity.getPosition(objID);
    sound.changePosition( sound_ID, x, y, z );
end
void sound::changeVolume ( int  soundID,
float  volume 
)

Change the Volume of a sound without stopping and playing the effect. It also works on sounds that loop and can be lengthy.

Parameters
soundID: The sound the ID represents will be played.
volume: How loud the sound is. 0 - no sound, 1 - normal sound. >1 extra volume.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.changeVolume( sound_ID, 0.5 );
end
int sound::createSound ( )

Create a new 2D Sound using the Properties you set by calling the previous functions. This will return a sound ID that you can use to identify the sound.

Returns
soundID : The ID of the sound for use later. E.g. when playing the sound you will need the ID to reference the sound.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound_ID = sound.createSound();
end
sound sound::distanceAttenuation ( int  soundID,
float  minDistance,
float  maxDistance,
float  minimum,
float  maximum 
)

add to an update() to give an spawned sound distance attenuation.

Parameters
soundID: The sound the ID represents will be freed.
minDistance:
maxDistance:
minimum:
maximum:
void sound::freeSound ( int  soundID)

Frees the sound for reuse. It also works on sounds that loop and sounds that are lengthy.

Parameters
soundID: The sound the ID represents will be freed.

Frees the sound ID so that the 256 limit is not reached. It is advisable to call this from the lua stop event
to free the sound for reuse next time the game is played from the editor. This will not be an issue in the final game exe
only required for development.

The following is a Small Example on how to use this function:

function onStop(  )
    sound.freeSound(sound_ID);
end
int sound::isPlaying ( int  soundID)

Check whether a sound is being played. Looped sounds are automatically stopped, so their playing flag changes to 0 when the loop stops.

Parameters
soundID: The sound ID to check if playing.

The following is a Small Example on how to use this function:

function update(objID)
    soundIsPlaying = sound.isPlaying(sound_ID);
    sky.lprint("soundIsPlaying"..soundIsPlaying);
end

-- should print 1 or 0
void sound::play2DSound ( int  soundID)

Play the Specified sound by passing this function a Sound ID.

Parameters
soundID: The sound the ID represents will be played.
Use the Functions setLooped(), setVolume(), setPitch(), setSoundFile() and setIsStreamed() to control the properties of the sound to play.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.play2DSound( sound_ID );
end
void sound::play3DSound ( int  soundID,
float  posX,
float  posY,
float  posZ 
)

Play the Specified sound in 3D space by passing this function a Sound ID. This will play the sound at a location in world space. When the camera moves closer to the sound, then the volume increases. If the camera moves away from the sound, then the volume decreases.

Also has built in doppler effect.

Parameters
soundID: The sound the ID represents will be played.
posX: The position on the X axis in world space to play this sound.
posY: The position on the Y axis in world space to play this sound.
posZ: The position on the Z axis in world space to play this sound.

Use the Functions setLooped(), setVolume(), setPitch(), setSoundFile() and setIsStreamed() to control the properties of the sound to play.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.play3DSound( sound_ID, 0, 0, 0 );
end
void sound::setIsStreamed ( int  enableState)

Set whether the Soundfile is streamed from the hard drive. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters
enableState: 0 = false; 1 = true. Set whether the sound is streamed.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setIsStreamed( 0 );
end
void sound::setLooped ( int  enableState)

Set the looped state of the sound. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters
enableState: 0 = false; 1 = true. Set whether this sound is looped or not

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setLooped( 1 );
end
void sound::setMaxDistance ( int  soundID,
float  distance 
)

Sets the sounds max attenuation distance. At this distance the sound will be at its lowest volume or zero based on an exponential equation. Use the rolloff the change the attenuation curve.

Parameters
soundID: The sound the ID represents will be played.
distance: The max attenuation distance.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setMaxDistance(soundID,0.9);
end
void sound::setMinDistance ( int  soundID,
float  distance 
)

Sets the sounds min attenuation distance. This is where the sound will be at its loudest before attenuation begins based on an exponential equation.

Parameters
soundID: The sound the ID represents will be played.
distance: The min attenuation distance.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setMinDistance(soundID,0.9);
end
void sound::setPitch ( float  pitch)

Set the Pitch of the new sound to create. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters
volume: Set the Pitch of the sound to create.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setPitch( 1 );
end
void sound::setRolloff ( int  soundID,
float  rolloff 
)

Sets the sounds attenuation fall off amount ie how quicly the sound fades out.

Parameters
soundID: The sound the ID represents will be played.
rolloff: The attenuation falloff.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setRolloff(soundID,0.9);
end
void sound::setSoundFile ( string  soundFilename)

Set the Soundfile to use. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters
soundFilename: Set the Soundfile to use. You will need to specify the file format the sound is in.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setSoundFile( "My_Sound.ogg" );
end
void sound::setVolume ( float  volume)

Set the Volume of the new sound to create. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters
volume: Set the Volume of the sound to create.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setVolume( 1 );
end
void sound::stopSound ( int  soundID)

Stop a sound that is currently playing.

Parameters
soundID: The sound ID to stop playing.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.play3DSound( sound_ID, 0, 0, 0 );
end

function onKeyDown(key)
    if( key == "1" and sound.isPlaying(sound_ID) == 1 )then sound.stopSound(sound_ID); end
end

The documentation for this class was generated from the following file: