Add a short_description to be used by mods (#8980)

builtin/game/register.lua

@@ -118,6 +118,12 @@ function core.register_item(name, itemdef)
 	end
 	itemdef.name = name
 
+	-- default description to item name
+	itemdef.description = itemdef.description or name
+	-- default short_description to first line of description
+	itemdef.short_description = itemdef.short_description or
+		itemdef.description:gsub("\n.*","")
+
 	-- Apply defaults and add to registered_* table
 	if itemdef.type == "node" then
 		-- Use the nodebox as selection box if it's not set manually

doc/lua_api.txt

@@ -2054,6 +2054,8 @@ Some of the values in the key-value store are handled specially:
 
 * `description`: Set the item stack's description. Defaults to
   `idef.description`.
+* `short_description`: Set the item stack's short description. Defaults
+   to `idef.short_description`.
 * `color`: A `ColorString`, which sets the stack's color.
 * `palette_index`: If the item has a palette, this is used to get the
   current color from the palette.
@@ -5994,6 +5996,8 @@ an itemstring, a table or `nil`.
   stack).
 * `set_metadata(metadata)`: (DEPRECATED) Returns true.
 * `get_description()`: returns the description shown in inventory list tooltips.
+* `get_short_description()`: returns the short description.
+    * Unlike the description, this does not include new lines.
 * `clear()`: removes all items from the stack, making it empty.
 * `replace(item)`: replace the contents of this stack.
     * `item` can also be an itemstring or table.
@@ -7096,6 +7100,12 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
 
     {
         description = "Steel Axe",
+        -- Can contain new lines. "\n" has to be used as new line character.
+        -- Defaults to the item's name.
+
+        short_description = "Steel Axe",
+        -- Must not contain new lines.
+        -- Defaults to the first line of description.
 
         groups = {},
         -- key = name, value = rating; rating = 1..3.

games/devtest/mods/unittests/init.lua

@@ -5,10 +5,12 @@ dofile(modpath .. "/random.lua")
 dofile(modpath .. "/player.lua")
 dofile(modpath .. "/crafting_prepare.lua")
 dofile(modpath .. "/crafting.lua")
+dofile(modpath .. "/itemdescription.lua")
 
 if minetest.settings:get_bool("devtest_unittests_autostart", false) then
 	unittests.test_random()
 	unittests.test_crafting()
+	unittests.test_short_desc()
 	minetest.register_on_joinplayer(function(player)
 		unittests.test_player(player)
 	end)

games/devtest/mods/unittests/itemdescription.lua

@@ -0,0 +1,44 @@
+local full_description = "Colorful Pickaxe\nThe best pick."
+minetest.register_tool("unittests:colorful_pick", {
+	description = full_description,
+	inventory_image = "basetools_mesepick.png",
+	tool_capabilities = {
+		full_punch_interval = 1.0,
+		max_drop_level=3,
+		groupcaps={
+			cracky={times={[1]=2.0, [2]=1.0, [3]=0.5}, uses=20, maxlevel=3},
+			crumbly={times={[1]=2.0, [2]=1.0, [3]=0.5}, uses=20, maxlevel=3},
+			snappy={times={[1]=2.0, [2]=1.0, [3]=0.5}, uses=20, maxlevel=3}
+		},
+		damage_groups = {fleshy=4},
+	},
+})
+
+minetest.register_chatcommand("item_description", {
+	param = "",
+	description = "Show the short and full description of the wielded item.",
+	func = function(name)
+		local player = minetest.get_player_by_name(name)
+		local item = player:get_wielded_item()
+		return true, string.format("short_description: %s\ndescription: %s",
+				item:get_short_description(), item:get_description())
+	end
+})
+
+function unittests.test_short_desc()
+	local stack = ItemStack("unittests:colorful_pick")
+	assert(stack:get_short_description() == "Colorful Pickaxe")
+	assert(stack:get_short_description() == minetest.registered_items["unittests:colorful_pick"].short_description)
+	assert(stack:get_description() == full_description)
+	assert(stack:get_description() == minetest.registered_items["unittests:colorful_pick"].description)
+
+	stack:get_meta():set_string("description", "Hello World")
+	assert(stack:get_short_description() == "Colorful Pickaxe")
+	assert(stack:get_description() == "Hello World")
+
+	stack:get_meta():set_string("short_description", "Foo Bar")
+	assert(stack:get_short_description() == "Foo Bar")
+	assert(stack:get_description() == "Hello World")
+
+	return true
+end

src/inventory.cpp

@@ -258,6 +258,20 @@ std::string ItemStack::getDescription(IItemDefManager *itemdef) const
 	return desc.empty() ? name : desc;
 }
 
