Add improvements

- Fix issues with frame calcs by verifying frame counts
- Add animation playback rate customization

Author: Starkku

docs/Fixed-or-Improved-Logics.md

@@ -1007,6 +1007,7 @@ ConsideredVehicle=  ; boolean
 - By default building `TurretAnim(Damaged)` with `TurretAnimIsVoxel=false` only displays one frame per each of the 32 facings. This can now be increased and there are additional animations available for low power state and firing weapons.
   - The frames in the .shp file should be in the order: `IdleFrames`, `LowPowerIdleFrames`, `FiringFrames`, `LowPowerFiringFrames`, animations with frame count set to 0 will be skipped / ignored.
   - Note that `FiringFrames` starts playing when attacking and weapon can fire, it will not stop firing of weapon until it has finished playing nor will anything prevent it from looping multiple times if weapon firing is blocked by [delayed firing](New-or-Enhanced-Logics.md#delayed-firing) for longer than there are frames for. Matching delayed firing duration with firing frame count can be used to make pre-firing animation.
+  - `TurretAnim.IdleRate` and `TurretAnim.FiringRate` can be used to customize animation frame playback rate for idle and firing frames respectively.
 
 In `rulesmd.ini`:
 ```ini
@@ -1015,6 +1016,8 @@ TurretAnim.IdleFrames=1            ; integer
 TurretAnim.LowPowerIdleFrames=0    ; integer
 TurretAnim.FiringFrames=0          ; integer
 TurretAnim.LowPowerFiringFrames=0  ; integer
+TurretAnim.IdleRate=1              ; integer, game frames
+TurretAnim.FiringRate=1            ; integer, game frames
 ```
 
 ### Custom exit cell for infantry factory

src/Ext/Building/Body.cpp

@@ -475,13 +475,15 @@ int BuildingExt::GetTurretFrame(BuildingClass* pThis)
 
 	int framesPerFacing = pTypeExt->TurretAnim_IdleFrames;
 	int baseOffset = offsetIdle;
+	bool hasFiringFrames = false;
 
 	if (isLowPower)
 	{
-		if (isFiring)
+		if (isFiring && pTypeExt->TurretAnim_LowPowerFiringFrames > 0)
 		{
 			framesPerFacing = pTypeExt->TurretAnim_LowPowerFiringFrames;
 			baseOffset = offsetLowPowerFiring;
+			hasFiringFrames = true;
 		}
 		else if (pTypeExt->TurretAnim_LowPowerIdleFrames > 0)
 		{
@@ -491,32 +493,49 @@ int BuildingExt::GetTurretFrame(BuildingClass* pThis)
 	}
 	else
 	{
-		if (isFiring)
+		if (isFiring && pTypeExt->TurretAnim_FiringFrames > 0)
 		{
 			framesPerFacing = pTypeExt->TurretAnim_FiringFrames;
 			baseOffset = offsetFiring;
+			hasFiringFrames = true;
 		}
 	}
 
 	int animFrame = 0;
 
-	if (framesPerFacing > 1)
+	if (isFiring && hasFiringFrames)
 	{
-		if (isFiring)
+		animFrame = pExt->TurretAnimFiringFrame;
+		pExt->TurretAnimRateTick++;
+
+		if (pExt->TurretAnimRateTick >= pTypeExt->TurretAnim_FiringRate)
 		{
-			animFrame = pExt->TurretAnimFiringFrame;
+			pExt->TurretAnimRateTick = 0;
 			pExt->TurretAnimFiringFrame++;
+		}
 
-			if (pExt->TurretAnimFiringFrame >= framesPerFacing)
-			{
-				pExt->TurretAnimFiringFrame = -1;
-				pExt->TurretAnimIdleFrame = 0; // Reset idle anim frame.
-			}
+		if (pExt->TurretAnimFiringFrame >= framesPerFacing)
+		{
+			pExt->TurretAnimFiringFrame = -1;
+			pExt->TurretAnimIdleFrame = 0; // Reset idle anim frame.
+			pExt->TurretAnimRateTick = 0;
 		}
-		else
+	}
+	else if (framesPerFacing > 1)
+	{
+		animFrame = pExt->TurretAnimIdleFrame;
+		pExt->TurretAnimRateTick++;
+
+		if (pExt->TurretAnimRateTick >= pTypeExt->TurretAnim_IdleRate)
+		{
+			pExt->TurretAnimRateTick = 0;
+			pExt->TurretAnimIdleFrame++;
+		}
+
+		if (pExt->TurretAnimIdleFrame >= framesPerFacing)
 		{
-			animFrame = pExt->TurretAnimIdleFrame;
-			++pExt->TurretAnimIdleFrame %= framesPerFacing;
+			pExt->TurretAnimIdleFrame = 0;
+			pExt->TurretAnimRateTick = 0;
 		}
 	}
 
@@ -544,6 +563,7 @@ void BuildingExt::ExtData::Serialize(T& Stm)
 		.Process(this->CurrentEMPulseSW)
 		.Process(this->TurretAnimIdleFrame)
 		.Process(this->TurretAnimFiringFrame)
+		.Process(this->TurretAnimRateTick)
 		//.Process(this->IsFiringNow) It is set and reset within a same function.
 		;
 }
@@ -575,7 +595,7 @@ bool BuildingExt::SaveGlobals(PhobosStreamWriter& Stm)
 // =============================
 // container
 
-BuildingExt::ExtContainer::ExtContainer() : Container("BuildingClass") { }
+BuildingExt::ExtContainer::ExtContainer() : Container("BuildingClass") {}
 
 BuildingExt::ExtContainer::~ExtContainer() = default;
 

src/Ext/Building/Body.h

@@ -29,6 +29,7 @@ class BuildingExt
 		bool IsFiringNow;
 		int TurretAnimIdleFrame;
 		int TurretAnimFiringFrame;
+		int TurretAnimRateTick;
 
 		ExtData(BuildingClass* OwnerObject) : Extension<BuildingClass>(OwnerObject)
 			, TypeExtData { nullptr }
@@ -46,6 +47,7 @@ class BuildingExt
 			, IsFiringNow { false }
 			, TurretAnimIdleFrame { 0 }
 			, TurretAnimFiringFrame { -1 }
+			, TurretAnimRateTick { 0 }
 		{ }
 
 		void DisplayIncomeString();

src/Ext/Building/Hooks.cpp

@@ -1121,7 +1121,10 @@ DEFINE_HOOK(0x44B6C7, BuildingClass_Mission_Attack_TurretAnim, 0x6)
 			bool firingFrames = isLowPower ? pTypeExt->TurretAnim_LowPowerFiringFrames : pTypeExt->TurretAnim_FiringFrames;
 
 			if (firingFrames > 0 && pExt->TurretAnimFiringFrame == -1)
+			{
 				pExt->TurretAnimFiringFrame = 0;
+				pExt->TurretAnimRateTick = 0;
+			}
 		}
 	}
 

