Files
sor/Server/src/SOR.Game/Abilities/Models/Action.cs
T
3b8de2deac feat(phase1): ability model expansion -- ActionGroup, CostGroup, new conditions/effects/filters
Action.cs:
  - TargetChooser enum (Self/Opponent/Ally/Random) + TargetSelector.Chooser field
    separates "whose entities qualify" from "who makes the selection"
  - ActionGroup { LogicOp(And/Or/Xor), ChooserRole, Actions[], Groups[] }
    replaces flat Action[] on AbilityDefinition; supports recursive AND/OR/XOR
  - ActionGroupLogicOp enum
  - CostGroup { LogicOp(And/Or/Xor), ChooserRole, Entries[], Groups[] }
    replaces flat CostEntry[] on AbilityDefinition
  - CostGroupLogicOp enum
  - ChooseOne.ChooserRole (within-action effect branching chooser)

AbilityDefinition.cs:
  - ActionGroup? (replaces Actions[]; old field kept [Obsolete] for migration reads)
  - CostGroup? (replaces Cost[]; old field kept [Obsolete] for migration reads)
  - OnEnterAuraActions / OnLeaveAuraActions (ActionGroup? each)

Triggers.cs:
  - OnChanneledTrigger.CardDefinitionId (specific card filter)
  - OnRuinActivationTrigger.OccupantFilters / OnUnitOccupyRuinTrigger.OccupantFilters
  - AmountComparator (Comparator enum) on OnDamageDealtTrigger, OnDamagePreventedTrigger,
    OnHealedTrigger, BeforeDamageAppliedTrigger, OnUnitMPSpentTrigger

Conditions.cs: 12 new condition types (UnitTypeIs, OwnershipIs, IsThisCard,
  UnitPropertyCompare, PlayerPropertyCompare, HandContainsCount,
  CardDefinitionCountInZone, IsInRangeOfUnit, TileOccupant, SurroundingTile,
  SPAccumulationCompare, CostOfCardsInHand)

Effects.cs: 16 new effect types across ArchSpirit zone ops (AscendFromZone,
  TransitionFromZone, ModifyChannelRange), Ruin ops (RelocateRuin,
  ActivateRuinAbility, DisableRuinForDuration), enhanced channeling
  (ChannelCardFromZone), token/spirit (CloneSpiritAsToken, DestroyToken,
  ModifySacrificeTokenReturn), player (SkipTurn, ModifyCardsDrawnThisTurn),
  zone (StackDeck, SearchAndPlace), unit (ChangeAttackType, ObstructMovementType).
  PreventDeathEffect + PreventNextDamageEffect extended with new fields.

Filters.cs: 3 new filter types (Ownership, UnitProperty, TileOccupancy)

AbilitySystem.cs + ActionCandidateGenerator.cs: #pragma disable CS0618 --
  authorized readers of backwards-compat obsolete fields

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
2026-04-19 12:35:55 -04:00

246 lines
11 KiB
C#

