Dovin.V3

V3 introduces a new effects system that is incompatible with V2 effects. V3 effects are more flexible and better align with the layer system. It also adds some new card properties.

• withEffect has a new, more flexible API.
• withEffectWhen added as a version of withEffect that allows customization of then the effect should apply (by default they apply when card is in play).
• withCMC to set converted mana cost on cards.
• addEffect to apply an effect to a card. In combination with effectPTAdjust this replaces altering cardStrengthModifier directly, which is now removed.
• Added a suite of `effect*` builders for effects.
• Added cardOwner property to cards, and withOwner fluid builder to set it.

Documentation

view :: MonadReader s m => Getting a s a -> m a

View the value pointed to by a Getter, Iso or Lens or the result of folding over all the results of a Fold or Traversal that points at a monoidal value.

view . to ≡ id

>>> view (to f) a
f a

>>> view _2 (1,"hello")
"hello"

>>> view (to succ) 5
6

>>> view (_2._1) ("hello",("world","!!!"))
"world"

As view is commonly used to access the target of a Getter or obtain a monoidal summary of the targets of a Fold, It may be useful to think of it as having one of these more restricted signatures:

view ::             Getter s a     -> s -> a
view :: Monoid m => Fold s m       -> s -> m
view ::             Iso' s a       -> s -> a
view ::             Lens' s a      -> s -> a
view :: Monoid m => Traversal' s m -> s -> m

In a more general setting, such as when working with a Monad transformer stack you can use:

view :: MonadReader s m             => Getter s a     -> m a
view :: (MonadReader s m, Monoid a) => Fold s a       -> m a
view :: MonadReader s m             => Iso' s a       -> m a
view :: MonadReader s m             => Lens' s a      -> m a
view :: (MonadReader s m, Monoid a) => Traversal' s a -> m a

type Formatter = Board -> String

type GameMonad a = ExceptT String (ReaderT Env (StateT Board (WriterT [Step] Identity))) a

data Step

Constructors

Step

Fields

• _stepId :: StepIdentifier
• _stepLabel :: String
• _stepState :: Board

type StepIdentifier = (Maybe String, Int)

data Env

Constructors

Env

Fields

• _envTemplate :: Card
• _envSBAEnabled :: Bool
• _envActor :: Player
• _envOwner :: Maybe Player

data Board

Constructors

Board

Fields

• _cards :: HashMap CardName BaseCard
• _resolvedCards :: HashMap CardName Card
• _stack :: [CardName]
• _deck :: HashMap Player [CardName]
• _counters :: HashMap String Int
• _life :: HashMap Player Int
• _manaPool :: HashMap Player ManaPool
• _phase :: Phase
• _currentStep :: StepIdentifier
• _currentTime :: Timestamp

type EffectName = String

data CardMatcher

Constructors

CardMatcher String (Card -> Bool)

Instances

Show CardMatcher

Defined in Dovin.Types

Methods

showsPrec :: Int -> CardMatcher -> ShowS

show :: CardMatcher -> String

showList :: [CardMatcher] -> ShowS

Semigroup CardMatcher

Defined in Dovin.Types

Methods

(<>) :: CardMatcher -> CardMatcher -> CardMatcher

sconcat :: NonEmpty CardMatcher -> CardMatcher

stimes :: Integral b => b -> CardMatcher -> CardMatcher

Monoid CardMatcher

Defined in Dovin.Types

Methods

mempty :: CardMatcher

mappend :: CardMatcher -> CardMatcher -> CardMatcher

mconcat :: [CardMatcher] -> CardMatcher

newtype BaseCard

Constructors

BaseCard Card

Instances

Eq BaseCard

Defined in Dovin.Types

Methods

(==) :: BaseCard -> BaseCard -> Bool

(/=) :: BaseCard -> BaseCard -> Bool

Show BaseCard

Defined in Dovin.Types

Methods

showsPrec :: Int -> BaseCard -> ShowS

show :: BaseCard -> String

showList :: [BaseCard] -> ShowS

data Card

Constructors

Card

Fields

• _cardName :: CardName
• _location :: (Player, Location)
• _cardOwner :: Player
• _cardDefaultAttributes :: CardAttributes
• _cardAttributes :: CardAttributes
• _cardStrength :: CardStrength
• _cardStrengthModifier :: CardStrength
• _cardDamage :: Int
• _cardLoyalty :: Int
• _cardEffects :: [CardEffect]
• _cardCmc :: Int
• _cardColors :: Colors
• _cardTargets :: [Target]
• _cardTimestamp :: Timestamp
• _cardPassiveEffects :: [LayeredEffectDefinition]
• _cardAbilityEffects :: [AbilityEffect]
• _cardPlusOneCounters :: Int
• _cardMinusOneCounters :: Int

Instances

Eq Card

Defined in Dovin.Types

Methods

