Explain level packs

LEVEL_EDITOR.md

@@ -224,6 +224,9 @@ If you think you made a nice level, send it to Wuzzy per e-mail at
 Wuzzy@disroot.org. This game desperately needs more levels, so submissions
 are appreciated. :D
 
+If you have multiple levels, you may construct a level pack. See
+`LEVEL_PACKS.md` for details.
+
 
 ### Technical steps
 

LEVEL_PACKS.md

@@ -0,0 +1,72 @@
+# Level packs
+
+A level pack is a collection of levels that belong together.
+
+This is the best way to store and share custom levels, but it requires
+Lua programming skills to add a new level pack.
+
+To add a new level pack, a new Luanti mod must be created containing these things:
+
+1) Level schematic (`*.mts`) files. These are for the blocks
+2) Level metadata in a level data CSV file. This contains all information that
+   the schematic file cannot hold, e.g. title, boundary blocks, weather, sky, etc.
+   The level data CSV specifies the metadata for ALL levels at once.
+   This file also defines the level order. Levels at the top will be played first.
+3) Lua code to register the level pack (see below)
+
+The Lua mod must depend on `lzr_levels`.
+
+## File structure
+
+Normally, the file structure of the mod is as follows:
+
+* `mod.conf`: Must declare dependency on `lzr_levels`
+* `init.lua`: Lua code to register level pack (see below)
+* `data/level_data.csv`: CSV file for level metadata for ALL levels
+* `schematics/`: The level `*.mts` files go here
+* `solutions/`: (optional) Level solution files `*.sol.csv` go here.
+* `locale/`: (optional) To store the locale files, if present
+
+Some of these file locations may be changed by parameters of the
+function `lzr_levels.register_level_pack`.
+
+## Register the level pack
+
+To register a level pack, you must call `lzr_levels.register_level_pack`.
+The full definition of this function can be found in the code comment above that
+function in the `lzr_levels` mod.
+
+If successful, the level pack will appear in the game under the custom levels menu.
+
+### Example
+
+A simple example with one level, translated into German.
+
+First, the file structure:
+
+* `mod.conf`
+* `init.lua`
+* `schematics`
+    * `example.mts`
+* `data`
+    * `level_data.csv`
+* `locale`
+    * `example_levels.pot`
+    * `example_levels.po.de`
+    * `example_levels_level_names.pot`
+    * `example_levels_level_names.de.po`
+    * `example_levels_npc_texts.pot`
+    * `example_levels_npc_texts.de.po`
+```
+
+local S = minetest.get_translator("example_levels")
+
+lzr_levels.register_level_pack("example",
+	{
+		title = S("My Example Levels"),
+		description = S("Some example levels to test things."),
+		textdomain_npc_texts = "example_levels_npc_texts",
+		textdomain_level_names = "example_levels_level_names",
+	}
+)
+```

mods/lzr_levels/init.lua

@@ -1379,7 +1379,32 @@ function lzr_levels.get_current_level_data()
 	return current_level_data
 end
 
-function lzr_levels.register_level_pack(name, level_data_file, schematic_path, solutions_path, info)
+--[[
+	Register a level pack. A level pack is a collection of levels that belong together.
+	For this to work, the level-related data must be present in the locations defined at
+	level_data_file, schematic_path and (optionally) solutions_path described below.
+
+	If successful, the level pack will appear in the game under the custom levels menu.
+	
+	Parameters:
+	* name: level pack ID (string, allowed characters are a-z, A-Z, 0-9 and _ (underscore))
+	* info: Table of optional additional information, with these fields:
+		* title: human-readable level pack title
+		* description: short description/explanation about this level pack. 1-3 sentences.
+		* textdomain_level_names: textdomain of the translation file containing the translated level names (default: no translation)
+		* textdomain_npc_texts: textdomain of the translation file containing the translated texts for NPCs like Goldie the Parrot (default: no translation)
+		* level_data_file: Path to CSV file containing metadata of all levels (default: <modpath>/data/level_data.csv)
+		* schematic_path: Path to directory containing the level '.mts' schematic files (default: <modpath>/schematics)
+		* solutions_path: Path to directory containing the OPTIONAL level '.sol.csv' solution files (default: <modpath>/solutions)
+]]
+function lzr_levels.register_level_pack(name, info)
+
+	local mod = minetest.get_current_modname()
+
+	local level_data_file = info.level_data_path or minetest.get_modpath(mod).."/data/level_data.csv"
+	local schematic_path = info.schematic_path or minetest.get_modpath(mod).."/schematics"
+	local solutions_path = info.solutions_path or minetest.get_modpath(mod).."/solutions"
+
 	local error_type, error_msg, error_detail
 	local level_data
 	level_data, error_type, error_msg, error_detail = lzr_levels.analyze_levels(

mods/lzr_levels_core/init.lua

@@ -33,9 +33,6 @@ if minetest.settings:get_bool("lzr_debug", false) then
 end
 
 lzr_levels.register_level_pack("__core",
-	minetest.get_modpath("lzr_levels_core").."/data/level_data.csv",
-	minetest.get_modpath("lzr_levels_core").."/schematics",
-	minetest.get_modpath("lzr_levels_core").."/solutions",
 	{
 		title = S("Lazarr!"),
 		description = S("The main adventure that comes pre-installed with the game."),