Fix: SpawnArea deferred adding/removing system for GameObjects during update loop added.

Fix: GameObject Layer lock added. While a GameObject is managed by a SpawnArea the layer can no longer be changed.
Nuget: Version changed from 5.2.0 to 5.3.0 and 5.3.0 Release Notes added.

Author: SoloByte

ShapeEngine/Core/GameObject.cs

@@ -1,3 +1,4 @@
+using System.ComponentModel;
 using System.Numerics;
 using ShapeEngine.Core.Structs;
 using ShapeEngine.Geometry.RectDef;
@@ -13,6 +14,8 @@ namespace ShapeEngine.Core;
 /// </remarks>
 public abstract class GameObject : IUpdateable, IDrawable
 {
+    #region Events
+    
     /// <summary>
     /// Occurs when this object is killed.
     /// <list type="bullet">
@@ -22,6 +25,7 @@ public abstract class GameObject : IUpdateable, IDrawable
     /// </list>
     /// </summary>
     public event Action<GameObject, string?, GameObject?>? OnKilled;
+  
     /// <summary>
     /// Occurs when this object is revived.
     /// <list type="bullet">
@@ -32,15 +36,68 @@ public abstract class GameObject : IUpdateable, IDrawable
     /// </summary>
     public event Action<GameObject, string?, GameObject?>? OnRevived;
 
+    #endregion
+    
+    #region Properties
+    
     /// <summary>
     /// Gets or sets the transform (position, rotation, scale) of this object.
     /// </summary>
     public Transform2D Transform { get; set; }
+    
     /// <summary>
     /// Gets whether this object is dead (killed).
     /// </summary>
     public bool IsDead { get; private set; }
 
+    /// <summary>
+    /// Gets a value indicating whether this object is currently managed by a <see cref="SpawnArea"/>.
+    /// </summary>
+    /// <value>
+    /// <see langword="true"/> if the object has been added to and is actively managed by a <see cref="SpawnArea"/>; otherwise, <see langword="false"/>.
+    /// </value>
+    /// <remarks>
+    /// <para>
+    /// <b>Deferred Processing:</b> Because <see cref="SpawnArea"/> processes additions and removals using deferred logic,
+    /// this state may not change immediately upon calling <see cref="SpawnArea.AddGameObject(GameObject)"/> or <see cref="SpawnArea.RemoveGameObject(GameObject)"/>.
+    /// Instead, the value is updated once the object is actually processed (which can be delayed until the end of the current frame).
+    /// </para>
+    /// </remarks>
+    public bool IsSpawned { get; private set; }
+    
+    private uint currentLayer;
+    
+    /// <summary>
+    /// Gets or sets the area layer in which this object is stored and drawn. Higher layers are rendered on top of lower layers.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>Restriction:</b> The layer <b>cannot</b> be changed while the object is spawned (i.e., when <see cref="IsSpawned"/> is <see langword="true"/>).
+    /// </para>
+    /// <para>
+    /// You must check that <see cref="IsSpawned"/> is <see langword="false"/> (or remove the object from its <see cref="SpawnArea"/>)
+    /// before setting this value. Attempting to modify the layer while spawned throws an <see cref="InvalidOperationException"/>.
+    /// </para>
+    /// </remarks>
+    /// <exception cref="InvalidOperationException">Thrown when attempting to set the layer while <see cref="IsSpawned"/> is <see langword="true"/>.</exception>
+    public uint Layer
+    {
+        get => currentLayer;
+        set
+        {
+            if (IsSpawned)
+            {
+                throw new InvalidOperationException(
+                    "Layer cannot be changed while the GameObject is spawned. Remove it from the SpawnArea first.");
+            }
+            currentLayer = value;
+        }
+    }
+    
+    #endregion
+    
+    #region Public Methods
+    
     /// <summary>
     /// Gets the bounding box of this object in world space.
     /// </summary>
@@ -74,17 +131,14 @@ public abstract class GameObject : IUpdateable, IDrawable
     /// <param name="gameArea">The area of the game world.</param>
     /// <returns>True if drawing to game, otherwise false.</returns>
     public virtual bool IsDrawingToGame(Rect gameArea) => true;
+ 
     /// <summary>
     /// Determines if this object should be drawn to the game UI. (default = false)
     /// </summary>
     /// <param name="gameUiArea">The area of the game UI.</param>
     /// <returns>True if drawing to game UI, otherwise false.</returns>
     public virtual bool IsDrawingToGameUI(Rect gameUiArea) => false;
-        
-    /// <summary>
-    /// Gets or sets the area layer this object is stored in. Higher layers are drawn on top of lower layers.
-    /// </summary>
-    public uint Layer { get; set; }
+    
     /// <summary>
     /// Called by the area to update the object's position based on the new parallax position.
     /// </summary>
@@ -103,6 +157,7 @@ public virtual void UpdateParallaxe(Vector2 newParallaxPosition) { }
     /// </summary>
     /// <param name="spawnArea">The spawn area this object is added to.</param>
     public virtual void OnSpawned(SpawnArea spawnArea){}
+  
     /// <summary>
     /// Called by the area once a game object is removed or dead.
     /// </summary>
@@ -136,20 +191,7 @@ public bool Kill(string? killMessage = null, GameObject? killer = null)
 
         return false;
     }
