Bucket: Allow buckets to trigger the on_punch of entities and nodes

The purpose of this is to allow mods to be able to interact (e.g. fill up)
an empty bucket when it is used to punch a node that's not a liquid source
or when punching a custom entity (e.g. milking a cow).

game_api.txt

@@ -19,7 +19,6 @@ Bucket API
 
 The bucket API allows registering new types of buckets for non-default liquids.
 
-
 	bucket.register_liquid(
 		"default:lava_source",   -- name of the source node
 		"default:lava_flowing",  -- name of the flowing node
@@ -32,6 +31,9 @@ The bucket API allows registering new types of buckets for non-default liquids.
 		                         -- Needed to avoid creating holes in sloping rivers.
 	)
 
+The filled bucket item is returned to the player that uses an empty bucket pointing to the given liquid source.
+When punching with an empty bucket pointing to an entity or a non-liquid node, the on_punch of the entity or node will be triggered.
+
 Beds API
 --------
 

mods/bucket/init.lua

@@ -115,8 +115,11 @@ minetest.register_craftitem("bucket:bucket_empty", {
 	stack_max = 99,
 	liquids_pointable = true,
 	on_use = function(itemstack, user, pointed_thing)
-		-- Must be pointing to node
-		if pointed_thing.type ~= "node" then
+		if pointed_thing.type == "object" then
+			pointed_thing.ref:punch(user, 1.0, { full_punch_interval=1.0 }, nil)
+			return user:get_wielded_item()
+		elseif pointed_thing.type ~= "node" then
+			-- do nothing if it's neither object nor node
 			return
 		end
 		-- Check if pointing to a liquid source
@@ -165,6 +168,13 @@ minetest.register_craftitem("bucket:bucket_empty", {
 			end
 
 			return ItemStack(giving_back)
+		else
+			-- non-liquid nodes will have their on_punch triggered
+			local node_def = minetest.registered_nodes[node.name]
+			if node_def then
+				node_def.on_punch(pointed_thing.under, node, user, pointed_thing)
+			end
+			return user:get_wielded_item()
 		end
 	end,
 })