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,81 +20,82 @@ 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>
         /// Not a firearm.
         /// </summary>
-        None,
+        None = 0,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunCOM15"/>.
         /// </summary>
-        Com15,
+        Com15 = 1,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunCOM18"/>.
         /// </summary>
-        Com18,
+        Com18 = 2,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunE11SR"/>.
         /// </summary>
-        E11SR,
+        E11SR = 4,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunCrossvec"/>.
         /// </summary>
-        Crossvec,
+        Crossvec = 8,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunFSP9"/>.
         /// </summary>
-        FSP9,
+        FSP9 = 16,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunLogicer"/>.
         /// </summary>
-        Logicer,
+        Logicer = 32,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunRevolver"/>.
         /// </summary>
-        Revolver,
+        Revolver = 64,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunAK"/>.
         /// </summary>
-        AK,
+        AK = 128,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunShotgun"/>.
         /// </summary>
-        Shotgun,
+        Shotgun = 256,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunCom45"/>.
         /// </summary>
-        Com45,
+        Com45 = 512,
 
         /// <summary>
         /// Represents the <see cref="ItemType.ParticleDisruptor"/>.
         /// </summary>
-        ParticleDisruptor,
+        ParticleDisruptor = 1024,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunFRMG0"/>.
         /// </summary>
-        FRMG0,
+        FRMG0 = 2048,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunA7"/>.
         /// </summary>
-        A7,
+        A7 = 4096,
 
         /// <summary>
         /// Represents the <see cref="ItemType.GunSCP127"/>.
         /// </summary>
-        Scp127,
+        Scp127 = 8192,
     }
 }

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,27 @@
+// -----------------------------------------------------------------------
+// <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 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,40 @@
+// -----------------------------------------------------------------------
+// <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 < TimeSpan.Zero)
+                return "-" + timeSpan.Negate().ToHumanReadable();
+
+            int days = timeSpan.Days;
+            int hours = timeSpan.Hours;
+            int minutes = timeSpan.Minutes;
+            int seconds = timeSpan.Seconds;
+
+            if (days > 0)
+                return $"{days}:{hours:D2}:{minutes:D2}:{seconds:D2}";
+            else if (hours > 0)
+                return $"{hours:D2}:{minutes:D2}:{seconds:D2}";
+            else
+                return $"{minutes}:{seconds:D2}";
+        }
+    }
+}

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 == null || buttonVariant.ParentDoor == 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,21 @@ 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)
+                return null;
+
+            DoorVariant doorVariant = gameObject.GetComponentInParent<DoorVariant>();
+            if (doorVariant != null)
+                return Get(doorVariant);
+
+            ButtonVariant buttonVariant = gameObject.GetComponent<ButtonVariant>();
+            if (buttonVariant != null && buttonVariant.ParentDoor != null)
+                return Get(gameObject.GetComponent<ButtonVariant>().ParentDoor);
+
+            return null;
+        }
 
         /// <summary>
         /// Returns the closest <see cref="Door"/> to the given <paramref name="position"/>.