Update pbmarks mod to v1.0...

Release: https://github.com/AntumMT/mod-pbmarks/releases/tag/v1.0

README.md

@@ -142,7 +142,7 @@ The game includes the mods from the default [minetest_game](https://github.com/m
   * [hud_compass][] (MIT / [CC BY-SA ][lic.ccbysa3.0]) -- version: [648c744
  Git][ver.hud_compass] *2020-04-23*
   * [hudbars][] ([MIT][lic.mit] / [CC BY-SA][lic.ccbysa3.0]) -- version: [2.3.1][ver.hudbars] *2020-07-11*
-  * [pbmarks][] ([MIT][lic.pbmarks]) -- version: [00c3549 Git][ver.pbmarks] *2021-05-28*
+  * [pbmarks][] ([MIT][lic.pbmarks]) -- version: [1.0][ver.pbmarks] *2021-06-15*
 * world/
   * [bright_night][] ([Unlicense][lic.unlicense]) -- version: [69b750a Git][ver.bright_night] *2018-06-03*
   * [desert_life][] ([CC BY-SA][lic.ccbysa4.0]) -- version: [188f984 Git][ver.desert_life] *2020-01-24*
@@ -606,7 +606,7 @@ The game includes the mods from the default [minetest_game](https://github.com/m
 [ver.nether]: https://github.com/minetest-mods/nether/tree/v3
 [ver.no_fall_damage]: https://repo.or.cz/minetest_no_fall_damage.git/shortlog/refs/tags/1.0.0
 [ver.painting]: https://github.com/minetest-mods/painting/tree/8961849
-[ver.pbmarks]: https://github.com/AntumMT/mod-pbmarks/tree/00c3549
+[ver.pbmarks]: https://github.com/AntumMT/mod-pbmarks/releases/tag/v1.0
 [ver.pipeworks]: https://gitlab.com/VanessaE/pipeworks/tree/2670fd8
 [ver.player_monoids]: https://github.com/minetest-mods/player_monoids/tree/ed11a73
 [ver.pvp_areas]: https://github.com/everamzah/pvp_areas/tree/6e4d66d

minetest.conf.example

@@ -2792,6 +2792,21 @@ inventory_craft_small = false
 inventory_default = craft
 
 
+# *** pbmarks ***
+
+## Number of allowed bookmarks.
+#    type:    int
+#    min:     1
+#    max:     5
+#    default: 5
+#pbmarks.max = 5
+
+## Don't allow bookmarks to be set in areas not accessible to player.
+#    type:    bool
+#    default: true
+#pbmarks.disallow_protected = true
+
+
 
 ###########
 ## WORLD ##

mods/ui/pbmarks/README.md

@@ -1,23 +1,57 @@
 ## Personal Bookmarks
 
+<img src="icon.png" alt="icon" width="100px" />
+
 ### Description:
 
 A [Minetest][] mod that allows players to create a limited number of personal bookmarks to where they can teleport.
 
-***WARNING:** this mod is in early development & not ready for live use*
+![screenshot](screenshot.png)
 
 ### Licensing:
 
 - Code: [MIT](LICENSE.txt)
 - Textures: CC0
+- Icon: [CC0](https://openclipart.org/detail/266815)
 
 ### Usage:
 
+```
+- open inventory
+- select "More" tab
+- select "Personal Bookmarks"
+- input a description into text field
+- press "Set" to store location
+- press "Go" to teleport to location
+```
+
+#### Settings:
+
+```
+- pbmarks.max
+  - number of allowed bookmarks
+  - type:    int
+  - min:     1
+  - max:     5
+  - default: 5
+
+- pbmarks.disallow_protected
+  - don't allow bookmarks to be set in areas not accessible to player (requires protection mod, currently only simple_protection supported)
+  - type:    bool
+  - default: true
+```
+
 ### Requirements:
 
+- Depends: [wdata](https://content.minetest.net/packages/AntumDeluge/wdata/), [sfinv_buttons](https://content.minetest.net/packages/Wuzzy/sfinv_buttons/)
+- Optional depends: [simple_protection](https://content.minetest.net/packages/Krock/simple_protection/)
+
 ### Links:
 
+- [![ContentDB](https://content.minetest.net/packages/AntumDeluge/pbmarks/shields/title/)](https://content.minetest.net/packages/AntumDeluge/pbmarks/)
+- [Forum](https://forum.minetest.net/viewtopic.php?t=26805)
 - [Git repo](https://github.com/AntumMT/mod-pbmarks)
+- [API](https://antummt.github.io/mod-pbmarks/docs/api.html)
 - [Changelog](changelog.txt)
 - [TODO](TODO.txt)
 

mods/ui/pbmarks/TODO.txt

@@ -1,2 +1,6 @@
 
 TODO:
+- resize formspec dependent on number of allowed bookmarks
+- increase maximum to 7 but keep default at 5
+- support protection mods (don't allow bookmarks to be set in protected areas that player can't access)
+	- areas

mods/ui/pbmarks/api.lua

@@ -1,14 +1,53 @@
 
+--- Personal Bookmarks API
+--
+--  @module api.lua
+
+
+local S = core.get_translator(pbmarks.modname)
+
 -- initialize bookmarks
 local bookmarks = wdata.read("personal_bookmarks") or {}
 
+local function update_pbmfile()
+	wdata.write("personal_bookmarks", bookmarks)
+end
 
+local function can_access(pos, pname) return true end
+local function get_owner(pos) return "" end
+
+if core.global_exists("s_protect") then
+	can_access = s_protect.can_access
+	get_owner = function(pos)
+		local claim = s_protect.get_claim(pos)
+		if claim then return s_protect.get_claim(pos).owner end
+
+		return ""
+	end
+end
+
+--- Retrieves a bookmark.
+--
+--  @tparam string pname Player name referenced for bookmark.
+--  @tparam int idx Index of bookmark to retrieve.
+--  @treturn table `BookmarkTable`.
 function pbmarks.get(pname, idx)
 	return (bookmarks[pname] or {})[idx]
 end
 
-
+--- Sets bookmark information.
+--
+--  @tparam string pname Player name referenced for bookmark.
+--  @tparam int idx Index of bookmark to be set.
+--  @tparam string label Label used to identify bookmark.
+--  @tparam table pos Position to be bookmarked.
 function pbmarks.set(pname, idx, label, pos)
+	-- check for protection
+	if pbmarks.disallow_protected and not can_access(pos, pname) then
+		core.chat_send_player(pname, S("You cannot set bookmarks in areas owned by @1.", get_owner(pos)))
+		return
+	end
+
 	idx = idx or 1
 
 	local pbm = bookmarks[pname] or {}
@@ -18,10 +57,33 @@ function pbmarks.set(pname, idx, label, pos)
 	}
 
 	bookmarks[pname] = pbm
-	wdata.write("personal_bookmarks", bookmarks)
+	update_pbmfile()
+end
+
+--- Unsets bookmark information.
+--
+--  @tparam string pname Player name referenced for bookmark.
+--  @tparam int idx Index of bookmark to be unset.
+function pbmarks.unset(pname, idx)
+	if not idx or idx < 1 or idx > pbmarks.max then
+		pbmarks.log("error", "cannot unset bookmark, invalid index: " .. tostring(idx))
+		return
+	end
+
+	local pbm = bookmarks[pname]
+	if not pbm then
+		pbmarks.log("error", "cannot unset bookmark, player not found: " .. pname)
+		return
+	end
+
+	pbm[idx] = nil
+	bookmarks[pname] = pbm
+	update_pbmfile()
 end
 
 
-function pbmarks.show_formspec(pname)
+--- Bookmark table.
-	core.show_formspec(pname, pbmarks.modname, pbmarks.get_formspec(pname))
+--
-end
+--  @table BookmarkTable
+--  @tfield string label Label used to identify bookmark.
+--  @tfield table pos Position table with x,y,z coordinates (example: *pos = {x=7, y=8, z=-12}*).

mods/ui/pbmarks/changelog.txt

@@ -2,3 +2,7 @@
 v1.0
 ----
 - initial release
+- created formspec that allows for managing 5 personal bookmarks
+- added localization support
+- added inventory support with sfinv_buttons
+- added protection support with simple_protection

mods/ui/pbmarks/formspec.lua

@@ -1,18 +1,24 @@
 
+--- Personal Bookmarks Formspec
+--
+--  @module formspec.lua
+
+
+local S = core.get_translator(pbmarks.modname)
+
 local width = 10
 local height = 8
 
-local title = "Personal Bookmarks"
-
 
+--- Retrieves formspec formatted string for this mod.
+--
+--  @tparam string pname Player name referenced for bookmarks.
+--  @treturn string Formatted string.
 function pbmarks.get_formspec(pname)
-	-- somewhat center title
-	local title_x = math.floor(width / 2) - (math.floor(string.len(title)) / 10)
-
 	local formspec = "formspec_version[4]"
 		.. "size[" .. tostring(width) .. "," .. tostring(height) .. "]"
-		.. "button[0.5,0.25;1.5,0.75;btn_back;Back]"
+		.. "button[0.5,0.25;1.5,0.75;btn_back;" .. S("Back") .. "]"
-		.. "label[" .. tostring(title_x) .. ",0.5;" .. title .. "]"
+		.. "label[2.25,0.65;" .. S("Personal Bookmarks") .. "]"
 
 	local init_y = 1.5 -- horizontal position of first bookmark
 	for idx = 1, pbmarks.max do
@@ -30,8 +36,8 @@ function pbmarks.get_formspec(pname)
 			.. "field[0.5," .. tostring(init_y) .. ";3,0.75;" .. fname .. ";;" .. label .. "]"
 			.. "field_close_on_enter[" .. fname .. ";false]"
 			.. "label[3.75," .. tostring(init_y) + 0.25 .. ";" .. core.formspec_escape(pos) .. "]"
-			.. "button[6.25," .. tostring(init_y) .. ";1.5,0.75;" .. btn_go .. ";Go]" -- TODO: change to "button_exit"
+			.. "button[6.25," .. tostring(init_y) .. ";1.5,0.75;" .. btn_go .. ";" .. S("Go") .. "]"
-			.. "button[8," .. tostring(init_y) .. ";1.5,0.75;" .. btn_set .. ";Set]"
+			.. "button[8," .. tostring(init_y) .. ";1.5,0.75;" .. btn_set .. ";" .. S("Set") .. "]"
 
 		init_y = init_y + 1.25
 	end
@@ -39,6 +45,13 @@ function pbmarks.get_formspec(pname)
 	return formspec
 end
 
+--- Displays formspec for managing bookmarks.
+--
+--  @tparam string pname Player name referenced for bookmarks & who will be shown formspec.
+function pbmarks.show_formspec(pname)
+	core.show_formspec(pname, pbmarks.modname, pbmarks.get_formspec(pname))
+end
+
 
 core.register_on_player_receive_fields(function(player, formname, fields)
 	if formname == pbmarks.modname then
@@ -67,7 +80,7 @@ core.register_on_player_receive_fields(function(player, formname, fields)
 
 		if go then
 			if not pbm.pos then
-				core.chat_send_player(pname, "This bookmark is not set.")
+				core.chat_send_player(pname, S("This bookmark is not set."))
 				return
 			end
 
@@ -78,7 +91,15 @@ core.register_on_player_receive_fields(function(player, formname, fields)
 		elseif set then
 			local label = (fields["input" .. tostring(idx)] or ""):trim()
 			if label == "" then
-				core.chat_send_player(pname, "You must choose a label to set this bookmark")
+				-- unset
+				if pbm.pos then
+					pbmarks.unset(pname, idx)
+					core.chat_send_player(pname, S("Unset bookmark at @1,@2,@3.", pbm.pos.x, pbm.pos.y, pbm.pos.z))
+					pbmarks.show_formspec(pname)
+				else
+					core.chat_send_player(pname, S("You must choose a label to set this bookmark."))
+				end
+
 				return
 			end
 

mods/ui/pbmarks/locale/template.txt

@@ -0,0 +1,11 @@
+Translated by:
+
+
+Personal Bookmarks=
+Back=
+Go=
+Set=
+This bookmark is not set.=
+You must choose a label to set this bookmark.=
+You cannot set bookmarks in areas owned by @1.=
+Unset bookmark at @1,@2,@3.=

mods/ui/pbmarks/mod.conf

@@ -4,5 +4,5 @@ description = Allows players to create a limited number of personal bookmarks to
 version = 1.0
 license = MIT
 author = Jordan Irwin (AntumDeluge)
-depends = wdata
+depends = wdata, sfinv_buttons
-optional_depends = sfinv_buttons
+optional_depends = simple_protection

mods/ui/pbmarks/settings.lua

@@ -1,4 +1,17 @@
 
+--- Personal Bookmarks Settings
+--
+--  @module settings.lua
+
+
+--- Number of allowed bookmarks.
+--
+--  - min: 1
+--  - max: 5
+--
+--  @setting pbmarks.max
+--  @settype int
+--  @default 5
 pbmarks.max = tonumber(core.settings:get("pbmarks.max")) or 5
 
 if pbmarks.max < 1 then
@@ -8,3 +21,10 @@ elseif pbmarks.max > 5 then
 	pbmarks.log("warning", "bookmark count too hight, setting to 5")
 	pbmarks.max = 5
 end
+
+--- Don't allow bookmarks to be set in areas not accessible to player.
+--
+--  @setting pbmarks.disallow_protected
+--  @settype bool
+--  @default true
+pbmarks.disallow_protected = core.settings:get_bool("pbmarks.disallow_protected", true)

mods/ui/pbmarks/settingtypes.txt

@@ -1,3 +1,6 @@
 
 # Number of allowed bookmarks.
 pbmarks.max (Number of bookmarks) int 5 1 5
+
+# Don't allow bookmarks to be set in areas not accessible to player.
+pbmarks.disallow_protected (Disallow bookmarking in protected areas) bool true

mods/ui/pbmarks/ui.lua

@@ -1,4 +1,6 @@
 
+local S = core.get_translator(pbmarks.modname)
+
 local ui_handlers = {
 	"sfinv_buttons",
 }
@@ -11,7 +13,7 @@ end
 
 
 sfinv_buttons.register_button(pbmarks.modname, {
-	title = "Personal Bookmarks",
+	title = S("Personal Bookmarks"),
 	image = "pbmarks_check.png",
 	action = function(player)
 		pbmarks.show_formspec(player:get_player_name())

settingtypes.txt

@@ -810,6 +810,15 @@ moreblocks.stairsplus_in_creative_inventory (Display Stairs+ nodes in creative i
 motorbike.punch_inv (Punch places in inventory) bool false
 
 
+[*pbmarks]
+
+# Number of allowed bookmarks.
+pbmarks.max (Number of bookmarks) int 5 1 5
+
+# Don't allow bookmarks to be set in areas not accessible to player.
+pbmarks.disallow_protected (Disallow bookmarking in protected areas) bool true
+
+
 [*pipeworks]
 
 #Enable pipes.