[Vanilla Enhancement] Customizable spawn delay of VoxelAnim's TrailerAnim and fix its incorrect position (#1722)

- Fixed the issue of incorrect position of `TrailerAnim` in `VoxelAnim`.

---

- You can now customize the generation interval of VoxelAnim's trailer
animation

In `rulesmd.ini`:
```ini
[SOMEVOXELANIM]       ; VoxelAnimType
Trailer.SpawnDelay=2  ; integer, game frames
```

Author: CrimRecya

CREDITS.md

@@ -491,6 +491,7 @@ This page lists all the individual contributions to the project by their author.
   - Exclusive SuperWeapon Sidebar
   - Fix an issue that the widespread damage caused by detonation on the bridge/ground cannot affect objects on the ground/bridge who are in the opposite case
   - Several new Infotypes, no display in specific status and a new single frame display method
+  - Customizable spawn delay of `VoxelAnim`'s `TrailerAnim` and fix its incorrect position
 - **Ollerus**:
   - Build limit group enhancement
   - Customizable rocker amplitude

docs/Fixed-or-Improved-Logics.md

@@ -233,6 +233,7 @@ This page describes all ingame logics that are fixed or improved in Phobos witho
 - Fixed the issue that the widespread damage caused by detonation on the bridge/ground cannot affect objects on the ground/bridge who are in the opposite case.
 - Fixed the bug that `DamageSelf` and `AllowDamageOnSelf` are ineffective on airforce.
 - Fixed the bug that damaged particle dont disappear after building has repaired by engineer.
+- Fixed the issue of incorrect position of `TrailerAnim` in `VoxelAnim`.
 
 ## Fixes / interactions with other extensions
 