(==) :: Card -> Card -> Bool

(/=) :: Card -> Card -> Bool

Show Card

Defined in Dovin.Types

Methods

showsPrec :: Int -> Card -> ShowS

show :: Card -> String

showList :: [Card] -> ShowS

data AbilityEffect

Constructors

AbilityEffect Timestamp EffectDuration [LayeredEffectPart]

data EffectDuration

Constructors

EndOfTurn

type Timestamp = Integer

data Phase

A phase or step in a turn. Phases and steps are not distinguished between because haven't seen a need to.

Constructors

Untap

Upkeep

DrawStep

FirstMain

BeginCombat

DeclareAttackers

DeclareBlockers

FirstStrikeDamage

CombatDamage

EndCombat

SecondMain

EndStep

Won Player

Instances

Eq Phase

Defined in Dovin.Types

Methods

(==) :: Phase -> Phase -> Bool

(/=) :: Phase -> Phase -> Bool

Ord Phase

Defined in Dovin.Types

Methods

compare :: Phase -> Phase -> Ordering

(<) :: Phase -> Phase -> Bool

(<=) :: Phase -> Phase -> Bool

(>) :: Phase -> Phase -> Bool

(>=) :: Phase -> Phase -> Bool

max :: Phase -> Phase -> Phase

min :: Phase -> Phase -> Phase

Show Phase

Defined in Dovin.Types

Methods

showsPrec :: Int -> Phase -> ShowS

show :: Phase -> String

showList :: [Phase] -> ShowS

data CardStrength

Constructors

CardStrength Int Int

Instances

Eq CardStrength

Defined in Dovin.Types

Methods

(==) :: CardStrength -> CardStrength -> Bool

(/=) :: CardStrength -> CardStrength -> Bool

Show CardStrength

Defined in Dovin.Types

Methods

showsPrec :: Int -> CardStrength -> ShowS

show :: CardStrength -> String

showList :: [CardStrength] -> ShowS

Semigroup CardStrength

Defined in Dovin.Types

Methods

(<>) :: CardStrength -> CardStrength -> CardStrength

sconcat :: NonEmpty CardStrength -> CardStrength

stimes :: Integral b => b -> CardStrength -> CardStrength

Monoid CardStrength

Defined in Dovin.Types

Methods

mempty :: CardStrength

mappend :: CardStrength -> CardStrength -> CardStrength

mconcat :: [CardStrength] -> CardStrength

type CardAttributes = Set CardAttribute

type CardLocation = (Player, Location)

data Target

Constructors

TargetPlayer Player

Target a player, use targetPlayer to construct.

TargetCard CardName

Target a card, use targetCard to construct.

Instances

Eq Target

Defined in Dovin.Types

Methods

(==) :: Target -> Target -> Bool

(/=) :: Target -> Target -> Bool

Show Target

Defined in Dovin.Types

Methods

showsPrec :: Int -> Target -> ShowS

show :: Target -> String

showList :: [Target] -> ShowS

data LayeredEffectDefinition

Constructors

LayeredEffectDefinition

Fields

• _leAppliesTo :: EffectMonad CardMatcher

  Filter to determine which cards are affected by this effect, if enabled.

• _leEffect :: LayeredEffect

  The actions to apply to affected cards.

• _leName :: EffectName

  A human readable description of the effect. Optional.

type LayeredEffect = [LayeredEffectPart]

data LayeredEffectPart

Constructors

LayeredEffectPart Layer (Card -> EffectMonad Card)

data Layer

Constructors

Layer1A

Copiable effects

Layer1B

Face down spells and permanents

Layer2

Control-changing effects

Layer3

Text changing effects

Layer4

Type changing effects

Layer5

Color changing effects

Layer6

Ability changing effects

Layer7A

P/T from CDAs

Layer7B

P/T from setting

Layer7C

P/T adjustments (inc. counters)

Layer7D

P/T Switching

LayerOther

Other game rule affecting effects

Instances

Bounded Layer

Defined in Dovin.Types

Methods

minBound :: Layer

maxBound :: Layer

Enum Layer

Defined in Dovin.Types

Methods

succ :: Layer -> Layer

pred :: Layer -> Layer

toEnum :: Int -> Layer

fromEnum :: Layer -> Int

enumFrom :: Layer -> [Layer]

enumFromThen :: Layer -> Layer -> [Layer]

enumFromTo :: Layer -> Layer -> [Layer]

enumFromThenTo :: Layer -> Layer -> Layer -> [Layer]

Eq Layer

Defined in Dovin.Types

Methods

(==) :: Layer -> Layer -> Bool

(/=) :: Layer -> Layer -> Bool

Ord Layer

Defined in Dovin.Types

Methods

compare :: Layer -> Layer -> Ordering

(<) :: Layer -> Layer -> Bool

(<=) :: Layer -> Layer -> Bool

