docs: added universe and universe object extension documentation comments

Engine.Core/Exceptions/BehaviourNotFoundException.cs

@@ -1,9 +1,3 @@
-using System;
-
 namespace Syntriax.Engine.Core.Exceptions;
 
-public class BehaviourNotFoundException(string? message) : Exception(message)
-{
-    public static NotAssignedException FromType<TBehaviour>()
-        => new($"{typeof(TBehaviour).FullName} was not found");
-}
+public class BehaviourNotFoundException(string? message) : NotFoundException(message);

Engine.Core/Exceptions/NotFoundException.cs

@@ -0,0 +1,9 @@
+using System;
+
+namespace Syntriax.Engine.Core.Exceptions;
+
+public class NotFoundException(string? message) : Exception(message)
+{
+    public static NotAssignedException FromType<T>()
+        => new($"{typeof(T).FullName} was not found");
+}

Engine.Core/Exceptions/UniverseObjectNotFoundException.cs

@@ -1,9 +1,3 @@
-using System;
-
 namespace Syntriax.Engine.Core.Exceptions;
 
-public class UniverseObjectNotFoundException(string? message) : Exception(message)
-{
-    public static NotAssignedException FromType<TUniverseObject>()
-        => new($"{typeof(TUniverseObject).FullName} was not found");
-}
+public class UniverseObjectNotFoundException(string? message) : NotFoundException(message);

Engine.Core/Extensions/BehaviourExtensions.cs

@@ -1,34 +0,0 @@
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-
-namespace Syntriax.Engine.Core;
-
-public static class BehaviourExtensions
-{
-    public static T? FindBehaviour<T>(this IEnumerable<IUniverseObject> universeObjects) where T : class
-    {
-        foreach (IUniverseObject universeObject in universeObjects)
-            if (universeObject.BehaviourController.GetBehaviour<T>() is T behaviour)
-                return behaviour;
-
-        return default;
-    }
-
-    public static bool TryFindBehaviour<T>(this IEnumerable<IUniverseObject> universeObjects, [NotNullWhen(returnValue: true)] out T? behaviour) where T : class
-    {
-        behaviour = FindBehaviour<T>(universeObjects);
-        return behaviour is not null;
-    }
-
-    public static void FindBehaviours<T>(this IEnumerable<IUniverseObject> universeObjects, List<T> behaviours) where T : class
-    {
-        behaviours.Clear();
-        List<T> cache = [];
-
-        foreach (IUniverseObject universeObject in universeObjects)
-        {
-            universeObject.BehaviourController.GetBehaviours(cache);
-            behaviours.AddRange(cache);
-        }
-    }
-}

Engine.Core/Extensions/UniverseExtensions.cs

@@ -7,9 +7,27 @@ public static class UniverseExtensions
     public static IUniverseObject InstantiateUniverseObject(this IUniverse universe, params object?[]? args)
         => universe.InstantiateUniverseObject<UniverseObject>(args);
 
+    /// <summary>
+    /// Searches through all<see cref="IUniverseObject"/>s to find the specified instance of the type.
+    /// </summary>
+    /// <typeparam name="T">Type to be searched through the <see cref="IUniverse"/>.</typeparam>
+    /// <returns>The specified type if found; otherwise, throws <see cref="UniverseObjectNotFoundException"/>.</returns>
     public static T GetRequiredUniverseObject<T>(this IUniverse universe) where T : class
         => universe.GetUniverseObject<T>() ?? throw new UniverseObjectNotFoundException($"{universe.GetType().FullName}({universe.Id}) does not contain any {nameof(IUniverseObject)} object of type {typeof(T).FullName}");
 
+    /// <summary>
+    /// Searches through all<see cref="IBehaviours"/>s to find the specified instance of the type.
+    /// </summary>
+    /// <typeparam name="T">Type to be searched through the <see cref="IUniverse"/>.</typeparam>
+    /// <returns>The specified type if found; otherwise, throws <see cref="BehaviourNotFoundException"/>.</returns>
     public static T FindRequiredBehaviour<T>(this IUniverse universe) where T : class
         => universe.FindBehaviour<T>() ?? throw new BehaviourNotFoundException($"{universe.GetType().FullName}({universe.Id}) does not contain any {nameof(IUniverseObject)} with {nameof(IBehaviour)} of type {typeof(T).FullName}");
