BREAKING CHANGE: Added IHierarchObject with Hierarchy Enter & Exit

Engine.Core/Abstract/Assignable/IHierarchyObject.cs

@@ -0,0 +1,62 @@
+namespace Syntriax.Engine.Core.Abstract;
+
+/// <summary>
+/// Represents an <see cref="IEntity"/> that can enter and exit a hierarchy within the <see cref="IGameManager"/> system.
+/// This interface allows for tracking the object's presence in the hierarchy and provides events 
+/// for notifying when the see enters or exits the hierarchy.
+/// </summary>
+public interface IHierarchyObject : IEntity
+{
+    /// <summary>
+    /// Event triggered when the <see cref="IEntity"/> enters the hierarchy.
+    /// </summary>
+    event OnEnteredHierarchyDelegate? OnEnteredHierarchy;
+
+    /// <summary>
+    /// Event triggered when the <see cref="IEntity"/> exits the hierarchy.
+    /// </summary>
+    event OnExitedHierarchyDelegate? OnExitedHierarchy;
+
+    /// <summary>
+    /// Gets the <see cref="IGameManager"/> associated with this <see cref="IEntity"/> , if any.
+    /// </summary>
+    IGameManager? GameManager { get; }
+
+    /// <summary>
+    /// Indicates whether the <see cref="IEntity"/> is currently in the hierarchy.
+    /// </summary>
+    bool IsInHierarchy { get; }
+
+    /// <summary>
+    /// Internal method to handle entering the hierarchy.
+    /// This should be called by the system to properly manage hierarchy states.
+    /// </summary>
+    /// <param name="gameManager">The game manager that is managing this hierarchy.</param>
+    /// <returns>
+    /// <see cref="true"/> if the <see cref="IEntity"/> successfully entered the hierarchy; 
+    /// <see cref="false"/> if it failed to do so.
+    /// </returns>
+    internal bool EnterHierarchy(IGameManager gameManager);
+
+    /// <summary>
+    /// Internal method to handle exiting the hierarchy.
+    /// This should be called by the system to properly manage hierarchy states.
+    /// </summary>
+    /// <returns>
+    /// <see cref="true"/> if the <see cref="IEntity"/> successfully exited the hierarchy; 
+    /// <see cref="false"/> if it failed to do so.
+    /// </returns>
+    internal bool ExitHierarchy();
+
+    /// <summary>
+    /// Delegate type for the event triggered when the <see cref="IEntity"/> enters the hierarchy.
+    /// </summary>
+    /// <param name="sender">The <see cref="IEntity"/> that entered the hierarchy.</param>
+    delegate void OnEnteredHierarchyDelegate(IHierarchyObject sender);
+
+    /// <summary>
+    /// Delegate type for the event triggered when the <see cref="IEntity"/> exits the hierarchy.
+    /// </summary>
+    /// <param name="sender">The <see cref="IEntity"/> that exited the hierarchy.</param>
+    delegate void OnExitedHierarchyDelegate(IHierarchyObject sender);
+}