Merge branch 'apis-rework' into devscp244

.github/workflows/docs.yml

@@ -9,7 +9,7 @@ on:
       - master
 
 env:
-  EXILED_REFERENCES_URL: https://www.exiled.host/build_deps/References.zip
+  EXILED_REFERENCES_URL: https://misaka-zerotwo.github.io/SL-References/Master.zip
   EXILED_REFERENCES_PATH: ${{ github.workspace }}/References
 
 jobs:
@@ -29,7 +29,7 @@ jobs:
       - name: Get references
         shell: pwsh
         run: |
-          Invoke-WebRequest -Uri https://exiled.host/build_deps/References.zip -OutFile ${{ github.workspace }}/References.zip
+          Invoke-WebRequest -Uri ${{ EXILED_REFERENCES_URL }} -OutFile ${{ github.workspace }}/References.zip
           Expand-Archive -Path References.zip -DestinationPath ${{ env.EXILED_REFERENCES_PATH }}
         
       - name: Download DocFX

EXILED.props

@@ -15,7 +15,7 @@
 
   <PropertyGroup>
     <!-- This is the global version and is used for all projects that don't have a version -->
-    <Version Condition="$(Version) == ''">8.7.3</Version>
+    <Version Condition="$(Version) == ''">8.8.1</Version>
     <!-- Enables public beta warning via the PUBLIC_BETA constant -->
     <PublicBeta>false</PublicBeta>
 

Exiled.API/Enums/DecontaminationState.cs → Exiled.API/Enums/DecontaminationPhase.cs

@@ -1,5 +1,5 @@
 // -----------------------------------------------------------------------
-// <copyright file="DecontaminationState.cs" company="Exiled Team">
+// <copyright file="DecontaminationPhase.cs" company="Exiled Team">
 // Copyright (c) Exiled Team. All rights reserved.
 // Licensed under the CC BY-SA 3.0 license.
 // </copyright>
@@ -12,14 +12,9 @@ namespace Exiled.API.Enums
     /// <summary>
     /// Represents the state of a <see cref="LightContainmentZoneDecontamination.DecontaminationController"/>.
     /// </summary>
