feat: Sending & Receiving gun sound events

EXILED/Exiled.Events/EventArgs/Player/ReceivingGunSoundEventArgs.cs

@@ -0,0 +1,101 @@
+// -----------------------------------------------------------------------
+// <copyright file="ReceivingGunSoundEventArgs.cs" company="ExMod Team">
+// Copyright (c) ExMod Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.Events.EventArgs.Player
+{
+    using API.Features;
+    using API.Features.Items;
+
+    using AudioPooling;
+
+    using Exiled.Events.EventArgs.Interfaces;
+
+    using UnityEngine;
+
+    /// <summary>
+    /// Contains all information before a player receive gun sound.
+    /// </summary>
+    public class ReceivingGunSoundEventArgs : IPlayerEvent, IDeniableEvent, IFirearmEvent
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ReceivingGunSoundEventArgs"/> class.
+        /// </summary>
+        /// <param name="hub">The referencehub who will receive gun sound.</param>
+        /// <param name="firearm">The internal firearm instance.</param>
+        /// <param name="audioIndex">The index of the audio clip to be played.</param>
+        /// <param name="mixerChannel">The audio mixer channel.</param>
+        /// <param name="range">The audible range of the sound.</param>
+        /// <param name="pitch">The pitch of the sound.</param>
+        /// <param name="ownPos">The audio owner position.</param>
+        /// <param name="isSenderVisible">The audio owner is visible for this player.</param>
+        public ReceivingGunSoundEventArgs(ReferenceHub hub, InventorySystem.Items.Firearms.Firearm firearm, int audioIndex, MixerChannel mixerChannel, float range, float pitch, Vector3 ownPos, bool isSenderVisible)
+        {
+            Player = Player.Get(hub);
+            Firearm = Item.Get<Firearm>(firearm);
+            Sender = Firearm.Owner;
+            Range = range;
+            Pitch = pitch;
+            AudioIndex = audioIndex;
+            MixerChannel = mixerChannel;
+            SenderPosition = ownPos;
+            SenderVisible = isSenderVisible;
+        }
+
+        /// <summary>
+        /// Gets the player who will receive gun sound.
+        /// </summary>
+        public Player Player { get; }
+
+        /// <summary>
+        /// Gets the player who owns the Firearm.
+        /// </summary>
+        public Player Sender { get; }
+
+        /// <inheritdoc/>
+        public Item Item => Firearm;
+
+        /// <summary>
+        /// Gets the firearm that was the source of the sound.
+        /// </summary>
+        public Firearm Firearm { get; }
+
+        /// <summary>
+        /// Gets or sets the index of the audio clip to be played from the firearm's audio list.
+        /// </summary>
+        public int AudioIndex { get; set; }
+
+        /// <summary>
+        /// Gets or sets the mixer channel through which the sound will be played.
+        /// </summary>
+        public MixerChannel MixerChannel { get; set; }
+
+        /// <summary>
+        /// Gets or sets the max audible distance of the gun sound.
+        /// </summary>
+        public float Range { get; set; }
+
+        /// <summary>
+        /// Gets or sets the pitch of the gun sound.
+        /// </summary>
+        public float Pitch { get; set; }
+
+        /// <summary>
+        /// Gets or sets the virtual origin point used(Only works when SenderVisible is false).
+        /// </summary>
+        public Vector3 SenderPosition { get; set; }
+
+        /// <summary>
+        /// Gets a value indicating whether Sender is visible for this player.
+        /// </summary>
+        public bool SenderVisible { get; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether the gun sound should be sent.
+        /// </summary>
+        public bool IsAllowed { get; set; } = true;
+    }
+}

EXILED/Exiled.Events/EventArgs/Player/SendingGunSoundEventArgs.cs

