Log in

Forge API

A reference guide for Scripting Cards using the API parsed by the Forge Engine.

Contents

Base Structure

By opening any file in the /res/cardsfolder folder you can see the basic structure of how the data is created. Here's an example of a vanilla creature:

Name:Vanilla Creature
ManaCost:2 G
Types:Creature Beast
Text:no text
PT:2/2


The name of this card is Vanilla Creature. It's casting cost is 2G. It has the types Creature and Beast. It will not display any additional text in the card's template. It has a Power-Toughness of 2/2. The text line appears only if any rules printed on card are not backed by abilities defined for the given card (in most cases presence of Text line means such abilities are hardcoded).

There are a few other Paramters that will appear in most, if not all, cards. These are

SVar:Picture:<PictureUrl>
Oracle:<Text>

PictureUrl is a URL to a picture on the web to be able to download an appropriate image.

Rarity and Set info are now defined in edition definition files. These can be found at /res/reditions path.

Oracle provides the Oracle text for a certain card.

We actually have a Python Script that runs to be able to fill in this missing information, so don't worry about filling it in. It's better to blame the automated script for messing things up.

Structures

Replacements

Replacements can be used in conjunction with AbilityEffect to create (currently only static) replacement effects.

Replacement

Triggers

Triggers can be used in conjunction with AbilityEffect abilities to create triggered abilities

Trigger

AbilityEffect

Our tried and true method for creating prototype SpellAbilities, working together with the other forms. These Effects mostly have AI setup for them. The best way to "see" them in action is to look up cards with similar effects and see how they work.

Ability Factory

Using Cost

Cost is a class that handles many types of costs that exist on a card. For each card that uses it, the order in which the cost is paid will always be the same.

Cost can be a bit complex, so make sure to read about it and check out the examples.

Using Target

Using Target is a simple object that handles Targeting any Game Object. There's some flexibility with how many targets and other corner cases.

ValidCards

getValidCards is a group of functions used throughout the codebase to filter all of the cards in the game down to a smaller subset for purposes like Targeting or Affecting.

SpellAbility_Restriction

SpellAbility_Restriction restricts when spells/abilities can be activated. Common examples are Putrid Leech's only activate this once per turn or different cards that can activate from Zones like the Hand or the Graveyard.

Static Abilities

Static_Ability.

Developer Mode

Forge_DevMode

Upcoming Cards

Forge_Upcoming

Remaining Cards

https://docs.google.com/spreadsheet/ccc?key=0Aipjpk0ZcU8fdFlMczZRR2tmazZGSGZYeDh1Z24teVE&usp=sharing

SVars

This list is a reminder for all developers and other people who want to add cards.

SVar:AltCost:[cost]

This SVar is for cards that have an Alternate cost, such as Force of Will. You are allowed to pay the Alternate Cost instead of the normal Mana cost when casting this spell.


SVar:AntiBuffedBy:[ValidCards]

If a permanent with this SVar is on the battlefield under human control the AI will play the specified cards in Main1. Applicable for cards like Heart Sliver or Timid Drake.


SVar:BuffedBy:[ValidCards]

If a permanent with this SVar is on the battlefield under its control the AI will play the specified cards in Main1. Applicable for creatures with a P/T setting static ability (Kithkin Rabble) or additional buffes (Radiant, Archangel).


SVar:EnchantMe:[Multiple]/[Once]

Creatures with "Multiple" in this SVar will always be prefered when the AI enchants (Rabid Wombat), creatures with "Once" only if they are not enchanted already (Gate Hound).


SVar:EquipMe:[Multiple]/[Once]

Creatures with "Multiple" in this SVar will always be prefered when the AI equippes (Myr Adapter), creatures with "Once" only if they are not equipped already (Kor Duelist).


SVar:HasAttackEffect:TRUE

Needs description.


SVar:MustBeBlocked:True

Needs description.


SVar:NeedsToPlayVar:[ValidCards]

Needs description.


SVar:PlayMain1:TRUE

The AI will play cards with this SVar in its first main phase. The AI will not play any permanents without this in Main1 (exceptions see below).


SVar:RemAIDeck:True

This SVar will prevent the card from appearing in random AI decks. It is applicable for cards the AI can't use at all like Dark Ritual and also for cards that the AI could use, but only ineffectively like Tortoise Formation. The AI won't draft these cards.


SVar:RemRandomDeck:True

This SVar will prevent the card from appearing in random decks. It is only applicable for cards that are too narrow for random decks like Root Cage or Into the North. The AI won't draft these cards.


SVar:SacMe:[number]

The AI will sacrifice these cards to pay costs. The higher the number the higher the priority. Example: Hatching Plans has SVar:SacMe:5.


SVar:X:Count$

Count is our general value computation function. It's quite varied with a lot of different things it can calculate and is often being updated.

Keywords

All keywords need to be prepended with "K:" to be parsed correctly. Each keyword must appear on a separate line

Example

Name:Flying Fast Creature
ManaCost:1 W W
Types:Creature Bird
Text:no text
PT:2/2
K:Flying
K:First Strike
End

