# HG changeset patch
# User Wuzzy
# Date 1520600564 0
# Node ID 141ed1f83d568a0d0f0faa6854fcd8544bb5cacf
# Parent  64a6028803d4c71dbbc46bd425b22e5d459e6874
LuaAPI: Add SetSoundMask, update PlaySound

diff -r 64a6028803d4 -r 141ed1f83d56 LuaAPI.wiki
--- a/LuaAPI.wiki	Fri Mar 09 10:56:06 2018 +0000
+++ b/LuaAPI.wiki	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.
+
+Example:
+
+<code language="lua">SetSoundMask(sndIncoming, true)
+-- Disable the “Incoming” sound from being played</code>
 
 == File system functions ==
 === <tt>!HedgewarsScriptLoad(scriptPath)</tt> ===