// Assets/_Project/Scripts/Core/PoolWeightAttribute.cs
using UnityEngine;

namespace TD.Core
{
    /// <summary>
    /// Marks a float field as a 0–1 <b>relative</b> draw weight inside an authored pool. The
    /// inspector renders it as a slider and, when the value is zero, shows a warning directly
    /// beneath explaining that the entry can never be drawn.
    /// </summary>
    /// <remarks>
    /// <b>Relative, not absolute.</b> Weights are normalized against the summed weight of the
    /// candidate set at draw time, so entries at equal weight are equally likely and an entry at
    /// 0.5 is half as likely as one at 1.0. This is why every weight field defaults to 1 —
    /// adding an entry to a pool then never silently re-weights the entries already in it.
    ///
    /// <para><b>The warning is advisory.</b> Muting an entry while tuning is a legitimate
    /// workflow, so the drawer never clamps the value or blocks the edit. It exists because a
    /// zero-weight entry is otherwise indistinguishable, in play, from one that simply hasn't come
    /// up yet — the failure is silent, so the authoring surface has to be loud.</para>
    /// </remarks>
    public class PoolWeightAttribute : PropertyAttribute
    {
        /// <summary>
        /// Noun used in the zero-weight warning ("this <c>wave</c> can never be drawn"). Keep it
        /// singular and lowercase.
        /// </summary>
        public readonly string Noun;

        public PoolWeightAttribute(string noun = "entry")
        {
            Noun = string.IsNullOrWhiteSpace(noun) ? "entry" : noun;
        }
    }
}