-    /// <seealso cref="Map.DecontaminationState"/>
-    public enum DecontaminationState
+    /// <seealso cref="Map.DecontaminationPhase"/>
+    public enum DecontaminationPhase
     {
-        /// <summary>
-        /// Decontamination is disable.
-        /// </summary>
-        Disabled = -1,
-
         /// <summary>
         /// Decontamination has started.
         /// </summary>

Exiled.API/Enums/WorkstationStatus.cs

@@ -0,0 +1,36 @@
+// -----------------------------------------------------------------------
+// <copyright file="WorkstationStatus.cs" company="Exiled Team">
+// Copyright (c) Exiled Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.API.Enums
+{
+    /// <summary>
+    /// All available workstation statuses.
+    /// </summary>
+    /// <seealso cref="API.Features.Workstation.CurrentStatus"/>
+    public enum WorkstationStatus : byte
+    {
+        /// <summary>
+        /// Workstation is currently offline.
+        /// </summary>
+        Offline,
+
+        /// <summary>
+        /// Workstation is currently powering up.
+        /// </summary>
+        PoweringUp,
+
+        /// <summary>
+        /// Workstation is currently powering down.
+        /// </summary>
+        PoweringDown,
+
+        /// <summary>
+        /// Workstation is currently online.
+        /// </summary>
+        Online,
+    }
+}

Exiled.API/Extensions/CollectionExtensions.cs

@@ -18,6 +18,24 @@ namespace Exiled.API.Extensions
     /// </summary>
     public static class CollectionExtensions
     {
+        /// <summary>
+        /// Removes elements from the enumerable that satisfy the specified condition.
+        /// </summary>
+        /// <typeparam name="T">The type of elements in the enumerable.</typeparam>
+        /// <param name="enumerable">The enumerable to remove elements from.</param>
+        /// <param name="func">The condition used to determine which elements to remove.</param>
+        /// <returns>A new enumerable with elements removed based on the specified condition.</returns>
+        public static IEnumerable<T> RemoveSpecified<T>(this IEnumerable<T> enumerable, Func<T, bool> func)
+        {
+            foreach (T item in enumerable)
+            {
+                if (!func(item))
+                {
+                    yield return item;
+                }
+            }
+        }
+
         /// <summary>
         /// Gets a random item from an <see cref="IEnumerable{T}"/>.
         /// </summary>

Exiled.API/Extensions/EffectTypeExtension.cs

@@ -9,6 +9,7 @@ namespace Exiled.API.Extensions
 {
     using System;
     using System.Collections.Generic;
+    using System.Collections.ObjectModel;
     using System.Linq;
 
     using CustomPlayerEffects;
@@ -25,7 +26,7 @@ public static class EffectTypeExtension
         /// <summary>
         /// Gets a dictionary that maps each <see cref="EffectType"/> to its corresponding <see cref="System.Type"/>.
         /// </summary>
-        public static Dictionary<EffectType, Type> EffectTypeToType { get; } = new(35)
+        public static ReadOnlyDictionary<EffectType, Type> EffectTypeToType { get; } = new(new Dictionary<EffectType, Type>(45)
         {
             { EffectType.AmnesiaItems, typeof(AmnesiaItems) },
             { EffectType.AmnesiaVision, typeof(AmnesiaVision) },
@@ -70,12 +71,12 @@ public static class EffectTypeExtension
 #pragma warning restore CS0618
             { EffectType.Strangled, typeof(Strangled) },
             { EffectType.Ghostly, typeof(Ghostly) },
-        };
+        });
 
         /// <summary>
         /// Gets a dictionary that maps each <see cref="System.Type"/> to its corresponding <see cref="EffectType"/>.
         /// </summary>
-        public static Dictionary<Type, EffectType> TypeToEffectType { get; } = EffectTypeToType.ToDictionary(x => x.Value, y => y.Key);
+        public static ReadOnlyDictionary<Type, EffectType> TypeToEffectType { get; } = new(EffectTypeToType.ToDictionary(x => x.Value, y => y.Key));
 
         /// <summary>
         /// Gets an instance of <see cref="System.Type"/> points to an effect.

Exiled.API/Extensions/EnumExtensions.cs

@@ -0,0 +1,39 @@
+// -----------------------------------------------------------------------
+// <copyright file="EnumExtensions.cs" company="Exiled Team">
+// Copyright (c) Exiled Team. All rights reserved.
+// Licensed under the CC BY-SA 3.0 license.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Exiled.API.Extensions
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Linq;
+
+    /// <summary>
+    /// Extensions for Enums.
+    /// </summary>
+    public static class EnumExtensions
+    {
+        private static Dictionary<Type, IEnumerable<object>> storedEnumValues = new();
+
+        /// <summary>
+        /// Queries an enum and returns their values.
+        /// </summary>
+        /// <typeparam name="T">The type to return.</typeparam>
+        /// <returns>An IEnumerable{T} of the enum values from the provided enum.</returns>
+        public static IEnumerable<T> QueryEnumValue<T>()
+            where T : Enum
+        {
+            Type type = typeof(T);
+
+            if (!storedEnumValues.ContainsKey(type))
+            {
+                storedEnumValues.Add(type, Enum.GetValues(type).ToArray<object>());
+            }
+
+            return storedEnumValues[type].Cast<T>();
+        }
+    }
+}

Exiled.API/Extensions/MathExtensions.cs

@@ -17,6 +17,12 @@ namespace Exiled.API.Extensions
     /// </summary>
     public static class MathExtensions
     {
+        /// <summary>Returns the square of the Euclidean distance between two specified points.</summary>
+        /// <param name="value1">First point.</param>
+        /// <param name="value2">Seconds point.</param>
+        /// <returns>Square of the distance.</returns>
+        public static float DistanceSquared(Vector3 value1, Vector3 value2) => (value1 - value2).sqrMagnitude;
+
         /// <summary>
         /// Evaluates a probability.
         /// </summary>

Exiled.API/Extensions/MirrorExtensions.cs

@@ -245,7 +245,8 @@ public static void ChangeAppearance(this Player player, RoleTypeId type, IEnumer
                 else
                     fpc = playerfpc;
 
-                fpc.FpcModule.MouseLook.GetSyncValues(0, out ushort value, out ushort _);
+                ushort value = 0;
+                fpc?.FpcModule.MouseLook.GetSyncValues(0, out value, out ushort _);
                 writer.WriteRelativePosition(player.RelativePosition);
                 writer.WriteUShort(value);
             }

Exiled.API/Extensions/RoleExtensions.cs

@@ -12,12 +12,12 @@ namespace Exiled.API.Extensions
     using System.Linq;
 
     using Enums;
+    using Exiled.API.Features.Roles;
     using Exiled.API.Features.Spawn;
     using InventorySystem;
     using InventorySystem.Configs;
     using PlayerRoles;
     using PlayerRoles.FirstPersonControl;
-
     using UnityEngine;
 
     using Team = PlayerRoles.Team;
@@ -55,6 +55,27 @@ public static class RoleExtensions
             _ => Side.None,
         };
 
+        /// <summary>
+        /// Gets a random <see cref="RoleTypeId"/> from the specified <see cref="Team"/>.
+        /// </summary>
+        /// <param name="team">The team to get a random of.</param>
+        /// <returns>A random role from the specified team.</returns>
+        public static RoleTypeId GetRandomRole(this Team team) => Role.ShuffledAllRoles.FirstOrDefault(r => GetTeam(r) == team);
+
+        /// <summary>
+        /// Gets a random <see cref="RoleTypeId"/> from the specified <see cref="Side"/>.
+        /// </summary>
+        /// <param name="side">The team to get a random of.</param>
+        /// <returns>A random role from the specified side.</returns>
+        public static RoleTypeId GetRandomRole(this Side side) => Role.ShuffledAllRoles.FirstOrDefault(r => GetSide(r) == side);
+
+        /// <summary>
+        /// Gets a random <see cref="RoleTypeId"/> that matches the condition.
+        /// </summary>
+        /// <param name="func">A function defining the condition for selecting.</param>
+        /// <returns>A random <see cref="RoleTypeId"/>.</returns>
+        public static RoleTypeId GetRandomRole(Func<RoleTypeId, bool> func) => Role.ShuffledAllRoles.FirstOrDefault(r => func(r));
+
         /// <summary>
         /// Gets the <see cref="Team"/> of the given <see cref="RoleTypeId"/>.
         /// </summary>
@@ -93,6 +114,16 @@ public static class RoleExtensions
         /// <returns>The <see cref="PlayerRoleBase"/>.</returns>
         public static bool TryGetRoleBase(this RoleTypeId roleType, out PlayerRoleBase roleBase) => PlayerRoleLoader.TryGetRoleTemplate(roleType, out roleBase);
 
+        /// <summary>
+        /// Tries to get the base <see cref="PlayerRoleBase"/> of the given <see cref="RoleTypeId"/>.
+        /// </summary>
+        /// <param name="roleType">The <see cref="RoleTypeId"/>.</param>
+        /// <param name="roleBase">The <see cref="PlayerRoleBase"/> to return.</param>
+        /// <typeparam name="T">The type to cast the <see cref="PlayerRoleBase"/> to.</typeparam>
+        /// <returns>The <see cref="PlayerRoleBase"/>.</returns>
+        public static bool TryGetRoleBase<T>(this RoleTypeId roleType, out T roleBase)
+            where T : PlayerRoleBase => PlayerRoleLoader.TryGetRoleTemplate(roleType, out roleBase);
+
         /// <summary>
         /// Gets the <see cref="LeadingTeam"/>.
         /// </summary>
@@ -120,40 +151,38 @@ public static class RoleExtensions
         /// <returns>Returns a <see cref="SpawnLocation"/> representing the spawn, or <see langword="null"/> if no spawns were found.</returns>
         public static SpawnLocation GetRandomSpawnLocation(this RoleTypeId roleType)
         {
-            if (roleType.GetRoleBase() is IFpcRole fpcRole &&
+            if (roleType.TryGetRoleBase(out FpcStandardRoleBase fpcRole) &&
                 fpcRole.SpawnpointHandler != null &&
                 fpcRole.SpawnpointHandler.TryGetSpawnpoint(out Vector3 position, out float horizontalRotation))
             {
-                return new SpawnLocation(roleType, position, horizontalRotation);
+                return new(roleType, position, horizontalRotation);
             }
 
             return null;
         }
 
+        /// <summary>
+        /// Gets the starting <see cref="InventoryRoleInfo"/> of a <see cref="RoleTypeId"/>.
+        /// </summary>
+        /// <param name="role">The <see cref="RoleTypeId"/>.</param>
+        /// <returns>The <see cref="InventoryRoleInfo"/> that the role receives on spawn. </returns>
+        public static InventoryRoleInfo GetStartingInventory(this RoleTypeId role)
+            => StartingInventories.DefinedInventories.TryGetValue(role, out InventoryRoleInfo info)
+                ? info
+                : new(Array.Empty<ItemType>(), new());
+
         /// <summary>
         /// Gets the starting items of a <see cref="RoleTypeId"/>.
         /// </summary>
         /// <param name="roleType">The <see cref="RoleTypeId"/>.</param>
         /// <returns>An <see cref="Array"/> of <see cref="ItemType"/> that the role receives on spawn. Will be empty for classes that do not spawn with items.</returns>
-        public static ItemType[] GetStartingInventory(this RoleTypeId roleType)
-        {
-            if (StartingInventories.DefinedInventories.TryGetValue(roleType, out InventoryRoleInfo info))
-                return info.Items;
-
-            return Array.Empty<ItemType>();
-        }
+        public static ItemType[] GetStartingItems(this RoleTypeId roleType) => roleType.GetStartingInventory().Items;
 
         /// <summary>
         /// Gets the starting ammo of a <see cref="RoleTypeId"/>.
         /// </summary>
         /// <param name="roleType">The <see cref="RoleTypeId"/>.</param>
         /// <returns>An <see cref="Array"/> of <see cref="ItemType"/> that the role receives on spawn. Will be empty for classes that do not spawn with ammo.</returns>
-        public static Dictionary<AmmoType, ushort> GetStartingAmmo(this RoleTypeId roleType)
-        {
-            if (StartingInventories.DefinedInventories.TryGetValue(roleType, out InventoryRoleInfo info))
-                return info.Ammo.ToDictionary(kvp => kvp.Key.GetAmmoType(), kvp => kvp.Value);
-
-            return new();
-        }
+        public static Dictionary<AmmoType, ushort> GetStartingAmmo(this RoleTypeId roleType) => roleType.GetStartingInventory().Ammo.ToDictionary(kvp => kvp.Key.GetAmmoType(), kvp => kvp.Value);
     }
 }

