Added SoundContainer SoundOverlapMode, to determine how it'll respond to being told to play while playing

Used this to add HDFirearm FireEchoSound, which plays alongside the regular FireSound, but is set to restart when overlapping. Also made ActiveSound no longer not affected by global pitch, since that stuff was cleaned up before
Made gold dig guisound also restart when overlapping so it's not so out of control
Reorganized and cleaned up SoundContainer header and cpp a bit
Added lua bindings for SoundContainer SoundCycleMode, SoundOverlapMode and Restart. Changelog entries will come later to minimize merge conflicts.

Author: garethyr

Entities/HDFirearm.cpp

@@ -36,6 +36,7 @@ void HDFirearm::Clear()
 
     m_pFlash = 0;
     m_FireSound.Reset();
+    m_FireEchoSound.Reset();
     m_ActiveSound.Reset();
     m_DeactivationSound.Reset();
     m_EmptySound.Reset();
@@ -112,6 +113,7 @@ int HDFirearm::Create(const HDFirearm &reference)
         m_pFlash->Attach(this, m_pFlash->GetParentOffset());
     }
     m_FireSound = reference.m_FireSound;
+    m_FireEchoSound = reference.m_FireEchoSound;
     m_ActiveSound = reference.m_ActiveSound;
     m_DeactivationSound = reference.m_DeactivationSound;
     m_EmptySound = reference.m_EmptySound;
@@ -175,12 +177,14 @@ int HDFirearm::ReadProperty(std::string propName, Reader &reader)
     }
     else if (propName == "FireSound")
         reader >> m_FireSound;
-    else if (propName == "ActiveSound") {
+    else if (propName == "FireEchoSound") {
+        reader >> m_FireEchoSound;
+        m_FireEchoSound.SetSoundOverlapMode(SoundContainer::SoundOverlapMode::MODE_RESTART);
+    } else if (propName == "ActiveSound") {
         reader >> m_ActiveSound;
-        m_ActiveSound.SetAffectedByGlobalPitch(false); //Active sound (i.e. weapon spinup) modifies its pitch, so it has to account for global pitch on its own.
-    } else if (propName == "DeactivationSound")
+    } else if (propName == "DeactivationSound") {
         reader >> m_DeactivationSound;
-    else if (propName == "EmptySound")
+    } else if (propName == "EmptySound")
         reader >> m_EmptySound;
     else if (propName == "ReloadStartSound")
         reader >> m_ReloadStartSound;
@@ -256,6 +260,8 @@ int HDFirearm::Save(Writer &writer) const
     writer << m_pFlash;
     writer.NewProperty("FireSound");
     writer << m_FireSound;
+    writer.NewProperty("FireEchoSound");
+    writer << m_FireEchoSound;
     writer.NewProperty("ActiveSound");
     writer << m_ActiveSound;
     writer.NewProperty("DeactivationSound");
@@ -313,6 +319,7 @@ void HDFirearm::Destroy(bool notInherited)
     delete m_pMagazine;
     delete m_pFlash;
     m_FireSound.Stop();
+    m_FireEchoSound.Stop();
     m_ActiveSound.Stop();
     m_DeactivationSound.Stop();
 
@@ -987,8 +994,12 @@ void HDFirearm::Update()
 
         // Play firing sound
         // Only start playing if it's not a looping fire sound that is already playing, and if there's a mag
