Common - Add keybind and function to unload unit's weapon/muzzle (#8735)

* add keybind and function to unload unit's weapon/muzzle

- add keybind and function to unload unit's weapon/muzzle
- requires CBATeam/CBA_A3#1527

* change function name

* rename the file too

* Create common-framework.md

* Set REQUIRED_CBA_VERSION to 3.15.7

* Update required CBA version

Co-authored-by: PabstMirror <pabstmirror@gmail.com>

* Apply suggestions from code review

Co-authored-by: PabstMirror <pabstmirror@gmail.com>

addons/common/XEH_PREP.hpp

@@ -185,6 +185,7 @@ PREP(uniqueElements);
 PREP(uniqueItems);
 PREP(unloadPerson);
 PREP(unloadPersonLocal);
+PREP(unloadUnitWeapon);
 PREP(unmuteUnit);
 PREP(useItem);
 PREP(useMagazine);

addons/common/XEH_postInit.sqf

@@ -539,4 +539,21 @@ GVAR(deviceKeyCurrentIndex) = -1;
 {false},
 [0xC7, [true, false, false]], false] call CBA_fnc_addKeybind;  //SHIFT + Home Key
 
+
+["ACE3 Weapons", QGVAR(unloadWeapon), localize LSTRING(unloadWeapon), {
+    // Conditions:
+    if !([ACE_player, objNull, ["isNotInside"]] call FUNC(canInteractWith)) exitWith {false};
+
+    private _currentWeapon = currentWeapon ACE_player;
+    if !(_currentWeapon != primaryWeapon _unit && {_currentWeapon != handgunWeapon _unit} && {_currentWeapon != secondaryWeapon _unit}) exitWith {false};
+
+    private _currentMuzzle = currentMuzzle ACE_player;
+    private _currentAmmoCount = ACE_player ammo _currentMuzzle;
+    if (_currentAmmoCount < 1) exitWith {false};
+
+    // Statement:
+    [ACE_player, _currentWeapon, _currentMuzzle, _currentAmmoCount, false] call FUNC(unloadUnitWeapon);
+    true
+}, {false}, [19, [false, false, true]], false] call CBA_fnc_addKeybind; //ALT + R Key
+
 GVAR(commonPostInited) = true;

addons/common/functions/fnc_unloadUnitWeapon.sqf

@@ -0,0 +1,87 @@
+#include "script_component.hpp"
+/*
+ * Author: drofseh & Commy2
+ * Unload the magazine from the unit's weapon and attempt to put it in a sensible place.
+ *
+ * Arguments:
+ * 0: Player <OBJECT>
+ * 1: Weapon <STRING>
+ * 2: Muzzle (optional, default: Weapon)<STRING>
+ * 3: Ammo count (optional, default: ammo currentMuzzle Player) <NUMBER>
+ * 4: Skip animation? (optional, default: false) <BOOL>
+ *
+ * Return Value:
+ * None
+ *
+ * Example:
+* [ACE_player, currentWeapon ACE_player, currentMuzzle ACE_player, 23, false] call ace_common_fnc_unloadUnitWeapon
+ *
+ * Public: No
+ */
+
+params ["_unit", "_weapon", ["_muzzle", _weapon], ["_ammoCount", _unit ammo _muzzle ], ["_skipAnim", false]];
+TRACE_5("params",_unit,_weapon,_muzzle,_ammoCount,_skipAnim);
+
+// audiovisual effects
+private _delay = 0;
+if !(_skipAnim) then {
+    _delay = 1.5;
+    private _config = configFile >> "CfgWeapons" >> _weapon;
+    if (_weapon != _muzzle) then {
+        _config = _config >> _muzzle;
+    };
+
+    // get and play animation
+    private _unloadAction = getText (_config >> "ACE_unloadAction");
+
+    if (_unloadAction == "") then {
+        _unloadAction = getText (_config >> "reloadAction");
+    };
+
+    [_unit, _unloadAction, 1] call FUNC(doGesture);
+
+    // get and play sound
+    private _unloadSound = getText (_config >> "ACE_unloadSound");
+
+    if (_unloadSound == "") then {
+        _unloadSound = "A3\Sounds_F\arsenal\weapons\Rifles\Katiba\reload_Katiba.wss";
+        private _unloadSoundArray = getArray (_config >> "reloadMagazineSound");
+
+        // file extention is required for playSound3D
+        if (_unloadSoundArray isNotEqualTo []) then {
+            private _wssTest = format ["%1.wss", _unloadSoundArray select 0];
+            if (fileExists _wssTest) then {
+                _unloadSound = _wssTest;
+            } else {
+                private _wavTest = format ["%1.wav", _unloadSoundArray select 0];
+                if (fileExists _wavTest) then {
+                    _unloadSound = _wavTest;
+                };
+            };
+        };
+    };
+
+    playSound3D [_unloadSound, _unit];
+};
+
+// remove magazine from weapon and add it to inventory
+[{
+    params ["_unit", "_weapon", "_ammoCount"];
+
+    // remove weapon item
+    private _magazineClass = currentMagazine _unit;
+
+    switch true do {
+        case (_weapon == primaryWeapon _unit): {
+            _unit removePrimaryWeaponItem _magazineClass;
+        };
+        case (_weapon == handgunWeapon _unit): {
+            _unit removeHandgunItem _magazineClass;
+        };
+        case (_weapon == secondaryWeapon _unit): {
+            _unit removeSecondaryWeaponItem _magazineClass;
+        };
+    };
+
+    [_unit, _magazineClass, _ammoCount, true] call CBA_fnc_addMagazine;
+}, [_unit, _weapon, _ammoCount], _delay] call CBA_fnc_waitAndExecute;

addons/common/stringtable.xml

@@ -1635,5 +1635,8 @@
             <Chinese>受所在位置影響提升醫療能力</Chinese>
             <Turkish>Konumlar Tedaviyi Hızlandırır</Turkish>
         </Key>
+        <Key ID="STR_ACE_Common_unloadWeapon">
+            <English>Unload Weapon</English>
+        </Key>
     </Package>
 </Project>

addons/main/script_mod.hpp

@@ -11,7 +11,7 @@
 
 // MINIMAL required version for the Mod. Components can specify others..
 #define REQUIRED_VERSION 2.06
-#define REQUIRED_CBA_VERSION {3,15,6}
+#define REQUIRED_CBA_VERSION {3,15,7}
 
 #ifdef COMPONENT_BEAUTIFIED
     #define COMPONENT_NAME QUOTE(ACE3 - COMPONENT_BEAUTIFIED)

docs/wiki/framework/common-framework.md

@@ -0,0 +1,26 @@
+---
+layout: wiki
+title: Common Framework
+description: Notes on ACE3 Common.
+group: framework
+order: 5
+parent: wiki
+mod: ace
+version:
+  major: 3
+  minor: 14
+  patch: 2
+---
+
+## 1. Config Values
+
+### 1.1 `CfgWeapons`
+
+```cpp
+class CfgWeapons {
+    class yourWeaponClass {
+        ACE_unloadAction = "GestureUnloadMyWeaponClass"; // Animation to play when weapon is unloaded with ace_common_fnc_unloadUnitWeapon
+        ACE_unloadSound = "A3\Sounds_F\arsenal\weapons\Rifles\Katiba\reload_Katiba.wss";  // Sound to play when weapon is unloaded with ace_common_fnc_unloadUnitWeapon
+    };
+};
+```