Allow animations to play sounds detached from audio event handler

docs/New-or-Enhanced-Logics.md

@@ -290,6 +290,16 @@ In `artmd.ini`:
 AttachedSystem=  ; ParticleSystem
 ```
 
+### Play sound as a detached sound event
+
+- It is now possible for animation to play a sound that is not attached to an audio event handler by using `DetachedReport`. By default animation `Report/StartSound` is played by an audio event handler, which allows the sound to loop and play at correct location even if it changes after its initial creation. This can also cause issues with animations that chain different types through `Next`, as the audio event handler resets when the animation restarts.
+
+In `artmd.ini`:
+```ini
+[SOMEANIM]       ; AnimationType
+DetachedReport=  ; sound entry
+```
+
 ## Buildings
 
 ### Extended building upgrades

docs/Whats-New.md

@@ -359,6 +359,7 @@ New:
 - Customizable DropPod properties on a per-InfantryType basis (by Trsdy)
 - Projectile return weapon (by Starkku)
 - Allow customizing aircraft landing direction per aircraft or per dock (by Starkku)
+- Allow animations to play sounds detached from audio event handler (by Starkku)
 
 Vanilla fixes:
 - Allow AI to repair structures built from base nodes/trigger action 125/SW delivery in single player missions (by Trsdy)

src/Ext/Anim/Hooks.cpp

@@ -191,6 +191,18 @@ DEFINE_HOOK(0x424807, AnimClass_AI_Next, 0x6)
 	return 0;
 }
 
+DEFINE_HOOK(0x424CF1, AnimClass_Start_DetachedReport, 0x6)
+{
+	GET(AnimClass*, pThis, ESI);
+
+	auto const pTypeExt = AnimTypeExt::ExtMap.Find(pThis->Type);
+
+	if (pTypeExt->DetachedReport.isset())
+		VocClass::PlayAt(pTypeExt->DetachedReport.Get(), pThis->GetCoords());
+
+	return 0;
+}
+
 DEFINE_HOOK(0x422CAB, AnimClass_DrawIt_XDrawOffset, 0x5)
 {
 	GET(AnimClass* const, pThis, ECX);

src/Ext/AnimType/Body.cpp

@@ -112,6 +112,7 @@ void AnimTypeExt::ExtData::LoadFromINIFile(CCINIClass* pINI)
 	this->AltPalette_ApplyLighting.Read(exINI, pID, "AltPalette.ApplyLighting");
 	this->MakeInfantryOwner.Read(exINI, pID, "MakeInfantryOwner");
 	this->ExtraShadow.Read(exINI, pID, "ExtraShadow");
+	this->DetachedReport.Read(exINI, pID, "DetachedReport");
 }
 
 template <typename T>
@@ -147,6 +148,7 @@ void AnimTypeExt::ExtData::Serialize(T& Stm)
 		.Process(this->AltPalette_ApplyLighting)
 		.Process(this->MakeInfantryOwner)
 		.Process(this->ExtraShadow)
+		.Process(this->DetachedReport)
 		;
 }
 

src/Ext/AnimType/Body.h

@@ -46,6 +46,7 @@ class AnimTypeExt
 		Valueable<bool> AltPalette_ApplyLighting;
 		Valueable<OwnerHouseKind> MakeInfantryOwner;
 		Valueable<bool> ExtraShadow;
+		NullableIdx<VocClass> DetachedReport;
 
 		ExtData(AnimTypeClass* OwnerObject) : Extension<AnimTypeClass>(OwnerObject)
 			, Palette { CustomPalette::PaletteMode::Temperate }
@@ -76,6 +77,7 @@ class AnimTypeExt
 			, AltPalette_ApplyLighting { false }
 			, MakeInfantryOwner { OwnerHouseKind::Victim }
 			, ExtraShadow { true }
+			, DetachedReport {}
 		{ }
 
 		virtual ~ExtData() = default;