(>) :: Layer -> Layer -> Bool

(>=) :: Layer -> Layer -> Bool

max :: Layer -> Layer -> Layer

min :: Layer -> Layer -> Layer

Show Layer

Defined in Dovin.Types

Methods

showsPrec :: Int -> Layer -> ShowS

show :: Layer -> String

showList :: [Layer] -> ShowS

type EffectMonad a = Reader (Board, Card) a

data CardEffect

Constructors

CardEffect

Fields

• _effectEnabled :: CardMatcher
• _effectFilter :: Card -> CardMatcher
• _effectAction :: Card -> GameMonad Card

data Location

Constructors

Hand

Graveyard

Play

Stack

Exile

Deck

Instances

Eq Location

Defined in Dovin.Types

Methods

(==) :: Location -> Location -> Bool

(/=) :: Location -> Location -> Bool

Ord Location

Defined in Dovin.Types

Methods

compare :: Location -> Location -> Ordering

(<) :: Location -> Location -> Bool

(<=) :: Location -> Location -> Bool

(>) :: Location -> Location -> Bool

(>=) :: Location -> Location -> Bool

max :: Location -> Location -> Location

min :: Location -> Location -> Location

Show Location

Defined in Dovin.Types

Methods

showsPrec :: Int -> Location -> ShowS

show :: Location -> String

showList :: [Location] -> ShowS

type ManaString = String

type ManaPool = String

data Player

Constructors

Active

Opponent

Instances

Eq Player

Defined in Dovin.Types

Methods

(==) :: Player -> Player -> Bool

(/=) :: Player -> Player -> Bool

Ord Player

Defined in Dovin.Types

Methods

compare :: Player -> Player -> Ordering

(<) :: Player -> Player -> Bool

(<=) :: Player -> Player -> Bool

(>) :: Player -> Player -> Bool

(>=) :: Player -> Player -> Bool

max :: Player -> Player -> Player

min :: Player -> Player -> Player

Show Player

Defined in Dovin.Types

Methods

showsPrec :: Int -> Player -> ShowS

show :: Player -> String

showList :: [Player] -> ShowS

Generic Player

Defined in Dovin.Types

Associated Types

type Rep Player :: Type -> Type

Methods

from :: Player -> Rep Player x

to :: Rep Player x -> Player

Hashable Player

Defined in Dovin.Types

Methods

hashWithSalt :: Int -> Player -> Int

hash :: Player -> Int

type Rep Player

Defined in Dovin.Types

