From 7b027f044ea7c1d358b0cba305412a0615133f8c Mon Sep 17 00:00:00 2001
From: teknomunk <teknomunk@protonmail.com>
Date: Sun, 20 Oct 2024 20:47:47 -0500
Subject: [PATCH] Document vl_projectile.replace_with_item_drop

---
 mods/ITEMS/vl_projectile/api.md   | 12 ++++++++++++
 mods/ITEMS/vl_projectile/init.lua | 13 ++++++++++---
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/mods/ITEMS/vl_projectile/api.md b/mods/ITEMS/vl_projectile/api.md
index acbacc0d6..8ba8b9f56 100644
--- a/mods/ITEMS/vl_projectile/api.md
+++ b/mods/ITEMS/vl_projectile/api.md
@@ -57,6 +57,18 @@ Arguments:
   * `owner`: passed thru unmodified
   * `extra`: passed thru unmodified
 
+## `vl_projectile.replace_with_item_drop(projectile_lua_entity, pos, projectile_def)`
+
+Removes the projectile and replaces it with an item entity based on either the entity's `_arrow_item` field or
+the value `self._vl_projectile.item`.
+
+Arguments:
+
+* `projectile_lua_entity`: the lua entity of the projectile to be replaced.
+* `pos`: the position to create the item entity
+* `projectile_def`: The projectile's `_vl_projectile` field. If not provided, it will be
+   extracted from the projectile's lua entity.
+
 ## Custom Projectile Behaviors
 
 The projectile API supports specifying the behaviors that a projectile will exhibit. There are several
diff --git a/mods/ITEMS/vl_projectile/init.lua b/mods/ITEMS/vl_projectile/init.lua
index fead27628..f9dd45f49 100644
--- a/mods/ITEMS/vl_projectile/init.lua
+++ b/mods/ITEMS/vl_projectile/init.lua
@@ -233,8 +233,15 @@ function mod.has_tracer(self, dtime, entity_def, projectile_def)
 	})
 end
 
-function mod.replace_with_item_drop(self, pos, entity_def, projectile_def)
-	local item = self._arrow_item or projectile_def.item
+function mod.replace_with_item_drop(self, pos, projectile_def)
+	local item = self._arrow_item
+
+	if not item then
+		projectile_def = projectile_def or self._vl_projectile
+		if not projectile_def then return end
+
+		item = projectile_def.item
+	end
 
 	if self._collectable and not minetest.is_creative_enabled("") then
 		local item = minetest.add_item(pos, item)
@@ -269,7 +276,7 @@ local function stuck_on_step(self, dtime, entity_def, projectile_def)
 			local node = minetest.get_node(self._stuckin)
 			local node_def = minetest.registered_nodes[node.name]
 			if node_def and node_def.walkable == false then
-				mod.replace_with_item_drop(self, pos, entity_def, projectile_def)
+				mod.replace_with_item_drop(self, pos, projectile_def)
 				return
 			end
 		end