+
+    /// <summary>
+    /// Searches through all <see cref="IUniverseObject"/>s and <see cref="IBehaviours"/>s to find the specified instance of the type.
+    /// </summary>
+    /// <typeparam name="T">Type to be searched through the <see cref="IUniverse"/>.</typeparam>
+    /// <returns>The specified type if found; otherwise, throws <see cref="NotFoundException"/>.</returns>
+    public static T FindRequired<T>(this IUniverse universe) where T : class
+        => universe.Find<T>() ?? throw new NotFoundException($"{universe.GetType().FullName}({universe.Id}) does not contain any {nameof(IUniverseObject)} or {nameof(IBehaviour)} of type {typeof(T).FullName}");
 }

Engine.Core/Extensions/UniverseObjectExtensions.cs

@@ -1,6 +1,8 @@
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 
+using Syntriax.Engine.Core.Exceptions;
+
 namespace Syntriax.Engine.Core;
 
 public static class UniverseObjectExtensions
@@ -14,6 +16,13 @@ public static class UniverseObjectExtensions
         return universeObject;
     }
 
+    #region Universe Object Search
+    /// <summary>
+    /// Gets a <see cref="IUniverseObject"/> of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObjects">The <see cref="IUniverseObject"/>s to search.</param>
+    /// <returns>The first found <see cref="IUniverseObject"/> of the specified type; otherwise, null.</returns>
     public static T? GetUniverseObject<T>(this IEnumerable<IUniverseObject> universeObjects) where T : class
     {
         foreach (IUniverseObject universeObject in universeObjects)
@@ -23,17 +32,215 @@ public static class UniverseObjectExtensions
         return default;
     }
 
-    public static bool TryGetUniverseObject<T>(this IEnumerable<IUniverseObject> universeObjects, [NotNullWhen(returnValue: true)] out T? behaviour) where T : class
+    /// <summary>
+    /// Tries to get a <see cref="IUniverseObject"/> of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObjects">The <see cref="IUniverseObject"/>s to search.</param>
+    /// <returns><see cref="true"/> if a <see cref="IUniverseObject"/> of the specified type was found in the universe objects; otherwise, <see cref="false"/>.</returns>
+    public static bool TryGetUniverseObject<T>(this IEnumerable<IUniverseObject> universeObjects, [NotNullWhen(returnValue: true)] out T? universeObject) where T : class
     {
-        behaviour = GetUniverseObject<T>(universeObjects);
+        universeObject = GetUniverseObject<T>(universeObjects);
+        return universeObject is not null;
+    }
+
+    /// <summary>
+    /// Searches through the provided <see cref="IUniverseObject"/>s to collect a list of <see cref="IUniverseObject"/>s of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObject">The <see cref="IUniverseObject"/> to search.</param>
+    /// <returns>The found <see cref="IUniverseObject"/>s of the specified types</returns>
+    public static void GetUniverseObjects<T>(this IEnumerable<IUniverseObject> universeObjects, IList<T> foundUniverseObjects) where T : class
+    {
+        foundUniverseObjects.Clear();
+
+        foreach (IUniverseObject universeObject in universeObjects)
+            if (universeObject is T @object)
+                foundUniverseObjects.Add(@object);
+    }
+    #endregion
+
+    #region Universe Object Search In Parent
+    /// <summary>
+    /// Tries to get a <see cref="IUniverseObject"/> of the specified type in it's parents recursively.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="behaviour">When this method returns, contains the <see cref="IUniverseObject"/> of the specified type, if found; otherwise, null.</param>
+    /// <returns><see cref="true"/> if a <see cref="IUniverseObject"/> of the specified type was found in the parent universe objects; otherwise, <see cref="false"/>.</returns>
+    public static bool TryGetUniverseObjectInParent<T>(this IUniverseObject universeObject, [NotNullWhen(returnValue: true)] out T? behaviour) where T : class
+    {
+        behaviour = GetUniverseObjectInParent<T>(universeObject);
         return behaviour is not null;
     }
 
