# Bos Wars Scripting API: Sound

Stratagus FAQ PREV NEXT LUA Index

DefineGameSounds MakeSound MakeSoundGroup MapSound PlayFile PlayMusic PlaySound SetCdMode SetGlobalSoundRange SetMusicVolume SetSoundRange SetSoundVolume SoundForName SoundOff SoundOn 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",{"RaceName", SoundId}
  "work-complete", {RaceName, SoundId}
Where Soundid is the sound to use
And RaceName the concerned race.

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

      "work-complete", {"human", MakeSound("basic human voices work complete", "human/basic_voices/work_complete.wav")},
      "work-complete", {"orc", MakeSound("basic orc voices work complete", "orc/basic_voices/work_complete.wav")},

      "rescue", {"human", MakeSound("human rescue", "human/rescue.wav")},
      "rescue", {"orc", MakeSound("orc rescue", "orc/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.

#### 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.
group
  sound-id or string

#### Example

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

### MapSound("name", "sound")

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

name
  Name of the sound.
sound
  Sound to map to.

#### Example

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

### PlayFile("name")

Play a sound file.

name
  Name of the file to play.

#### Example

    -- Play the file "spells/lightning.wav".
    PlayFile("spells/lightning.wav")

### PlayMusic("name")

Name of the music file to play.

name
  Name of the music file.

#### Example

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

### PlaySound("name")

Ask the sound system to play the specified sound.

"name"
  Name of the sound to play.

#### Example

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

### SetCdMode("mode")

Set the cd mode.

"all"
  plays all tracks
"random"
  plays random tracks
"defined"
  play according to playlist below. define before playlist = {"song1", "song2", ...}
"off"
  turns cd player off

#### Example

    -- Set the cd mode to play songs in a random order.
    SetCdMode("random")

### SetGlobalSoundRange(distance)

Set the cut off distance.

distance
  Max tile distance to hear sounds.

#### Example

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

### SetMusicVolume(volume)

Set the music volume.

volume
  Number between 0 and MaxVolume.

#### Example

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

### SetSoundRange("name", distance)

Set the range of a given sound.

name
  Name of the sound.
distance
  Max tile distance to hear the sound.

#### Example

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

### SetSoundVolume(volume)

Global volume support.

volume
  Number between 0 and MaxVolume.

#### Example

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

### SoundForName("name")

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

name
  Name of the sound.

#### Example

    SoundForName("peasant attack")

### SoundOff()

Turn off sound.

#### Example

    -- Turns off sound.
    SoundOff()

### SoundOn()

Turn on sound.

#### Example

    -- Turns on sound.
    SoundOn()

### StopMusic()

Stop playing music.

#### Example

    -- Stop playing music.
    StopMusic()

Last changed: $Id: sound.html 8569 2007-02-10 23:21:43Z feb $
All trademarks and copyrights on this page are owned by their respective owners.