Bos Wars Scripting API: Sound

Intro - Introduction to sound functions and variables

Everything around sound.

Functions

DefineGameSounds("name", arg, [[name2, arg] ...])

Specify some global sounds.

"name", arg

One of the following:

• "click", SoundId
• "placement-error", SoundId
• "placement-success", SoundId
• "rescue", SoundId

Where Soundid is the sound to use

RETURNS

Nothing

Example

--	Define sounds used by game
--
DefineGameSounds(

  "placement-error", MakeSound("placement error", "ui/placement_error.wav"),
  "placement-success", MakeSound("placement success", "ui/placement_success.wav"),
  "click", sound_click, -- sound_click already define as SoundId

-- FIXME: Not ready
--  "transport-docking",
--  "building-construction",

  "rescue", MakeSound("human rescue", "human/rescue.wav"),

MakeSound("name", "file" or {"file1", "file2", ...})

Asks the sound system to register a sound under a given name, with an associated list of files (the list can be replaced by only one file).

name

Name of the sound.

file

Name of the file or a list of files.

RETURNS

A SoundId object that represents the registered sound.

Example

-- Makes the sounds "lightning" and "basic human voices acknowledge".
MakeSound("lightning", "spells/lightning.wav")

MakeSound("basic human voices acknowledge",
	{"human/basic_voices/acknowledgement/1.wav",
	"human/basic_voices/acknowledgement/2.wav",
	"human/basic_voices/acknowledgement/3.wav",
	"human/basic_voices/acknowledgement/4.wav"})

MakeSoundGroup("name", "groupname1" or SoundId, "groupname2" or SoundId)

Asks the sound system to build a special sound group.

name

Name of the sound.

group1

SoundId or string

group2

SoundId or string

RETURNS

A SoundId object that represents the sound group.

Example

--	Define selection sound groups.
MakeSoundGroup("footman-selected",
	"basic human voices selected", "basic human voices annoyed")

MapSound("name", "sound")

Asks the sound system to remap a sound id to a given name.

name

Name of the sound.

sound

Sound to map to: either a sound name (a string) or a SoundId.

Example

-- Maps the name "footman-acknowledge" to "basic human voices acknowledge".
MapSound("footman-acknowledge", "basic human voices acknowledge")

PlaySoundFile("name" [, callback])

Plays a sound file.

name

Name of the file to play.

callback

An optional Lua function that the engine will call when the sound finishes playing.

RETURNS

The channel number allocated for the sound, or -1 if no channels are available. The Lua script can pass this number to various "Channel" functions to control the sound as it plays.

Example

-- Play the file "spells/lightning.wav", with no callback.
PlaySoundFile("spells/lightning.wav")

PlayFile("name" [, callback])

Like PlaySoundFile, except the callback must be a LuaActionListener object. Lua scripts should use PlaySoundFile instead.

PlayMusic("filename")

Plays music from the specified file.

name

Name of the music file.

RETURNS

0 if it started playing music from the file. -1 if music is disabled or an error occurred.

Example

-- Plays the music file "music/default.ogg".
PlayMusic("music/default.ogg")

PlaySound("name")

Asks the sound system to play the specified sound.

"name"

Name of the sound to play.

RETURNS

Nothing

Example

-- Play the sound "basic human voices ready".
PlaySound("basic human voices ready")

SetGlobalSoundRange(distance)

Sets the cut off distance.

distance

Max tile distance to hear sounds.

RETURNS

Nothing

Example

-- Set the sound range to 40.
SetGlobalSoundRange(40)

SetMusicVolume(volume)

Sets the music volume. GetMusicVolume reads this setting back.

volume

Number between 0 and MaxVolume.

RETURNS

Nothing

Example

-- Set the music volume to 128.
SetMusicVolume(128)

GetMusicVolume()

Gets the music volume. SetMusicVolume changes this setting.

RETURNS

Number between 0 and MaxVolume.

SetSoundRange("name", distance)

Sets the range of a given sound.

name

Name or SoundId of the sound.

distance

Max tile distance to hear the sound.

RETURNS

The name or SoundId given as the first parameter.

Example

-- Set the range of the sound "basic human voices ready" to 20.
SetSoundRange("basic human voices ready", 20)

SetEffectsVolume(volume)

Sets the volume of sound effects. GetEffectsVolume reads this setting back.

volume

Number between 0 and MaxVolume.

RETURNS

Nothing

Example

-- Set the sound volume to 128.
SetEffectsVolume(128)

GetEffectsVolume()

Gets the volume of sound effects. SetEffectsVolume changes this setting.

RETURNS

Number between 0 and MaxVolume.

SoundForName("name")

Asks the sound system to associate a sound id to a sound name.

name

Name of the sound.

RETURNS

SoundId

Example

SoundForName("peasant attack")

SetEffectsEnabled(enabled)

Turns sound effects on or off. IsEffectsEnabled reads this setting back.

enabled

true or false.

RETURNS

Nothing

Example

-- Turns on sound effects.
SetEffectsEnabled(true)

IsEffectsEnabled()

Checks whether sound effects are enabled. SetEffectsEnabled changes this setting.

RETURNS

true or false

SetMusicEnabled(enabled)

Turns music on or off. When music has been disabled with SetMusicEnabled(false), PlayMusic does nothing. IsMusicEnabled reads this setting back.

enabled

true or false.

RETURNS

Nothing

Example

-- Turns on music.
SetMusicEnabled(true)

IsMusicEnabled()

Checks whether music is enabled. SetMusicEnabled changes this setting.

RETURNS

true or false

StopMusic()

Stops playing music. Unlike SetMusicEnabled(false), this does not prevent PlayMusic from starting music again.

RETURNS

Nothing

Example

-- Stop playing music.
StopMusic()

SetChannelVolume(channel, volume)

Sets the sound volume of the channel.

channel

Channel number returned by PlaySoundFile.

volume

The new sound volume of the channel. Should be between 0 and MaxVolume. If this parameter is negative, then SetChannelVolume does not change the volume. If this parameter is too large, then SetChannelVolume uses MaxVolume instead.

RETURNS

The resulting sound volume of the channel, or -1 if the channel number is out of range.

SetChannelStereo(channel, stereo)

Sets the panning of the channel between the left and right outputs.

channel

Channel number returned by PlaySoundFile.

stereo

The new panning position of the channel. -128 means left, 0 means center, and 127 means right.

RETURNS

The resulting panning position of the channel, or -1 if the channel number is out of range.

StopChannel(channel)

Stops the sound playing in the specified channel.

channel

Channel number returned by PlaySoundFile.

RETURNS

Nothing

StopAllChannels()

Stops all sound effects currently playing. Calls their callback functions, if any. Does not stop music.

RETURNS

Nothing