@defold-typescript/types 0.52.0 → 0.54.0

package/fixtures/defold-1.13.1/sound_doc.json

@@ -0,0 +1,582 @@
+{
+  "elements": [
+    {
+      "type": "PROPERTY",
+      "name": "gain",
+      "brief": "<span class=\"type\">number</span> sound gain",
+      "description": "The gain on the sound-component. Note that gain is in linear scale,\nbetween 0 and 1.",
+      "returnvalues": [],
+      "parameters": [],
+      "examples": "<div class=\"codehilite\"><pre><span></span><code><span class=\"kr\">function</span> <span class=\"nf\">init</span><span class=\"p\">(</span><span class=\"n\">self</span><span class=\"p\">)</span>\n  <span class=\"kd\">local</span> <span class=\"n\">gain</span> <span class=\"o\">=</span> <span class=\"n\">go</span><span class=\"p\">.</span><span class=\"n\">get</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;gain&quot;</span><span class=\"p\">)</span>\n  <span class=\"n\">go</span><span class=\"p\">.</span><span class=\"n\">set</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;gain&quot;</span><span class=\"p\">,</span> <span class=\"n\">gain</span> <span class=\"o\">*</span> <span class=\"mf\">1.5</span><span class=\"p\">)</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "PROPERTY",
+      "name": "pan",
+      "brief": "<span class=\"type\">number</span> sound pan",
+      "description": "The pan on the sound-component. The valid range is from -1.0 to 1.0,\nrepresenting -45 degrees left, to +45 degrees right.",
+      "returnvalues": [],
+      "parameters": [],
+      "examples": "<div class=\"codehilite\"><pre><span></span><code><span class=\"kr\">function</span> <span class=\"nf\">init</span><span class=\"p\">(</span><span class=\"n\">self</span><span class=\"p\">)</span>\n  <span class=\"kd\">local</span> <span class=\"n\">pan</span> <span class=\"o\">=</span> <span class=\"n\">go</span><span class=\"p\">.</span><span class=\"n\">get</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;pan&quot;</span><span class=\"p\">)</span>\n  <span class=\"n\">go</span><span class=\"p\">.</span><span class=\"n\">set</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;pan&quot;</span><span class=\"p\">,</span> <span class=\"n\">pan</span> <span class=\"o\">*</span> <span class=\"o\">-</span><span class=\"mi\">1</span><span class=\"p\">)</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "PROPERTY",
+      "name": "speed",
+      "brief": "<span class=\"type\">number</span> sound speed",
+      "description": "The speed on the sound-component where 1.0 is normal speed, 0.5 is half\nspeed and 2.0 is double speed. Valid range is 0.0 to 50.0.",
+      "returnvalues": [],
+      "parameters": [],
+      "examples": "<div class=\"codehilite\"><pre><span></span><code><span class=\"kr\">function</span> <span class=\"nf\">init</span><span class=\"p\">(</span><span class=\"n\">self</span><span class=\"p\">)</span>\n  <span class=\"kd\">local</span> <span class=\"n\">speed</span> <span class=\"o\">=</span> <span class=\"n\">go</span><span class=\"p\">.</span><span class=\"n\">get</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;speed&quot;</span><span class=\"p\">)</span>\n  <span class=\"n\">go</span><span class=\"p\">.</span><span class=\"n\">set</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;speed&quot;</span><span class=\"p\">,</span> <span class=\"n\">speed</span> <span class=\"o\">*</span> <span class=\"mf\">0.5</span><span class=\"p\">)</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "PROPERTY",
+      "name": "sound",
+      "brief": "<span class=\"type\">hash</span> sound data",
+      "description": "The sound data used when playing the sound. The type of the property is hash.",
+      "returnvalues": [],
+      "parameters": [],
+      "examples": "How to change the sound:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kr\">function</span> <span class=\"nf\">init</span><span class=\"p\">(</span><span class=\"n\">self</span><span class=\"p\">)</span>\n  <span class=\"c1\">-- load a wav file bundled as a custom resource</span>\n  <span class=\"kd\">local</span> <span class=\"n\">wav</span> <span class=\"o\">=</span> <span class=\"n\">sys</span><span class=\"p\">.</span><span class=\"n\">load_resource</span><span class=\"p\">(</span><span class=\"s2\">&quot;foo.wav&quot;</span><span class=\"p\">)</span>\n  <span class=\"c1\">-- get resource path to the sound component</span>\n  <span class=\"kd\">local</span> <span class=\"n\">resource_path</span> <span class=\"o\">=</span> <span class=\"n\">go</span><span class=\"p\">.</span><span class=\"n\">get</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;sound&quot;</span><span class=\"p\">)</span>\n  <span class=\"c1\">-- update the resource with the loaded wav file</span>\n  <span class=\"n\">resource</span><span class=\"p\">.</span><span class=\"n\">set_sound</span><span class=\"p\">(</span><span class=\"n\">resource_path</span><span class=\"p\">,</span> <span class=\"n\">wav</span><span class=\"p\">)</span>\n  <span class=\"c1\">-- play the updated sound</span>\n  <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">play</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">)</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.is_music_playing",
+      "brief": "check if background music is playing",
+      "description": "Checks if background music is playing, e.g. from iTunes.\n<span class=\"icon-macos\"></span><span class=\"icon-windows\"></span><span class=\"icon-linux\"></span><span class=\"icon-html5\"></span> On non mobile platforms,\nthis function always return <code>false</code>.\n<span class=\"icon-attention\"></span><span class=\"icon-android\"></span> On Android you can only get a correct reading\nof this state if your game is not playing any sounds itself. This is a limitation\nin the Android SDK. If your game is playing any sounds, <em>even with a gain of zero</em>, this\nfunction will return <code>false</code>.\nThe best time to call this function is:\n<ul>\n<li>In the <code>init</code> function of your main collection script before any sounds are triggered</li>\n<li>In a window listener callback when the window.WINDOW_EVENT_FOCUS_GAINED event is received</li>\n</ul>\nBoth those times will give you a correct reading of the state even when your application is\nswapped out and in while playing sounds and it works equally well on Android and iOS.",
+      "returnvalues": [
+        {
+          "name": "playing",
+          "doc": "<code>true</code> if music is playing, otherwise <code>false</code>.",
+          "types": ["boolean"]
+        }
+      ],
+      "parameters": [],
+      "examples": "If music is playing, mute \"master\":\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kr\">if</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">is_music_playing</span><span class=\"p\">()</span> <span class=\"kr\">then</span>\n    <span class=\"c1\">-- mute &quot;master&quot;</span>\n    <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">set_group_gain</span><span class=\"p\">(</span><span class=\"s2\">&quot;master&quot;</span><span class=\"p\">,</span> <span class=\"mi\">0</span><span class=\"p\">)</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.get_rms",
+      "brief": "get RMS value from mixer group",
+      "description": "Get RMS (Root Mean Square) value from mixer group. This value is the\nsquare root of the mean (average) value of the squared function of\nthe instantaneous values.\nFor instance: for a sinewave signal with a peak gain of -1.94 dB (0.8 linear),\nthe RMS is <code>0.8 &times; 1/sqrt(2)</code> which is about 0.566.\n<span class=\"icon-attention\"></span> Note the returned value might be an approximation and in particular\nthe effective window might be larger than specified.",
+      "returnvalues": [
+        {
+          "name": "rms_l",
+          "doc": "RMS value for left channel",
+          "types": ["number"]
+        },
+        {
+          "name": "rms_r",
+          "doc": "RMS value for right channel",
+          "types": ["number"]
+        }
+      ],
+      "parameters": [
+        {
+          "name": "group",
+          "doc": "group name",
+          "types": ["string", "hash"],
+          "is_optional": "False"
+        },
+        {
+          "name": "window",
+          "doc": "window length in seconds",
+          "types": ["number"],
+          "is_optional": "False"
+        }
+      ],
+      "examples": "Get the RMS from the \"master\" group where a mono -1.94 dB sinewave is playing:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kd\">local</span> <span class=\"n\">rms</span> <span class=\"o\">=</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">get_rms</span><span class=\"p\">(</span><span class=\"s2\">&quot;master&quot;</span><span class=\"p\">,</span> <span class=\"mf\">0.1</span><span class=\"p\">)</span> <span class=\"c1\">-- throw away right channel.</span>\n<span class=\"nb\">print</span><span class=\"p\">(</span><span class=\"n\">rms</span><span class=\"p\">)</span> <span class=\"c1\">--&gt; 0.56555819511414</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.get_peak",
+      "brief": "get peak gain value from mixer group",
+      "description": "Get peak value from mixer group.\n<span class=\"icon-attention\"></span> Note that gain is in linear scale, between 0 and 1.\nTo get the dB value from the gain, use the formula <code>20 * log(gain)</code>.\nInversely, to find the linear value from a dB value, use the formula\n<code>10<sup>db/20</sup></code>.\nAlso note that the returned value might be an approximation and in particular\nthe effective window might be larger than specified.",
+      "returnvalues": [
+        {
+          "name": "peak_l",
+          "doc": "peak value for left channel",
+          "types": ["number"]
+        },
+        {
+          "name": "peak_r",
+          "doc": "peak value for right channel",
+          "types": ["number"]
+        }
+      ],
+      "parameters": [
+        {
+          "name": "group",
+          "doc": "group name",
+          "types": ["string", "hash"],
+          "is_optional": "False"
+        },
+        {
+          "name": "window",
+          "doc": "window length in seconds",
+          "types": ["number"],
+          "is_optional": "False"
+        }
+      ],
+      "examples": "Get the peak gain from the \"master\" group and convert to dB for displaying:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kd\">local</span> <span class=\"n\">left_p</span><span class=\"p\">,</span> <span class=\"n\">right_p</span> <span class=\"o\">=</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">get_peak</span><span class=\"p\">(</span><span class=\"s2\">&quot;master&quot;</span><span class=\"p\">,</span> <span class=\"mf\">0.1</span><span class=\"p\">)</span>\n<span class=\"n\">left_p_db</span> <span class=\"o\">=</span> <span class=\"mi\">20</span> <span class=\"o\">*</span> <span class=\"n\">log</span><span class=\"p\">(</span><span class=\"n\">left_p</span><span class=\"p\">)</span>\n<span class=\"n\">right_p_db</span> <span class=\"o\">=</span> <span class=\"mi\">20</span> <span class=\"o\">*</span> <span class=\"n\">log</span><span class=\"p\">(</span><span class=\"n\">right_p</span><span class=\"p\">)</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.set_group_gain",
+      "brief": "set mixer group gain",
+      "description": "Set mixer group gain",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "group",
+          "doc": "group name",
+          "types": ["string", "hash"],
+          "is_optional": "False"
+        },
+        {
+          "name": "gain",
+          "doc": "gain in range [0..1] mapped to [0 .. -60dB]",
+          "types": ["number"],
+          "is_optional": "False"
+        }
+      ],
+      "examples": "Set mixer group gain on the \"soundfx\" group to 50% (-30dB):\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">set_group_gain</span><span class=\"p\">(</span><span class=\"s2\">&quot;soundfx&quot;</span><span class=\"p\">,</span> <span class=\"mf\">0.5</span><span class=\"p\">)</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.get_group_gain",
+      "brief": "get mixer group gain",
+      "description": "Get mixer group gain",
+      "returnvalues": [
+        {
+          "name": "gain",
+          "doc": "gain in [0 1] range ([-60dB.. 0dB])",
+          "types": ["number"]
+        }
+      ],
+      "parameters": [
+        {
+          "name": "group",
+          "doc": "group name",
+          "types": ["string", "hash"],
+          "is_optional": "False"
+        }
+      ],
+      "examples": "Get the mixer group gain for the \"soundfx\" and convert to dB:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kd\">local</span> <span class=\"n\">gain</span> <span class=\"o\">=</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">get_group_gain</span><span class=\"p\">(</span><span class=\"s2\">&quot;soundfx&quot;</span><span class=\"p\">)</span>\n<span class=\"kd\">local</span> <span class=\"n\">gain_db</span> <span class=\"o\">=</span> <span class=\"mi\">60</span> <span class=\"o\">*</span> <span class=\"n\">gain</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.get_groups",
+      "brief": "get all mixer group names",
+      "description": "Get a table of all mixer group names (hashes).",
+      "returnvalues": [
+        {
+          "name": "groups",
+          "doc": "table of mixer group names",
+          "types": ["table"]
+        }
+      ],
+      "parameters": [],
+      "examples": "Get the mixer groups, set all gains to 0 except for \"master\" and \"soundfx\"\nwhere gain is set to 1:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kd\">local</span> <span class=\"n\">groups</span> <span class=\"o\">=</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">get_groups</span><span class=\"p\">()</span>\n<span class=\"kr\">for</span> <span class=\"n\">_</span><span class=\"p\">,</span><span class=\"n\">group</span> <span class=\"kr\">in</span> <span class=\"nb\">ipairs</span><span class=\"p\">(</span><span class=\"n\">groups</span><span class=\"p\">)</span> <span class=\"kr\">do</span>\n    <span class=\"kr\">if</span> <span class=\"n\">group</span> <span class=\"o\">==</span> <span class=\"n\">hash</span><span class=\"p\">(</span><span class=\"s2\">&quot;master&quot;</span><span class=\"p\">)</span> <span class=\"ow\">or</span> <span class=\"n\">group</span> <span class=\"o\">==</span> <span class=\"n\">hash</span><span class=\"p\">(</span><span class=\"s2\">&quot;soundfx&quot;</span><span class=\"p\">)</span> <span class=\"kr\">then</span>\n        <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">set_group_gain</span><span class=\"p\">(</span><span class=\"n\">group</span><span class=\"p\">,</span> <span class=\"mi\">1</span><span class=\"p\">)</span>\n    <span class=\"kr\">else</span>\n        <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">set_group_gain</span><span class=\"p\">(</span><span class=\"n\">group</span><span class=\"p\">,</span> <span class=\"mi\">0</span><span class=\"p\">)</span>\n    <span class=\"kr\">end</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.get_group_name",
+      "brief": "get mixer group name string",
+      "description": "Get a mixer group name as a string.\n<span class=\"icon-attention\"></span> This function is to be used for debugging and\ndevelopment tooling only. The function does a reverse hash lookup, which does not\nreturn a proper string value when the game is built in release mode.",
+      "returnvalues": [
+        {
+          "name": "name",
+          "doc": "group name",
+          "types": ["string"]
+        }
+      ],
+      "parameters": [
+        {
+          "name": "group",
+          "doc": "group name",
+          "types": ["string", "hash"],
+          "is_optional": "False"
+        }
+      ],
+      "examples": "Get the mixer group string names so we can show them as labels on a dev mixer overlay:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kd\">local</span> <span class=\"n\">groups</span> <span class=\"o\">=</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">get_groups</span><span class=\"p\">()</span>\n<span class=\"kr\">for</span> <span class=\"n\">_</span><span class=\"p\">,</span><span class=\"n\">group</span> <span class=\"kr\">in</span> <span class=\"nb\">ipairs</span><span class=\"p\">(</span><span class=\"n\">groups</span><span class=\"p\">)</span> <span class=\"kr\">do</span>\n    <span class=\"kd\">local</span> <span class=\"n\">name</span> <span class=\"o\">=</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">get_group_name</span><span class=\"p\">(</span><span class=\"n\">group</span><span class=\"p\">)</span>\n    <span class=\"n\">msg</span><span class=\"p\">.</span><span class=\"n\">post</span><span class=\"p\">(</span><span class=\"s2\">&quot;/mixer_overlay#gui&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;set_mixer_label&quot;</span><span class=\"p\">,</span> <span class=\"p\">{</span> <span class=\"n\">group</span> <span class=\"o\">=</span> <span class=\"n\">group</span><span class=\"p\">,</span> <span class=\"n\">label</span> <span class=\"o\">=</span> <span class=\"n\">name</span><span class=\"p\">})</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.is_phone_call_active",
+      "brief": "check if a phone call is active",
+      "description": "Checks if a phone call is active. If there is an active phone call all\nother sounds will be muted until the phone call is finished.\n<span class=\"icon-macos\"></span><span class=\"icon-windows\"></span><span class=\"icon-linux\"></span><span class=\"icon-html5\"></span> On non mobile platforms,\nthis function always return <code>false</code>.",
+      "returnvalues": [
+        {
+          "name": "call_active",
+          "doc": "<code>true</code> if there is an active phone call, <code>false</code> otherwise.",
+          "types": ["boolean"]
+        }
+      ],
+      "parameters": [],
+      "examples": "Test if a phone call is on-going:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kr\">if</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">is_phone_call_active</span><span class=\"p\">()</span> <span class=\"kr\">then</span>\n    <span class=\"c1\">-- do something sensible.</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.play",
+      "brief": "plays a sound",
+      "description": "Make the sound component play its sound. Multiple voices are supported. The limit is set to 32 voices per sound component.\n<span class=\"icon-attention\"></span> A sound will continue to play even if the game object the sound component belonged to is deleted. You can call <code>sound.stop()</code> to stop the sound.",
+      "returnvalues": [
+        {
+          "name": "play_id",
+          "doc": "The identifier for the sound voice",
+          "types": ["number"]
+        }
+      ],
+      "parameters": [
+        {
+          "name": "url",
+          "doc": "the sound that should play",
+          "types": ["string", "hash", "url"],
+          "is_optional": "False"
+        },
+        {
+          "name": "play_properties",
+          "doc": "<dl>\n<dt>optional table with properties:</dt>\n<dt><code>delay</code></dt>\n<dd><span class=\"type\">number</span> delay in seconds before the sound starts playing, default is 0.</dd>\n<dt><code>gain</code></dt>\n<dd><span class=\"type\">number</span> sound gain between 0 and 1, default is 1. The final gain of the sound will be a combination of this gain, the group gain and the master gain.</dd>\n<dt><code>pan</code></dt>\n<dd><span class=\"type\">number</span> sound pan between -1 and 1, default is 0. The final pan of the sound will be an addition of this pan and the sound pan.</dd>\n<dt><code>speed</code></dt>\n<dd><span class=\"type\">number</span> sound speed where 1.0 is normal speed, 0.5 is half speed and 2.0 is double speed. Valid range is 0.0 to 50.0. The final speed of the sound will be a multiplication of this speed and the sound speed.</dd>\n<dt><code>start_time</code></dt>\n<dd><span class=\"type\">number</span> start playback offset (seconds). Optional, mutually exclusive with <code>start_frame</code>.</dd>\n<dt><code>start_frame</code></dt>\n<dd><span class=\"type\">number</span> start playback offset (frames/samples). Optional, mutually exclusive with <code>start_time</code>. If both are provided, <code>start_frame</code> is used.</dd>\n</dl>",
+          "types": ["table"],
+          "is_optional": "True"
+        },
+        {
+          "name": "complete_function",
+          "doc": "function to call when the sound has finished playing or stopped manually via <a href=\"/ref/sound#sound.stop\">sound.stop</a>.\n<dl>\n<dt><code>self</code></dt>\n<dd><span class=\"type\">object</span> The current object.</dd>\n<dt><code>message_id</code></dt>\n<dd><span class=\"type\">hash</span> The name of the completion message, which can be either <code>\"sound_done\"</code> if the sound has finished playing, or <code>\"sound_stopped\"</code> if it was stopped manually.</dd>\n<dt><code>message</code></dt>\n<dd><span class=\"type\">table</span> Information about the completion:</dd>\n</dl>\n<ul>\n<li><span class=\"type\">number</span> <code>play_id</code> - the sequential play identifier that was given by the sound.play function.</li>\n</ul>\n<dl>\n<dt><code>sender</code></dt>\n<dd><span class=\"type\">url</span> The invoker of the callback: the sound component.</dd>\n</dl>",
+          "types": ["function(self, message_id, message, sender)"],
+          "is_optional": "True"
+        }
+      ],
+      "examples": "Assuming the script belongs to an instance with a sound-component with id \"sound\", this will make the component play its sound after 1 second:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">play</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"p\">{</span> <span class=\"n\">delay</span> <span class=\"o\">=</span> <span class=\"mi\">1</span><span class=\"p\">,</span> <span class=\"n\">gain</span> <span class=\"o\">=</span> <span class=\"mf\">0.9</span><span class=\"p\">,</span> <span class=\"n\">pan</span> <span class=\"o\">=</span> <span class=\"o\">-</span><span class=\"mf\">1.0</span> <span class=\"p\">}</span> <span class=\"p\">)</span>\n</code></pre></div>\n\nUsing the callback argument, you can chain several sounds together:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"kd\">local</span> <span class=\"kr\">function</span> <span class=\"nf\">sound_done</span><span class=\"p\">(</span><span class=\"n\">self</span><span class=\"p\">,</span> <span class=\"n\">message_id</span><span class=\"p\">,</span> <span class=\"n\">message</span><span class=\"p\">,</span> <span class=\"n\">sender</span><span class=\"p\">)</span>\n  <span class=\"c1\">-- play &#39;boom&#39; sound fx when the countdown has completed</span>\n  <span class=\"kr\">if</span> <span class=\"n\">message_id</span> <span class=\"o\">==</span> <span class=\"n\">hash</span><span class=\"p\">(</span><span class=\"s2\">&quot;sound_done&quot;</span><span class=\"p\">)</span> <span class=\"ow\">and</span> <span class=\"n\">message</span><span class=\"p\">.</span><span class=\"n\">play_id</span> <span class=\"o\">==</span> <span class=\"n\">self</span><span class=\"p\">.</span><span class=\"n\">countdown_id</span> <span class=\"kr\">then</span>\n    <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">play</span><span class=\"p\">(</span><span class=\"s2\">&quot;#boom&quot;</span><span class=\"p\">,</span> <span class=\"kc\">nil</span><span class=\"p\">,</span> <span class=\"n\">sound_done</span><span class=\"p\">)</span>\n  <span class=\"kr\">end</span>\n<span class=\"kr\">end</span>\n\n<span class=\"kr\">function</span> <span class=\"nf\">init</span><span class=\"p\">(</span><span class=\"n\">self</span><span class=\"p\">)</span>\n  <span class=\"n\">self</span><span class=\"p\">.</span><span class=\"n\">countdown_id</span> <span class=\"o\">=</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">play</span><span class=\"p\">(</span><span class=\"s2\">&quot;#countdown&quot;</span><span class=\"p\">,</span> <span class=\"kc\">nil</span><span class=\"p\">,</span> <span class=\"n\">sound_done</span><span class=\"p\">)</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [
+        "Sounds are panned using a constant power panning (non linear fade). 0 means left/right channels are balanced at 71%/71% each.\nAt -1 (full left) the channels are at 100%/0%, and 1 they're at 0%/100%."
+      ],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.stop",
+      "brief": "stop a playing a sound(s)",
+      "description": "Stop playing all active voices or just one voice if <code>play_id</code> provided",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "url",
+          "doc": "the sound component that should stop",
+          "types": ["string", "hash", "url"],
+          "is_optional": "False"
+        },
+        {
+          "name": "stop_properties",
+          "doc": "<dl>\n<dt>optional table with properties:</dt>\n<dt><code>play_id</code></dt>\n<dd><span class=\"type\">number</span> the sequential play identifier that should be stopped (was given by the sound.play() function)</dd>\n</dl>",
+          "types": ["table"],
+          "is_optional": "True"
+        }
+      ],
+      "examples": "Assuming the script belongs to an instance with a sound-component with id \"sound\", this will make the component stop all playing voices:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">stop</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">)</span>\n<span class=\"kd\">local</span> <span class=\"n\">id</span> <span class=\"o\">=</span> <span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">play</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">)</span>\n<span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">stop</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"p\">{</span><span class=\"n\">play_id</span> <span class=\"o\">=</span> <span class=\"n\">id</span><span class=\"p\">})</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.pause",
+      "brief": "pause a playing a sound(s)",
+      "description": "Pause all active voices",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "url",
+          "doc": "the sound that should pause",
+          "types": ["string", "hash", "url"],
+          "is_optional": "False"
+        },
+        {
+          "name": "pause",
+          "doc": "true if the sound should pause",
+          "types": ["boolean"],
+          "is_optional": "False"
+        }
+      ],
+      "examples": "Assuming the script belongs to an instance with a sound-component with id \"sound\", this will make the component pause all playing voices:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">pause</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"kc\">true</span><span class=\"p\">)</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.set_gain",
+      "brief": "set sound gain",
+      "description": "Set gain on all active playing voices of a sound.",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "url",
+          "doc": "the sound to set the gain of",
+          "types": ["string", "hash", "url"],
+          "is_optional": "False"
+        },
+        {
+          "name": "gain",
+          "doc": "sound gain between 0 and 1 [-60dB .. 0dB]. The final gain of the sound will be a combination of this gain, the group gain and the master gain.",
+          "types": ["number"],
+          "is_optional": "True"
+        }
+      ],
+      "examples": "Assuming the script belongs to an instance with a sound-component with id \"sound\", this will set the gain to 0.9\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">set_gain</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"mf\">0.9</span><span class=\"p\">)</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "FUNCTION",
+      "name": "sound.set_pan",
+      "brief": "set sound pan",
+      "description": "Set panning on all active playing voices of a sound.\nThe valid range is from -1.0 to 1.0, representing -45 degrees left, to +45 degrees right.",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "url",
+          "doc": "the sound to set the panning value to",
+          "types": ["string", "hash", "url"],
+          "is_optional": "False"
+        },
+        {
+          "name": "pan",
+          "doc": "sound panning between -1.0 and 1.0",
+          "types": ["number"],
+          "is_optional": "True"
+        }
+      ],
+      "examples": "Assuming the script belongs to an instance with a sound-component with id \"sound\", this will set the gain to 0.5\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">sound</span><span class=\"p\">.</span><span class=\"n\">set_pan</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"mf\">0.5</span><span class=\"p\">)</span> <span class=\"c1\">-- pan to the right</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [
+        "Sounds are panned using a constant power panning (non linear fade). 0 means left/right channels are balanced at 71%/71% each.\nAt -1 (full left) the channels are at 100%/0%, and 1 they're at 0%/100%."
+      ],
+      "language": ""
+    },
+    {
+      "type": "MESSAGE",
+      "name": "play_sound",
+      "brief": "plays a sound",
+      "description": "Post this message to a sound-component to make it play its sound. Multiple voices is supported. The limit is set to 32 voices per sound component.\n<span class=\"icon-attention\"></span> Note that gain is in linear scale, between 0 and 1.\nTo get the dB value from the gain, use the formula <code>20 * log(gain)</code>.\nInversely, to find the linear value from a dB value, use the formula\n<code>10<sup>db/20</sup></code>.\n<span class=\"icon-attention\"></span> A sound will continue to play even if the game object the sound component belonged to is deleted. You can send a <code>stop_sound</code> to stop the sound.\n<span class=\"icon-attention\"></span> <code>play_id</code> should be specified in case you want to receive <code>sound_done</code> or <code>sound_stopped</code> in <code>on_message()</code>.",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "delay",
+          "doc": "delay in seconds before the sound starts playing, default is 0.",
+          "types": ["number"],
+          "is_optional": "True"
+        },
+        {
+          "name": "gain",
+          "doc": "sound gain between 0 and 1, default is 1.",
+          "types": ["number"],
+          "is_optional": "True"
+        },
+        {
+          "name": "play_id",
+          "doc": "the identifier of the sound, can be used to distinguish between consecutive plays from the same component.",
+          "types": ["number"],
+          "is_optional": "True"
+        },
+        {
+          "name": "start_time",
+          "doc": "optional start offset (seconds). Mutually exclusive with <code>start_frame</code>.",
+          "types": ["number"],
+          "is_optional": "True"
+        },
+        {
+          "name": "start_frame",
+          "doc": "optional start offset (frames). If both are provided, <code>start_frame</code> is used.",
+          "types": ["number"],
+          "is_optional": "True"
+        }
+      ],
+      "examples": "Assuming the script belongs to an instance with a sound-component with id \"sound\", this will make the component play its sound after 1 second:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">msg</span><span class=\"p\">.</span><span class=\"n\">post</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;play_sound&quot;</span><span class=\"p\">,</span> <span class=\"p\">{</span><span class=\"n\">delay</span> <span class=\"o\">=</span> <span class=\"mi\">1</span><span class=\"p\">,</span> <span class=\"n\">gain</span> <span class=\"o\">=</span> <span class=\"mf\">0.5</span><span class=\"p\">})</span>\n</code></pre></div>\n\n<div class=\"codehilite\"><pre><span></span><code><span class=\"c1\">-- use `play_id` and `msg.post()` if you want to recieve `sound_done` or `sound_stopped` in on_message()</span>\n<span class=\"kr\">function</span> <span class=\"nf\">init</span><span class=\"p\">()</span>\n <span class=\"n\">msg</span><span class=\"p\">.</span><span class=\"n\">post</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;play_sound&quot;</span><span class=\"p\">,</span> <span class=\"p\">{</span><span class=\"n\">play_id</span> <span class=\"o\">=</span> <span class=\"mi\">1</span><span class=\"p\">,</span> <span class=\"n\">delay</span> <span class=\"o\">=</span> <span class=\"mi\">1</span><span class=\"p\">,</span> <span class=\"n\">gain</span> <span class=\"o\">=</span> <span class=\"mf\">0.5</span><span class=\"p\">})</span>\n<span class=\"kr\">end</span>\n\n<span class=\"kr\">function</span> <span class=\"nf\">on_message</span><span class=\"p\">(</span><span class=\"n\">self</span><span class=\"p\">,</span> <span class=\"n\">message_id</span><span class=\"p\">,</span> <span class=\"n\">message</span><span class=\"p\">)</span>\n <span class=\"kr\">if</span> <span class=\"n\">message_id</span> <span class=\"o\">==</span> <span class=\"n\">hash</span><span class=\"p\">(</span><span class=\"s2\">&quot;sound_done&quot;</span><span class=\"p\">)</span> <span class=\"kr\">then</span>\n     <span class=\"nb\">print</span><span class=\"p\">(</span><span class=\"s2\">&quot;Sound play id: &quot;</span><span class=\"o\">..</span><span class=\"n\">message</span><span class=\"p\">.</span><span class=\"n\">play_id</span><span class=\"p\">)</span>\n <span class=\"kr\">end</span>\n<span class=\"kr\">end</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "MESSAGE",
+      "name": "stop_sound",
+      "brief": "stop a playing a sound(s)",
+      "description": "Post this message to a sound-component to make it stop playing all active voices",
+      "returnvalues": [],
+      "parameters": [],
+      "examples": "Assuming the script belongs to an instance with a sound-component with id \"sound\", this will make the component stop all playing voices:\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">msg</span><span class=\"p\">.</span><span class=\"n\">post</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;stop_sound&quot;</span><span class=\"p\">)</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "MESSAGE",
+      "name": "set_gain",
+      "brief": "set sound gain",
+      "description": "Post this message to a sound-component to set gain on all active playing voices.\n<span class=\"icon-attention\"></span> Note that gain is in linear scale, between 0 and 1.\nTo get the dB value from the gain, use the formula <code>20 * log(gain)</code>.\nInversely, to find the linear value from a dB value, use the formula\n<code>10<sup>db/20</sup></code>.",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "gain",
+          "doc": "sound gain between 0 and 1, default is 1.",
+          "types": ["number"],
+          "is_optional": "True"
+        }
+      ],
+      "examples": "Assuming the script belongs to an instance with a sound-component with id \"sound\", this will set the gain to 0.5\n<div class=\"codehilite\"><pre><span></span><code><span class=\"n\">msg</span><span class=\"p\">.</span><span class=\"n\">post</span><span class=\"p\">(</span><span class=\"s2\">&quot;#sound&quot;</span><span class=\"p\">,</span> <span class=\"s2\">&quot;set_gain&quot;</span><span class=\"p\">,</span> <span class=\"p\">{</span><span class=\"n\">gain</span> <span class=\"o\">=</span> <span class=\"mf\">0.5</span><span class=\"p\">})</span>\n</code></pre></div>",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "MESSAGE",
+      "name": "sound_done",
+      "brief": "reports when a sound has finished playing",
+      "description": "This message is sent back to the sender of a <code>play_sound</code> message\nif the sound could be played to completion and a <code>play_id</code> was provided with the <code>play_sound</code> message.",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "play_id",
+          "doc": "id number supplied when the message was posted.",
+          "types": ["number"],
+          "is_optional": "True"
+        }
+      ],
+      "examples": "",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    },
+    {
+      "type": "MESSAGE",
+      "name": "sound_stopped",
+      "brief": "reports when a sound has been manually stopped",
+      "description": "This message is sent back to the sender of a <code>play_sound</code> message, if the sound\nhas been manually stopped and a <code>play_id</code> was provided with the <code>play_sound</code> message.",
+      "returnvalues": [],
+      "parameters": [
+        {
+          "name": "play_id",
+          "doc": "id number supplied when the message was posted.",
+          "types": ["number"],
+          "is_optional": "True"
+        }
+      ],
+      "examples": "",
+      "replaces": "",
+      "error": "",
+      "tparams": [],
+      "members": [],
+      "notes": [],
+      "language": ""
+    }
+  ],
+  "info": {
+    "namespace": "sound",
+    "name": "Sound",
+    "brief": "Sound API documentation",
+    "description": "Functions and messages for controlling sound components and\nmixer groups.",
+    "path": "engine/gamesys/src/gamesys/scripts/script_sound.cpp",
+    "file": "",
+    "notes": [],
+    "language": "Lua"
+  }
+}