@@ -1793,6 +1794,16 @@ UseWeeds.ReadinessAnimationPercentage=0.9       ; double - when this many weeds
 
 - The INI keys and behaviour is mostly identical to the [equivalent behaviour available to regular animations](#customizable-debris--meteor-impact-and-warhead-detonation-behaviour). Main difference is that the keys must be listed in the VoxelAnim's entry in `rulesmd.ini`, not `artmd.ini`.
 
+### Customizable debris trailer anim spawn delay
+
+- You can now customize the generation interval of VoxelAnim's trailer animation
+
+In `rulesmd.ini`:
+```ini
+[SOMEVOXELANIM]       ; VoxelAnimType
+Trailer.SpawnDelay=2  ; integer, game frames
+```
+
 ## Warheads
 
 ### Allowing damage dealt to firer

docs/Whats-New.md

@@ -394,6 +394,7 @@ New:
 - Targeting limitation for berzerk technos (by TaranDahl)
 - Allowed faking digital display for `InfoType=Health` at disguise (by Ollerus)
 - [Customize limit and sound when engineer repair a building](New-or-Enhanced-Logics.md#engineer-repair-customization) (by NetsuNegi)
+- Customizable debris trailer anim spawn delay (by CrimRecya)
 
 Vanilla fixes:
 - Fixed sidebar not updating queued unit numbers when adding or removing units when the production is on hold (by CrimRecya)
@@ -420,6 +421,7 @@ Vanilla fixes:
 - Fixed the issue that the widespread damage caused by detonation on the bridge/ground cannot affect objects on the ground/bridge who are in the opposite case (by CrimRecya)
 - Fixed the bug that `DamageSelf` and `AllowDamageOnSelf` are ineffective on airforce (by NetsuNegi)
 - Fixed the bug that damaged particle dont disappear after building has repaired by engineer (by NetsuNegi)
+- Fixed the issue of incorrect position of `TrailerAnim` in `VoxelAnim` (by CrimRecya)
 
 Phobos fixes:
 - Fixed the bug that `AllowAirstrike=no` cannot completely prevent air strikes from being launched against it (by NetsuNegi)

src/Ext/VoxelAnim/Body.cpp

@@ -29,7 +29,8 @@ template <typename T>
 void VoxelAnimExt::ExtData::Serialize(T& Stm)
 {
 	Stm
-		.Process(LaserTrails)
+		.Process(this->LaserTrails)
+		.Process(this->TrailerSpawnTimer)
 		;
 }
 

src/Ext/VoxelAnim/Body.h

@@ -25,9 +25,11 @@ class VoxelAnimExt
 	public:
 
 		std::vector<LaserTrailClass> LaserTrails;
+		CDTimerClass TrailerSpawnTimer;
 
 		ExtData(VoxelAnimClass* OwnerObject) : Extension<VoxelAnimClass>(OwnerObject)
 			, LaserTrails()
+			, TrailerSpawnTimer()
 		{ }
 
 		virtual ~ExtData() = default;

src/Ext/VoxelAnim/Hooks.cpp

@@ -41,10 +41,6 @@ DEFINE_HOOK(0x74A027, VoxelAnimClass_AI_Expired, 0x6)
 	GET(int, flag, EAX);
 
 	bool heightFlag = flag & 0xFF;
-
-	if (!pThis || !pThis->Type)
-		return SkipGameCode;
-
 	auto const pType = pThis->Type;
 	auto const pTypeExt = VoxelAnimTypeExt::ExtMap.Find(pType);
 	auto const splashAnims = pTypeExt->SplashAnims.GetElements(RulesClass::Instance->SplashList);
@@ -54,3 +50,26 @@ DEFINE_HOOK(0x74A027, VoxelAnimClass_AI_Expired, 0x6)
 
 	return SkipGameCode;
 }
+
+DEFINE_HOOK(0x74A70E, VoxelAnimClass_AI_Trailer, 0x6)
+{
+	enum { SkipGameCode = 0x74A7AB };
+
+	GET(VoxelAnimClass* const, pThis, EBX);
+
+	const auto pType = pThis->Type;
+
+	if (const auto pAnimType = pType->TrailerAnim)
+	{
+		auto pExt = VoxelAnimExt::ExtMap.Find(pThis);
+
+		if (pExt->TrailerSpawnTimer.Expired())
+		{
+			pExt->TrailerSpawnTimer.Start(VoxelAnimTypeExt::ExtMap.Find(pType)->Trailer_SpawnDelay.Get());
+			auto const pTrailerAnim = GameCreate<AnimClass>(pAnimType, pThis->Location, 1, 1);
+			AnimExt::SetAnimOwnerHouseKind(pTrailerAnim, pThis->OwnerHouse, nullptr, false, true);
+		}
+	}
+
+	return SkipGameCode;
+}

src/Ext/VoxelAnimType/Body.cpp

@@ -16,6 +16,7 @@ void VoxelAnimTypeExt::ExtData::LoadFromINIFile(CCINIClass* pINI)
 	this->WakeAnim.Read(exINI, pID, "WakeAnim");
 	this->SplashAnims.Read(exINI, pID, "SplashAnims");
 	this->SplashAnims_PickRandom.Read(exINI, pID, "SplashAnims.PickRandom");
+	this->Trailer_SpawnDelay.Read(exINI, pID, "Trailer.SpawnDelay");
 }
 
 // =============================
@@ -30,6 +31,7 @@ void VoxelAnimTypeExt::ExtData::Serialize(T& Stm)
 		.Process(this->WakeAnim)
 		.Process(this->SplashAnims)
 		.Process(this->SplashAnims_PickRandom)
+		.Process(this->Trailer_SpawnDelay)
 		;
 }
 

src/Ext/VoxelAnimType/Body.h

@@ -28,6 +28,7 @@ class VoxelAnimTypeExt
 		Valueable<AnimTypeClass*> WakeAnim;
 		NullableVector<AnimTypeClass*> SplashAnims;
 		Valueable<bool> SplashAnims_PickRandom;
+		Valueable<int> Trailer_SpawnDelay;
 
 		ExtData(VoxelAnimTypeClass* OwnerObject) : Extension<VoxelAnimTypeClass>(OwnerObject)
 			, LaserTrail_Types()
