enjine 0.1.0

data/docs/reference/types.md

@@ -0,0 +1,216 @@
+# Card types
+
+<!-- Generated by `rake docs` from the primitive registry. Do not edit. -->
+
+## artifact
+
+A permanent cast at sorcery speed.
+
+Rules: CR 301.1
+
+```json
+{
+  "name": "Example Relic",
+  "mana_cost": "{2}",
+  "types": [
+    "artifact"
+  ]
+}
+```
+
+## creature
+
+A permanent with power and toughness that can attack and block. Cast at sorcery speed. It can't attack or use {T} abilities unless controlled continuously since its controller's most recent turn began (summoning sickness).
+
+Rules: CR 302.1, CR 302.4, CR 302.6, CR 307.1
+
+```json
+{
+  "name": "Grizzly Bears",
+  "mana_cost": "{1}{G}",
+  "types": [
+    "creature"
+  ],
+  "subtypes": [
+    "bear"
+  ],
+  "power": 2,
+  "toughness": 2
+}
+```
+
+## enchantment
+
+A permanent cast at sorcery speed.
+
+Rules: CR 303.1
+
+```json
+{
+  "name": "Example Aura",
+  "mana_cost": "{1}{W}",
+  "types": [
+    "enchantment"
+  ]
+}
+```
+
+## instant
+
+A spell cast any time its controller has priority. Its spell ability resolves, then it goes to the graveyard.
+
+Rules: CR 304.1, CR 304.2, CR 608.2n
+
+```json
+{
+  "name": "Lightning Bolt",
+  "mana_cost": "{R}",
+  "types": [
+    "instant"
+  ],
+  "abilities": [
+    {
+      "spell": {
+        "targets": [
+          "any_target"
+        ],
+        "effects": [
+          {
+            "deal_damage": {
+              "amount": 3,
+              "to": {
+                "target": 0
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## kindred
+
+A card type that goes with another one ("Kindred Sorcery — Goblin"): the card is cast and resolves as its other type, and its subtypes are creature types.
+
+Rules: CR 308.1, CR 308.2, CR 205.3m
+
+```json
+{
+  "name": "Example Goblin Gambit",
+  "mana_cost": "{R}",
+  "types": [
+    "kindred",
+    "sorcery"
+  ],
+  "subtypes": [
+    "goblin"
+  ],
+  "abilities": [
+    {
+      "spell": {
+        "targets": [
+          "any_target"
+        ],
+        "effects": [
+          {
+            "deal_damage": {
+              "amount": 1,
+              "to": {
+                "target": 0
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## land
+
+A permanent played with the special action "play a land" (one per turn, main phase, empty stack). It has no mana cost.
+
+Rules: CR 305.1, CR 305.2, CR 305.3, CR 202.1a
+
+```json
+{
+  "name": "Forest",
+  "types": [
+    "land"
+  ],
+  "supertypes": [
+    "basic"
+  ],
+  "subtypes": [
+    "forest"
+  ]
+}
+```
+
+## planeswalker
+
+A permanent that enters with loyalty counters equal to its printed loyalty. Its loyalty abilities can be activated at sorcery speed, one per turn. Damage dealt to it removes loyalty counters; at 0 loyalty it is put into its owner's graveyard.
+
+Rules: CR 306.5b, CR 306.8, CR 120.3c, CR 606.3, CR 704.5i
+
+```json
+{
+  "name": "Vessa, Rally Captain",
+  "mana_cost": "{2}{W}{W}",
+  "types": [
+    "planeswalker"
+  ],
+  "loyalty": 3,
+  "abilities": [
+    {
+      "loyalty": {
+        "cost": 1,
+        "effects": [
+          {
+            "pump": {
+              "power": 1,
+              "toughness": 1,
+              "to": {
+                "each": "creature",
+                "controller": "you"
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## sorcery
+
+A spell cast only in its controller's main phase while the stack is empty.
+
+Rules: CR 307.1, CR 307.2, CR 608.2n
+
+```json
+{
+  "name": "Divination",
+  "mana_cost": "{2}{U}",
+  "types": [
+    "sorcery"
+  ],
+  "abilities": [
+    {
+      "spell": {
+        "effects": [
+          {
+            "draw": {
+              "amount": 2
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```

data/exe/enjine

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "enjine/cli"
+
+exit Enjine::CLI.new(ARGV).run

data/lib/enjine/actions/activate_mana_ability.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Actions
+    # CR 605.3a: a player may activate a mana ability whenever they have priority.
+    # It resolves immediately (CR 605.3b). Mana is always tapped manually, one source at a time.
+    class ActivateManaAbility
+      def self.doc
+        '`{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.'
+      end
+
+      def self.options(engine, index)
+        engine.mana_activation_options(engine.all_mana_sources(index))
+      end
+
+      def self.perform(engine, index, option)
+        engine.activate_mana_ability!(index, option[:object], option[:ability], option[:mana])
+        engine.action_taken!(index)
+      end
+    end
+    register("activate_mana", ActivateManaAbility)
+  end
+end

data/lib/enjine/actions/cast.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Actions
+    # CR 601: cast a spell from hand. Instants and flash cards at any priority; others at sorcery speed.
+    # A card in another zone can be cast when a rule or effect allows it (CR 601.3): `via` names how.
+    class Cast
+      def self.doc
+        '`{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."
+      end
+
+      def self.options(engine, index)
+        engine.player(index).hand.flat_map do |id|
+          (engine.castable?(index, id) ? [{ type: "cast", object: id }] : []) + engine.face_cast_options(index, id)
+        end + engine.permission_cast_options(index)
+      end
+
+      def self.perform(engine, index, option) = engine.begin_cast!(index, option[:object], via: option[:via], face: option[:face])
+    end
+    register("cast", Cast)
+
+    # CR 602 / 606: activate a non-mana activated or loyalty ability of a permanent you control,
+    # or an ability that functions from your hand, such as cycling (CR 113.6m, 702.29a).
+    class Activate
+      def self.doc
+        '`{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)."
+      end
+
+      def self.options(engine, index)
+        out = []
+        engine.state.battlefield.each do |id|
+          add_options(engine, index, id, out) if engine.object(id).controller == index
+        end
+        engine.player(index).hand.each { add_options(engine, index, it, out) } # CR 602.2: the owner activates
+        engine.player(index).graveyard.each { add_options(engine, index, it, out) } # CR 113.6m: e.g. "exile this card from your graveyard"
+        engine.state.exile.each { add_options(engine, index, it, out) if engine.object(it).owner == index } # CR 113.6b
+        out
+      end
+
+      def self.add_options(engine, index, id, out)
+        engine.chars(id).activated_abilities.each do |inst|
+          out << { type: "activate", object: id, ability: inst.ref } if engine.activatable?(index, id, inst.ref)
+        end
+      end
+
+      def self.perform(engine, index, option) = engine.begin_activation!(index, option[:object], option[:ability])
+    end
+    register("activate", Activate)
+  end
+end

data/lib/enjine/actions/pass.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Actions
+    # CR 117.3d: pass priority.
+    class Pass
+      def self.doc
+        '`{type: "pass"}` — pass priority. When all players pass in succession with an empty stack, the step ends (CR 117.4).'
+      end
+
+      OPTION = { type: "pass" }.freeze
+
+      def self.options(_engine, _index) = [OPTION]
+      def self.perform(engine, index, _option) = engine.pass_priority!(index)
+    end
+    register("pass", Pass)
+  end
+end

data/lib/enjine/actions/play_land.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Actions
+    # CR 305.1-305.2, 116.2a: playing a land is a special action — own main phase,
+    # empty stack, while holding priority, one land per turn plus any additional land plays
+    # (Engine#land_plays_allowed).
+    # A land outside the hand (the top of the library, exile) can be played when an effect allows it;
+    # `via` names the permission (CR 305.1: "from the zone it was in"); a land outside the game is named by
+    # its outside key (Engine::Permissions#outside_key) and brought in as it's played (CR 400.11b).
+    class PlayLand
+      def self.doc
+        '`{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)."
+      end
+
+      def self.options(engine, index)
+        return [] unless engine.sorcery_timing?(index) && engine.land_play_available?(index)
+
+        engine.player(index).hand.flat_map do |id|
+          (engine.chars(id).land? ? [{ type: "play_land", object: id }] : []) + engine.face_land_options(id)
+        end + engine.permission_land_options(index)
+      end
+
+      def self.perform(engine, index, option)
+        engine.use_play_method!(engine.play_method(index, option[:object], option[:via])) if option[:via]
+        engine.player(index).lands_played += 1
+        face = option[:face] && { "face" => option[:face] } # CR 712.9
+        if !face && engine.entering_choice(engine.candidate_object(index, option[:object]))
+          engine.state.frames << { "type" => "play_land", "object" => option[:object], "player" => index }
+          return engine.ask!(nil)
+        end
+        engine.put_played_land!(index, option[:object], enters: face)
+        engine.action_taken!(index) # CR 117.3c: the player receives priority again
+      end
+
+      # The play_land frame: ask the "as this enters" choice, then put the land onto the battlefield.
+      def self.step(engine, frame)
+        land = engine.candidate_object(frame["player"], frame["object"])
+        return engine.ask_enter_choice!(frame["object"], frame["player"]) if engine.entering_choice_pending?(land, frame["enter"])
+
+        enters = engine.enters_from_answer(land, frame)
+        engine.pay_entering_costs!(frame["player"], frame)
+        engine.put_played_land!(frame["player"], frame["object"], enters: enters)
+        engine.action_taken!(frame["player"])
+        :done
+      end
+    end
+    register("play_land", PlayLand)
+  end
+end

data/lib/enjine/actions/special_action.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Actions
+    # CR 116.2f, 116.2h: special actions that pay a cost and exile a card from your hand (foretell, suspend).
+    # The card's ability names the cost, when the action is allowed and what it does; the cost is paid in a
+    # "pay" frame (Engine::Payment#begin_payment!), which can be cancelled, and the player gets priority
+    # again afterwards (CR 116.3).
+    class SpecialAction
+      def self.doc
+        '`{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)."
+      end
+
+      def self.options(engine, index)
+        engine.player(index).hand.flat_map do |id|
+          obj = engine.object(id)
+          engine.chars(obj).abilities.filter_map do |inst|
+            ability = inst.ability
+            next unless ability.respond_to?(:special!) && ability.special_allowed?(engine, obj, index)
+            next unless engine.affordable?(index, ability.special_cost, nil)
+
+            { type: "special_action", object: id, ability: inst.ref }
+          end
+        end
+      end
+
+      def self.perform(engine, index, option)
+        ability = engine.chars(option[:object]).ability(option[:ability])
+        engine.begin_payment!(index, ability.special_cost, option[:object],
+                              special: { "object" => option[:object], "ability" => option[:ability] })
+      end
+    end
+    register("special_action", SpecialAction)
+  end
+end

data/lib/enjine/actions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Enjine
+  # Actions a player can take while holding priority. Each action class has:
+  #   .options(engine, player_index) -> Array of option Hashes
+  #   .perform(engine, player_index, option)
+  # Adding a new kind of action (cast a spell, activate an ability, ...) means adding
+  # one class and registering it here.
+  module Actions
+    PRIORITY = [] # rubocop:disable Style/MutableConstant -- extension registry
+    BY_TYPE = {} # rubocop:disable Style/MutableConstant -- extension registry
+
+    def self.register(type, klass)
+      PRIORITY << klass
+      BY_TYPE[type] = klass
+    end
+
+    def self.fetch(type) = BY_TYPE.fetch(type)
+  end
+end

data/lib/enjine/agents/busy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Agents
+    # A random agent that would rather do something than pass: with priority it plays a land when it can,
+    # and otherwise casts a spell or activates an ability `eagerness` percent of the time. Every other
+    # decision (targets, payments, attacks, blocks) is uniform, as for Agents::Random. It still passes now
+    # and then, so a free repeatable ability can't hold a game forever. Card checks use it so cards get used.
+    class Busy < Random
+      ACTIONS = %w[play_land cast activate special_action].freeze
+
+      def initialize(seed: 0, cancel_rate: 0.02, eagerness: 85)
+        super(seed: seed, cancel_rate: cancel_rate)
+        @eagerness = eagerness
+      end
+
+      def choose(decision)
+        actions = decision.options.select { ACTIONS.include?(it[:type]) }
+        return super if actions.empty? || @rng.rand(100) >= @eagerness
+
+        lands = actions.select { it[:type] == "play_land" }
+        pick = lands.empty? ? actions : lands
+        pick[@rng.rand(pick.size)]
+      end
+    end
+  end
+end

data/lib/enjine/agents/random.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Agents
+    # Picks uniformly among the legal options. No strategy: a fuzzing driver and CLI seat.
+    #
+    # `cancel_rate` is the chance of choosing "cancel" when other options exist. With a
+    # uniform pick, a 4-mana spell (about 8 payment decisions, each offering cancel)
+    # would almost never finish casting, so expensive cards and planeswalkers would
+    # go untested. The default keeps cancellation exercised but rare.
+    class Random
+      CANCEL = { type: "cancel" }.freeze
+
+      def initialize(seed: 0, cancel_rate: 0.02)
+        @rng = Rng.from_seed(seed)
+        @cancel_threshold = (cancel_rate * 1_000_000).round
+      end
+
+      def choose(decision)
+        options = decision.options
+        others = options.include?(CANCEL) && options.size > 1 ? options - [CANCEL] : options
+        return CANCEL if others.size < options.size && @rng.rand(1_000_000) < @cancel_threshold
+
+        others[@rng.rand(others.size)]
+      end
+    end
+  end
+end