add-trigger

Adding a Triggered Ability

Triggered abilities fire in response to game events and go on the stack (MTG Rule 603). They differ from replacement effects (which modify events) and static abilities (which exist continuously). This skill covers the full trigger pipeline: event fired → matcher detects → APNAP ordering → targeting → stack → resolution.

Before you start: Trace how ChangesZone (ETB/dies) triggers work end-to-end. They're the most complete reference: parse_trigger_line() in oracle_trigger.rs → TriggerDefinition → process_triggers() → match_changes_zone() → stack placement → resolve_top().

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 "^603.2" docs/MagicCompRules.txt (etc.) for every number. If you cannot find it, do not write the annotation.

---

MTG Rules Reference

Rule	What it governs	Engine implication
603.2	A triggered ability triggers when its event occurs	process_triggers() scans all permanents against the event
603.3	Triggered abilities are placed on the stack (APNAP order)	Sort by (is_nap, timestamp) before stack placement
603.3b	Active player's triggers go on stack first (resolve last)	NAP triggers pushed after AP triggers
603.4	Intervening-if checked at fire-time AND resolution-time	TriggerCondition checked in both process_triggers() and resolve_top()
603.5	Triggered abilities target when placed on stack	extract_target_filter_from_effect() → targeting phase before stack
603.6c	"Once each turn" constraint	TriggerConstraint::OncePerTurn tracked in triggers_fired_this_turn

---

Key Types

TriggerDefinition — crates/engine/src/types/ability.rs

pub struct TriggerDefinition {
    pub mode: TriggerMode,                    // Event type: ChangesZone, DamageDone, SpellCast, etc.
    pub execute: Option<Box<AbilityDefinition>>, // Effect to run when triggered
    pub valid_card: Option<TargetFilter>,      // Filter on the event subject ("another creature")
    pub origin: Option<Zone>,                  // For zone changes: from where
    pub destination: Option<Zone>,             // For zone changes: to where
    pub trigger_zones: Vec<Zone>,             // Active zones (default: Battlefield)
    pub phase: Option<Phase>,                 // For phase triggers (Upkeep, End, etc.)
    pub optional: bool,                       // "You may" triggers
    pub combat_damage: bool,                  // Combat damage only filter
    pub secondary: bool,                      // Multi-target secondary indicator
    pub valid_target: Option<TargetFilter>,   // Controller filter for events (You, Opponent)
    pub valid_source: Option<TargetFilter>,   // Source filter for damage/spell triggers
    pub description: Option<String>,          // Human-readable text
    pub constraint: Option<TriggerConstraint>, // OncePerTurn, OncePerGame, OnlyDuringYourTurn
    pub condition: Option<TriggerCondition>,   // Intervening-if condition
}