@@ -36,6 +37,7 @@ class VoxelAnimTypeExt
 			, WakeAnim {}
 			, SplashAnims {}
 			, SplashAnims_PickRandom { false }
+			, Trailer_SpawnDelay { 2 }
 		{ }
 
 		virtual ~ExtData() = default;

src/Misc/Hooks.BugFixes.cpp

@@ -125,45 +125,53 @@ DEFINE_HOOK(0x702299, TechnoClass_ReceiveDamage_DebrisMaximumsFix, 0xA)
 {
 	GET(TechnoClass* const, pThis, ESI);
 
-	auto pType = pThis->GetTechnoType();
+	const auto pType = pThis->GetTechnoType();
 
-	// If DebrisMaximums has one value, then legacy behavior is used
+// Jun12,2025 - CrimRecya : I think there is no need to return to the unreasonable vanilla logic
+// Otherwise, they should be in a parallel relationship rather than a sequential relationship
+/*	// If DebrisMaximums has one value, then legacy behavior is used
 	if (pType->DebrisMaximums.Count == 1 &&
 		pType->DebrisMaximums.GetItem(0) > 0 &&
 		pType->DebrisTypes.Count > 0)
 	{
 		return 0;
-	}
+	}*/
+
+	// Removed -1 from the MaxDebris
+	int totalSpawnAmount = ScenarioClass::Instance->Random.RandomRanged(pType->MinDebris, pType->MaxDebris);
 
-	auto totalSpawnAmount = ScenarioClass::Instance->Random.RandomRanged(
-		pType->MinDebris, pType->MaxDebris);
+	const auto& debrisTypes = pType->DebrisTypes;
+	const auto& debrisMaximums = pType->DebrisMaximums;
 
-	if (pType->DebrisTypes.Count > 0 && pType->DebrisMaximums.Count > 0)
+	// Make DebrisTypes generate completely in accordance with DebrisMaximums,
+	// without continuously looping until it exceeds totalSpawnAmount
+	if (debrisTypes.Count > 0 && debrisMaximums.Count > 0)
 	{
-		auto cord = pThis->GetCoords();
-		for (int currentIndex = 0; currentIndex < pType->DebrisTypes.Count; ++currentIndex)
+		auto coord = pThis->GetCoords();
+
+		for (int currentIndex = 0; currentIndex < debrisMaximums.Count; ++currentIndex)
 		{
-			if (pType->DebrisMaximums.GetItem(currentIndex) > 0)
+			const int currentMaxDebris = debrisMaximums.GetItem(currentIndex);
+
+			if (currentMaxDebris > 0)
 			{
-				int adjustedMaximum = Math::min(pType->DebrisMaximums.GetItem(currentIndex), pType->MaxDebris);
-				int amountToSpawn = abs(ScenarioClass::Instance->Random.Random()) % (adjustedMaximum + 1); //0x702337
+				const int adjustedMaximum = Math::min(currentMaxDebris, pType->MaxDebris);
+				int amountToSpawn = std::abs(ScenarioClass::Instance->Random.Random()) % (adjustedMaximum + 1); // 0x702337
 				amountToSpawn = Math::min(amountToSpawn, totalSpawnAmount);
 				totalSpawnAmount -= amountToSpawn;
 
-				for (; amountToSpawn > 0; --amountToSpawn)
+				for ( ; amountToSpawn > 0; --amountToSpawn)
 				{
-					GameCreate<VoxelAnimClass>(pType->DebrisTypes.GetItem(currentIndex),
-						&cord, pThis->Owner);
+					GameCreate<VoxelAnimClass>(debrisTypes.GetItem(currentIndex), &coord, pThis->Owner);
 				}
 
-				if (totalSpawnAmount < 1)
+				if (totalSpawnAmount <= 0)
 					break;
 			}
 		}
 	}
 
 	R->EBX(totalSpawnAmount);
-
 	return 0x7023E5;
 }