add-interactive-effect

Adding an Interactive Effect

Interactive effects pause game resolution to wait for player input, then resume. Examples: Scry (choose top/bottom), Dig (choose cards to keep), Surveil (choose graveyard/library), Search (choose from library), Reveal+Choose (pick opponent's card).

The core mechanism is the continuation pattern: resolve_ability_chain() detects a waiting state, stashes remaining sub-abilities in pending_continuation, and returns. When the player responds, engine.rs resumes the chain.

Before you start: Trace Scry end-to-end as the simplest example:

• Resolver: effects/scry.rs — sets WaitingFor::ScryChoice
• Engine handler: engine.rs — (WaitingFor::ScryChoice, GameAction::SelectCards) arm
• Continuation: pending_continuation resumed after player selects
• AI: legal_actions.rs — generates legal card selections
• Frontend: CardChoiceModal → ScryModal

CR Verification Rule: Every CR number in annotations MUST be verified by grepping docs/MagicCompRules.txt before writing. Do NOT rely on memory — 701.x and 702.x numbers are arbitrary sequential assignments that LLMs consistently hallucinate. Run grep -n "^701.22" docs/MagicCompRules.txt (etc.) for every number. If you cannot find it, do not write the annotation.

---

The Continuation Pattern

This is the most important architectural concept for interactive effects.

Problem

A card says "Scry 2, then draw a card." This is parsed as Scry { count: 2 } with sub_ability: Draw { count: 1 }. But Scry requires player input — the engine can't just barrel through to Draw.

Solution: pending_continuation

resolve_ability_chain(ability) called:
    ↓
resolve_effect(Scry) → sets state.waiting_for = ScryChoice
    ↓
resolve_ability_chain detects waiting state:
    Has sub_ability (Draw)?
        YES → store as state.pending_continuation
        Return Ok(()) — chain paused
    ↓
[Player makes scry selection via GameAction::SelectCards]
    ↓
engine.rs handler processes the selection
    ↓
Check state.pending_continuation.take():
    Some(continuation) → resolve_ability_chain(continuation)
    None → return to Priority