Add command to reveal all entries at once

API.md

@@ -77,6 +77,7 @@ These functions are available:
 * `doc.entry_revealed`: Checks whether an entry is visible and normally accessible to a player
 * `doc.mark_entry_as_viewed`: Manually marks an entry as viewed/read by a player
 * `doc.mark_entry_as_revealed`: Make a hidden entry visible and accessible to a player
+* `doc.mark_all_entries_as_revealed`: Make all hidden entries visible and accessible to a player
 * `doc.add_entry_alias`: Add an alternative name which can be used to access an entry
 * `doc.add_entry_aliases`: Add multiple alternative names which can be used to access an entry
 * `doc.get_category_count`: Returns the total number categories
@@ -285,7 +286,7 @@ Always `nil`.
 Marks a particular entry as “revealed” to a player. If the entry is
 declared as hidden, it will become visible in the list of entries for
 this player and will always be accessible with `doc.show_entry`. This
-change is permanently.
+change is permanent.
 
 For entries which are not normally hidden, this function has no direct
 effect.
@@ -298,6 +299,15 @@ effect.
 #### Returns
 Always `nil`.
 
+### `doc.mark_entry_as_revealed(playername)`
+Marks all entries as “revealed” to a player. This change is permanent.
+
+#### Parameters
+* `playername`: Name of the player for whom to reveal the entries
+
+#### Returns
+Always `nil`.
+
 ### `doc.add_entry_alias(category_id, entry_id, alias)`
 Adds a single alias for an entry. When an entry has an alias, supplying the
 alias to a function which demands an `entry_id` will work as if the original

README.md

@@ -6,6 +6,7 @@ The mod itself does not provide any help texts, just the framework.
 Current version: 0.5.0
 
 ## For users
+### Accessing the help
 To open the help, there are multiple ways:
 
 - Say “/help” in chat. This always works.
@@ -16,6 +17,16 @@ The documentation system itself should be more or less self-explanatory.
 This mod is useless on its own, you will only need this mod as a dependency
 for mods which actually add some help entries.
 
+### Hidden entries
+Some entries are initially hidden from you. You can't see them until you
+unlocked them. Mods can decide for themselves how particular entries are
+revealed. Normally you just have to proceed in the game to unlock more
+entries. Hidden entries exist to avoid spoilers and give players a small
+sense of progress.
+
+Players with the `doc_reveal` privilege can use the `doc_reveal` chat command
+to reveal all hidden entries instantly.
+
 ## For modders and subgame authors
 This mod helps you in writing extensive documentation for your mod or subgame.
 You can write about basically anything in the presentation you prefer.

init.lua

@@ -93,6 +93,42 @@ function doc.mark_entry_as_revealed(playername, category_id, entry_id)
 	end
 end
 
+-- Reveal
+function doc.mark_all_entries_as_revealed(playername)
+	-- Has at least 1 new entry been revealed?
+	local reveal1 = false
+	for category_id, category in pairs(doc.data.categories) do
+		if doc.data.players[playername].stored_data.revealed[category_id] == nil then
+			doc.data.players[playername].stored_data.revealed[category_id] = {}
+			doc.data.players[playername].stored_data.revealed_count[category_id] = doc.get_entry_count(category_id) - doc.data.categories[category_id].hidden_count
+		end
+		for entry_id, _ in pairs(category.entries) do
+			if doc.data.players[playername].stored_data.revealed[category_id][entry_id] ~= true then
+				doc.data.players[playername].stored_data.revealed[category_id][entry_id] = true
+				doc.data.players[playername].stored_data.revealed_count[category_id] = doc.data.players[playername].stored_data.revealed_count[category_id] + 1
+				reveal1 = true
+			end
+		end
+	end
+
+	if reveal1 then
+		-- Needed because new entries are added to player's view on entry list
+		doc.data.players[playername].entry_textlist_needs_updating = true
+
+		-- Notify
+		local msg = "All help entries unlocked!"
+		if minetest.get_modpath("central_message") ~= nil then
+			cmsg.push_message_player(minetest.get_player_by_name(playername), msg)
+		else
+			minetest.chat_send_player(playername, msg)
+		end
+
+		-- Play notification sound (ignore sound limit intentionally)
+		minetest.sound_play({ name = "doc_reveal", gain = 0.2 }, { to_player = playername })
+		doc.data.players[playername].last_reveal_sound = os.time()
+	end
+end
+
 -- Returns true if the specified entry has been viewed by the player
 function doc.entry_viewed(playername, category_id, entry_id)
 	local entry, entry_id = doc.get_entry(category_id, entry_id)
@@ -842,3 +878,17 @@ if minetest.get_modpath("unified_inventory") ~= nil then
 		end,
 	})
 end
+
+minetest.register_privilege("doc_reveal", {
+	description = "Allows you to reveal all hidden help entries with /doc_unlock",
+	give_to_singleplayer = false
+})
+
+minetest.register_chatcommand("doc_reveal", {
+	params = "",
+	description = "Reveals all hidden help entries to you",
+	privs = { doc_unlock = true },
+	func = function(name, param)
+		doc.mark_all_entries_as_revealed(name)
+	end,
+})