Add an api function for destroying items.

LUA_API.rst

@@ -999,6 +999,10 @@ Items module
 
   Move the item to the unit inventory. Returns *false* if impossible.
 
+* ``dfhack.items.remove(item[, no_uncat])``
+
+  Removes the item, and marks it for garbage collection unless ``no_uncat`` is true.
+
 * ``dfhack.items.makeProjectile(item)``
 
   Turns the item into a projectile, and returns the new object, or *nil* if impossible.

Lua API.html

@@ -1213,6 +1213,9 @@ Returns <em>false</em> in case of error.</p>
 <li><p class="first"><tt class="docutils literal">dfhack.items.moveToInventory(item,unit,use_mode,body_part)</tt></p>
 <p>Move the item to the unit inventory. Returns <em>false</em> if impossible.</p>
 </li>
+<li><p class="first"><tt class="docutils literal">dfhack.items.remove(item[, no_uncat])</tt></p>
+<p>Removes the item, and marks it for garbage collection unless <tt class="docutils literal">no_uncat</tt> is true.</p>
+</li>
 <li><p class="first"><tt class="docutils literal">dfhack.items.makeProjectile(item)</tt></p>
 <p>Turns the item into a projectile, and returns the new object, or <em>nil</em> if impossible.</p>
 </li>

library/LuaApi.cpp

@@ -886,6 +886,12 @@ static bool items_moveToInventory
     return Items::moveToInventory(mc, item, unit, mode, body_part);
 }
 
+static bool items_remove(df::item *item, bool no_uncat)
+{
+    MapExtras::MapCache mc;
+    return Items::remove(mc, item, no_uncat);
+}
+
 static df::proj_itemst *items_makeProjectile(df::item *item)
 {
     MapExtras::MapCache mc;
@@ -904,6 +910,7 @@ static const LuaWrapper::FunctionReg dfhack_items_module[] = {
     WRAPN(moveToBuilding, items_moveToBuilding),
     WRAPN(moveToInventory, items_moveToInventory),
     WRAPN(makeProjectile, items_makeProjectile),
+    WRAPN(remove, items_remove),
     { NULL, NULL }
 };
 

library/include/modules/Items.h

@@ -157,6 +157,9 @@ DFHACK_EXPORT bool moveToBuilding(MapExtras::MapCache &mc, df::item *item, df::b
 DFHACK_EXPORT bool moveToInventory(MapExtras::MapCache &mc, df::item *item, df::unit *unit,
     df::unit_inventory_item::T_mode mode = df::unit_inventory_item::Carried, int body_part = -1);
 
+/// Makes the item removed and marked for garbage collection
+DFHACK_EXPORT bool remove(MapExtras::MapCache &mc, df::item *item, bool no_uncat = false);
+
 /// Detaches the items from its current location and turns it into a projectile
 DFHACK_EXPORT df::proj_itemst *makeProjectile(MapExtras::MapCache &mc, df::item *item);
 }

library/modules/Items.cpp

@@ -730,6 +730,18 @@ static bool detachItem(MapExtras::MapCache &mc, df::item *item)
         item->flags.bits.in_inventory = false;
         return true;
     }
+    else if (item->flags.bits.removed)
+    {
+        item->flags.bits.removed = false;
+
+        if (item->flags.bits.garbage_collect)
+        {
+            item->flags.bits.garbage_collect = false;
+            item->categorize(true);
+        }
+
+        return true;
+    }
     else
         return false;
 }
@@ -871,6 +883,26 @@ bool DFHack::Items::moveToInventory(
     return true;
 }
 
+bool Items::remove(MapExtras::MapCache &mc, df::item *item, bool no_uncat)
+{
+    CHECK_NULL_POINTER(item);
+
+    auto pos = getPosition(item);
+
+    if (!detachItem(mc, item))
+        return false;
+
+    if (pos.isValid())
+        item->pos = pos;
+
+    if (!no_uncat)
+        item->uncategorize();
+
+    item->flags.bits.removed = true;
+    item->flags.bits.garbage_collect = !no_uncat;
+    return true;
+}
+
 df::proj_itemst *Items::makeProjectile(MapExtras::MapCache &mc, df::item *item)
 {
     CHECK_NULL_POINTER(item);