namespace SOR.Game.Abilities.Models;
// ── Value expression ──────────────────────────────────────────────────────────
/// <summary>
/// An integer value that may be a fixed constant or a dynamic runtime reference.
/// Dynamic references (§4.5) use dot-path notation, e.g.:
/// "EventData.Amount", "Self.Damage", "Action1.Target.Defense"
/// </summary>
public sealed class ValueExpr
{
public int? Fixed { get; set; }
public string? Ref { get; set; }
[System.Text.Json.Serialization.JsonIgnore]
public bool IsDynamic => Ref is not null;
public static implicit operator ValueExpr(int n) => new() { Fixed = n };
}
/// <summary>
/// An affinity value that may be fixed or a dynamic reference.
/// E.g.: "Self.Affinity", "Action1.Target.Affinity".
/// </summary>
public sealed class AffinityExpr
{
public SOR.Database.Enums.Affinity? Fixed { get; set; }
public string? Ref { get; set; }
}
// ── Target selector ───────────────────────────────────────────────────────────
public enum TargetScope { Hand, Deck, Discard, Battlefield, Player, AnyZone }
public enum TargetType { Unit, ArchSpirit, Spirit, SpiritToken, Ruin, Tile, Card, Player }
public enum TargetOwnership { Self, ExactSelf, Owner, Ally, Enemy, Any, Random, Target }
/// <summary>
/// Who makes the selection from the valid target pool.
/// Distinct from <see cref="TargetOwnership"/>, which filters whose entities qualify.
/// </summary>
public enum TargetChooser { Self, Opponent, Ally, Random }
public sealed class TargetCount
{
/// <summary>Exact number of targets; or the maximum when UpTo=true.</summary>
public int N { get; set; } = 1;
/// <summary>Player may select fewer than N valid targets.</summary>
public bool UpTo { get; set; }
/// <summary>Target all valid entities (N is ignored).</summary>
public bool All { get; set; }
}
/// <summary>
/// Defines how targets are resolved for a single Action.
/// Scope + Type + Ownership narrow the pool; Filters refine further.
/// </summary>
public sealed class TargetSelector
{
public TargetScope Scope { get; set; }
public TargetType Type { get; set; }
/// <summary>Filters whose entities qualify as valid targets.</summary>
public TargetOwnership Ownership { get; set; }
/// <summary>
/// Who makes the selection from the valid target pool.
/// Self/Opponent/Ally emits a <c>PendingTargetPick</c> to the appropriate client.
/// Random resolves immediately server-side with no client prompt.
/// </summary>
public TargetChooser Chooser { get; set; } = TargetChooser.Self;
public TargetCount Count { get; set; } = new();
public Filter[]? Filters { get; set; }
}
// ── Action ────────────────────────────────────────────────────────────────────
/// <summary>
/// The atomic unit of targeting and effect delivery within an ability.
/// All effects within one action share the same target and duration.
/// Actions within an ability resolve sequentially; a prior action's resolved
/// target is accessible in subsequent actions via chained targeting filters.
/// </summary>
public sealed class Action
{
public TargetSelector Target { get; set; } = new();
public Condition[]? Conditions { get; set; }
public Effect[] Effects { get; set; } = [];
public DurationModel? Duration { get; set; }
/// <summary>
/// When non-null this Action is a branch selector — <see cref="Effects"/> are ignored.
/// The controlling player picks one <see cref="Branch"/>; its <see cref="Branch.Actions"/>
/// execute instead. Set <see cref="AbilityTarget.BranchIndex"/> in the client payload
/// to indicate which branch was chosen (0-based; defaults to 0 if absent).
/// Branch sub-actions are auto-resolved (no nested client targeting required).
/// </summary>
public ChooseOne? ChooseOne { get; set; }
}
// ── ChooseOne ─────────────────────────────────────────────────────────────────
/// <summary>
/// Within a single action step (target already resolved), presents a set of mutually
/// exclusive effect branches. Exactly one branch is selected; others are skipped.
/// Use for "deal damage OR push the same target." For grouping distinct action steps
/// with different targets, use <see cref="ActionGroup"/> instead.
/// </summary>
public sealed class ChooseOne
{
public Branch[] Branches { get; set; } = [];
/// <summary>
/// Who selects the branch.
/// "Self" = controlling player, "Opponent" = opposing player, "Random" = server picks.
/// </summary>
public string ChooserRole { get; set; } = "Self";
}
public sealed class Branch
{
public string Label { get; set; } = string.Empty;
public Action[] Actions { get; set; } = [];
}
// ── ActionGroup ───────────────────────────────────────────────────────────────
/// <summary>
/// Logical grouping of ability-level action steps with AND / OR / XOR semantics.
/// Replaces the flat <c>Action[]</c> on <see cref="AbilityDefinition"/>.
///
/// AND — all children execute sequentially (same as the old flat list).
/// OR — the chooser picks exactly one child (leaf Action or nested group) to execute;
/// emits <c>PendingActionGroupPick</c> when ChooserRole is Self or Opponent.
/// XOR — same resolution as OR; signals mutually-exclusive design intent.
///
/// Groups can nest arbitrarily. The engine descends recursively.
/// </summary>
public sealed class ActionGroup
{
public ActionGroupLogicOp LogicOp { get; set; } = ActionGroupLogicOp.And;
/// <summary>
/// For OR/XOR: who selects which child executes.
/// "Self" / "Opponent" emits PendingActionGroupPick. "Random" resolves server-side.
/// </summary>
public string ChooserRole { get; set; } = "Self";
/// <summary>Leaf action steps in this group.</summary>
public Action[] Actions { get; set; } = [];
/// <summary>Nested child groups. Evaluated after leaf Actions in AND mode; same pool as Actions in OR/XOR.</summary>
public ActionGroup[] Groups { get; set; } = [];
}
public enum ActionGroupLogicOp { And, Or, Xor }
// ── Cost entry ────────────────────────────────────────────────────────────────
public enum CostType
{
SpiritPoints,
SacrificeTokens,
DiscardFromHand,
MillTopOfDeck,
MillBottomOfDeck,
SendSpiritFromBattlefieldToDiscard,
DealDamageToOwnArchSpirit,
DealDamageToOwnSpirit,
}
/// <summary>
/// How the player(s) resolve the selection for an interactive cost (e.g. DiscardFromHand).
/// Null / absent: server auto-resolves (picks first N valid candidates).
/// </summary>
public enum CostPickMode
{
/// <summary>Server picks randomly from valid candidates.</summary>
Random,
/// <summary>Controlling player sees and picks which cards to pay.</summary>
SelfPick,
/// <summary>Opponent picks on behalf of the controlling player (sees all options).</summary>
EnemySeePick,
/// <summary>Opponent picks randomly from the controlling player's valid candidates.</summary>
EnemyRandomPick,
/// <summary>Opponent has free choice of which cards the controlling player pays.</summary>
EnemyPick,
}
/// <summary>
/// A single cost element for an Active ability.
/// Multiple CostEntry items must all be paid simultaneously before the ability resolves.
/// </summary>
public sealed class CostEntry
{
public CostType Type { get; set; }
public int Amount { get; set; } = 1;
/// <summary>Optional filter for targeted costs (e.g. "Discard a Spirit card from hand").</summary>
public Filter[]? Filters { get; set; }
/// <summary>
/// When set, the cost resolution is interactive: a player (controlling or opponent)
/// is prompted to pick which specific cards/units satisfy the cost.
/// Null = auto-resolve (engine picks first N matching candidates).
/// </summary>
public CostPickMode? PickMode { get; set; }
}
// ── CostGroup ─────────────────────────────────────────────────────────────────
/// <summary>
/// Logical grouping of ability costs with AND / OR / XOR semantics.
/// Replaces the flat <c>CostEntry[]</c> on <see cref="AbilityDefinition"/>.
///
/// AND — all entries must be paid (same as the old flat array).
/// OR — the chooser selects one entry or child group to pay;
/// emits <c>PendingCostGroupPick</c> when ChooserRole is Self or Opponent.
/// XOR — same resolution as OR; signals mutually-exclusive design intent.
///
/// Groups can nest arbitrarily. Example: (pay 2 SP AND discard 1 card) OR (pay 6 SP).
/// </summary>
public sealed class CostGroup
{
public CostGroupLogicOp LogicOp { get; set; } = CostGroupLogicOp.And;
/// <summary>
/// For OR/XOR: who selects which option is paid.
/// "Self" / "Opponent" emits PendingCostGroupPick. "Random" resolves server-side.
/// </summary>
public string ChooserRole { get; set; } = "Self";
/// <summary>Leaf cost entries in this group.</summary>
public CostEntry[] Entries { get; set; } = [];
/// <summary>Nested child groups. In AND mode all pay; in OR/XOR the chooser picks one.</summary>
public CostGroup[] Groups { get; set; } = [];
}
public enum CostGroupLogicOp { And, Or, Xor }
// ── Ability range ─────────────────────────────────────────────────────────────
public sealed class AbilityRange
{
public int Min { get; set; } = 1;
public int Max { get; set; } = 1;
/// <summary>
/// When true, the engine validates that a clear line of sight exists between the
/// caster and the target tile/unit before allowing the ability to be used.
/// </summary>
public bool RequiresLos { get; set; } = false;
/// <summary>
/// When true, only targets that lie on a straight cardinal or diagonal line from
/// the caster are valid (e.g. Push, Pull, beam-style abilities).
/// </summary>
public bool LinearOnly { get; set; } = false;
}