// Assets/_Project/Scripts/Gameplay/EnemyAbilities/EnemySpawnContext.cs
namespace TD.Gameplay.EnemyAbilities
{
    /// <summary>
    /// Mutable per-spawn copy of an enemy's stats, handed to each of its abilities before the
    /// enemy is built so they can alter what it spawns as.
    /// </summary>
    /// <remarks>
    /// <b>Why a context rather than more parameters.</b> Wave buffs like "grounded enemies become
    /// flying" or "enemies spawn at half health" have to land <i>before</i>
    /// <c>EnemyHealth.InitializeServer</c> and before the spawn position is computed (flyers are
    /// raised by their flight height). Threading each new stat through <c>SpawnEnemy</c> as another
    /// argument was already unwieldy at two; this keeps the signature flat and gives abilities one
    /// obvious place to write.
    ///
    /// <para>Seeded from the <see cref="EnemyDefinition"/>, never written back to it — the
    /// definition is a shared asset and a buff that mutated it would leak across waves, matches,
    /// and (in the editor) sessions.</para>
    /// </remarks>
    public struct EnemySpawnContext
    {
        public float MaxHp;
        public float MoveSpeed;
        public bool  IsFlying;
        public float FlightHeight;
        public int   LivesCost;

        /// <summary>Uniform transform scale relative to the prefab's authored scale.</summary>
        public float VisualScale;

        /// <summary>
        /// Seeds a context from an enemy definition's authored stats, with health supplied by the
        /// caller.
        /// </summary>
        /// <param name="def">The type being spawned. Supplies everything except health.</param>
        /// <param name="resolvedMaxHp">Health this enemy spawns with, already resolved from the
        /// encounter's budget and the type's <see cref="EnemyDefinition.HpMultiplier"/> — see
        /// <see cref="EnemyScalingConfig.ResolvePerEnemyHp"/>. Passed in rather than read off the
        /// definition because it depends on run position and the wave's enemy count, neither of
        /// which the asset knows about.</param>
        public static EnemySpawnContext FromDefinition(EnemyDefinition def, float resolvedMaxHp)
            => new EnemySpawnContext
            {
                MaxHp        = resolvedMaxHp,
                MoveSpeed    = def.MoveSpeed,
                IsFlying     = def.IsFlying,
                FlightHeight = def.FlightHeight,
                LivesCost    = def.LivesCost,
                VisualScale  = 1f,
            };
    }
}