Exiled.API/Features/Camera.cs

@@ -197,13 +197,9 @@ internal Camera(Scp079Camera camera079)
         public override Vector3 Position => Base.Position;
 
         /// <summary>
-        /// Gets or sets the camera's rotation.
+        /// Gets the camera's rotation.
         /// </summary>
-        public override Quaternion Rotation
-        {
-            get => Base._cameraAnchor.rotation;
-            set => Base._cameraAnchor.rotation = value;
-        }
+        public override Quaternion Rotation => Base._cameraAnchor.rotation;
 
         /// <summary>
         /// Gets the value of the <see cref="Camera"/> zoom.

Exiled.API/Features/Core/GameEntity.cs

@@ -88,15 +88,15 @@ public virtual Quaternion Rotation
         /// The nearest <see cref="GameEntity" /> within the specified distance, or <see langword="null" /> if no game
         /// entity is found.
         /// </returns>
-        public static GameEntity GetNearestEntity(Vector3 vector, float distance) => GetNearestEntities(vector, distance).OrderBy(p => (vector - p.GameObject.transform.position).sqrMagnitude).FirstOrDefault();
+        public static GameEntity GetNearestEntity(Vector3 vector, float distance) => GetNearestEntities(vector, distance).OrderBy(p => MathExtensions.DistanceSquared(vector, p.GameObject.transform.position)).FirstOrDefault();
 
         /// <summary>
         /// Gets all game entities near the specified <see cref="Vector3" /> within the given distance.
         /// </summary>
         /// <param name="vector">The <see cref="Vector3" /> to compare.</param>
         /// <param name="distance">The maximum distance the game entity can be from the <paramref name="vector" /> to be included.</param>
         /// <returns>The filtered collection of <see cref="GameEntity" /> objects.</returns>