-    public static void GetUniverseObjects<T>(this IEnumerable<IUniverseObject> universeObjects, List<T> behaviours) where T : class
+    /// <summary>
+    /// Gets a <see cref="IUniverseObject"/> of the specified type in it's parents recursively.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObject">The <see cref="IUniverseObject"/> to start searching from.</param>
+    /// <returns>The <see cref="IUniverseObject"/> of the specified type if found; otherwise, null.</returns>
+    public static T? GetUniverseObjectInParent<T>(this IUniverseObject universeObject) where T : class
+    {
+        if (universeObject.GetUniverseObject<T>() is T localUniverseObject)
+            return localUniverseObject;
+
+        IUniverseObject? parent = universeObject;
+
+        while (parent is not null)
+        {
+            if (parent is T behaviour)
+                return behaviour;
+
+            parent = universeObject.Parent;
+        }
+
+        return default;
+    }
+
+    /// <summary>
+    /// Gets a <see cref="IUniverseObject"/> of the specified type in the parents recursively. Throws an error if not found.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObject">The <see cref="IUniverseObject"/> to start searching from.</param>
+    /// <returns>The <see cref="IUniverseObject"/> of the specified type if found; otherwise, throws <see cref="UniverseObjectNotFoundException"/>.</returns>
+    public static T GetRequiredUniverseObjectInParent<T>(this IUniverseObject universeObject) where T : class
+        => universeObject.GetUniverseObjectInParent<T>() ?? throw new UniverseObjectNotFoundException($"{universeObject.Name}'s {nameof(IUniverseObject)} does not contain any {typeof(T).FullName} on any parent ");
+
+    #endregion
+
+    #region Universe Object Search In Children
+    /// <summary>
+    /// Tries to get a <see cref="IUniverseObject"/> of the specified type in it's children recursively.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="behaviour">When this method returns, contains the <see cref="IUniverseObject"/> of the specified type, if found; otherwise, null.</param>
+    /// <returns><see cref="true"/> if a <see cref="IUniverseObject"/> of the specified type was found in the child universe objects; otherwise, <see cref="false"/>.</returns>
+    public static bool TryGetUniverseObjectInChildren<T>(this IUniverseObject universeObject, [NotNullWhen(returnValue: true)] out T? behaviour) where T : class
+    {
+        behaviour = GetUniverseObjectInChildren<T>(universeObject);
+        return behaviour is not null;
+    }
+
+    /// <summary>
+    /// Gets a <see cref="IUniverseObject"/> of the specified type in it's children recursively.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObject">The <see cref="IUniverseObject"/> to start searching from.</param>
+    /// <returns>The <see cref="IUniverseObject"/> of the specified type if found; otherwise, null.</returns>
+    public static T? GetUniverseObjectInChildren<T>(this IUniverseObject universeObject) where T : class
+    {
+        if (universeObject.GetUniverseObject<T>() is T localUniverseObject)
+            return localUniverseObject;
+
+        foreach (IUniverseObject child in universeObject)
+            if (GetUniverseObjectInChildren<T>(child) is T behaviour)
+                return behaviour;
+
+        return default;
+    }
+
+    /// <summary>
+    /// Gets a <see cref="IUniverseObject"/> of the specified type in the children recursively. Throws an error if not found.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IUniverseObject"/> to get.</typeparam>
+    /// <param name="universeObject">The <see cref="IUniverseObject"/> to start searching from.</param>
+    /// <returns>The <see cref="IUniverseObject"/> of the specified type if found; otherwise, throws <see cref="UniverseObjectNotFoundException"/>.</returns>
+    public static T GetRequiredUniverseObjectInChildren<T>(this IUniverseObject universeObject) where T : class
+        => universeObject.GetUniverseObjectInChildren<T>() ?? throw new UniverseObjectNotFoundException($"{universeObject.Name}'s {nameof(IUniverseObject)} does not contain any {typeof(T).FullName} on any children ");
+    #endregion
+
+    #region Behaviour Search
+    /// <summary>
+    /// Finds a <see cref="IBehaviour"/> of the specified type in the provided <see cref="IUniverseObject"/>s.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to find.</typeparam>
+    /// <returns>The first found <see cref="IBehaviour"/> of the specified type; otherwise, null.</returns>
+    public static T? FindBehaviour<T>(this IEnumerable<IUniverseObject> universeObjects) where T : class
+    {
+        foreach (IUniverseObject universeObject in universeObjects)
+            if (universeObject.BehaviourController.GetBehaviour<T>() is T behaviour)
+                return behaviour;
+
+        return default;
+    }
+
+    /// <summary>
+    /// Tries to find a <see cref="IBehaviour"/> of the specified type in the provided <see cref="IUniverseObject"/>s.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to find.</typeparam>
+    /// <param name="behaviour">When this method returns, contains the <see cref="IUniverseObject"/> of the specified type, if found; otherwise, null.</param>
+    /// <returns><see cref="true"/> if a <see cref="IBehaviour"/> of the specified type was found in the provided <see cref="IUniverseObject"/>s; otherwise, <see cref="false"/>.</returns>
+    public static bool TryFindBehaviour<T>(this IEnumerable<IUniverseObject> universeObjects, [NotNullWhen(returnValue: true)] out T? behaviour) where T : class
+    {
+        behaviour = FindBehaviour<T>(universeObjects);
+        return behaviour is not null;
+    }
+
+    /// <summary>
+    /// Searches through the provided <see cref="IUniverseObject"/>s to collect a list of <see cref="IBehaviour"/>s of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to get.</typeparam>
+    /// <param name="universeObjects">The <see cref="IUniverseObject"/>s to search.</param>
+    public static void FindBehaviours<T>(this IEnumerable<IUniverseObject> universeObjects, IList<T> behaviours) where T : class
     {
         behaviours.Clear();
+        List<T> cache = [];
+
         foreach (IUniverseObject universeObject in universeObjects)
-            if (universeObject is T @object)
-                behaviours.Add(@object);
+        {
+            universeObject.BehaviourController.GetBehaviours(cache);
+            foreach (T behaviour in cache)
+                behaviours.Add(behaviour);
+        }
     }
