DOCS: remove internal function

DOCS.md

@@ -0,0 +1,42 @@
+# Achievements Lib
+
+## 1. Achievements: structure
+`achievements` is a big table taking mod names as a key and a table as a value. This table can contain whatever entry you like (`name`, `img`, `idontknow`), because the only thing that matters to it is to check whether something exists at the given index. In fact, the following examples are all correct:
+```
+local achievements = {
+  [1] = "inhale",
+  [2] = "exhale"
+}
+
+local achievements = {
+  [1] = { name = "inhale",	img = "mod_inhale.png" },
+  [2] = { name = "exhale",	img = "mod_exhale.png" }
+}
+
+-- pretty useless but hey ¯\_(ツ)_/¯
+local achievements = {
+  [1] = true,
+  [2] = true
+}
+```
+
+The table is _not_ saved into the storage, only players progress is.
+
+## 2. Registering and unlocking achievements
+In order to register the achievements of a mod, do:  
+`achvmt_lib.register_achievements(mod, mod_achievements)`  
+where `mod` is the mod name and `mod_achievements` a table containing whatever value you want.
+
+On the contrary, to unlock an achievement:
+`achvmt_lib.unlock_achievement(p_name, mod, achvmt_ID)`
+
+### 2.1 Utils
+`achvmt_lib.has_player_achievement(p_name, mod, achvmt_ID)`: check whether a player has unlocked an achievement
+`achvmt_lib.is_player_in_storage(p_name, mod)`: check whether a player has connected after a new mod supporting achievements_lib has been added
+
+### 2.2 Getters
+`achvmt_lib.get_achievement(mod, achvmt_ID)`: returns the value assigned to the achievement at the corresponding `achvmt_ID`, if any
+`achvmt_lib.get_player_achievements(p_name, mod)`: returns a table containing all the achievements unlocked by `p_name`, where entries are in the format `ID = true`
+
+## 3 About the author
+I'm Zughy (Marco), a professional Italian pixel artist who fights for FOSS and digital ethics. If this library spared you a lot of time and you want to support me somehow, please consider donating on [LiberaPay](https://liberapay.com/Zughy/).

README.md

@@ -2,8 +2,15 @@
 
 Achievements API for Minetest
 
-S4 League inspired shooter minigame for Minetest.
+<a href="https://liberapay.com/Zughy/"><img src="https://i.imgur.com/4B2PxjP.png" alt="Support my work"/></a>  
 
