mirror of
https://github.com/Card-Forge/forge.git
synced 2025-11-12 16:58:57 +00:00
Cleanup scripting API first pass (#9070)
This commit is contained in:
tool4ever
GitHub
File diff suppressed because it is too large
Load Diff
@@ -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`
|
||||
|
||||
43
docs/Console-and-cheats.md
Normal file
43
docs/Console-and-cheats.md
Normal file
@@ -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 <item name or code?> | 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 |
|
||||
46
docs/Currency.md
Normal file
46
docs/Currency.md
Normal file
@@ -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
|
||||
28
docs/Deck-Building-Tips.md
Normal file
28
docs/Deck-Building-Tips.md
Normal file
@@ -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.
|
||||
@@ -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?
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user