enjine 0.1.0

data/docs/reference/costs.md

@@ -0,0 +1,339 @@
+# Costs
+
+<!-- Generated by `rake docs` from the primitive registry. Do not edit. -->
+
+## behold
+
+Behold `count` (default 1) objects matching the card spec `card`: each a card revealed from your hand or a permanent you control, chosen while casting or activating. `exile: true` also exiles them as it becomes cast; they are then "exiled with" it (selector `exiled_with`).
+
+Rules: CR 701.4a, CR 701.4b, CR 601.2h, CR 602.2b, CR 118.3, CR 607.2a
+
+| Parameter | Description |
+| --- | --- |
+| `card` | card spec (required), e.g. {"subtypes": ["goblin"]} |
+| `count` | integer (default 1) |
+| `exile` | true: exile what was beheld |
+
+```json
+{
+  "behold": {
+    "card": {
+      "subtypes": [
+        "goblin"
+      ]
+    },
+    "exile": true
+  }
+}
+```
+
+## blight
+
+Blight `amount`: put that many -1/-1 counters on a creature you control, chosen while casting or activating and put on it as it becomes cast.
+
+Rules: CR 701.68a, CR 701.68b, CR 601.2h, CR 602.2b, CR 118.3
+
+| Parameter | Description |
+| --- | --- |
+| `amount` | integer >= 1 |
+
+```json
+{
+  "blight": {
+    "amount": 1
+  }
+}
+```
+
+## bottom_self_from_graveyard
+
+Put this card from your graveyard on the bottom of your library. An ability with this cost is activated from your graveyard.
+
+Rules: CR 401.1, CR 113.6m, CR 602.2b, CR 118.3
+
+```json
+"bottom_self_from_graveyard"
+```
+
+## discard
+
+Discard `count` cards (default 1) from your hand, never this card, matching the card spec `card` if given: chosen while casting or activating and discarded as the spell or ability becomes cast. `random: true` discards them at random instead.
+
+Rules: CR 701.9a, CR 701.9b, CR 601.2h, CR 602.2b, CR 118.3
+
+| Parameter | Description |
+| --- | --- |
+| `count` | integer (default 1), or "X": the X announced |
+| `card` | card spec, e.g. {"types": ["land"]} |
+| `random` | true: at random (CR 701.9b) |
+
+```json
+{
+  "discard": {
+    "count": 1
+  }
+}
+```
+
+## discard_self
+
+Discard the card the ability belongs to (it goes from your hand to your graveyard). An ability with this cost is activated from your hand.
+
+Rules: CR 701.9a, CR 602.2b, CR 113.6m, CR 118.3
+
+```json
+"discard_self"
+```
+
+## exert
+
+Exert this permanent: it doesn't untap during your next untap step.
+
+Rules: CR 701.43a, CR 701.43b, CR 701.43c
+
+```json
+"exert"
+```
+
+## exile_from_graveyard
+
+Exile `count` cards from your graveyard (default 1), never this card, chosen while casting or activating and exiled as the spell or ability becomes cast. `card` (a card spec) restricts which.
+
+Rules: CR 406.1, CR 601.2h, CR 602.2b, CR 118.3
+
+| Parameter | Description |
+| --- | --- |
+| `count` | integer (default 1), or "X": the X announced |
+| `card` | card spec, e.g. {"types": ["creature"]} |
+
+```json
+{
+  "exile_from_graveyard": {
+    "count": 2
+  }
+}
+```
+
+## exile_from_hand
+
+Exile `count` cards from your hand (default 1), chosen while casting or activating, exiled as the spell or ability becomes cast. `card` (a card spec) restricts which.
+
+Rules: CR 406.1, CR 601.2h, CR 602.2b, CR 118.3
+
+| Parameter | Description |
+| --- | --- |
+| `count` | integer (default 1), or "X": the X announced |
+| `card` | card spec, e.g. {"types": ["creature"]} |
+
+```json
+{
+  "exile_from_hand": {
+    "count": 1
+  }
+}
+```
+
+## exile_self_from_graveyard
+
+Exile this card from your graveyard. An ability with this cost is activated from your graveyard.
+
+Rules: CR 406.1, CR 113.6m, CR 602.2b, CR 118.3
+
+```json
+"exile_self_from_graveyard"
+```
+
+## get_counters
+
+You get `amount` counters of the kind `counter` (e.g. poison). It can always be paid.
+
+Rules: CR 118.1, CR 122.1, CR 704.5c
+
+| Parameter | Description |
+| --- | --- |
+| `counter` | player counter kind, e.g. "poison" |
+| `amount` | integer >= 1 |
+
+```json
+{
+  "get_counters": {
+    "counter": "poison",
+    "amount": 5
+  }
+}
+```
+
+## mana
+
+Pay mana as part of an activation. Paid during the activation by spending mana from your pool, tapping sources one at a time.
+
+Rules: CR 601.2g, CR 601.2h, CR 602.2b
+
+| Parameter | Description |
+| --- | --- |
+| `(value)` | mana cost string, e.g. "{1}{R}" |
+
+```json
+{
+  "mana": "{1}{R}"
+}
+```
+
+## one_of
+
+Pay one of the listed costs (two or more), chosen as the spell or ability is cast or activated (the `choose_cost_option` decision) or, for `pay` and ward, as it is paid. A cost that can't be paid can't be chosen.
+
+Rules: CR 118.3, CR 601.2b, CR 601.2f, CR 602.2b, CR 118.12
+
+| Parameter | Description |
+| --- | --- |
+| `(list)` | two or more costs |
+
+```json
+{
+  "one_of": [
+    {
+      "behold": {
+        "card": {
+          "subtypes": [
+            "goblin"
+          ]
+        }
+      }
+    },
+    {
+      "mana": "{2}"
+    }
+  ]
+}
+```
+
+## pay_life
+
+Pay that much life (you lose it). Only possible while your life total is at least that much. `"X"` pays the X announced for the spell or ability (at most your life total); it may be a spell's additional cost.
+
+Rules: CR 119.4, CR 119.4b, CR 118.3b, CR 601.2b, CR 107.3a
+
+| Parameter | Description |
+| --- | --- |
+| `(value)` | integer >= 1, or "X" |
+
+```json
+{
+  "pay_life": 2
+}
+```
+
+## remove_counters
+
+Remove `count` counters (of kind `counter`, or any kind) from among permanents you control matching `filter` (default creature), one counter per choice. Removed as it becomes cast.
+
+Rules: CR 602.2b, CR 601.2h, CR 118.3, CR 122.1
+
+| Parameter | Description |
+| --- | --- |
+| `count` | integer |
+| `filter` | filter (default creature) |
+| `counter` | counter name (optional) |
+
+```json
+{
+  "remove_counters": {
+    "count": 3
+  }
+}
+```
+
+## sacrifice
+
+Sacrifice the permanent the ability belongs to (it goes to its owner's graveyard).
+
+Rules: CR 701.21a, CR 602.2b, CR 118.3
+
+```json
+"sacrifice"
+```
+
+## sacrifice_permanent
+
+Sacrifice `count` permanents you control matching `filter` (`other: true`: not the source). Chosen while casting or activating, sacrificed as it becomes cast; the sacrificed permanent's last known types and subtypes are remembered (condition `sacrificed`).
+
+Rules: CR 701.21a, CR 601.2h, CR 602.2b, CR 118.3, CR 608.2h
+
+| Parameter | Description |
+| --- | --- |
+| `filter` | filter (default permanent) |
+| `count` | integer (default 1) |
+| `other` | true: not the source itself |
+
+```json
+{
+  "sacrifice_permanent": {
+    "filter": "creature",
+    "other": true
+  }
+}
+```
+
+## tap
+
+{T} — tap the permanent the ability belongs to. Requires it to be untapped.
+
+Rules: CR 107.5, CR 602.5a
+
+```json
+"tap"
+```
+
+## tap_another_creature
+
+Tap another untapped creature you control, chosen while activating. A creature that came under your control this turn can be tapped this way.
+
+Rules: CR 702.184a, CR 601.2h, CR 602.2b, CR 302.6
+
+```json
+"tap_another_creature"
+```
+
+## tap_permanents
+
+Tap `count` untapped permanents you control matching `filter` (default: creature), chosen while casting or activating; `other: true` excludes the source. They are tapped as they are chosen; cancelling untaps them.
+
+Rules: CR 601.2h, CR 602.2b, CR 302.6, CR 118.3
+
+| Parameter | Description |
+| --- | --- |
+| `count` | integer (default 1) |
+| `filter` | filter (default creature) |
+| `other` | true: not the source itself |
+
+```json
+{
+  "tap_permanents": {
+    "count": 3,
+    "filter": {
+      "creature": {
+        "types": [
+          "artifact"
+        ]
+      }
+    }
+  }
+}
+```
+
+## waterbend
+
+Waterbend [cost]: pay this mana cost; for each generic mana in it you may instead tap an untapped artifact or creature you control (pay_cost option `{type: "waterbend", object: id}`). Only the waterbend cost's own generic mana can be paid this way.
+
+Rules: CR 701.67a, CR 701.67b, CR 701.67c
+
+| Parameter | Description |
+| --- | --- |
+| `(value)` | mana cost string, e.g. "{3}" or "{X}" |
+
+```json
+{
+  "waterbend": "{3}"
+}
+```

data/docs/reference/counters.md

@@ -0,0 +1,121 @@
+# Counters with rules
+
+<!-- Generated by `rake docs` from the primitive registry. Do not edit. -->
+
+## +1/+1
+
+Adds 1 to power and toughness (layer 7c). Any +X/+Y or -X/-Y counter works the same way. If a permanent has both +1/+1 and -1/-1 counters, N of each are removed as a state-based action (N = the smaller count).
+
+Rules: CR 122.1a, CR 122.3, CR 613.4c, CR 704.5q
+
+```json
+{
+  "add_counters": {
+    "counter": "+1/+1",
+    "amount": 1,
+    "to": "self"
+  }
+}
+```
+
+## -1/-1
+
+Subtracts 1 from power and toughness (layer 7c).
+
+Rules: CR 122.1a, CR 122.3, CR 613.4c, CR 704.5q
+
+```json
+{
+  "add_counters": {
+    "counter": "-1/-1",
+    "amount": 1,
+    "to": {
+      "target": 0
+    }
+  }
+}
+```
+
+## finality
+
+If the permanent would be put into a graveyard from the battlefield, it is exiled instead.
+
+Rules: CR 122.1h, CR 614.1a
+
+```json
+{
+  "enters_with_counters": {
+    "counters": {
+      "finality": 1
+    }
+  }
+}
+```
+
+## keyword
+
+A counter named after a keyword (flying, first_strike, double_strike, deathtouch, decayed, haste, hexproof, indestructible, lifelink, menace, reach, trample, vigilance) gives the permanent that keyword (layer 6). Write the keyword itself as the counter name.
+
+Rules: CR 122.1b, CR 613.1f
+
+```json
+{
+  "add_counters": {
+    "counter": "hexproof",
+    "amount": 1,
+    "to": "self"
+  }
+}
+```
+
+## loyalty
+
+A planeswalker's loyalty; at 0 it is put into its owner's graveyard.
+
+Rules: CR 122.1e, CR 306.5b, CR 704.5i
+
+```json
+{
+  "add_counters": {
+    "counter": "loyalty",
+    "amount": 1,
+    "to": "self"
+  }
+}
+```
+
+## shield
+
+If the permanent would be destroyed by an effect, instead remove a shield counter. If damage would be dealt to it, prevent it and remove a shield counter (simultaneous damage, such as combat damage, removes only one).
+
+Rules: CR 122.1c, CR 614.1a, CR 615.1a, CR 701.8b
+
+```json
+{
+  "add_counters": {
+    "counter": "shield",
+    "amount": 1,
+    "to": {
+      "target": 0
+    }
+  }
+}
+```
+
+## stun
+
+If the permanent would become untapped (untap step or an effect), instead one stun counter is removed from it.
+
+Rules: CR 122.1d, CR 502.3, CR 701.26b
+
+```json
+{
+  "add_counters": {
+    "counter": "stun",
+    "amount": 1,
+    "to": {
+      "target": 0
+    }
+  }
+}
+```

data/docs/reference/decisions.md

@@ -0,0 +1,102 @@
+# Decisions
+
+<!-- Generated by `rake docs` from the primitive registry. Do not edit. -->
+
+`game.pending_decision` returns the decision below; submit one of its `options`.
+
+## assign_damage
+
+Assign one point of combat damage of `attacker`: `{type: "assign", object: blocker_id}`. `remaining` points are left.
+
+## bottom
+
+Right after a mulligan, put one card from the new hand on the bottom of the library: `{type: "bottom", object: id}`, once per mulligan taken so far, before declaring again. Hidden from the opponent (CR 103.5).
+
+## choose_cost
+
+While casting/activating: `{type: "cost", object: id}` picks the permanent (or card) a cost uses (the creature to tap for station, the creature to sacrifice, the creature beamed up, ...); `{type: "done"}` stops choosing for a cost of any number of permanents once enough are chosen (crew: total power N or more); `{type: "cancel"}` rewinds. `cost` describes the cost.
+
+## choose_cost_option
+
+While casting/activating with a choice between costs (cost `one_of`): `{type: "cost_option", option: i}` (0-based, in the order of `costs`) for one that could be paid; `{type: "cancel"}` rewinds.
+
+## choose_kicker
+
+While casting a spell with kicker: `{type: "kick"}` pays the kicker cost too, `{type: "no_kick"}` doesn't; `{type: "cancel"}` rewinds. `cost` describes the kicker cost.
+
+## choose_mode
+
+Choose a mode of a modal ("choose one") spell or ability: `{type: "mode", mode: index}` (0-based, in printed order); `{type: "done"}` once enough are chosen when more are allowed; `{type: "cancel"}` rewinds a cast. `choose` modes in total (at least `min`).
+
+## choose_target
+
+While casting/activating: `{type: "target", target: ref}` for the next target (ref is an object id or "player:<name>"); `{type: "done"}` chooses no more for an "up to" target; `{type: "cancel"}` rewinds the whole cast.
+
+## choose_target_count
+
+While casting/activating: `{type: "count", count: n}` announces how many targets (from `min` to `max`, at most as many as there are legal ones) target ##`index` + 1 will have; `{type: "cancel"}` rewinds.
+
+## choose_x
+
+While casting/activating a spell or ability with {X} in its cost: `{type: "x", value: n}` announces X (0 up to `max`, the most the available mana could pay for); `{type: "cancel"}` rewinds.
+
+## declare_attackers
+
+Declare one attacker: `{type: "attack", object: id, target: ref}` (the defending player or one of their planeswalkers), or `{type: "done"}` (withheld while a creature that attacks each combat if able could still attack, CR 508.1d, or while a creature that can't attack alone attacks alone, CR 506.5; then `{type: "withdraw", object: id}` undoes an attack).
+
+## declare_blockers
+
+Declare one blocker: `{type: "block", object: id, attacker: id}`, `{type: "done"}` (only when the blocks are legal), or `{type: "unblock", object: id}` to fix an illegal menace block or free a creature for an attacker that must be blocked if able (CR 509.1c).
+
+## discard
+
+Cleanup step: discard one card, `{type: "discard", object: id}`, until the hand has 7 cards. `count` is how many remain (CR 514.1).
+
+## distribute
+
+While casting: `{type: "assign", target: ref}` gives one more of the divided amount to that target (each target already has one); `{type: "cancel"}` rewinds. `left` is what remains to divide.
+
+## effect_choice
+
+A choice made while an effect resolves (scry, surveil, discard...): submit one of the `choices` exactly as listed; `prompt` describes it.
+
+## enter_choice
+
+Before `object` enters: `{type: "pay_life", life: n}` (only with enough life) or `{type: "enter_tapped"}` (CR 614.12, 119.4), or `{type: "behold", object: id}` (CR 701.4a); `{type: "number", number: n}` for "choose a number"; `{type: "name", name: "..."}` for "choose a card name" (CR 201.4); `{type: "color", color: "R"}`, `{type: "creature_type", creature_type: "elf"}`, `{type: "card_type", card_type: "artifact"}`, `{type: "basic_land_type", basic_land_type: "forest"}` or `{type: "option", option: "word"}` for the other "choose a ..." abilities (CR 607.2d); devour picks permanents to sacrifice one at a time, `{type: "devour", object: id}` (`chosen` lists them), then `{type: "done"}` (CR 702.82a). With `effect: true` the permanent is being put onto the battlefield by a resolving effect (a token about to be created has `card`); with several entering at once, each is asked in turn before any enters (CR 614.12a-b).
+
+## legend_rule
+
+Keep one of your legendary permanents named `name`: `{type: "keep", object: id}`; the others go to the graveyard (CR 704.5j).
+
+## mulligan
+
+Keep the hand (`{type: "keep"}`) or take a London mulligan (`{type: "mulligan"}`). Players declare in turn order; mulligans then happen simultaneously (CR 103.5).
+
+## order_triggers
+
+Put one of your pending triggered abilities on the stack next: `{type: "trigger", trigger: id}` (CR 603.3b). The last one put on the stack resolves first.
+
+## pay_cost
+
+While casting/activating or paying a cost: `{type: "pay_mana", mana: "R"}` spends one mana from the pool (`restricted: i`: restricted mana, CR 106.6; `from: i`: the pool mana an artifact made that pool_sources[i] names), `{type: "activate_mana", object: id, ability: ref}` (plus `mana: "{G}{G}"` when the mana is chosen) taps a source, `{type: "cancel"}` rewinds (or declines a payment asked for while resolving). Cancel isn't offered once a mana ability with a cost other than {T} (a Treasure) has been activated. `{type: "convoke", object: id}` taps a creature to pay for {1} or one mana of its color (a spell with convoke); `{type: "improvise", object: id}` taps an artifact to pay for {1} (a spell with improvise); `{type: "waterbend", object: id}` taps an artifact or creature to pay {1} of a waterbend cost. `remaining` shows what is left to pay.
+
+## play_or_draw
+
+The die-roll winner chooses `{type: "play"}` or `{type: "draw"}` (CR 103.1).
+
+## priority
+
+The player holding priority takes an action or passes. Options come from the priority actions below (CR 117).
+
+## untap_choice
+
+Untap step: `{type: "untap", object: id}` or `{type: "keep_tapped", object: id}` for a permanent you may choose not to untap (CR 502.3).
+
+## Priority actions
+
+- `activate` — `{type: "activate", object: id, ability: ref}` — start activating an ability (CR 602.2), including planeswalker loyalty abilities (CR 606) and abilities of cards in your hand (cycling, CR 702.29).
+- `activate_mana` — `{type: "activate_mana", object: id, ability: ref}` — activate a mana ability; it resolves immediately (CR 605.3). `mana: "{G}{G}"` names the mana when it is chosen as the ability is activated.
+- `cast` — `{type: "cast", object: id}` — start casting a card from your hand (CR 601.2). `{type: "cast", object: id, via: method}` casts a card from another zone (graveyard, exile, the top of your library) by the permission or alternative cost `via` names, e.g. beam me up (CR 601.3, 702.196). A card outside the game is named `"outside:<card id>"` (CR 400.11b). `{type: "cast", object: id, face: 1}` casts another face of a card in your hand: a modal double-faced card's back face, an Adventure or an Omen (CR 712.8b, 716.3, 721.3). Offered only when timing allows, targets exist and enough mana is available.
+- `pass` — `{type: "pass"}` — pass priority. When all players pass in succession with an empty stack, the step ends (CR 117.4).
+- `play_land` — `{type: "play_land", object: id}` — special action: your main phase, empty stack, one land per turn plus additional land plays (CR 305.1, 305.2). With `via`: a land from another zone that an effect lets you play. With `face: 1`: a modal double-faced card played with its land back face up (CR 712.9).
+- `special_action` — `{type: "special_action", object: id, ability: ref}` — a special action of a card in your hand: foretell (during your turn, pay {2} and exile it face down, CR 116.2h) or suspend (when you could begin to cast it, pay its suspend cost and exile it with time counters, CR 116.2f).