fix wound audio spam by disabling more than one per MO per frame

Author: pawnishoovy

CHANGELOG.md

@@ -31,6 +31,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - New `SoundContainer` features.  
 	Lua property `Paused` (R/W) to pause or unpause all sounds of a SoundContainer. Newly played sounds will not begin playback until unpaused.  
 	Lua function `GetAudibleVolume` to get the real audible volume of a SoundContainer's sounds as a float from 0 to 1. This accounts for literally everything, including game volume.
+	
+- New `AEmitter` and `PEmitter` INI and Lua (R/W) property `PlayBurstSound` which denotes whether the BurstSound should play when appropriate. This should not be confused for a trigger - it's just a enable/disable toggle to avoid having to remove and add BurstSound altogether.
 
 - Allow lua scripts to use LuaJIT's BitOp module (see https://bitop.luajit.org/api.html)
 
@@ -54,6 +56,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - `MovableMan:OpenAllDoors()`, when passed `NOTEAM`, will now open/close doors specifically for `NOTEAM` (instead of all doors).
 
+- MOs now only play the BurstSound of the first Wound they receive in a frame, which not only solves audio spam during e.g. explosions but also preserves intended audio when firing guns with a high ParticleCount at them.
+
 </details>
 
 <details><summary><b>Fixed</b></summary>

Source/Entities/AEmitter.cpp