-        public static IEnumerable<GameEntity> GetNearestEntities(Vector3 vector, float distance) => List.Where(p => p.GameObject.transform && (vector - p.GameObject.transform.position).sqrMagnitude <= distance * distance);
+        public static IEnumerable<GameEntity> GetNearestEntities(Vector3 vector, float distance) => List.Where(p => p.GameObject.transform && MathExtensions.DistanceSquared(vector, p.GameObject.transform.position) <= distance * distance);
 
         /// <summary>
         /// Gets the farthest game entity from the specified <see cref="Vector3" /> within the given distance.
@@ -107,15 +107,15 @@ public virtual Quaternion Rotation
         /// The farthest <see cref="GameEntity" /> from the specified <paramref name="vector" /> within the given
         /// distance, or <see langword="null" /> if no game entity is found.
         /// </returns>
-        public static GameEntity GetFarthestEntity(Vector3 vector, float distance) => GetFarthestEntities(vector, distance).OrderByDescending(p => (vector - p.GameObject.transform.position).sqrMagnitude).FirstOrDefault();
+        public static GameEntity GetFarthestEntity(Vector3 vector, float distance) => GetFarthestEntities(vector, distance).OrderByDescending(p => MathExtensions.DistanceSquared(vector, p.GameObject.transform.position)).FirstOrDefault();
 
         /// <summary>
         /// Gets all game entities that have a distance greater than the specified distance from the given <see cref="Vector3" />.
         /// </summary>
         /// <param name="vector">The <see cref="Vector3" /> to compare.</param>
         /// <param name="distance">The minimum distance the game entity can be from the <paramref name="vector" /> to be included.</param>
         /// <returns>The filtered collection of <see cref="GameEntity" /> objects.</returns>
