init

src/StatusEffect/IStatusActions.cs

@@ -0,0 +1,21 @@
+namespace Cthangover.CardBattle.StatusEffect
+{
+    /// <summary>
+    /// Interface exposed by <see cref="StatusEffectQueue"/> to <see cref="IStatusEffect"/> instances
+    /// so that status effects can communicate back to the queue during turn lifecycle callbacks.
+    /// <c>SkipTurn</c> allows an effect (e.g. stun) to mark the character's entire turn as skipped.
+    /// <c>RemoveStatus</c> allows an effect to self-remove from the queue.
+    /// </summary>
+    public interface IStatusActions
+    {
+        /// <summary>
+        /// Marks the character's current turn as skipped. Called by <see cref="StunStatusEffect.OnTurnStart"/>.
+        /// </summary>
+        void SkipTurn();
+        /// <summary>
+        /// Removes the specified status effect from the queue. Called by effects that want to
+        /// self-terminate before their turn count expires.
+        /// </summary>
+        void RemoveStatus(IStatusEffect status);
+    }
+}

src/StatusEffect/IStatusEffect.cs

@@ -0,0 +1,26 @@
+using Cthangover.Core.Characters;
+
+namespace Cthangover.CardBattle.StatusEffect
+{
+    /// <summary>
+    /// Defines a status effect that is applied to a <see cref="Character"/> during battle
+    /// and processed each turn by <see cref="StatusEffectQueue"/>. Effects receive callbacks
+    /// at turn start and turn end, and self-report expiration via <see cref="IsExpired"/>
+    /// when their <see cref="Turns"/> counter reaches zero. The <see cref="IStatusActions"/>
+    /// callback parameter allows effects to influence the character's turn (e.g. skip it).
+    /// </summary>
+    public interface IStatusEffect
+    {
+        /// <summary>Integer identifier for the effect type (1 = stun). Used for serialization.</summary>
+        int Type { get; }
+        /// <summary>Remaining turn count before expiry. Decremented by <see cref="StatusEffectQueue"/>.</summary>
+        int Turns { get; set; }
+        /// <summary>Returns <c>true</c> when <see cref="Turns"/> ≤ 0, signalling removal from the queue.</summary>
+        bool IsExpired { get; }
+
+        /// <summary>Called by <see cref="StatusEffectQueue.OnTurnStart"/> before the turn counter is decremented.</summary>
+        void OnTurnStart(Character character, IStatusActions actions);
+        /// <summary>Called by <see cref="StatusEffectQueue.OnTurnEnd"/> after the character's actions have resolved.</summary>
+        void OnTurnEnd(Character character, IStatusActions actions);
+    }
+}

src/StatusEffect/StatusEffectItem.cs

@@ -0,0 +1,27 @@
+namespace Cthangover.CardBattle.StatusEffect
+{
+    /// <summary>
+    /// Data-only container for a status effect's serializable fields (<see cref="Type"/> and <see cref="Turns"/>).
+    /// Used in <see cref="StatusEffectQueue.Copy"/> to deep-clone status effect state when a character
+    /// is copied for battle. Cast to <see cref="IStatusEffect"/> when added back to a queue.
+    /// </summary>
+    public class StatusEffectItem
+    {
+        /// <summary>Effect type identifier (matches <see cref="IStatusEffect.Type"/>).</summary>
+        public int Type { get; set; }
+        /// <summary>Remaining turns before expiry.</summary>
+        public int Turns { get; set; }
+
+        /// <summary>
+        /// Creates a field-by-field copy for deep-cloning during character duplication.
+        /// </summary>
+        public StatusEffectItem Copy()
+        {
+            return new StatusEffectItem
+            {
+                Type = Type,
+                Turns = Turns
+            };
+        }
+    }
+}

src/StatusEffect/StatusEffectQueue.cs

