lua: set package path if loaded from a script directory

And document the shit.

This uses code from commit bc1c024ae0.

DOCS/man/lua.rst

@@ -1,12 +1,7 @@
 LUA SCRIPTING
 =============
 
-mpv can load Lua scripts. Scripts passed to the ``--script`` option, or found in
-the ``scripts`` subdirectory of the mpv configuration directory (usually
-``~/.config/mpv/scripts/``) will be loaded on program start. mpv also appends the
-``scripts`` subdirectory to the end of Lua's path so you can import scripts from
-there too. Since it's added to the end, don't name scripts you want to import
-the same as Lua libraries because they will be overshadowed by them.
+mpv can load Lua scripts. (See `Script location`_.)
 
 mpv provides the built-in module ``mp``, which contains functions to send
 commands to the mpv core and to retrieve information about playback state, user
@@ -30,6 +25,43 @@ A script which leaves fullscreen mode when the player is paused:
     mp.observe_property("pause", "bool", on_pause_change)
 
 
+Script location
+---------------
+
+Scripts can be passed to the ``--script`` option, and are automatically loaded
+from the ``scripts`` subdirectory of the mpv configuration directory (usually
+``~/.config/mpv/scripts/``).
+
+A script can be a single file. The file extension is used to select the
+scripting backend to use for it. For Lua, it is ``.lua``. If the extension is
+not recognized, an error is printed. (If an error happens, the extension is
+either mistyped, or the backend was not compiled into your mpv binary.)
+
+Entries with ``.disable`` extension are always ignored.
+
+If a script is a directory (either if a directory is passed to ``--script``,
+or any sub-directories in the script directory, such as for example
+``~/.config/mpv/scripts/something/``), then the directory represents a single
+script. The player will try to load a file named ``main.x``, where ``x`` is
+replaced with the file extension. For example, if ``main.lua`` exists, it is
+loaded with the Lua scripting backend.
+
+You must not put any other files or directories that start with ``main.`` into
+the script's top level directory. If the script directory contains for example
+both ``main.lua`` and ``main.js``, only one of them will be loaded (and which
+one depends on mpv internals that may change any time). Likewise, if there is
+for example ``main.foo``, your script will break as soon as mpv adds a backend
+that uses the ``.foo`` file extension.
+
+mpv also appends the top level directory of the script to the start of Lua's
+package path so you can import scripts from there too. Be aware that this will
+shadow Lua libraries that use the same package path.
+
+On the other hand, if the script is a single file (directly located in
+``~/.config/mpv/scripts/`` and not as sub-directory), the Lua package path
+does not include any mpv specific directories. (This was silently changed in
+mpv 0.32.0.)
+
 Details on the script initialization and lifecycle
 --------------------------------------------------
 

DOCS/man/mpv.rst

@@ -1242,10 +1242,11 @@ For Windows-specifics, see `FILES ON WINDOWS`_ section.
 
 ``~/.config/mpv/scripts/``
     All files in this directory are loaded as if they were passed to the
-    ``--script`` option. They are loaded in alphabetical order. Directory entries
-    other than files are ignored. Files with unknown extension lead to an
-    initialization error. Files with ``.disable`` extension are ignored. The
-    ``--load-scripts=no`` option disables loading these files.
+    ``--script`` option. They are loaded in alphabetical order.
+
+    The ``--load-scripts=no`` option disables loading these files.
+
+    See `Script location`_ for details.
 
 ``~/.config/mpv/watch_later/``
     Contains temporary config files needed for resuming playback of files with

player/lua.c

@@ -83,6 +83,7 @@ static const char * const builtin_lua_scripts[][2] = {
 struct script_ctx {
     const char *name;
     const char *filename;
+    const char *path; // NULL if single file
     lua_State *state;
     struct mp_log *log;
     struct mpv_handle *client;
@@ -273,6 +274,30 @@ static int load_scripts(lua_State *L)
     return 0;
 }
 
+static void set_path(lua_State *L)
+{
+    struct script_ctx *ctx = get_ctx(L);
+
+    if (!ctx->path)
+        return;
+
+    void *tmp = talloc_new(NULL);
+
+    lua_getglobal(L, "package"); // package
+    lua_getfield(L, -1, "path"); // package path
+    const char *path = lua_tostring(L, -1);
+
+    char *newpath = talloc_asprintf(tmp, "%s;%s",
+                                    mp_path_join(tmp, ctx->path, "?.lua"),
+                                    path ? path : "");
+
+    lua_pushstring(L, newpath);  // package path newpath
+    lua_setfield(L, -3, "path"); // package path
+    lua_pop(L, 2);  // -
+
+    talloc_free(tmp);
+}
+
 static int run_lua(lua_State *L)
 {
     struct script_ctx *ctx = lua_touserdata(L, -1);
@@ -326,6 +351,9 @@ static int run_lua(lua_State *L)
 
     assert(lua_gettop(L) == 0);
 
+    set_path(L);
+    assert(lua_gettop(L) == 0);
+
     // run this under an error handler that can do backtraces
     lua_pushcfunction(L, error_handler); // errf
     lua_pushcfunction(L, load_scripts); // errf fn
@@ -348,6 +376,7 @@ static int load_lua(struct mp_script_args *args)
         .name = mpv_client_name(args->client),
         .log = args->log,
         .filename = args->filename,
+        .path = args->path,
     };
 
     if (LUA_VERSION_NUM != 501 && LUA_VERSION_NUM != 502) {