@@ -0,0 +1,86 @@
+// -----------------------------------------------------------------------
+// <copyright file="SendingGunSoundEventArgs.cs" company="ExMod Team">
+// Copyright (c) ExMod Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+namespace Exiled.Events.EventArgs.Player
+{
+    using API.Features;
+    using API.Features.Items;
+
+    using AudioPooling;
+
+    using Exiled.Events.EventArgs.Interfaces;
+
+    using UnityEngine;
+
+    /// <summary>
+    /// Contains all information before a gun sound is sent to players.
+    /// </summary>
+    public class SendingGunSoundEventArgs : IPlayerEvent, IDeniableEvent, IFirearmEvent
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SendingGunSoundEventArgs"/> class.
+        /// </summary>
+        /// <param name="firearm">The internal firearm instance.</param>
+        /// <param name="audioIndex">The index of the audio clip to be played.</param>
+        /// <param name="mixerChannel">The audio mixer channel.</param>
+        /// <param name="range">The audible range of the sound.</param>
+        /// <param name="pitch">The pitch of the sound.</param>
+        /// <param name="ownPos">The audio owner position.</param>
+        public SendingGunSoundEventArgs(InventorySystem.Items.Firearms.Firearm firearm, int audioIndex, MixerChannel mixerChannel, float range, float pitch, Vector3 ownPos)
+        {
+            Firearm = Item.Get<Firearm>(firearm);
+            Player = Firearm.Owner;
+            Range = range;
+            Pitch = pitch;
+            AudioIndex = audioIndex;
+            MixerChannel = mixerChannel;
+            SendingPosition = ownPos;
+        }
+
+        /// <summary>
+        /// Gets the player who owns the Firearm.
+        /// </summary>
+        public Player Player { get; }
+
+        /// <inheritdoc/>
+        public Item Item => Firearm;
+
+        /// <summary>
+        /// Gets the firearm that was the source of the sound.
+        /// </summary>
+        public Firearm Firearm { get; }
+
+        /// <summary>
+        /// Gets or sets the index of the audio clip to be played from the firearm's audio list.
+        /// </summary>
+        public int AudioIndex { get; set; }
+
+        /// <summary>
+        /// Gets or sets the mixer channel through which the sound will be played.
+        /// </summary>
+        public MixerChannel MixerChannel { get; set; }
+
+        /// <summary>
+        /// Gets or sets the max audible distance of the gun sound.
+        /// </summary>
+        public float Range { get; set; }
+
+        /// <summary>
+        /// Gets or sets the pitch of the gun sound.
+        /// </summary>
+        public float Pitch { get; set; }
+
+        /// <summary>
+        /// Gets or sets the virtual origin point used(Only will work when this player not visible for sending player).
+        /// </summary>
+        public Vector3 SendingPosition { get; set; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether the gun sound should be sent.
+        /// </summary>
+        public bool IsAllowed { get; set; } = true;
+    }
+}

EXILED/Exiled.Events/Handlers/Player.cs

@@ -279,6 +279,16 @@ public class Player
         /// </summary>
         public static Event<ShootingEventArgs> Shooting { get; set; } = new();
 
+        /// <summary>
+        /// Invoked before a <see cref="API.Features.Player"/> sends a gun sound to nearby players.
+        /// </summary>
+        public static Event<SendingGunSoundEventArgs> SendingGunSound { get; set; } = new();
+
+        /// <summary>
+        /// Invoked before a <see cref="API.Features.Player"/> receives a gun sound.
+        /// </summary>
+        public static Event<ReceivingGunSoundEventArgs> ReceivingGunSound { get; set; } = new();
+
         /// <summary>
         /// Invoked before a <see cref="API.Features.Player"/> enters the pocket dimension.
         /// </summary>
@@ -900,6 +910,18 @@ public static void OnRoomChanged(RoomChangedEventArgs ev)
         /// <param name="ev">The <see cref="ShootingEventArgs"/> instance.</param>
         public static void OnShooting(ShootingEventArgs ev) => Shooting.InvokeSafely(ev);
 
+        /// <summary>
+        /// Called before the server sends a gun sound to nearby players.
+        /// </summary>
+        /// <param name="ev">The <see cref="SendingGunSoundEventArgs"/> instance.</param>
+        public static void OnSendingGunSound(SendingGunSoundEventArgs ev) => SendingGunSound.InvokeSafely(ev);
+
+        /// <summary>
+        /// Called when a <see cref="API.Features.Player"/> receives a gun sound.
+        /// </summary>
+        /// <param name="ev">The <see cref="ReceivingGunSoundEventArgs"/> instance.</param>
+        public static void OnReceivingGunSound(ReceivingGunSoundEventArgs ev) => ReceivingGunSound.InvokeSafely(ev);
+
         /// <summary>
         /// Called before a <see cref="API.Features.Player"/> enters the pocket dimension.
         /// </summary>