Lua bindings to get current crouch amount or set an override

Author: Causeless

CHANGELOG.md

@@ -88,6 +88,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - New `AHuman` INI and Lua (R/W) property `MaxCrouchRotation`, which determines how much the actor will rotate when ducking to avoid low ceilings above them. This can be set to 0 to never duck. Defaults to a quarter of Pi * 1.25 (roughly 56 degrees).  
 
+- New `AHuman` Lua (R/W) property `CrouchAmountOverride`, which enforces that the actor crouch a certain amount, where 0 means fully standing and 1 is fully crouching. This override can be disabled by setting it to -1.0.  
+
+- New `AHuman` Lua (R) property `CrouchAmount`, which returns how much the actor is crouching, where 0 means fully standing and 1 is fully crouching.
+
 - New `MOPixel` INI and Lua (R/W) property `Staininess`, which defines how likely a pixel is to stain a surface when it collides with it. Staining a surface changes that surface's `Color` to that of this `MOPixel`, without changing the underlying material. Value can be between 0 and 1. Defaults to 0 (never stain).  
 
 - New `Activity` INI and Lua (R/W) property `AllowsUserSaving`, which can be used to enable/disable manual user saving/loading. This defaults to true for all `GAScripted` with an `OnSave()` function, but false otherwise. Lua `ActivityMan::SaveGame()` function now forces a save even if `AllowsUserSaving` is disabled. This allows mods and scripted gamemodes to handle saving in their own way (for example, only allowing saving at set points).  

Entities/AHuman.cpp

@@ -67,6 +67,7 @@ void AHuman::Clear()
     m_ProneTimer.Reset();
 	m_MaxWalkPathCrouchShift = 6.0F;
 	m_MaxCrouchRotation = c_QuarterPI * 1.25F;