@@ -38,6 +38,7 @@ void AEmitter::Clear() {
 	// Set this to really long so an initial burst will be possible
 	m_BurstTimer.SetElapsedSimTimeS(50000);
 	m_BurstTimer.SetElapsedRealTimeS(50000);
+	m_PlayBurstSound = true;
 	m_EmitAngle.Reset();
 	m_EmissionOffset.Reset();
 	m_EmitDamage = 0;
@@ -87,6 +88,7 @@ int AEmitter::Create(const AEmitter& reference) {
 	m_EmitterDamageMultiplier = reference.m_EmitterDamageMultiplier;
 	m_BurstSpacing = reference.m_BurstSpacing;
 	m_BurstTriggered = reference.m_BurstTriggered;
+	m_PlayBurstSound = reference.m_PlayBurstSound;
 	m_EmitAngle = reference.m_EmitAngle;
 	m_EmissionOffset = reference.m_EmissionOffset;
 	m_EmitDamage = reference.m_EmitDamage;
@@ -147,6 +149,7 @@ int AEmitter::ReadProperty(const std::string_view& propName, Reader& reader) {
 	MatchProperty("EmitterDamageMultiplier", { reader >> m_EmitterDamageMultiplier; });
 	MatchProperty("BurstSpacing", { reader >> m_BurstSpacing; });
 	MatchProperty("BurstTriggered", { reader >> m_BurstTriggered; });
+	MatchProperty("PlayBurstSound", { reader >> m_PlayBurstSound; });
 	MatchProperty("EmissionAngle", { reader >> m_EmitAngle; });
 	MatchProperty("EmissionOffset", { reader >> m_EmissionOffset; });
 	MatchProperty("EmissionDamage", { reader >> m_EmitDamage; });
@@ -197,6 +200,8 @@ int AEmitter::Save(Writer& writer) const {
 	writer << m_BurstSpacing;
 	writer.NewProperty("BurstTriggered");
 	writer << m_BurstTriggered;
+	writer.NewProperty("PlayBurstSound");
+	writer << m_PlayBurstSound;
 	writer.NewProperty("EmissionAngle");
 	writer << m_EmitAngle;
 	writer.NewProperty("EmissionOffset");
@@ -392,7 +397,7 @@ void AEmitter::Update() {
 		float throttleFactor = GetThrottleFactor();
 		m_FlashScale = throttleFactor;
 		// Check burst triggering against whether the spacing is fulfilled
-		if (m_BurstTriggered && CanTriggerBurst()) {
+		if (m_PlayBurstSound && m_BurstTriggered && CanTriggerBurst()) {
 			// Play burst sound
 			if (m_BurstSound) {
 				m_BurstSound->Play(m_Pos);

Source/Entities/AEmitter.h

@@ -292,6 +292,14 @@ namespace RTE {
 		/// @param newValue Emit damage of emitter.
 		void SetEmitDamage(float newValue) { m_EmitDamage = newValue; }
 
+		/// Returns whether this emitter will play its burst sound when appropriate or not.
+		/// @return Whether this emitter will play its burst sound when appropriate or not.
+		bool GetPlayBurstSound() const { return m_PlayBurstSound; }
+
+		/// Sets whether this emitter will play its burst sound when appropriate or not.
+		/// @param playBurstSound Whether this emitter should play its burst sound when appropriate or not.
+		void SetPlayBurstSound(bool playBurstSound) { m_PlayBurstSound = playBurstSound; }
+
 		/// Returns damage multiplier of this emitter.
 		/// @return Damage multiplier of emitter.
 		float GetEmitterDamageMultiplier() const { return m_EmitterDamageMultiplier; }
@@ -390,6 +398,8 @@ namespace RTE {
 		float m_BurstSpacing;
 		// Measures the shortest possible time between bursts
 		Timer m_BurstTimer;
+		// Whether to play the BurstSound when a burst is triggered or not.
+		bool m_PlayBurstSound;
 		// The angle of the direction the emitted particles will head in.
 		// The m_Roataion of this AEmitter will be added to this angle.
 		Matrix m_EmitAngle;

Source/Entities/MOSRotating.cpp

@@ -54,6 +54,7 @@ void MOSRotating::Clear() {
 	m_RecoilForce.Reset();
 	m_RecoilOffset.Reset();
 	m_Wounds.clear();
+	m_WoundBurstSoundPlayedThisFrame = false;
 	m_Attachables.clear();
 	m_ReferenceHardcodedAttachableUniqueIDs.clear();
 	m_HardcodedAttachableUniqueIDsAndSetters.clear();
@@ -458,6 +459,12 @@ void MOSRotating::AddWound(AEmitter* woundToAdd, const Vector& parentOffsetToSet
 		woundToAdd->SetParentOffset(parentOffsetToSet);
 		woundToAdd->SetParent(this);
 		woundToAdd->SetIsWound(true);
+		if (woundToAdd->GetBurstSound()) {
+			if (m_WoundBurstSoundPlayedThisFrame) {
+				woundToAdd->SetPlayBurstSound(false);
+			}
+			m_WoundBurstSoundPlayedThisFrame = true;
+		}
 		if (woundToAdd->HasNoSetDamageMultiplier()) {
 			woundToAdd->SetDamageMultiplier(1.0F);
 		}
@@ -1340,6 +1347,8 @@ void MOSRotating::Update() {
 		m_Rotation += radsToGo * m_OrientToVel * velInfluence;
 	}
 
+	m_WoundBurstSoundPlayedThisFrame = false;
+	
 	for (auto woundItr = m_Wounds.begin(); woundItr != m_Wounds.end();) {
 		AEmitter* wound = *woundItr;
 		RTEAssert(wound && wound->IsAttachedTo(this), "Broken wound AEmitter in Update");

Source/Entities/MOSRotating.h

@@ -540,6 +540,8 @@ namespace RTE {
 		Vector m_RecoilOffset;
 		// The list of wound AEmitters currently attached to this MOSRotating, and owned here as well.
 		std::vector<AEmitter*> m_Wounds;
+		// Whether we added a wound with a BurstSound this frame or not, so we can disable further ones to avoid audio spam.
+		bool m_WoundBurstSoundPlayedThisFrame;
 		// The list of Attachables currently attached and Owned by this.
 		std::list<Attachable*> m_Attachables;
 		std::unordered_set<unsigned long> m_ReferenceHardcodedAttachableUniqueIDs; //!< An unordered set is filled with the Unique IDs of all of the reference object's hardcoded Attachables when using the copy Create.

Source/Entities/PEmitter.cpp

@@ -35,6 +35,7 @@ void PEmitter::Clear() {
 	// Set this to really long so an initial burst will be possible
 	m_BurstTimer.SetElapsedSimTimeS(50000);
 	m_BurstTimer.SetElapsedRealTimeS(50000);
+	m_PlayBurstSound = true;
 	m_EmitAngle.Reset();
 	m_EmissionOffset.Reset();
 	m_LastEmitTmr.Reset();
@@ -73,6 +74,7 @@ int PEmitter::Create(const PEmitter& reference) {
 	m_BurstScale = reference.m_BurstScale;
 	m_BurstSpacing = reference.m_BurstSpacing;
 	m_BurstTriggered = reference.m_BurstTriggered;
+	m_PlayBurstSound = reference.m_PlayBurstSound;
 	m_EmitAngle = reference.m_EmitAngle;
 	m_EmissionOffset = reference.m_EmissionOffset;
 	m_FlashScale = reference.m_FlashScale;
@@ -122,6 +124,7 @@ int PEmitter::ReadProperty(const std::string_view& propName, Reader& reader) {
 	MatchProperty("BurstScale", { reader >> m_BurstScale; });
 	MatchProperty("BurstSpacing", { reader >> m_BurstSpacing; });
 	MatchProperty("BurstTriggered", { reader >> m_BurstTriggered; });
+	MatchProperty("PlayBurstSound", { reader >> m_PlayBurstSound; });
 	MatchProperty("EmissionAngle", { reader >> m_EmitAngle; });
 	MatchProperty("EmissionOffset", { reader >> m_EmissionOffset; });
 	MatchProperty("FlashScale", { reader >> m_FlashScale; });
@@ -166,6 +169,8 @@ int PEmitter::Save(Writer& writer) const {
 	writer << m_BurstSpacing;
 	writer.NewProperty("BurstTriggered");
 	writer << m_BurstTriggered;
+	writer.NewProperty("PlayBurstSound");
+	writer << m_PlayBurstSound;
 	writer.NewProperty("EmissionAngle");
 	writer << m_EmitAngle;
 	writer.NewProperty("EmissionOffset");
@@ -295,7 +300,7 @@ void PEmitter::Update() {
 		float throttleFactor = GetThrottleFactor();
 		m_FlashScale = throttleFactor;
 		// Check burst triggering against whether the spacing is fulfilled
-		if (m_BurstTriggered && (m_BurstSpacing <= 0 || m_BurstTimer.IsPastSimMS(m_BurstSpacing))) {
+		if (m_PlayBurstSound && m_BurstTriggered && (m_BurstSpacing <= 0 || m_BurstTimer.IsPastSimMS(m_BurstSpacing))) {
 			// Play burst sound
 			m_BurstSound.Play(m_Pos);
 			// Start timing until next burst

Source/Entities/PEmitter.h

@@ -226,6 +226,14 @@ namespace RTE {
 		/// Indicates whether this PEmitter is set to burst next update or not.
 		/// @return Whether a burst is gonna happen or not..
 		bool IsSetToBurst() const { return m_BurstTriggered; }
+		
+		/// Returns whether this emitter will play its burst sound when appropriate or not.
+		/// @return Whether this emitter will play its burst sound when appropriate or not.
+		bool GetPlayBurstSound() const { return m_PlayBurstSound; }
+
+		/// Sets whether this emitter will play its burst sound when appropriate or not.
+		/// @param playBurstSound Whether this emitter should play its burst sound when appropriate or not.
+		void SetPlayBurstSound(bool playBurstSound) { m_PlayBurstSound = playBurstSound; }
 
 		/// Registers a new AlarmEvent if this emitter has a loudness above zero.
 		/// @param Team Team that will ignore this AlarmEvent.
@@ -300,6 +308,8 @@ namespace RTE {
 		float m_BurstSpacing;
 		// Measures the shortest possible time between bursts
 		Timer m_BurstTimer;
+		// Whether to play the BurstSound when a burst is triggered or not.
+		bool m_PlayBurstSound;
 		// The angle of the direction the emitted particles will head in.
 		// The m_Roataion of this PEmitter will be added to this angle.
 		Matrix m_EmitAngle;

Source/Lua/LuaBindingsEntities.cpp

@@ -340,6 +340,7 @@ LuaBindingRegisterFunctionDefinitionForType(EntityLuaBindings, AEmitter) {
 	    .property("BurstSound", &AEmitter::GetBurstSound, &LuaAdaptersPropertyOwnershipSafetyFaker::AEmitterSetBurstSound)
 	    .property("EndSound", &AEmitter::GetEndSound, &LuaAdaptersPropertyOwnershipSafetyFaker::AEmitterSetEndSound)
 	    .property("BurstScale", &AEmitter::GetBurstScale, &AEmitter::SetBurstScale)
+	    .property("PlayBurstSound", &AEmitter::GetPlayBurstSound, &AEmitter::SetPlayBurstSound)
 	    .property("EmitAngle", &AEmitter::GetEmitAngle, &AEmitter::SetEmitAngle)
 	    .property("GetThrottle", &AEmitter::GetThrottle, &AEmitter::SetThrottle)
 	    .property("Throttle", &AEmitter::GetThrottle, &AEmitter::SetThrottle)
@@ -1002,6 +1003,7 @@ LuaBindingRegisterFunctionDefinitionForType(EntityLuaBindings, PEmitter) {
 	return ConcreteTypeLuaClassDefinition(PEmitter, MOSParticle)
 
 	    .property("BurstScale", &PEmitter::GetBurstScale, &PEmitter::SetBurstScale)
+	    .property("PlayBurstSound", &PEmitter::GetPlayBurstSound, &PEmitter::SetPlayBurstSound)
 	    .property("EmitAngle", &PEmitter::GetEmitAngle, &PEmitter::SetEmitAngle)
 	    .property("GetThrottle", &PEmitter::GetThrottle, &PEmitter::SetThrottle)
 	    .property("Throttle", &PEmitter::GetThrottle, &PEmitter::SetThrottle)