From bcce427376fe5fab756c3a853edef3a896eb768f Mon Sep 17 00:00:00 2001
From: Syntriax <Syntriax@gmail.com>
Date: Sun, 25 May 2025 12:20:37 +0300
Subject: [PATCH] feat: added GetUniverseObject/InChildren/InParent to
 UniverseObjectExtensions

---
 .../Extensions/UniverseObjectExtensions.cs    | 94 +++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/Engine.Core/Extensions/UniverseObjectExtensions.cs b/Engine.Core/Extensions/UniverseObjectExtensions.cs
index f2603b3..a47f4eb 100644
--- a/Engine.Core/Extensions/UniverseObjectExtensions.cs
+++ b/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
@@ -15,6 +17,7 @@ public static class UniverseObjectExtensions
     }
 
     #region Universe Object Search
+
     public static T? GetUniverseObject<T>(this IEnumerable<IUniverseObject> universeObjects) where T : class
     {
         foreach (IUniverseObject universeObject in universeObjects)
@@ -38,6 +41,97 @@ public static class UniverseObjectExtensions
             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;
+    }
+
+    /// <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