Sounds (v1.12)

• Index

Contents

• Functions
• Objects

Topics

• settings
• api
• node
• groups
• animal_groups
• creature_groups
• firearm_groups
• node_groups
• projectile_groups
• scifi_groups
• vehicle_groups
• weather_groups
• tests
• README

Topic api

Sounds API

Functions

sounds:play (name[, sp])	Plays a sound.
sounds:play_random (snds[, sp])	Plays a random sound from a list.
sounds:stop (handle)	Wrapper for core.sound_stop.
sounds:register_biome_sounds (biome, snds[, params])	Registers sounds to play randomly in biome.
sounds:get_biome_sounds ([biome])	Retrieves sounds for biome.

Objects

SoundGroup	Sound Group.
SoundGroup (def)	Constructor.
SoundGroup:count ()	Retrieves number of sounds in group.
SoundGroup:play ([idx[, sp]])	Plays a sound from the group.
SoundGroup:get_random ()	Retrieves random name from group.
SoundGroup:get ([idx])	Retrieves sounds names in group.
iSoundGroup	Internal Sound Group.

Functions

sounds:play (name[, sp])

Plays a sound.

Parameters:

• name string Sound file without .ogg suffix.
• sp SoundParams Sound parameters. (optional)

Returns:

list (int) Sound handle or nil and (string) sound file name.

Usage:

local handle = sounds:play("sound1", {gain=1.0})
if handle then
  print("Sound handle: " .. handle)
end

sounds:play_random (snds[, sp])

Plays a random sound from a list.

Parameters:

• snds table List of sound names.
• sp SoundParams Sound parameters. (optional)

sounds:stop (handle)

Wrapper for core.sound_stop.

Parameters:

• handle int

sounds:register_biome_sounds (biome, snds[, params])

Registers sounds to play randomly in biome.

Parameters:

• biome string Biome name.
• snds Sounds registered with biome. Can be string, table, or SoundGroup.
• params table Sound parameter table. (optional)

sounds:get_biome_sounds ([biome])

Retrieves sounds for biome. sound groups are returned.

Parameters:

• biome string Biome name. (optional)

Returns:

SoundGroup or nil. If biome parameter is nil, then all registered biome

Objects

SoundGroup

Sound Group.

Fields:

• count SoundGroup:count Retrieves number of available sounds.
• play SoundGroup:play Plays indexed or random sound.
• prepend bool If set to true, prepends "sounds_" to sound filenames when played or accessed.

SoundGroup (def)

Constructor.

Parameters:

• def table Sound definition.

Returns:

SoundGroup Sound group definition table.

Usage:

-- create new sound groups
local s_group1 = SoundGroup({"sound1", "sound2", prepend=true})
local s_group2 = SoundGroup({"modname_sound1", "modname_sound2"})

-- play sound at index
s_group1:play(2)

-- play random sound from group
s_group1:play()

-- play sound at index with parameters
s_group1:play(1, {gain=1.0, max_hear_distance=100})

-- play random sound with parameters
s_group1:play({gain=1.0, max_hear_distance=100})

-- calling a SoundGroup instance directly is the same as executing the "play" method
s_group(1, {gain=1.0, max_hear_distance=100})

SoundGroup:count ()

Retrieves number of sounds in group.

Returns:

int

SoundGroup:play ([idx[, sp]])

Plays a sound from the group.

If idx is not specified, an available sound will be selected randomly from the group.

Notes:

• idx & sp parameters positions can be switched.

Parameters:

• idx int Sound index. (optional)
• sp SoundParams Sound parameters. (optional)

Returns:

int Sound handle or nil.

Usage:

local handle = SoundGroup:play(2, {gain=1.0})
if handle then
  print("Sound handle: " .. handle)
end

SoundGroup:get_random ()

Retrieves random name from group.

Returns:

string

SoundGroup:get ([idx])

Retrieves sounds names in group.

If idx is supplied, a string or nil is returned. If there is only one sound in the group, the string name of that sound is returned. Otherwise, a table is returned with all sound file names.

Parameters:

• idx int Sound index. (optional)

Returns:

string or table containing sound file names.

iSoundGroup

Internal Sound Group.

Same as SoundGroup but with "prepend" set to "true" by default. Meant for use with sound files prefixed with "sounds_" only.