-    /// <summary>
-    /// Called after the object is killed. Override for custom logic.
-    /// </summary>
-    /// <param name="killMessage">Optional message for the kill event.</param>
-    /// <param name="killer">Optional killer object.</param>
-    protected virtual void WasKilled(string? killMessage = null, GameObject? killer = null) { }
-    /// <summary>
-    /// Called before the object is killed. Override to prevent kill by returning false.
-    /// </summary>
-    /// <param name="killMessage">Optional message for the kill event.</param>
-    /// <param name="killer">Optional killer object.</param>
-    /// <returns>True to allow kill, false to prevent.</returns>
-    protected virtual bool TryKill(string? killMessage = null, GameObject? killer = null) => true;
-
+ 
     /// <summary>
     /// Tries to revive this game object.
     /// </summary>
@@ -170,17 +212,56 @@ public bool Revive(string? reviveMessage = null, GameObject? reviver = null)
 
         return false;
     }
+
+    #endregion
+
+    #region Protected Methods
+    
+    /// <summary>
+    /// Called after the object is killed. Override for custom logic.
+    /// </summary>
+    /// <param name="killMessage">Optional message for the kill event.</param>
+    /// <param name="killer">Optional killer object.</param>
+    protected virtual void WasKilled(string? killMessage = null, GameObject? killer = null) { }
+    
+    /// <summary>
+    /// Called before the object is killed. Override to prevent kill by returning false.
+    /// </summary>
+    /// <param name="killMessage">Optional message for the kill event.</param>
+    /// <param name="killer">Optional killer object.</param>
+    /// <returns>True to allow kill, false to prevent.</returns>
+    protected virtual bool TryKill(string? killMessage = null, GameObject? killer = null) => true;
+
     /// <summary>
     /// Called after the object is revived. Override for custom logic.
     /// </summary>
     /// <param name="reviveMessage">Optional message for the revive event.</param>
     /// <param name="reviver">Optional reviver object.</param>
     protected virtual void WasRevived(string? reviveMessage = null, GameObject? reviver = null) { }
+    
     /// <summary>
     /// Called before the object is revived. Override to prevent revive by returning false.
     /// </summary>
     /// <param name="reviveMessage">Optional message for the revive event.</param>
     /// <param name="reviver">Optional reviver object.</param>
     /// <returns>True to allow revive, false to prevent.</returns>
     protected virtual bool TryRevive(string? reviveMessage = null, GameObject? reviver = null) => true;
+
+    #endregion
+    
+    #region Internal
+
+    internal void ResolveOnSpawned(SpawnArea spawnArea)
+    {
+        IsSpawned = true;
+        OnSpawned(spawnArea);
+    }
+    
+    internal void ResolveOnDespawned(SpawnArea spawnArea)
+    {
+        IsSpawned = false;
+        OnDespawned(spawnArea);
+    }
+
+    #endregion
 }