From 128f6359e936bcdc5e26409ddd73438bce9c6dd6 Mon Sep 17 00:00:00 2001
From: rubenwardy <rw@rubenwardy.com>
Date: Sun, 30 Jan 2022 22:40:53 +0000
Subject: Use virtual paths to specify exact mod to enable (#11784)

---
 doc/menu_lua_api.txt | 17 ++++++++++++++---
 doc/world_format.txt | 13 +++++++++++++
 2 files changed, 27 insertions(+), 3 deletions(-)

(limited to 'doc')

diff --git a/doc/menu_lua_api.txt b/doc/menu_lua_api.txt
index a8928441e..c2931af31 100644
--- a/doc/menu_lua_api.txt
+++ b/doc/menu_lua_api.txt
@@ -221,13 +221,24 @@ Package - content which is downloadable from the content db, may or may not be i
     * returns path to global user data,
       the directory that contains user-provided mods, worlds, games, and texture packs.
 * core.get_modpath() (possible in async calls)
-    * returns path to global modpath, where mods can be installed
+    * returns path to global modpath in the user path, where mods can be installed
 * core.get_modpaths() (possible in async calls)
-    * returns list of paths to global modpaths, where mods have been installed
-
+    * returns table of virtual path to global modpaths, where mods have been installed
       The difference with "core.get_modpath" is that no mods should be installed in these
       directories by Minetest -- they might be read-only.
 
+      Ex:
+
+      ```
+      {
+          mods = "/home/user/.minetest/mods",
+          share = "/usr/share/minetest/mods",
+
+          -- Custom dirs can be specified by the MINETEST_MOD_DIR env variable
+          ["/path/to/custom/dir"] = "/path/to/custom/dir",
+      }
+      ```
+
 * core.get_clientmodpath() (possible in async calls)
     * returns path to global client-side modpath
 * core.get_gamepath() (possible in async calls)
diff --git a/doc/world_format.txt b/doc/world_format.txt
index eb1d7f728..98c9d2009 100644
--- a/doc/world_format.txt
+++ b/doc/world_format.txt
@@ -133,6 +133,19 @@ Example content (added indentation and - explanations):
   load_mod_<mod> = false        - whether <mod> is to be loaded in this world
   auth_backend = files          - which DB backend to use for authentication data
 
+For load_mod_<mod>, the possible values are:
+
+* `false` - Do not load the mod.
+* `true` - Load the mod from wherever it is found (may cause conflicts if the same mod appears also in some other place).
+* `mods/modpack/moddir` - Relative path to the mod
+    * Must be one of the following:
+        * `mods/`: mods in the user path's mods folder (ex `/home/user/.minetest/mods`)
+        * `share/`: mods in the share's mods folder (ex: `/usr/share/minetest/mods`)
+        * `/path/to/env`: you can use absolute paths to mods inside folders specified with the `MINETEST_MOD_PATH` env variable.
+    * Other locations and absolute paths are not supported
+    * Note that `moddir` is the directory name, not the mod name specified in mod.conf.
+
+
 Player File Format
 ===================
 
-- 
cgit v1.2.3