Add events for GunComponent values, muzzle flashes and cartridge spread (#24077)

* Add a modifier event for GunComponent values

* Add docs

* Add VV readwrite to modified values

* Add more docs

* More docs

* Add Gun parameter to GunRefreshModifiersEvent

* Add another event for handling cartridge spread

* Fix pneumatic speed

Content.Shared/Weapons/Ranged/Events/GunGetAmmoSpreadEvent.cs

@@ -0,0 +1,8 @@
+namespace Content.Shared.Weapons.Ranged.Events;
+
+/// <summary>
+///     Raised directed on the gun entity when ammo is shot to calculate its spread.
+/// </summary>
+/// <param name="Spread">The spread of the ammo, can be changed by handlers.</param>
+[ByRefEvent]
+public record struct GunGetAmmoSpreadEvent(Angle Spread);

Content.Shared/Weapons/Ranged/Events/GunMuzzleFlashAttemptEvent.cs

@@ -0,0 +1,8 @@
+namespace Content.Shared.Weapons.Ranged.Events;
+
+/// <summary>
+///     Raised directed on the gun entity when a muzzle flash is about to happen.
+/// </summary>
+/// <param name="Cancelled">If set to true, the muzzle flash will not be shown.</param>
+[ByRefEvent]
+public record struct GunMuzzleFlashAttemptEvent(bool Cancelled);

Content.Shared/Weapons/Ranged/Events/GunRefreshModifiersEvent.cs

@@ -0,0 +1,23 @@
+using Content.Shared.Weapons.Ranged.Components;
+using Content.Shared.Weapons.Ranged.Systems;
+using Robust.Shared.Audio;
+
+namespace Content.Shared.Weapons.Ranged.Events;
+
+/// <summary>
+///     Raised directed on the gun entity when <see cref="SharedGunSystem.RefreshModifiers"/>
+///     is called, to update the values of <see cref="GunComponent"/> from other systems.
+/// </summary>
+[ByRefEvent]
+public record struct GunRefreshModifiersEvent(
+    Entity<GunComponent> Gun,
+    SoundSpecifier? SoundGunshot,
+    float CameraRecoilScalar,
+    Angle AngleIncrease,
+    Angle AngleDecay,
+    Angle MaxAngle,
+    Angle MinAngle,
+    int ShotsPerBurst,
+    float FireRate,
+    float ProjectileSpeed
+);