From 0f4593ac7cb8f9d52f347c87617663136abfe35c Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 19 Apr 2026 11:53:51 -0400 Subject: [PATCH] docs(plan): add ActionGroup model -- AND/OR/XOR action grouping at ability level Introduces ActionGroup { LogicOp, ChooserRole, Actions[], Groups[] } to replace the flat Action[] on AbilityDefinition. Mirrors CostGroup pattern. - Axiom A updated: ActionGroup is the ability-level grouping; ChooseOne is the within-action effect-branching mechanism -- distinct and complementary - Axiom B: adds PendingActionGroupPick to the Pending* prompt table - Axiom C renamed to cover ActionGroup + ChooseOne + CostGroup all having ChooserRole - Phase 1.3 (new): ActionGroup model, execution semantics (AND/OR/XOR), and clear distinction from ChooseOne with concrete examples - Phase 1.10: AbilityDefinition gains ActionGroup, marks Actions [Obsolete] with backwards-compat read rule (wrap Actions in And group if ActionGroup null) - Phase 4: ActionGroup node type added to palette, canvas layouts show the ActionGroup container with AND/OR/XOR header and nested Action children; ActionGroup property inspector section added - Phase 5: 5.1a -- ActionGroup recursive descent in the engine Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude Co-Authored-By: Happy --- NewCard-AbilityChange.md | 209 +++++++++++++++++++++++++++++---------- 1 file changed, 157 insertions(+), 52 deletions(-) diff --git a/NewCard-AbilityChange.md b/NewCard-AbilityChange.md index 692c870..488b9e2 100644 --- a/NewCard-AbilityChange.md +++ b/NewCard-AbilityChange.md @@ -25,11 +25,23 @@ Database migrations sit between 1 and 2/3 and must land first. Every layer nests arbitrarily: - CostGroup contains CostEntry leaves and/or child CostGroup nodes (AND/OR/XOR). - ConditionGroup (AND/OR/XOR/NOT) contains leaf conditions and/or child groups. -- Each Action in an AbilityDefinition is either a leaf (Target + Effects) or a ChooseOne - branch selector whose branches each contain their own Action[]. -- Branches may contain further ChooseOne nodes -- no depth limit. +- ActionGroup contains leaf Action nodes and/or child ActionGroup nodes (AND/OR/XOR). + The ability-level action sequence is therefore not a flat list but an ActionGroup tree. +- A leaf Action may additionally carry a ChooseOne, which branches the effects within + that single action step. ChooseOne branches each contain their own Action[]. +- Action[] inside a ChooseOne branch can contain further ChooseOne nodes -- no depth limit. - SearchDeckEffect.ThenAction and ApplyOnEventEffect.Effects are recursive trees. +ActionGroup vs ChooseOne -- these are distinct and complementary: + ActionGroup (ability level): groups multiple top-level action steps with AND/OR/XOR. + AND -- all steps execute sequentially. + OR -- chooser picks one step (or one group) to execute. + XOR -- exactly one step executes, mutually exclusive. + ChooseOne (action level): within a single action step (shared target already resolved), + the chooser picks one effect branch. Suitable for "deal damage OR push" on the same + target. Not suitable for "target an ally and heal them OR target an enemy and damage + them" -- that requires two leaf Actions inside an OR ActionGroup. + The engine processes all of this via recursive descent. ### B. Every Client Decision Must Be Prompted @@ -43,9 +55,10 @@ Prompt categories and their Pending* types: Decision | Pending* Type | Chooser field --------------------------------------------|-------------------------|----------------------------- + Which OR/XOR action group to execute | PendingActionGroupPick | ActionGroup.ChooserRole (NEW) Which OR/XOR cost branch to pay | PendingCostGroupPick | CostGroup.ChooserRole Which specific cards satisfy a cost | PendingCostPick (exist) | CostEntry.PickMode - Which ability branch to take (ChooseOne) | PendingBranchPick | ChooseOne.ChooserRole + Which ChooseOne branch to take | PendingBranchPick | ChooseOne.ChooserRole Which target(s) to assign to an action | PendingTargetPick | TargetSelector.Chooser (NEW) Which tile for token/reposition | PendingTilePick | effect-level Which player for UnderControlOf: Choice | PendingPlayerPick | effect-level @@ -64,7 +77,7 @@ All Pending* types share a common envelope: GameState must be fully serializable mid-resolution so the server survives restarts. -### C. ChooseOne and CostGroup Both Have a ChooserRole +### C. ActionGroup, ChooseOne, and CostGroup All Have a ChooserRole "Self" -- the ability's controlling player chooses "Opponent" -- the opposing player chooses @@ -180,7 +193,56 @@ CostEntry already supports: No changes needed to CostEntry itself. The PickMode and Filters fields already cover all interactive cost scenarios from the spec. -### 1.3 -- Target Selector: Add Chooser Field +### 1.3 -- Action Groups (AND / OR / XOR) + +Current state: AbilityDefinition.Actions is Action[] -- all actions execute sequentially +(implicit AND). There is no ability-level grouping with OR or XOR semantics. + +Gap: the spec requires AND/OR/XOR grouping for the top-level action sequence, with +control over who selects which group executes. + +New type in Action.cs (mirrors CostGroup structure): + + ActionGroup { + LogicOp: ActionGroupLogicOp -- And | Or | Xor + ChooserRole: string = "Self" -- for Or/Xor: who picks which group(s) execute + Actions: Action[] -- leaf actions in this group + Groups: ActionGroup[] -- nested child groups + } + + enum ActionGroupLogicOp { And, Or, Xor } + +Execution semantics: + And -- all leaf Actions and all child Groups execute in order. + Or -- the chooser (ChooserRole) picks exactly one leaf Action or one child Group + to execute. Emits PendingActionGroupPick to the appropriate client. + Xor -- same as Or; the "exclusive" intent is that only one fires and the choices + are truly mutually exclusive (engine enforces; semantically equivalent to Or + from a resolution standpoint). + +AbilityDefinition change: + + // Replace: + public Action[] Actions { get; set; } = []; + // With: + public ActionGroup? ActionGroup { get; set; } + [Obsolete] public Action[] Actions { get; set; } = []; + // Backwards-compat read: if ActionGroup is null and Actions is non-empty, the + // EffectsJson cutover reader wraps Actions in an ActionGroup { LogicOp=And }. + +ChooserRole=Random: server picks one leaf Action or child Group immediately, no prompt. +ChooserRole=Self/Opponent: emit PendingActionGroupPick to the appropriate client with + the list of available choices (labels derived from Action/Group descriptions). + +Relationship to ChooseOne: + ActionGroup (this section): groups multiple independent action steps that may each + have their own distinct targets. "Heal an ally AND draw a card" or "Heal an ally + OR damage an enemy" are ActionGroup expressions. + ChooseOne (existing, on Action): branches the effects within a single action step + after the target is already resolved. "Deal damage OR push" to the same resolved + target is a ChooseOne expression. No model change to ChooseOne needed. + +### 1.4 -- Target Selector: Add Chooser Field In Action.cs, add to TargetSelector: @@ -193,7 +255,7 @@ New enum: Chooser=Random: engine resolves from the filtered pool immediately (no PendingTargetPick). Chooser=Self/Opponent/Ally: engine emits PendingTargetPick to the appropriate client. -### 1.4 -- ChooseOne: Add ChooserRole +### 1.5 -- ChooseOne: Add ChooserRole In Action.cs, add to ChooseOne: @@ -201,7 +263,7 @@ In Action.cs, add to ChooseOne: Values: "Self" | "Opponent" | "Random" -### 1.5 -- Trigger Event Coverage +### 1.6 -- Trigger Event Coverage All 40 trigger events from the spec are already present in Triggers.cs. Full list: @@ -265,7 +327,7 @@ Enrichments needed (not new types, just new fields on existing types): Trigger limit fields already exist: TriggerLimitPerTurn, TriggerLimitPerGame. SourceZoneGate already exists. -### 1.6 -- Condition Additions +### 1.7 -- Condition Additions New conditions to add to Conditions.cs: @@ -291,7 +353,7 @@ Existing composites AND/OR/XOR/NOT already exist -- no changes needed. Existing Comparator enum already has: Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual -- covers all op values from spec. -### 1.7 -- Effect Additions +### 1.8 -- Effect Additions New effects to add to Effects.cs: @@ -325,7 +387,7 @@ Existing effects needing additions: Existing minimal ChannelCardEffect: mark [Obsolete]. The builder emits ChannelCardFromZoneEffect. Old type stays deserializable for the EffectsJson cutover reader. -### 1.8 -- Filter Additions +### 1.9 -- Filter Additions Audit Filters.cs and add any missing: @@ -339,7 +401,7 @@ Audit Filters.cs and add any missing: TileOccupancyFilter -- filter tiles by occupant type/ownership/properties RangeFilter -- target within [Min,Max] tiles of source -### 1.9 -- AbilityDefinition Additions +### 1.10 -- AbilityDefinition Additions // Aura -- per-unit entry/exit action lists (new) public Action[]? OnEnterAuraActions { get; set; } @@ -348,6 +410,12 @@ Audit Filters.cs and add any missing: // Cost (replaces CostEntry[]) public CostGroup? CostGroup { get; set; } + // Action sequence (replaces Action[]) + public ActionGroup? ActionGroup { get; set; } + [Obsolete] public Action[] Actions { get; set; } = []; + // Read rule: if ActionGroup is null and Actions is non-empty, wrap Actions in + // ActionGroup { LogicOp=And } at read time. Cutover tool converts all existing data. + // Existing verified fields (no change needed): // Active: Range (AbilityRange with Min/Max/RequiresLos/LinearOnly) // UsesPerTurn (int = 1) @@ -480,50 +548,70 @@ AbilityBuilder.razor: ### 4.2 -- Node Types - Node type | Color token | Purpose - ------------|-------------|--------------------------------------------- - Meta | blue | Ability name, description, type badge - Range | teal | RangeMin, RangeMax, RequiresLOS, LinearOnly - | (Active only; also UsesPerTurn) - Cost | amber | CostGroup recursive builder (AND/OR/XOR) - Trigger | purple | TriggerEvent type + all event-specific fields - Condition | yellow | ConditionGroup recursive builder (AND/OR/XOR/NOT) - Action | green | TargetSelector (Scope/Type/Ownership/Chooser/Count/Filters) - | + Duration + action-level Conditions + ChooseOne toggle - Effect | red | Specific effect type + parameters (one node per effect) - AuraRange | teal | AuraRange Min/Max (Aura only) - OnEnter | green-dim | OnEnterAuraActions sub-graph (Aura only) - OnLeave | red-dim | OnLeaveAuraActions sub-graph (Aura only) - Animation | grey | AbilityAnimationDefinition: track name, cast sound URL, - | impact sound URL (shown on every ability meta node as - | an expandable section, not a separate node) + Node type | Color token | Purpose + -------------|-------------|--------------------------------------------- + Meta | blue | Ability name, description, type badge + Range | teal | RangeMin, RangeMax, RequiresLOS, LinearOnly + | (Active only; also UsesPerTurn) + Cost | amber | CostGroup recursive builder (AND/OR/XOR) + Trigger | purple | TriggerEvent type + all event-specific fields + Condition | yellow | ConditionGroup recursive builder (AND/OR/XOR/NOT) + ActionGroup | green-dark | LogicOp (AND/OR/XOR) + ChooserRole; contains Action nodes + | and/or nested ActionGroup nodes; replaces flat Action[] + Action | green | Leaf action: TargetSelector (Scope/Type/Ownership/Chooser/ + | Count/Filters) + Duration + action-level Conditions + | + ChooseOne toggle (for within-action effect branching) + Effect | red | Specific effect type + parameters (one node per effect) + AuraRange | teal | AuraRange Min/Max (Aura only) + OnEnter | green-dim | OnEnterAuraActions sub-graph (Aura only) + OnLeave | red-dim | OnLeaveAuraActions sub-graph (Aura only) + Animation | grey | AbilityAnimationDefinition: track name, cast sound URL, + | impact sound URL (expandable section on Meta node, not + | a separate draggable node) ### 4.3 -- Node Layout Per Ability Type Active ability (left to right): - [Meta + Range + UsesPerTurn] --> [Cost?] --> [ActivationCondition?] --> [Action 1..N] - | - [Effect 1..N] + [Meta + Range + UsesPerTurn] --> [Cost?] --> [ActivationCondition?] --> [ActionGroup] + | + [AND/OR/XOR header] + / \ + [Action 1] [Action 2] + | | + [Effect 1..N] [Effect 1..N] Triggered ability: - [Meta] --> [Trigger] --> [TriggerCondition?] --> [Action 1..N] - | - [Effect 1..N] + [Meta] --> [Trigger] --> [TriggerCondition?] --> [ActionGroup] + | + [AND/OR/XOR header] + / \ + [Action 1] [Action N] + | + [Effect 1..N] Passive ability: - [Meta] --> [ActivationCondition?] --> [Action 1..N] - | - [Effect 1..N] + [Meta] --> [ActivationCondition?] --> [ActionGroup] + | + [AND header (implicit)] + | + [Action 1..N] Aura ability: - [Meta] --> [AuraRange] --> [ActivationCondition?] --> [Action 1..N (while in range)] - | - [OnEnter sub-graph] [Effect 1..N] - [OnLeave sub-graph] + [Meta] --> [AuraRange] --> [ActivationCondition?] --> [ActionGroup (while in range)] + [OnEnter ActionGroup] + [OnLeave ActionGroup] -The Meta node for Active abilities includes the Range and UsesPerTurn fields inline -(not as a separate node) to reduce visual noise for simple abilities. A "Expand Range" -toggle shows the full Range sub-form when needed. +ActionGroup visual representation: + The ActionGroup node renders as a bordered container with: + - A header bar showing LogicOp (AND / OR / XOR) and ChooserRole + - Child Action nodes and nested ActionGroup nodes inside the container + - An "Add Action" button and an "Add Group" button in the footer + - Connections between ActionGroup and its children are shown as containment + (dashed border), not as separate edge lines, to distinguish from targeting connections + +The Meta node for Active abilities includes Range and UsesPerTurn inline (not a separate +node) to reduce visual noise for simple abilities. An "Expand Range" toggle reveals the +full Range sub-form when needed. ### 4.4 -- Canvas Mechanics @@ -579,11 +667,19 @@ Cost node (recursive CostGroupEditor component): - "Add Cost" button (adds leaf CostEntry) - "Add Group" button (nests a child CostGroup) -Action node fields: +ActionGroup node fields (recursive ActionGroupEditor component): + - LogicOp selector: AND / OR / XOR + - For OR/XOR: ChooserRole: Self / Opponent / Random + - Child list: each child is either a leaf Action or a nested ActionGroup + - "Add Action" button (adds leaf Action) + - "Add Group" button (nests a child ActionGroup) + +Action node fields (leaf; always lives inside an ActionGroup): + - Label (optional, shown as the choice text when parent ActionGroup is OR/XOR) - Target: Scope -> Type -> Ownership -> Chooser -> Count (N / UpTo / All) -> Filters - Duration picker - Conditions (ConditionGroupEditor component) - - ChooseOne toggle: + - ChooseOne toggle (within-action effect branching): Off: direct Effect list On: branch list; each branch has Label + nested Action list (recursive) ChooserRole: Self / Opponent / Random @@ -622,12 +718,19 @@ Condition group editor (ConditionGroupEditor component, recursive): Each item is independently mergeable after Phase 1 lands. 5.1 Full interactive resolution protocol - Add PendingCostGroupPick, PendingBranchPick, PendingTilePick, - PendingPlayerPick, PendingRevealChoicePick. + Add PendingActionGroupPick, PendingCostGroupPick, PendingBranchPick, + PendingTilePick, PendingPlayerPick, PendingRevealChoicePick. All Pending* states serializable as part of GameState. Enforce TimeoutMs with server-side Random fallback. Wire TargetSelector.Chooser into PendingTargetPick emission logic. + 5.1a ActionGroup resolution + Replace flat Action[] iteration with recursive ActionGroup descent. + AND: execute all children sequentially. + OR/XOR: emit PendingActionGroupPick (ChooserRole=Self/Opponent) or + pick randomly (ChooserRole=Random); resume after client responds. + Backwards-compat: if ActionGroup is null, wrap Actions[] in And group. + 5.2 ChooseOne.ChooserRole resolution Opponent -> emit PendingBranchPick to opponent client Random -> server picks immediately @@ -701,9 +804,11 @@ Phase 5 sub-items are independently mergeable once Phase 1 is in. File | Action --------------------------------------------------|-------------------------------------------- - SOR.Game/Abilities/Models/Action.cs | Add CostGroup, TargetChooser, ChooseOne.ChooserRole - SOR.Game/Abilities/Models/AbilityDefinition.cs | Add CostGroup, OnEnterAuraActions, OnLeaveAuraActions; - | verify Range/UsesPerTurn fields exist + SOR.Game/Abilities/Models/Action.cs | Add ActionGroup, ActionGroupLogicOp, CostGroup, + | TargetChooser, ChooseOne.ChooserRole + SOR.Game/Abilities/Models/AbilityDefinition.cs | Add ActionGroup, CostGroup, OnEnterAuraActions, + | OnLeaveAuraActions; verify Range/UsesPerTurn exist; + | mark Actions [Obsolete] SOR.Game/Abilities/Models/Conditions.cs | Add 12 new condition types (s1.6) SOR.Game/Abilities/Models/Triggers.cs | Add UnitFilters, OccupantFilters, | CardDefinitionId, AmountComparator fields (s1.5)