diff --git a/docs/Card-scripting-API/AbilityFactory.md b/docs/Card-scripting-API/AbilityFactory.md index 959833fe2b5..1305fa3721a 100644 --- a/docs/Card-scripting-API/AbilityFactory.md +++ b/docs/Card-scripting-API/AbilityFactory.md @@ -1,66 +1,73 @@ -[[_TOC_]] - -_NOTE: These factories are refactored from time to time (often to adapt to new sets), so while some entries could be slightly outdated, the base information should still be correct._ - AbilityFactory parses differently from the Keyword parser. Your Ability line will look more like this: -`A:{AB/SP/DB/ST}$ | {Necessary$ Parameters}| {Separated$ By} | {Pipes$ Here}` +`A:{AB/SP/DB/ST}$ | {Necessary$ Parameters} | {Separated$ By} | {Pipes$ Here} | [Optional$ Values]` In most cases, each AF subclass implements both the Spell and Ability. Much of the code is shared, so creating the data object will look very similar. - - AB is for Activated Abilities. - - SP is for Spell. - - DB is for Drawback and for many abilities that are subsidiary to - other things, like replacements. They are only used to chain AFs - together, and will never be the root AF. - - ST is for Static, this gets used in case the API should resolve without using the stack (e.g. special actions) + - **AB** is for Activated Abilities + - **SP** is for Spell + - **DB** is for Drawback and many abilities that are subsidiary to other things, like replacements. They are only used to chain AFs together, and will never be the root AF + - **ST** is for Static, this gets used in case the API should resolve without using the stack
(e.g. the unique *Circling Vultures* special action is directly implemented in the script this way) -### Common Parameters +>*NOTE:* +> - these factories are refactored from time to time (often to adapt to new sets), so while some entries could be slightly outdated, the base information should still be correct +> - a few factories also have _*All_ variants, these are slowly being phased out +> - some parameters are only added for very exotic cards, these won't be included here to keep the focus on understanding the general concepts of scripting +> - when in doubt you can always cross check with the [available APIs](https://github.com/Card-Forge/forge/tree/master/forge-game/src/main/java/forge/game/ability/effects) code -#### Cost / UnlessCost +# Common Parameters -`Cost$ ` is the appropriate way to set the Cost of the Ability. Currently for spells, any additional costs including the original Mana cost need to appear in the Cost parameter in the AbilityFactory. For each card that uses it, the order in which the cost is paid will always be the same. +## Cost / UnlessCost -Secondary abilities such as the DB executed by triggers or replacements don't need costs. (This is one reason to use DB over AB in these cases.) +`Cost$ ` is the appropriate way to set the cost of the ability. Currently for spells, any additional costs including the original Mana cost need to appear in the Cost parameter in the AbilityFactory. For each card that uses it, the order in which the cost is paid will always be the same. + +Secondary abilities such as the DB executed by triggers or replacements (usually) don't need costs. (This is one reason to use DB over AB in these cases.) Read more about it in [Costs](Costs) -#### Target / Defined +## ValidTgts / Defined -There are two different ways to Target. One or the other will need to be used for Spells/Abilities that target. If your effect does not target, but instead defines what will be affected by the Spell/Ability, use the Defined Parameter. +Most effects need to know (at least implicitly) which players or objects they're trying to affect. There are two different ways for that: +- `ValidTgts` will need to be used for abilities that target +- if your ability instead describes on what it's applied use `Defined` Read more about it in [Affected / Targets](Targeting) -#### Restriction +## Restrictions / Conditions -[Restriction](Restrictions) restricts when spells/abilities can be activated or resolved. 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. +Restrictions limit when abilities can be put on the stack and Conditions apply during resolving. 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. -#### SpellDescription +Read more about it in [Restriction](Restrictions) + +## SpellDescription SpellDescription is how the text of the ability will display on the card and in the option dialog for cards with multiple abilities. The SpellDescription for secondary abilities (both AB and DB) is now displayed when (and if) the ability prompts for user input in the prompt pane so it is useful to put some nice text there. -#### StackDescription +## StackDescription *(Optional)* StackDescription is the description the ability will have on the stack. This is automatically generated by the effect, but may be overridden using this parameter. This is sometimes needed with complex effects, when the generated text can't handle some details. Properties of the spell can be accessed like this: {c:Targeted}. You can reuse the spell text by just putting `SpellDescription` or `None` to leave it empty. -#### AI instructions +## Remember* -IsCurse$ True - For effects that are normally treated positive e. g. Pump +Remembering is often needed when a card becomes a new object, which is then further affected by the ability. Typical example: [Flicker](https://github.com/Card-Forge/forge/blob/master/forge-gui/res/cardsfolder/f/flicker.txt)
+Because cards keep their remembered parts when changing zones manual [cleanup](#Cleanup) is usually required. + +## AI params + +`IsCurse$ True` - For effects that are normally treated positive e.g. Pump `AITgts$ BetterThanEvalRating.130` -## Factories +# Factories (in Alphabetical Order) -In Alphabetical Order. - -### AlterLife +## AlterLife AlterLife is for Abilities that Alter a player's life total. -#### GainLife +### GainLife Have a player gain the specified amount of life. @@ -71,7 +78,7 @@ LifeAmount$ is required. This is how much life you will gain. Defined is optional, if it appears the defined player(s) gain life. Target is optional, if it appears and Defined doesn't then targeted player(s) gain life. -#### LoseLife +### LoseLife Have a player lose the specified amount of life. @@ -85,19 +92,7 @@ Remember, if Defined is missing, the default for Players is "You" Part of resolving sets the **SVar AFLifeLost** to the amount of life lost by all players. -#### Poison - -Poison gives a player the specified number of poison counters. - -`A:AB$ Poison | Cost$ B T | ValidTgts$ Player | TgtPrompt$ Select target player | Num$ 2 | SpellDescription$ Target player gets 2 poison counters.` - -Parameters: - - - Num (required) - the number of poison counters to give - -Target is optional and used if available. Defined is optional and used if no Target (defaults to "You"). - -#### SetLife +### SetLife SetLife sets one or both player's life total to a specified value (i.e. "your life total becomes 20" or "Target player's life total is equal to @@ -111,7 +106,7 @@ LifeAmount (required) - the value to set the life total(s) to Defined is optional. If it exists, it will be used. Target is optional. If it exists and defined doesn't it will be used. Default player is "You". -#### ExchangeLife +### ExchangeLife ExchangeLife switches the Life total of two players. @@ -123,7 +118,7 @@ defined doesn't it will be used. If there aren't two determined players by the SA, the activating player is added as the second player. -### Animate +## Animate Animate handles animation effects like "This card becomes a 5/5 green creature with flying until end of turn." It is designed to handle @@ -184,7 +179,7 @@ Parameters: Target is optional, will be used if possible. Defined is optional, will be used if no Targets (Self by default) -### Attach +## Attach Attach is being used directly only for Auras, primarily for Aura Spells, but also for Auras entering the battlefield by some effect. @@ -210,13 +205,13 @@ Parameters: Attach separates the actually granting of abilities from the attaching to permanents to streamline how things work. -### BecomeMonarch +## BecomeMonarch -### Bond +## Bond -Soulbonding two creatures +Soulbonding two creatures. Only used internally by the engine. -### Branch +## Branch Sometimes, an ability might do certain things when a specific condition is true, and other things if not. This can be implemented by using `Branch`. The branch evaluates the SVar specified by the property `BranchConditionSVar`, using the comparison defined with `BranchConditionSVarCompare` (such as `GTY`, `LT1`, etc). Depending on whether the condition evaluated to true or false, the subability defined by `TrueSubAbility` or `FalseSubAbility` is executed. @@ -229,11 +224,556 @@ SVar:PutLandCreature:DB$ ChangeZone | Origin$ Hand | Destination$ Battlefield | SVar:X:Count$Valid Enchantment.YouCtrl ``` +## Charm -### ChangeState +This allows cards that have a mode to be chosen to occur after a trigger. + +Parameters + + - CharmNum - Number of Modes to Choose + - Choices - A Comma delimited list of SVars containing the Modes + +## Choose* + +These can be used to chain effects together. However for common cases many effects already support this directly, e.g. `PutCounter | Choices$``.
+Besides making the script shorter using such shortcuts usually also helps the AI making better use of the effect. + +### ChooseType + +This can be used when you are asked to choose a card type or creature type. + + - Type - Required - Can be Card or Creature + - InvalidTypes - Optional - Use to specify any type that cannot be chosen (ex: "Choose any creature type except Wall") + +The Defined is for target players. + +## Clash + +This AF handles clashing. It takes two special parameters: WinSubAbility and +OtherwiseSubAbility. They are both optional and work the same way, +namely that it contains the name of an SVar that in turn contains a +drawback to be executed. The example below is for Release the Ants. + +`A:SP$ DealDamage | Cost$ 1 R | Tgt$ TgtCP | NumDmg$ 1 | SubAbility$ DBClash | SpellDescription$ Release the Ants deals 1 damage to target creature or player. Clash with an opponent. If you win, return CARDNAME to its owner's hand.` +`SVar:DBClash:DB$ Clash | WinSubAbility$ DBReturn` +`SVar:DBReturn:DB$ ChangeZone | Defined$ Self | Origin$ Stack | Destination$ Hand` + +## Cleanup + +A non-functional, maintenance AF used for Cleaning up certain Variables before a Spell finishes Resolving. + +Parameters + + - ClearRemembered$ (optional) Set to True to clear this card's + remembered list. Generally useful for Cards that Remember a card, do + something to it, then need to forget it once it's done. + - ClearImprinted$ (optional) Set to True to clear the list of + imprinted cards. + - ClearChosenX$ (optional) Set to True to clear the chosen X value. + - ClearTriggered$ (optional) Set to True to clear any delayed triggers + produced by this card. + - ClearCoinFlips$ (optional) Set to True to clear the remembered coin + flip result. + - ClearChosenCard$ (optional) Set to True to clear the chosen cards. + - ForgetDefined$ (optional) If present, remove the specified cards + from this card's remembered list. + +## Control + +### GainControl + +Example: Act of Aggression + +`A:SP$ GainControl | Cost$ 3 PR PR | ValidTgts$ Creature.OppCtrl | TgtPrompt$ Select target creature an opponent controls. | LoseControl$ EOT | Untap$ True | AddKWs$ Haste | SpellDescription$ Gain control of target creature an opponent controls until end of turn. Untap that creature. It gains haste until end of turn.` + +Parameters: + +- NewController(Targeted player, if there is no target player, the + default is the ActivatingPlayer) +- AllValid(all valid types, no targets) +- LoseControl(LeavesPlay, Untap, LoseControl, EOT(end of turn)) + +### ControlExchange + +### ControlSpell + +## Copy* + +### CopyPermanent + +Copies a permanent on the battlefield. + +Parameters: + + - NumCopies - optional - the number of copies to put onto the + battlefield. Supports SVar:X:????. + - Keywords - optional - a list of keywords to add to the copies + - AtEOT - optional + - Sacrifice - set to this is copy should be sacrificed at End of + Turn + - Exile - set to this is copy should be exiled at End of Turn + +### CopySpellAbility + +Copies a spell on the stack (Twincast, etc.). + +## Counter + +Countering Spells or Abilities. + +`A:SP$ Counter | Cost$ 1 U | TargetType$ Spell | TgtPrompt$ Select target spell | ValidTgts$ Card | UnlessCost$ 3 | SpellDescription$ Counter target spell unless its controller pays 3.` +`A:SP$ Counter | Cost$ U | TgtPrompt$ Select target Activated or Triggered Ability | ValidTgts$ Card | TargetType$ Activated,Triggered | SpellDescription$ Counter target activated or triggered ability.` +`A:SP$ Counter | Cost$ G | TargetType$ Spell | ValidTgts$ Instant,Aura | TargetValidTargeting$ Permanent.YouCtrl | SpellDescription$ Counter target instant or Aura spell that targets a permanent you control. ` + +Parameters + + - TargetType - Can be Spell,Activated,Triggered. If more than one, + just put a comma in between. + - ValidTgts - a "valid" expression for types of source card (if you + don't know what it is it's just "Card") + - TargetValidTargeting- a "valid" expression for targets of this + spell's target + - Destination - send countered spell to: (only applies to Spells; ignored for Abilities) + - Graveyard (Default) + - Exile + - TopDeck + - Hand + - BottomDeck + - Shuffle + +## Counters* + +Factories to handle counters on cards. + +### Poison + +Poison gives a player the specified number of poison counters. + +`A:AB$ Poison | Cost$ B T | ValidTgts$ Player | TgtPrompt$ Select target player | Num$ 2 | SpellDescription$ Target player gets 2 poison counters.` + +Parameters: + +- Num (required) - the number of poison counters to give + +Target is optional and used if available. Defined is optional and used if no Target (defaults to "You"). + +### PutCounter + +Put any type of counter on a game object. + +`A:AB$ PutCounter | Cost$ T | CounterType$ CHARGE | CounterNum$1 | SpellDescription$ Put a charge counter on CARDNAME.` +`A:SP$ PutCounter | Cost$ G | Tgt$ TgtC | CounterType$ P1P1 | CounterNum$ 1 | SpellDescription$ Put a charge counter on CARDNAME.` + +Target is optional. If no Target is provided, the permanent will put counters on itself. + + - CounterType (required) specifies the type of counter and should + appear in all caps. It should be one of the values in the Counters + enum. + - CounterNum (required) specifies how many counters will be put on + the chosen card. + +### PutCounterAll + +Put any type of counter on all valid cards. + + - CounterType (required) specifies the type of counter and should + appear in all caps. It should be one of the values in the Counters + enum. + - CounterNum (required) specifies how many counters will be put on + the chosen cards. + - ValidCards (required) specifies the cards to add counters to. + +### RemoveCounter + +Remove any type of counter from a card. + +Target is optional. If no Target is provided, the permanent will remove +counters from itself. + + - CounterType (required) specifies the type of counter and should + appear in all caps. It should be one of the values in the Counters + enum. + - CounterNum (required) specifies how many counters will be removed + from the chosen card. + - UpTo is optional. If an effect states you may remove "up to X + counters", set this to True. + +### RemoveCounterAll + +Remove any type of counter from all valid cards. + + - CounterType$ (required) specifies the type of counter and should + appear in all caps. It should be one of the values in the Counters + enum. + - CounterNum$ (required) specifies how many counters will be removed + from the chosen cards. + - ValidCards$ (required) specifies the card to remove counters from. + +### Proliferate + +No own parameters. + +### MoveCounters + +Used for cards that Move Counters on Resolution, requiring the Host card +to have Counters for the Move to occur. + +Parameters + + - Source - The Source of the Moving Counters + - Defined - The Destination of the Moving Counters + - CounterType - The type of counter to move. + - CounterNum - The number of counters to move. + +## Damage + +### DealDamage + +Deal damage to a specified player or permanent. + +`A:AB$ DealDamage | Cost$ T | Tgt$ TgtCP | NumDmg$ 1 | SpellDescription$ CARDNAME deals 1 damage to target creature or player.` + +NumDmg is required. This is the amount of damage dealt. + +### EachDamage + +## Debuff + +Parameters + + - Keywords + - Duration + +An AbilityFactory for Removing Keywords, either temporarily or for longer durations. + +## Destroy + +These APIs handles destruction of cards on the battlefield. + +`A:SP$Destroy | Cost$ 1 W W | ValidTgts$ Artifact,Enchantment | TgtPrompt$ Select target artifact or enchantment | SpellDescription$ Destroy target artifact or enchantment.` + +## Effect + +Effect is an oddball of the AF family. Where usually AFs have similarities to each other to help with AI use, Effect doesn't fall under that jurisdiction. In general, an effect is some type of SA that +lasts longer than its resolution. + +A good example is High Tide. For the rest of the turn, High Tide makes +all Islands produce an extra mana. It doesn't matter if the Island was +in play, if it turned into an Island after High Tide was cast, any of that. + +`A:SP$ Effect | Cost$ U | Name$ High Tide Effect | Triggers$ IslandTrigger | SVars$ TrigMana | SpellDescription$ Until end of turn, whenever a player taps an Island for mana, that player adds U to his or her mana pool (in addition to the mana the land produces).` +`SVar:IslandTrigger:Mode$ TapsForMana | ValidCard$ Island | Execute$ TrigMana | TriggerDescription$ Whenever a player taps an Island for mana, that player adds U to his or her mana pool (in addition to the mana the land produces).` +`SVar:TrigMana:AB$Mana | Cost$ 0 | Produced$ U | Amount$ 1` + +Effect is most similar to Token as it creates a pseudo-permanent, except +Effect creates in the command zone rather than the battlefield. It stays +active there for a set Duration. + +Parameters + + - Abilities,Triggers,SVars are comma separated lists which contain + SVars that point to the appropriate type that the Effect will gain. + - Duration is how long the Effect lasts. Right now, most effects will + last Until End of Turn. In the future, they may have other + conditions. + +Duration$ Permanent for effects that have no specific Duration. + + - Stackable$ False - Most Effects are assumed to be Stackable. By + setting the Stackable Flag to False, the AI will know having a + second one in play is useless, so will save it's Resource for + something else. + - Image - a file\_name\_without\_extension (image needs to reside in + the tokens directory) + +## Explore + +## Fight + +## Fog + +Fog is an ability based on the original Fog spell. "Prevent all combat +damage that would be dealt this turn." While this could be done with an +effect, the specialized nature of the AI gives it its own AF. + +## Game outcome + +### GameDraw + +### GameLoss + +### GameWin + +### RestartGame + +Used in the script of *Karn Liberated* + +## Goad + +## Investigate + +## Mana + +For lands or other permanent to produce mana. + +`A:AB$ Mana | Cost$ T | Produced$ | SpellDescription$ Add W to your mana pool.` + +In this example ManaType would be W. + +## Manifest + +## PermanentState + +API for things that alter a permanent's state. + +### Phases + +### SetState Changing a cards State. This is mostly for Flip Cards or the Transform mechanic. +### Tap + +`A:AB$ Tap | Cost$ R | ValidTgts$ Wall | TgtPrompt$ Select target wall | SpellDescription$ Tap target wall.` + +### TapOrUntap + +### Untap + +`A:AB$ Untap | Cost$ G | ActivationLimit$ 1| SpellDescription$ Untap CARDNAME. Activate this ability only once each turn.` +`A:SP$ Untap | Cost$ W | ValidTgts$ Permanent | TgtPrompt$ Select target permanent | SpellDescription$ Untap target permanent.` + +Target is optional. If not provided, will untap the permanent with this ability. + +## Play + +Playing a card or cards as part of SA. The player may have to make a +choice about which card to play if there are more choices than the +number of cards to play. + +Sunbird's Invocation uses many of the parameters. + +Amount - How many cards can be played (a non-negative integer or "All"). + +Valid - Selection criteria for valid cards from the zone to cast. + +ValidSA - Applied after Valid, this will filter based on all spells of the cards. + +ValidZone - The zone to look in to determine the valid cards. + +ShowCards - Other cards in the zone to show when selecting valid cards. + +Optional - Casting the card is optional. + +RememberPlayed - Remember the card played. + +ForgetRemembered - Remove all remembered cards from the source (but only +if a card was successfully played) + +ForgetTargetRemembered - Remove the played card from remembered cards +(but only if it was successfully played) + +WithoutManaCost - The card can be cast without mana payment. + +## PreventDamage + +AF damage prevention effects. + + - A:SP$ PreventDamage | Cost$ W | ValidTgts$ Creature | Amount$ 3 + | TgtPrompt$ Select target creature | SpellDescription$ Prevent + the next 3 damage that would be dealt to target creature this + turn. + +## Protection + +Protection grants protection from colors or cards types, or creature +types. Anything that has "Protection from ..." + +Gains - required - the thing to gain protection from (green, artifacts, +Demons, etc.) or "Choice" if you can choose one of... + +Choices - optional +- if Gains$ Choice then this is a comma-delimited list of choices + +## Pump + +This factory handles pumping creatures power/toughness or granting abilities to permanents (usually creatures). + + - A:AB$ Pump | Cost$ R | NumAtt$ +1 | SpellDescription$ CARDNAME + gets +1/+0 until end of turn. + - A:SP$ Pump | Cost$ 1 U | ValidTgts$ Creature | KW$ Shroud| + SpellDescription$ Target creature gains shroud until end of + turn. | TgtPrompt$ Select target creature. + +Target is optional. If it's not provided, the activating permanent will be pumped. + +NumAtt$ is optional, will pump Power. + +NumDef$ is optional, will pump Toughness. + +KW$ is optional, will give temporary keywords. + +## Regenerate + +Regenerate is similar to abilities like Pump. But for creating +Regeneration shields. + + - A:AB$ Regenerate | Cost$ B | SpellDescription$ Regenerate + CARDNAME + - A:SP$ Regenerate | Cost$ W | ValidTgts$ Creature | TgtPrompt$ + Select target creature | SpellDescription$ Regenerate target + creature. + +Target is optional. If not provided, will regenerate the permanent with this ability. + +## Repeat + +Repeat the specified ability. + +### Repeat + +`A:SP$ Repeat | Cost$ 3 B B | RepeatSubAbility$ DBDig | RepeatOptional$ True` + + - MaxRepeat - optional - the maxium times to repeat, execute repeat + ability at least once + - RepeatSubAbility - required - setup subability to repeat + - RepeatOptional - optional - you make the choice whether to repeat + the process + - RepeatPresent, RepeatCompare, RepeatDefined, RepeatCheckSVar, + RepeatSVarCompare - optional - condition check + +### RepeatEach + + - RepeatSubAbility - required - to set up repeat subability + - RepeatCards - to repeat for each valid card (zone: present zone of + the valid repeat cards, default: battlefield) + - DefinedCards + - RepeatPlayers - to repeat for each valid player + - RepeatCounters - to repeat for each valid counters + +## Reveal + +### RevealHand + +Look at a player's hand. + +Target or Defined is required. + +`A:AB$ RevealHand | Cost$ T | ValidTgts$ Player | TgtPrompt$ Select target player | SpellDescription$ Look at target player's hand.` + +### Reveal + +`A:AB$ Reveal | Cost$ 2 U T | Defined$ You | RevealValid$ Card.Blue | AnyNumber$ True | RememberRevealed$ True` + +Parameters: + + - RevealValid: to limit the valid cards. + - AnyNumber + - Random + - RememberRevealed: to remember the cards revealed + +### PeekAndReveal + +This AF is very similar to things that Dig can do, but handle a much +simpler form, with less complex coding underneath. Similar to how +RearrangeTopOfLibrary could be handled with Dig. + +Primarily used with cards that allow you to Peek at the top card of your +library, and allow you to reveal it if it's of a certain type. The +Kinship cards fit this bill perfectly, so they are used to simplify the +complex popups that would be required if using multiple Dig +SubAbilities. + +RevealOptional - Whether or not the Reveal is optional. + +RememberRevealed - Whether to remember the revealed cards (after +filtering by Valid) + +RememberPeeked - Whether to remember the peeked cards (only if they are +not revealed\!) + +RevealValid - defaults to Card, but allows you to set a specific +ValidType if you can only have certain things + +PeekAmount - defaults to 1, but allows you to peek at multiple cards if +possible + +## RollDice + +## Sacrifice + +Usually you choose a player and that player has to sacrifice something + +`A:SP$ Sacrifice | Cost$ 1 B | ValidTgts$ Player | SacValid$ Creature | SacMessage$ Creature | Amount$ 2 | SpellDescription$ Target player sacrifices a creature.` + +Destroy$ True - An optional parameter for destroying permanents target +player chooses (eg: Burning of Xinye, or Imperial Edict). + +`A:SP$ Sacrifice | Cost$ 1 B | ValidTgts$ Opponent | SacValid$ Creature | SacMessage$ Creature | Destroy$ True | SpellDescription$ Target opponent chooses a creature he or she controls. Destroy it.` + +## Scry + +`A:AB$ Scry | Cost$ 1 T | ScryNum$ 2` + +## StoreSVar + +## Token + +Token simply lets you create tokens of any type. + +`A:SP$ Token | Cost$ 3 W U | TokenImage$ W 1 1 Bird Flying | TokenAmount$ X | TokenName$ Bird | TokenTypes$ Creature,Bird | TokenOwner$ You | TokenColors$ Blue | TokenPower$ 1 | TokenToughness$ 1 | TokenKeywords$ Flying` + +This ability factory does not take a target. All the parameters are +mandatory except for TokenKeywords. If you provide a non-integer for +TokenAmount, TokenPower or TokenToughness the AF will attempt to look for +an SVar of that name and interpret it's contents as a Count$ line. Worth +noting is that TokenTypes and TokenColors are simple commaseparated +lists while TokenKeywords is a list where the items are separated by +"\<\>". If TokenImage is not provided, the factory will attempt to +construct a filename on it's own. TokenOwner can use Defined-like +parameters, such as "You" "Opponent" or the new Triggered-Variables. + +You can also use the parameters TokenAbilities$, TokenTriggers$ and +TokenSVars$ to give the created tokens any number of either. For +example, here's how Growth Spasm creates an Eldrazi Spawn token complete +with ability. + + SVar:DBToken:DB$Token | TokenAmount$ 1 | TokenName$ Eldrazi Spawn | TokenTypes$ Creature,Eldrazi,Spawn | TokenOwner$ You | TokenColors$ Colorless | TokenPower$ 0 | TokenToughness$ 1 | TokenAbilities$ ABMana SVar:ABMana:AB$Mana | Cost$ Sac<1/CARDNAME> | Produced$ 1 | Amount$ 1 | SpellDescription$ Add 1 to your mana pool. + +As another example, here's Mitotic Slimes' use of TokenTriggers$: + + T:Mode$ ChangesZone | Origin$ Battlefield | Destination$ Graveyard | ValidCard$ Card.Self | Execute$ TrigTokenSenior | TriggerDescription$ When CARDNAME is put into a graveyard from the battlefield, put two 2/2 green Ooze creature tokens onto the battlefield. They have "When this creature is put into a graveyard, put two 1/1 green Ooze creature tokens onto the battlefield." + SVar:TrigTokenSenior:AB$ Token | Cost$ 0 | TokenImage$ g 2 2 ooze | TokenName$ Ooze | TokenTypes$ Creature,Ooze | TokenColors$ Green | TokenOwner$ You | TokenPower$ 2 | TokenToughness$ 2 | TokenAmount$ 2 | TokenTriggers$ TriggerJunior | TokenSVars$ TrigTokenJunior + SVar:TriggerJunior:Mode$ ChangesZone | Origin$ Battlefield | Destination$ Graveyard | ValidCard$ Card.Self | Execute$ TrigTokenJunior | TriggerDescription$ When this creature is put into a graveyard, put two 1/1 green Ooze creature tokens onto the battlefield. SVar:TrigTokenJunior:AB$Token | Cost$ 0 | TokenImage$ g 1 1 ooze | TokenName$ Ooze | TokenTypes$ Creature,Ooze | TokenColors$ Green | TokenOwner$ You | TokenPower$ 1 | TokenToughness$ 1 | TokenAmount$ 2 + +## Trigger + +If possible split the SpellDescription$ of the the effect so the part for the trigger can become the StackDescription directly. + +### DelayedTrigger + +### ImmediateTrigger + +## Turn structure + +### AddPhase + +### AddTurn + +`A:SP$ AddTurn | Cost$ 1 U | NumTurns$ 1 | SpellDescription$ Take an extra turn after this one.` + +### EndTurn + +### ReverseTurnOrder + +### SkipPhase + +### SkipTurn + +## ZoneAffecting + +For specific effects that handle zones in a specific manner + ### ChangeZone ChangeZone is a united front of any card that changes zone. This does @@ -281,638 +821,50 @@ card is changing zones?" happens on activation, generally by targeting. For Known, since it just uses Target, normal target parameters are used in this Scenario. -#### ChangeZoneResolve +### ChangeZoneResolve This is a helper AF, for chained effects that create multiple permanents which should enter the battlefield at the same time. To use it, you need to set the param "ChangeZoneTable" on the first effect and then call this at the end. This is supported by the following effects: - - Amass - - CopyPermanent - - RepeatEach (_NOTE: if you wrap the creation, you don't need to call this AF on its own_) - - Token +- Amass +- CopyPermanent +- RepeatEach (_NOTE: if you wrap the creation, you don't need to call this AF on its own_) +- Token -### Charm - -This allows cards that have a mode to be chosen to occur after a trigger. - -Parameters - - - CharmNum - Number of Modes to Choose - - Choices - A Comma delimited list of SVars containing the Modes - -### Choose - -#### ChooseType - -This can be used when you are asked to choose a card type or creature type. - - - Type - Required - Can be Card or Creature - - InvalidTypes - Optional - Use to specify any type that cannot be chosen (ex: "Choose any creature type except Wall") - -The Defined is for target players. - -*NOTE_: Make sure that when this is used with a SubAbility that the DB$AF\_Whatever will support Card.ChosenType. This will need testing on a case by case basis.* - -### Clash - -This AF handles clashing. It takes two special parameters: WinSubAbility and -OtherwiseSubAbility. They are both optional and work the same way, -namely that it contains the name of an SVar that in turn contains a -drawback to be executed. The example below is for Release the Ants. - -`A:SP$ DealDamage | Cost$ 1 R | Tgt$ TgtCP | NumDmg$ 1 | SubAbility$ DBClash | SpellDescription$ Release the Ants deals 1 damage to target creature or player. Clash with an opponent. If you win, return CARDNAME to its owner's hand.` -`SVar:DBClash:DB$ Clash | WinSubAbility$ DBReturn` -`SVar:DBReturn:DB$ ChangeZone | Defined$ Self | Origin$ Stack | Destination$ Hand` - -### Cleanup - -A non-functional, maintenance AF used for Cleaning up certain Variables before a Spell finishes Resolving. - -Parameters - - - ClearRemembered$ (optional) Set to True to clear this card's - remembered list. Generally useful for Cards that Remember a card, do - something to it, then need to forget it once it's done. - - ClearImprinted$ (optional) Set to True to clear the list of - imprinted cards. - - ClearChosenX$ (optional) Set to True to clear the chosen X value. - - ClearTriggered$ (optional) Set to True to clear any delayed triggers - produced by this card. - - ClearCoinFlips$ (optional) Set to True to clear the remembered coin - flip result. - - ClearChosenCard$ (optional) Set to True to clear the chosen cards. - - ForgetDefined$ (optional) If present, remove the specified cards - from this card's remembered list. - -### Copy - -#### CopyPermanent - -Copies a permanent on the battlefield. - -Parameters: - - - NumCopies - optional - the number of copies to put onto the - battlefield. Supports SVar:X:????. - - Keywords - optional - a list of keywords to add to the copies - - AtEOT - optional - - Sacrifice - set to this is copy should be sacrificed at End of - Turn - - Exile - set to this is copy should be exiled at End of Turn - -#### CopySpellAbility - -Copies a spell on the stack (Twincast, etc.). - -### Counter - -Countering Spells or Abilities. - -`A:SP$ Counter | Cost$ 1 U | TargetType$ Spell | TgtPrompt$ Select target spell | ValidTgts$ Card | UnlessCost$ 3 | SpellDescription$ Counter target spell unless its controller pays 3.` -`A:SP$ Counter | Cost$ U | TgtPrompt$ Select target Activated or Triggered Ability | ValidTgts$ Card | TargetType$ Activated,Triggered | SpellDescription$ Counter target activated or triggered ability.` -`A:SP$ Counter | Cost$ G | TargetType$ Spell | ValidTgts$ Instant,Aura | TargetValidTargeting$ Permanent.YouCtrl | SpellDescription$ Counter target instant or Aura spell that targets a permanent you control. ` - -Parameters - - - TargetType - Can be Spell,Activated,Triggered. If more than one, - just put a comma in between. - - ValidTgts - a "valid" expression for types of source card (if you - don't know what it is it's just "Card") - - TargetValidTargeting- a "valid" expression for targets of this - spell's target - - Destination - send countered spell to: (only applies to Spells; ignored for Abilities) - - Graveyard (Default) - - Exile - - TopDeck - - Hand - - BottomDeck - - Shuffle - -### Counters - -Factories to handle counters on cards. - -#### PutCounter - -Put any type of counter on a game object. - -`A:AB$ PutCounter | Cost$ T | CounterType$ CHARGE | CounterNum$1 | SpellDescription$ Put a charge counter on CARDNAME.` -`A:SP$ PutCounter | Cost$ G | Tgt$ TgtC | CounterType$ P1P1 | CounterNum$ 1 | SpellDescription$ Put a charge counter on CARDNAME.` - -Target is optional. If no Target is provided, the permanent will put counters on itself. - - - CounterType (required) specifies the type of counter and should - appear in all caps. It should be one of the values in the Counters - enum. - - CounterNum (required) specifies how many counters will be put on - the chosen card. - -#### PutCounterAll - -Put any type of counter on all valid cards. - - - CounterType (required) specifies the type of counter and should - appear in all caps. It should be one of the values in the Counters - enum. - - CounterNum (required) specifies how many counters will be put on - the chosen cards. - - ValidCards (required) specifies the cards to add counters to. - -#### RemoveCounter - -Remove any type of counter from a card. - -Target is optional. If no Target is provided, the permanent will remove -counters from itself. - - - CounterType (required) specifies the type of counter and should - appear in all caps. It should be one of the values in the Counters - enum. - - CounterNum (required) specifies how many counters will be removed - from the chosen card. - - UpTo is optional. If an effect states you may remove "up to X - counters", set this to True. - -#### RemoveCounterAll - -Remove any type of counter from all valid cards. - - - CounterType$ (required) specifies the type of counter and should - appear in all caps. It should be one of the values in the Counters - enum. - - CounterNum$ (required) specifies how many counters will be removed - from the chosen cards. - - ValidCards$ (required) specifies the card to remove counters from. - -#### Proliferate - -No own parameters. - -#### MoveCounters - -Used for cards that Move Counters on Resolution, requiring the Host card -to have Counters for the Move to occur. - -Parameters - - - Source - The Source of the Moving Counters - - Defined - The Destination of the Moving Counters - - CounterType - The type of counter to move. - - CounterNum - The number of counters to move. - -### Damage - -#### DealDamage - -Deal damage to a specified player or permanent. - -`A:AB$ DealDamage | Cost$ T | Tgt$ TgtCP | NumDmg$ 1 | SpellDescription$ CARDNAME deals 1 damage to target creature or player.` - -NumDmg is required. This is the amount of damage dealt. - -#### DamageAll - -This is for damaging all applicable cards/players. Spells like -Earthquake fit in this category. - -`A:SP$ DamageAll | Cost$ 1 B | NumDmg$ 1 | ValidCards$ Creature | ValidPlayers$ Each | ValidDescription$ each creature and each player. | SpellDescription$ CARDNAME deals 1 damage to each creature and each player.` - -ValidCards are for specifying the cards that will take damage. -ValidPlayers are for specifying the players. - -### Debuff - -Parameters - - - Keywords - - Duration - -#### Debuff - -An AbilityFactory for Removing Keywords, either temporarily or for longer durations. - -#### DebuffAll - -Same as Debuff, but for all of something - -### DelayedTrigger - -### Destroy - -These APIs handles destruction of cards on the battlefield. - -See [Sacrifice](Forge_AbilityFactory "wikilink") for special case: -'Target opponent chooses \[x cards\]. Destroy those \[cards\]' - -#### Destroy - -`A:SP$Destroy | Cost$ 1 W W | ValidTgts$ Artifact,Enchantment | TgtPrompt$ Select target artifact or enchantment | SpellDescription$ Destroy target artifact or enchantment.` - -#### DestroyAll - -`A:SP$ DestroyAll | Cost$ 3 U | ValidCards$ Forest | SpellDescription$ Destroy all Forests.` - -### Effect - -Effect is an oddball of the AF family. Where usually AFs have similarities to each other to help with AI use, Effect doesn't fall under that jurisdiction. In general, an effect is some type of SA that -lasts longer than its resolution. - -A good example is High Tide. For the rest of the turn, High Tide makes -all Islands produce an extra mana. It doesn't matter if the Island was -in play, if it turned into an Island after High Tide was cast, any of that. - -`A:SP$ Effect | Cost$ U | Name$ High Tide Effect | Triggers$ IslandTrigger | SVars$ TrigMana | SpellDescription$ Until end of turn, whenever a player taps an Island for mana, that player adds U to his or her mana pool (in addition to the mana the land produces).` -`SVar:IslandTrigger:Mode$ TapsForMana | ValidCard$ Island | Execute$ TrigMana | TriggerDescription$ Whenever a player taps an Island for mana, that player adds U to his or her mana pool (in addition to the mana the land produces).` -`SVar:TrigMana:AB$Mana | Cost$ 0 | Produced$ U | Amount$ 1` - -Effect is most similar to Token as it creates a pseudo-permanent, except -Effect creates in the command zone rather than the battlefield. It stays -active there for a set Duration. - -Parameters - - - Abilities,Triggers,SVars are comma separated lists which contain - SVars that point to the appropriate type that the Effect will gain. - - Duration is how long the Effect lasts. Right now, most effects will - last Until End of Turn. In the future, they may have other - conditions. - -Duration$ Permanent for effects that have no specific Duration. - - - Stackable$ False - Most Effects are assumed to be Stackable. By - setting the Stackable Flag to False, the AI will know having a - second one in play is useless, so will save it's Resource for - something else. - - Image - a file\_name\_without\_extension (image needs to reside in - the tokens directory) - -### Game outcome - -#### GameDraw - -#### GameLoss - -#### GameWin - -#### RestartGame - -Used in the script of Karn Liberated - -### Explore - -### Fight - -### Fog - -Fog is an ability based on the original Fog spell. "Prevent all combat -damage that would be dealt this turn." While this could be done with an -effect, the specialized nature of the AI gives it it's own AF. - -### GainControl - -Example: Act of Aggression - -`A:SP$ GainControl | Cost$ 3 PR PR | ValidTgts$ Creature.OppCtrl | TgtPrompt$ Select target creature an opponent controls. | LoseControl$ EOT | Untap$ True | AddKWs$ Haste | SpellDescription$ Gain control of target creature an opponent controls until end of turn. Untap that creature. It gains haste until end of turn.` - -Parameters: - - - NewController(Targeted player, if there is no target player, the - default is the ActivatingPlayer) - - AllValid(all valid types, no targets) - - LoseControl(LeavesPlay, Untap, LoseControl, EOT(end of turn)) - -### Goad - -### Investigate - -### Mana - -For lands or other permanent to produce mana. - -`A:AB$ Mana | Cost$ T | Produced$ | SpellDescription$ Add W to your mana pool.` - -In this example ManaType would be W. - -### Manifest - -### PermanentState - -API for things that alter a permanent's state: tap, untap, or phase in/out. - -#### Untap - -`A:AB$ Untap | Cost$ G | ActivationLimit$ 1| SpellDescription$ Untap CARDNAME. Activate this ability only once each turn.` -`A:SP$ Untap | Cost$ W | ValidTgts$ Permanent | TgtPrompt$ Select target permanent | SpellDescription$ Untap target permanent.` - -Target is optional. If not provided, will untap the permanent with this ability. - -#### UntapAll - -`A:SP$ UntapAll | Cost$ G | ValidCards$ Creature.YouCtrl | SpellDescription$ Untap all creatures you control.` - -#### Tap - -`A:AB$ Tap | Cost$ R | ValidTgts$ Wall | TgtPrompt$ Select target wall | SpellDescription$ Tap target wall.` - -#### TapAll - -`A:AB$ TapAll | Cost$ U U U | ValidCards$ Creature.withoutFlying | SpellDescription$ Tap all creatures without flying.` - -#### TapOrUntap - -#### Phases - -### Play - -Playing a card or cards as part of SA. The player may have to make a -choice about which card to play if there are more choices than the -number of cards to play. - -Sunbird's Invocation uses many of the parameters. - -Amount - How many cards can be played (a non-negative integer or "All"). - -Valid - Selection criteria for valid cards from the zone to cast. - -ValidSA - Applied after Valid, this will filter based on all spells of the cards. - -ValidZone - The zone to look in to determine the valid cards. - -ShowCards - Other cards in the zone to show when selecting valid cards. - -Optional - Casting the card is optional. - -RememberPlayed - Remember the card played. - -ForgetRemembered - Remove all remembered cards from the source (but only -if a card was successfully played) - -ForgetTargetRemembered - Remove the played card from remembered cards -(but only if it was successfully played) - -WithoutManaCost - The card can be cast without mana payment. - -### PreventDamage - -AF damage prevention effects. - -#### PreventDamage - - - A:SP$ PreventDamage | Cost$ W | ValidTgts$ Creature | Amount$ 3 - | TgtPrompt$ Select target creature | SpellDescription$ Prevent - the next 3 damage that would be dealt to target creature this - turn. - -#### PreventDamageAll - -Same as PreventDamage, but for all ValidCards and/or ValidPlayers - -### Protection - -#### Protection - -Protection grants protection from colors or cards types, or creature -types. Anything that has "Protection from ..." - -Gains - required - the thing to gain protection from (green, artifacts, -Demons, etc.) or "Choice" if you can choose one of... - -Choices - optional -- if Gains$ Choice then this is a comma-delimited list of choices - -#### ProtectionAll - -Same as Protection, but for all ValidCards and/or ValidPlayers - -### Pump - -#### Pump - -This factory handles pumping creatures power/toughness or granting -abilities to permanents (usually creatures). - - - A:AB$ Pump | Cost$ R | NumAtt$ +1 | SpellDescription$ CARDNAME - gets +1/+0 until end of turn. - - A:SP$ Pump | Cost$ 1 U | ValidTgts$ Creature | KW$ Shroud| - SpellDescription$ Target creature gains shroud until end of - turn. | TgtPrompt$ Select target creature. - -Target is optional. If it's not provided, the activating permanent will be pumped. - -NumAtt$ is optional, will pump Power. - -NumDef$ is optional, will pump Toughness. - -KW$ is optional, will give temporary keywords. - -#### PumpAll - -### Regenerate - -#### Regenerate - -Regenerate is similar to abilities like Pump. But for creating -Regeneration shields. - - - A:AB$ Regenerate | Cost$ B | SpellDescription$ Regenerate - CARDNAME - - A:SP$ Regenerate | Cost$ W | ValidTgts$ Creature | TgtPrompt$ - Select target creature | SpellDescription$ Regenerate target - creature. - -Target is optional. If not provided, will regenerate the permanent with -this ability. - -#### RegenerateAll - -Same as regenerate, but for all. - -ValidCards - required - a valid expression for cards to regenerate - -### Repeat - -Repeat the specified ability. - -#### Repeat - -`A:SP$ Repeat | Cost$ 3 B B | RepeatSubAbility$ DBDig | RepeatOptional$ True` - - - MaxRepeat - optional - the maxium times to repeat, execute repeat - ability at least once - - RepeatSubAbility - required - setup subability to repeat - - RepeatOptional - optional - you make the choice whether to repeat - the process - - RepeatPresent, RepeatCompare, RepeatDefined, RepeatCheckSVar, - RepeatSVarCompare - optional - condition check - -#### RepeatEach - - - RepeatSubAbility - required - to set up repeat subability - - RepeatCards - to repeat for each valid card (zone: present zone of - the valid repeat cards, default: battlefield) - - DefinedCards - - RepeatPlayers - to repeat for each valid player - - RepeatCounters - to repeat for each valid counters - -### Reveal - -#### Dig +### Dig Dig is for an ability that does basically this: "You look at the X cards of your Library, put Y of them somewhere, then put the rest somewhere." Think of Impulse. - - DigNum - Required - look at the top number of cards of your library. - - Reveal - Optional - for abilities that say "Reveal the top X cards - of your library". Default is false. - - SourceZone - Optional - the zone to dig in. Default is Library. - - DestinationZone - Optional - the zone to put the Y cards in. Default - is Hand. - - LibraryPosition - Optional - if DestinationZone is Library, use this - to specify position. Default is -1 (bottom of library). - - ChangeNum - Optional - the number of cards to move to the - DestinationZone (or "All" when it's for things like "put all lands - revealed this way into your hand"). Default is 1. - - ChangeValid - Optional - use this to specify if "you may move an - artifact to DestinationZone". Default is any Card. - - AnyNumber - Optional - use if you can move any number of Cards to - DestinationZone. Default is false. (think of Lead the Stampede) - - Optional - Optional - set this if you "may" move a card to - DestinationZone. Default is false. - - DestinationZone2 - Optional - the zone to put the rest of the cards - in. If it is library, you are prompted for the order. Default is - Library. - - LibraryPosition2 - Optional - if DestinationZone2 is Library, use - this to specify position. Default is -1 (bottom of library). +- DigNum - Required - look at the top number of cards of your library. +- Reveal - Optional - for abilities that say "Reveal the top X cards + of your library". Default is false. +- SourceZone - Optional - the zone to dig in. Default is Library. +- DestinationZone - Optional - the zone to put the Y cards in. Default + is Hand. +- LibraryPosition - Optional - if DestinationZone is Library, use this + to specify position. Default is -1 (bottom of library). +- ChangeNum - Optional - the number of cards to move to the + DestinationZone (or "All" when it's for things like "put all lands + revealed this way into your hand"). Default is 1. +- ChangeValid - Optional - use this to specify if "you may move an + artifact to DestinationZone". Default is any Card. +- AnyNumber - Optional - use if you can move any number of Cards to + DestinationZone. Default is false. (think of Lead the Stampede) +- Optional - Optional - set this if you "may" move a card to + DestinationZone. Default is false. +- DestinationZone2 - Optional - the zone to put the rest of the cards + in. If it is library, you are prompted for the order. Default is + Library. +- LibraryPosition2 - Optional - if DestinationZone2 is Library, use + this to specify position. Default is -1 (bottom of library). -#### DigUntil +### DigUntil -#### RevealHand - -Look at a player's hand. - -Target or Defined is required. - -`A:AB$ RevealHand | Cost$ T | ValidTgts$ Player | TgtPrompt$ Select target player | SpellDescription$ Look at target player's hand.` - -#### Scry - -`A:AB$ Scry | Cost$ 1 T | ScryNum$ 2` - -#### RearrangeTopOfLibrary - -#### Reveal - -`A:AB$ Reveal | Cost$ 2 U T | Defined$ You | RevealValid$ Card.Blue | AnyNumber$ True | RememberRevealed$ True` - -Parameters: - - - RevealValid: to limit the valid cards. - - AnyNumber - - Random - - RememberRevealed: to remember the cards revealed - -#### PeekAndReveal - -This AF is very similar to things that Dig can do, but handle a much -simpler form, with less complex coding underneath. Similar to how -RearrangeTopOfLibrary could be handled with Dig. - -Primarily used with cards that allow you to Peek at the top card of your -library, and allow you to reveal it if it's of a certain type. The -Kinship cards fit this bill perfectly, so they are used to simplify the -complex popups that would be required if using multiple Dig -SubAbilities. - -RevealOptional - Whether or not the Reveal is optional. - -RememberRevealed - Whether to remember the revealed cards (after -filtering by Valid) - -RememberPeeked - Whether to remember the peeked cards (only if they are -not revealed\!) - -RevealValid - defaults to Card, but allows you to set a specific -ValidType if you can only have certain things - -PeekAmount - defaults to 1, but allows you to peek at multiple cards if -possible - -### RollDice - -### Sacrifice - -#### Sacrifice - -Usually you choose a player and that player has to sacrifice something - -`A:SP$ Sacrifice | Cost$ 1 B | ValidTgts$ Player | SacValid$ Creature | SacMessage$ Creature | Amount$ 2 | SpellDescription$ Target player sacrifices a creature.` - -Destroy$ True - An optional parameter for destroying permanents target -player chooses (eg: Burning of Xinye, or Imperial Edict). - -`A:SP$ Sacrifice | Cost$ 1 B | ValidTgts$ Opponent | SacValid$ Creature | SacMessage$ Creature | Destroy$ True | SpellDescription$ Target opponent chooses a creature he or she controls. Destroy it.` - -#### SacrificeAll - -### StoreSVar - -### Token - -Token simply lets you create tokens of any type. - -`A:SP$ Token | Cost$ 3 W U | TokenImage$ W 1 1 Bird Flying | TokenAmount$ X | TokenName$ Bird | TokenTypes$ Creature,Bird | TokenOwner$ You | TokenColors$ Blue | TokenPower$ 1 | TokenToughness$ 1 | TokenKeywords$ Flying` - -This ability factory does not take a target. All the parameters are -mandatory except for TokenKeywords. If you provide a non-integer for -TokenAmount, TokenPower or TokenToughness the AF will attempt to look for -an SVar of that name and interpret it's contents as a Count$ line. Worth -noting is that TokenTypes and TokenColors are simple commaseparated -lists while TokenKeywords is a list where the items are separated by -"\<\>". If TokenImage is not provided, the factory will attempt to -construct a filename on it's own. TokenOwner can use Defined-like -parameters, such as "You" "Opponent" or the new Triggered-Variables. - -You can also use the parameters TokenAbilities$, TokenTriggers$ and -TokenSVars$ to give the created tokens any number of either. For -example, here's how Growth Spasm creates an Eldrazi Spawn token complete -with ability. - - SVar:DBToken:DB$Token | TokenAmount$ 1 | TokenName$ Eldrazi Spawn | TokenTypes$ Creature,Eldrazi,Spawn | TokenOwner$ You | TokenColors$ Colorless | TokenPower$ 0 | TokenToughness$ 1 | TokenAbilities$ ABMana SVar:ABMana:AB$Mana | Cost$ Sac<1/CARDNAME> | Produced$ 1 | Amount$ 1 | SpellDescription$ Add 1 to your mana pool. - -As another example, here's Mitotic Slimes' use of TokenTriggers$: - - T:Mode$ ChangesZone | Origin$ Battlefield | Destination$ Graveyard | ValidCard$ Card.Self | Execute$ TrigTokenSenior | TriggerDescription$ When CARDNAME is put into a graveyard from the battlefield, put two 2/2 green Ooze creature tokens onto the battlefield. They have "When this creature is put into a graveyard, put two 1/1 green Ooze creature tokens onto the battlefield." - SVar:TrigTokenSenior:AB$ Token | Cost$ 0 | TokenImage$ g 2 2 ooze | TokenName$ Ooze | TokenTypes$ Creature,Ooze | TokenColors$ Green | TokenOwner$ You | TokenPower$ 2 | TokenToughness$ 2 | TokenAmount$ 2 | TokenTriggers$ TriggerJunior | TokenSVars$ TrigTokenJunior - SVar:TriggerJunior:Mode$ ChangesZone | Origin$ Battlefield | Destination$ Graveyard | ValidCard$ Card.Self | Execute$ TrigTokenJunior | TriggerDescription$ When this creature is put into a graveyard, put two 1/1 green Ooze creature tokens onto the battlefield. SVar:TrigTokenJunior:AB$Token | Cost$ 0 | TokenImage$ g 1 1 ooze | TokenName$ Ooze | TokenTypes$ Creature,Ooze | TokenColors$ Green | TokenOwner$ You | TokenPower$ 1 | TokenToughness$ 1 | TokenAmount$ 2 - -### Turn structure - -#### AddPhase - -#### AddTurn - -`A:SP$ AddTurn | Cost$ 1 U | NumTurns$ 1 | SpellDescription$ Take an extra turn after this one.` - -#### EndTurn - -#### ReverseTurnOrder - -#### SkipPhase - -#### SkipTurn - -### ZoneAffecting - -For specific effects that handle zones in a specific manner - -#### Draw - -`A:AB$ Draw | Cost$ 1 Sac<1/CARDNAME> | NumCards$ 1 | SpellDescription$ Draw a card.` - -#### Discard +### Discard `A:AB$ Discard | Cost$ T | ValidTgts$ Opponent | NumCards$ 1 | Mode$ TgtChoose | SpellDescription$ Target opponent discards a card. ` @@ -926,17 +878,23 @@ For specific effects that handle zones in a specific manner - UnlessType - a ValidCards expression for "discard X unless you discard " -#### Mill +### Draw + +`A:AB$ Draw | Cost$ 1 Sac<1/CARDNAME> | NumCards$ 1 | SpellDescription$ Draw a card.` + +### Mill `A:AB$ Mill | Cost$ 2 T | NumCards$ 2 | ValidTgts$ Player | TgtPrompt$ Choose a player to mill | SpellDescription$ Target player puts the top two cards of his or her library into his or her graveyard.` -#### Shuffle +### RearrangeTopOfLibrary + +### Shuffle Used for shuffling a player's library - Optional - Set this parameter if the user should be prompted Yes/No to shuffle the given library. Default is false. -#### TwoPiles +### TwoPiles -### Vote +## Vote diff --git a/docs/Card-scripting-API/Card-scripting-API.md b/docs/Card-scripting-API/Card-scripting-API.md index cfb8d3ea915..cd1c7a962a0 100644 --- a/docs/Card-scripting-API/Card-scripting-API.md +++ b/docs/Card-scripting-API/Card-scripting-API.md @@ -1,30 +1,27 @@ -A reference guide for Scripting Cards using the API parsed by the Forge -Engine. +A reference guide for scripting cards using the API parsed by the Forge engine. -### Base Structure +# 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: +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 +Oracle: ``` -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). +The name of this card is Vanilla Creature.
+It's casting cost is {2}{G}.
+It has the types Creature and Beast.
+It has a Power-Toughness of 2/2.
+It will not display any additional text in the card's template.
If a card has two faces, use AlternateMode:{CardStateName} in the front face and separate both by a new line with the text "ALTERNATE". -There are a few other Parameters that will appear in most, if not all, cards. These are +There are a few other properties that will appear in many cards. These are | Property | Description | - | - @@ -33,8 +30,8 @@ There are a few other Parameters that will appear in most, if not all, cards. Th |`Colors`|Color(s) of the card

When a card's color is determined by a color indicator rather than shards in a mana cost, this property must be defined. If no identifier is needed, this property should be omitted.

* `Colors:red` - This is used on Kobolds of Kher Keep, which has a casting cost of {0} and requires a red indicator to make it red.

* `Colors:red,green` - Since Arlinn, Embraced by the Moon has no casting cost (it's the back of a double-faced card), the red and green indicator must be included. |`DeckHints`|AI-related hints for a deck including this card

To improve synergy this will increase the rank of of all other cards that share some of its DeckHints types. This helps with smoothing the selection so cards without these Entries won't be at an unfair disadvantage.

The relevant code can be found in the [CardRanker](https://git.cardforge.org/core-developers/forge/-/blob/master/forge-gui/src/main/java/forge/gamemodes/limited/CardRanker.java) class. |`DeckNeeds`|This can be considered a stronger variant when the AI should not put this card into its deck unless it has whatever other type is specified. The way this works is "inverted": it will directly decrease the rank of the card unless other cards are able to satisfy its types.
If a card demands more than one kind of type you can reuse it:
`DeckNeeds:Type$Human & Type$Warrior` will only find Human Warrior compared to `DeckNeeds:Type$Human\|Warrior` which is either -|`DeckHas`|specifies that the deck now has a certain ability (like, token generation or counters) so that the drafting/deckbuilding AI knows that it now meets requirements for DeckHints/DeckNeeds. This is actually very useful since many of these (such as Ability$Graveyard, Ability$Token, Ability$Counters) are not deduced by parsing the abilities, so an explicit hint is necessary. Using the other types is also supported in case the implicit parsing wouldn't find it.
It doesn't require exact matching to have an effect but cards that care about multiple entries for a given type will be judged higher if a card seems to provide even "more" synergy for it.
Example:
Chishiro has two abilities so `DeckHas:Ability$Token & Ability$Counters` is used, therefore score for `DeckNeeds:Ability$Token\|Counters` is increased -|`K`|Keyword +|`DeckHas`|specifies that the deck now has a certain ability (like, token generation or counters) so that the drafting/deckbuilding AI knows that it now meets requirements for DeckHints/DeckNeeds. This is actually very useful since many of these (such as `Ability$Graveyard, Ability$Token, Ability$Counters`) are not deduced by parsing the abilities, so an explicit hint is necessary. Using the other types is also supported in case the implicit parsing wouldn't find it.
It doesn't require exact matching to have an effect but cards that care about multiple entries for a given type will be judged higher if a card seems to provide even "more" synergy for it.
Example:
Chishiro has two abilities so `DeckHas:Ability$Token & Ability$Counters` is used, therefore score for `DeckNeeds:Ability$Token\|Counters` is increased +|`K`|Keyword (see below) |`Loyalty`|Number of starting loyalty counters |`ManaCost`|Cost to cast the card shown in mana shards

This property is required. It has a single parameter that is a mana cost.

* `ManaCost:no cost` for cards that cannot be cast
* `ManaCost:1 W W` sets the casting cost to {1}{W}{W} |`Name`|Name of the card

A string of text that serves as the name of the card. Note that the registered trademark symbol cannot be included, and this property must have at least one character.

Example:
* `Name:A Display of My Dark Power` sets the card's name to "A Display of My Dark Power" @@ -49,95 +46,21 @@ There are a few other Parameters that will appear in most, if not all, cards. Th Rarity and Set info are now defined in edition definition files. These can be found at /res/reditions path. -## General SVars +## Conventions +- filename: all lowercase, skip special characters, underscore for spaces +- Unix(LF) line endings +- use empty lines only when separating multiple faces on a card +- try to avoid writing default params to keep scripts concise + - e.g. just `SP$ Draw` instead of `SP$ Draw | Defined$ You | NumCards$ 1` -`SVar:SoundEffect:goblinpolkaband.mp3` +# Keywords -The sound system supports a special SVar that defines the sound that should be played when the spell is cast. +All keywords need to be prepended with "K:" to be parsed correctly. Each keyword must appear on a separate line. -`SVar:AltCost:[cost]` +## Keywords without Parameters -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:AIPreference:SacCost$Creature.token,Creature.cmcLE2` - -`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:AIEvaluationModifier:[ValidAmount]` - -`SVar:EndOfTurnLeavePlay:True` - -`SVar:maxLevel:` - -`SVar:HasCombatEffect:True` - -`SVar:HasAttackEffect:True` - -`SVar:HasBlockEffect:True` - -`SVar:MustAttack:True` - -`SVar:MustBeBlocked:True` - -`SVar:NeedsToPlayVar:[ValidCards]` - -`SVar:ManaNeededToAvoidNegativeEffect:` - -`SVar:NonStackingEffect:True` - -`SVar:PlayMain1:TRUE/ALWAYS/OPPONENTCREATURES` - -The AI will play cards with this SVar in its first main phase. Without other AILogic, it will usually not play any permanents without this in Main1. - -`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:Targeting:Dies` - -`SVar:UntapMe:True` - -The AI will prioritize untapping of this card. - -`SVar:AIUntapPreference:` - -`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. - -### 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. +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.
+Examples: - Cascade - Changeling @@ -201,7 +124,7 @@ This section is for Keywords that require no additional parameters and are one o - Vigilance - Wither -### Keywords with parameters +## Keywords with parameters - Adapt:{cost} - AdjustLandPlays:{params} @@ -272,10 +195,11 @@ This section is for Keywords that require no additional parameters and are one o - UpkeepCost:{cost} - Vanishing:{TimeCounters} -### Longer Card Properties +## Plaintext keywords -Plaintext properties/triggers. This section is for Keywords that are two -words or longer. CARDNAME is replaced by the card's name. +These are hardcoded but not truly keywords rules-wise and will eventually be turned into static abilities. +Only listing the most common ones here so you can recognize them. +CARDNAME is replaced by the card's name ingame. - All creatures able to block CARDNAME do so. - CARDNAME assigns no combat damage @@ -352,10 +276,81 @@ words or longer. CARDNAME is replaced by the card's name. - You may have CARDNAME assign its combat damage as though it weren't blocked. - Your life total can't change. -## Developer Mode +# General SVars -[Forge\_DevMode](Forge_DevMode "wikilink") +`SVar:SoundEffect:goblinpolkaband.mp3` -## Remaining Cards +The sound system supports a special SVar that defines the sound that should be played when the spell is cast. - \ No newline at end of file +`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. + +# AI specific SVars + +`SVar:AIPreference:SacCost$Creature.token,Creature.cmcLE2` + +`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:AIEvaluationModifier:[ValidAmount]` + +`SVar:EndOfTurnLeavePlay:True` + +`SVar:maxLevel:` + +`SVar:HasCombatEffect:True` + +`SVar:HasAttackEffect:True` + +`SVar:HasBlockEffect:True` + +`SVar:MustAttack:True` + +`SVar:MustBeBlocked:True` + +`SVar:NeedsToPlayVar:[ValidCards]` + +`SVar:ManaNeededToAvoidNegativeEffect:` + +`SVar:NonStackingEffect:True` + +`SVar:PlayMain1:TRUE/ALWAYS/OPPONENTCREATURES` + +The AI will play cards with this SVar in its first main phase. Without other AILogic, it will usually not play any permanents without this in Main1. + +`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:Targeting:Dies` + +`SVar:UntapMe:True` + +The AI will prioritize untapping of this card. + +`SVar:AIUntapPreference:` + +`SVar:NoZeroToughnessAI:True` diff --git a/docs/Console-and-cheats.md b/docs/Console-and-cheats.md new file mode 100644 index 00000000000..43d75863bf0 --- /dev/null +++ b/docs/Console-and-cheats.md @@ -0,0 +1,43 @@ +Forge provides an in-game console in adventure mode. + +You can access (and close) the console while exploring by pressing F9 (or Fn-F9). + +To scroll the console window, click and drag the text box. + +## Available commands + +| Command Example | Description | +| -- | -- | +| resetMapQuests | Resets the map quests, resulting in all side-quest progress being lost and all side-quest types being re-picked | +| give gold 1000 | Give 1000 gold | +| give shards 1000 | Give 1000 shards | +| give print lea 232 | Add an alpha (LEA set code) black lotus (232 collector number) | +| give item | Adds an in game item such as leather boots | +| give set sld | Give 4 copies of every card in the Secret Lair Drop (set code SLD), flagged as having no sell value | +| give nosell card forest | Gives a forest with no sell value | +| give boosters leb | Add a booster from beta (LEB set code) | +| give quest 123 | Add the quest by its number ID | +| give life 10 | Add 10 life to yourself | +| give card forest | Adds a forest to your inventory | +| debug collision | Displays bounding boxes around entities | +| debug map | TODO | +| debug off | Turns off previously enable debugging | +| teleport to 6000 5000 | Moves you 6000 tiles east and 5000 tiles north from the left bottom corner | +| fullHeal | Returns your health back to baseline | +| sprint 100 | Increases your speed for 100 seconds | +| setColorId R | Sets the player color identity; Probably used for testing and shops | +| clearnosell | Clears the no sell value flag from all cards you own that are not used in a deck | +| remove enemy abc | Remove the enemy from the map with the map ID abc | +| remove enemy all | Remove all the enemies from the map | +| dumpEnemyDeckList | Print the enemy deck lists to terminal output stream | +| getShards amount 100 | Similar to give shards command; Gives 100 shards to the player | +| resetQuests | Resets the world quests. In progress quests are not abandonned or reset including dungeons. Does not reroll abandoned quests. Not really sure what this does. | +| hide 100 | Enemies do not chase you for 100 seconds | +| fly 100 | You can walk over obstacles for 100 seconds | +| crack | Cracks a random item you are wearing | +| spawn enemy Sliver | Spawns a Sliver on your screen | +| listPOI | Prints all locations in terminal output stream as ID-type pairings | +| leave | Gets you out of the current town/dungeon/cave | +| dumpEnemyColorIdentity | Prints all enemies, their colour affinity and deck name to terminal output | +| heal | Recover your full health | +| dumpEnemyDeckColors | Prints all decks available to enemies and their affinities | diff --git a/docs/Currency.md b/docs/Currency.md new file mode 100644 index 00000000000..f460e30f197 --- /dev/null +++ b/docs/Currency.md @@ -0,0 +1,46 @@ +There are many currencies in the game, and most of them can be interchanged. + +# Cards + +Acquired by: +- World drops +- Match reward +- Draft wins +- Shop purchases +- Quests + +Spent on: +- Selling to shops + +# Gold + +Acquired by: +- World drop +- Match reward +- Draft reward +- Quests + +Spent on: +- Cards and items from shops +- Drafts games +- Crafting cards +- Shards + +# Shards + +Acquired by +- World drop +- Quest reward + +Spent on +- Crafting cards +- Shop Re-rolls +- Gold exchange + +# Challenge Coins + +Acquired by +- At the start of the game + +Spent on +- Drafts \ No newline at end of file diff --git a/docs/Deck-Building-Tips.md b/docs/Deck-Building-Tips.md new file mode 100644 index 00000000000..7758414b7e9 --- /dev/null +++ b/docs/Deck-Building-Tips.md @@ -0,0 +1,28 @@ +# Adding basic lands and special arts + +You can add lands by clicking the triple dots icon in the right top of the deck building interface. + +Initially you only have access to jumpstart basic land arts - to get more, you need to purchase the landscape sketch books from the basic land shop (The Cartographers Guild). + +# 40-card deck recommendation + +40-card decks give you a much more predictable curve. + +In a 40-card deck, each individual card has a 2.5% chance of being drawn. + +In a 60-card deck, each individual card has a 1.6% chance of being drawn. + +When you use a smaller deck, the significance of each individual card is much higher and will give you more predictable performance. + +# Autosell + +When you click a card that is not part of any decks, you get the option to move it to auto-sell. + +The numbers in the interface indicate how many copies you have. + +To sell the cards you have marked, go to any town and enter the Inn. +In the Inn, the middle icon of the coin called Sell (E) will sell all your cards you have marked to sell. + +Individual card values vary by rarity and reputation with the town you sell them in. + +Since dying will cause you to lose a percentage of your gold, you may want to not sell all your cards immediately. diff --git a/docs/Home.md b/docs/Home.md index 47b1224bb98..b9b56a03071 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -1,5 +1,5 @@ > [!CAUTION] -> - if you want to contribute to this Wiki please only make pull requests against the main repos docs folder or your changes might get lost +> - if you want to contribute to this Wiki please only make pull requests against the main repositories *docs* folder or your changes might get lost > - due to GitHub limitations all filenames should be unique # What is Forge? diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 1cdeef09071..9820e519a6c 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -13,10 +13,13 @@ - [Getting Started](Gameplay-Guide.md) - [Different Planes](Different-Planes.md) + - [Currency](Currency.md) + - [Deck Building Tips](Deck-Building-Tips.md) - [Towns & Capitals](Towns-&-Capitals.md) - [Dungeons](Dungeons.md) - [Equipments and Items](Equipments-and-Items.md) - [Keyboard Shortcuts](Keyboard-Shortcuts.md) + - [Console and Cheats](Console-and-Cheats.md) - [Modding and Development](Modding-and-Development.md) @@ -36,9 +39,10 @@ - [Ability effects](Card-scripting-API/AbilityFactory.md) - [Triggers](Card-scripting-API/Triggers.md) - [Replacements](Card-scripting-API/Replacements.md) + - Statics - [Costs](Card-scripting-API/Costs.md) - [Affected / Targets](Card-scripting-API/Targeting.md) - - [Restrictions](Card-scripting-API/Restrictions.md) + - [Restrictions / Conditions](Card-scripting-API/Restrictions.md) - [Guide: Creating a Custom Card](Card-scripting-API/Creating-a-Custom-Card.md) - [Development]((SM-autoconverted)-how-to-get-started-developing-forge.md) diff --git a/forge-gui/res/cardsfolder/p/powerbalance.txt b/forge-gui/res/cardsfolder/p/powerbalance.txt index 9c5cc60e009..a7ef286ff66 100644 --- a/forge-gui/res/cardsfolder/p/powerbalance.txt +++ b/forge-gui/res/cardsfolder/p/powerbalance.txt @@ -2,7 +2,7 @@ Name:Powerbalance ManaCost:R R Types:Enchantment T:Mode$ SpellCast | ValidCard$ Card | ValidActivatingPlayer$ Opponent | OptionalDecider$ You | TriggerZones$ Battlefield | Execute$ TrigReveal | TriggerDescription$ Whenever an opponent casts a spell, you may reveal the top card of your library. If you do, you may cast that card without paying its mana cost if the two spells have the same mana value. -SVar:TrigReveal:DB$ PeekAndReveal | PeekAmount$ 1 | RevealOptional$ True | RememberRevealed$ True | SubAbility$ DBPlay +SVar:TrigReveal:DB$ PeekAndReveal | PeekAmount$ 1 | NoPeek$ True | RevealOptional$ True | RememberRevealed$ True | SubAbility$ DBPlay SVar:DBPlay:DB$ Play | Defined$ Remembered | ValidSA$ Spell.cmcEQX | WithoutManaCost$ True | Optional$ True | SubAbility$ DBCleanup SVar:DBCleanup:DB$ Cleanup | ClearRemembered$ True SVar:X:TriggeredSpellAbility$CardManaCostLKI