namespace SOR.Game.Abilities.Models; /// Ability type determines activation model and required fields. public enum AbilityType { /// Manually activated by the controlling player. Costs optional range and UsesPerTurn. Active, /// Always active while the unit is in play and conditions are met. No activation, no cost. Passive, /// Always-on area effect anchored to a unit's position. Evaluated per-turn and on unit entry. Aura, /// Automatically fires when a matching TriggerEvent occurs. Triggered, } /// /// The top-level definition of a unit ability or card effect. /// Stored as JSONB in CardDefinition.AbilitiesJson (array) and CardDefinition.EffectsJson. /// /// All four ability types share the Action/Effect/Condition model. /// Type-specific fields are non-null only for the relevant type. /// public sealed class AbilityDefinition { public AbilityType Type { get; set; } public Condition[]? ActivationConditions { get; set; } public Action[] Actions { get; set; } = []; // ── Active only ────────────────────────────────────────────────────────── public CostEntry[]? Cost { get; set; } public AbilityRange? Range { get; set; } /// How many times this Active ability may be used per turn (default 1). public int UsesPerTurn { get; set; } = 1; // ── Aura only ──────────────────────────────────────────────────────────── public AbilityRange? AuraRange { get; set; } /// /// When true, effects applied by this aura to a unit are reverted immediately when that /// unit leaves range. Default false: effects expire at their configured Duration. /// Ignored when is set. /// public bool ClearOnLeave { get; set; } /// /// If set, effects switch to this duration when a unit leaves range instead of /// being reverted immediately. Takes precedence over . /// Null means effects expire at their own configured Duration. /// public DurationModel? LingerDuration { get; set; } // ── Triggered only ─────────────────────────────────────────────────────── /// The event that fires this ability. Must be set for Triggered type. public TriggerEvent? TriggerEvent { get; set; } /// /// Optional display name shown in the admin tool and client ability list. /// Not required for game logic. /// public string? Name { get; set; } /// /// Plain-English description of what this ability does. /// Used in the admin ability builder. Not used by game logic. /// public string? Description { get; set; } /// /// Optional ability-level duration that overrides per-action Duration for every effect /// this ability produces. When null, each Action's own Duration is used instead. /// /// For Passive abilities this defaults to WhileSourceOnBattlefield when left null; /// set it explicitly to choose a different lifespan (e.g. UntilEndOfTurn). /// public DurationModel? Duration { get; set; } /// /// Optional client-side animation and sound metadata. /// Not used by server game logic. Null means the client uses its default effect. /// public AbilityAnimationDefinition? Animation { get; set; } }