+std::string ItemStack::getShortDescription(IItemDefManager *itemdef) const
+{
+	std::string desc = metadata.getString("short_description");
+	if (desc.empty())
+		desc = getDefinition(itemdef).short_description;
+	if (!desc.empty())
+		return desc;
+	// no short_description because of old server version or modified builtin
+	// return first line of description
+	std::stringstream sstr(getDescription(itemdef));
+	std::getline(sstr, desc, '\n');
+	return desc;
+}
+
 
 ItemStack ItemStack::addItem(ItemStack newitem, IItemDefManager *itemdef)
 {

src/inventory.h

@@ -49,6 +49,7 @@ struct ItemStack
 	std::string getItemString(bool include_meta = true) const;
 	// Returns the tooltip
 	std::string getDescription(IItemDefManager *itemdef) const;
+	std::string getShortDescription(IItemDefManager *itemdef) const;
 
 	/*
 		Quantity methods

src/itemdef.cpp

@@ -62,6 +62,7 @@ ItemDefinition& ItemDefinition::operator=(const ItemDefinition &def)
 	type = def.type;
 	name = def.name;
 	description = def.description;
+	short_description = def.short_description;
 	inventory_image = def.inventory_image;
 	inventory_overlay = def.inventory_overlay;
 	wield_image = def.wield_image;
@@ -102,6 +103,7 @@ void ItemDefinition::reset()
 	type = ITEM_NONE;
 	name = "";
 	description = "";
+	short_description = "";
 	inventory_image = "";
 	inventory_overlay = "";
 	wield_image = "";
@@ -162,6 +164,8 @@ void ItemDefinition::serialize(std::ostream &os, u16 protocol_version) const
 	writeARGB8(os, color);
 	os << serializeString16(inventory_overlay);
 	os << serializeString16(wield_overlay);
+
+	os << serializeString16(short_description);
 }
 
 void ItemDefinition::deSerialize(std::istream &is)
@@ -213,8 +217,9 @@ void ItemDefinition::deSerialize(std::istream &is)
 
 	// If you add anything here, insert it primarily inside the try-catch
 	// block to not need to increase the version.
-	//try {
-	//} catch(SerializationError &e) {};
+	try {
+		short_description = deSerializeString16(is);
+	} catch(SerializationError &e) {};
 }
 
 

src/itemdef.h

@@ -56,6 +56,7 @@ struct ItemDefinition
 	ItemType type;
 	std::string name; // "" = hand
 	std::string description; // Shown in tooltip.
+	std::string short_description;
 
 	/*
 		Visual properties

src/script/common/c_content.cpp

@@ -56,6 +56,7 @@ void read_item_definition(lua_State* L, int index,
 			es_ItemType, ITEM_NONE);
 	getstringfield(L, index, "name", def.name);
 	getstringfield(L, index, "description", def.description);
+	getstringfield(L, index, "short_description", def.short_description);
 	getstringfield(L, index, "inventory_image", def.inventory_image);
 	getstringfield(L, index, "inventory_overlay", def.inventory_overlay);
 	getstringfield(L, index, "wield_image", def.wield_image);
@@ -142,6 +143,8 @@ void push_item_definition_full(lua_State *L, const ItemDefinition &i)
 	lua_setfield(L, -2, "name");
 	lua_pushstring(L, i.description.c_str());
 	lua_setfield(L, -2, "description");
+	lua_pushstring(L, i.short_description.c_str());
+	lua_setfield(L, -2, "short_description");
 	lua_pushstring(L, type.c_str());
 	lua_setfield(L, -2, "type");
 	lua_pushstring(L, i.inventory_image.c_str());

src/script/lua_api/l_item.cpp

@@ -193,6 +193,16 @@ int LuaItemStack::l_get_description(lua_State *L)
 	return 1;
 }
 
+// get_short_description(self)
+int LuaItemStack::l_get_short_description(lua_State *L)
+{
+	NO_MAP_LOCK_REQUIRED;
+	LuaItemStack *o = checkobject(L, 1);
+	std::string desc = o->m_stack.getShortDescription(getGameDef(L)->idef());
+	lua_pushstring(L, desc.c_str());
+	return 1;
+}
+
 // clear(self) -> true
 int LuaItemStack::l_clear(lua_State *L)
 {
@@ -493,6 +503,7 @@ const luaL_Reg LuaItemStack::methods[] = {
 	luamethod(LuaItemStack, get_metadata),
 	luamethod(LuaItemStack, set_metadata),
 	luamethod(LuaItemStack, get_description),
+	luamethod(LuaItemStack, get_short_description),
 	luamethod(LuaItemStack, clear),
 	luamethod(LuaItemStack, replace),
 	luamethod(LuaItemStack, to_string),

src/script/lua_api/l_item.h

@@ -72,6 +72,9 @@ class LuaItemStack : public ModApiBase {
 	// get_description(self)
 	static int l_get_description(lua_State *L);
 
+	// get_short_description(self)
+	static int l_get_short_description(lua_State *L);
+
 	// clear(self) -> true
 	static int l_clear(lua_State *L);