From 105676b952484affdb97164eceaf4cb903955373 Mon Sep 17 00:00:00 2001
From: paramat <mat.gregory@virginmedia.com>
Date: Thu, 1 Dec 2016 04:49:17 +0000
Subject: [PATCH] Lua_api.txt: Clarify use of looping sounds

---
 doc/lua_api.txt | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index eb47270f4..092704c04 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -441,18 +441,24 @@ from the available ones of the following files:
 
 Examples of sound parameter tables:
 
-    -- Play location-less on all clients
+    -- Play locationless on all clients
     {
         gain = 1.0, -- default
     }
-    -- Play location-less to a player
+    -- Play locationless to one player
     {
         to_player = name,
         gain = 1.0, -- default
     }
+    -- Play locationless to one player, looped
+    {
+        to_player = name,
+        gain = 1.0, -- default
+        loop = true,
+    }
     -- Play in a location
     {
-        pos = {x=1,y=2,z=3},
+        pos = {x = 1, y = 2, z = 3},
         gain = 1.0, -- default
         max_hear_distance = 32, -- default, uses an euclidean metric
     }
@@ -461,15 +467,18 @@ Examples of sound parameter tables:
         object = <an ObjectRef>,
         gain = 1.0, -- default
         max_hear_distance = 32, -- default, uses an euclidean metric
-        loop = true, -- only sounds connected to objects can be looped
+        loop = true,
     }
 
+Looped sounds must either be connected to an object or played locationless to
+one player using `to_player = name,`
+
 ### `SimpleSoundSpec`
 * e.g. `""`
 * e.g. `"default_place_node"`
 * e.g. `{}`
-* e.g. `{name="default_place_node"}`
-* e.g. `{name="default_place_node", gain=1.0}`
+* e.g. `{name = "default_place_node"}`
+* e.g. `{name = "default_place_node", gain = 1.0}`
 
 Registered definitions of stuff
 -------------------------------