+	m_CrouchAmountOverride = -1.0F;
     for (int i = 0; i < MOVEMENTSTATECOUNT; ++i) {
         m_Paths[FGROUND][i].Reset();
         m_Paths[BGROUND][i].Reset();
@@ -1726,27 +1727,33 @@ void AHuman::UpdateWalkAngle(AHuman::Layer whichLayer) {
 
 void AHuman::UpdateCrouching() {
 	if (!m_Controller.IsState(BODY_JUMP) && m_pHead) {
-		// Cast a ray above our head to either side to determine whether we need to crouch
-		float desiredCrouchHeadRoom = std::floor(m_pHead->GetRadius() + 2.0f);
-		float toPredicted = std::floor(m_Vel.m_X * m_pHead->GetRadius()); // Check where we'll be a second from now
-		Vector hitPosStart = (m_pHead->GetPos() + Vector(0.0F, m_SpriteRadius * 0.5F)).Floor();
-		Vector hitPosPredictedStart = (m_pHead->GetPos() + Vector(toPredicted, m_SpriteRadius * 0.5F)).Floor();
-		Vector hitPos, hitPosPredicted;
-		g_SceneMan.CastStrengthRay(hitPosStart, Vector(0.0F, -desiredCrouchHeadRoom + m_SpriteRadius * -0.5F), 1.0F, hitPos, 0, g_MaterialGrass);
-		g_SceneMan.CastStrengthRay(hitPosPredictedStart, Vector(0.0F, -desiredCrouchHeadRoom + m_SpriteRadius * -0.5F), 1.0F, hitPosPredicted, 0, g_MaterialGrass);
-
-		// Don't do it if we're already hitting, we're probably in a weird spot
-		if (hitPosStart.m_Y - hitPos.m_Y <= 2.0F) {
-			hitPos.m_Y = 0.0F;
-		}
+		float walkPathYOffset = 0.0F;
+		if (m_CrouchAmountOverride == -1.0F) {
+			// Cast a ray above our head to either side to determine whether we need to crouch
+			float desiredCrouchHeadRoom = std::floor(m_pHead->GetRadius() + 2.0f);
+			float toPredicted = std::floor(m_Vel.m_X * m_pHead->GetRadius()); // Check where we'll be a second from now
+			Vector hitPosStart = (m_pHead->GetPos() + Vector(0.0F, m_SpriteRadius * 0.5F)).Floor();
+			Vector hitPosPredictedStart = (m_pHead->GetPos() + Vector(toPredicted, m_SpriteRadius * 0.5F)).Floor();
+			Vector hitPos, hitPosPredicted;
+			g_SceneMan.CastStrengthRay(hitPosStart, Vector(0.0F, -desiredCrouchHeadRoom + m_SpriteRadius * -0.5F), 1.0F, hitPos, 0, g_MaterialGrass);
+			g_SceneMan.CastStrengthRay(hitPosPredictedStart, Vector(0.0F, -desiredCrouchHeadRoom + m_SpriteRadius * -0.5F), 1.0F, hitPosPredicted, 0, g_MaterialGrass);
+
+			// Don't do it if we're already hitting, we're probably in a weird spot
+			if (hitPosStart.m_Y - hitPos.m_Y <= 2.0F) {
+				hitPos.m_Y = 0.0F;
+			}
 
-		if (hitPosPredictedStart.m_Y - hitPosPredicted.m_Y <= 2.0F) {
-			hitPosPredicted.m_Y = 0.0F;
+			if (hitPosPredictedStart.m_Y - hitPosPredicted.m_Y <= 2.0F) {
+				hitPosPredicted.m_Y = 0.0F;
+			}
+
+			float headroom = m_pHead->GetPos().m_Y - std::max(hitPos.m_Y, hitPosPredicted.m_Y);
+			float adjust = desiredCrouchHeadRoom - headroom;
+			walkPathYOffset = std::clamp(LERP(0.0F, 1.0F, -m_WalkPathOffset.m_Y, adjust, 0.3F), 0.0F, m_MaxWalkPathCrouchShift);
+		} else {
+			walkPathYOffset = m_CrouchAmountOverride * m_MaxWalkPathCrouchShift;
 		}
 
-		float headroom = m_pHead->GetPos().m_Y - std::max(hitPos.m_Y, hitPosPredicted.m_Y);
-		float adjust = desiredCrouchHeadRoom - headroom;
-		float walkPathYOffset = std::clamp(LERP(0.0F, 1.0F, -m_WalkPathOffset.m_Y, adjust, 0.3F), 0.0F, m_MaxWalkPathCrouchShift);
 		m_WalkPathOffset.m_Y = -walkPathYOffset;
 
 		// If crouching, move at reduced speed

Entities/AHuman.h

@@ -892,6 +892,24 @@ DefaultPieMenuNameGetter("Default Human Pie Menu");
 	/// <param name="newValue">The new value for this AHuman's max crouch rotation adjustment.</param>
 	void SetMaxCrouchRotation(float newValue) { m_MaxCrouchRotation = newValue; }
 
+    /// <summary>
+	/// Gets this AHuman's current crouch amount. 0.0 == fully standing, 1.0 == fully crouched.
+	/// </summary>
+	/// <returns>This AHuman's current crouch amount.</returns>
+    float GetCrouchAmount() const { return (m_WalkPathOffset.m_Y * -1.0F) / m_MaxWalkPathCrouchShift; }
+
+    /// <summary>
+	/// Gets this AHuman's current crouch amount override. 0.0 == fully standing, 1.0 == fully crouched, -1 == no override.
+	/// </summary>
+	/// <returns>This AHuman's current crouch amount override.</returns>
+    float GetCrouchAmountOverride() const { return m_CrouchAmountOverride; }
+
+    /// <summary>
+	/// Sets this AHuman's current crouch amount override.
+	/// </summary>
+	/// <param name="newValue">The new value for this AHuman's current crouch amount override.</param>
+    void SetCrouchAmountOverride(float newValue) { m_CrouchAmountOverride = newValue; }
+
 	/// <summary>
 	/// Gets this AHuman's stride sound. Ownership is NOT transferred!
 	/// </summary>
@@ -968,6 +986,8 @@ DefaultPieMenuNameGetter("Default Human Pie Menu");
     float m_MaxWalkPathCrouchShift;
     // The maximum amount we will duck our head down to avoid obstacles above us.
     float m_MaxCrouchRotation;
+    // The script-set forced crouching amount. 0.0 == fully standing, 1.0 == fully crouched, -1 == no override.
+    float m_CrouchAmountOverride;
     // Limb paths for different movement states.
     // [0] is for the foreground limbs, and [1] is for BG.
     LimbPath m_Paths[2][MOVEMENTSTATECOUNT];

Lua/LuaBindingsEntities.cpp

@@ -462,6 +462,8 @@ namespace RTE {
 		.property("BGFoot", &AHuman::GetBGFoot, &LuaAdaptersPropertyOwnershipSafetyFaker::AHumanSetBGFoot)
 		.property("MaxWalkPathCrouchShift", &AHuman::GetMaxWalkPathCrouchShift, &AHuman::SetMaxWalkPathCrouchShift)
 		.property("MaxCrouchRotation", &AHuman::GetMaxCrouchRotation, &AHuman::SetMaxCrouchRotation)
+		.property("CrouchAmount", &AHuman::GetCrouchAmount)
+		.property("CrouchAmountOverride", &AHuman::GetCrouchAmountOverride, &AHuman::SetCrouchAmountOverride)
 		.property("StrideSound", &AHuman::GetStrideSound, &LuaAdaptersPropertyOwnershipSafetyFaker::AHumanSetStrideSound)
 		.property("UpperBodyState", &AHuman::GetUpperBodyState, &AHuman::SetUpperBodyState)
 		.property("MovementState", &AHuman::GetMovementState, &AHuman::SetMovementState)