enjine 0.1.0

data/docs/reference/triggers.md

@@ -0,0 +1,797 @@
+# Trigger conditions
+
+<!-- Generated by `rake docs` from the primitive registry. Do not edit. -->
+
+## ability_triggers
+
+A triggered ability of the subject triggers. `cause: "attacks"` (required): its trigger event was the subject attacking. {"triggering": "ability"} is that triggered ability while it's on the stack.
+
+Rules: CR 603.2, CR 603.3b, CR 508.1, CR 707.10
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, "controller": ..., "other": true} |
+| `cause` | attacks |
+
+```json
+{
+  "ability_triggers": {
+    "subject": {
+      "each": "creature",
+      "controller": "you"
+    },
+    "cause": "attacks"
+  }
+}
+```
+
+## activates_ability
+
+A player (`controller`: you (default) | opponent | any) activates an ability that isn't a mana ability. `source`: optional filter on the source's card; `name: "chosen"`: only a source with the name chosen as this permanent entered. `exhaust: true`: only an exhaust ability ("whenever you activate an exhaust ability", CR 702.177). `boast: true`: only a boast ability ("whenever a creature you control boasts", CR 702.142b).
+
+Rules: CR 602.2, CR 605.1a, CR 603.2, CR 201.4, CR 702.177a, CR 702.142b
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+| `source` | card filter |
+| `name` | "chosen" |
+| `exhaust` | true: only exhaust abilities |
+| `boast` | true: only boast abilities |
+
+```json
+{
+  "activates_ability": {
+    "controller": "opponent"
+  }
+}
+```
+
+## airbends
+
+A player (`controller`: you (default) | opponent | any) airbends.
+
+Rules: CR 701.65b
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "airbends": {}
+}
+```
+
+## any_of
+
+Triggers when any of the listed trigger conditions is met.
+
+Rules: CR 603.2, CR 603.2c
+
+| Parameter | Description |
+| --- | --- |
+| `(list)` | two or more trigger conditions |
+
+```json
+{
+  "any_of": [
+    {
+      "enters": {}
+    },
+    {
+      "attacks": {}
+    }
+  ]
+}
+```
+
+## attacks
+
+The subject is declared as an attacker. `first_time_this_turn: true`: only the first time that creature attacks this turn (later combats of the turn don't trigger it).
+
+Rules: CR 508.3a, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+| `first_time_this_turn` | boolean |
+
+```json
+{
+  "attacks": {
+    "subject": "self",
+    "first_time_this_turn": true
+  }
+}
+```
+
+## becomes_blocked
+
+The subject becomes blocked: once per combat when blockers are declared, even if several creatures block it.
+
+Rules: CR 509.3c, CR 509.1h, CR 603.2e
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+
+```json
+{
+  "becomes_blocked": {
+    "subject": "self"
+  }
+}
+```
+
+## becomes_crewed
+
+A crew ability of the subject resolves (it becomes crewed).
+
+Rules: CR 702.122e, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+
+```json
+{
+  "becomes_crewed": {}
+}
+```
+
+## becomes_level
+
+This permanent's level becomes `level` (a class level bar's ability resolves).
+
+Rules: CR 717.2a, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `level` | integer >= 2 |
+
+```json
+{
+  "becomes_level": {
+    "level": 3
+  }
+}
+```
+
+## becomes_saddled
+
+The subject becomes saddled (its saddle ability resolved, or an effect saddled it).
+
+Rules: CR 702.171b, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+
+```json
+{
+  "becomes_saddled": {}
+}
+```
+
+## becomes_tapped
+
+The subject becomes tapped (for any reason: a cost, attacking, an effect). A permanent that enters tapped doesn't become tapped. `for: "teamwork"`: only when it's tapped to pay a teamwork cost (it triggers once the spell is cast).
+
+Rules: CR 603.2e, CR 701.26a, CR 702.194a
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+| `for` | teamwork |
+
+```json
+{
+  "becomes_tapped": {
+    "subject": "self"
+  }
+}
+```
+
+## becomes_target
+
+The subject becomes the target of a spell or ability (controlled by `by`: opponent | you | any (default), relative to the source's controller). One trigger per matching object targeted.
+
+Rules: CR 115.1, CR 601.2c, CR 603.2, CR 603.2c
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+| `by` | opponent | you | any |
+
+```json
+{
+  "becomes_target": {
+    "subject": {
+      "each": "creature",
+      "controller": "you"
+    },
+    "by": "opponent"
+  }
+}
+```
+
+## becomes_untapped
+
+The subject becomes untapped (in the untap step or by an effect). A permanent that enters untapped doesn't become untapped.
+
+Rules: CR 603.2e, CR 701.26b
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default), "attached" or {"each": filter, ...} |
+
+```json
+{
+  "becomes_untapped": {
+    "subject": "attached"
+  }
+}
+```
+
+## blocks
+
+The subject is declared as a blocker. With `blocking`, only when the attacking creature it blocks matches that filter ("blocks a creature with flying"). {"triggering": "object"} is the blocking creature.
+
+Rules: CR 509.3a, CR 509.3b, CR 509.3f, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+| `blocking` | filter |
+
+```json
+{
+  "blocks": {
+    "blocking": {
+      "creature": {
+        "keywords": [
+          "flying"
+        ]
+      }
+    }
+  }
+}
+```
+
+## cast
+
+A player casts a spell. `controller`: you (default) | opponent | any; `spell`: creature | noncreature | instant_or_sorcery, or any spell filter, e.g. {"spell": {"subtypes": ["saga"]}} or {"one_of": [...]} for "creature or Spacecraft spell"; `name` / `mana_value`: "chosen" (the source's as-it-entered choice); `self: true`: "when you cast this spell" (it functions on the stack). `targets`: only a spell that targets something matching this filter ("self": this permanent), e.g. {"creature": {"controller": "you"}}. `from` / `not_from`: only a spell cast from (not from) that zone: hand | graveyard | exile | library | outside. `single_target: true`: only a spell with exactly one target.
+
+Rules: CR 603.2, CR 601.2i, CR 113.6, CR 202.3e, CR 201.4, CR 607.2, CR 115.1, CR 601.2a, CR 601.2c
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+| `spell` | creature | noncreature | instant_or_sorcery | filter |
+| `name` | "chosen" |
+| `mana_value` | "chosen" |
+| `self` | true |
+| `targets` | "self" or a target filter |
+| `from` | zone |
+| `not_from` | zone |
+| `single_target` | true |
+
+```json
+{
+  "cast": {
+    "controller": "you",
+    "spell": "noncreature"
+  }
+}
+```
+
+## counters_placed
+
+One or more counters (only `counter`, if given) are put on the subject, including the counters it enters the battlefield with. Triggers once per event, however many counters.
+
+Rules: CR 122.6, CR 603.2, CR 603.2c
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+| `counter` | counter name |
+| `first_time_this_turn` | true: only the first time each turn such counters are put on that permanent (an earlier placement counts even if nothing could trigger then) |
+
+```json
+{
+  "counters_placed": {
+    "counter": "+1/+1"
+  }
+}
+```
+
+## crews_vehicle
+
+The subject (a creature) crews a Vehicle: it's tapped to pay that Vehicle's crew cost. {"triggering": "object"} is the Vehicle.
+
+Rules: CR 702.122b, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+
+```json
+{
+  "crews_vehicle": {
+    "subject": "self"
+  }
+}
+```
+
+## cycles
+
+A player (`controller`: you (default) | opponent | any) cycles a card (activates its cycling or typecycling ability; optional `card` filter).
+
+Rules: CR 702.29a, CR 702.29e
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+| `card` | card filter |
+
+```json
+{
+  "cycles": {
+    "controller": "you"
+  }
+}
+```
+
+## deals_damage
+
+The subject deals damage. `combat: true` only counts combat damage, `noncombat: true` only noncombat damage; `to`: player | opponent (of the source's controller) | creature | any (default). Triggers once per damage event (each combat damage step is one, so double strike can trigger twice).
+
+Rules: CR 510.2, CR 603.2, CR 603.2c, CR 120.2a, CR 120.2b, CR 120.3
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+| `combat` | true | false |
+| `noncombat` | true | false |
+| `to` | player | opponent | creature | any |
+
+```json
+{
+  "deals_damage": {
+    "combat": true,
+    "to": "player"
+  }
+}
+```
+
+## dealt_damage
+
+Damage is dealt to the `subject` (a permanent: "self" by default, "attached" or {"each": filter, ...}) or, with `player` (you | opponent | any), to a player. `combat` / `noncombat`: only that damage. {"triggering": "object"} is the permanent dealt damage, {"triggering": "player"} the player, {"triggering": "amount"} how much. `batched: true`: "one or more ..." (once per damage event, CR 603.2c).
+
+Rules: CR 120.3, CR 603.2, CR 603.2c, CR 120.2a, CR 120.2b
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default), "attached" or {"each": filter, ...} |
+| `player` | you | opponent | any |
+| `combat` | true | false |
+| `noncombat` | true | false |
+| `batched` | true | false |
+
+```json
+{
+  "dealt_damage": {
+    "subject": "self"
+  }
+}
+```
+
+## dies
+
+The subject is put into a graveyard from the battlefield. Looks back in time (CR 603.10a).
+
+Rules: CR 603.6c, CR 603.10a, CR 700.4
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+
+```json
+{
+  "dies": {
+    "subject": "self"
+  }
+}
+```
+
+## discards
+
+A player (`controller`: you (default) | opponent | any) discards a card (optional `card` filter). `batched: true`: "one or more cards", once per event batch; then "that many" is how many were discarded.
+
+Rules: CR 701.9a, CR 603.2c, CR 702.29d
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+| `card` | card filter |
+| `batched` | true | false |
+
+```json
+{
+  "discards": {
+    "controller": "you",
+    "batched": true
+  }
+}
+```
+
+## draws
+
+A player draws a card; triggers once per card (draws happen one at a time). `controller`: you (default) | opponent | any.
+
+Rules: CR 121.1, CR 121.2
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "draws": {
+    "controller": "you"
+  }
+}
+```
+
+## earthbends
+
+A player (`controller`: you (default) | opponent | any) earthbends.
+
+Rules: CR 701.66b
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "earthbends": {}
+}
+```
+
+## enters
+
+The subject enters the battlefield. `untapped: true`: only if it entered untapped. `from`: only if it entered from that zone ("enters from exile").
+
+Rules: CR 603.6a, CR 603.2, CR 614.12
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, "controller": you|opponent|any, "other": true} |
+| `untapped` | true | false |
+| `from` | hand | graveyard | exile | library | stack | outside |
+
+```json
+{
+  "enters": {
+    "subject": {
+      "each": "land",
+      "controller": "you"
+    }
+  }
+}
+```
+
+## faces_dilemma
+
+A player faces a dilemma: they chose one or more modes for a spell or ability (cast, activated, or a triggered ability put on the stack). `controller`: you (default) | opponent | any. CR 700.17.
+
+Rules: CR 700.17, CR 700.2, CR 601.2b, CR 603.3c
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "faces_dilemma": {}
+}
+```
+
+## firebends
+
+A player (`controller`: you (default) | opponent | any) firebends.
+
+Rules: CR 702.189b
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "firebends": {}
+}
+```
+
+## gains_life
+
+A player gains life (once per life gain event; lifelink combat damage is one event per source). `controller`: you (default) | opponent | any.
+
+Rules: CR 119.9, CR 120.3f
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "gains_life": {
+    "controller": "you"
+  }
+}
+```
+
+## leaves_battlefield
+
+The subject leaves the battlefield (for any zone, or only `to` that zone). Looks back in time: the permanent is matched as it last existed (types, controller, counters).
+
+Rules: CR 603.6c, CR 603.10a, CR 400.7
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, "controller": ..., "other": true} |
+| `to` | graveyard | exile | hand | library |
+
+```json
+{
+  "leaves_battlefield": {
+    "subject": {
+      "each": "creature",
+      "controller": "you",
+      "other": true
+    }
+  }
+}
+```
+
+## leaves_graveyard
+
+A card leaves a graveyard (whose: `controller` you (default) | opponent | any). Optional `card` filter on its card types. `batched: true` is "one or more cards leave": once per event that moves cards (one effect, cost or action), however many cards.
+
+Rules: CR 603.10a, CR 603.2c, CR 404.1
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+| `card` | card type filter, e.g. "creature" |
+| `batched` | true | false |
+
+```json
+{
+  "leaves_graveyard": {
+    "controller": "you",
+    "batched": true
+  }
+}
+```
+
+## loses_life
+
+A player loses life (damage to a player is life loss, CR 120.3a). `controller`: you (default) | opponent | any.
+
+Rules: CR 119.3, CR 120.3a
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "loses_life": {
+    "controller": "opponent"
+  }
+}
+```
+
+## player_attacks
+
+A player declares one or more attackers (once per combat, not per creature). `controller`: you (default) | opponent | any. `attacking_power` ({"at_least": n}): only when the attacking creatures' total power is at least n as they're declared; with `first_time_this_turn: true`, only the first combat this turn in which it was.
+
+Rules: CR 508.3d, CR 508.1, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+| `attacking_power` | {"at_least": n} |
+| `first_time_this_turn` | boolean |
+
+```json
+{
+  "player_attacks": {
+    "controller": "you",
+    "attacking_power": {
+      "at_least": 12
+    },
+    "first_time_this_turn": true
+  }
+}
+```
+
+## plays_land
+
+A player (`controller`: you (default) | opponent | any) plays a land. `from` / `not_from`: only a land played from (not from) that zone: hand | graveyard | exile | library | outside. Lands put onto the battlefield by effects aren't played.
+
+Rules: CR 305.1, CR 603.2, CR 601.2a
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+| `from` | zone |
+| `not_from` | zone |
+
+```json
+{
+  "plays_land": {
+    "not_from": "hand"
+  }
+}
+```
+
+## put_into
+
+A card is put into `zone` (graveyard | exile) from anywhere, or only `from` the listed zones. `controller`: the card's owner (you (default) | opponent | any); optional `card` filter on the card. `batched: true`: "one or more cards", once per event batch. With "battlefield" among `from` it looks back in time like leaves_battlefield.
+
+Rules: CR 603.6c, CR 603.2c, CR 400.3
+
+| Parameter | Description |
+| --- | --- |
+| `zone` | graveyard | exile |
+| `from` | list of battlefield, graveyard, hand, library, stack, exile (default: anywhere) |
+| `controller` | you | opponent | any |
+| `card` | card filter |
+| `batched` | true | false |
+
+```json
+{
+  "put_into": {
+    "zone": "graveyard",
+    "card": "creature",
+    "batched": true
+  }
+}
+```
+
+## sacrifices
+
+The subject is sacrificed (`controller` of the subject: who sacrificed it). Looks back in time, like leaves_battlefield. `batched: true`: "one or more", once per event batch.
+
+Rules: CR 701.21a, CR 603.10a, CR 603.2c
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, "controller": you, "other": true} |
+| `batched` | true | false |
+
+```json
+{
+  "sacrifices": {
+    "subject": {
+      "each": "artifact",
+      "controller": "you"
+    }
+  }
+}
+```
+
+## saddles_mount
+
+The subject (a creature) saddles a Mount: it's tapped to pay that Mount's saddle cost. {"triggering": "object"} is the Mount.
+
+Rules: CR 702.171c, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+
+```json
+{
+  "saddles_mount": {
+    "subject": "self"
+  }
+}
+```
+
+## scries
+
+A player (`controller`: you (default) | opponent | any) scries (not scry 0). Triggers after the scry is complete.
+
+Rules: CR 701.22a, CR 701.22b
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "any_of": [
+    {
+      "scries": {}
+    },
+    {
+      "surveils": {}
+    }
+  ]
+}
+```
+
+## step_begins
+
+A step begins. `whose`: "your" (default), "each" or "opponent".
+
+Rules: CR 603.6b, CR 503.1a, CR 513.1a
+
+| Parameter | Description |
+| --- | --- |
+| `step` | upkeep | draw | precombat_main | end | ... |
+| `whose` | your | each | opponent |
+
+```json
+{
+  "step_begins": {
+    "step": "upkeep",
+    "whose": "your"
+  }
+}
+```
+
+## surveils
+
+A player (`controller`: you (default) | opponent | any) surveils (not surveil 0). Triggers after the surveil is complete.
+
+Rules: CR 701.25a, CR 701.25c, CR 701.25d
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "surveils": {
+    "controller": "you"
+  }
+}
+```
+
+## transforms
+
+The subject transforms. For the default subject (this permanent), the ability is on the face that's up afterward, so it means "whenever this transforms into [this face]".
+
+Rules: CR 701.27f, CR 603.2
+
+| Parameter | Description |
+| --- | --- |
+| `subject` | "self" (default) or {"each": filter, ...} |
+
+```json
+{
+  "transforms": {}
+}
+```
+
+## waterbends
+
+A player (`controller`: you (default) | opponent | any) waterbends.
+
+Rules: CR 701.67c
+
+| Parameter | Description |
+| --- | --- |
+| `controller` | you | opponent | any |
+
+```json
+{
+  "waterbends": {}
+}
+```