feat: Create Custom Keycard Methods

EXILED/Exiled.API/Enums/CustomizableKeycardType.cs

@@ -0,0 +1,41 @@
+// -----------------------------------------------------------------------
+// <copyright file="CustomizableKeycardType.cs" company="ExMod Team">
+// Copyright (c) ExMod Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.API.Enums
+{
+    /// <summary>
+    ///  Customizable Keycard types present in the game.
+    /// </summary>
+    /// <seealso cref="Extensions.ItemExtensions.GetItemType(CustomizableKeycardType)"/>
+    public enum CustomizableKeycardType
+    {
+        /// <summary>
+        /// Not Customizable Keycard.
+        /// </summary>
+        None,
+
+        /// <summary>
+        /// Used by <see cref="ItemType.KeycardCustomManagement"/>.
+        /// </summary>
+        Vertical,
+
+        /// <summary>
+        /// Used by <see cref="ItemType.KeycardCustomMetalCase"/>.
+        /// </summary>
+        MetalFramed,
+
+        /// <summary>
+        /// Used by <see cref="ItemType.KeycardCustomTaskForce"/>.
+        /// </summary>
+        Perforated,
+
+        /// <summary>
+        /// Used by <see cref="ItemType.KeycardCustomSite02"/>.
+        /// </summary>
+        Standart,
+    }
+}

EXILED/Exiled.API/Extensions/ItemExtensions.cs

@@ -201,6 +201,20 @@ public static int GetMaxAmmo(this FirearmType item)
             _ => ItemType.None,
         };
 
+        /// <summary>
+        /// Converts an <see cref="ItemType"/> into it's corresponding <see cref="ItemType"/>.
+        /// </summary>
+        /// <param name="type">The <see cref="CustomizableKeycardType"/> to convert.</param>
+        /// <returns>The Item type of the specified customizable keycard.</returns>
+        public static ItemType GetItemType(this CustomizableKeycardType type) => type switch
+        {
+            CustomizableKeycardType.Vertical => ItemType.KeycardCustomManagement,
+            CustomizableKeycardType.Standart => ItemType.KeycardCustomSite02,
+            CustomizableKeycardType.MetalFramed => ItemType.KeycardCustomMetalCase,
+            CustomizableKeycardType.Perforated => ItemType.KeycardCustomTaskForce,
+            _ => ItemType.None,
+        };
+
         /// <summary>
         /// Converts a <see cref="FirearmType"/> into it's corresponding <see cref="ItemType"/>.
         /// </summary>

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

@@ -10,8 +10,12 @@ namespace Exiled.API.Features.Items
     using System;
 
     using Exiled.API.Enums;
+    using Exiled.API.Extensions;
     using Exiled.API.Interfaces;
+    using Interactables.Interobjects.DoorUtils;
+    using InventorySystem;
     using InventorySystem.Items.Keycards;
+    using UnityEngine;
 
     /// <summary>
     /// A wrapper class for <see cref="KeycardItem"/>.
@@ -63,8 +67,78 @@ public KeycardPermissions Permissions
                 return KeycardPermissions.None;
             }
 