Keywords without Parameters

This section is for Keywords that require no additional parameters and are one or two words long. Most of these you would see exactly on cards in the game.

  • Cascade
  • Changeling
  • Deathtouch
  • Defender
  • Double Strike
  • Epic
  • Exalted
  • Fear
  • First Strike
  • Flanking
  • Flash
  • Flying
  • Forestwalk
  • Haste
  • Hexproof
  • Horsemanship
  • Indestructible
  • Infect
  • Intimidate
  • Islandwalk
  • Landfall
  • Legendary landwalk
  • Lifelink
  • Living Weapon
  • Menace
  • Mountainwalk
  • Nonbasic landwalk
  • Persist
  • Plainswalk
  • Proliferate
  • Provoke
  • Reach
  • Rebound
  • Shadow
  • Shroud
  • Snow forestwalk
  • Snow islandwalk
  • Snow landwalk
  • Snow mountainwalk
  • Snow plainswalk
  • Snow swamp walk
  • Soulbond
  • Split second
  • Storm
  • Sunburst
  • Swampwalk
  • Totem Armor
  • Trample
  • Unblockable
  • Undying
  • Vigilance
  • Wither

Keywords with parameters

This section is for Keywords that require additional parameters. Most of these keywords are fairly simple to understand and are similar to the keywords used by the paper version.

Anything that isn't a known Keyword will be explained what it does. This is a work in progress and a detailed description will come at a later date.

  • AdjustLandPlays:{params}
  • Alternative Cost {cost}
  • Amplify:{cost}:{validType(comma separated)}
  • Annihilator {magnitude}
  • Bloodthirst {magnitude}
  • Bushido {magnitude}
  • CantBeBlockedBy {ValidCards}
  • CantBlock {ValidCards}
  • Champion:{validType}
  • CostChange:{params}
  • Cumulative upkeep:{cost}
  • Cycling:{cost}
  • Devour:{magnitude}
  • Dredge {DredgedCards}
  • Echo:{cost}
  • Enchant {params} [Curse]
  • Enchant {Type}
  • eqPump {EquipCost}:{params}
  • etbCounter:{CounterType}:{CounterAmount}
  • ETBReplacement:{Control/Copy/Other}:{AbilitySVar}[:Optional]
  • Evoke:{cost}
  • Fading:{FadeCounters}
  • Flashback {cost}
  • Graft {value}
  • Haunt:{ability}:{Description}
  • Kicker:{cost}
  • Level up:{cost}
  • Madness:{cost}
  • maxLevel:{magnitude}
  • MayEffectFromOpeningHand:{Effect}
  • Miracle:{cost}
  • Modular {Counters}
  • Morph:{cost}
  • Multikicker {magnitude}
  • Poisonous {magnitude}
  • PreventAllDamageBy {ValidCard}
  • Protection:{ValidCards}:{Description}
  • Rampage {magnitude}
  • Recover:{cost}
  • Replicate {cost}
  • Ripple:{magnitude}
  • Scry (magnitude}
  • Soulshift:{magnitude}
  • Suspend:{turns}:{cost}
  • Transmute:{cost}
  • TypeCycling:{Type}:{cost}
  • Unearth:{cost}
  • Upkeep:{cost}
  • Vanishing:{TimeCounters}

Longer Card Properties

