namespace AcDream.Core.Spells;

/// <summary>
/// Per-spell static metadata loaded once at startup from
/// <c>docs/research/data/spells.csv</c> via <see cref="SpellTable"/>.
/// One record per known spell id (3,956 entries in the retail dump).
///
/// <para>
/// Used for:
/// </para>
/// <list type="bullet">
///   <item>Buff / debuff bar labels (<see cref="Name"/>,
///         <see cref="School"/>, <see cref="IconId"/>).</item>
///   <item>Stacking aggregation (<see cref="Family"/> — only one
///         enchantment per family-bucket is active; this is what
///         <c>EnchantmentMath</c> uses to filter out superseded
///         buffs in <c>LocalPlayerState.GetMaxApprox</c>).</item>
///   <item>Spell tooltips (<see cref="Description"/>,
///         <see cref="ManaCost"/>, <see cref="Duration"/>,
///         <see cref="SpellWords"/>).</item>
///   <item>Cast-bar audio + animation cues
///         (<see cref="SpellWords"/> drives the chant).</item>
/// </list>
///
/// <para>
/// Fields not exposed (yet) from the 35-column source CSV: SortKey,
/// Difficulty, Flags, Generation, IsFastWindup, IsIrresistible,
/// IsOffensive, IsUntargetted, Speed, CasterEffect, TargetEffect,
/// TargetMask, Type, plus 10 anonymous Unknown1..10. Add them on
/// demand as panels grow.
/// </para>
/// </summary>
public sealed record SpellMetadata(
    uint   SpellId,
    string Name,
    string School,
    uint   Family,
    uint   IconId,
    string SpellWords,
    float  Duration,
    int    ManaCost,
    bool   IsDebuff,
    bool   IsFellowship,
    string Description);