minetest_doc_example/doc_items.lua

--[[ This is the doc_items example.
This example shows how to add help texts to items and how to use
other frequently-used features of doc_items.
]]

--[[ IMPORTANT REMINDER: doc_items mod will automatically generate help
entries for all items (a few exceptions apply) without your intervention.
doc_items already extracts a lot of item definition automatically.
The API is mainly concernd about enhancing the existing item entries.

Hint: When using this example, use the `/help_reveal`
chat command to reveal all item entries (for testing) ]]

--[[ HELP TEXTS ]]

-- For nontrivial items, you typically want to use the _doc_items_* fields
minetest.register_craftitem("doc_example:item1", {
	description = "doc_example test item 1",
	-- This is the typical way to add extended item descriptions.
	_doc_items_longdesc = "This is an useless example item. It does nothing.",
	-- This simple item is self-explanatory, so we can omit _doc_items_usagehelp
	-- For more fields, see API.md of doc_items

	-- Just an example group
	group = { example = 1 },
})

-- These are just more example items which we use for the factoids later
minetest.register_craftitem("doc_example:item2", {
	description = "doc_example test item 2",
	group = { example = 2 },
})

minetest.register_craftitem("doc_example:item3", {
	description = "doc_example test item 3",
	group = { example = 25 },
})

minetest.register_tool("doc_example:tool", {
	description = "doc_example chat tool",
	_doc_items_longdesc = "This tool is able to write something into the chat.",
	-- This tool has an unique non-standard use (i.e. not mining, not melee combat, etc.), so we should add this field as well
	-- Read API.md of doc_items for guidelines to write good help texts
	_doc_items_usagehelp = "Punch to send a chat message.",
	-- The tool entry will be visible for everyone at start
	_doc_items_hidden = false,
	on_punch = function()
		minetest.chat_send_all("The doc_example chat tool has been used!")
	end,
})

--[[ FACTOIDS
	Reminder: A factoid is an automatically generated text based on the item definition.
	This section will demonstrate the use of factoids
]]

-- This adds an automatically generated text for all items which are a member of the example group
doc.sub.items.register_factoid("craftitems", "groups", function(category_id, def)
	if def.groups.example then
		return string.format("Example factoid: This item is member of the example group at rating %d.", def.groups.example)
	else
		return ""
	end
end)

-- This factoid adds the drawtype for nodes
doc.sub.items.register_factoid("nodes", "misc", function(category_id, def)
	return string.format("Example factoid: This item has the drawtype “%s”.", def.drawtype)
end)


--[[ USING ENTRY ALIASES
	Sometimes, mods register multiple items for basically the same thing in different “states”.
	One example is the furnace from Minetest Game (default:furnace and default:furnace_active).
	If the node in all “states” is similar enough, you might consider to suppress the entries
	of some of the entries in order to concentrate information on a single entry. If you do this, you
	also have to register aliases since the lookup tool will stop working on nodes with suppressed
	entries.
	Suppressing entries may also be useful to combine large lists of similar items, but be careful
	not to overdo it and throw away potentionally valuable information in the process.

	The following code shows two nodes which changes its textures when punched.
	For the player, doc_example:node2 is basically the same as doc_example:node1, only with a
	different textures. Only one entry is created for both nodes.
]]
-- Node for the first “state”. This no
minetest.register_node("doc_example:node1", {
	description = "doc_example test node",
	_doc_items_longdesc = "When rightclicked, the textures of this block change.",
	tiles = {"doc_example_1.png"},
	on_rightclick = function(pos, node, clicker, itemstack, pointed_thing)
		minetest.set_node(pos, {name="doc_example:node2"})
	end,
	groups = {dig_immediate=2},
})

-- Node for the second “state”. No entry will be created for this.
minetest.register_node("doc_example:node2", {
	description = "doc_example test node",
	-- Suppresses the entry
	_doc_items_create_entry = false,
	-- Note that we also do not add _doc_items_longdesc or similar fields,
	-- since these fiel
	tiles = {"doc_example_2.png"},
	on_rightclick = function(pos, node, clicker, itemstack, pointed_thing)
		minetest.set_node(pos, {name="doc_example:node1"})
	end,
	groups = {dig_immediate=2, not_in_creative_inventory=1},
	drop = "doc_example:node1",
})

--[[ Register an alias to make sure the lookup tool still works.
If this is NOT done, the lookup tool will fail when it is
sed on doc_example:node2. ]]
doc.add_entry_alias("nodes", "doc_example:node1", "doc_example:node2")

-- Another example of this concept in action be seen in the mod “doc_identifier”.