-        if (!(m_FireSound.GetLoopSetting() == -1 && m_FireSound.IsBeingPlayed()) && m_pMagazine)
-            m_FireSound.Play(m_Pos);
+        if (m_pMagazine) {
+            if (!(m_FireSound.GetLoopSetting() == -1 && m_FireSound.IsBeingPlayed())) {
+                m_FireSound.Play(m_Pos);
+            }
+            m_FireEchoSound.Play(m_Pos);
+        }
     }
     else {
         m_Recoiled = false;

Entities/HDFirearm.h

@@ -743,6 +743,7 @@ ClassInfoGetters
 
     // The audio of this FireArm being fired.
     SoundContainer m_FireSound;
+    SoundContainer m_FireEchoSound; //!< The audio that is played as the echo for the gun. Each shot will restart this sound, so it doesn't ever overlap.
     // The audio that is played immediately upon activation, but perhaps before actual first firing, if there's a pre-delay
     SoundContainer m_ActiveSound;
     // The audio that is played immediately upon cease of activation

Entities/SoundContainer.cpp

@@ -5,10 +5,15 @@ namespace RTE {
 
 	ConcreteClassInfo(SoundContainer, Entity, 50);
 
-	const std::unordered_map<std::string, SoundContainer::SoundCycleMode> SoundContainer::c_CycleModeMap = {
+	const std::unordered_map<std::string, SoundContainer::SoundCycleMode> SoundContainer::c_SoundCycleModeMap = {
 		{"Random", SoundContainer::SoundCycleMode::MODE_RANDOM},
 		{"Forwards", SoundContainer::SoundCycleMode::MODE_FORWARDS}
 	};
+	const std::unordered_map<std::string, SoundContainer::SoundOverlapMode> SoundContainer::c_SoundOverlapModeMap = {
+		{"Overlap", SoundContainer::SoundOverlapMode::MODE_OVERLAP},
+		{"Restart", SoundContainer::SoundOverlapMode::MODE_RESTART},
+		{"Ignore Play", SoundContainer::SoundOverlapMode::MODE_IGNORE_PLAY}
+	};
 
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
@@ -18,6 +23,7 @@ namespace RTE {
 		m_SoundSelectionCycleMode = MODE_RANDOM;
 
 		m_PlayingChannels.clear();
+		m_SoundOverlapMode = MODE_OVERLAP;
 
 		m_Immobile = false;
 		m_AttenuationStartDistance = c_DefaultAttenuationStartDistance;
@@ -48,6 +54,7 @@ namespace RTE {
 		m_SoundSelectionCycleMode = reference.m_SoundSelectionCycleMode;
 
 		m_PlayingChannels.clear();
+		m_SoundOverlapMode = reference.m_SoundOverlapMode;
 
 		m_Immobile = reference.m_Immobile;
 		m_AttenuationStartDistance = reference.m_AttenuationStartDistance;
@@ -70,11 +77,18 @@ namespace RTE {
 			return ReadSoundOrSoundSet(propName, reader);
 		} else if (propName == "CycleMode") {
 			std::string cycleModeString = reader.ReadPropValue();
-			if (c_CycleModeMap.find(cycleModeString) != c_CycleModeMap.end()) {
-				m_SoundSelectionCycleMode = c_CycleModeMap.find(cycleModeString)->second;
+			if (c_SoundCycleModeMap.find(cycleModeString) != c_SoundCycleModeMap.end()) {
+				m_SoundSelectionCycleMode = c_SoundCycleModeMap.find(cycleModeString)->second;
 			} else {
 				reader.ReportError("Cycle mode " + cycleModeString + " is invalid.");
 			}
+		} else if (propName == "OverlapMode") {
+			std::string overlapModeString = reader.ReadPropValue();
+			if (c_SoundOverlapModeMap.find(overlapModeString) != c_SoundOverlapModeMap.end()) {
+				m_SoundOverlapMode = c_SoundOverlapModeMap.find(overlapModeString)->second;
+			} else {
+				reader.ReportError("Cycle mode " + overlapModeString + " is invalid.");
+			}
 		} else if (propName == "Immobile") {
 			reader >> m_Immobile;
 		} else if (propName == "AttenuationStartDistance") {
@@ -190,14 +204,21 @@ namespace RTE {
 		}
 
 		writer.NewProperty("CycleMode");
-		bool t = m_SoundSelectionCycleMode == SoundCycleMode::MODE_FORWARDS;
-		std::list<std::pair<const std::string, SoundContainer::SoundCycleMode>>::const_iterator cycleModeMapEntry = std::find_if(c_CycleModeMap.begin(), c_CycleModeMap.end(), [&soundSelectionCycleMode = m_SoundSelectionCycleMode](auto element) { return element.second == soundSelectionCycleMode; });
-		if (cycleModeMapEntry != c_CycleModeMap.end()) {
+		std::list<std::pair<const std::string, SoundCycleMode>>::const_iterator cycleModeMapEntry = std::find_if(c_SoundCycleModeMap.begin(), c_SoundCycleModeMap.end(), [&soundSelectionCycleMode = m_SoundSelectionCycleMode](auto element) { return element.second == soundSelectionCycleMode; });
+		if (cycleModeMapEntry != c_SoundCycleModeMap.end()) {
 			writer << cycleModeMapEntry->first;
 		} else {
 			writer << m_SoundSelectionCycleMode;
 		}
 
+		writer.NewProperty("OverlapMode");
+		std::list<std::pair<const std::string, SoundOverlapMode>>::const_iterator overlapModeMapEntry = std::find_if(c_SoundOverlapModeMap.begin(), c_SoundOverlapModeMap.end(), [&soundOverlapMode = m_SoundOverlapMode](auto element) { return element.second == soundOverlapMode; });
+		if (overlapModeMapEntry != c_SoundOverlapModeMap.end()) {
+			writer << overlapModeMapEntry->first;
+		} else {
+			writer << m_SoundOverlapMode;
+		}
+
 		writer.NewProperty("Immobile");
 		writer << m_Immobile;
 		writer.NewProperty("AttenuationStartDistance");
@@ -261,6 +282,23 @@ namespace RTE {
 		return NULL;
 	}
 
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+	bool SoundContainer::Play(int player) {
+		if (HasAnySounds()) {
+			if (IsBeingPlayed()) {
+				if (m_SoundOverlapMode == MODE_RESTART) {
+					Restart(player);
+				} else if (m_SoundOverlapMode == MODE_IGNORE_PLAY) {
+					return false;
+				}
+			}
+			return g_AudioMan.PlaySoundContainer(this, player);
+
+		}
+		return false;
+	}
+
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
 	bool SoundContainer::SelectNextSoundSet() {

Entities/SoundContainer.h

@@ -20,15 +20,24 @@ namespace RTE {
 		ClassInfoGetters
 
 		/// <summary>
-		/// How the SoundContainer should choose the next SoundSet to play when SelectNextSoundSet is called
+		/// How the SoundContainer should choose the next SoundSet to play when SelectNextSoundSet is called.
 		/// </summary>
 		enum SoundCycleMode {
 			MODE_RANDOM = 0,
 			MODE_FORWARDS = 1
 		};
 
 		/// <summary>
-		/// Self-contained struct defining an individual sound in a SoundSet
+		/// How the SoundContainer should behave when it tries to play again while already playing.
+		/// </summary>
+		enum SoundOverlapMode {
+			MODE_OVERLAP = 0,
+			MODE_RESTART = 1,
+			MODE_IGNORE_PLAY = 2
+		};
+
+		/// <summary>
+		/// Self-contained struct defining an individual sound in a SoundSet.
 		/// </summary>
 		struct SoundData {
 			ContentFile SoundFile;
@@ -155,30 +164,6 @@ namespace RTE {
 		/// <returns>Whether this sound has any samples.</returns>
 		bool HasAnySounds() const { return !m_SoundSets.empty(); }
 
-		/// <summary>
-		/// Gets the channels playing sounds from this SoundContainer.
-		/// </summary>
-		/// <returns>The channels currently being used.</returns>
-		std::unordered_set<unsigned short> *GetPlayingChannels() { return &m_PlayingChannels; }
-
-		/// <summary>
-		/// Indicates whether any sound in this SoundContainer is currently being played.
-		/// </summary>
-		/// <returns>Whether any sounds are playing.</returns>
-		bool IsBeingPlayed() const { return !m_PlayingChannels.empty(); }
-
-		/// <summary>
-		/// Adds a channel index to the SoundContainer's collection of playing channels.
-		/// </summary>
-		/// <param name="channel">The channel index to add.</param>
-		void AddPlayingChannel(unsigned short channel) { m_PlayingChannels.insert(channel); }
-
-		/// <summary>
-		/// Removes a channel index from the SoundContainer's collection of playing channels.
-		/// </summary>
-		/// <param name="channel">The channel index to remove.</param>
-		void RemovePlayingChannel(unsigned short channel) { m_PlayingChannels.erase(channel); }
-
 		/// <summary>
 		/// Gets the current sound selection cycle mode, which is used to determine what SoundSet to select next time SelectNextSoundSet is called.
 		/// </summary>
@@ -209,6 +194,42 @@ namespace RTE {
 		/// <param name="sound">The FMOD::Sound to search for.</param>
 		/// <returns>A pointer to the corresponding SoundData or a null pointer.</returns>
 		const SoundData *GetSoundDataForSound(const FMOD::Sound *sound) const;
+
+		/// <summary>
+		/// Gets the channels playing sounds from this SoundContainer.
+		/// </summary>
+		/// <returns>The channels currently being used.</returns>
+		std::unordered_set<unsigned short> *GetPlayingChannels() { return &m_PlayingChannels; }
+
+		/// <summary>
+		/// Indicates whether any sound in this SoundContainer is currently being played.
+		/// </summary>
+		/// <returns>Whether any sounds are playing.</returns>
+		bool IsBeingPlayed() const { return !m_PlayingChannels.empty(); }
+
+		/// <summary>
+		/// Adds a channel index to the SoundContainer's collection of playing channels.
+		/// </summary>
+		/// <param name="channel">The channel index to add.</param>
+		void AddPlayingChannel(unsigned short channel) { m_PlayingChannels.insert(channel); }
+
+		/// <summary>
+		/// Removes a channel index from the SoundContainer's collection of playing channels.
+		/// </summary>
+		/// <param name="channel">The channel index to remove.</param>
+		void RemovePlayingChannel(unsigned short channel) { m_PlayingChannels.erase(channel); }
+
+		/// <summary>
+		/// Gets the SoundOverlapMode of this SoundContainer, which is used to determine how it should behave when it's told to play while already playing.
+		/// </summary>
+		/// <returns>The SoundOverlapMode of this SoundContainer.</returns>
+		SoundOverlapMode GetSoundOverlapMode() const { return m_SoundOverlapMode; }
+
+		/// <summary>
+		/// Sets the SoundOverlapMode of this SoundContainer, which is used to determine how it should behave when it's told to play while already playing. 
+		/// </summary>
+		/// <param name="newSoundOverlapMode">The new SoundOverlapMode this SoundContainer should use.</param>
+		void SetSoundOverlapMode(SoundOverlapMode newSoundOverlapMode) { m_SoundOverlapMode = newSoundOverlapMode; }
 #pragma endregion
 
 #pragma region Sound Property Getters and Setters
@@ -329,7 +350,7 @@ namespace RTE {
 		/// </summary>
 		/// <param name="player">The player to start playback of this SoundContainer's sounds for.</param>
 		/// <returns>Whether there were sounds to play and they were able to be played.</returns>
-		bool Play(int player) { return HasAnySounds() ? g_AudioMan.PlaySoundContainer(this, player) : false; }
+		bool Play(int player);
 
 		/// <summary>
 		/// Plays the next sound of this SoundContainer at the given position for all players.
@@ -359,6 +380,19 @@ namespace RTE {
 		/// <returns>Whether this SoundContainer successfully stopped playing.</returns>
 		bool Stop(int player) { return (HasAnySounds() && IsBeingPlayed()) ? g_AudioMan.StopSound(this, player) : false; }
 
+		/// <summary>
+		/// Restarts playback of this SoundContainer for all players.
+		/// </summary>
+		/// <returns>Whether this SoundContainer successfully restarted its playback.</returns>
+		bool Restart() { return Restart(-1); }
+
+		/// <summary>
+		/// Restarts playback of this SoundContainer for a specific player.
+		/// </summary>
+		/// <param name="player">Player to restart playback of this SoundContainer for.</param>
+		/// <returns>Whether this SoundContainer successfully restarted its playback.</returns>
+		bool Restart(int player) { return (HasAnySounds() && IsBeingPlayed()) ? g_AudioMan.StopSound(this, player) && g_AudioMan.PlaySoundContainer(this, player) : false; }
+
 		/// <summary>
 		/// Selects the next sounds of this SoundContainer to be played.
 		/// </summary>
@@ -383,17 +417,19 @@ namespace RTE {
 	protected:
 
 		static Entity::ClassInfo m_sClass; //!< ClassInfo for this class.
-		static const std::unordered_map<std::string, SoundCycleMode> c_CycleModeMap; //!< A map of strings to CycleModes to support string parsing for the CycleMode enum. Populated in the implementing cpp file.
+		static const std::unordered_map<std::string, SoundCycleMode> c_SoundCycleModeMap; //!< A map of strings to SoundCycleModes to support string parsing for the SoundCycleMode enum. Populated in the implementing cpp file.
+		static const std::unordered_map<std::string, SoundOverlapMode> c_SoundOverlapModeMap; //!< A map of strings to SoundOverlapModes to support string parsing for the SoundOverlapMode enum. Populated in the implementing cpp file.
 
 		std::vector<std::vector<SoundData>> m_SoundSets; //The vector of SoundSets in this SoundContainer, wherein a SoundSet is a vector containing one or more SoundData structs.
 		size_t m_SelectedSoundSet; //!< The selected SoundSet for this SoundContainer, used to determine what sounds will play when Play is called.
-		SoundCycleMode m_SoundSelectionCycleMode; //!< The sound cycle mode for this sound container, used to determine what will play next, each time play is called.
+		SoundCycleMode m_SoundSelectionCycleMode; //!< The SoundCycleMode for this SoundContainer, used to determine what will play next, each time play is called.
 
-		std::unordered_set<unsigned short> m_PlayingChannels; //!< The channels this SoundContainer is currently using
+		std::unordered_set<unsigned short> m_PlayingChannels; //!< The channels this SoundContainer is currently using.
+		SoundOverlapMode m_SoundOverlapMode; //!< The SoundOverlapMode for this SoundContainer, used to determine how it should handle overlapping play calls.
 
 		bool m_Immobile; //!< Whether this SoundContainer's sounds should be treated as immobile, i.e. not affected by 3D sound effects. Mostly used for GUI sounds and the like.
 		float m_AttenuationStartDistance; //!< The distance away from the AudioSystem listener to start attenuating this sound. Attenuation follows FMOD 3D Inverse roll-off model.
-		int m_Loops; //!< Number of loops (repeats) the SoundContainer's sounds should play when played. 0 means it plays once, -1 means it plays until stopped .
+		int m_Loops; //!< Number of loops (repeats) the SoundContainer's sounds should play when played. 0 means it plays once, -1 means it plays until stopped.
 		bool m_SoundPropertiesUpToDate = false; //!< Whether this SoundContainer's sounds' modes and properties are up to date. Used primarily to handle discrepancies that can occur when loading from ini if the line ordering isn't ideal.
 
 		int m_Priority; //!< The mixing priority of this SoundContainer's sounds. Higher values are more likely to be heard.

GUI/GUISound.cpp

@@ -83,6 +83,7 @@ namespace RTE {
 		m_FundsChangedSound.AddSound("Base.rte/Sounds/GUIs/FundsChanged4.flac", true);
 		m_FundsChangedSound.AddSound("Base.rte/Sounds/GUIs/FundsChanged5.flac", true);
 		m_FundsChangedSound.AddSound("Base.rte/Sounds/GUIs/FundsChanged6.flac", true);
+		m_FundsChangedSound.SetSoundOverlapMode(SoundContainer::SoundOverlapMode::MODE_RESTART);
 
 		m_ActorSwitchSound.Create("Base.rte/Sounds/GUIs/ActorSwitch.flac", true, false);
 

Managers/LuaMan.cpp

@@ -574,6 +574,17 @@ int LuaMan::Create() {
 
         CONCRETELUABINDING(SoundContainer, Entity)
 			.def(constructor<>())
+            .enum_("SoundCycleMode")[
+                value("MODE_RANDOM", SoundContainer::SoundCycleMode::MODE_RANDOM),
+                value("MODE_FORWARDS", SoundContainer::SoundCycleMode::MODE_FORWARDS)
+            ]
+            .enum_("SoundOverlapMode")[
+                value("MODE_OVERLAP", SoundContainer::SoundOverlapMode::MODE_OVERLAP),
+                value("MODE_RESTART", SoundContainer::SoundOverlapMode::MODE_RESTART),
+                value("MODE_IGNORE_PLAY", SoundContainer::SoundOverlapMode::MODE_IGNORE_PLAY)
+            ]
+            .property("SoundCycleMode", &SoundContainer::GetSoundSelectionCycleMode, &SoundContainer::SetSoundSelectionCycleMode)
+            .property("SoundOverlapMode", &SoundContainer::GetSoundOverlapMode, &SoundContainer::SetSoundOverlapMode)
             .property("Immobile", &SoundContainer::IsImmobile, &SoundContainer::SetImmobile)
             .property("AttenuationStartDistance", &SoundContainer::GetAttenuationStartDistance, &SoundContainer::SetAttenuationStartDistance)
             .property("Loops", &SoundContainer::GetLoopSetting, &SoundContainer::SetLoopSetting)
@@ -590,6 +601,8 @@ int LuaMan::Create() {
             .def("Play", (bool (SoundContainer:: *)(const Vector &position, int player)) &SoundContainer::Play)
             .def("Stop", (bool (SoundContainer:: *)()) &SoundContainer::Stop)
             .def("Stop", (bool (SoundContainer:: *)(int player)) &SoundContainer::Stop)
+            .def("Restart", (bool (SoundContainer:: *)()) &SoundContainer::Restart)
+            .def("Restart", (bool (SoundContainer:: *)(int player)) &SoundContainer::Restart)
             .def("AddSound", (void (SoundContainer:: *)(std::string const &soundFilePath)) &SoundContainer::AddSound)
             .def("AddSound", (void (SoundContainer:: *)(std::string const &soundFilePath, const Vector &offset, float attenuationStartDistance, bool abortGameForInvalidSound)) &SoundContainer::AddSound)
             .def("AddSound", (void (SoundContainer:: *)(std::string const &soundFilePath, unsigned int soundSetIndex, const Vector &offset, float minimumAudibleDistance, float attenuationStartDistance, bool abortGameForInvalidSound)) &SoundContainer::AddSound)