+    #endregion
+
+    #region General Search
+    /// <summary>
+    /// Finds an object of the specified type in the provided <see cref="IUniverseObject"/>s and their <see cref="IBehaviour"/>s.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to find.</typeparam>
+    /// <returns>The first found instance of the specified type; otherwise, null.</returns>
+    public static T? Find<T>(this IEnumerable<IUniverseObject> universeObjects) where T : class
+    {
+        if (universeObjects.GetUniverseObject<T>() is T foundUniverseObject)
+            return foundUniverseObject;
+
+        if (universeObjects.FindBehaviour<T>() is T foundBehaviour)
+            return foundBehaviour;
+
+        return null;
+    }
+
+    /// <summary>
+    /// Tries to find an object of the specified type in the provided <see cref="IUniverseObject"/>s and their <see cref="IBehaviour"/>s.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to find.</typeparam>
+    /// <param name="behaviour">When this method returns, contains the <see cref="IUniverseObject"/> of the specified type, if found; otherwise, null.</param>
+    /// <returns><see cref="true"/> if an object of the specified type was found in the provided <see cref="IUniverseObject"/>s; otherwise, <see cref="false"/>.</returns>
+    public static bool TryFind<T>(this IEnumerable<IUniverseObject> universeObjects, [NotNullWhen(returnValue: true)] out T? behaviour) where T : class
+    {
+        behaviour = Find<T>(universeObjects);
+        return behaviour is not null;
+    }
+
+    /// <summary>
+    /// Searches through the provided <see cref="IUniverseObject"/>s and their <see cref="IBehaviour"/>s to collect a list of the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="IBehaviour"/> to get.</typeparam>
+    /// <param name="instances">List of objects found wit the specified type.</param>
+    /// <param name="universeObjects">The <see cref="IUniverseObject"/>s to search.</param>
+    public static void Find<T>(this IEnumerable<IUniverseObject> universeObjects, IList<T> instances) where T : class
+    {
+        instances.Clear();
+        List<T> cache = [];
+
+        foreach (IUniverseObject universeObject in universeObjects)
+        {
+            universeObject.Find(cache);
+            foreach (T behaviour in cache)
+                instances.Add(behaviour);
+        }
+    }
+    #endregion
 }