@@ -0,0 +1,103 @@
+using System.Collections.Generic;
+using Cthangover.Core.Characters;
+
+namespace Cthangover.CardBattle.StatusEffect
+{
+    /// <summary>
+    /// Manages the collection of <see cref="IStatusEffect"/> instances attached to a single <see cref="Character"/>.
+    /// Implements <see cref="IStatusActions"/> so that individual effects can call back into the queue
+    /// (e.g. to skip the turn). During <see cref="OnTurnStart"/>, each effect's callback is invoked and
+    /// its turn counter is decremented; expired effects are removed. <see cref="SkipTurn"/> is checked by
+    /// <see cref="CardBattleCore.RunEnemyTurn"/> to skip stunned enemies.
+    /// Supports deep copying for character duplication via <see cref="Copy"/>.
+    /// </summary>
+    public class StatusEffectQueue : IStatusActions
+    {
+        private readonly Character _character;
+        private readonly List<IStatusEffect> _effects = new();
+
+        /// <summary>
+        /// Set to <c>true</c> when an effect calls <see cref="IStatusActions.SkipTurn"/> during <see cref="OnTurnStart"/>.
+        /// Reset to <c>false</c> at the start of each turn before effects are processed.
+        /// </summary>
+        public bool SkipTurn { get; private set; }
+
+        /// <summary>
+        /// Creates a new queue bound to the given <paramref name="character"/>.
+        /// </summary>
+        public StatusEffectQueue(Character character)
+        {
+            _character = character;
+        }
+
+        /// <summary>
+        /// Creates a deep copy of this queue bound to <paramref name="newCharacter"/>.
+        /// <see cref="StatusEffectItem"/> effects are field-copied; other effect types are shared by reference.
+        /// </summary>
+        public StatusEffectQueue Copy(Character newCharacter)
+        {
+            var clone = new StatusEffectQueue(newCharacter);
+            foreach (var effect in _effects)
+            {
+                if (effect is StatusEffectItem item)
+                    clone._effects.Add(item.Copy() as IStatusEffect);
+                else
+                    clone._effects.Add(effect);
+            }
+            return clone;
+        }
+
+        /// <summary>
+        /// Adds a new status effect to the end of the processing list. Effects are processed
+        /// in reverse order during turn callbacks (last-added first).
+        /// </summary>
+        public void AddEffect(IStatusEffect effect)
+        {
+            _effects.Add(effect);
+        }
+
+        /// <summary>
+        /// Processes all effects at the start of the character's turn: resets <see cref="SkipTurn"/>,
+        /// calls <see cref="IStatusEffect.OnTurnStart"/> for each effect in reverse order,
+        /// decrements the turn counter, and removes expired effects.
+        /// Called by <see cref="CardBattleCore.StartPlayerTurn"/> and <see cref="CardBattleCore.RunEnemyTurn"/>.
+        /// </summary>
+        public void OnTurnStart()
+        {
+            SkipTurn = false;
+            for (int i = _effects.Count - 1; i >= 0; i--)
+            {
+                var effect = _effects[i];
+                effect.OnTurnStart(_character, this);
+                effect.Turns--;
+                if (effect.IsExpired)
+                    _effects.RemoveAt(i);
+            }
+        }
+
+        /// <summary>
+        /// Processes all effects at the end of the character's turn: calls
+        /// <see cref="IStatusEffect.OnTurnEnd"/> in reverse order and removes expired effects.
+        /// </summary>
+        public void OnTurnEnd()
+        {
+            for (int i = _effects.Count - 1; i >= 0; i--)
+            {
+                var effect = _effects[i];
+                effect.OnTurnEnd(_character, this);
+                if (effect.IsExpired)
+                    _effects.RemoveAt(i);
+            }
+        }
+
+        void IStatusActions.SkipTurn()
+        {
+            SkipTurn = true;
+        }
+
+        void IStatusActions.RemoveStatus(IStatusEffect status)
+        {
+            _effects.Remove(status);
+        }
+    }
+}

src/StatusEffect/StunStatusEffect.cs

@@ -0,0 +1,52 @@
+using Cthangover.Core.Characters;
+
+namespace Cthangover.CardBattle.StatusEffect
+{
+    /// <summary>
+    /// Status effect that causes a character to skip their entire turn.
+    /// On <see cref="OnTurnStart"/>, calls <see cref="IStatusActions.SkipTurn"/> which sets
+    /// <see cref="StatusEffectQueue.SkipTurn"/> to <c>true</c>. <see cref="CardBattleCore.RunEnemyTurn"/>
+    /// checks this flag and skips the character's action selection and resolution entirely.
+    /// Created by <see cref="PhysicsStunActionCard"/> when a stun card is played,
+    /// and added to the target's <see cref="StatusEffectQueue"/> via <c>Add("effect/physics/stun", turns)</c>.
+    /// </summary>
+    public class StunStatusEffect : IStatusEffect
+    {
+        /// <summary>Type identifier for stun (1).</summary>
+        public int Type => 1;
+        /// <summary>Number of turns this stun remains active.</summary>
+        public int Turns { get; set; }
+        /// <summary>Expired when the turn counter reaches zero or below.</summary>
+        public bool IsExpired => Turns <= 0;
+
+        /// <summary>
+        /// Creates a stun effect lasting for <paramref name="turns"/> turns.
+        /// </summary>
+        public StunStatusEffect(int turns)
+        {
+            Turns = turns;
+        }
+
+        /// <summary>
+        /// Parameterless constructor for deserialization. Sets <see cref="Turns"/> to 0 (expired immediately).
+        /// </summary>
+        public StunStatusEffect()
+        {
+        }
+
+        /// <summary>
+        /// Calls <see cref="IStatusActions.SkipTurn"/> to mark the character's turn as skipped.
+        /// </summary>
+        public void OnTurnStart(Character character, IStatusActions actions)
+        {
+            actions.SkipTurn();
+        }
+
+        /// <summary>
+        /// Stun has no end-of-turn effect.
+        /// </summary>
+        public void OnTurnEnd(Character character, IStatusActions actions)
+        {
+        }
+    }
+}