Add extended tooltips

mods/HELP/tt/API.md

@@ -0,0 +1,33 @@
+# Tooltip API
+This API explains how to handle the extended item tooltips (`description` field).
+
+## Fields
+
+Add these to the item definition.
+
+* `_tt_ignore`: If `true`, the `description` of this item won't be altered at all
+* `_tt_help`: Custom help text
+* `_tt_food`: If `true`, item is a food item that can be consumed by the player
+* `_tt_food_hp`: Health increase (in HP) for player when consuming food item
+
+Once this mod had overwritten the `description` field of an item was overwritten, it will save the original (unaltered) `description` in the `_tt_original_description` field.
+
+## `tt.register_snippet(func)`
+
+Register a custom snippet function.
+`func` is a function of the form `func(itemstring)`.
+It will be called for (nearly) every itemstring.
+
+Returns: Two values, the first one is required.
+1st return value: A string you want to append to this item or `nil` if nothing shall be appended.
+2nd return value: If nil, `tt` will take of the text color. If a ColorString in `"#RRGGBB"` format, entire text is colorized in this color. Return `false` to force `tt` to not apply text any colorization (useful if you want to call `minetest.colorize` yourself.
+
+Example:
+
+```
+tt.register_snippet(function(itemstring)
+	if minetest.get_item_group(itemstring, "magic") == 1 then
+		return "This item is magic"
+	end
+end)
+```

mods/HELP/tt/README.md

@@ -0,0 +1,12 @@
+# Extended Tooltip (`tt`)
+This mod extends the tooltip of items to add more informative texts.
+
+It displays the following useful information:
+* Weapon damage and speed
+* Tool properties
+* Noteworthy block properties
+* Food satiation
+* Custom help text (added by mods)
+
+## License
+MIT License.

mods/HELP/tt/init.lua

@@ -0,0 +1,55 @@
+local S = minetest.get_translator("tt")
+
+tt = {}
+tt.COLOR_DEFAULT = "#d0ffd0"
+tt.COLOR_DANGER = "#ffff00"
+tt.COLOR_GOOD = "#00ff00"
+
+-- API
+tt.registered_snippets = {}
+
+tt.register_snippet = function(func)
+	table.insert(tt.registered_snippets, func)
+end
+
+-- Register core snippets
+
+dofile(minetest.get_modpath(minetest.get_current_modname()).."/snippets_core.lua")
+dofile(minetest.get_modpath(minetest.get_current_modname()).."/snippets_builtin.lua")
+
+-- Apply item description updates
+
+local function append_snippets()
+	for itemstring, def in pairs(minetest.registered_items) do
+		if itemstring ~= "" and itemstring ~= "air" and itemstring ~= "ignore" and itemstring ~= "unknown" and def ~= nil and def.description ~= nil and def.description ~= "" and def._tt_ignore ~= true then
+			local desc = def.description
+			local orig_desc = desc
+			local first = true
+			-- Apply snippets
+			for s=1, #tt.registered_snippets do
+				local str, snippet_color = tt.registered_snippets[s](itemstring)
+				if snippet_color == nil then
+					snippet_color = tt.COLOR_DEFAULT
+				elseif snippet_color == false then
+					snippet_color = false
+				end
+				if str then
+					if first then
+						first = false
+					end
+					desc = desc .. "\n"
+					if snippet_color then
+						desc = desc .. minetest.colorize(snippet_color, str)
+					else
+						desc = desc .. str
+					end
+				end
+			end
+			if desc ~= def.description then
+				minetest.override_item(itemstring, { description = desc, _tt_original_description = orig_desc })
+			end
+		end
+	end
+end
+
+minetest.register_on_mods_loaded(append_snippets)

mods/HELP/tt/locale/template.txt

@@ -0,0 +1,27 @@
+# textdomain:tt
+Damage: @1=
+Damage (@1): @2=
+Healing: @1=
+Healing (@1): @2=
+Full punch interval: @1s=
+Food item=
++@1 satiation=
+@1 satiation=
++@1 food points=
+Contact damage: @1 per second=
+Contact healing: @1 per second=
+Drowning damage: @1=
+Bouncy (@1%)=
+Luminance: @1=
+Slippery=
+Climbable=
+Climbable (only downwards)=
+No jumping=
+No swimming upwards=
+No rising=
+Fall damage: @1%=
+Fall damage: +@1%=
+No fall damage=
+Digs @1 blocks=
+Digs @1 blocks instantly=
+Minimum dig time: @1s=

mods/HELP/tt/locale/tt.de.tr

@@ -0,0 +1,27 @@
+# textdomain:tt
+Damage: @1=Schaden: @1
+Damage (@1): @2=Schaden (@1): @2
+Healing: @1=Heilung: @1
+Healing (@1): @2=Heilung (@1): @2
+Full punch interval: @1s=Zeit zum Ausholen: @1s
+Food item=Lebensmittel
++@1 satiation=+@1 Sättigung
+@1 satiation=@1 Sättigung
++@1 food points=+@1 Nahrungspunkte
+Contact damage: @1 per second=Kontaktschaden: @1 pro Sekunde
+Contact healing: @1 per second=Kontaktheilung: @1 pro Sekunde
+Drowning damage: @1=Ertrinkensschaden: @1
+Bouncy (@1%)=Sprunghaft (@1%)
+Luminance: @1=Lichtstärke: @1
+Slippery=Rutschig
+Climbable=Erkletterbar
+Climbable (only downwards)=Erkletterbar (nur nach unten)
+No jumping=Kein Springen
+No swimming upwards=Kein nach oben schwimmen
+No rising=Kein Aufsteigen
+Fall damage: @1%=Fallschaden: @1%
+Fall damage: +@1%=Fallschaden: +@1%
+No fall damage=Kein Fallschaden
+Digs @1 blocks=Gräbt „@1“-Blöcke
+Digs @1 blocks instantly=Gräbt „@1“-Blöcke sofort
+Minimum dig time: @1s=Minimale Grabezeit: @1s

mods/HELP/tt/mod.conf

@@ -0,0 +1,2 @@
+name = tt
+description = Appends a helpful tooltip to the item description

mods/HELP/tt/snippets_builtin.lua

@@ -0,0 +1,210 @@
+local S = minetest.get_translator("tt")
+
+local function get_min_digtime(caps)
+	local mintime
+	local unique = true
+	local maxlevel = caps.maxlevel
+	if not maxlevel then
+		maxlevel = 1
+	end
+	if maxlevel > 1 then
+		unique = false
+	end
+	if caps.times then
+		for r=1,3 do
+			local time = caps.times[r]
+			if time and maxlevel > 1 then
+				time = time / maxlevel
+			end
+			if time and ((not mintime) or (time < mintime)) then
+				if mintime and (time < mintime) then
+					unique = false
+				end
+				mintime = time
+			end
+		end
+	end
+	return mintime, unique
+end
+
+local function newline(str)
+	if str ~= "" then
+		str = str .. "\n"
+	end
+	return str
+end
+
+-- Digging capabilities of tool
+tt.register_snippet(function(itemstring)
+	local def = minetest.registered_items[itemstring]
+	if not def.tool_capabilities then
+		return
+	end
+	local groupcaps = def.tool_capabilities.groupcaps
+	if not groupcaps then
+		return
+	end
+	local formstring = ""
+	local capstr = ""
+	local caplines = 0
+	for k,v in pairs(groupcaps) do
+		local speedstr = ""
+		local miningusesstr = ""
+		-- Mining capabilities
+		caplines = caplines + 1
+		local maxlevel = v.maxlevel
+		if not maxlevel then
+			-- Default from tool.h
+			maxlevel = 1
+		end
+
+		-- Digging speed
+		local speed_class = def.groups and def.groups.dig_speed_class
+		if speed_class == 1 then
+			speedstr = S("Painfully slow")
+		elseif speed_class == 2 then
+			speedstr = S("Very slow")
+		elseif speed_class == 3 then
+			speedstr = S("Slow")
+		elseif speed_class == 4 then
+			speedstr = S("Fast")
+		elseif speed_class == 5 then
+			speedstr = S("Very fast")
+		elseif speed_class == 6 then
+			speedstr = S("Extremely fast")
+		elseif speed_class == 7 then
+			speedstr = S("Instantaneous")
+		end
+
+		-- Number of mining uses
+		local base_uses = v.uses
+		if not base_uses then
+			-- Default from tool.h
+			base_uses = 20
+		end
+		if def._doc_items_durability == nil and base_uses > 0 then
+			local real_uses = base_uses * math.pow(3, maxlevel)
+			if real_uses < 65535 then
+				miningusesstr = S("@1 uses", real_uses)
+			else
+				miningusesstr = S("Unlimited uses")
+			end
+		end
+
+		if speedstr ~= "" then
+			capstr = capstr .. S("Mining speed: @1", speedstr) .. "\n"
+		end
+		if miningusesstr ~= "" then
+			capstr = capstr .. S("Mining durability: @1", miningusesstr) .. "\n"
+		end
+
+		-- Only show one group at max
+		break
+	end
+	if caplines > 0 then
+		-- Capabilities
+		formstring = formstring .. capstr
+		-- Max. drop level
+		local mdl = def.tool_capabilities.max_drop_level
+		if not def.tool_capabilities.max_drop_level then
+			mdl = 0
+		end
+		formstring = formstring .. S("Block breaking strength: @1", mdl)
+	end
+	if formstring == "" then
+		formstring = nil
+	end
+	return formstring
+end)
+
+-- Food
+tt.register_snippet(function(itemstring)
+	local def = minetest.registered_items[itemstring]
+	local desc
+	if def._tt_food then
+		desc = S("Food item")
+		if def._tt_food_hp then
+			local msg = S("+@1 food points", def._tt_food_hp)
+			desc = desc .. "\n" .. msg
+		end
+	end
+	return desc
+end)
+
+-- Node info
+tt.register_snippet(function(itemstring)
+	local def = minetest.registered_items[itemstring]
+	local desc = ""
+
+	-- Health-related node facts
+	if def.damage_per_second then
+		if def.damage_per_second > 0 then
+			desc = newline(desc)
+			desc = desc .. minetest.colorize(tt.COLOR_DANGER, S("Contact damage: @1 per second", def.damage_per_second))
+		elseif def.damage_per_second < 0 then
+			desc = newline(desc)
+			desc = desc .. minetest.colorize(tt.COLOR_GOOD, S("Contact healing: @1 per second", math.abs(def.damage_per_second)))
+		end
+	end
+	if def.drowning and def.drowning ~= 0 then
+		desc = newline(desc)
+		desc = desc .. minetest.colorize(tt.COLOR_DANGER, S("Drowning damage: @1", def.drowning))
+	end
+	local tmp = minetest.get_item_group(itemstring, "fall_damage_add_percent")
+	if tmp > 0 then
+		desc = newline(desc)
+		desc = desc .. minetest.colorize(tt.COLOR_DANGER, S("Fall damage: +@1%", tmp))
+	elseif tmp == -100 then
+		desc = newline(desc)
+		desc = desc .. minetest.colorize(tt.COLOR_GOOD, S("No fall damage"))
+	elseif tmp < 0 then
+		desc = newline(desc)
+		desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("Fall damage: @1%", tmp))
+	end
+
+	-- Movement-related node facts
+	if minetest.get_item_group(itemstring, "disable_jump") == 1 and not def.climbable then
+		if def.liquidtype == "none" then
+			desc = newline(desc)
+			desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("No jumping"))
+		elseif minetest.get_item_group(itemstring, "fake_liquid") == 0 then
+			desc = newline(desc)
+			desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("No swimming upwards"))
+		else
+			desc = newline(desc)
+			desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("No rising"))
+		end
+	end
+	if def.climbable then
+		if minetest.get_item_group(itemstring, "disable_jump") == 1 then
+			desc = newline(desc)
+			desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("Climbable (only downwards)"))
+		else
+			desc = newline(desc)
+			desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("Climbable"))
+		end
+	end
+	if minetest.get_item_group(itemstring, "slippery") >= 1 then
+		desc = newline(desc)
+		desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("Slippery"))
+	end
+	local tmp = minetest.get_item_group(itemstring, "bouncy")
+	if tmp >= 1 then
+		desc = newline(desc)
+		desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("Bouncy (@1%)", tmp))
+	end
+
+	-- Node appearance
+	tmp = def.light_source
+	if tmp and tmp >= 1 then
+		desc = newline(desc)
+		desc = desc .. minetest.colorize(tt.COLOR_DEFAULT, S("Luminance: @1", tmp))
+	end
+
+
+	if desc == "" then
+		desc = nil
+	end
+	return desc, false
+end)
+

mods/HELP/tt/snippets_core.lua

@@ -0,0 +1,11 @@
+-- CORE SNIPPETS --
+
+-- Custom text (_tt_help)
+tt.register_snippet(function(itemstring)
+	local def = minetest.registered_items[itemstring]
+	if def._tt_help then
+		return def._tt_help
+	end
+end)
+
+