LuaAPI: Add SetSoundMask, update PlaySound
Fri, 09 Mar 2018 13:02:44 +0000
changeset 1256 141ed1f83d56
parent 1255 64a6028803d4
child 1257 75747cc55f41
LuaAPI: Add SetSoundMask, update PlaySound
--- a/	Fri Mar 09 10:56:06 2018 +0000
+++ b/	Fri Mar 09 13:02:44 2018 +0000
@@ -1317,13 +1317,24 @@
 if it is `false`, cinematic mode is disabled.
 == Sound functions ==
-=== <tt>!PlaySound(soundId)</tt> ===
+=== `PlaySound(soundId, [gearUid [, instaVoice]])` ===
 Plays the specified sound. Possible values for `soundId` are listed on the [Sounds] page.
-=== <tt>!PlaySound(soundId, gearUid)</tt> ===
-Plays the specified sound for the chosen hedgehog gear. This can be used to play a taunt with the voicepack of the hedgehog’s team.
+If `gearUid` (optional argument) is set, you can also play a voice, see [Taunts] for a list. `gearUid` is the hedgehog gear which is used to “speak”.
+If you play a voice, by default the voice will respect an internal queue and might be played with an delay in order to prevent annoying voice overlapping. Since version 0.9.24, you can disable this behaviour and force Hedgewars to instantly play the voice by also setting `instaVoice` to `true`.
+=== `SetSoundMask(soundId, isMasked)` (0.9.24) ===
+Disables a given sound (including taunts) from being played by the engine. `soundId` is a valid sound ID on [Sounds] or [Taunts]. `isMasked` is a boolean. If `true`, the sound will not be played by the engine anymore. If `false`, playing this sound is allowed again.
-Possible values for `soundId` are listed on the [Sounds] page. See also [Taunts].
+Sounds played by the Lua function `PlaySound` will always work, however, and ignore the sound mask.
+Note: Due to the way the voices work internally in Hedgewars, if you want to play a masked voice, you have to set `instaVoice` to `true` when you call `PlaySound`. Otherwise, it won't work.
+<code language="lua">SetSoundMask(sndIncoming, true)
+-- Disable the “Incoming” sound from being played</code>
 == File system functions ==
 === <tt>!HedgewarsScriptLoad(scriptPath)</tt> ===