Documentation completed

DOCS.md

@@ -1,6 +1,6 @@
 # Arena_lib docs
 
->> Arena_lib is a library for Minetest working as a core for any arena-like minigame you have in mind. The doc is NOT finished yet
+>> Arena_lib is a library for Minetest working as a core for any arena-like minigame you have in mind
 
 ## Preamble
 
@@ -24,24 +24,63 @@ An arena is a table having as a key an ID and as a value its parameters. They ar
 * `in_loading`: (bool)
 * `in_game`: (bool)
 * `in_celebration`: (bool)
+* `enabled`: (bool) by default an arena is disabled, to avoid any damage
 
-Being arenas stored by ID, they can be easily retrieved by `arena_libs.arenas[THEARENAID]`. And to retrieve the ID, there is a handy function called `arena_libs.get_arenaID_by_player(p_name)`. (Trivia: this function does NOT iterate between areas; instead, there is a local table called `players_in_game` which takes a player name as a key and the arena ID they're in as an index. So it simply return `players_in_game[p_name]`)
+Being arenas stored by ID, they can be easily retrieved by `arena_libs.arenas[THEARENAID]`.  
+
+There are two ways to know an arena ID: the first is in-game via the two debug utilities:
+* `arena_lib.print_arenas(sender)`: coincise
+* `arena_lib.print_arena_info(sender, arena_name)`: extended with much more information
+
+The second is via code by the function `arena_libs.get_arenaID_by_player(p_name)`.  
+(Trivia: this function does NOT iterate between areas; instead, there is a local table called `players_in_game` which takes a player name as a key and the arena ID they're in as an index. So it simply returns `players_in_game[p_name]`)
 
 ### 1.1 Creating and removing arenas
 There are two functions for it and they all need to be connected to some command in your mod. The functions are
 * `arena_lib.create_arena(sender, arena_name)`: it doesn't accept duplicates. Sender is a string 
 * `arena_lib.remove_arena(arena_name)`: if a game is taking place in it, it won't go through
 
-##### 1.1.1 Storing arenas
-Arenas and their settings are stored inside the mod storage. What is *not* stored are players, their stats and such  
+#### 1.1.1 Storing arenas
+Arenas and their settings are stored inside the mod storage. What is *not* stored are players, their stats and such.  
+Better said, these kind of parameters are emptied every time the server starts. And not when it ends, because handling situations like crashes is simply not possible.
   
 ### 1.2 Setting up an arena
-TODO  
-TODO  setting spawners, signs
-TODO  
+Two things are needed to have an arena up to go: spawners and signs. There are two functions for that:  
+* `arena_lib.set_spawner(sender, arena_name, spawner_ID)`
+* `arena_lib.set_sign(sender, arena_name)`
+
+#### 1.2.1 Spawners
+`arena_lib.set_spawner(sender, arena_name, spawner_ID)` creates a spawner where the sender is standing, so be sure to stand where you want the spawn point to be.  
+`spawner_ID` is optional and it does make a difference: with it, it overrides an existing spawner (if exists), without it, it creates a new one. Spawners can't exceed the maximum players of an arena and, more specifically, the must be the same number.  
+I suggest you using [ChatCmdBuilder](https://rubenwardy.com/minetest_modding_book/en/players/chat_complex.html) by rubenwardy and connect the `set_spawner` function to two separate subcommands such as:
+
+```
+ChatCmdBuilder.new("NAMEOFYOURCOMMAND", function(cmd)
+
+    cmd:sub("setspawn :arena", function(name, arena)
+        arena_lib.set_spawner(name, arena)
+      end)
+
+      cmd:sub("setspawn :arena :spawnID:int", function(name, arena, spawn_ID)
+          arena_lib.set_spawner(name, arena, spawn_ID)
+        end)
+
+   [etc.]
+```
+
+#### 1.2.2 Signs
+`arena_lib.set_sign(sender, arena_name)` gives the player an item to hit a sign with. There must be one and one only sign for arena, and when hit it becomes the access to the arena.
+
+#### 1.2.3 Enabling an arena
+When a sign has been set, it won't work. This because an arena must be enabled manually via  
+`arena_lib.enable_arena(sender, arena_ID)`  
+If all the conditions are met, you'll receive a confirmation. If not, you'll receive a reason and the arena will remain disabled. The only reason right now is not having set all the spawners.  
+  
+Arenas can be disabled too, via  
+`arena_lib.disable_arena(sender, arena_ID)`  
+In order to do that, no game must be taking place.  
 
 ### 1.3 Arena phases
-
 An arena comes in 4 phases, each one of them linked to a specific function:
 * `waiting phase`: it's the queuing process. People hit a sign waiting for other players to play with 
 * `loading phase`: it's the pre-match. By default players get teleported in the arena not being able to do anything but jump
@@ -54,11 +93,11 @@ The 4 functions, intertwined with the previously mentioned phases are:
 * `arena_lib.load_celebration(arena_ID, winner_name)`: between the fighting and the celebration phase. Called when the winning conditions are met.
 * `arena_lib.end_arena(arena)`: at the very end of the celebration phase. It teleports people outside the arena
 
-Overriding these functions it's not recommended. Instead, there are 4 respective functions made specifically to customize the behaviour of the formers, sharing the same variables. They are called *after* the function they're associated with and by default they are empty, so feel free to override them. They are:
+Overriding these functions is not recommended. Instead, there are 4 respective functions made specifically to customize the behaviour of the formers, sharing the same variables. They are called *after* the function they're associated with and by default they are empty, so feel free to override them. They are:
 * `arena_lib.on_load(arena_ID)` 
 * `arena_lib.on_start(arena)`
 * `arena_lib.on_celebration(arena_ID, winner_name)`
-* `arena_lib.on_end(arena)`
+* `arena_lib.on_end(arena, players)`
 
 So for example if we want to add an object in the first slot when they join the pre-match, we can simply do:
 
@@ -75,14 +114,25 @@ function arena_lib.on_load(arena_ID)
 end
 ```
 
-## Configuration
+## 2. Configuration
 
-To config the library, go in your `init.lua` and call the `arena_lib.settings` function.
+First of all follow the basic README.md instructions, adding the content of the library inside a folder called `arena_lib` INSIDE your mod (beware of the textures) and adding this line in your `init.lua`.  
+`dofile(minetest.get_modpath("YOURMODNAME") .. "/arena_lib/api.lua")`  
+
+Then, to better config the library, go in your `init.lua` and call the `arena_lib.settings` function.
 The parameters are:
 * `prefix`: what's gonna appear in most of the lines printed by your mod. Default is `[arena_lib] `
+* `hub_spawn_point`: where players will be teleported when a match ends and when they reconnect. Default is `{ x = 0, y = 20, z = 0 }`
 * `load_time`: the time between the loading state and the start of the match. Default is 3
 * `celebration_time`: the time between the celebration state and the end of the match. Default is 3
 * `immunity_time`: the duration of the immunity right after respawning. Default is 3
 * `immunity_slot`: the slot whereto put the immunity item. Default is 9 (the first slot of the inventory minus the hotbar)
 
+### 2.1 Commands
+You need to connect the functions of the library with your mod in order to use them. The best way is with commands and again I suggest you the [ChatCmdBuilder](https://rubenwardy.com/minetest_modding_book/en/players/chat_complex.html) by rubenwardy. [This](https://gitlab.com/zughy-friends-minetest/minetest-quake/-/blob/master/commands.lua) is what I came up with in my Quake minigame, which relies on arena_lib.
 
+## 3. Collaborating
+Something's wrong? Feel free to open an issue, go for a pull request and whatnot. I'd really appreciate it :)
+
+## 4. About the author(s)
+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://it.liberapay.com/EticaDigitale/) directly to my educational Italian project (because not everyone speaks English and Italy media don't talk much about these topics). Also, this project wouldn't have been possible if it hadn't been for some friends who helped me testing through: `SonoMichele`, `_Zaizen_` and `Xx_Crazyminer_xX`

README.md

@@ -20,7 +20,7 @@ arena_lib.settings({
 ```
 in your init.lua.  
 
-For a in-depth understanding of what you can do with the library, have a look at the API document (TODO).
+4) For a in-depth understanding of what you can do with the library, have a look at the [full documentation](https://gitlab.com/zughy-friends-minetest/arena_lib/-/blob/master/DOCS.md).
 
 ### Dependencies
 [signs_lib](https://gitlab.com/VanessaE/signs_lib) by Vanessa Dannenberg