type Rep Player = D1 ('MetaData "Player" "Dovin.Types" "dovin-3.0-D8jAg3rtI8467M8j4unCKt" 'False) (C1 ('MetaCons "Active" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Opponent" 'PrefixI 'False) (U1 :: Type -> Type))

type CardAttribute = String

type CardName = String

type Colors = Set Color

data Color

Constructors

Red

Green

Blue

Black

White

Instances

Eq Color

Defined in Dovin.Types

Methods

(==) :: Color -> Color -> Bool

(/=) :: Color -> Color -> Bool

Ord Color

Defined in Dovin.Types

Methods

compare :: Color -> Color -> Ordering

(<) :: Color -> Color -> Bool

(<=) :: Color -> Color -> Bool

(>) :: Color -> Color -> Bool

(>=) :: Color -> Color -> Bool

max :: Color -> Color -> Color

min :: Color -> Color -> Color

Show Color

Defined in Dovin.Types

Methods

showsPrec :: Int -> Color -> ShowS

show :: Color -> String

showList :: [Color] -> ShowS

allLayers :: [Layer]

mkEffect :: CardMatcher -> (Card -> CardMatcher) -> (Card -> Identity Card) -> CardEffect

mkLayeredEffectPart :: EffectMonad CardMatcher -> LayeredEffect -> EffectName -> LayeredEffectDefinition

targetPlayer :: Player -> Target

targetCard :: CardName -> Target

incrementStep :: StepIdentifier -> StepIdentifier

counters :: Lens' Board (HashMap String Int)

currentTime :: Lens' Board Timestamp

cardAbilityEffects :: Lens' Card [AbilityEffect]

cardAttributes :: Lens' Card CardAttributes

cardCmc :: Lens' Card Int

cardColors :: Lens' Card Colors

cardDamage :: Lens' Card Int

cardDefaultAttributes :: Lens' Card CardAttributes

cardEffects :: Lens' Card [CardEffect]

cardLoyalty :: Lens' Card Int

cardMinusOneCounters :: Lens' Card Int

cardName :: Lens' Card CardName

cardOwner :: Lens' Card Player

cardPassiveEffects :: Lens' Card [LayeredEffectDefinition]

cardPlusOneCounters :: Lens' Card Int

cardStrength :: Lens' Card CardStrength

cardTargets :: Lens' Card [Target]

cardTimestamp :: Lens' Card Timestamp

location :: Lens' Card (Player, Location)

effectAction :: Lens' CardEffect (Card -> GameMonad Card)

effectEnabled :: Lens' CardEffect CardMatcher

effectFilter :: Lens' CardEffect (Card -> CardMatcher)

envActor :: Lens' Env Player

envOwner :: Lens' Env (Maybe Player)

envSBAEnabled :: Lens' Env Bool

envTemplate :: Lens' Env Card

stepId :: Lens' Step StepIdentifier

stepLabel :: Lens' Step String

stepState :: Lens' Step Board

leAppliesTo :: Lens' LayeredEffectDefinition (EffectMonad CardMatcher)

leEffect :: Lens' LayeredEffectDefinition LayeredEffect

leName :: Lens' LayeredEffectDefinition EffectName

stepFork :: Lens' Step (Maybe String)

stepNumber :: Lens' Step Int

mkStep :: StepIdentifier -> String -> Board -> Step

cardLocation :: Lens' Card (Player, Location)

cardPower :: Lens' Card Int

cardToughness :: Lens' Card Int

cardController :: Lens' Card Player

manaPoolFor :: Functor f => Player -> ([Char] -> f [Char]) -> Board -> f Board

_manaPoolForTyping :: Board -> ManaPool

emptyEnv :: Env

mkStrength :: (Int, Int) -> CardStrength

emptyCard :: Card

mkCard :: CardName -> (Player, Location) -> Card

opposing :: Player -> Player

emptyBoard :: Board

run :: (Step -> Formatter) -> GameMonad () -> IO ()

numbered :: Int -> CardName -> CardName

Return a card name suffixed by the given number.

activated :: CardAttribute

arcane :: CardAttribute

attacking :: CardAttribute

aura :: CardAttribute

artifact :: CardAttribute

copy :: CardAttribute

creature :: CardAttribute

deathtouch :: CardAttribute

deathtouched :: CardAttribute

defender :: CardAttribute

doublestrike :: CardAttribute

enchantment :: CardAttribute

exerted :: CardAttribute

exileWhenLeaveStack :: CardAttribute

firststrike :: CardAttribute

flash :: CardAttribute

flying :: CardAttribute

haste :: CardAttribute

indestructible :: CardAttribute

instant :: CardAttribute

hexproof :: CardAttribute

land :: CardAttribute

legendary :: CardAttribute

lifelink :: CardAttribute

mentor :: CardAttribute

planeswalker :: CardAttribute

sorcery :: CardAttribute

storm :: CardAttribute

summoned :: CardAttribute

undying :: CardAttribute

tapped :: CardAttribute

token :: CardAttribute

trample :: CardAttribute

triggered :: CardAttribute

vigilance :: CardAttribute

matchDamage :: Int -> CardMatcher

matchLoyalty :: Int -> CardMatcher

matchPlusOneCounters :: Int -> CardMatcher

matchMinusOneCounters :: Int -> CardMatcher

matchLocation :: CardLocation -> CardMatcher

matchInPlay :: CardMatcher

matchAttribute :: CardAttribute -> CardMatcher

matchAttributes :: [CardAttribute] -> CardMatcher

matchName :: CardName -> CardMatcher

matchOtherCreatures :: Card -> CardMatcher

matchOther :: CardAttribute -> Card -> CardMatcher

matchController :: Player -> CardMatcher

matchLesserPower :: Int -> CardMatcher

matchNone :: CardMatcher

matchCard :: Card -> CardMatcher

matchToughness :: Int -> CardMatcher

matchPower :: Int -> CardMatcher

matchStrength :: (Int, Int) -> CardMatcher

matchTarget :: Target -> CardMatcher

missingAttribute :: CardAttribute -> CardMatcher

matchOr :: CardMatcher -> CardMatcher -> CardMatcher

invert :: CardMatcher -> CardMatcher

labelMatch :: String -> CardMatcher -> CardMatcher

applyMatcherWithDesc :: CardMatcher -> Card -> Either String ()

applyMatcher :: CardMatcher -> Card -> Bool

hasAttribute :: CardAttribute -> Card -> Bool

manaSpec :: ParsecT String u Identity [Char]

parseMana :: String -> ManaPool

requireCard :: CardName -> CardMatcher -> GameMonad Card

allCards :: GameMonad [Card]

modifyCardDeprecated :: CardName -> ASetter Card Card a b -> (a -> b) -> GameMonad ()

modifyCard :: ASetter Card Card a b -> (a -> b) -> CardName -> GameMonad ()

loseAttribute :: CardAttribute -> CardName -> ExceptT String (ReaderT Env (StateT Board (WriterT [Step] Identity))) ()

removeAttribute :: CardAttribute -> Card -> Card

gainAttribute :: CardAttribute -> CardName -> ExceptT String (ReaderT Env (StateT Board (WriterT [Step] Identity))) ()

setAttribute :: CardAttribute -> Card -> Card

forCards :: CardMatcher -> (CardName -> GameMonad ()) -> GameMonad ()

gameFinished :: GameMonad Bool

getTimestamp :: GameMonad Timestamp

type FormatMonad = Writer [(String, GameMonad String)]

blankFormatter :: Formatter

attributeFormatter :: FormatMonad () -> Formatter

stackFormatter :: Formatter

cardFormatter :: String -> CardMatcher -> Formatter

formatCards :: [Card] -> [Char]

formatCard :: Card -> [Char]

boardFormatter :: Formatter

attribute :: Show a => String -> GameMonad a -> FormatMonad ()

countLife :: Player -> GameMonad Int

countValue :: String -> GameMonad Int

countCards :: CardMatcher -> GameMonad Int

countManaPool :: Player -> GameMonad Int

addCard :: CardName -> GameMonad ()

addAura :: CardName -> GameMonad ()

addArtifact :: CardName -> GameMonad ()

addCreature :: (Int, Int) -> CardName -> GameMonad ()

addPlaneswalker :: Int -> CardName -> GameMonad ()

addEnchantment :: CardName -> GameMonad ()

addInstant :: CardName -> GameMonad ()

addLand :: CardName -> GameMonad ()

addLands :: Int -> CardName -> GameMonad ()

addSorcery :: CardName -> GameMonad ()

as :: Player -> GameMonad () -> GameMonad ()

Perform action as the specified player.

withAttribute :: String -> GameMonad () -> GameMonad ()

Add an attribute to the created card, as identified by a string. Attributes with that special meaning to Dovin built-ins (such as flying) are defined in Dovin.Attributes.

withAttributes :: [String] -> GameMonad () -> GameMonad ()

Helper version of withAttribute for adding multiple attributes at a time.

withEffectWhen

Arguments

:: EffectMonad Bool

Effect only applies when this returns true

-> EffectMonad CardMatcher

The set of cards to apply the effect to

-> [LayeredEffectPart]

The effect to apply

-> EffectName

Human-readable description, cosmetic only.

-> GameMonad ()

-> GameMonad ()

A more flexible version of withEffect that allows customization of then the effect should apply.

withCMC :: Int -> GameMonad () -> GameMonad ()

Set the converted mana cost of the created card.

withLocation :: Location -> GameMonad () -> GameMonad ()

Place the created card into a specific location.

withOwner :: Player -> GameMonad () -> GameMonad ()

Set the owner for the created card. If not specified, defaults to the owner of the card location.

withPlusOneCounters :: Int -> GameMonad () -> GameMonad ()

Set the number of +1/+1 counters of the created card.

withMinusOneCounters :: Int -> GameMonad () -> GameMonad ()

Set the number of -1/-1 counters of the created card.

addMana :: ManaString -> GameMonad ()

Add mana to actor's mana pool.

addMana "2RG"

Validates

• Mana specification is valid.

Effects

• Mana pool is increased.

cast :: ManaPool -> CardName -> GameMonad ()

Casts a card from actor's hand. See castFromLocation for specification.

cast "R" "Shock"

Validates

• Card exists in hand.

castFromLocation :: CardLocation -> ManaPool -> CardName -> GameMonad ()

Move a card to the stack, spending the specified mana. If not tracking mana, use the empty string to cast for no mana. Typically you will want to resolve after casting. For the common case of casting from hand, see cast. See spendMana for additional mana validations and effects.

castFromLocation "1B" "Oathsworn Vampire" >> resolveTop

Validates

• Card exists in location.
• If not an instant or has flash, see validateCanCastSorcery for extra validations.

Effects

• Card moved to top of stack.
• Counter storm incremented if card has instant or sorcery attribute.

counter :: CardName -> GameMonad ()

Remove a spell from the stack.

counter "Shock"

Validates

• Card is on stack.
• Card is not a triggered or activated ability.

Effects

• Card is moved to graveyard. (See move for alternate effects.)

flashback :: ManaPool -> CardName -> GameMonad ()

Cast a card from actor's graveyard, exiling it when it leaves the stack. See castFromLocation for further specification.

flashback "R" "Shock"

Does not validate whether the card actually has a flashback cost. If important, use a wrapper function in your solution:

flashbackSnapped mana castName = do
  validate (matchAttribute "snapcastered") castName
  flashback mana castName

Validates

• Card is in actor's graveyard.

Effects

• Card gains exileWhenLeaveStack.

jumpstart :: ManaPool -> CardName -> CardName -> GameMonad ()

Cast a card from active player's graveyard, discarding a card in addition to its mana cost, exiling it when it leaves the stack. See castFromLocation for further specification.

jumpstart "R" "Mountain" "Shock"

Validates

• Card is in actor's graveyard.
• Discard card is in actor's hand.

Effects

• Card gains exileWhenLeaveStack.
• Discard card moved to graveyard.

resolve :: CardName -> GameMonad ()

Resolves a card on the stack.

cast "R" "Shock" >> resolve "Shock"

Validates

• Stack is not empty.
• Card is on top of stack.

Effects

• See resolveTop.

resolveTop :: GameMonad ()

Resolves the top card of the stack. Use this for simple cast-and-resolve scenarios. For more complicated stack states, prefer resolve with a named spell to ensure the expected one is resolving.

Validates

• Stack is not empty.

Effects

• If spell, move card to graveyard of owner.
• If permanent, move card to play area of owner.
• If trigger, remove card.
• See move for possible alternate effects, depending on card attributes.

resolveMentor :: CardName -> CardName -> ExceptT String (ReaderT Env (StateT Board (WriterT [Step] Identity))) ()

Resolves a trigger created by triggerMentor. Adds +1/+1 to target card if still a valid mentor target.

resolveMentor "Goblin 1" "Legion Warboss"

Validates

• Mentor trigger is top of stack.
• Target card is attacking.
• Target card has less power than source card.

Effects

• Target card gets +1/+1.
• Trigger is removed from top of stack.

sacrifice :: CardName -> GameMonad ()

Sacrifice a permanent.

sacrifice "Soldier"

Validates

• Permanent controlled by current actor.
• Permanent is in play.

Effects

• Card is moved to graveyard. See move for possible alternate effects.

splice :: CardName -> ManaString -> CardName -> GameMonad ()

Splices a spell on to a previously cast arcane spell.

splice "Goryo's Vengeance" "2RR" "Through the Breach"

Validates

• Target spell is arcane.
• Target spell is on stack.
• Spliced spell is in hand.
• See spendMana for additional validations.

Effects

• See spendMana for additional effects.

tapForMana :: ManaString -> CardName -> GameMonad ()

Combination of tap and addMana, see them for specification.

transitionTo :: Phase -> GameMonad ()

Transition to a new game phase or step.

transitionTo DeclareAttackers

Validates

• The new phase would occur after the current phase in a normal turn.

Effects

• Empty the mana pool.
• Transition to new phase.

transitionToForced :: Phase -> GameMonad ()

Equivalent to transitionTo except it skips all validation. Useful when an effect has modified the normal order of phases, such as adding an extra combat step.

trigger :: CardName -> CardName -> GameMonad ()

Triggers an effect of a permanent. Typically you will want to resolve after triggering.

trigger "Draw Card" "Dawn of Hope" >> resolveTop

Validates

• Card is in play or graveyard.
• Card is cotrolled by actor.

Effects

• A card with triggered is added to stack.

triggerMentor :: CardName -> CardName -> GameMonad ()

Triggers a mentor effect from an attacking creature, targeting another attacking creature with lesser power. Typically you will want to resolveMentor after triggering.

triggerMentor "Goblin 1" "Legion Warboss"

Validates

• Source card has attacking and mentor attributes.
• Target card is attacking.
• Target card has less power than source card.

Effects

• A triggered card is placed on the stack.

with :: CardName -> (CardName -> GameMonad ()) -> GameMonad ()

Helper function to provide a scoped let.

with "Angel" $ \cn -> target cn >> destroy cn

move :: CardLocation -> CardLocation -> CardName -> GameMonad ()

Move a card from one location to another.

move (Opponent, Play) (Active, Play) "Angel"

Validates

• Card exists in source location.
• Destination is not stack (use a cast variant instead).
• Destination does not match source.
• If card has token attribute, source is in play. (Removing token once they have left play is handled by runStateBasedActions.)
• If card has copy attribute, source is the stack. (Removing token once they have left play is handled by runStateBasedActions.)

Effects

• Card moved to destination location.
• If card is leaving play, remove all damage, counters, and gained attributes.
• If card has exileWhenLeaveStack attribute, move to exile and remove exileWhenLeaveStack instead.
• If card has undying, is moving from play to graveyard, and has no +1/+1 counters, add a +1/+1 counter instead. (Note: undying should move card to graveyard then back to play for owner, but since neither triggers nor owner tracking are implemented, this simplification is valid.)
• If card is entering play or changing controller, add summoned attribute.

target :: CardName -> GameMonad ()

Target a permanent.

Validates

• Card is in play.
• If card belongs to opponent, does not have hexproof.

targetInLocation :: CardLocation -> CardName -> GameMonad ()

Target a card in a non-play location.

Validates

• Card is in zone.

activate :: CardName -> ManaPool -> CardName -> GameMonad ()

Activate an ability of a permanent. See spendMana for additional mana validations and effects. Typically you will want to resolve after activating.

activate "Create Soldier" "3W" "Dawn of Hope" >> resolveTop

Validates

• Card is in play or graveyard.
• Card is controlled by actor.

Effects

• A card with activated is added to stack.

activatePlaneswalker :: CardName -> Int -> CardName -> GameMonad ()

Activate a loyalty ability of a planeswalker. Typically you will want to resolve after activating.

activatePlaneswalker2 "Get a card" (-1) "Karn, Scion of Urza" >> resolveTop

Validates

• Card is in play.
• Card has enough loyalty.

Effects

• Card loyalty is adjusted.

See activate for additional validations and effects.

attackWith :: [CardName] -> GameMonad ()

Start an attack with the given creatures.

attackWith ["Fanatical Firebrand"]

Validates

• Cards are in play.
• Cards have creature attribute.
• Cards either have haste or are missing summoned.
• Cards do not have defender.

Effects

• Cards become tapped, unless they have vigilance.
• Cards gain attacking attribute.
• Transitions to DeclareAttackers step.

combatDamage :: [CardName] -> CardName -> GameMonad ()

Apply combat damage between an attacker and blockers, using a simple damage assignment algorithm. For more complex assignments, use damage directly.

combatDamage ["Spirit 1", "Spirit 2"] "Angel"

See damage for other validations and effects.

Validates

• Attacker has attribute attacking.
• Attacker and blockers are in play.
• Attacker controlled by current actor.
• Blockers have attribute creature.

Effects

• Damage is dealt to blockers in order given, with the final blocker receiving any left over damage.
• If no blockers, damage is dealt to opposing player.
• If attacker has trample, any remaining damage is dealt to opposing player.

copySpell :: CardName -> CardName -> ExceptT String (ReaderT Env (StateT Board (WriterT [Step] Identity))) ()

Copy a spell on the stack, adding it to top of stack.

copySpell "Snap Copy" "Snap"

Validates

• Card is on stack.

Effects

• New card is on top of stack.

damage

Arguments

:: (Card -> Int)

A function that returns the amount of damage to apply, given the source card.

-> Target

Target to apply damage to

-> CardName

Source card

-> GameMonad ()

Applies damage from a source to a target.

damage (const 2) (targetPlayer Opponent) "Shock"

Validates

• Source exists.
• Damage is not less than zero.
• If targeting a card, target is in play and is either a creature or a planeswalker.

Effects

• Adds damage to the target.
• If target is a planeswalker, remove loyalty counters instead.
• If source has deathtouch and target is a creature and damage is non-zero, add deathtouched attribute to target.
• If source has lifelink, controller of source gains life equal to damage dealt.
• Note runStateBasedActions handles actual destruction (if applicable) of creatures and planeswalkers.

destroy :: CardName -> GameMonad ()

Destroy a permanent.

Validates

• Card is in play.
• Card is not indestructible

Effects

• Card is moved to graveyard. See move for possible alternate effects.

discard :: CardName -> GameMonad ()

Discard a card from the active player's hand.

discard "Mountain"

Validates

• Card exists in active player's hand.

Effects

• Card moved to graveyard.

exert :: CardName -> GameMonad ()

Exert a card. Works best when card has an associated effect that applies when exerted attribute is present.

withAttributes [flying]
  $ withEffect
      (matchInPlay <> matchAttribute exerted)
      (    matchLocation . view cardLocation
        <> const (matchAttribute creature)
      )
      (pure . over cardStrengthModifier (mkStrength (1, 1) <>))
  $ addCreature (2, 2) "Tah-Crop Elite"
attackWith ["Tah-Crop Elite"]
exert "Tah-Crop Elite"

Validates

• Card has tapped attribute.

Effects

• Card gains exerted attribute.

exile :: CardName -> GameMonad ()

Move a card to the Exile zone.

exile "Bridge from Below"

See moveTo for validations and effects.

fight :: CardName -> CardName -> GameMonad ()

Have one card fight another (each deals damage to the other).

Validates

• Card is in play.
• Card is a creature.

Effects

• Each card has damage dealt to it equal to the other's power. A creature fighting itself will take twice its power in damage.
• Note runStateBasedActions handles actual destruction (if applicable) of creatures.

modifyStrength :: (Int, Int) -> CardName -> GameMonad ()

Modify the strength of a card in play. It will be reset to base when the card leaves play.

modifyStrength (-2, -2) "Soldier"

Validates

• Card is in play.
• Card is a creature.

Effects

• Changes the strength modifier for the card.

moveTo :: Location -> CardName -> GameMonad ()

Move card to location with same controller.

moveTo Graveyard "Forest"

Validates

• Card exists.

Effects

• Card is moved to location.
• See move for possible alternate effects, depending on card

remove :: CardName -> GameMonad ()

spendMana :: ManaString -> GameMonad ()

Remove mana from the pool. Colored mana will be removed first, then extra mana of any type will be removed to match the colorless required.

spendMana "2RG"

Validates

• Mana specification is valid.
• Sufficient mana exists in pool.

Effects

• Mana pool is reduced.

tap :: CardName -> GameMonad ()

Taps a card.

Validates

• Card is in play.
• Card is not tapped.
• If creature, is not summoned or has haste.

Effects

• Card gains tapped attribute.

untap :: CardName -> GameMonad ()

Untaps a card.

Validates

• Card is in play.
• Card is tapped.

Effects

• Card loses tapped attribute.

validate :: CardMatcher -> CardName -> GameMonad ()

Validate that a card matches a matcher.

validate (matchAttribute "pirate") "Angrath's Marauders"

Validates

• Card matches matcher.

validateRemoved :: CardName -> GameMonad ()

Validates that a card is no longer present in the game. Particularly helpful for checking destruction of tokens.

validateRemoved "Angel"

Validates

• Name does not refer to a card.

validatePhase :: Phase -> GameMonad ()

Validates that the game is in a particular phase.

validatePhase BeginCombat

Validates

• Game is in the given phase.

validateCanCastSorcery :: GameMonad ()

Validates that a sorcery is able to be cast.

Validates

• Stack is empty.
• In a main phase.

validateLife :: Int -> Player -> GameMonad ()

Validates a player has a specific life total.

validateLife 0 Opponent

Validates

• Player life equals amount.

withStateBasedActions :: GameMonad a -> GameMonad a

Pause running of state-based actions for the duration of the action, running them at the end.

runStateBasedActions :: GameMonad ()

Run state-based actions. These include:

• If a creature does not have indestructible, and has damage exceeding toughess or deathtouched attribute, destroy it.
• If a card is a token and is not in play, remove it.
• If a card is a copy and is not on the stack, remove it.

These are run implicitly at the end of each step, so it's not usually needed to call this explicitly. Even then, using withStateBasedActions is usually preferred.

Running state-based actions can in turn trigger more state-based actions. This method loops until no more are generated, which has the potential for non-termination for pathological game states.

step :: String -> GameMonad a -> GameMonad a

Define a high-level step in the proof. A proof typically consists on multiple steps. Each step is a human-readable description, then a definition of that step using actions. If a step fails, no subsequent steps will be run. runStateBasedActions is implicitly called at the end of each step. Nested step invocations execute the nested action but have no other effects - generally they should be avoided.

fork :: String -> GameMonad () -> GameMonad ()

Branch off a labeled alternate line. Steps inside the fork will be reported at the end of the main line output.

gainLife :: Int -> GameMonad ()

Increments life total for current actor.

as Opponent $ gainLife 1

Effects

• Increases life total by amount

loseLife :: Int -> GameMonad ()

Decrements life total for current actor.

as Opponent $ loseLife 1

Effects

• Decreases life total by amount

setLife :: Int -> GameMonad ()

Sets life total for current actor.

as Opponent $ setLife 1

Effects

• Sets life total to amount

addEffect :: LayeredEffectPart -> CardName -> GameMonad ()

Adds an "until end of turn" effect to a card. Note in practice, since turns aren't modeled, the effect will stay around until the end of the solution.

addEffect (effectPTSet 1 1) "Soldier"

Effects

• Adds a new "until end of turn" effect to the card with the current timestamp.

withEffect

Arguments

:: EffectMonad CardMatcher

The set of cards to apply the effect to

-> [LayeredEffectPart]

The effect to apply

-> EffectName

Human-readable description, cosmetic only.

-> GameMonad ()

-> GameMonad ()

Add an effect to the created card. The effect will only apply when the card is in play.

effectPTSet :: (Int, Int) -> LayeredEffectPart

Constant variant of effectPTSetF.

effectPTSetF :: (Card -> EffectMonad (Int, Int)) -> LayeredEffectPart

Layer 7B effect to set the power and toughness of a creature.

effectPTAdjust :: (Int, Int) -> LayeredEffectPart

Constant variant of effectPTAdjustF

effectPTAdjustF :: (Card -> EffectMonad (Int, Int)) -> LayeredEffectPart

Layer 7C effect to adjust the power and toughness of a creature.

effectAddAbility :: CardAttribute -> LayeredEffectPart

Layer 6 effect to add an ability to a card. In practice, it adds adds a new CardAttribute.

effectNoAbilities :: LayeredEffectPart

Layer 6 effect to remove all abilities from a card. This doesn't temporary abilities added by addEffect.

effectAddType :: CardAttribute -> LayeredEffectPart

Layer 4 effect to add a type to a card. Since card types are modeled explicitly, it instead adds a new CardAttribute.

enabledInPlay :: EffectMonad Bool

Effect enabled definition to apply when a card is in play.

askSelf :: EffectMonad Card

The card that is generating the effect being applied.

viewSelf :: Getting b Card b -> ReaderT (Board, Card) Identity b

Apply a lens to askSelf.

askCards :: CardMatcher -> EffectMonad [Card]

Return cards fitting the given matcher.