README: Document chat commands

This properly fixes #1.

README.md

@@ -25,6 +25,9 @@ To toggle its display, use the `//hud` command - it takes no arguments.
      - Ignore `wielded_light:*` nodes when raycasting
  - v0.4: 31st May 2021
      - Fix deprecation warning for `getpos` → `get_pos` (#2)
+ - v0.5: 31st July 2021
+     - Add `//hudoffset [<offset_in_pixels>]` chat command to adjust the vertical offset of the HUD (fixes #1)
+     - Persist per-player settings to disk (per-world)
 
 
 ## More Screenshots
@@ -32,8 +35,27 @@ To toggle its display, use the `//hud` command - it takes no arguments.
 ![](https://gitlab.com/sbrl/worldedit_hud_helper/raw/master/screenshots/screenshot_c.png)
 ![](https://gitlab.com/sbrl/worldedit_hud_helper/raw/master/screenshots/screenshot_d.png)
 
-## Todo
- - Add a setting based on [this code](https://github.com/Pilcrow182/flying_saucer/blob/master/init.lua#L21-L30) to change whether the node id or the display text is shown to the user
+
+## Chat commands
+worldedit_hud_helper provides 2 chat commands:
+
+## `//hud`
+Toggles whether the HUD is shown or not.
+
+
+## `//hudoffset <offset_in_pixels>`
+Adjusts the vertical height of the HUD. For example, to adjust it to be greater (higher up on the screen), do this:
+
+```
+//hudoffset 50
+```
+
+The default value is 0. You can reset to the default value like this:
+
+```
+//hudoffset
+```
+
 
 ## License
 This mod is licensed under the _Mozilla Public License 2.0_, a copy of which (along with a helpful summary as to what you can and can't do with it) can be found in the [`LICENSE`](https://gitlab.com/sbrl/worldedit_hud_helper/blob/master/LICENSE) file in this repository.

commands.lua

@@ -19,3 +19,16 @@ minetest.register_chatcommand("/hud", {
 		worldedit_hud_helper.player_notify(player_name, message)
 	end
 })
+
+minetest.register_chatcommand("/hudoffset", {
+	params = "[<offset_in_pixels>]",
+	description = "Sets the vertical offset of the HUD in pixels. Default: 0, If not specified, then the value is return to it's default value.",
+	func = function(player_name, params_text)
+		local new_offset = tonumber(params_text) or 0
+		local player = minetest.get_player_by_name(player_name)
+		
+		worldedit_hud_helper.update_hud_offset(player, new_offset)
+		
+		worldedit_hud_helper.player_notify(player_name, "HUD offset set to "..new_offset.." pixels (default: 0).")
+	end
+})

hud.lua

@@ -1,15 +1,35 @@
+local default_node_name_offset_y = -100
+local default_rotation_offset_y = -135
 
+--- Initialises a brand-new info table for the given player name.
+-- @param	player_name	string	The name of the player to initialise a new info table for.
+-- @returns	table		The newly generated info table for convenience (note that tables are passed by reference in Lua).
+function worldedit_hud_helper.initialise_info(player_name)
+	worldedit_hud_helper.info[player_name] = {
+		-- Persistable
+		enabled = true,
+		node_name_offset_y = default_node_name_offset_y,
+		rotation_offset_y = default_rotation_offset_y,
+		
+		-- Dynamic
+		node_name = nil,
+		rotation = nil
+	}
+	return worldedit_hud_helper.info[player_name]
+end
+
+--- Initialises the HUD for a given player.
+-- May be called multiple times. 
+-- If called more than once, this has the effect of cycling the HUD registration
+-- with Minetest for the given player.
+-- @param	player		Player	The player object (as returned by minetest.get_player_by_name(player_name: string)).
+-- @returns	nil
 function worldedit_hud_helper.initialise_hud(player)
 	local player_name = player:get_player_name()
 	local player_info = worldedit_hud_helper.info[player_name]
 	
 	if not player_info then
-		player_info = {
-			enabled = true,
-			node_name = nil,
-			rotation = nil
-		}
-		worldedit_hud_helper.info[player_name] = player_info
+		player_info = worldedit_hud_helper.initialise_info(player_name)
 	end
 	
 	player_info.id_node_name = player:hud_add({
@@ -17,7 +37,7 @@ function worldedit_hud_helper.initialise_hud(player)
 		text			= "",
 		number			= 0xFFFFFF,
 		position		= { x = 0.5, y = 1 },
-		offset			= { x = 0, y = -100 },
+		offset			= { x = 0, y = player_info.node_name_offset_y },
 		
 		alignment		= { x = 0, y = 0 }, -- Align to the centre
 		scale			= { x = 150, y = 30 }
@@ -28,7 +48,7 @@ function worldedit_hud_helper.initialise_hud(player)
 		text			= "",
 		number			= 0xFFFFFF,
 		position		= { x = 0.5, y = 1 },
-		offset			= { x = 0, y = -135 },
+		offset			= { x = 0, y = player_info.rotation_offset_y },
 		
 		alignment		= { x = 0, y = 0 }, -- Align to the centre
 		scale			= { x = 150, y = 30 }
@@ -36,6 +56,9 @@ function worldedit_hud_helper.initialise_hud(player)
 	
 end
 
+--- Hides the HUD for a player without deleting their registration & settings.
+-- @param	player		Player	The player object (as returned by minetest.get_player_by_name(player_name: string)).
+-- @returns	nil
 function worldedit_hud_helper.hide_hud(player)
 	local player_info = worldedit_hud_helper.info[player:get_player_name()]
 	
@@ -45,12 +68,48 @@ function worldedit_hud_helper.hide_hud(player)
 	
 	player_info.node_name = nil
 	player_info.rotation = nil
+	
+	worldedit_hud_helper.save_defer()
 end
 
+--- Deletes the HUD for a player.
+-- Caution: This will also wipe all customised settings with no way to recover
+-- them!
+-- @param	player		Player	The player object (as returned by minetest.get_player_by_name(player_name: string)).
 function worldedit_hud_helper.delete_hud(player)
 	worldedit_hud_helper.info[player:get_player_name()] = nil
+	
+	worldedit_hud_helper.save_defer()
+end
+
+--- Updates the HUD offset in pixels.
+-- Larger numbers move the HUD further upwards on the screen.
+-- Default: 0.
+-- @param	player		Player	The player object (as returned by minetest.get_player_by_name(player_name: string)).
+-- @param	new_offset	number	The new offset, as an integer.
+-- @returns	bool		Whether the update was successful or not. A HUD must be initialised for that player for it up have its offset updated.
+function worldedit_hud_helper.update_hud_offset(player, new_offset)
+	if not new_offset then new_offset = 0 end
+	
+	local player_info = worldedit_hud_helper.info[player:get_player_name()]
+	
+	if not player_info then return false end
+	
+	-- Update the new offset
+	player_info.node_name_offset_y = default_node_name_offset_y + -new_offset
+	player_info.rotation_offset_y = default_rotation_offset_y + -new_offset
+	
+	-- Restart the HUD
+	worldedit_hud_helper.hide_hud(player)
+	worldedit_hud_helper.initialise_hud(player)
+	
+	-- Save the new setting(s) to disk
+	worldedit_hud_helper.save_defer()
+	
+	return true
 end
 
 
 minetest.register_on_joinplayer(worldedit_hud_helper.initialise_hud)
-minetest.register_on_leaveplayer(worldedit_hud_helper.delete_hud)
+-- Don't delete the HUD when the player leaves anymore, since we now persist it to disk
+-- minetest.register_on_leaveplayer(worldedit_hud_helper.delete_hud)

init.lua

@@ -20,3 +20,7 @@ dofile(mod_path .. "/raycast_polyfill.lua")
 dofile(mod_path .. "/hud.lua")
 dofile(mod_path .. "/hud_info.lua")
 dofile(mod_path .. "/commands.lua")
+dofile(mod_path .. "/io.lua")
+
+
+worldedit_hud_helper.load()

io.lua

@@ -0,0 +1,88 @@
+
+local filepath_data = minetest.get_worldpath().."/worldedit_hud_helper_data.tsv"
+
+-- Splits a string using a given delimiter.
+-- @source	https://stackoverflow.com/a/7615129/1460422
+-- @param	inputstr	string	The string to split.
+-- @param	sep			string	The delimiter.
+-- @returns	string[]	A table of substrings split out of the input string.
+local function split(inputstr, sep)
+	if sep == nil then
+		sep = "%s"
+	end
+	local t = {}
+	for str in string.gmatch(inputstr, "([^"..sep.."]+)") do
+		table.insert(t, str)
+	end
+	return t
+end
+
+
+--- Serialises and saves the settings for all players to disk.
+-- Settings are saved to a file in the world's directory called
+-- 'worldedit_hud_helper_data.tsv'.
+-- @returns	nil
+function worldedit_hud_helper.save()
+	local result = {
+		table.concat({
+			"player_name",
+			"enabled",
+			"node_name_offset_y",
+			"rotation_offset_y"
+		}, "\t")
+	}
+
+	for player_name, player_info in pairs(worldedit_hud_helper.info) do
+		print("DEBUG player_name", player_name)
+		local next = table.concat({
+			player_name,
+			tostring(player_info.enabled),
+			tostring(player_info.node_name_offset_y),
+			tostring(player_info.rotation_offset_y),
+		}, "\t")
+		print("DEBUG next", next)
+		table.insert(result, next)
+	end
+
+	local handle = io.open(filepath_data, "w+")
+	handle:write(table.concat(result, "\n"))
+	handle:close()
+end
+
+--- Calls worldedit_hud_helper.save(), but pushes the call to the end of the
+-- function queue.
+function worldedit_hud_helper.save_defer()
+	minetest.after(0, function()
+		worldedit_hud_helper.save()
+	end)
+end
+
+--- Loads all the settings for all players from disk.
+-- CAUTION: This should only be called ONCE on server start when no players are
+-- connected!
+-- Note that this does NOT reinitialise any player's HUDs, since it is expected
+-- that they are not connected yet when this function is called.
+-- Note also that if no settings have yet been saved to disk (i.e. the settings
+-- file doesn't exist), then this function silently returns.
+-- @returns	nil
+function worldedit_hud_helper.load()
+	local handle = io.open(filepath_data, "r")
+	if handle == nil then return end
+
+	local i = 0
+	for line in handle:lines() do
+		if i > 0 then
+			local parts = split(line)
+			local player_name = parts[1]
+			local player_info = worldedit_hud_helper.initialise_info(player_name)
+			
+			player_info.enabled = parts[2]
+			player_info.node_name_offset_y = parts[3]
+			player_info.rotation_offset_y = parts[4]
+		end
+		
+		i = i + 1
+	end
+	
+	minetest.log("info", "[worldedit_hud_helper] Loaded per-world settings for "..i.." players.")
+end