-Zughy <a href="https://liberapay.com/Zughy/"><img src="https://i.imgur.com/4B2PxjP.png" alt="Support Zughy"/></a>
+### DOCS
+For an in-depth understanding of what you can do with the library, have a look at the [full documentation](https://gitlab.com/zughy-friends-minetest/achievements_lib/-/blob/master/DOCS.md).  
 
-(I'll write a documentation as soon as I have time)
+### Dependencies
+---
+
+### Want to help?
+Feel free to:
+* open an [issue](https://gitlab.com/zughy-friends-minetest/achievements_lib/-/issues)
+* submit a merge request. In this case, PLEASE, do follow milestones and my [coding guidelines](https://cryptpad.fr/pad/#/2/pad/view/-l75iHl3x54py20u2Y5OSAX4iruQBdeQXcO7PGTtGew/embed/). I won't merge features for milestones that are different from the upcoming one (if it's declared), nor messy code

api.lua

@@ -1,4 +1,4 @@
-achievements_lib = {}
+achvmt_lib = {}
 
 
 
@@ -11,7 +11,6 @@ local function update_storage() end
 local storage = minetest.get_mod_storage()
 local achievements = {}       -- KEY: mod; VALUE: {KEY: achievement ID; VALUE: {whatever properties}
 local p_achievements = {}     -- KEY: p_name; VALUE: {KEY: mod, VALUE: {KEY: achievement ID VALUE: true/nil}}}
-local access_keys = {}        -- KEY: random ID; VALUE: mod name
 
 
 -- inizializzo storage caricando tutti i giocatori
@@ -26,14 +25,14 @@ end
 -------------------CORPO----------------------
 ----------------------------------------------
 
-function achievements_lib.register_achievements(mod, mod_achievements)
+function achvmt_lib.register_achievements(mod, mod_achievements)
   assert(achievements[mod] == nil, "[ACHIEVEMENTS_LIB] There was an attempt to register the mod " .. mod .. " more than once! Be sure you didn't call this function twice and you didn't install any suspicious mod")
   achievements[mod] = mod_achievements
 end
 
 
 
-function achievements_lib.add_achievement(p_name, mod, achvmt_ID)
+function achvmt_lib.unlock_achievement(p_name, mod, achvmt_ID)
 
   local achievement = achievements[mod][achvmt_ID]
 
@@ -53,13 +52,13 @@ end
 --------------------UTILS---------------------
 ----------------------------------------------
 
-function achievements_lib.has_player_achievement(p_name, mod, achvmt_ID)
+function achvmt_lib.has_player_achievement(p_name, mod, achvmt_ID)
   return p_achievements[p_name][mod][achvmt_ID] ~= nil
 end
 
 
 
-function achievements_lib.is_player_in_storage(p_name, mod)
+function achvmt_lib.is_player_in_storage(p_name, mod)
   if p_achievements[p_name] then
     if mod and p_achievements[p_name][mod] then
       return true
@@ -73,23 +72,27 @@ end
 
 
 
-function achievements_lib.add_player_to_storage(p_name, mod)
+-- INTERNAL USE ONLY
+function achvmt_lib.add_player_to_storage(p_name)
 
   if not minetest.get_player_by_name(p_name) then
     minetest.log("Warning", "[ACHIEVEMENTS_LIB] Player " .. p_name .. " must be online in order to be added to the storage!")
     return end
 
-  if p_achievements[p_name] then
-    if mod and p_achievements[p_name][mod] then
-      minetest.log("Warning", "[ACHIEVEMENTS_LIB] Can't add player to storage, an entry within this mod already exists!")
-    elseif mod then
-      p_achievements[p_name][mod] = {}
-      storage:set_string(p_name, minetest.serialize(p_achievements[p_name]))
-    else
-      minetest.log("Warning", "[ACHIEVEMENTS_LIB] Can't add player to storage, an entry already exists!")
-    end
-  else
+  if not p_achievements[p_name] then
     p_achievements[p_name] = {}
+  end
+
+  local update_storage = false
+
+  for mod, _ in pairs(achievements) do
+    if not achvmt_lib.is_player_in_storage(p_name, mod) then
+      p_achievements[p_name][mod] = {}
+      update_storage = true
+    end
+  end
+
+  if update_storage then
     storage:set_string(p_name, minetest.serialize(p_achievements[p_name]))
   end
 end
@@ -102,13 +105,13 @@ end
 -----------------GETTERS----------------------
 ----------------------------------------------
 
-function achievements_lib.get_achievement(mod, achvmt_ID)
+function achvmt_lib.get_achievement(mod, achvmt_ID)
   return achievements[mod][achvmt_ID]
 end
 
 
 
-function achievements_lib.get_player_achievements(p_name, mod)
+function achvmt_lib.get_player_achievements(p_name, mod)
   return p_achievements[p_name][mod]
 end
 
@@ -123,3 +126,16 @@ end
 function update_storage(p_name)
   storage:set_string(p_name, minetest.serialize(p_achievements[p_name]))
 end
+
+
+
+
+
+----------------------------------------------
+------------------DEPRECATED------------------
+----------------------------------------------
+
+function achvmt_lib.add_achievement(p_name, mod, achvmt_ID)
+	minetest.log("warning", "[ACHIEVEMENTS_LIB] (" .. mod .. ") achvmt_lib.add_achievement is deprecated: use unlock_achievement instead")
+	achvmt_lib.unlock_achievement(p_name, mod, achvmt_ID)
+end

player_manager.lua

@@ -1,3 +1,3 @@
-minetest.register_on_newplayer(function(ObjectRef)
-  achievements_lib.add_player_to_storage(ObjectRef:get_player_name())
+minetest.register_on_joinplayer(function(player)
+  achvmt_lib.add_player_to_storage(player:get_player_name())
 end)