feat: Lots of new useful features and fix

EXILED/Exiled.API/Enums/FirearmType.cs

@@ -7,6 +7,8 @@
 
 namespace Exiled.API.Enums
 {
+    using System;
+
     /// <summary>
     /// Represents a firearm.
     /// </summary>
@@ -18,6 +20,7 @@ namespace Exiled.API.Enums
     /// <seealso cref="Extensions.ItemExtensions.GetWeaponAmmoType(FirearmType)"/>
     /// <seealso cref="Extensions.ItemExtensions.TryGetAttachments(FirearmType, uint, out System.Collections.Generic.IEnumerable{Structs.AttachmentIdentifier})"/>
     /// <seealso cref="Features.Items.Firearm.FirearmType"/>
+    [Flags]
     public enum FirearmType
     {
         /// <summary>

EXILED/Exiled.API/Extensions/IEnumerableExtensions.cs

@@ -0,0 +1,33 @@
+// -----------------------------------------------------------------------
+// <copyright file="IEnumerableExtensions.cs" company="ExMod Team">
+// Copyright (c) ExMod Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.API.Extensions
+{
+    using System;
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// A set of extensions for <see cref="IEnumerable{T}"/>.
+    /// </summary>
+    public static class IEnumerableExtensions
+    {
+        /// <summary>
+        /// Perform an action on each element of a collection.
+        /// </summary>
+        /// <typeparam name="T">Type of <see cref="IEnumerable{T}"/> elements.</typeparam>
+        /// <param name="enumerable"><see cref="IEnumerable{T}"/> in this collection, the elements will perform actions.</param>
+        /// <param name="action">Action that needs to be performed.</param>
+        public static void ForEach<T>(this IEnumerable<T> enumerable, Action<T> action)
+        {
+            if (enumerable is null || action is null)
+                return;
+
+            foreach (T e in enumerable)
+                action(e);
+        }
+    }
+}

EXILED/Exiled.API/Extensions/PlayerPermissionsExtensions.cs

@@ -0,0 +1,48 @@
+// -----------------------------------------------------------------------
+// <copyright file="PlayerPermissionsExtensions.cs" company="ExMod Team">
+// Copyright (c) ExMod Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.API.Extensions
+{
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// A set of extensions for <see cref="PlayerPermissions"/>.
+    /// </summary>
+    public static class PlayerPermissionsExtensions
+    {
+        /// <summary>
+        /// Checks whether the current permissions contain any of the permissions specified in the mask.
+        /// </summary>
+        /// <param name="playerPermissions">The current permissions to check.</param>
+        /// <param name="mask">The mask of permissions to test against.</param>
+        /// <returns><see langword="true"/> if the current permissions contain at least one permission from the mask; otherwise, <see langword="false"/>.</returns>
+        public static bool HasAnyPermission(this PlayerPermissions playerPermissions, PlayerPermissions mask)
+        {
+            return (playerPermissions & mask) != 0;
+        }
+
+        /// <summary>
+        /// Checks whether the current permissions contain any of the permissions specified in the collection.
+        /// </summary>
+        /// <param name="playerPermissions">The current permissions to check.</param>
+        /// <param name="collectionPlayerPermissions">The collection of permissions to test against.</param>
+        /// <returns><see langword="true"/> if the current permissions contain at least one permission from the collection; otherwise, <see langword="false"/>.</returns>
+        public static bool HasAnyPermission(this PlayerPermissions playerPermissions, IEnumerable<PlayerPermissions> collectionPlayerPermissions)
+        {
+            if (collectionPlayerPermissions is null)
+                return false;
+
+            foreach (PlayerPermissions perm in collectionPlayerPermissions)
+            {
+                if (playerPermissions.HasAnyPermission(perm))
+                    return true;
+            }
+
+            return false;
+        }
+    }
+}

EXILED/Exiled.API/Extensions/RandomExtensions.cs

@@ -0,0 +1,75 @@
+// -----------------------------------------------------------------------
+// <copyright file="RandomExtensions.cs" company="ExMod Team">
+// Copyright (c) ExMod Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.API.Extensions
+{
+    using System;
+
+    /// <summary>
+    /// A set of extensions for <see cref="Random"/>.
+    /// </summary>
+    public static class RandomExtensions
+    {
+        /// <summary>
+        /// Generate a random float.
+        /// </summary>
+        /// <param name="rnd"><see cref="Random"/> object.</param>
+        /// <param name="min">Minimum value.</param>
+        /// <param name="max">Maximum value.</param>
+        /// <returns>Random value between minimum and maximum.</returns>
+        public static float NextFloat(this Random rnd, float min, float max)
+        {
+            return (float)((rnd.NextDouble() * (max - min)) + min);
+        }
+
+        /// <summary>
+        /// Generate a random float.
+        /// </summary>
+        /// <param name="rnd"><see cref="Random"/> object.</param>
+        /// <param name="min">Minimum value.</param>
+        /// <param name="max">Maximum value.</param>
+        /// <returns>Random value between minimum and maximum.</returns>
+        public static float NextFloat(this Random rnd, double min, float max)
+        {
+            return (float)((rnd.NextDouble() * (max - min)) + min);
+        }
+
+        /// <summary>
+        /// Generate a random float.
+        /// </summary>
+        /// <param name="rnd"><see cref="Random"/> object.</param>
+        /// <param name="min">Minimum value.</param>
+        /// <param name="max">Maximum value.</param>
+        /// <returns>Random value between minimum and maximum.</returns>
+        public static float NextFloat(this Random rnd, float min, double max)
+        {
+            return (float)((rnd.NextDouble() * (max - min)) + min);
+        }
+
+        /// <summary>
+        /// Generate a random float.
+        /// </summary>
+        /// <param name="rnd"><see cref="Random"/> object.</param>
+        /// <param name="min">Minimum value.</param>
+        /// <param name="max">Maximum value.</param>
+        /// <returns>Random value between minimum and maximum.</returns>
+        public static float NextFloat(this Random rnd, double min, double max)
+        {
+            return (float)((rnd.NextDouble() * (max - min)) + min);
+        }
+
+        /// <summary>
+        /// Generate a random bool.
+        /// </summary>
+        /// <param name="rnd"><see cref="Random"/> object.</param>
+        /// <returns>Random boolean value.</returns>
+        public static bool NextBool(this Random rnd)
+        {
+            return (rnd.Next() & 1) == 0;
+        }
+    }
+}

EXILED/Exiled.API/Extensions/TimeSpanExtensions.cs

@@ -0,0 +1,35 @@
+// -----------------------------------------------------------------------
+// <copyright file="TimeSpanExtensions.cs" company="ExMod Team">
+// Copyright (c) ExMod Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.API.Extensions
+{
+    using System;
+
+    /// <summary>
+    /// A set of extensions for <see cref="TimeSpan"/>.
+    /// </summary>
+    public static class TimeSpanExtensions
+    {
+        /// <summary>
+        /// Converts a TimeSpan object to a human-readable format.
+        /// </summary>
+        /// <param name="timeSpan"><see cref="TimeSpan"/> object.</param>
+        /// <returns>A <see cref="TimeSpan"/> object in string representation.</returns>
+        public static string ToHumanReadable(this TimeSpan timeSpan)
+        {
+            if (timeSpan.TotalHours < 1)
+                return timeSpan.ToString(@"mm\:ss");
+
+            if (timeSpan.TotalDays < 1)
+                return timeSpan.ToString(@"hh\:mm\:ss");
+
+            string daysPart = timeSpan.Days == 1 ? "1 day" : $"{timeSpan.Days} days";
+            string timePart = timeSpan.ToString(@"hh\:mm\:ss");
+            return $"{daysPart}, {timePart}";
+        }
+    }
+}

EXILED/Exiled.API/Extensions/Vector3Extensions.cs

@@ -0,0 +1,54 @@
+// -----------------------------------------------------------------------
+// <copyright file="Vector3Extensions.cs" company="ExMod Team">
+// Copyright (c) ExMod Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.API.Extensions
+{
+    using Exiled.API.Enums;
+    using Exiled.API.Features;
+
+    using UnityEngine;
+
+    /// <summary>
+    /// A set of extensions for <see cref="Vector3"/> that provide conversions between world space and
+    /// room‑relative local space.
+    /// </summary>
+    public static class Vector3Extensions
+    {
+        /// <summary>
+        /// Converts a world position to a position relative to the specified room's local coordinate system.
+        /// </summary>
+        /// <param name="worldPos">The world‑space position to convert.</param>
+        /// <param name="room">The room whose local space will be used as the reference.</param>
+        /// <returns>
+        /// The position expressed in the room's local space.
+        /// If the room is the <see cref="RoomType.Surface"/>, the original world position is returned unchanged.
+        /// </returns>
+        public static Vector3 FromWorldToRelativePos(this Vector3 worldPos, Room room)
+        {
+            if (room.Type == RoomType.Surface)
+                return worldPos;
+            return room.Transform.InverseTransformPoint(worldPos);
+        }
+
+        /// <summary>
+        /// Converts a position relative to the specified room's local space back to world space.
+        /// </summary>
+        /// <param name="relativePos">The local‑space position to convert.</param>
+        /// <param name="room">The room whose local space was used as the reference.</param>
+        /// <returns>
+        /// The position expressed in world space.
+        /// If the room is the <see cref="RoomType.Surface"/>, the original local position is returned unchanged
+        /// (since surface uses world coordinates directly).
+        /// </returns>
+        public static Vector3 FromRelativeToWorldPos(this Vector3 relativePos, Room room)
+        {
+            if (room.Type == RoomType.Surface)
+                return relativePos;
+            return room.Transform.TransformPoint(relativePos);
+        }
+    }
+}

EXILED/Exiled.API/Features/Doors/Door.cs

@@ -337,6 +337,28 @@ public static Door Get(DoorVariant doorVariant)
         public static T Get<T>(DoorVariant doorVariant)
             where T : Door => Get(doorVariant) as T;
 
+        /// <summary>
+        /// Gets the door object associated with a specific <see cref="ButtonVariant"/>.
+        /// </summary>
+        /// <param name="buttonVariant">The base-game <see cref="ButtonVariant"/>.</param>
+        /// <returns>A <see cref="Door"/> wrapper object.</returns>
+        public static Door Get(ButtonVariant buttonVariant)
+        {
+            if (buttonVariant is null || buttonVariant.ParentDoor is null)
+                return null;
+
+            return Get(buttonVariant.ParentDoor);
+        }
+
+        /// <summary>
+        /// Gets the <see cref="Door"/> by <see cref="ButtonVariant"/>.
+        /// </summary>
+        /// <param name="buttonVariant">The <see cref="ButtonVariant"/> to convert into an door.</param>
+        /// <typeparam name="T">The specified <see cref="Door"/> type.</typeparam>
+        /// <returns>The door wrapper for the given <see cref="ButtonVariant"/>.</returns>
+        public static T Get<T>(ButtonVariant buttonVariant)
+            where T : Door => Get(buttonVariant) as T;
+
         /// <summary>
         /// Gets a <see cref="Door"/> given the specified <see cref="DoorType"/>.
         /// </summary>
@@ -378,7 +400,16 @@ public static T Get<T>(string name)
         /// </summary>
         /// <param name="gameObject">The base-game <see cref="UnityEngine.GameObject"/>.</param>
         /// <returns>The <see cref="Door"/> with the given name or <see langword="null"/> if not found.</returns>
-        public static Door Get(GameObject gameObject) => gameObject is null ? null : Get(gameObject.GetComponentInParent<DoorVariant>());
+        public static Door Get(GameObject gameObject)
+        {
+            if (gameObject != null)
+            {
+                // ParentDoor requires enabling "unsafe code"
+                return Get(gameObject.GetComponentInParent<DoorVariant>() ?? gameObject.GetComponent<ButtonVariant>()?.ParentDoor);
+            }
+
+            return null;
+        }
 
         /// <summary>
         /// Returns the closest <see cref="Door"/> to the given <paramref name="position"/>.

EXILED/Exiled.API/Features/Items/Firearm.cs

@@ -143,7 +143,7 @@ public static IReadOnlyDictionary<Player, Dictionary<FirearmType, AttachmentIden
         public new BaseFirearm Base { get; }
 
         /// <summary>
-        /// Gets a primaty magazine for current firearm.
+        /// Gets a primary magazine for current firearm.
         /// </summary>
         public PrimaryMagazine PrimaryMagazine { get; }
 
@@ -156,7 +156,7 @@ public static IReadOnlyDictionary<Player, Dictionary<FirearmType, AttachmentIden
         public BarrelMagazine BarrelMagazine { get; }
 
         /// <summary>
-        /// Gets a primaty magazine for current firearm.
+        /// Gets a primary magazine for current firearm.
         /// </summary>
         public HitscanHitregModuleBase HitscanHitregModule { get; }
 
@@ -189,6 +189,36 @@ public int MagazineAmmo
             set => PrimaryMagazine.Ammo = value;
         }
 
+        /// <summary>
+        /// Gets or sets a value indicating whether the magazine is attached from the weapon. Setter will attach the magazine, but it will be empty. Weapons that do not have a detachable magazine return false by default. For example, a revolver.
+        /// </summary>
+        public bool IsMagazineAttached
+        {
+            get
+            {
+                if (PrimaryMagazine is NormalMagazine normalMag)
+                    return normalMag.MagazineInserted;
+
+                // Weapons that do not have a detachable magazine return false by default. For example, a revolver.
+                return false;
+            }
+
+            set
+            {
+                if (PrimaryMagazine is NormalMagazine normalMag)
+                    normalMag.MagazineInserted = value;
+            }
+        }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether the magazine is attached from the weapon.
+        /// </summary>
+        public bool IsMagazineDeattached
+        {
+            get => !IsMagazineAttached;
+            set => IsMagazineAttached = !value;
+        }
+
         /// <summary>
         /// Gets or sets the amount of ammo in the firearm barrel.
         /// </summary>

EXILED/Exiled.API/Features/Log.cs

@@ -73,7 +73,7 @@ public static T DebugObject<T>(T @object)
         /// Server must have exiled_debug config enabled.
         /// </summary>
         /// <param name="message">The message to be sent.</param>
-        public static void Debug(string message)
+        public static void Debug(string message = "")
         {
             Assembly callingAssembly = Assembly.GetCallingAssembly();
 #if DEBUG
@@ -98,7 +98,7 @@ public static void Debug(string message)
         /// Sends a <see cref="Discord.LogLevel.Warn"/> level messages to the game console.
         /// </summary>
         /// <param name="message">The message to be sent.</param>
-        public static void Warn(string message) => Send($"[{Assembly.GetCallingAssembly().GetName().Name}] {message}", Discord.LogLevel.Warn, ConsoleColor.Magenta);
+        public static void Warn(string message = "") => Send($"[{Assembly.GetCallingAssembly().GetName().Name}] {message}", Discord.LogLevel.Warn, ConsoleColor.Magenta);
 
         /// <summary>
         /// Sends a <see cref="Discord.LogLevel.Error"/> level messages to the game console.
@@ -114,7 +114,7 @@ public static void Debug(string message)
         /// It's recommended to send any messages in the catch block of a try/catch as errors with the exception string.
         /// </summary>
         /// <param name="message">The message to be sent.</param>
-        public static void Error(string message) => Send($"[{Assembly.GetCallingAssembly().GetName().Name}] {message}", Discord.LogLevel.Error, ConsoleColor.DarkRed);
+        public static void Error(string message = "") => Send($"[{Assembly.GetCallingAssembly().GetName().Name}] {message}", Discord.LogLevel.Error, ConsoleColor.DarkRed);
 
         /// <summary>
         /// Sends a log message to the game console.