# Bos Wars Scripting API: Sound

Bos Wars FAQ PREV NEXT LUA Index

DefineGameSounds GetEffectsVolume GetMusicVolume IsEffectsEnabled IsMusicEnabled MakeSound MakeSoundGroup MapSound PlayFile PlayMusic PlaySound PlaySoundFile SetChannelStereo SetChannelVolume SetEffectsEnabled SetEffectsVolume SetGlobalSoundRange SetMusicEnabled SetMusicVolume SetSoundRange SoundForName StopAllChannels StopChannel StopMusic

## 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

All trademarks and copyrights on this page are owned by their respective owners.