mirror of
https://github.com/Card-Forge/forge.git
synced 2025-11-11 16:26:22 +00:00
Cleanup scripting API first pass (#9070)
This commit is contained in:
tool4ever
GitHub
@@ -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.<br>
|
||||
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.<br>
|
||||
It's casting cost is {2}{G}.<br>
|
||||
It has the types Creature and Beast.<br>
|
||||
It has a Power-Toughness of 2/2.<br>
|
||||
It will not display any additional text in the card's template.<br>
|
||||
|
||||
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<br /><br />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.<br /><br />* `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.<br /><br />* `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<br /><br />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.<br /><br />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.<br />If a card demands more than one kind of type you can reuse it:<br />`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.<br />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.<br />Example:<br />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.<br />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.<br />Example:<br />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<br /><br />This property is required. It has a single parameter that is a mana cost.<br /><br />* `ManaCost:no cost` for cards that cannot be cast<br />* `ManaCost:1 W W` sets the casting cost to {1}{W}{W}
|
||||
|`Name`|Name of the card<br /><br />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.<br /><br />Example:<br />* `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.<br>
|
||||
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.
|
||||
|
||||
<https://docs.google.com/spreadsheet/ccc?key=0Aipjpk0ZcU8fdFlMczZRR2tmazZGSGZYeDh1Z24teVE&usp=sharing>
|
||||
`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`
|
||||
|
||||
Reference in New Issue
Block a user