Improve API: add awards.get_award_states()

README.md

@@ -37,10 +37,11 @@ awards.register_award("mymod:award", {
 
 The above trigger type is an example of a counted_key trigger:
 rather than a single counter there's a counter per key - in this
-case the key is the value of the `node` field. If you leave out
+case the key is the value of the `node` field.
-the key in a `counted_key` trigger, then the total will be used
+
-instead. For example, here is an award which unlocks after you've
+If you leave out the key in a `counted_key` trigger, then the total will be used
-placed 10 nodes of any type:
+instead. For example, here is an award which unlocks after you've placed 10
+nodes of any type:
 
 ```lua
 awards.register_award("mymod:award", {
@@ -125,6 +126,10 @@ awards.register_trigger("foo", {
 	type             = "custom",
 	progress         = "@1/@2 foos",
 	auto_description = { "Do a foo", "Foo @1 times" },
+
+	on_register = function(self, award)
+		print(award.name .. " was registered with foo trigger type")
+	end,
 })
 
 minetest.register_on_foo(function()
@@ -168,7 +173,9 @@ end
 
 # API
 
-* awards.register_award(name, def), the def table has the following fields:
+## Awards
+
+* `awards.register_award(name, def)`, the def table has the following fields:
 	* `title` - title of the award (defaults to name)
 	* `description` - longer description of the award, displayed in Awards tab
 	* `difficulty` - see [Award Difficulty](#award-difficulty).
@@ -182,23 +189,44 @@ end
 	* `background` - the background image, use default otherwise.
 	* `trigger` - trigger definition, see [Builtin Trigger Types](#builtin-trigger-types).
 	* `on_unlock(name, def)` - callback on unlock.
-* awards.register_trigger(name, def), the def table has the following fields:
+* `awards.registered_awards` - table of award name to definition.
-	* `type` - see [Trigger Types](#trigger-types).
+* `awards.register_on_unlock(func(name, def))`
+	* `name` is the player name
+	* `def` is the award def.
+	* return true to cancel HUD
+* `awards.unlock(player_name, award)`
+	* gives an award to a player
+* `awards.get_award_states(player_name)`
+	* Returns list of tables, sorted by `score`, each having the fields:
+
+			{
+				name     = "mymod:awardname",
+				def      = {}, -- Award definition
+				unlocked = true, -- Whether award has been unlocked
+				started  = true, -- Whether any progress has been made
+				score    = 0, -- Score used in sorting
+
+				-- Either a table or nil
+				progress = {
+					current = 5,
+					target  = 10,
+					label   = "label", -- Label to show over progress bar
+				}
+			}
+
+## Triggers
+
+* `awards.register_trigger(name, def)`, the def table has the following fields:
+	* `type` - see trigger type types in [Trigger Types](#trigger-types).
 	* `progress` - used to format progress, defaults to "%1/%2".
 	* `auto_description` - a table of two elements. Each element is a format string. Element 1 is singular, element 2 is plural. Used for the award description (not title) if none is given.
-	* `on_register(award_def)` - called when an award registers with this type.
+	* `on_register(self, award_def)` - called when an award registers with this type.
 	* "counted_key" only:
 		* `auto_description_total` - Used if the trigger is for the total.
 		* `get_key(self, def)` - get key for particular award, return nil for a total.
 		* `key_is_item` - true if the key is an item name. On notify(),
 			any watched groups will also be notified as `group:groupname` keys.
-* awards.register_on_unlock(func(name, def))
+* `awards.registered_triggers` - table of trigger name to definition.
-	* name is the player name
-	* def is the award def.
-	* return true to cancel HUD
-* awards.unlock(name, award)
-	* gives an award to a player
-	* name is the player name
 
 ## Builtin Trigger Types
 

init.lua

@@ -3,7 +3,9 @@
 -- The global award namespace
 awards = {
 	show_mode = "hud",
+	registered_awards = {},
 	registered_triggers = {},
+	on_unlock = {},
 }
 
 -- Internationalization support.

src/api_awards.lua

@@ -182,3 +182,71 @@ function awards.unlock(name, award)
 		end)
 	end
 end
+
+function awards.get_award_states(name)
+	local hash_is_unlocked = {}
+	local retval = {}
+
+	-- Add all unlocked awards
+	local data = awards.player(name)
+	if data and data.unlocked then
+		for awardname, _ in pairs(data.unlocked) do
+			local def = awards.registered_awards[awardname]
+			if def then
+				hash_is_unlocked[awardname] = true
+				local score = -100000
+
+				local difficulty = def.difficulty or 1
+				if def.trigger and def.trigger.target then
+					difficulty = difficulty * def.trigger.target
+				end
+				score = score + difficulty
+
+				retval[#retval + 1] = {
+					name     = awardname,
+					def      = def,
+					unlocked = true,
+					started  = true,
+					score    = score,
+					progress = nil,
+				}
+			end
+		end
+	end
+
+	-- Add all locked awards
+	for _, def in pairs(awards.registered_awards) do
+		if not hash_is_unlocked[def.name] and def:can_unlock(data) then
+			local progress = def.get_progress and def:get_progress(data)
+			local started = false
+			local score = def.difficulty or 1
+			if def.secret then
+				score = 1000000
+			elseif def.trigger and def.trigger.target and progress then
+				local perc = progress.current / progress.target
+				score = score * (1 - perc) * def.trigger.target
+				if perc < 0.001 then
+					score = score + 100
+				else
+					started = true
+				end
+			else
+				score = 100
+			end
+
+			retval[#retval + 1] = {
+				name     = def.name,
+				def      = def,
+				unlocked = false,
+				started  = started,
+				score    = score,
+				progress = progress,
+			}
+		end
+	end
+
+	table.sort(retval, function(a, b)
+		return a.score < b.score
+	end)
+	return retval
+end

src/api_triggers.lua

@@ -2,9 +2,7 @@
 
 local S, NS = awards.gettext, awards.ngettext
 
-awards.registered_awards = {}
 awards.on = {}
-awards.on_unlock = {}
 
 local default_def = {}
 
@@ -43,11 +41,12 @@ function awards.register_trigger(tname, tdef)
 			}
 			tdef.register(tmp)
 
-			function def.getProgress(_, data)
+			function def.get_progress(_, data)
-				local done = math.min(data[tname] or 0, tmp.target)
+				local current = math.min(data[tname] or 0, tmp.target)
 				return {
-					perc = done / tmp.target,
+					current = current,
-					label = S(tdef.progress, done, tmp.target),
+					target = tmp.target,
+					label = S(tdef.progress, current, tmp.target),
 				}
 			end
 
@@ -102,7 +101,7 @@ function awards.register_trigger(tname, tdef)
 			end
 
 			-- Called to get progress values and labels
-			function def.getProgress(_, data)
+			function def.get_progress(_, data)
 				data[tname] = data[tname] or {}
 
 				local done
@@ -114,7 +113,8 @@ function awards.register_trigger(tname, tdef)
 				done = math.min(done, tmp.target)
 
 				return {
-					perc = done / tmp.target,
+					current = done,
+					target = tmp.target,
 					label = S(tdef.progress, done, tmp.target),
 				}
 			end

src/gui.lua

@@ -2,73 +2,9 @@
 
 local S = awards.gettext
 
-local function order_awards(name)
-	local hash_is_unlocked = {}
-	local retval = {}
-
-	local data = awards.player(name)
-	if data and data.unlocked then
-		for awardname, _ in pairs(data.unlocked) do
-			local def = awards.registered_awards[awardname]
-			if def then
-				hash_is_unlocked[awardname] = true
-				local score = -100000
-
-				local difficulty = def.difficulty or 1
-				if def.trigger and def.trigger.target then
-					difficulty = difficulty * def.trigger.target
-				end
-				score = score + difficulty
-
-				retval[#retval + 1] = {
-					name     = awardname,
-					def      = def,
-					unlocked = true,
-					started  = true,
-					score    = score,
-				}
-			end
-		end
-	end
-
-	for _, def in pairs(awards.registered_awards) do
-		if not hash_is_unlocked[def.name] and def:can_unlock(data) then
-			local started = false
-			local score = def.difficulty or 1
-			if def.secret then
-				score = 1000000
-			elseif def.trigger and def.trigger.target and def.getProgress then
-				local progress = def:getProgress(data).perc
-				score = score * (1 - progress) * def.trigger.target
-				if progress < 0.001 then
-					score = score + 100
-				else
-					started = true
-				end
-			else
-				score = 100
-			end
-
-			retval[#retval + 1] = {
-				name     = def.name,
-				def      = def,
-				unlocked = false,
-				started  = started,
-				score    = score,
-			}
-		end
-	end
-
-	table.sort(retval, function(a, b)
-		return a.score < b.score
-	end)
-	return retval
-end
-
 function awards.get_formspec(name, to, sid)
 	local formspec = ""
-	local awards_list = order_awards(name)
+	local awards_list = awards.get_award_states(name)
-	local data  = awards.player(name)
 
 	if #awards_list == 0 then
 		formspec = formspec .. "label[3.9,1.5;"..minetest.formspec_escape(S("Error: No achivements available.")).."]"
@@ -106,15 +42,11 @@ function awards.get_formspec(name, to, sid)
 		if sdef and sdef.icon then
 			formspec = formspec .. "image[0.45,0;3.5,3.5;" .. sdef.icon .. "]"  -- adjusted values from 0.6,0;3,3
 		end
-		local barwidth = 3.95
+
-		local perc = nil
+		if sitem.progress then
-		local label = nil
+			local barwidth = 3.95
-		if sdef.getProgress and data then
+			local perc = sitem.progress.current / sitem.progress.target
-			local res = sdef:getProgress(data)
+			local label = sitem.progress.label
-			perc = res.perc
-			label = res.label
-		end
-		if perc then
 			if perc > 1 then
 				perc = 1
 			end
@@ -124,6 +56,7 @@ function awards.get_formspec(name, to, sid)
 				formspec = formspec .. "label[1.6,8.15;" .. minetest.formspec_escape(label) .. "]"
 			end
 		end
+
 		if sdef and sdef.description then
 			formspec = formspec .. "box[-0.05,3.75;3.9,4.2;#000]"
 			formspec = formspec	.. "textarea[0.25,3.75;3.9,4.2;;" ..
@@ -174,7 +107,7 @@ function awards.show_to(name, to, sid, text)
 		return
 	end
 	if text then
-		local awards_list = order_awards(name)
+		local awards_list = awards.get_award_states(name)
 		if #awards_list == 0 then
 			minetest.chat_send_player(to, S("Error: No award available."))
 			return