src/Ext/BuildingType/Body.cpp

@@ -229,6 +229,8 @@ void BuildingTypeExt::ExtData::LoadFromINIFile(CCINIClass* const pINI)
 	this->TurretAnim_LowPowerIdleFrames.Read(exINI, pSection, "TurretAnim.LowPowerIdleFrames");
 	this->TurretAnim_FiringFrames.Read(exINI, pSection, "TurretAnim.FiringFrames");
 	this->TurretAnim_LowPowerFiringFrames.Read(exINI, pSection, "TurretAnim.LowPowerFiringFrames");
+	this->TurretAnim_IdleRate.Read(exINI, pSection, "TurretAnim.IdleRate");
+	this->TurretAnim_FiringRate.Read(exINI, pSection, "TurretAnim.FiringRate");
 
 	if (pThis->NumberOfDocks > 0)
 	{
@@ -389,6 +391,8 @@ void BuildingTypeExt::ExtData::Serialize(T& Stm)
 	    .Process(this->TurretAnim_LowPowerIdleFrames)
 	    .Process(this->TurretAnim_FiringFrames)
 	    .Process(this->TurretAnim_LowPowerFiringFrames)
+		.Process(this->TurretAnim_IdleRate)
+		.Process(this->TurretAnim_FiringFrames)
 
 		// Ares 0.2
 		.Process(this->CloningFacility)

src/Ext/BuildingType/Body.h

@@ -108,6 +108,8 @@ class BuildingTypeExt
 		Valueable<int> TurretAnim_LowPowerIdleFrames;
 		Valueable<int> TurretAnim_FiringFrames;
 		Valueable<int> TurretAnim_LowPowerFiringFrames;
+		Valueable<int> TurretAnim_IdleRate;
+		Valueable<int> TurretAnim_FiringRate;
 
 		// Ares 0.2
 		Valueable<bool> CloningFacility;
@@ -192,6 +194,8 @@ class BuildingTypeExt
 		    , TurretAnim_LowPowerIdleFrames { 0 }
 		    , TurretAnim_FiringFrames { 0 }
 			, TurretAnim_LowPowerFiringFrames { 0 }
+			, TurretAnim_IdleRate { 1 }
+			, TurretAnim_FiringRate { 1 }
 
 			// Ares 0.2
 			, CloningFacility { false }