Plaintext properties/triggers. This section is for Keywords that are two words or longer. CARDNAME is replaced by the card's name.

  • All creatures able to block CARDNAME do so.
  • At the beginning of the end step, destroy CARDNAME.
  • At the beginning of the end step, exile CARDNAME.
  • At the beginning of the end step, sacrifice CARDNAME.
  • At the beginning of the end step, you lose the game.
  • At the beginning of your upkeep, CARDNAME deals {num} damage to you unless you pay:{cost}
  • At the beginning of your upkeep, destroy CARDNAME unless you pay:{cost}
  • At the beginning of your upkeep, sacrifice CARDNAME unless you pay:{cost}
  • CARDNAME assigns no combat damage
  • CARDNAME attacks each turn if able.
  • CARDNAME can attack as though it didn't have defender.
  • CARDNAME can attack as though it had haste.
  • CARDNAME can block creatures with flying.
  • CARDNAME can block creatures with shadow as though they didn't have shadow.
  • CARDNAME can block only creatures with flying.
  • CARDNAME can only attack alone.
  • CARDNAME can't attack.
  • CARDNAME can't attack if defending player controls an untapped creature with power {rest of text string}
  • CARDNAME can't attack or block.
  • CARDNAME can't attack unless defending player controls an Island.
  • CARDNAME can't attack unless defending player controls a Mountain.
  • CARDNAME can't attack unless defending player controls a snow land.
  • CARDNAME can't be blocked by artifact creatures. (Deprecated)
  • CARDNAME can't be blocked by creatures with flying. (Deprecated)
  • CARDNAME can't be blocked by creatures with power {rest of text string}
  • CARDNAME can't be blocked by more than one creature.
  • CARDNAME can't be blocked by Walls.
  • CARDNAME can't be blocked by white creatures.
  • CARDNAME can't be blocked except by artifact creatures and/or white creatures.
  • CARDNAME can't be blocked except by black creatures.
  • CARDNAME can't be blocked except by creatures with flying.
  • CARDNAME can't be blocked except by two or more creatures.
  • CARDNAME can't be blocked except by Walls.
  • CARDNAME can't be blocked except by Walls and/or creatures with flying.
  • CARDNAME can't be countered.
  • CARDNAME can't be enchanted.
  • CARDNAME can't be equipped.
  • CARDNAME can't be regenerated.
  • CARDNAME can't be the target of Aura spells.
  • CARDNAME can't be the target of spells.
  • CARDNAME can't block.
  • CARDNAME can't block creatures with power {rest of text string}
  • CARDNAME can't have counters placed on it.
  • CARDNAME can't transform
  • CARDNAME doesn't untap during your untap step.
  • CARDNAME enters the battlefield tapped.
  • CARDNAME enters the battlefield tapped unless you control a {land} or a {land}.
  • CARDNAME enters the battlefield tapped unless you control two or fewer other lands.
  • CARDNAME is {color}.
  • CARDNAME must be blocked if able.
  • CARDNAME's activated abilities can't be activated.
  • CARDNAME's power and toughness are switched
  • CARDNAME untaps during each other player's untap step.
  • Creatures can't attack unless their controller pays:{params}
  • Damage that would be dealt by CARDNAME can't be prevented.
  • Damage that would reduce your life total to less than 1 reduces it to 1 instead.
  • Enchant artifact
  • Enchant creature
  • Enchant creature with converted mana cost 2 or less
  • Enchant creature without flying
  • Enchant red or green creature
  • Enchant land
  • Enchant land you control
  • Enchant tapped creature
  • If a card would be put into an opponent's graveyard from anywhere, exile it instead.
  • If a card would be put into your graveyard from anywhere, exile it instead.
  • If a spell or ability an opponent controls causes you to discard CARDNAME, put it onto the battlefield instead of putting it into your graveyard.
  • If CARDNAME would be put into a graveyard from anywhere, reveal CARDNAME and shuffle it into its owner's library instead.
  • If CARDNAME would be put into a graveyard this turn, exile it instead. (Deprecated)
  • If CARDNAME would be put into a graveyard, exile it instead.
  • If CARDNAME would leave the battlefield, exile it instead of putting it anywhere else.
  • If damage would be dealt to CARDNAME, prevent that damage. Remove a +1/+1 counter from CARDNAME.
  • May be played
  • May be played by your opponent
  • May be played by your opponent without paying its mana cost
  • May be played without paying its mana cost
  • May be played without paying its mana cost and as though it has flash
  • No more than one creature can attack each combat.
  • No more than one creature can block each combat.
  • No more than two creatures can attack you each combat.
  • No more than two creatures can block each combat.
  • Permanents don't untap during their controllers' untap steps
  • Play with the top card of your library revealed.
  • Play with your hand revealed.
  • Players play with the top card of their libraries revealed.
  • Prevent all combat damage that would be dealt to and dealt by CARDNAME.
  • Prevent all combat damage that would be dealt to CARDNAME.
  • Prevent all damage that would be dealt to CARDNAME.
  • Prevent all damage that would be dealt to CARDNAME by artifact creatures.
  • Protection from black
  • Protection from blue
  • Protection from green
  • Protection from red
  • Protection from white
  • Protection from artifacts
  • Protection from Clerics
  • Protection from colored spells
  • Protection from creatures
  • Protection from Demons
  • Protection from Dragons
  • Protection from enchantments
  • Protection from Goblins
  • Protection from Gorgons
  • Remove CARDNAME from your deck before playing if you're not playing for ante.
  • Reveal the first card you draw each turn.
  • Skip your draw step.
  • Skip your next combat phase.
  • Skip your next draw step.
  • Skip your next untap step.
  • Spells and abilities your opponents control can't cause you to sacrifice permanents.
  • When CARDNAME is dealt damage, destroy it. [It can't be regenerated.]
  • When CARDNAME is put into a graveyard from anywhere, reveal CARDNAME and shuffle it into its owner's library instead. (Deprecated)
  • When CARDNAME is put into a graveyard from anywhere, reveal CARDNAME and its owner shuffles his or her graveyard into his or her library. (Deprecated)
  • When CARDNAME is put into a graveyard from anywhere, shuffle it into its owner's library.
  • Whenever a creature dealt damage by CARDNAME this turn is put into a graveyard, put a +1/+1 counter on CARDNAME.
  • You can't pay life to cast spells or activate abilities.
  • You can't sacrifice creatures to cast spells or activate abilities.
  • You can't draw cards.
  • You can't gain life.
  • You can't lose the game.
  • You can't win the game.
  • You don't lose the game for having 0 or less life.
  • You may cast nonland cards as though they had flash.
  • You may choose not to untap CARDNAME during your untap step.
  • You may have CARDNAME assign its combat damage as though it weren't blocked.
  • You may look at this card.
  • Your opponent may look at this card.
  • Your opponents can't lose the game.