put locations and custom graphical resources/translations into the world folder

.gitignore

@@ -1 +1,4 @@
-locations/
+locale/locations
+template/
+textures/locations
+textures/menu

DOCS.md

@@ -1,19 +1,5 @@
 # Magic Compass DOCS
 
-### Create new locations
-Every icon in the menu is a location. Locations must be declared in one or more .yml files inside the `locations` folder like so:
-```yml
-ID:                                     # must be a number, don't write "ID"
-  description: Red Forest               # the name you want to show in the menu when hovering the icon
-  icon: magiccompass_redforest.png      # the associated texture
-  teleport_to: 90.5, 20.0, -30.5        # where the player will be teleported
-  cooldown: 5                           # (optional) cooldown before being able to use it again. None by default
-  requires: fast                        # (optional) privileges required in order to use it. Use ", " to separate them or it won't work
-  hidden_by_default: true               # (optional) whether to hide the icon to players who don't have the required privileges
-```
-
-The ID indicates the position of the associated item in the grid (which scales according to the highest number declared), and empty spaces are generated automatically if the numbers of the items don't represent a full sequence.  
-
 ### Callbacks
 If you want to run additional code from an external mod of yours, there a few callbacks coming in handy:
 * `magic_compass.register_on_use(function(player, ID, item_name, pos))`: use it to run more checks BEFORE being teleported. If it returns nil or false, the action is cancelled. If true, it keeps going

README.md

@@ -1,7 +1,7 @@
 # Magic Compass
 
 Teleport system for Minetest
-  
+
 <a href="https://liberapay.com/Zughy/"><img src="https://i.imgur.com/4B2PxjP.png" alt="Support my work"/></a>  
 
 <img src="https://content.minetest.net/uploads/1j9d672Pie.png"/>  
@@ -10,7 +10,22 @@ Teleport system for Minetest
 Look for the "Magic Compass" item in your creative inventory, put it in your hand and left click it to open the locations menu
 
 ### Customisation
-Check out the [DOCS](/DOCS.md) to create new locations, use callbacks and change the graphic aspect of your compass
+1. be sure the world has been launched at least once with Magic Compass active
+2. go to `your world folder/magic_compass`
+3. open an existing `.yml` file or create a new one (Magic Compass can read multiple locations from multiple files)
+4. follow the template down below, where ID is an actual number
+```yml
+ID:
+  description:
+  icon:
+  teleport_to: X, Y, Z
+  cooldown: (optional, default none)
+  requires: (optional privileges required to use the teleport: separate them with `, `, default none)
+  hidden_by_default: (optional, put `true` to hide the icon to players who don't have the required privileges)
+```
+For more information, check out the `instructions.txt` file inside that folder.
+
+For using the API, check out the [DOCS](/DOCS.md).
 
 ### Want to help?
 Feel free to:

src/deserializer.lua

@@ -8,9 +8,31 @@ local S = minetest.get_translator("magic_compass")
 
 local function load_locations()
 
-  local dir = minetest.get_modpath("magic_compass") .. "/locations"
+  local dir = minetest.get_worldpath() .. "/magic_compass"
   local content = minetest.get_dir_list(dir)
 
+  local modpath = minetest.get_modpath("magic_compass")
+  local i18n_dir = modpath .. "/locale/locations"
+  local txtr_dir = modpath .. "/textures/locations"
+  local menu_ui_dir = modpath .. "/textures/menu"
+
+
+  -- se la cartella delle skin non esiste/è vuota, copio la cartella base `template`
+  if not next(content) then
+    local src_dir = minetest.get_modpath("magic_compass") .. "/template"
+    minetest.cpdir(src_dir, dir)
+    minetest.cpdir(src_dir .. "/locale", i18n_dir)
+    minetest.cpdir(src_dir .. "/icons", txtr_dir)
+    minetest.cpdir(src_dir .. "/menu", menu_ui_dir)
+    os.remove(dir .. "/README.md")
+    content = minetest.get_dir_list(dir)
+  else
+    minetest.cpdir(dir .. "/locale", i18n_dir)
+    minetest.cpdir(dir .. "/icons", txtr_dir)
+    minetest.cpdir(dir .. "/menu", menu_ui_dir)
+  end
+
+
   for _, f_name in pairs(content) do
     if f_name:sub(-4) == ".yml" or f_name:sub(-5) == ".yaml" then
       local file = io.open(dir .. "/" .. f_name, "r")

template/README.md

@@ -0,0 +1,4 @@
+
+**EDITING THIS FOLDER IS USELESS, EDIT THE ONE CALLED magic_compass IN THE WORLD FOLDER INSTEAD**
+
+The first time the world is launched with `magic_compass` on, this folder is copy-pasted into the world folder (and this file deleted). The purpose of this folder is to provide all the menu assets and a few examples by default. This help modders understand how to implement their locations more easily.

template/instructions.txt

@@ -0,0 +1,19 @@
+This folder shall contain all the information regarding the locations linked to this world. DO NOT rename folders or the mod won't be able to read them.
+
+locations are stored in .yml files, and every file can contain multiple locations. Locations must follow the template down below, where 'ID' is an actual number
+
+ID:
+  description:
+  icon:
+  teleport_to: X, Y, Z
+  cooldown: (optional, default none)
+  requires: (optional privileges required to use the teleport: separate them with ", ", default none)
+  hidden_by_default: (optional, put 'true' to hide the icon to players who don't have the required privileges)
+
+The ID indicates the position of the associated item in the grid (which scales according to the highest number declared), and empty spaces are generated automatically if the numbers of the items don't represent a full sequence.
+
+/icons is for... icons.
+
+/locale is for translation files, in case you want to geolocalise the name of your icons. It's highly recommended to rename the example files, so put whatever name you want, followed by the country code the file represents and .tr. For instance, a translation file for Spanish would be "mycoolgame.es.tr".
+
+/menu is for customising the locations formspec. DO NOT rename files or they won't work, just override them with your custom image.

template/locale/example.it.tr

@@ -0,0 +1,6 @@
+# author(s): Zughy
+# reviewer(s):
+# textdomain: magic_compass
+
+# example skins
+Check the magic_compass folder inside the world folder to edit us!=Controlla la cartella magic_compass dentro a quella del mondo per modificarci!

template/locale/template_example.txt

@@ -0,0 +1,6 @@
+# author(s):
+# reviewer(s):
+# textdomain: magic_compass
+
+# example
+Check the magic_compass folder inside the world folder to edit us!

template/locations.yml

@@ -1,5 +1,5 @@
 1:
-  description: Check the Locations folder inside the mod to edit us!
+  description: Check the magic_compass folder inside the world folder to edit us!
   icon: magiccompass_example.png
   teleport_to: 10.5, 30.0, 20.5