Add naming policy for scripts and l10n files to documentation

docs/source/reference/lua-scripting/api.rst

@@ -59,7 +59,8 @@ Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can overrid
 
 .. include:: tables/aux_packages.rst
 
-**Interfaces of built-in scripts**
+Interfaces of built-in scripts
+------------------------------
 
 .. list-table::
   :widths: 20 20 60

docs/source/reference/lua-scripting/overview.rst

@@ -85,7 +85,7 @@ Let's write a simple example of a `Player script`:
 
 .. code-block:: Lua
 
-    -- Save to my_lua_mod/example/player.lua
+    -- Save to my_lua_mod/scripts/example/player.lua
 
     local ui = require('openmw.ui')
 
@@ -107,7 +107,7 @@ The options are:
 1. Create text file "my_lua_mod.omwscripts" with the following line:
 ::
 
-    PLAYER: example/player.lua
+    PLAYER: scripts/example/player.lua
 
 2. (not implemented yet) Add the script in OpenMW CS on "Lua scripts" view and save as "my_lua_mod.omwaddon".
 
@@ -122,6 +122,19 @@ Enable it in ``openmw.cfg`` the same way as any other mod:
 Now every time the player presses "X" on a keyboard, a message is shown.
 
 
+Lua scripts naming policy
+=========================
+
+Technically scripts can be placed anywhere in the virtual file system, but we recommend to follow the naming policy and choose one of:
+
+- ``scripts/<ModName>/<ScriptName>.lua``: general case.
+- ``scripts/<AuthorName>/<ModName>/<ScriptName>.lua``: if "ModName" is short and can potentially collide with other mods.
+- ``scripts/<ModName>.lua``: if it is a simple mod that consists from a single script, the script can placed to ``scripts/`` without subdirs.
+
+``scripts/omw/`` is reserved for built-in scripts, don't use it in mods. Overriding built-in scripts is not recommended, prefer to adjust their behaviour via :ref:`Interfaces of built-in scripts` instead.
+
+See also naming policy of :ref:`Localisation Files`.
+
 Format of ``.omwscripts``
 =========================
 
@@ -129,20 +142,20 @@ Format of ``.omwscripts``
 
     # Lines starting with '#' are comments
 
-    GLOBAL: my_mod/some_global_script.lua
+    GLOBAL: scripts/my_mod/some_global_script.lua
 
     # Script that will be automatically attached to the player
-    PLAYER: my_mod/player.lua
+    PLAYER: scripts/my_mod/player.lua
 
     # Local script that will be automatically attached to every NPC and every creature in the game
-    NPC, CREATURE: my_mod/some_other_script.lua
+    NPC, CREATURE: scripts/my_mod/some_other_script.lua
 
     # Local script that can be attached to any object by a global script
-    CUSTOM: my_mod/something.lua
+    CUSTOM: scripts/my_mod/something.lua
 
     # Local script that will be automatically attached to any Container AND can be
     # attached to any other object by a global script.
-    CONTAINER, CUSTOM: my_mod/container.lua
+    CONTAINER, CUSTOM: scripts/my_mod/container.lua
 
 Each script is described by one line:
 ``<flags>: <path to .lua file in virtual file system>``.