From c31c852a6ea63eb2ffed49089881866fb59df0ed Mon Sep 17 00:00:00 2001
From: AFCMS <afcm.contact@gmail.com>
Date: Tue, 20 Jul 2021 16:14:34 +0200
Subject: [PATCH] add documentation

---
 mods/ENTITIES/mcl_boats/init.lua     |  2 +-
 mods/ENTITIES/mcl_minecarts/init.lua |  2 +-
 mods/HUD/mcl_title/API.md            | 42 ++++++++++++++++++++++++++++
 mods/HUD/mcl_title/init.lua          |  2 +-
 mods/ITEMS/mcl_beds/functions.lua    |  2 +-
 5 files changed, 46 insertions(+), 4 deletions(-)
 create mode 100644 mods/HUD/mcl_title/API.md

diff --git a/mods/ENTITIES/mcl_boats/init.lua b/mods/ENTITIES/mcl_boats/init.lua
index e81e9ffc5d..311b07882f 100644
--- a/mods/ENTITIES/mcl_boats/init.lua
+++ b/mods/ENTITIES/mcl_boats/init.lua
@@ -84,7 +84,7 @@ local function attach_object(self, obj)
 			end
 		end, name)
 		obj:set_look_horizontal(yaw)
-		mcl_title.set(obj, "actionbar", {text=S("Sneak to dismount"), color="white", stay=3})
+		mcl_title.set(obj, "actionbar", {text=S("Sneak to dismount"), color="white", stay=60})
 	else
 		obj:get_luaentity()._old_visual_size = visual_size
 	end
diff --git a/mods/ENTITIES/mcl_minecarts/init.lua b/mods/ENTITIES/mcl_minecarts/init.lua
index a76ab538af..4d3873cc23 100644
--- a/mods/ENTITIES/mcl_minecarts/init.lua
+++ b/mods/ENTITIES/mcl_minecarts/init.lua
@@ -646,7 +646,7 @@ register_minecart(
 				if player then
 					mcl_player.player_set_animation(player, "sit" , 30)
 					player:set_eye_offset({x=0, y=-5.5, z=0},{x=0, y=-4, z=0})
-					mcl_title.set(clicker, "actionbar", {text=S("Sneak to dismount"), color="white", stay=3})
+					mcl_title.set(clicker, "actionbar", {text=S("Sneak to dismount"), color="white", stay=60})
 				end
 			end, name)
 		end
diff --git a/mods/HUD/mcl_title/API.md b/mods/HUD/mcl_title/API.md
new file mode 100644
index 0000000000..50614be4f1
--- /dev/null
+++ b/mods/HUD/mcl_title/API.md
@@ -0,0 +1,42 @@
+# mcl_title
+
+Allow mods to show messages in the hud of players.
+
+## mcl_title.set(player, type, data)
+
+Show a hud message of `type` to player `player` with `data` as params.
+
+The element will stay for the per-player param `stay` or `data.stay` (in gametick which is 1/20 second).
+
+Here is a usage exemple:
+
+```lua
+--show a title in the HUD with minecraft color "gold" 
+mcl_title.set(player, "title", {text="dummy text", color="gold"})
+
+--show a subtitle in the HUD with hex color "#612D2D" 
+mcl_title.set(player, "subtitle", {text="dummy subtitle", color="#612D2D"})
+
+--show an actionbar in the HUD (above the hotbar) with minecraft color "red"
+mcl_title.set(player, "subtitle", {text="dummy actionbar", color="red"})
+
+--show a title in the HUD with minecraft color "gold" staying for 3 seconds (override stay setting)
+mcl_title.set(player, "title", {text="dummy text", color="gold", stay=3})
+```
+
+## mcl_title.remove(player, type)
+
+Hide HUD element of type `type` for player `player`.
+
+## mcl_title.clear(player)
+
+Remove every title/subtitle/actionbar from a player.
+Basicaly run `mcl_title.remove(player, type)` for every type.
+
+## mcl_title.params_set(player, params)
+
+Allow mods to set `stay` and upcomming `fadeIn`/`fadeOut` params.
+
+```lua
+mcl_title.params_set(player, {stay = 600}) --elements with no 'data.stay' field will stay during 30s (600/20)
+```
\ No newline at end of file
diff --git a/mods/HUD/mcl_title/init.lua b/mods/HUD/mcl_title/init.lua
index 03fe176147..d1dbece4b4 100644
--- a/mods/HUD/mcl_title/init.lua
+++ b/mods/HUD/mcl_title/init.lua
@@ -134,7 +134,7 @@ function mcl_title.set(player, type, data)
 
 	player:hud_change(huds_idx[type][player], "text", data.text)
 	player:hud_change(huds_idx[type][player], "number", hex_color)
-	hud_hide_timeouts[type][player:get_player_name()] = data.stay or mcl_title.params_get(player).stay
+	hud_hide_timeouts[type][player:get_player_name()] = gametick_to_secondes(data.stay) or mcl_title.params_get(player).stay
 	return true
 end
 
diff --git a/mods/ITEMS/mcl_beds/functions.lua b/mods/ITEMS/mcl_beds/functions.lua
index f323ca4c72..e196f69ade 100644
--- a/mods/ITEMS/mcl_beds/functions.lua
+++ b/mods/ITEMS/mcl_beds/functions.lua
@@ -330,7 +330,7 @@ function mcl_beds.on_rightclick(pos, player, is_top)
 			message = select(2, lay_down(player, ppos, other))
 		end
 		if message then
-			mcl_title.set(player, "actionbar", {text=message, color="white", stay=3})
+			mcl_title.set(player, "actionbar", {text=message, color="white", stay=60})
 		end
 	else
 		lay_down(player, nil, nil, false)