Cargo: Add removeCargoItem Function (#5432)

* Add removeCargoItem function to cargo module

* Fix documentation typos

* Fix header 'public' field

Of course it's a public function, that's the whole point!

* Fix spelling

* Add missing then command

* Work better with objects

* After-test fixes

* Also update wiki

* Overhaul

* Make the event more robust

* Fix logic & shorten docs

addons/cargo/XEH_PREP.hpp

@@ -14,6 +14,7 @@ PREP(moduleMakeLoadable);
 PREP(moduleSettings);
 PREP(onMenuOpen);
 PREP(paradropItem);
+PREP(removeCargoItem);
 PREP(setSize);
 PREP(setSpace);
 PREP(startLoadIn);

addons/cargo/functions/fnc_removeCargoItem.sqf

@@ -0,0 +1,70 @@
+/*
+ * Author: 654wak654
+ * Removes a cargo item from the vehicle.
+ *
+ * Arguments:
+ * 0: Item <STRING> or <OBJECT>
+ * 1: Vehicle <OBJECT>
+ * 2: Amount <NUMBER> (default: 1)
+ *
+ * Return Value:
+ * Number of items removed <NUMBER>
+ *
+ * Example:
+ * ["ACE_Wheel", vehicle, 2] call ace_cargo_fnc_removeCargoItem
+ * [crate_7, truck] call ace_cargo_fnc_removeCargoItem
+ *
+ * Public: Yes
+ */
+#include "script_component.hpp"
+
+params ["_item", "_vehicle", ["_amount", 1]];
+TRACE_3("params",_item,_vehicle,_amount);
+
+private _loaded = _vehicle getVariable [QGVAR(loaded), []];
+
+private _addedSpace = 0;
+private _itemClass = _item;
+private _itemsRemoved = 0;
+
+private _continue = if (_item isEqualType objNull) then {
+    if !(_item in _loaded) exitWith {false};
+    _addedSpace = [_item] call FUNC(getSizeItem);
+    _loaded deleteAt (_loaded find _item);
+    _itemClass = typeOf _item;
+    deleteVehicle _item;
+    _itemsRemoved = 1;
+    true
+} else {
+    {
+        if (_itemsRemoved == _amount) exitWith {};
+
+        if (
+            (_x isEqualType "" && {_x == _item}) || // Check for classname, case-insensitive
+            {_x isEqualType objNull && {typeOf _x isEqualTo _item}}
+        ) then {
+            INC(_itemsRemoved);
+            ADD(_addedSpace,[_x] call FUNC(getSizeItem));
+
+            if (_x isEqualType objNull) then {
+                deleteVehicle _x;
+            };
+            _loaded set [_forEachIndex, nil];
+        };
+    } forEach _loaded;
+
+    FILTER(_loaded,_x != nil);
+    true
+};
+
+if (!_continue) exitWith {0};
+
+_vehicle setVariable [QGVAR(loaded), _loaded, true];
+
+private _space = [_vehicle] call FUNC(getCargoSpaceLeft);
+_vehicle setVariable [QGVAR(space), _space + _addedSpace, true];
+
+// Invoke listenable event
+["ace_cargoRemoved", [_itemClass, _vehicle, _amount, _itemsRemoved]] call CBA_fnc_globalEvent;
+
+_itemsRemoved

docs/wiki/framework/cargo-framework.md

@@ -50,6 +50,7 @@ Event Name | Passed Parameter(s) | Locality | Description
 ---------- | ----------- | ------------------- | --------
 `ace_cargoLoaded` | [_item, _vehicle] | Global | Cargo has been Loaded into vehicle
 `ace_cargoUnloaded` | [_item, _vehicle] | Global | Cargo has been Unloaded from vehicle
+`ace_cargoRemoved` | [_itemClass, _vehicle, _amountRequested, _amountRemoved] | Global | Cargo has been removed (deleted) from vehicle
 
 ## 3. Editor Attributes
 
@@ -141,3 +142,21 @@ Note first arg can be a in-game object or a classname of an object type.
  * Example:
  * [object, vehicle] call ace_cargo_fnc_unloadItem
 ```
+
+### 4.6 Remove/ Delete cargo from vehicle (Added in ACE3 3.11.0)
+
+`ace_cargo_fnc_removeCargoItem`
+
+```cpp
+ * Arguments:
+ * 0: Item <STRING> or <OBJECT>
+ * 1: Vehicle <OBJECT>
+ * 2: Amount <NUMBER> (default: 1)
+ *
+ * Return Value:
+ * Number of items removed <NUMBER>
+ *
+ * Example:
+ * ["ACE_Wheel", vehicle, 2] call ace_cargo_fnc_removeCargoItem
+ * [crate_7, truck] call ace_cargo_fnc_removeCargoItem
+```