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:
+157
-52
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user