-            [Obsolete("Not functional anymore", true)]
-            set => _ = value;
+            set
+            {
+                if (!Base.Customizable)
+                {
+                    Log.Error($"The keycard {Type} is not customizable, so you cannot set permissions on it.");
+                    return;
+                }
+
+                CustomPermsDetail._customLevels = new KeycardLevels((DoorPermissionFlags)value);
+
+                KeycardDetailSynchronizer.Database.Remove(Serial);
+                KeycardDetailSynchronizer.ServerProcessItem(Base);
+            }
+        }
+
+        /// <summary>
+        /// Creates and returns a <see cref="Keycard"/> representing the provided <see cref="CustomizableKeycardType"/>.
+        /// </summary>
+        /// <param name="keycardType">The type of keycard to create.</param>
+        /// <param name="keycardName">The display name of the keycard.</param>
+        /// <param name="labelText">The label text shown on the card.</param>
+        /// <param name="ownerName">The name of the owner displayed on the card.</param>
+        /// <param name="permissions">The door permission flags for the card.</param>
+        /// <param name="levelsColor">The color representing the permission levels on the keycard.</param>
+        /// <param name="tintColor">The tint color of the card.</param>
+        /// <param name="labelColor">The color of the label text.</param>
+        /// <returns>The newly created <see cref="Keycard"/>.</returns>
+        public static Keycard CreateCustom(CustomizableKeycardType keycardType, string keycardName, string labelText, string ownerName, DoorPermissionFlags permissions, Color32 levelsColor, Color32 tintColor, Color32 labelColor) => CreateCustom(keycardType, keycardName, labelText, ownerName, new KeycardLevels(permissions), levelsColor, tintColor, labelColor);
+
+        /// <summary>
+        /// Creates and returns a <see cref="Keycard"/> representing the provided <see cref="CustomizableKeycardType"/>.
+        /// </summary>
+        /// <param name="keycardType">The type of keycard to create.</param>
+        /// <param name="keycardName">The display name of the keycard.</param>
+        /// <param name="labelText">The label text shown on the card.</param>
+        /// <param name="ownerName">The name of the owner displayed on the card.</param>
+        /// <param name="containmentLevel">The containment access level.</param>
+        /// <param name="armoryLevel">The armory access level.</param>
+        /// <param name="adminLevel">The admin access level.</param>
+        /// <param name="levelsColor">The color representing the permission levels on the keycard.</param>
+        /// <param name="tintColor">The tint color of the card.</param>
+        /// <param name="labelColor">The color of the label text.</param>
+        /// <param name="clampLevels">Whether to clamp the access level values to valid ranges.</param>
+        /// <returns>The newly created <see cref="Keycard"/>.</returns>
+        public static Keycard CreateCustom(CustomizableKeycardType keycardType, string keycardName, string labelText, string ownerName, int containmentLevel, int armoryLevel, int adminLevel, Color32 levelsColor, Color32 tintColor, Color32 labelColor, bool clampLevels = true) => CreateCustom(keycardType, keycardName, labelText, ownerName, new KeycardLevels(containmentLevel, armoryLevel, adminLevel, clampLevels), levelsColor, tintColor, labelColor);
+
+        /// <summary>
+        /// Creates and returns a <see cref="Keycard"/> representing the provided <see cref="CustomizableKeycardType"/>.
+        /// </summary>
+        /// <param name="keycardType">The type of keycard to create.</param>
+        /// <param name="keycardName">The name of keycard.</param>
+        /// <param name="labelText">The label text to display on the keycard.</param>
+        /// <param name="ownerName">The name of the owner to display on the keycard.</param>
+        /// <param name="levels">The level associated with the keycard.</param>
+        /// <param name="levelsColor">The color representing the levels on the keycard.</param>
+        /// <param name="tintColor">The tilt color of the keycard.</param>
+        /// <param name="labelColor">The color of the label text on the keycard.</param>
+        /// <returns>The newly created <see cref="Keycard"/>.</returns>
+        public static Keycard CreateCustom(CustomizableKeycardType keycardType, string keycardName, string labelText, string ownerName, KeycardLevels levels, Color32 levelsColor, Color32 tintColor, Color32 labelColor)
+        {
+            if (!keycardType.GetItemType().TryGetTemplate(out KeycardItem keycard) || !keycard.Customizable)
+                throw new ArgumentException($"The provided ItemType {keycardType} is not a valid keycard type or cant be customizable type.", nameof(keycardType));
+
+            NametagDetail._customNametag = ownerName;
+            CustomPermsDetail._customLevels = levels;
+            CustomLabelDetail._customText = labelText;
+            CustomTintDetail._customColor = tintColor;
+            CustomLabelDetail._customColor = labelColor;
+            CustomPermsDetail._customColor = levelsColor;
+            CustomItemNameDetail._customText = keycardName;
+
+            return new Keycard(keycard.ItemTypeId);
         }
 
         /// <summary>
@@ -73,4 +147,4 @@ public KeycardPermissions Permissions
         /// <returns>A string containing Keycard-related data.</returns>
         public override string ToString() => $"{Type} ({Serial}) [{Weight}] *{Scale}* |{Permissions}|";
     }
-}
+}