-        public static IEnumerable<GameEntity> GetFarthestEntities(Vector3 vector, float distance) => List.Where(p => p.GameObject.transform && (vector - p.GameObject.transform.position).sqrMagnitude >= distance * distance);
+        public static IEnumerable<GameEntity> GetFarthestEntities(Vector3 vector, float distance) => List.Where(p => p.GameObject.transform && MathExtensions.DistanceSquared(vector, p.GameObject.transform.position) >= distance * distance);
 
         /// <summary>
         /// Returns the local space position, based on a world space position.

Exiled.API/Features/Core/Generic/UniqueUnmanagedEnumClass.cs

@@ -38,13 +38,17 @@ public abstract class UniqueUnmanagedEnumClass<TSource, TObject> : IComparable,
         public UniqueUnmanagedEnumClass()
         {
             values ??= new();
+            TypeCode code = Convert.GetTypeCode(typeof(TSource).GetField("MinValue").GetValue(null));
+
+            if (code is TypeCode.UInt16 or TypeCode.UInt32 or TypeCode.UInt64)
+                nextValue = 0;
 
             lock (values)
             {
                 TSource value;
                 do
                 {
-                    value = (TSource)(object)nextValue++;
+                    value = (TSource)Convert.ChangeType(nextValue++, code);
                 }
                 while (values.ContainsKey(value));