Syntriax.Engine/Engine.Core/Abstract/Assignable/IHierarchyObject.cs

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, INameable
{
    /// <summary>
    /// Event triggered when the <see cref="IEntity"/> enters the hierarchy.
    /// </summary>
    event OnEnteredHierarchyEventHandler? OnEnteredHierarchy;

    /// <summary>
    /// Event triggered when the <see cref="IEntity"/> exits the hierarchy.
    /// </summary>
    event OnExitedHierarchyEventHandler? 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>
    /// EventHandler delegate for the event triggered when the <see cref="IEntity"/> enters the hierarchy of a <see cref="IGameManager">.
    /// </summary>
    /// <param name="sender">The <see cref="IEntity"/> that entered the hierarchy.</param>
    /// <param name="gameManager">The <see cref="IGameManager"/> that the <see cref="IEntity"/> has entered it's hierarchy.</param>
    delegate void OnEnteredHierarchyEventHandler(IHierarchyObject sender, IGameManager gameManager);

    /// <summary>
    /// EventHandler delegate for the event triggered when the <see cref="IEntity"/> exits the hierarchy of a <see cref="IGameManager">.
    /// </summary>
    /// <param name="sender">The <see cref="IEntity"/> that exited the hierarchy.</param>
    /// <param name="gameManager">The <see cref="IGameManager"/> that the <see cref="IEntity"/> has exited it's hierarchy.</param>
    delegate void OnExitedHierarchyEventHandler(IHierarchyObject sender, IGameManager gameManager);
}