Merge branch 'shield_sheath' into 'master'

Fix shield equip and unequip animations, add docs for shield sheathing feature

See merge request OpenMW/openmw!4936

CHANGELOG.md

@@ -76,6 +76,7 @@
     Bug #8680: Dead ancestor ghosts stop being dust when you rest near them
     Bug #8686: openmw-cs: Crash when smoothing terrain of a not-yet-created cell.
     Bug #8710: Absorb Skill breaks on creatures
+    Bug #8734: Shield sheathing does not work properly
     Feature #2522: Support quick item transfer
     Feature #3740: Gamepad GUI Mode
     Feature #3769: Allow GetSpellEffects on enchantments

apps/openmw/mwmechanics/character.cpp

@@ -1071,25 +1071,19 @@ namespace MWMechanics
 
         std::string_view action = evt.substr(groupname.size() + 2);
         if (action == "equip attach")
-        {
-            if (mUpperBodyState == UpperBodyState::Equipping)
         {
             if (groupname == "shield")
                 mAnimation->showCarriedLeft(true);
-                else
+            else if (mUpperBodyState == UpperBodyState::Equipping)
                 mAnimation->showWeapons(true);
         }
-        }
         else if (action == "unequip detach")
-        {
-            if (mUpperBodyState == UpperBodyState::Unequipping)
         {
             if (groupname == "shield")
                 mAnimation->showCarriedLeft(false);
-                else
+            else if (mUpperBodyState == UpperBodyState::Unequipping)
                 mAnimation->showWeapons(false);
         }
-        }
         else if (action == "chop hit" || action == "slash hit" || action == "thrust hit" || action == "hit")
         {
             int attackType = -1;
@@ -1392,7 +1386,7 @@ namespace MWMechanics
                 // We can not play un-equip animation if weapon changed since last update
                 if (!weaponChanged)
                 {
-                    // Note: we do not disable unequipping animation automatically to avoid body desync
+                    // Note: we do not disable the weapon unequipping animation automatically to avoid body desync
                     weapgroup = getWeaponAnimation(mWeaponType);
                     int unequipMask = MWRender::BlendMask_All;
                     mUpperBodyState = UpperBodyState::Unequipping;
@@ -1401,6 +1395,7 @@ namespace MWMechanics
                         && !(mWeaponType == ESM::Weapon::None && weaptype == ESM::Weapon::Spell))
                     {
                         unequipMask = unequipMask | ~MWRender::BlendMask_LeftArm;
+                        mAnimation->disable("shield");
                         playBlendedAnimation("shield", Priority_Block, MWRender::BlendMask_LeftArm, true, 1.0f,
                             "unequip start", "unequip stop", 0.0f, 0);
                     }
@@ -1458,6 +1453,7 @@ namespace MWMechanics
                             if (useShieldAnims && weaptype != ESM::Weapon::Spell)
                             {
                                 equipMask = equipMask | ~MWRender::BlendMask_LeftArm;
+                                mAnimation->disable("shield");
                                 playBlendedAnimation("shield", Priority_Block, MWRender::BlendMask_LeftArm, true, 1.0f,
                                     "equip start", "equip stop", 0.0f, 0);
                             }

docs/source/reference/modding/extended.rst

@@ -165,6 +165,7 @@ The minimum you need is the ``xbase_anim_sh.nif`` file from the `Weapon Sheathin
 
     [Game]
     weapon sheathing = true
+    use additional anim sources = true
 
 The ``xbase_anim_sh.nif`` contains default placement points for different weapon types.
 That way you'll get Gothic-style weapon sheathing for all biped actors (without quivers and scabbards).
@@ -204,6 +205,28 @@ It is important to make sure the names of empty nodes start with ``"Bip01 "``, o
 An example of a mod which uses this feature is `Weapon Sheathing`_.
 
 
+Shield sheathing support
+------------------------
+
+The minimum you need is the ``xbase_anim_sh.nif`` file from the `Weapon Sheathing`_ mod and this line in your settings.cfg:
+
+.. code-block:: ini
+    :caption: settings.cfg
+
+    [Game]
+    shield sheathing = true
+    use additional anim sources = true
+
+The ``xbase_anim_sh.nif`` contains default placement points for shields (a ``"Bip01 AttachShield"`` node). 
+You also may use meshes with ``_sh`` suffix (with ``Bip01 Sheath`` node) to tweak how particular shield looks in the sheathed mode. A stub sheath means that the shield should be excluded from this feature. 
+When a two-handed weapon is equipped, a shield is hidden when this feature is enabled.
+This feature also supports shield equipping and unequipping animations. It is a ``Shield`` group (with ``Equip Start``, ``Equip Attach``, ``Equip Stop``, ``Unequip Start``, ``Unequip Attach`` and ``Unequip Stop`` keys).
+Note that equip and unequip animation blocks should not overlap each other and weapon equip/unequip animations. 
+Basically, you need to avoid situations when you play an animation block where you need both to attach and detach the shield.
+
+An example of a mod which uses this feature is `Weapon Sheathing`_.
+
+
 Skeleton extensions
 -------------------