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 <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
dingo
2026-04-19 11:53:51 -04:00
co-authored by Claude Happy
parent 3b37b15ff0
commit 0f4593ac7c
+157 -52
View File
@@ -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)