AI cleanup (#9210)

* Cherry pick priority improvement

* Align signatures

.github/workflows/sync-wiki.yml

@@ -18,7 +18,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: fix md links for Gollum
-        run: find ${{ github.workspace }}/docs/ -type f -name "*.md" -exec sed -i -E 's|(\[[^]]+]\()([^)]+\/)*([^).]+).md\)|\1\3)|g' '{}' \;
+        run: find ${{ github.workspace }}/docs/ -type f -name "*.md" -exec sed -i -E 's|(\[[^]]+]\()([^)]+\/)*([^).]+).md(#)*([[:alnum:]]*)\)|\1\3\4\5)|g' '{}' \;
       - name: fix image links for Gollum
         run: find ${{ github.workspace }}/docs/ -type f -name "*.png" -exec mv '{}' ${{ github.workspace }}/docs/ \;
       - uses: Andrew-Chen-Wang/github-wiki-action@v5

CONTRIBUTING.md

@@ -2,8 +2,6 @@
 
 [Official repo](https://github.com/Card-Forge/forge.git).
 
-Dev instructions here: [Getting Started](https://github.com/Card-Forge/forge/wiki) (Somewhat outdated)
-
 ## Requirements / Tools
 
 - your favourite Java IDE (IntelliJ, Eclipse, VSCodium, Emacs, Vi...)
@@ -18,11 +16,10 @@ Dev instructions here: [Getting Started](https://github.com/Card-Forge/forge/wik
 
 ## Project Quick Setup
 
-- Login into GitHub with your user account and fork the project.
+- Login into GitHub with your user account and fork the project
-
 - Clone your forked project to your local machine
-
+- Go to the project location on your machine. Run Maven to download all dependencies and build a snapshot.
-- Go to the project location on your machine. Run Maven to download all dependencies and build a snapshot. Example for Windows & Linux: `mvn -U -B clean -P windows-linux install`
+  - Example for Windows & Linux: `mvn -U -B clean -P windows-linux install`
 
 ## IntelliJ
 
@@ -30,107 +27,31 @@ IntelliJ is the recommended IDE for Forge development. Quick start guide for [se
 
 ## Eclipse
 
-Eclipse includes Maven integration so a separate install is not necessary. For other IDEs, your mileage may vary.
+Eclipse includes Maven integration so a separate install is not necessary.
-At this time, Eclipse is not the recommended IDE for Forge development.
+Google no longer supports Android SDK releases for Eclipse.
 
-### Project Setup
+## Windows
-
-- Follow the instructions for cloning from GitHub. You'll need to setup an account and your SSH key.
-
-  If you are on a Windows machine you can use Putty with TortoiseGit for SSH keys. Run puttygen.exe to generate the key -- save the private key and export
-  the OpenSSH public key. If you just leave the dialog open, you can copy and paste the key from it to your GitHub profile under
-  "SSH keys". Run pageant.exe and add the private key generated earlier. TortoiseGit will use this for accessing GitHub.
-
-- Fork the Forge git repo to your GitHub account.
-
-- Clone your forked repo to your local machine.
-
-- Make sure the Java SDK is installed -- not just the JRE. Java 17 or newer required. If you execute `java -version` at the shell or command prompt, it should report version 17 or later.
-
-- Install Eclipse 2021-12 or later for Java. Launch it.
-
-- Create a workspace. Go to the workbench. Right-click inside of Package Explorer > Import... > Maven > Existing Maven Projects > Navigate to root path of the local forge repo and
-  ensure everything is checked > Finish.
-
-- Let Eclipse run through building the project. You may be prompted for resolving any missing Maven plugins -- accept the ones offered. You may see errors appear in the "Problems" tab. These should
-  be automatically resolved as plug-ins are installed and Eclipse continues the build process. If this is the first time for some plug-in installs, Eclipse may prompt you to restart. Do so. Be patient
-  for this first time through.
-
-- Once everything builds, all errors should disappear. You can now advance to Project launch.
-
-### Project Launch
-
-#### Desktop
-
-This is the standard configuration used for releasing to Windows / Linux / MacOS.
-
-- Right-click on forge-gui-desktop > Run As... > Java Application > "Main - forge.view" > Ok
-
-- The familiar Forge splash screen, etc. should appear. Enjoy!
-
-#### Mobile (Desktop dev)
-
-This is the configuration used for doing mobile development using the Windows / Linux / MacOS front-end. Knowledge of libgdx is helpful here.
-
-- Right-click on forge-gui-mobile-dev > Run As... > Java Application > "Main - forge.app" > Ok.
-
-- A view similar to a mobile phone should appear. Enjoy!
-
-### Eclipse / Android SDK Integration
-
-Google no longer supports Android SDK releases for Eclipse. use IntelliJ.
-
-#### Android SDK
 
 TBD
 
-##### Windows
+## Linux / Mac OSX
 
 TBD
 
-##### Linux / Mac OSX
+### Android Platform
 
-TBD
+In IntelliJ, if the SDK Manager is not already running, go to Tools > Android > Android SDK Manager. Install the following options / versions:
-
-#### Android Plugin for Eclipse
-
-TBD
-
-#### Android Platform
-
-In Intellij, if the SDK Manager is not already running, go to Tools > Android > Android SDK Manager. Install the following options / versions:
 
 - Android SDK Build-tools 35.0.0
 - Android 15 (API 35) SDK Platform
 
-#### Proguard update
+> [!CAUTION]
+> Be careful about using unsupported api calls e.g. ``StringBuilder.isEmpty()``. Google's documentation for these is sometimes inaccurate.
+
+### Proguard update
 
 Standalone Proguard 7.6.0 is included with the project (proguard.jar) under forge-gui-android > tools and supports up to Java 23 (latest android uses Java 17).
 
-#### Android Build
-
-TBD
-
-#### Android Deploy
-
-TBD
-
-#### Android Debugging
-
-TBD
-
-### Windows / Linux SNAPSHOT build
-
-SNAPSHOT builds can be built via the Maven integration in Eclipse.
-
-1. Create a Maven build for the forge top-level project. Right-click on the forge project. Run as.. > Maven build...
-
-   - On the Main tab, set Goals: clean install, set Profiles: windows-linux
-
-2. Run forge Maven build. If everything built, you should see "BUILD SUCCESS" in the Console View.
-
-The resulting snapshot will be found at: forge-gui-desktop/target/forge-gui-desktop-[version]-SNAPSHOT
-
 ## Card Scripting
 
 Visit [this page](https://github.com/Card-Forge/forge/wiki/Card-scripting-API) for information on scripting.
@@ -139,6 +60,8 @@ Card scripting resources are found in the forge-gui/res/ path.
 
 ## General Notes
 
+Art files need to be copyright-free and they should be in the public domain.
+
 ### Project Hierarchy
 
 Forge is divided into 4 primary projects with additional projects that target specific platform releases. The primary projects are:
@@ -193,3 +116,5 @@ Mobile GUI game logic utilizing [libgdx](https://libgdx.badlogicgames.com/) libr
 #### forge-gui-mobile-dev
 
 Libgdx backend for desktop development for mobile backends. Utilizes LWJGL. Relies on forge-gui-mobile for GUI logic.
+
+#### forge-installer

README.md

@@ -32,7 +32,7 @@ Join the **Forge community** on [Discord](https://discord.gg/HcPJNyD66a)!
 4. **Java Requirement:** Ensure you have **Java 17 or later** installed.
 
 ### 📱 Android Installation
-- _(Note: **Android 11** is the minimum requirements with at least **6GB RAM** to run smoothly. You need to enable **"Install unknown apps"** for Forge to initialize and update itself)_
+- _(Note: **Android 11** is the minimum requirement with at least **6GB RAM** to run smoothly. You need to enable **"Install unknown apps"** for Forge to initialize and update itself)_
 - Download the **APK** from the [Snapshot Build](https://github.com/Card-Forge/forge/releases/tag/daily-snapshots). On the first launch, Forge will automatically download all necessary assets.
 
 ---
@@ -61,7 +61,7 @@ Test your skills against AI in multiple formats:
 - **Commander**
 - **Cube**
 
-For comprehensive gameplay instructions, visit our [Gameplay Guide](https://github.com/Card-Forge/forge/wiki/Gameplay-Guide).
+For comprehensive gameplay instructions, visit our [User Guide](https://github.com/Card-Forge/forge/wiki/User-Guide).
 
 <img width="1282" height="752" alt="Sealed" src="https://github.com/user-attachments/assets/ae603dbd-4421-4753-a333-87cb0a28d772" />
 

docs/AI.md

@@ -1,11 +1,14 @@
 # About Forge's Artificial Intelligence
 
-The AI is *not* "trained". It uses basic rules and can be easy to overcome knowing it's weaknesses.
+The AI is *not* "trained". It uses basic rules and can be easy to overcome knowing its weaknesses.
 
 The AI is:
-* Best with Aggro and midrange decks
+- Best with Aggro and midrange decks
-* Poor to Ok in control decks
+- Poor to Ok in control decks
-* Pretty bad for most combo decks
+- Pretty bad for most combo decks
+
+The logic is mostly based on heuristics and split between effect APIs and all other ingame decisions. Sometimes there is hardcoded logic for single cards but that's usually not a healthy approach though it can be more justifiable for highly iconic cards.  
+Defining general concepts of smart play can help improve the win rate much easier, e.g. the AI will always attack with creatures that it has temporarily gained control of until end of turn in order not to miss the opportunity and thus waste the control effect.
 
 If you want to train a model for the AI, please do. We would love to see something like that implemented in Forge.
 

docs/Advanced-Search.md

@@ -0,0 +1,192 @@
+# Advanced Search
+
+Forge implements many ways to help you find the cards you want in your ever growing collection.
+
+Pressing Ctrl+Enter in current search adds another editable search bar.  
+Here's how searching for all Goblins without Haste-related abilities might look:
+![search](search.png)
+
+Click the "X" in the upper right corner of each search widget to remove that filter from the filter stack.
+
+Find-as-you-type is implemented for Deck Editor tables. Just start typing while the table has focus and the next card with a matching string in its name will be highlighted. If more than one card matches, hit Enter to select the next matching card. A popup panel will appear with the search string so you know what you are searching for. If no cards match the string, the string will be highlighted in red. Find-as-you-type mode is automatically exited after 5 seconds of inactivity, or hit Escape to exit find-as-you-type mode immediately.
+
+## Additional information
+
+Another way to filter is using [Scryfall-like syntax](https://scryfall.com/docs/syntax) in the collection search bar.
+
+If no operators are passed between tokens, Forge will assume it is joined by `and`. For example, `t:cat t:warrior t:creature` will search for "creatures that are a cat **and** a warrior". Make sure to use `|` or `or` for your queries, as well as parentheses `( )` when needed.
+
+Keywords can be negated by prefixing a minus sign `-`. For example, `t:creature -t:goblin` will search for "creatures that aren't goblins".
+
+If no keywords are used, Forge will search in their name, type and oracle text for the passed values. For exemple, `(cat | warrior)` will search for cards that has `cat` or `warrior` anywhere in their name, type, or oracle text. Not that it is not bounrd, so it will also match on "catastrophe". This type of search can be negated too. For exemple, `lightning -bolt` will search for card with "lightning and not bolt in their name, types, or oracle text", or `(t:cat | t:warrior) -(orc | angel | phyrexian)` will search for "cat or warrior cards that don't have orc, angel, or phyrexian in their name, types, or oracle text.
+
+## Implemented keywords
+
+### Colors
+
+#### Keyword(s): `color`, `c`
+
+You can find cards that are a certain color using the `c:` or `color:` keyword. Both keywords accepts full color names like blue or the abbreviated color letters `w`, `u`, `r`, `b` and `g`.
+
+You can use many nicknames for color sets: all guild names (e.g. `azorius`), all shard names (e.g. `bant`), all college names (e.g., `quandrix`), all wedge names (e.g. `abzan`), and the four-color nicknames `chaos`, `aggression`, `altruism`, `growth`, `artifice` are supported.
+
+Use `c` or `colorless` to match colorless cards, and `m`, `multi`, or `multicolor` to match multicolor cards.
+
+You can use comparison expressions (`>`, `<`, `>=`, `<=`, and `!=`) to check against ranges of colors.
+
+*Exemples:*
+`c:rg` - Cards that are at least red and green
+`c!gruul` - Cards that exclusively red and green
+`color>=uw -c:red` - Cards that are at least white and blue, but not red
+
+### Card Types
+
+#### Keyword(s): `type:`, `t:`
+
+Find cards of a certain card type with the `t:` or `type:` keywords. You can search for any supertype, card type, or subtype.
+
+Using only partial words is allowed.
+
+*Exemples:*
+`t:merfolk t:legend` - Legendary merfolk cards
+`t:goblin -t:creature` - Goblin cards that aren't creatures
+
+### Card Text
+
+#### Keyword(s): `oracle:`, `o:`
+
+Use the `o:` or `oracle:` keywords to find cards that have specific phrases in their text box.
+
+You must put quotes `" "` around text with punctuation or spaces.
+
+*Exemples:*
+`o:"enters tapped"` - Cards that enter the battlefield tapped
+
+#### Keyword(s): `keyword:`, `kw:`
+
+You can use `keyword:` or `kw:` to search for cards with a specific keyword ability.
+
+> Note: Known to be buggy. You can search by oracle text instead.
+
+*Exemples:*
+`kw:flying -t:creature` - Noncreatures that have the flying keyword
+
+#### Keyword(s): `name:`
+
+You can find cards with certain words in their name using `name`.
+
+Supports `!` (exact search), `!=` (doesn't contain), and `:` or `=` (contains).
+
+*Exemples:*
+`name!Fire` - The card Fire
+`name:Phyrexian`- Cards that contain Phyrexian in their name
+
+#### Keyword(s): `is:vanilla`
+
+Find vanilla cratures (Creatures with no abilities).
+
+### Mana Costs
+
+#### Keyword(s): `manavalue`, `mv`, `cmc`
+
+You can find cards of a specific mana value with `manavalue`, `mv`, or `cmc`, comparing with a numeric expression (>, <, =, >=, <=, and !=).
+
+*Exemples:*
+`c:u mv=5` - Blue cards with mana value 5
+
+### Power, Toughness, and Loyalty
+
+#### Keyword(s): `power`, `pow`
+
+You can use numeric expressions (>, <, =, >=, <=, and !=) to find cards with certain power using `power` or `pow`.
+
+*Exemples:*
+`pow>=8` - Cards with 8 or more power
+`pow>tou c:w t:creature` - White creatures that are top-heavy
+
+#### Keyword(s): `toughness`, `tou`
+
+You can use numeric expressions (>, <, =, >=, <=, and !=) to find cards with certain toughness using `toughness` or `tou`.
+
+*Exemples:*
+`tou<=4` - Cards with 4 or less thoughness
+
+#### Keyword(s): `loyalty`, `loy`
+
+You can use numeric expressions (`>`, `<`, `=`, `>=`, `<=`, and `!=`) to find cards with certain starting loyalty using `loyalty` or `loy`.
+
+*Exemples:*
+`t:planeswalker loy=3` - Planeswalkers that start at 3 loyalty
+
+### Sets (Editions)
+
+#### Keyword(s): `set:`, `s:`, `edition:`, `e`
+
+Use `s:`, `e:`, `set:`, or `edition:` to find cards using their Magic set code.
+
+Examples:
+`e:war` - Cards from War of the Spark
+
+#### Keyword(s): `in:` (set)
+
+The `in:` keyword finds cards that appeared in given set code.
+
+Examples:
+`in:lea` - Find cards that once appeared in Alpha.
+
+### Rarity
+
+#### Keyword(s): `rarity:`, `r:`
+
+Use `r:` or `rarity:` to find cards by their print rarity. You can search for `land` (`l`) (usually only basic lands), `common` (`c`), `uncommon` (`u`), `rare` (`r`), `mythic` (`m`), and `special` (`s`). You can also use comparison operators like `<` and `>=.`
+
+Examples:
+`r:common t:artifact` - Common artifacts
+`r>=r`- Cards at rare rarity or above (rares and mythics)
+
+#### Keyword(s): `in:` (rarity)
+
+You can find cards that have been printed in a given rarity using `in:`
+
+Examples:
+`in:rare` - Cards that have been printed at rare.
+
+### Multi-faced cards
+
+#### Keyword(s): `is:split`
+
+Find split-faced cards.
+
+#### Keyword(s): `is:flip`
+
+Find flip cards.
+
+#### Keyword(s): `is:transform`
+
+Find cards that transform.
+
+#### Keyword(s): `is:meld`
+
+Find cards that meld.
+
+#### Keyword(s) `is:leveler`
+
+Find cards with Level Up.
+
+### Others
+
+#### Keyword(s): `is:modal`
+
+Find modal cards.
+
+#### Keyword(s): `is:custom`
+
+Find cards from custom sets.
+
+#### Keyword(s) `is:foil`
+
+Find foil cards.
+
+#### Keyword(s) `is:nonfoil`
+
+Find nonfoil cards.

docs/Adventure/Console-and-cheats.md

@@ -1,6 +1,8 @@
 Forge provides an in-game console in adventure mode.
 
 You can access (and close) the console while exploring by pressing F9 (or Fn-F9).
+The equivalent method to access the console on mobile is to hold down the character image in the right top of the screen.
+Holding the character image again will close the console (as will typing `exit`).
 
 To scroll the console window, click and drag the text box.
 

docs/Adventure/Create-Enemies.md

@@ -1,6 +1,6 @@
 All Enemies are stored under `res/<AdventureName>/world/enemies.json`
 
-Enemies spawned on the overworld map or on map stages will use this exact template to define their base behavior. These values can be modified or added to with additional settings on an individual enemy basis, details of which can be found within [map instance](Create-new-Maps).
+Enemies spawned on the overworld map or on map stages will use this exact template to define their base behavior. These values can be modified or added to with additional settings on an individual enemy basis, details of which can be found within [map instance](Create-new-Maps.md).
 
 Some ideas for custom enemy cards:
 - basic (CR or at least Alchemy conform) effects for normal mobs to add flavor
@@ -64,7 +64,7 @@ Supported directions are "Right","Left","Up","Down","RightDown","LeftDown","Left
 Array of strings containing paths to the decks used for this enemy (from `res/<AdventureName>`)  
 If no decks are defined then the enemy will act like a treasure chest and give the rewards without a fight.  
 (only for enemies in dungeons)  
-The format for the deck file can be the normal forge *.dck syntax or a json file that will behave like a collection of [rewards](Create-Rewards) to get a random generated deck.  
+The format for the deck file can be the normal forge *.dck syntax or a json file that will behave like a collection of [rewards](Create-Rewards.md) to get a random generated deck.  
 
 ## **randomizeDeck**
 Boolean - if true then the enemy deck will be randomly selected from the deck array. If false, an algorithm will select a deck in sequential order based on the player's prior win/loss ratio against that opponent (discouraged and currently unused due to wild swings in ratio at low game count).
@@ -85,17 +85,17 @@ Decimal - Relative frequency with which this enemy will be picked to spawn in ap
 Decimal - Relative estimated difficulty associated with this enemy. Currently unused, but will likely be factored in as a part of filtering enemies into early/late game appropriate opponents. Existing values range from 0 to 1.0.
 
 ## **speed**
-Integer - Movement speed of this enemy in overworld or on a [map instance](Create-new-Maps). For comparison, the player's base speed is set at a value of 32 (before any equipment / ability modifiers).
+Integer - Movement speed of this enemy in overworld or on a [map instance](Create-new-Maps.md). For comparison, the player's base speed is set at a value of 32 (before any equipment / ability modifiers).
 
 ## **scale**
 Decimal - Default 1.0. For enemies whose sprites are too large or small for their intended usage, this serves as multiplier for the enemy's visual dimensions & collision area. By default, we work with 16x16 pixel sprites for most entities - this can be replicated with a more detailed 32x32 sprite by setting a scale of 0.5 for the enemy entry.
 
 ## **life**
-Integer - Base starting life total. This is modified universally by a value determined by the player's chosen difficulty, and can be adjusted further at the enemy object level on [map instances](Create-new-Maps).
+Integer - Base starting life total. This is modified universally by a value determined by the player's chosen difficulty, and can be adjusted further at the enemy object level on [map instances](Create-new-Maps.md).
 
 ## **rewards**
 Array - A collection of the rewards to be granted for defeating the enemy.  
-see [Create Rewards](Create-Rewards) for the syntax.
+see [Create Rewards](Create-Rewards.md) for the syntax.
 
 ## **equipment**
 Array - A collection of strings representing [equipment items](adventure-items) normally intended for player use that this enemy will have. Not used widely, usually when an enemy will drop that [equipment](adventure-items) and it does not use [mana shards](mana-shards).

docs/Adventure/Create-Rewards.md

@@ -107,7 +107,7 @@ Valid options are:
 * `item` will give items to be added to the player's inventory.
 * `card` will create one or more cards matching a detailed set of filters to follow.
 * `union` is a wrapper for multiple `card` instances that can have mutually exclusive filters.
-* `deckCard` is only used with rewards from [enemies](Create-Enemies), this functions as a `card` reward that is limited to cards found in that enemy's deck.
+* `deckCard` is only used with rewards from [enemies](Create-Enemies.md), this functions as a `card` reward that is limited to cards found in that enemy's deck.
 
 `{"type": "card", ...}`
 

docs/Adventure/Equipments-and-Items.md

@@ -516,7 +516,7 @@ Opponent starting life +5
 1. **Cost**: 5000
 
 #### Blue Staff
-1. **Effect**: Let's you fly for 5 shards
+1. **Effect**: Lets you fly for 5 shards
 1. **Location** : Capital cities
 1. **Cost**: 5000
 

docs/Adventure/GAMEPAD.md

@@ -1,6 +1,6 @@
 Basic Gamepad Support for Adventure Mode
 
-Tested using DS4 Cpntroller on Windows and Android.
+Tested using DS4 Controller on Windows and Android.
 
 If using on Windows OS and you have DS4Windows installed, you might experience dual input because of Emulated/Virtual Controller. To fix this you must use HidHide (better than exclusive mode). Refer to the guide here:
 https://vigem.org/projects/HidHide/Simple-Setup-Guide/

docs/Card-Images.md

@@ -8,6 +8,10 @@ Primarily there are two types of images you'll care about; cards, and tokens.
 
 **Tokens** - are the images for the cards replacing a generic "1/1 zombie" for example. These are less frequently updated, and are typically the bulk of what is missing when doing an audit. However, these are probably where the more true "custom" replacements are available, with either custom artwork, or modified of other existing.
 
+A deck may explicitly define the edition and art variant of each card it includes. If a deck specifies those for no card, Forge uses a special algorithm to determine which card printings were the latest by the moment all of deck's had been printed. These very editions of cards are used when loading deck into memory to reflect the flavour of the season when the deck was built.
+
+Card images are cleared from memory cache when switching screens and between games.
+
 # Downloading
 
 Due to charges in Forges hosting and scryfall terms you can no longer predownload card images. Turn on auto download in forge to download card images when first viewed.
@@ -26,6 +30,8 @@ Due to charges in Forges hosting and scryfall terms you can no longer predownloa
 
 **(I'm not gatekeeping, please if you have a private location for bulk downloads or for alternate or custom arts, you can update this wiki too or let us know in the discord. I'll be happy to update the wiki page with additional sources.)**
 
+If you have an older Android device for increased performance or to save bandwidth it might be a good idea to use lower resolution images instead: https://www.slightlymagic.net/forum/viewtopic.php?f=15&t=29104
+
 # Storage
 
 Card images are stored in `pics/cards`, and tokens in `pics/tokens`, in the Cache folder for forge: 

docs/Card-scripting-API/AbilityFactory.md

@@ -1,14 +1,18 @@
 AbilityFactory parses differently from the Keyword parser. Your Ability line will look more like this:
 
-`A:{AB/SP/DB/ST}$ <AFSubclass> | {Necessary$ Parameters} | {Separated$ By} | {Pipes$ Here} | [Optional$ Values]`
+`A:<AB/SP/DB/ST>$ <AFSubclass> | <Necessary$ Parameters> | (<Separated$ By> | <Pipes$ Here>) | [Optional$ {Values} [Nested$ Dependency]]`
 
-In most cases, each AF subclass implements both the Spell and Ability.
+The ability types are:
-Much of the code is shared, so creating the data object will look very similar.
+- **AB** for Activated Abilities
+- **SP** for Spell
+- **DB** 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** for Static, this gets used in case the API should resolve without using the stack<br /> (e.g. the unique *Circling Vultures* special action is directly implemented in the script this way)
 
-  - **AB** is for Activated Abilities
+Syntax definitions like the above will use different symbols to separate the variable parts from the plaintext:
-  - **SP** is for Spell
+- angle brackets for mandatory parts
-  - **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
+- square brackets for optional parts
-  - **ST** is for Static, this gets used in case the API should resolve without using the stack<br> (e.g. the unique *Circling Vultures* special action is directly implemented in the script this way)
+- round brackets for grouping parts that are exclusive to each other
+- curly brackets to denote the type of a param
 
 >*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
@@ -20,7 +24,7 @@ Much of the code is shared, so creating the data object will look very similar.
 
 ## Cost / UnlessCost
 
-`Cost$ <AbilityCost>` 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$ {AbilityCost}` 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.)
 
@@ -52,9 +56,11 @@ The SpellDescription for secondary abilities (both AB and DB) is now displayed w
 
 ## Remember*
 
-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)<br>
+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)<br />
 Because cards keep their remembered parts when changing zones manual [cleanup](#Cleanup) is usually required.
 
+## Duration
+
 ## AI params
 
 `IsCurse$ True` - For effects that are normally treated positive e.g. Pump
@@ -207,6 +213,8 @@ Attach separates the actually granting of abilities from the attaching to perman
 
 ## BecomeMonarch
 
+No own parameters.
+
 ## Bond
 
 Soulbonding two creatures. Only used internally by the engine.
@@ -235,7 +243,7 @@ Parameters
 
 ## Choose*
 
-These can be used to chain effects together. However for common cases many effects already support this directly, e.g. `PutCounter | Choices$``.<br>
+These can be used to chain effects together. However for common cases many effects already support this directly, e.g. `PutCounter | Choices$``.<br />
 Besides making the script shorter using such shortcuts usually also helps the AI making better use of the effect.
 
 ### ChooseType
@@ -295,6 +303,8 @@ Parameters:
 
 ### ControlExchange
 
+### ControlPlayer
+
 ### ControlSpell
 
 ## Copy*
@@ -304,7 +314,6 @@ Parameters:
 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
@@ -315,7 +324,9 @@ Parameters:
 
 ### CopySpellAbility
 
-Copies a spell on the stack (Twincast, etc.).
+Parameters:
+- Num$ <Integer>
+- Restrict$ <String>
 
 ## Counter
 
@@ -411,8 +422,6 @@ Remove any type of counter from all valid cards.
 
 ### Proliferate
 
-No own parameters.
-
 ### MoveCounters
 
 Used for cards that Move Counters on Resolution, requiring the Host card
@@ -510,8 +519,6 @@ Used in the script of *Karn Liberated*
 
 ## Goad
 
-## Investigate
-
 ## Mana
 
 For lands or other permanent to produce mana.
@@ -717,7 +724,13 @@ player chooses (eg: Burning of Xinye, or Imperial Edict).
 
 ## StoreSVar
 
-## Token
+## Tokens
+
+### Amass
+
+### Investigate
+
+### Token
 
 Token simply lets you create tokens of any type.
 
@@ -748,12 +761,14 @@ As another example, here's Mitotic Slimes' use of TokenTriggers$:
 
 ## Trigger
 
-If possible split the SpellDescription$ of the the effect so the part for the trigger can become the StackDescription directly.
+If possible split the SpellDescription of the effect so the part for the trigger can become the StackDescription directly.
 
 ### DelayedTrigger
 
 ### ImmediateTrigger
 
+TriggerAmount
+
 ## Turn structure
 
 ### AddPhase

docs/Card-scripting-API/Card-scripting-API.md

@@ -2,7 +2,7 @@ A reference guide for scripting cards using the API parsed by the Forge engine.
 
 # Base Structure
 
-By opening any file in the /res/cardsfolder folder you can see the basic structure of how the data is created.<br>
+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:
 
 ```
@@ -13,11 +13,11 @@ PT:2/2
 Oracle:
 ```
 
-The name of this card is Vanilla Creature.<br>
+The name of this card is Vanilla Creature.  
-It's casting cost is {2}{G}.<br>
+It's casting cost is {2}{G}.  
-It has the types Creature and Beast.<br>
+It has the types Creature and Beast.  
-It has a Power-Toughness of 2/2.<br>
+It has a Power-Toughness of 2/2.  
-It will not display any additional text in the card's template.<br>
+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".
 
@@ -25,23 +25,23 @@ There are a few other properties that will appear in many cards. These are
 
 | Property | Description
 | - | -
-|`A`|[Ability effect](AbilityFactory)
+|`A`|[Ability effect](Card-scripting-API/AbilityFactory.md)
-|`AI`|RemoveDeck:<br />* `All`<br />This will prevent the card from appearing in random AI decks. It is applicable for cards the AI can't use at all like Dark Ritual and also for cards that the AI could use, but only ineffectively like Tortoise Formation. The AI won't draft these cards.<br />* `Random`<br /> This will prevent the card from appearing in random decks. It is only applicable for cards that are too narrow for random decks like Root Cage or Into the North. The AI won't draft these cards.<br />* `NonCommander`<br /> 
+|`AI`|RemoveDeck:<br />* `All`<br />This will prevent the card from appearing in random AI decks. It is applicable for cards the AI can't use at all and also for cards that the AI could use, but only ineffectively. The AI won't draft these cards.<br />* `Random`<br /> This will prevent the card from appearing in random decks. It is only applicable for cards that are too narrow for random decks like *Root Cage* or *Into the North*. The AI won't draft these cards.<br />* `NonCommander`<br />
-|`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.
+|`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 />Example:<br />`Colors:red,green` - Since *Arlinn, Embraced by the Moon* has no mana 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.
+|`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. The following types are supported:<br />* Color<br />* Keyword<br />* Name<br />* Type<br /><br />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://github.com/Card-Forge/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
+|`DeckHas`|Specifies that the deck now has a certain ability (like, token generation) so that the drafting/deckbuilding AI knows that it now meets requirements for DeckHints/DeckNeeds. This is useful since many of these are not deduced by parsing the abilities, so an explicit hint is necessary. If you want to create a new archetype make sure to tag at least roughly 50 cards to start with and balacing the Has/Needs ratio. Currently used values are:<br />* Counters<br />* Graveyard<br />* Token<br /><br />Using the generic types is also supported in case the implicit parsing wouldn't find it (TokenScript$ is also included).<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 /><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"
 |`Oracle`|The current Oracle text used by the card.<br /><br />We actually have a Python Script that runs to be able to fill in this information, so don't worry about manually editing a lot of cards when Wizards decides to change the rules. <br /><br />This field is used by the Deck Editor to allow non-Legendary Creatures to be marked as potential commanders. Make sure "CARDNAME can be your commander." appears in the oracle text.
 |`PT`|Power and toughness
-|`R`|[Replacement effect](Replacements)
+|`R`|[Replacement effect](Card-scripting-API/Replacements.md)
-|`S`|[Static ability](static-abilities)
+|`S`|[Static ability](Card-scripting-API/Statics.md)
 |`SVar`|String variable. Used throughout scripting in a handful of different ways.
-|`T`|[Triggered ability](Triggers)
+|`T`|[Triggered ability](Card-scripting-API/Triggers.md)
-|`Text`|Additional text that needs to be displayed on the CardDetailPanel that doesn't have any spell/ability that generates a description for it, for example "CARDNAME can be your commander." or "X can't be 0.".
+|`Text`|Additional text that needs to be displayed on the CardDetailPanel that doesn't have any spell/ability that generates a description for it, e.g. "CARDNAME can be your commander." or "X can't be 0.".
 |`Types`|Card types and subtypes<br /><br />Include all card types and subtypes, separated by spaces.<br /><br />Example:<br />* `Types:Enchantment Artifact Creature Golem` for a card that reads Enchantment Artifact Creature -- Golem
 
 Rarity and Set info are now defined in edition definition files. These can be found at /res/reditions path.
@@ -50,6 +50,7 @@ Rarity and Set info are now defined in edition definition files. These can be fo
 - filename: all lowercase, skip special characters, underscore for spaces
 - Unix(LF) line endings
 - use empty lines only when separating multiple faces on a card
+- AI SVars right before the Oracle
 - try to avoid writing default params to keep scripts concise
   - e.g. just `SP$ Draw` instead of `SP$ Draw | Defined$ You | NumCards$ 1`
 
@@ -59,67 +60,24 @@ All keywords need to be prepended with "K:" to be parsed correctly. Each keyword
 
 ## 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.<br>
+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
 - Cipher
-- Conspire
 - Convoke
-- Deathtouch
-- Defender
-- Delve
 - Devoid
-- Double Strike
-- Epic
-- Exalted
-- Fear
 - First Strike
-- Flanking
 - Flash
-- Flying
-- Forestwalk
-- Fuse
 - Haste
-- Hideaway
-- Horsemanship
 - Indestructible
-- Infect
-- Intimidate
-- Islandwalk
-- Landfall
-- Legendary landwalk
-- Lifelink
-- Living Weapon
-- Menace
 - Mentor
-- Mountainwalk
-- Nonbasic landwalk
-- Persist
-- Plainswalk
-- Prowess
 - Provoke
 - Reach
-- Rebound
-- Retrace
-- Riot
-- Shadow
 - Shroud
-- Snow forestwalk
-- Snow islandwalk
-- Snow landwalk
-- Snow mountainwalk
-- Snow plainswalk
-- Snow swamp walk
-- Soulbond
 - Split second
 - Storm
-- Sunburst
-- Swampwalk
-- Totem Armor
 - Trample
-- Unblockable
 - Undying
 - Vigilance
 - Wither
@@ -127,7 +85,6 @@ Examples:
 ## Keywords with parameters
 
 - Adapt:{cost}
-- AdjustLandPlays:{params}
 - Afterlife:{N}
 - AlternateAdditionalCost:{cost}
 - Amplify:{cost}:{validType(comma separated)}
@@ -135,9 +92,7 @@ Examples:
 - Bloodthirst:{magnitude}
 - Bestow:{cost}
 - Bushido:{magnitude}
-- CantBeBlockedByAmount {xMath}
 - Champion:{validType}
-- CostChange:{params}
 - Crew:{cost}
 - Cumulative upkeep:{cost}:{Description}
 - Cycling:{cost}
@@ -146,12 +101,9 @@ Examples:
 - Dredge:{magnitude}
 - Echo:{cost}
 - Emerge:{cost}
-- Enchant {params} \[Curse\]
+- Enchant:{Type}
-- Enchant {Type}
 - Entwine:{cost}
 - Equip:{cost}
-- etbCounter:{CounterType}:{CounterAmount}
-- ETBReplacement:{Control/Copy/Other}:{AbilitySVar}\[:Optional\]
 - Evoke:{cost}
 - Fabricate:{cost}
 - Fading:{FadeCounters}
@@ -159,13 +111,11 @@ Examples:
 - Foretell:{cost}
 - Fortify:{cost}
 - Graft:{value}
-- Haunt:{ability}:{Description}
+- Haunt:{ability}:<Ability>
-- Hexproof:{ValidCards}:{Description}
+- Hexproof:{ValidCards}:[Description]
 - Kicker:{cost}
 - Level up:{cost}
 - Madness:{cost}
-- ManaConvert:
-- maxLevel:{magnitude}
 - MayEffectFromOpeningHand:{Effect}
 - Miracle:{cost}
 - Modular:{magnitude}
@@ -176,8 +126,6 @@ Examples:
 - Ninjutsu:{cost}
 - Outlast:{cost}
 - Partner:{CardName}
-- Poisonous {magnitude}
-- PreventAllDamageBy {ValidCards}
 - Protection:{ValidCards}:{Description}
 - Prowl:{cost}
 - Rampage:{magnitude}
@@ -192,7 +140,6 @@ Examples:
 - Toxic:{poisonCounters}
 - TypeCycling:{Type}:{cost}
 - Unearth:{cost}
-- UpkeepCost:{cost}
 - Vanishing:{TimeCounters}
 
 ## Plaintext keywords
@@ -201,80 +148,12 @@ These are hardcoded but not truly keywords rules-wise and will eventually be tur
 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
-- CARDNAME attacks each turn if able.
-- CARDNAME attacks each combat if able.
-- CARDNAME blocks each combat if able.
-- CARDNAME blocks each turn if able.
-- CARDNAME can attack as though it didn't have defender.
-- CARDNAME can attack as though it had haste.
-- CARDNAME can block as though it were untapped.
-- CARDNAME can block creatures with shadow as though they didn't have shadow.
-- CARDNAME can block creatures with landwalk abilities as though they didn't have those abilities.
-- CARDNAME can block only creatures with flying.
-- CARDNAME can only attack alone.
-- CARDNAME can't attack.
-- CARDNAME can't attack if you cast a spell this turn.
-- CARDNAME can't attack if defending player controls an untapped creature with power {rest of text string}
-- CARDNAME can't attack or block.
 - CARDNAME can't attack or block alone.
-- CARDNAME can't be countered.
-- CARDNAME can't be enchanted.
-- CARDNAME can't be equipped.
-- CARDNAME can't be regenerated.
-- CARDNAME can't be the target of Aura spells.
-- CARDNAME can't block.
-- CARDNAME can't block creatures with power {rest of text string}
 - CARDNAME can't block unless a creature with greater power also blocks.
-- CARDNAME can't block unless at least two other creatures block.
-- CARDNAME can't transform
-- CARDNAME doesn't untap during your untap step.
-- CARDNAME enters the battlefield tapped.
-- CARDNAME is {color}.
 - CARDNAME must be blocked if able.
-- CARDNAME must be blocked by exactly one creature if able.
-- CARDNAME must be blocked by two or more creatures if able.
-- CARDNAME can't be blocked unless all creatures defending player controls block it.
-- CARDNAME's power and toughness are switched
-- CARDNAME untaps during each other player's untap step.
-- CARDNAME's activated abilities can't be activated.
-- Creatures with power greater than CARDNAME's power can't block it.
-- Creatures can't attack unless their controller pays:{params}
-- Damage that would be dealt by CARDNAME can't be prevented.
-- Damage that would reduce your life total to less than 1 reduces it to 1 instead.
-- Enchant artifact
-- Enchant creature
-- Enchant creature with converted mana cost 2 or less
-- Enchant creature without flying
-- Enchant red or green creature
-- Enchant land
-- Enchant land you control
-- Enchant tapped creature
-- No more than one creature can attack each combat.
-- No more than one creature can block each combat.
-- No more than two creatures can attack you each combat.
-- No more than two creatures can block each combat.
-- Play with your hand revealed.
-- Prevent all combat damage that would be dealt to and dealt by CARDNAME.
-- Prevent all combat damage that would be dealt by CARDNAME.
-- Prevent all combat damage that would be dealt to CARDNAME.
-- Prevent all damage that would be dealt to and dealt by CARDNAME.
-- Prevent all damage that would be dealt by CARDNAME.
-- Prevent all damage that would be dealt to CARDNAME.
-- Protection from {type}
 - Remove CARDNAME from your deck before playing if you're not playing for ante.
-- Spells and abilities your opponents control can't cause you to sacrifice permanents.
-- You can't pay life to cast spells or activate abilities.
-- You can't sacrifice creatures to cast spells or activate abilities.
-- You can't draw cards.
-- You can't gain life.
-- You can't lose the game.
-- You can't win the game.
-- You don't lose the game for having 0 or less life.
 - You may choose not to untap CARDNAME during your untap step.
-- You may have CARDNAME assign its combat damage as though it weren't blocked.
+- CantSearchLibrary
-- Your life total can't change.
 
 # General SVars
 
@@ -319,8 +198,6 @@ equipped already (Kor Duelist).
 
 `SVar:EndOfTurnLeavePlay:True`
 
-`SVar:maxLevel:`
-
 `SVar:HasCombatEffect:True`
 
 `SVar:HasAttackEffect:True`

docs/Card-scripting-API/Statics.md

@@ -0,0 +1,23 @@
+There are two major groups of static abilities:
+
+# Statics for the main 7 layers
+
+Syntax:  
+`S:Mode$ <Continuous> | <Affected$ {Valid Player/Card}> | <Layer-specific$ Params> | [Description$ {String}]`
+
+Here's an example for layer 7c:  
+`Affected$ Creature.YouCtrl | AddPower$ 1 | AddToughness$ 1 | Description$ Creatures you control get +1/+1.`
+
+See [StaticAbility.generateLayer()](https://github.com/Card-Forge/forge/blob/master/forge-game/src/main/java/forge/game/staticability/StaticAbility.java) for the full list of params on each Layer.
+
+*Note:* Layer 1 is currently only implemented as a resolving effect instead.
+
+# Statics for the concluding "game rules layer" ([CR 613.11](https://yawgatog.com/resources/magic-rules/#R61311))
+
+The available effects are defined here: [StaticAbilityMode](https://github.com/Card-Forge/forge/blob/master/forge-game/src/main/java/forge/game/staticability/StaticAbilityMode.java).
+
+*Note:* some rules-modifying parts are still coded via `Continuous` mode for now, e.g. `SetMaxHandSize$ {Integer}`.
+
+## Combat
+
+## Costs

docs/Creating-a-custom-Card.md

@@ -1,54 +1,6 @@
-# Guide - Creating a Custom Card
+Using the Forge API you can create your own custom cards and sets. This tutorial will walk you through the process of creating custom cards via the Force Custom Card Script.
 
-Using the Forge API you can create your own custom cards and sets. This guide will walk you through the process of creating custom cards via the Force Custom Card Script. 
+If you are trying to script cards for a new set make sure you take advantage of the [Developer Mode](Development/DevMode.md) for testing to try and contribute without any obvious bugs.
-
-The next tutorial will walk you through the process of adding your new cards to a custom set. 
-
-
-## File Locations
-
-### Custom Card Scripts
-
-Windows:
-> C:/Users/<your username>/Application Data/Roaming/Forge/custom/cards
-
-Linux:
-> ~/.forge/custom/cards
-
-Mac:
-> TODO Add filepath
-
-### Custom Tokens
-
-Windows:
-> C:/Users/<your username>/Application Data/Roaming/Forge/custom/tokens
-
-Linux:
-> ~/.forge/custom/tokens
-
-Mac:
-> TODO Add filepath
-
-### Custom Editions
-
-> C:/Users/<your username>/Application Data/Roaming/Forge/custom/editions
-
-Linux:
-> ~/.forge/custom/editions
-
-Mac:
-> TODO Add filepath
-
-### Card Images
-
-Windows:
-> C:/Users/<your username>/Application Data/Local/Forge/Cache/pics/cards
-
-Linux:
-> ~/.cache/forge/pics/cards
-
-Mac:
-> TODO Add filepath
 
 ## Creating a New Card
 
@@ -84,11 +36,11 @@ Let's break our card down:
  - K - A Keyword that gives our creature an ability. 
  - Oracle - The actual text that appears on that card. 
 
-For a refrence of possible fields and their descriptions please see the [Card Scripting API](Card-scripting-API) document. Note that maintaining an up to date list of every ability of every Magic Card ever printed is not feasable. The API is meant to serve as a guide and includes most common used information. 
+For a reference of possible fields and their descriptions please see the [Card Scripting API](Card-scripting-API) document. Note that maintaining an up to date list of every ability of every Magic Card ever printed is not feasable. The API is meant to serve as a guide and includes most common used information. 
 
 3. Add Card to a Set
 
-Now that we have a new card we need to add it to a set so that it will be included in the game. For the purposes of this turorial we'll add out card to an existing set. If you wish to create your own set you can follow this guide: `Guide Coming Soon`
+Now that we have a new card we need to add it to a set so that it will be included in the game. For the purposes of this tutorial we'll add our card to an existing set. If you wish to create your own set you can follow this [guide](Creating-a-custom-Set.md).
 
 Navigate to your Custom Editions folder and open the text file for the set you would like to add your card to. Let's add our card to the "DCI Promos" set.
 
@@ -171,8 +123,62 @@ Simply save and rename the image to "Goblin Card Guide.fullborder.jpg" then over
 
 You can check the [Abilities](AbilityFactory) and [Triggers](Triggers) documentation for more information on this topic. These documents are meant as a guide and are unlikely to contain information about every ability in the game.
 
-The sinplest method for creating an effect on your card is to find another card that does the same thing and copying the ability. These can be found in your Forge folder:
+The sinmlest method for creating an effect on your card is to find another card that does the same thing and copying the ability. These can be found in your Forge folder:
 
 >./Forge/res/cardsfolder/cardsfolder.zip
 
 Unzipping this file will sllow you to search for any card in the containing subfolders. 
+
+# Custom mechanics
+
+We don't accept new mechanics from outside of official Cards into the main repository. This restriction is needed to keep the engine healthy.
+
+However there is some support to simulate them using named abilities:
+
+This will support things like being able to target specific SA using a custom name. (Flash on Meditate abilities in this example)
+
+```text
+Name:Plo Koon
+ManaCost:3 W W
+Types:Legendary Creature KelDor Jedi
+PT:4/4
+
+S:Mode$ CastWithFlash | ValidSA$ Activated.NamedAbilityMeditate | Caster$ You | Description$ You may activate meditate abilities any time you could cast an instant.
+
+A:AB$ ChangeZone | Named$ Meditate | Cost$ 1 W | ActivationZone$ Battlefield | SorcerySpeed$ True | Origin$ Battlefield | Destination$ Hand | Defined$ Self | SpellDescription$ Meditate (Return this creature to its owner's hand. Meditate only as a sorcery.)
+
+Oracle:You may activate meditate abilities any time you could cast an instant.\nMeditate 1W (Return this creature to its owner's hand. Meditate only as a sorcery.)
+```
+
+Restrict trigger to only if was triggered by a specific type of SA (Only Scry when Meditating and not being bounced), and reduce cost for a specific type of ability.
+
+```text
+Name:Jedi Training
+ManaCost:U
+Types:Enchantment
+
+S:Mode$ ReduceCost | ValidCard$ Card | ValidSpell$ Activated.NamedAbilityMeditate | Activator$ You | Amount$ 1 | Description$ Meditate abilities you activate cost {1} less to activate.
+
+T:Mode$ ChangesZone | Origin$ Battlefield | Destination$ Hand | TriggerZones$ Battlefield | ValidCard$ Creature.Jedi+YouCtrl | Condition$ FromNamedAbilityMeditate | SubAbility$ DBScry | TriggerDescription$ Whenever a Jedi creature you control meditates, scry 1.
+SVar:DBScry:DB$ Scry | ScryNum$ 1
+
+Oracle:Meditate abilities you activate cost {1} less to activate.\nWhenever a Jedi creature you control meditates, scry 1.
+```
+
+It will also allow for cards to check if a card was cast using an certain ability using `Count$FromNamedAbility<name>.<true>.<false>`:
+
+```text
+Name:Chronic Traitor
+ManaCost:2 B
+Types:Creature Human Rogue
+PT:2/1
+
+T:Mode$ ChangesZone | Origin$ Any | Destination$ Battlefield | ValidCard$ Card.Self | TriggerZones$ Battlefield | Execute$ TrigSacrifice | TriggerDescription$ When this creature enters, each player sacrifices a creature. If this creature's paranoia cost was paid, each player sacrifices two creatures instead.
+SVar:TrigSacrifice:DB$ Sacrifice | Defined$ Player | SacValid$ Creature | Amount$ X
+SVar:X:Count$FromNamedAbilityParanoia.2.1
+
+T:Mode$ ChangesZone | TriggerZones$ Hand | ValidCard$ Permanent.YouCtrl | Origin$ Battlefield | Destination$ Any | Execute$ PayParanoia | TriggerDescription$ Paranoia {2}{B}{B} (You may cast this spell for its paranoia cost when a permanent you control leaves the battlefield.)
+SVar:PayParanoia:DB$ Play | Named$ Paranoia | PlayCost$ 2 B B | ValidSA$ Spell.Self | Controller$ You | ValidZone$ Hand | Optional$ True
+
+Oracle:When this creature enters, each player sacrifices a creature. If this creature's paranoia cost was paid, each player sacrifices two creatures instead.\nParanoia {2}{B}{B} (You may cast this spell for its paranoia cost when a permanent you control leaves the battlefield.)
+```

docs/Creating-a-custom-Set.md

@@ -1,5 +1,3 @@
-# Creating a custom set
-
 This is a tutorial to start creating your own custom set, or implementing an existing one. We'll take you step by step into implementing a few cards from [MSEM Champions](https://msem-instigator.herokuapp.com/set/MPS_MSE). This is a basic guide to help you get started.
 
 **Note:** This tutorial is currently for **Windows only**.
@@ -111,11 +109,11 @@ Each line is as follow: `CollectorNumber Rarity CardName @ArtistName`.
 
 > Note: You can put the cards in the list even if they aren't scripted yet. Forge will skip over them.
 
-```
+```text
 [tokens]
-b_1_1_bird_flying
+1 b_1_1_bird_flying
-b_3_3_cat_deathtouch
+2 b_3_3_cat_deathtouch
-b_5_5_golem_trample
+3 b_5_5_golem_trample
 ```
 
 The **[tokens]** section is optional, and only needed if you want to use specific token images in this set. They should be named using the name of their token script. `b_1_1_bird_flying` means it is a black 1/1 bird with flying. More on that later.
@@ -124,7 +122,7 @@ If you load the game with just file, you'll be able to see that Master Chef, Une
 
 Let's comment out Master Chef to avoid a name conflict with an existing MTG card:
 
-```
+```text
 [cards]
 #7 M Master Chef
 33 M Golden Touch
@@ -133,9 +131,9 @@ Let's comment out Master Chef to avoid a name conflict with an existing MTG card
 
 Save your file, and let's move onto another step.
 
-## Scripting your first cards
+> If there is a conflict, you can add something in its name for differenciate it, such as a set tag (ie. `Master Chef (MSEM)`).
 
-As mentioned earlier, your custom card rules need to be located inside `%appdata%/Forge/custom/cards`. I recommend creating subfolders for each starting letter (`Forge/custom/cards/a`, `Forge/custom/cards/b`, etc.) to quickly find if a card has a duplicate name.
+## Scripting your first cards
 
 Now, you might remember than Unearth was an existing MTG card so we do not need to create a custom card rule for it. Let's create a few others.
 > This tutorial will not teach you to script your cards, and they might not be perfect. Please check out [Creating a Custom Card](https://github.com/Card-Forge/forge/wiki/Creating-a-Custom-Card) if you want more info, or look at the existing cards to learn more complex scripting.
@@ -143,7 +141,8 @@ Now, you might remember than Unearth was an existing MTG card so we do not need
 Let's create the following files:
 
 avatar_of_basat.txt
-```
+
+```text
 Name:Avatar of Basat
 ManaCost:R
 Types:Creature Avatar
@@ -154,7 +153,8 @@ Oracle:Menace\nAvatar of Basat can't block.
 ```
 
 exhunt.txt
-```
+
+```text
 Name:Exeunt
 ManaCost:B
 Types:Instant
@@ -164,7 +164,8 @@ Oracle:Each player sacrifices a creature.
 ```
 
 fox_of_the_orange_orchard.txt
-```
+
+```text
 Name:Fox of the Orange Orchard
 ManaCost:1 W
 Types:Creature Fox Spirit
@@ -173,7 +174,8 @@ Oracle:
 ```
 
 inked_summoner.txt
-```
+
+```text
 Name:Inked Summoner
 ManaCost:1 B
 Types:Creature Human Warlock Artist
@@ -192,7 +194,7 @@ Oracle:At the beginning of your end step, if you lost 2 or more life this turn,
 
 If you load your game now, you should be able to find these cards you just scripted! You'll also notice that Inked Summoner is only listed as a Human Warlock, missing the Artist subtype. That's because Artist is not a real MTG subtype. You can add custom types directing inside the set definition file by following the sections found inside the `res/lists/TypeLists.txt` file. Duplicates will be ignored.
 
-```
+```text
 [CreatureTypes]
 Artist:Artists
 ```
@@ -201,13 +203,12 @@ Oh no! If you play with Inked Summoner now, you will crash when summoning a toke
 
 ## Scripting custom tokens
 
-The token scripts are located at `%appdata%/Forge/custom/tokens`.
-
 Let's add the new tokens we need to make Inked Summoner work!
 > Just like for card scripting, this tutorial will not teach you about scripting them.
 
 b_1_1_bird.flying.txt
-```
+
+```text
 Name:Bird Token
 ManaCost:no cost
 Colors:black
@@ -218,7 +219,8 @@ Oracle:Flying
 ```
 
 b_3_3_cat_deathtouch.txt
-```
+
+```text
 Name:Cat Token
 ManaCost:no cost
 Colors:black
@@ -229,7 +231,8 @@ Oracle:Deathtouch
 ```
 
 b_5_5_golem_trample.txt
-```
+
+```text
 Name:Golem Token
 ManaCost:no cost
 Colors:black
@@ -243,9 +246,9 @@ Great! Now Inked Summoner no longer make the game crash! Now let's add some imag
 
 ## Adding card and token images
 
-You can find the card images for the MSEM Champions edition [here](https://msem-instigator.herokuapp.com/set/CHAMPIONS). Find the ones you need and save them inside `%appdata%/../Local/Forge/Cache/pics/cards/MSEM_CHAMPIONS` Remember the filename format should be something like `Swamp.full.jpg` if you only have one variant in your edition. If you have multiples, then it should be something like `Fox of the Orange Orchard1.full.jpg`, `Fox of the Orange Orchard2.full.jpg`, etc. You can find the alternate images from [here](https://msem-instigator.herokuapp.com/set/MPS_MSE) if you want.
+You can find the card images for the MSEM Champions edition [here](https://msem-instigator.herokuapp.com/set/CHAMPIONS). Find the ones you need and save them inside `%appdata%/../Local/Forge/Cache/pics/cards/MSEM_CHAMPIONS` Remember the filename format should be `{cardname}.fullborder.jpg` if you only have one variant in your edition. If you have multiples, then it should be `{cardname}{number}.fullborder.jpg` (ie. `Fox of the Orange Orchard1.fullborder.jpg`, `Fox of the Orange Orchard2.fullborder.jpg`, etc). You can find the alternate images from [here](https://msem-instigator.herokuapp.com/set/MPS_MSE) if you want.
 
-For the tokens, we can deposit them inside `%localappdata%/Forge/Cache/pics/tokens/MSEM_CHAMPIONS`. They should be named the same as their token script so `b_1_1_bird_flying.jpg` and so forth.
+For the tokens, we can deposit them inside `%localappdata%/Forge/Cache/pics/tokens/MSEM_CHAMPIONS`. They should be named the same as their number + token script so `1_b_1_1_bird_flying.jpg`, `2_b_3_3_cat_deathtouch.jpg`, and so forth.
 
 ![b_1_1_bird_flying](https://github.com/user-attachments/assets/531583c1-3985-4744-858a-3a49fd12740a)
 ![b_3_3_cat_deathtouch](https://github.com/user-attachments/assets/15a24e62-be43-4c0c-aeac-0ddb38fca97a)
@@ -253,6 +256,15 @@ For the tokens, we can deposit them inside `%localappdata%/Forge/Cache/pics/toke
 
 You can now start your game again, and see that the art loads correctly now.
 
-## 🎉 Congratulations!
+## Excursion: Card variants
+
+There are currently multiple ways to specify a flavor name:
+* Manually, by writing `Variant:Foo:FlavorName:Loret Ipsum` in the card script, and adding `${"variant": "Foo"}` to the end of the edition entry. You'll also want to add `Variant:Foo:Oracle:When Loret Ipsum enters...` if the flavor name would appear in the Oracle text, or if it would otherwise be changed.
+* By lookup, again by using `Variant:Foo:FlavorName:Loret Ipsum` in the card script, but simply using "Loret Ipsum" as the name in the edition file.
+* Automatically, by putting `${"flavorName": "Loret Ipsum"}` at the end of the edition entry.
+
+The third method is the easiest, but besides a simple find/replace for the card name, it won't be able to make any changes to flavor the Oracle text, such as for ability words. They all function the same under the hood once the CardDB is loaded; the latter two are just shortcuts for the first.
+
+## 🎉 Congratulations
 
 You’ve just added your first custom set in Forge! There's still much more to explore — scripting advanced abilities, custom mechanics, and set structures — but you now have a solid foundation to build from.

docs/Development/Android-Builds.md

@@ -42,5 +42,3 @@ mvn -U -B clean \\
     -Dcardforge.user=${FORGE_FTP_USER} \\
     -Dcardforge.pass=${FORGE_FTP_PASS}
 ```
-
-After this, the appropriate forum posts will need to be made announcing the new release.

docs/Development/DevMode.md

@@ -2,19 +2,10 @@ Developer Mode is a Mode that allows Developers to try out different
 things and gain different shortcuts during play. In a Normal program,
 this Mode would be available in a Debug build, but removed from the code
 during the Retail build. Since Forge is in constant Beta, this Mode is
-available during our Beta releases. On the NewGame Screen, just make
+available during our Beta releases. You can turn on or off this mode at the
-sure it's checked and you'll be able to edit the options at any point
+Home View -> Game Settings -> Preferences -> Gameplay Options section.
-during the game.
 
-## Lose By Decking
+It's important to note you won't get achievements in a game once you started cheating.
-
-This one is a simple Checkbox. If your Library is Empty and you try to
-try a card, you normally lose the game. This checkbox should be on by
-Default (meaning you lose) but if you are running a deck without many
-cards, uncheck this box so you don't lose when failing to draw a card
-when you need to.
-
-\[THIS OPTION NOT READILY VISIBLE IN VERSIONS 1.6.23\]
 
 ## View Zone
 
@@ -26,8 +17,7 @@ that Zone are revealed to you.
 ## Generate Mana
 
 Useful for not needing Land in your Deck while you are just trying to
-test something out, by selecting Generate Mana, 7 of each color and 7
+test something out, by selecting Generate Mana, 7 of each type is generated and put into your Mana Pool.
-colorless is generated and put into your Mana Pool.
 
 ## Setup Game State
 
@@ -179,5 +169,3 @@ AI hands and leaves them intact, and adds Force of Nature, Raging
 Goblin, and Amulet of Kroog to the computer's graveyard. Does not
 replace either library. Sets the current player to Human and the current
 phase to Main 1.
-
-It's important to note you won't get achievements in a game once you started cheating.

docs/Development/Network-Play-Rewrite.md

@@ -1,44 +0,0 @@
-# Why Rewrite Network Play?
-
-The current implementation of **Network Play** relies on [Java serialization/deserialization](https://www.geeksforgeeks.org/serialization-in-java/) via [Netty](https://netty.io/).  While this does work, it is inefficient, transferring large amounts of unnecessary (duplicate) data.  The transferring of duplicate data has two negatives:
-
-1. increased latency
-2. increased bandwidth
-
-The increased latency is very noticeable throughout a network game.
-The increased bandwidth is a potential concern for mobile players, not everyone has an unlimited data plan.
-
-Testing of the existing **Network Play** implementation has shown an individual **Game** transferring over 300MB of data.
-
-# The Rewrite
-
-The rewrite will utilize [protobuf](https://developers.google.com/protocol-buffers) and be approached in phases:
-
-1. Lobby
-2. Match
-3. Game
-
-## Lobby
-
-The **Lobby** portion will handle:
-
-* Handshake
-* Player
-  * Name
-  * Avatar
-* Game Rules Selection
-* Deck Submission
-
-The **Handshake** portion of the **Lobby** will be responsible for ensuring that it is a **Forge** client that is connecting **and** that the client is running a compatible **Network Play** implementation.
-
-## Match
-
-Number of **Games** that comprise a **Match**, normally first player to win 2 **Games**.  This is important, because it is not *technically* best of 3.  For example if either of the first two games of a **Match** are a *draw*, it is entirely possible to play a fourth **Game** in a **Match**. (Need a judge ruling reference on this)
-
-## Game
-
-This will be broken down in more detail, but the important bits to hand first are:
-
-* Phases
-* Passing of **priority**
-* Notification upon receipt of **priority**

docs/Development/Snapshots-and-Releases.md

@@ -40,7 +40,5 @@ It would be useful for other people to be comfortable with the release process.
 * Create a PR from your branch and get it merged as quickly as you can (ideally before other PRs are merged). 
 * Create a new release from https://github.com/Card-Forge/forge/releases
 * Upload the package and its sha to the create new release page
-
+5. Marketing
-
-4. Marketing
 * Advertise in the #announcements channel in the Discord

docs/Development/ownership.md

@@ -34,7 +34,7 @@ The "Ancestors" column is basically there to list currently inactive developers
 ## Forge Script DSL
 | Concept | Owners | Ancestors | Example tasks |
 | - | - | - | - |
-| [Card Scripting](cardscripting) | TRT, Northmoc, Simisays, Fulgur14, Dracontes | a lot | - implement new Sets<br>- clean up outdated elements<br>- apply Oracle updates |
+| [Card Scripting](cardscripting) | TRT, Northmoc, Simisays, Fulgur14, Dracontes | a lot | - implement new Sets<br>- review script PR<br>- clean up outdated elements<br>- apply Oracle updates |
 | ForgeScribe | | Austinino | |
 
 ## Modes

docs/Forge-historical-reference.md

@@ -26,6 +26,8 @@ Mostly old-style interface with new age loading screen. Initial card scripting i
 
 Supports over 10,000 cards. We start using a reconstructed UI that allows for better theming. And makes things feel less like an "Application" and more like a "Game"
 
+## 2013-10 - ver 1.5.1 is the first with Commander
+
 ## 2014-05 - Android app is published via Maven
 
 ## 2015-04 - Network play is rudimentary but available
@@ -36,8 +38,6 @@ Supports over 10,000 cards. We start using a reconstructed UI that allows for be
 
 ## 2024-07 - _All non-Un set cards have been added to Forge_
 
-## 2024-08 - Bloomburrow release
-
 ## 2024-09 - Duskmouth Release 1.6.65 (**Last release that supports Java 1.8**)
 
 Supports over 28,500 cards. 
@@ -68,8 +68,6 @@ For any of you curious about what the first attempt at making a Shandalar-like A
 Interestingly, the above-mentioned thread refers to the proposed game mode as "Adventure Mode" a few times (closer to the end of the thread), something that we actually currently have and actively develop 👍
 The interesting aspect of that development was the day/night cycle, I don't know why but I remember I thought that it looked quite atmospheric back in the day
 
-
-
 ## Abe Sergeant writes about Forge
 
 2009-09-11 - Here is the article on star city. 
@@ -80,15 +78,12 @@ And here is it in archive.org in case that gets taken down
 
 https://web.archive.org/web/20210707215155/https://articles.starcitygames.com/articles/the-kitchen-table-302-an-mtg-forge-quest/
 
-MTG Forge comes with a Quest Mode. In Quest Mode, you begin with a random selection of cards, and have to build a 60-card deck. Then you play against decks by various computer opponents, and as you win, you get more cards, and the difficulty of your opponents increases.
+> MTG Forge comes with a Quest Mode. In Quest Mode, you begin with a random selection of cards, and have to build a 60-card deck. Then you play against decks by various computer opponents, and as you win, you get more cards, and the difficulty of your opponents increases.<br />
-
+> Quest is the most fun I’ve had playing Magic in a year.
-Quest is the most fun I’ve had playing Magic in a year.
-
-What I am going to do is show you a quick 10-game win in quest. You can play to 10, 20, 30, or 40 wins, but I’m just going to show you a 10 win in quest. I will show you where the game has bugs too, so you can see what I am talking about when I say WIP. I’m not holding anything back.
 
 # Major disruptions
 
-One interesting thing about Forge is the way it grew. Much of the first few years was solely on the back of an Amateur software engineer called "MTG Rares" soon enough "Dennis Bergkamp" came along and was doing a bunch more development. New Software Engineers joined the ranks off and on. From there on people would jump in, help for a handful of years and get too busy with life, or stop really playing magic or whatever. A handful of us have been around the longhaul, but not too many. 
+One interesting thing about Forge is the way it grew. Much of the first few years was solely on the back of an Amateur software engineer called "MTG Rares". Soon enough "Dennis Bergkamp" came along and was doing a bunch more development. New Software Engineers joined the ranks off and on. From there on people would jump in, help for a handful of years and get too busy with life, or stop really playing magic or whatever. A handful of us have been around the longhaul, but not too many. 
 
 ## Sourceforge SVN (2007-2008)
  Original location. Moved when the name changed.
@@ -103,13 +98,11 @@ One interesting thing about Forge is the way it grew. Much of the first few year
 ## Github (2021-Present)
  Conversion from Git to Git was a lot easier.
 
-
 ## Jendave's modularization (2011)
 The initial modularization attempt pulled everything from living under forge-gui/ module and built out some of the Maven structure. 
 
 ## Maxmtg's modularization (2013?)
 Took this the next step further massively reorganizing the codebase. It caused major issues and took a few months to get resolved.
 
-## Hanmac's modularization (2017?
+## Hanmac's modularization (2017?)
 This was a smaller modularization mostly within certains areas that ultimately was positive, but led to some headaches during the process.
-

docs/Frequently-Asked-Questions.md

@@ -1,35 +1,25 @@
-This is a list of basic troubleshooting questions that come up for most new players, before running to the discord about your issue, please review this FAQ for some of the more common issues.
+This is a list of basic troubleshooting questions that come up for most new players, before running to the discord about your issue, please review this document for some of the more common issues.
-
-### Check the FAQ in Discord 
 
+* Check the FAQ in Discord (probably more up-to-date if things break unexpectedly on us)
 https://discord.com/channels/267367946135928833/1095026912927154176
 
-### Search the help posts in Discord
+* Search the help posts in Discord
-
 https://discord.com/channels/267367946135928833/1047001034788196452
 
-### Write a post in help section of Discord
-
-https://discord.com/channels/267367946135928833/1047001034788196452
-
-Note: For now, please also check [this](https://www.slightlymagic.net/forum/viewtopic.php?f=26&t=11825) forum topic for some additional information.
-
 # General
 
-### How do I download content?
+## How do I download content?
 
-Forge has content downloaders within the app itself, you can use those tools to update the graphics assets. More information about card and token image assets can be found here. [Card Images, Downloading](Card-Images#downloading)
+Forge has content downloaders within the app itself, you can use those tools to update the graphics assets. More information about card and token image assets can be found here. [Card Images, Downloading](Card-Images.md#downloading)
 
+## My desktop match/deck view is all messed up?
+The match and deck editor windows contain panels that can be moved and/or resized. The changes that you make are saved to files that are named "editor.xml" and "match.xml". These files can be found in your userDir/preferences/ directory.
 
+Sometimes people will decide that they do not like the changes that they made and wish to go back to the original layout. To reset layouts to default, go to the Game Settings -> Preferences -> Troubleshooting section. You will find at this location two buttons that will reset the match layout and the deck editor layouts.
 
-* If you have an older Android device for increased performance or to save bandwidth it might be a good idea to use lower resolution images instead: https://www.slightlymagic.net/forum/viewtopic.php?f=15&t=29104
+Also use the mentioned measure if your match or deckeditor won't start - it would help in 90% of the cases.
 
-### How do I extract Forge?
+## I think I found a bug in Forge. What do I do?
-
-* Forge uses a .tar.bz2 format for archiving. Depending on your operating system, different utilities can be used to untar the archive. 
-  * If you use Windows, you may want to try 7-Zip (http://www.7-zip.org/download.html).
-
-### I think I found a bug in Forge. What do I do?
 
 *Most users, who are running beta versions of Forge, should continue to use these instructions. As for alpha testers, these instructions have yet to be made congruent with the latest automatic bug reporting from within Forge.*
 
@@ -37,10 +27,9 @@ Bug reports from users are the lifeblood of Forge. Please keep in mind that "bet
 
 For starters, please take note of (1) what you had in play, (2) what your opponent had in play and (3) what you were doing when the error occurred. If you get a Crash Report from inside Forge, please save the data to a file. This information is very important when reporting a problem. Don't worry if you didn't think of that right away, until your next start, the "Forge.log" in the game directory will also provide that information.
 
-If you did not get a Crash Report, but you have experienced a problem in how Forge handled one or more cards or game rules, *please read the cards (and the Oracle rulings) carefully* to make sure you understand how they work. You may be surprised to find that Forge is actually enforcing the rules 
+If you did not get a Crash Report, but you have experienced a problem in how Forge handled one or more cards or game rules, *please read the cards (and the Oracle rulings) carefully* to make sure you understand how they work. You may be surprised to find that Forge is actually enforcing the rules correctly.
-correctly.
 
-Because duplicate bug reports use up our limited resources, please research your bug with the **Search** box on Forge's [issue tracker](https://git.cardforge.org/core-developers/forge/-/issues) to see if your bug has already been reported there. For Crash Reports, use key words from the second paragraph of the Crash Report.
+Because duplicate bug reports use up our limited resources, please research your bug with the **Search** box on Forge's [issue tracker](https://github.com/Card-Forge/forge/issues) to see if your bug has already been reported there. For Crash Reports, use key words from the second paragraph of the Crash Report.
 
 * If you find a matching issue, examine it to see if you have anything new to contribute. For example, a different way of reproducing a problem can sometimes be helpful. If the issue was posted to the forum, you may post your additional information there.
 
@@ -48,13 +37,13 @@ Because duplicate bug reports use up our limited resources, please research your
 
 * If you're unsure, you can also post on one of the support channels of the discord. In case you do not get a timely response, please submit a new issue anyway to make sure it doesn't get lost.
 
-### I have an idea to make Forge better. What do I do?
+## I have an idea to make Forge better. What do I do?
 
 Follow the directions in [Bug Reports](Frequently-Asked-Questions#i-think-i-found-a-bug-in-forge-what-do-i-do), keeping in mind that you are not reporting a bug, but rather a **Feature Request**.
 
 # Development
 
-### I want to help develop Forge. How do I get started?
+## I want to help develop Forge. How do I get started?
 
 Forge is written in Java, so knowledge in that language (or similar Object Oriented languages like C++ or C\#) is very helpful. However, it is possible to learn the grammar for writing the data objects of cards without programming experience.
 
@@ -62,32 +51,38 @@ A development environment such as [IntelliJ](https://www.jetbrains.com/idea) is
 
 Thanks to the nature of how cards are implemented, you can also contribute these as small plain text files. This is especially helpful during a preview season, when there are a lot of new cards in the backlog. This is mostly coordinated in #card-scripting on the Discord (and the pins there).
 
-To obtain the source code of Forge, read our [Development Guide]((SM-autoconverted)--how-to-get-started-developing-forge).
+For smaller first-time contributions using the GitHub web interface is also an alternative:
+![github](Development/github.png)
 
-### My system is all setup to help. What now?
+1. Register GitHub Account (if you don't already have one)
+2. Make your own fork of Forge, press this button on the main project page (must only be done first time)
+3. In your fork you can navigate to `forge-gui/res/cardsfolder/upcoming` and either Upload new files or open an existing one
+4. When you're done at the bottom make sure to create a new branch, that makes it easier to keep your changes apart
+5. On the next page make sure you choose the original project as merge target (see screens)
+6. Please test your scripts and watch for review comments
+
+To obtain the source code of Forge, read our [Development Guide](Development/IntelliJ-setup/IntelliJ-setup.md).
+
+## My system is all setup to help. What now?
 
 Take a look through the /res/cardsfolder folder. This is where all the card data lives. If you know of cards that are missing from Forge, see if there are similar cards that already exist.
 
 # Gameplay
 
-### Where do I use Flashback or a similar ability that is in an External area?
+## Where do I use Flashback or a similar ability that is in an External area?
 
-Click on the Lightning Bolt icon in the player panel. Since cards with External Activations aren't as clear to activate, we created this shortcut for this specific purpose.
+Click on the Lightning Bolt icon in the player panel. Since cards with external Activations aren't as clear to activate, we created this shortcut for this specific purpose. After the last card is removed from a zone window, that window will automatically be hidden.
 
-### How do I target a player?
+## How do I target a player?
 
 Just click on the player's Avatar in the Player Panel when prompted to select a Player as a target.
 
-### Where did my mana go?
+## Where did my mana go?
 
 If you have an effect that generated you some mana, and you don't know where it is. Check out the Player Panel. There are 6 different mana subpools one for each color/colorless that should have it. If you accidentally tapped your mana before your Main Phase, your mana is gone. Sorry, we don't have a way at this time to revert these actions. In general, I'd say it's easier/better to start casting a spell first, then activate your mana so this doesn't happen.
 
 # Quest Mode
 
-### What is the difference between Fantasy Quest and Normal Quest?
+## What is the difference between Fantasy Quest and Normal Quest?
 
 In Normal Quest, you start with 20 life and only have access to the Card Shop. In Fantasy Quest, you start at 15 life and gain additional access to the Bazaar which allows you to buy things like extra life points, Pets, Plants and more.
-
-### Sealed Deck Mode
-
-[HOW-TO: Customize your Sealed Deck games with fantasy blocks](https://www.slightlymagic.net/forum/viewtopic.php?f=26&t=8164)

docs/Home.md

@@ -8,37 +8,35 @@ Forge is a "Rules Engine" for the game Magic: the Gathering.
 Forge is not related in any way with Wizards of the Coast.  
 Forge is open source software released under the GNU Public License.
 
-Up to 8 players are supported, with control of each assigned to human or AI control. Player decks can be imported, user-created with the Deck Editor, or automatically generated. Over 99% (and counting) of all cards in Magic's existence are available, with the missing ones mostly being pointless to implement in the context (e. g. the notorious Chaos Orb) or impossible. That's more than the official Magic Online! 
+Up to 8 players are supported, with each assigned to human or AI control. Player decks can be imported, user-created with the Deck Editor, or automatically generated. Over [99%](Missing-Cards-in-Forge.md) (and counting) of all cards in Magic's existence are available, with the missing ones mostly being pointless to implement in the context (e.g. the notorious Chaos Orb) or impossible. That's more than the official Magic Online!
 
-For a complete list of unimplemented cards, either check the most recent release topic on the forums or use the "Audit Card and Image Data" check from "Content Downloaders" menu.
+Forge creates a unique experience by combining this enormous card library with some RPG elements in [**Quest mode**](https://www.slightlymagic.net/forum/viewtopic.php?f=26&t=9258) on the desktop version, and **Planar Conquest** on the mobile version.
 
-Forge creates a unique experience by combining this enormous card library with some RPG elements in [**Quest mode**](https://www.slightlymagic.net/forum/viewtopic.php?f=26&t=9258) (comparable to the 'Shandalar', the late 90's PC Game) on the desktop version, and **Planar Conquest** on the mobile version. Forge now includes a Graphical Map Based game mode called "Adventure Mode" which is more akin to 'Shandalar.'
+Forge also features a wide variety of puzzles. For more details and features see the other pages in this wiki.
 
-Forge also features a wide variety of puzzles. For more details and features see the MANUAL.txt in your game folder.
+Currently, Forge functions best in Human vs. AI matches. Playing against another human player over the Internet with [Online Multiplayer mode](Network-FAQ.md) is functional, but may still result in game play errors.
-
-Currently, Forge functions best in Human vs. AI matches. Playing against another human player over the Internet with Online Multiplayer mode is functional, but may still result in game play errors. See the Network Play section of this wiki.
 
 # Adventure Mode
-Forge now has an Adventure Mode, along with the Classic deck building and match game modes with AI.
+Forge now includes a Graphical Map Based game mode, along with the Classic deck building and match game modes with AI.
 
-Adventure mode is a work-in-progress game mode where you explore the ever-changing landscape of Shandalar, and duel creatures to gain gold and new cards ~~to become the best and collect them all!~~ to battle the bosses in the castles for each color. You can visit towns to buy equipment and cards, crawl through dungeons to find artifacts and loot to help you on your journey. Adventure mode is an awesome reimagining of the original 'Shandalar' 90's PC Game in Forge.
+Adventure mode is a work-in-progress game mode where you explore the ever-changing landscape of Shandalar, and duel creatures to gain gold and new cards ~~to become the best and collect them all!~~ to battle the bosses in the castles for each color. You can visit towns to buy equipment and cards, crawl through dungeons to find artifacts and loot to help you on your journey. Adventure mode is an awesome reimagining of the original 'Shandalar' late 90's PC Game in Forge.
 
 Adventure is baked into the Android/Mobile release of Forge, and as a separate executable already provided in the Desktop release package.
  
 # Download and Install
 
-* Most users please see the [User Guide.](User-Guide)
+* Most users please see the [User Guide](User-Guide.md).
 
-* For SteamDeck or Bazzite Installation see [Steam Deck Install.](Steam-Deck-and-Bazzite-Install)
+* For SteamDeck or Bazzite devices see this [extra manual](Steam-Deck-and-Bazzite-Install.md).
 
 # Support
-[Basic Troubleshooting](Troubleshooting-FAQ) - Check here first.
+[Basic Troubleshooting](#Troubleshooting.md) - Check here first.
 
 [Join the Discord](https://discord.com/invite/3v9JCVr)! - We're happy to help you get going.
 
-[Other Frequently Asked Questions](Frequently-Asked-Questions) - For more advanced questions about forge mechanics and gameplay.
+[Other Frequently Asked Questions](Frequently-Asked-Questions.md) - For more advanced explanations about Forge mechanics and gameplay.
 
-# Forge Developers
+# Developers
 
 The original programmer can be found at http://mtgrares.blogspot.com. A while
 back he open sourced the project and let the other developers improve it
@@ -52,6 +50,8 @@ lot of behind the scenes action going on. For each release, it is common
 for the release developer to give a shout out for those that helped
 specifically for that version. Feel free to give kudos there.
 
-If you are curious about the written/oral history of Forge, we're working on recreating some of that [Forge Historical reference](Forge-historical-reference)
+If you are curious about the written/oral history of Forge, we're working on recreating some of that [Forge Historical reference](Forge-historical-reference.md)
+
+***
 
 > <span style="color: red;">Note:</span> if you're reading this locally here's the [Table of Contents](_sidebar.md)

docs/Keyboard-Shortcuts.md

@@ -1,11 +0,0 @@
-# Keyboard Shortcuts
-
-The following shortcuts are available for the player during the match:
-
-- Space: Confirm (most times, is the button shown on the left)
-- Escape: Cancel (most times, is the button shown on the right)
-- E: end turn
-- Ctrl + Q: concede
-- Ctrl + Z: undo
-- Y: auto-yield to a trigger (always YES)
-- N: auto-yield to a trigger (always NO)

docs/Retired/(SM-autoconverted)-Duplicate-decks-checking-tool.md

@@ -1,23 +0,0 @@
-**[WARNING!!!]**
-
-Page imported from the old SlightlyMagic wiki. To be integrated into other wiki pages and/or README... or deleted.
-
----
-
-## Duplicate decks checking tool
-
-This python script will check through your deck files and identify which
-ones are similar to each other.
-
-It has been tested with Python 2.6.
-
-The source can be found on [it's bitbucket
-page](https://bitbucket.org/asret/forge/src/tip/deckdupcheck.py), or
-[downloaded
-directly](https://bitbucket.org/asret/forge/raw/tip/deckdupcheck.py).
-
-To run it, download it to your forge's "res" directory and invoke the
-python interpretor on it.
-
-It still needs work. At present it checks all decks against every other.
-This means it will output each matching pair twice - once for each deck.

docs/Retired/(SM-autoconverted)-maven-build-system.md

@@ -1,125 +0,0 @@
-**[WARNING!!!]**
-
-Page imported from the old SlightlyMagic wiki. To be integrated into other wiki pages and/or README... or deleted.
-
----
-
-**WORK IN PROGRESS**
-
-### Install Maven
-
-<http://maven.apache.org/download.html#Installation>.
-
-To test your installation you should execute the following command:
-
-`mvn --version`
-
-You should see something like like this:
-
-`Apache Maven 3.0.3 (r1075438; 2011-02-28 09:31:09-0800)`  
-`Maven home: /opt/local/share/java/maven3`  
-`Java version: 1.6.0_24, vendor: Apple Inc.`  
-`Java home: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home`  
-`Default locale: en_US, platform encoding: MacRoman`  
-`OS name: "mac os x", version: "10.6.7", arch: "x86_64", family: "mac"`
-
-#### Mac OSX
-
-Maven should already be installed. To test installation, open the
-Terminal application run the test command above.
-
-#### Windows
-
-1.  Use the above link to download the zip file.
-2.  Unzip the file into a directory.
-3.  Add the directory to your "PATH" variable.
-4.  Open a command window
-5.  Execute the test command above.
-
-#### Linux
-
-1.  Open your package manager e.g. Synaptic on Debian
-2.  Install the Maven2 package
-3.  Open a Terminal
-4.  Execute the test command above.
-
-### Install SVN
-
-<http://subversion.tigris.org/>
-
-To test your installation you should execute the following command:
-
-`svn --version`
-
-You should see something like like this:
-
-`svn, version 1.6.17 (r1128011)`  
-`compiled Jun  2 2011, 09:40:34`
-
-#### Mac OSX
-
-Maven should already be installed. To test installation, open the
-Terminal application run the test command above.
-
-#### Windows
-
-1.  Use the above link to download the zip file.
-2.  Unzip the file into a directory.
-3.  Add the directory to your "PATH" variable.
-4.  Open a command window
-5.  Execute the test command above.
-
-#### Linux
-
-1.  Open your package manager e.g. Synaptic on Debian
-2.  Install the Subversion package
-3.  Open a Terminal
-4.  Execute the test command above.
-
-### Build Forge
-
-From a terminal window, go to the directory where forge was checked out
-via GIT. Update to the latest version of the code
-
-`mvn scm:update`
-
-Use this command to perform a simple build of the jar file
-
-`mvn -U -B clean install`
-
-Use this command to do a snapshot package build
-
-`mvn -U -B clean -P osx,windows-linux install`
-
-Use this command to do a snapshot package build of the Windows/Linux
-package only
-
-`mvn -U -B clean -P windows-linux install`
-
-Use this command to do a snapshot package build of the Mac OSX package
-only
-
-`mvn -U -B clean -P osx install`
-
-Use this command to do a snapshot package build and site deployment
-
-`mvn -U -B clean -P osx,windows-linux install site deploy site:deploy`
-
-Use this command to do full package build and upload to GoogleCode
-
-`mvn -U -B clean -P osx,windows-linux install site release:clean release:prepare release:perform -Dusername="`<user>`" -Dpassword="`<password>`"`
-
-where <user> and <password> are your GoogleCode credentials (typically
-something like "you@gmail.com" "w4e4sdg")
-
-### Build System Utilities
-
-These utilities are used in the build process. They are automatically
-included in the build. The links are for reference only.
-
-[Google Upload](http://code.google.com/p/maven-gcu-plugin/wiki/Usage)
-
-[Jar Bundler](http://www.informagen.com/JarBundler/)
-
-[Create DMG Script](http://www.yoursway.com/free/#createdmg)
-

docs/Retired/cardscripting.md

@@ -1,73 +0,0 @@
-What follows is a rough start of an API document for cardscripts.
-
-| Property | Description
-| - | -
-|`A`|Ability
-|`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
-|`K`|Keyword
-|`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"
-|`Oracle`|Oracle text
-|`PT`|Power and toughness
-|`R`|Replacement effect
-|`S`|Static ability
-|`SVar`|String variable. Used throughout scripting in a handful of different ways.
-|`T`|Triggered ability
-|`Text`|Text on card
-|`Types`|Card types and subtypes<br /><br />Include all card types and subtypes, separated by spaces.<br /><br />Example:<br />* `Types:Enchantment Artifact Creature Golem` for a card that reads Enchantment Artifact Creature -- Golem
-
-** Parameters for abilities and variables and known accepted values **
-
-(incomplete list):
-
-* `AB$`: Ability
-* `Ability$`: Ability
-* `ActiveZones$`: Zone
-* `Affected$`: Card
-* `AffectedZone$`: Zone
-* `ChangeNum$`: Integer
-* `ChangeValid$`: CardType
-* `ColorOrType$`: `Type`
-* `Cost$`: Cost
-* `Count$`: `xPaid`
-* `DB$`: DB
-* `Defined$`: Player, Card
-* `Description$`: Text
-* `Destination$`: Zone
-* `DestinationZone$`: Zone
-* `DigNum$`: Integer
-* `Duration$`: UntilYourNextTurn
-* `Event$`: Event
-* `Execute$`: DB
-* `Hidden$`: boolean
-* `KW$`: Keyword
-* `LifeAmount$`: Integer
-* `MayPlay$: boolean
-* `Mode$`: Mode
-* `Name$`: Text
-* `NotCause$`: Ability
-* `NumAtt$`: `+1`
-* `NumCards$`: Integer
-* `Optional$`: boolean
-* `Origin$`: Zone
-* `Produced$`: ManaType
-* `References$`: SVar
-* `ReflectProperty$`: Property
-* `ReplaceWith$`: Text
-* `SP$`: Spell
-* `SpellDescription$`: Text
-* `StackDescription$`: Text
-* `Static$`: boolean
-* `SVars$`: SVar
-* `TargetMax$`: Integer
-* `TargetMin$`: Integer
-* `TargetPrompt$`: Text
-* `TriggerDescription$`: Text
-* `TriggeredCard$`: Property
-* `Triggers$`: Mode
-* `TriggerZones$`: Zone
-* `Valid$`: `Triggered`
-* `ValidCard$`: Card
-* `ValidTgts$`: Player, CardType

docs/Retired/images.md

@@ -1,5 +0,0 @@
-Forge can work with card images of your choice.
-
-The naming convention is as follows:
-
-If you have an older Android device for increased performance or to save bandwidth it might be a good idea to use lower resolution images instead: https://www.slightlymagic.net/forum/viewtopic.php?f=15&t=29104

docs/Skins.md

@@ -0,0 +1,4 @@
+Download more skins here:
+https://github.com/Card-Forge/forge-extras/releases/tag/themes
+
+[Skin Template + Atlas file](https://github.com/user-attachments/files/23420566/forge_sprite_icons_template.zip)

docs/Steam-Deck-and-Bazzite-Install.md

@@ -1,10 +1,8 @@
-# SteamDeck and Bazzite Support
-
 _This instruction was written using Bazzite, however should be similar enough for SteamOS._
 
 In order to support the SteamDeck "natively" for full Forge Desktop mode, we would likely need to have a flatpack installer for the best user install experience, currently Forge has no intention to have a flatpack. The current **best** and recommended way to have Forge on your SteamDeck is to install and run the Android APK version in Waydroid Android Container.
 
-* You will need to have installed Waydroid first, this reddit post may work for you; https://www.reddit.com/r/SteamDeck/comments/1ay7ev8/how_to_install_waydroid_android_on_your_steam_deck/
+* You will need to have installed Waydroid first, this reddit post may work for you: https://www.reddit.com/r/SteamDeck/comments/1ay7ev8/how_to_install_waydroid_android_on_your_steam_deck/
 
 ## Installing Forge Android in Waydroid (Recommended Method)
 Once you've installed Waydroid, you can follow the same steps you would in any Android device.

docs/Themes.md

@@ -1,3 +0,0 @@
-This page is a placeholder for Theme creation information.
-
-I'm working on creating an atlas data file for the skin sprite sheets. I'll separate this into 3 sections; Skins, Music and Sounds, and Card Images.

docs/User-Guide.md

@@ -1,116 +1,196 @@
 # Downloads
-* **Snapshots**;
-  * READ THESE NOTES BEFORE DOWNLOADING SNAPSHOTS:
-    * **Please use snapshots for Adventure Mode!**
-    * May contain more bugs, bug fixes, **definitely gets newest cards faster** and newer features.
-    * These are **NOW** automatically released daily.
-    * If the snapshot isn't in the location below, it's because its in the middle of uploading a new snapshot. Come back later to grab it.
-  * [_**CLICK HERE FOR DOWNLOAD LINKS - Forge SNAPSHOT Version (DESKTOP/ANDROID)**_](https://github.com/Card-Forge/forge/releases/tag/daily-snapshots)
-    * For desktop, grab the installer file that ends in .jar
-    * For android, grab the android file that ends in .apk  
-* **Android Installation Guide**
-  * Quick Guide for installing Android Snapshots: <br />
 
+## Snapshots
 
-https://github.com/user-attachments/assets/7a0c7bb8-7cf9-4800-8091-bcc30ff2f4d8
+* Snapshots are automated daily builds of the source code.
+* They contain the latest bug fixes, features and cards.
+* If the snapshot isn't in the location below, it's because its in the middle of uploading a new snapshot - come back later to grab it.
 
+[***CLICK HERE FOR DOWNLOAD LINKS - Forge SNAPSHOT Version (DESKTOP/ANDROID)***](https://github.com/Card-Forge/forge/releases/tag/daily-snapshots)
 
+* For desktop, grab the installer file that ends in .jar
+* For android, grab the android file that ends in .apk
+  &dash; Watch the screen recording if one of following steps isn't clear for you
 
-* **Releases**;
+<https://github.com/user-attachments/assets/7a0c7bb8-7cf9-4800-8091-bcc30ff2f4d8>
-  * READ THESE NOTES BEFORE DOWNLOADING RELEASES: 
-    - "Releases" are really intended where "99% cards implemented are working and stable."
-    - If you are looking for newly spoiled cards as soon as possible, grab the snapshot instead.
-    - The current release mechanism is failing unexpectedly for Android. So just stick with snapshots for Android users. 
-  * [_**CLICK HERE FOR DOWNLOAD LINKS - RELEASE DESKTOP**_](https://github.com/Card-Forge/forge/releases/latest)
-    - Grab the installer file that ends in .jar
 
+## Releases
 
-# Java Requirement
+* "Releases" are really intended where "99% cards implemented are working and stable".
+* **They are NOT bug-free.** They are not updated after they're built, meaning you need to wait for the next release if you encounter a bug, or use the SNAPSHOT version instead.
+* If you are looking for newly spoiled cards as soon as possible, grab the SNAPSHOT version instead.
+* The current release mechanism is failing unexpectedly for Android. So just stick with snapshots for Android users.
+
+[***CLICK HERE FOR DOWNLOAD LINKS - RELEASE DESKTOP***](https://github.com/Card-Forge/forge/releases/latest)
+
+* Grab the installer file that ends in .jar
+
+# System Requirements
 
 **Forge Requires Java** to run, please make sure you have Java installed on your machine prior to attempting to run.
 
-* **Java 17** is required as minimum version and can be acquired through the Standard Edition Development Kit (JDK) or the OpenJDK. Continued development provides new features in those editions, therefore you need the Java Development Kit to have those newer editions;
+* **Java 17** is required as minimum version and can be acquired through the Standard Edition Development Kit (JDK) or the OpenJDK. Continued development provides new features in those editions, therefore you need the Java Development Kit to have those newer editions:
-  - Download - [https://jdk.java.net/](https://jdk.java.net/)
+  * Download - [https://jdk.java.net/](https://jdk.java.net/)
-  - Source Code - [https://github.com/openjdk/jdk/](https://github.com/openjdk/jdk/)
+  * Source Code - [https://github.com/openjdk/jdk/](https://github.com/openjdk/jdk/)
 
 Most people who have problems setting up Forge, do not have Java setup properly. If you are having trouble, open your terminal/command line and run `java --version`. That number should be 17 or higher.
 
+The memory requirements for Forge have fluctuated over time. The default
+setting on your computer for the Java heap space may not be enough to
+prevent the above problems. If you launch Forge by double-clicking the
+jar files directly you could eventually receive a **java heap space
+error**.
+
+We have created several scripts that will launch Forge with a greater
+allotment of system resources. (We do this by passing `-Xmx1024m` as
+an argument to the Java VM.)
+
+If you plan to eventually download all card images make sure you have several gigabytes of free drive space.
+
 # Install and Run
 
-Forge requires Java to run. 
+> Warning: Do **NOT** owerwrite an existing installation. Always unpack/install the package in a new folder to avoid problems!
 
-_**Download and unpack /install the package to their own new folder!**_
+## Install Wizard (jar)
 
-### Install Wizard (jar)
 * Run/Double click "**forge-installer**-VERSION.jar" where VERSION is the current release version and click next until the Target Path window appears. If double clicking the .jar file doesn't load the main interface you can run it via terminal/command line ```java -jar FILENAME.jar``` where FILENAME is the name of the installer.
 
-* Browse to your preferred install directory (create a new directory for clean installation) and click next until installation starts.
+* Browse to your preferred install directory and click next until installation starts.
 
 ![image](https://github.com/Card-Forge/forge/assets/9781539/b7575f49-f6b3-4933-a15f-726314547c4f)
 
 * After the installation finishes, close the installer. Run the executable forge|forge-adventure (.exe/.sh/.cmd)
 
-### Manual Extraction (tar.bz2)
+### What if double-clicking doesn’t work?
 
-* **Desktop Windows**:
+Sometimes double-clicking will open the jar file in a different program.
-  * Unpack "forge...tar.**bz2**" with any unpacking/unzipping app (e.g. 7-zip, winrar, etc) 
+In Windows, you may need to right-click and open the properties to change the launching program to Java.
-    * You'll end up with "forge...**tar**".
+This might be different in OSX or Linux systems (file permission related).
-  * Unpack that ".tar" file once more into its own folder. 
+
-  * Run Forge app/exe
+## Manual Extraction (tar.bz2)
-* **Desktop Linux/Mac**:
+
-  * Unpack "forge...**tar.bz2**" with any unpacking app. (Check your package repository, or app store.)
+### Desktop Windows
+
+* Unpack "forge...*tar.bz2*" with any unpacking/unzipping app (e.g. 7-zip, winrar, etc)
+  * You'll end up with "forge...*tar*".
+* Unpack that ".tar" file once more into its own folder.
+* Run Forge app/exe
+
+### Desktop Linux/Mac
+
+* Unpack "forge...*tar.bz2*" with any unpacking app. (Check your package repository, or app store.)
   * You'll probably end up with just a folder, and fully extracted.
-    * If you do end up with a ".tar" file, unpack that file also into it's own folder.
+  * If you do end up with a ".tar" file, unpack that file also into its own folder.
-  * Run Forge script; 
+* Run Forge script:
   * Linux: Run the ".sh" file in a terminal (double clicking might work.)
   * MacOS/OSX: Run the ".command" file by double clicking in Finder, or run from the terminal.
     * If the command file doesn't appear to do anything, you'll need to [modify the permissions to be executable.](https://support.apple.com/guide/terminal/make-a-file-executable-apdd100908f-06b3-4e63-8a87-32e71241bab4/mac) (This is a temporary bug in the build process.)
     * Additionally OSX needs to have a JRE AND a JDK installed because reasons.
-* **Android**:
-  * Sideload/Install "forge...apk"
-  * Run Forge
 
-## Play Adventure Mode on Desktop
+### Android
+
+* Sideload/Install "forge...apk"
+* Run Forge
+
+# User data migration
+There are three defined user data directories: userDir, cacheDir, and cardPicsDir, and their locations depend on the standard paths for your operating system:
+
+    Windows:
+        userDir=%APPDATA%/Forge/
+        cacheDir=%LOCALAPPDATA%/Forge/Cache/ (or %APPDATA%/Forge/Cache/ for Windows versions before the local/roaming directory split)
+    OSX:
+        userDir=$HOME/Library/Application Support/Forge/
+        cacheDir=$HOME/Library/Caches/Forge/
+    Linux:
+        userDir=$HOME/.forge/
+        cacheDir=$HOME/.cache/forge/
+
+The appdata directory is hidden by default in Windows 7 and above versions. Open a Windows Explorer window (or double-click on My Computer) and in the address field type "%appdata%/forge/" (without the quotes).
+
+cardPicsDir is defined as <cacheDir>/pics/cards/ by default.  If you wish to use a non-default directory, please see the forge.profile.properties.example file located in the Forge installation directory root.  You can use this file to, for example, share the card pics directory with another program, such as Magic Workstation.
+
+If you are using the Mac OS X version of Forge then you will find the forge.profile.properties.example file by right clicking or control clicking on the Forge.app icon. Select "Show Package Contents" from the contextual menu. A Finder window will open and will display a folder named Contents. Navigate to the folder:
+/Contents/Resources/Java/
+and you will find the file.
+
+## Import Data
+If you have a directory full of deck files, you can use the Import Data dialog to copy or move them to the appropriate directory. The dialog gives you a full listing of all file copy/move operations, so you can see what will happen before you click 'Start Import'.
+
+# Accessibility
+We know some people are colorblind and may not be able to differentiate between colors of the default theme. Forge does have access to other [Skins](Skins.md), which use other color palettes that might be more suitable for you.
+
+# Play Adventure Mode on Desktop
 
 * Run the Adventure Mode EXE or Script in the Folder you extracted.
 * The game will start with an option for Adventure or Classic Mobile UI.
 * Android/Mobile builds are built as the Adventure Mode or Mobile UI and nothing special is needed.
-  - If adventure mode option does not show up;
+  * If adventure mode option does not show up;
-    - check you're up to date with your version.
+    * check you're up to date with your version.
-    - check in the settings that the "Selector Mode" is set to `Default`
+    * check in the settings that the "Selector Mode" is set to `Default`
 
-# System Requirements and Historic Details
+# Gameplay
 
-Since Forge is written in Java, it is compatible on any Operating System
+## Targeting Arrows
-that can run the Java Runtime Environment. Forge requires
+When hovering over items on the stack, arrows will be displayed between that item and all of its targets (both cards and players).
-Java 17 (Forge is not backwards compatible with older versions of Java).
+The arrow will be red if the spell/ability's activator is an opponent of the target or its controller, and blue if targeting an ally of the target or its controller.
-If you have difficulties with your System not working with Forge, 
-please come to the Discord so we can attempt to help.
-This program works best with a screen resolution of **1280 by 720** or
-better. Forge can now have it's window minimized to **800 by 600**
-pixels but this may make the display area cramped and possibly limit
-your ability to play. (This means Forge may not compatible with some
-netbook computers.)
 
-The memory requirements for Forge have fluctuated over time. The default
+## Card Zoomer
-setting on your computer for the java heap space may not be enough to
+You can gaze at your HQ images in all their glory with just a flick of the mousewheel, holding the middle mouse button down, or holding the left and right mouse buttons down at the same time. This feature will also increase the size of low quality pics up to the size used for high quality pics, but the image will not be very clear.
-prevent the above problems. If you launch Forge by double-clicking the
-file **run-forge.jar** you will eventually receive a **java heap space
-error**. The name of the forge jar file has changed as part of our new
-Maven based build and release system. The name format now used is:
 
-**forge-**{version number}**-jar-with-dependencies.jar**
+Instructions:
+- Works on any card image in the Deck Editor or Duel screen.
+- Move your mouse over the card you want to zoom and mouse-wheel forward.
+- Mouse-wheel back, mouse click or pressing ESC closes the zoomed image.
 
-We have created several scripts that will launch Forge with a greater
+Split cards (name contains "//") are rotated 90 degrees for easier viewing.
-allotment of system resources. (We do this by passing **-Xmx1024m** as
-an argument to the Java VM.) People using Windows OS should double click
-the **forge.exe** file. People using Apple's Mac OS X should use the Mac
-OS version and double click the **forge.command** file. People using one of the
-other \*nix OS should double click the **forge.sh** file.
 
-# What if double-clicking doesn’t work?
+If a card is a flip or double-sided card then you can easily view the alternate image using flick wheel forward or tap CTRL key.
 
-Sometimes double-clicking will open the jar file in a different program.
+The standard flip graphic (the two rotated arrows) is displayed if the card can be flipped or transformed.
-In Windows, you may need to right-click and open the properties to
+
-change the launching program to Java. This might be different in OSX or
+Forge supports showing XLHQ (extra large high quality) card pictures when zooming in on a card if these pictures are available. Forge will look for XLHQ card art in the "XLHQ" subfolder of the "pics/cards" folder in Forge cache. XLHQ pictures should have the ".xlhq.jpg" extension instead of the ".full.jpg" one (CCGHQ XLHQ releases comply with this naming scheme).  
-Linux systems (file permission related).
+Please note that XLHQ versions of cards are *only* showed in the zoom view, regular card pictures are still used (LQ/HQ, depending on what you're using) on the battlefield and elsewhere in the game because XLHQ art is significantly more taxing in memory consumption  (and in addition to that, XLHQ card borders are not cropped the way Forge expects them in order to show them properly on the battlefield anyway).
+
+XLHQ tokens are also supported, but the naming scheme for them is a little different - they are looked up in "pics/tokens/XLHQ" and have their ordinary names.
+
+## Easier creature type selection
+When prompted to select a creature type for a card like *Obelisk of Urd*, creature types present in your deck will appear on top, sorted from most to least frequent, followed by all other creature types.  
+This should make it so, more often than not, you can just accept the dialog without searching.
+
+## Auto-Target
+When playing spells and abilities with the text "target opponent", if you only have one opponent, you will no longer be asked to choose the opponent to target.  
+When triggered abilities have only one valid target, that target will now be auto-selected.
+
+## Auto-Pay
+When paying mana costs, you can press Enter/Spacebar or click the Auto button in the Prompt to automatically pay the mana cost using available mana sources if possible.
+- The button will be disabled if you cannot pay the mana cost at that time, in which case Enter/Spacebar will cancel the spell/ability instead.
+- Uses the same logic the AI uses to pay mana costs. This means it will try to use mana in your pool before mana sources in play, using colorless mana to pay the colorless part of the cost if any is available.
+- You can still manually pay the cost by clicking mana sources in play (e.g. lands) or clicking symbols in your mana pool, which might be a good idea if you want to save specific mana sources for a later play that turn.
+- you'll still be prompted when paying Sunburst or cards that care what colors are spent to cast it (ex. Firespout).
+
+## Auto-Yield
+- When a spell or an ability appears on the stack and it says "(OPTIONAL)" you can right-click it to decide if you want to always accept or to decline it.
+
+  It is possible to specify the granularity level for auto-yields: the difference is that, for example, when choosing per ability if you auto-yield to Hellrider's triggered ability once, all triggers from other Hellrider cards will be automatically yielded to as well. When choosing per card, you will need to auto-yield to each Hellrider separately.
+
+  Note that in when auto-yielding per ability, yields will NOT be automatically cleared between games in a match, which should speed the game up. When auto-yielding per card, yields WILL be automatically cleared between games because they are dependent on card IDs which change from game to game, thus you will need to auto-yield to each card again in each game of the match.
+
+- Pressing "End Turn" skips your attack phase and doesn't get cancelled automatically if a spell or ability is put on the stack. You'll still be given a chance to declare blockers if your opponent attacks, but after that the rest of your opponent's turn will then progress without you receiving priority.
+
+  To alleviate pressing this accidentally, as long as you're passing this way, you'll be able to press Escape or the Cancel button to be given the chance to act again. Phases with stops and spells/abilities resolving will be given a slight delay to allow you to see what's going on.
+
+## Shift Key helper
+* When you mouse over a flip, transform or Morph (controlled by you) card in battlefield, hold SHIFT to see other state of that card at the side panel that displays card picture and details.
+* Hold SHIFT when clicking on mana pool icons to use as much of that mana type as possible towards the cost.
+* Tap all lands in a stack using Shift+click on any in the stack.
+* Attack with all creatures in a stack using Shift+click on any in the stack.
+
+## Full Control
+Right click/long tap on your player avatar:  
+This feature lets you skip different helpers that streamline gameplay by avoiding somewhat annoying GUI interactions and instead use AI logic to make reasonable decisions for beginners. Useful for certain corner cases or if you want to challenge yourself with the Comprehensive Rules:  
+e.g. the opposite cost order is needed if activating an animated "Halo Fountain" that's also tapped.
+
+## Repeatable Sequences (Macros)
+A feature for advanced users: during a match, you can use the default shortcut shift-R to specify a sequence of actions (mouse clicks, essentially, in the desktop paradigm). Type the IDs of cards/players you'd like to interact with, in order. Then the default shortcut @ (shift-2) will execute your sequence, one "click" at a time, repeating when it reaches the end. This is useful for executing repeated combos, such as sacrificing a recurring creature to Goblin Bombardment. You can see the IDs of cards by turning them on under "Card Overlays" in the "Game" menu.
+
+The macro will dutifully execute your click sequence without regard to changes in game state (so if an opponent kills your specified creature mid-macro, and you continue to execute it, you will be essentially clicking on the creature in the graveyard, which may or may not be what you want).

docs/_sidebar.md

@@ -1,4 +1,5 @@
 ### [Forge Wiki Home](Home.md)
+
 - [User Guide](User-Guide.md)
   - [FAQ](Frequently-Asked-Questions.md)
   - [SteamDeck/Bazzite](Steam-Deck-and-Bazzite-Install.md)
@@ -6,60 +7,60 @@
   - [Network Play](network-play.md)
     - [Network FAQ](Network-FAQ.md)
     - [Network Extra](Networking-Extras.md)
+  - [Advanced search](Advanced-Search.md)
 
-- [Adventure Mode](Adventure-Mode.md)
+- [Adventure Mode](Adventure/Adventure-Mode.md)
 
     - Gameplay Guide
+      - [Getting Started](Adventure/Gameplay-Guide.md)
+      - [Different Planes](Adventure/Different-Planes.md)
+      - [Currency](Adventure/Currency.md)
+      - [Deck Building Tips](Adventure/Deck-Building-Tips.md)
+      - [Towns & Capitals](Adventure/Towns-&-Capitals.md)
+      - [Dungeons](Adventure/Dungeons.md)
+      - [Equipment & Items](Adventure/Equipments-and-Items.md)
+      - [Controller Support](Adventure/GAMEPAD.md)
+      - [Console & Cheats](Adventure/Console-and-Cheats.md)
 
-      - [Getting Started](Gameplay-Guide.md)
+  - [Modding & content creation](Adventure/Modding.md)
-      - [Different Planes](Different-Planes.md)
+    - [Create Enemies](Adventure/Create-Enemies.md)
-      - [Currency](Currency.md)
+    - [Create Rewards](Adventure/Create-Rewards.md)
-      - [Deck Building Tips](Deck-Building-Tips.md)
+    - [Create Maps](Adventure/Create-new-Maps.md)
-      - [Towns & Capitals](Towns-&-Capitals.md)
+    - [Configure Planes](Adventure/Configure-Planes.md)
-      - [Dungeons](Dungeons.md)
+    - [Configure Starting Sets](Adventure/Configure-Sets.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)
-
-    - [Create Enemies](Create-Enemies.md)
-    - [Create Rewards](Create-Rewards.md)
-    - [Create Maps](Create-new-Maps.md)
-    - [Configure Planes](Configure-Planes.md)
-    - [Configure Starting Sets](Configure-Sets.md)
 
   - Tutorials
-    - [Tutorial 1, Create your first Plane](Tutorial-1-Create-your-First-Plane.md)
+    - [Tutorial 1, Create your first Plane](Adventure/Tutorial-1-Create-your-First-Plane.md)
-    - [Tutorial 2, A New Look (creating your first map.)](Tutorial-2-A-New-Look.md)
+    - [Tutorial 2, A New Look (creating your first map.)](Adventure/Tutorial-2-A-New-Look.md)
-    - [Tutorial 3, Configuration (Configuring your Plane)](Tutorial-3-Configuration.md)
+    - [Tutorial 3, Configuration (Configuring your Plane)](Adventure/Tutorial-3-Configuration.md)
-
 
 - [Card Scripting API](Card-scripting-API/Card-scripting-API.md)
   - [Ability effects](Card-scripting-API/AbilityFactory.md)
   - [Triggers](Card-scripting-API/Triggers.md)
   - [Replacements](Card-scripting-API/Replacements.md)
-  - Statics
+  - [Statics](Card-scripting-API/Statics.md)
   - [Costs](Card-scripting-API/Costs.md)
   - [Affected / Targets](Card-scripting-API/Targeting.md)
   - [Restrictions / Conditions](Card-scripting-API/Restrictions.md)
-  - [Guide: Creating a Custom Card](Card-scripting-API/Creating-a-Custom-Card.md)
+  - [Tutorial: creating a custom card](Card-scripting-API/Creating-a-Custom-Card.md)
 
-- [Development]((SM-autoconverted)-how-to-get-started-developing-forge.md)
+- Development
   - [IntelliJ Setup](Development/IntelliJ-setup/IntelliJ-setup.md)
-  - [Snapshots and Releases](Snapshots-and-Releases.md)
+  - [Snapshots & Releases](Development/Snapshots-and-Releases.md)
-  - [Android Builds](Development/android-builds.md)
+  - [Android Builds](Development/Android-Builds.md)
+  - [Dev Mode](Development/DevMode.md)
   - [Ownership](Development/ownership.md)
   - [Docker Container](docker-setup.md)
 
-- [Customization and Themes.md](Themes.md)
+- Customization & Themes
-  - Skins
+  - [Skins](Skins.md)
-  - Sounds
+  - [Sounds & Music](Custom-Audio.md)
-  - [Music](Custom-Music.md)
   - [Card Images](Card-Images.md)
   - [File Formats](File-Formats.md)
-  - [Creating your first custom set](Creating-a-custom-set.md)
+  - [Tutorial: creating your first custom set](Creating-a-custom-Set.md)
+  - [Fantasy Blocks](fantasy-blocks.md)
 
 - [Missing Cards in Forge](Missing-Cards-in-Forge.md)
   - [Un‐cards, Playtest Cards, and Other Funny Cards](Un‐cards,-Playtest-Cards,-and-Other-Funny-Cards.md)
-- [Credit and Thanks](Credit-and-Thanks.md)
+
+- [Credit & Thanks](Credit-and-Thanks.md)

docs/fantasy-blocks.md

@@ -0,0 +1,83 @@
+# How to customize your Forge Sealed Deck game with fantasy blocks
+
+You can define your own dream block for sealed deck games by choosing the exact sets you want to include in the game - and even easily spice up your sealed deck experience with special booster packs that generate cards based on several different sets, the full cardpool or your customized cube.
+
+To do this, you need to modify your "fantasyblocks.txt" file with your text editor of choice. You will find the file in the res/blockdata folder. Notice that there is also a "blocks.txt" file in this folder - it contains the predefined official MtG blocks (better leave it alone). The "fantasyblocks.txt" file currently includes some sample blocks we have built. You can delete them all, replace them with your own blocks, or just add new blocks after them. You can have as many fantasy blocks as you like - just remember to increment the index number every time you add a new one!
+
+When you are finished, just save the fantasyblocks.txt file and relaunch Forge. If have made errors when editing the fantasyblocks.txt file, you may get error messages in your block now and Forge may fail to launch. (If this happens, check your logfile to see what went wrong.)
+
+# What is a block file made of?
+
+A block definition file (fantasyblocks.txt or blocks.txt) contains block definitions that are parsed when the game launches and then used internally when the game is running. One block definition per line. Let's look at a sample line:
+
+`Index:0|Set0:LEA|Name:Alpha|DraftPacks:3|LandSetCode:LEA|SealedPacks:6`
+
+This is the first line in the official blocks.txt file. It contains several parameters and values that are separated with |'s. The format for a parameter value/pair is "Parameter:value". Here's what the parameters mean:
+
+Index: The internal index number of the block. This needs to be unique. When you add a new block (row), just check the last number and add 1.
+Set0: This is a 3-letter code for MtG set. "LEA" value means that one of the sets included in this block is Alpha. A block can contain as many as 9 different sets (given as parameters Set0:xxx|Set1:yyy| etc. until Set8:zzz). Hint: If you don't know the 3-letter code for a set you want, you can look it up in the setdata.txt file in the same directory (res/blockdata).
+Name: This is the name that is displayed in the block selection dialog box.
+DraftPacks: How many boosters you get when Drafting this block.
+LandSetCode: Which edition basic lands are used when playing Draft/Sealed Deck games with this block. Again, if necessary, you can look up the set code in the setdata.txt file. Note that if your block contains a core set, it is usually a good idea to use that edition's code here or may get basic lands from different editions and they will not show up properly in the deck editor.
+SealedPacks: How many boosters you get when playing Sealed Deck games with this block. Note that the current version of Forge supports 4-9 booster pack SD games but if you give the players (for example) only 4 booster packs and your block contains more than four sets, you will be able to choose from the first four sets only. Thus, this number should always be at least as great as the number of different sets in the block if you want to be able to use them all. But it can, of course, be higher than number of sets in a sealed deck game. In this particular example, all players get 6 booster packs but, since the only set included in the block is Alpha, all 6 will be Alpha boosters.
+
+Let's try another fairly straightforward example, this time from fantasyblocks.txt:
+
+`Index:25|Set0:2ED|Set1:ATQ|Set2:ARN|Set3:DRK|Set4:LEG|Set5:FEM|Set6:ICE|Set7:HML|Set8:ALL|Name:(9) MtG Encyclopedia|DraftPacks:3|LandSetCode:2ED|SealedPacks:9`
+
+Yes: this is fantasy block #25 (actually 26th block, since the first block is #0, not #1). It contains 9 different sets, basically everything from the birth of the game to Alliances. Hence, the name "MtG Encyclopedia" - theoretically, any card from the old printed book Magic the Gathering: Official Encyclopedia ("godbook") would be included here (except the promo cards). (The "(9)" in front of the name is simply a clue to give you an idea how many sets there are in the block.) Unlimited lands are used here. Draft players get only 3 different booster packs, so this block is poorly suited to Draft games (they would only get Unlimited, Arabian Nights and Antiquities boosters from this blocks). In Sealed Deck games, however, all you would get 9 different boosters if you select this block - and have the option of selecting starter packs instead of booster packs for Unlimited and/or Ice Age.
+
+But the fun doesn't stop here...
+
+# MetaSets: What are they, why should I care, and how do I use them?
+
+Even 9 different sets may seem limiting sometimes. Or maybe you would have booster based your special, customized fantasy card list? MetaSets are have been added to allow you do exactly that: create a special booster pack that wouldn't be possible in real life.
+
+Here is a MetaSet sample from fantasyblocks.txt:
+
+`Index:26|Meta1:CUBE/ArabianExtended/ARAB|Meta2:META/ISD,DKA,AVR,M13/M13-ISD|Meta3:FULL/*/*|Name:(3) Metaset Sample|DraftPacks:3|LandSetCode:2ED|SealedPacks:6`
+
+To define a MetaSet, you use the Meta0...Meta8 parameters, just like you would use the Set0...Set8 parameters. (Notice that, illogically, here I have accidentally started with Meta1 and not Meta0, shame on me! But the number doesn't really matter that much, it's the amount of different sets/MetaSets in a block that matters.)
+
+The main difference lies in the values that a Meta(x) parameter can have. First we have:
+
+`Meta1:CUBE/ArabianExtended/ARAB`
+
+A MetaSet always needs 3 values, separated with slashes. The first value is the MetaSet type, in this case, a CUBE. The first value must be CUBE, FULL, or META. Any other value will cause an error.
+The other two values are data and display name (they behave differently for the different MetaSet types). For a cube, the second value must be the cube name. If Forge cannot find this cube (defined in res/sealed/), it will give you an error when you try to choose this block. The last name is simply a visual name that is displayed when you choose the set distribution for you sealed deck game. For a cube, a "*C:" prefix is always automatically appended.
+
+Next we have:
+
+`Meta2:META/ISD,DKA,AVR,M13/M13-ISD`
+
+This is a genuine 'meta' MetaSet - i.e., a set of sets, a block within a block. The first value is the type (META) and the last value is the display name (M13-ISD), just like in the cube example. For meta-type MetaSets, a "*B:" prefix is added in indicate that it is really a sub-block within the block.
+The second value is the interesting part. It is a comma-separated list of sets that are combined to make the cardpool for this booster, in this case the whole Innistrad block and M13 core set. (Again, look up the codes in setdata.txt if you don't know them.) And here's the cool part: you can list any number of sets you like in the comma-separated list!
+
+The final MetaSet in this sample block is:
+
+`Meta3:FULL/*/*`
+
+This one is pretty straightforward. It simply indicates that the boosters for this 'set' are based on the full cardpool available in Forge. While values 2 and 3 must be supplied (otherwise the line won't parse correctly), they are not important for the full cardpool MetaSet type. Value 2 is not used at all, and its display name will always be "*FULL".
+
+So, effectively, the above "Metaset Sample" block can generate boosters based on the "Arabian Extended" cube, a sub-block consisting of the Innistrad block + M13, and/or full cardpool.
+
+Finally, note that you can mix-and-match regular sets and MetaSets in a block - just be sure to count both when you set the SealedPacks parameter. For example, if your block contains regular sets Set0, Set1, and Set2 (3 sets), and MetaSets Meta1 and Meta2, the value will need to be at least 5. (The regular 6 would work nicely, too.)
+
+# MetaSets: The Next Level
+
+`Meta-Choose(S(RTR Prerelease Azorius Guild)Azorius guild;S(RTR Prerelease Selesnya Guild)Selesnya guild;S(RTR Prerelease Izzet Guild)Izzet guild;S(RTR Prerelease Rakdos Guild)Rakdos guild;S(RTR Prerelease Golgari Guild)Golgari guild)Guild`
+
+Forge has these MetaSet types:
+
+* Full("F") - All cards
+* Cube("C") - Cube
+* JoinedSet("J") - Joined set.. ex: J(ICE ALL HML CSP)Ice_Age_Block_Extended
+* Choose("Select") - Choose from a list of nested metasets
+* Random("Any") - Randomly select one of nested metasets
+* Combo("All") - Combined booster means all nested sets will be selected
+* Booster("B") - a common booster, associated with card edition... ex: B(DKA)
+* SpecialBooster("S") - Special booster defined to support special events, that is not linked to any edition, see note below.
+* Pack("T") - Tournament pack or Starter, valid only for editions where it was avaliable
+
+* You may use either name or a shorter alias to denote a meta set. They are case insensitive now
+* There is a new meta type "SpecialBooster" (added during 1.3.16 development), it's used to refer to special boosters declared in res\blockdata\boosters-special.txt . These boosters are used to hold RTR block sealed events, and may be used for MBS faction booster generation (if anyone would like to build a themed sealed game)

forge-ai/src/main/java/forge/ai/AiController.java

@@ -810,13 +810,13 @@ public class AiController {
         return reserveManaSources(sa, phaseType, enemy, true, null);
     }
     public boolean reserveManaSources(SpellAbility sa, PhaseType phaseType, boolean enemy, boolean forNextSpell, SpellAbility exceptForThisSa) {
-        ManaCostBeingPaid cost = ComputerUtilMana.calculateManaCost(sa.getPayCosts(), sa, true, 0, false);
+        ManaCostBeingPaid cost = ComputerUtilMana.calculateManaCost(sa.getPayCosts(), sa, player, true, 0, false);
         CardCollection manaSources = ComputerUtilMana.getManaSourcesToPayCost(cost, sa, player);
 
         // used for chained spells where two spells need to be cast in succession
         if (exceptForThisSa != null) {
             manaSources.removeAll(ComputerUtilMana.getManaSourcesToPayCost(
-                    ComputerUtilMana.calculateManaCost(exceptForThisSa.getPayCosts(), exceptForThisSa, true, 0, false),
+                    ComputerUtilMana.calculateManaCost(exceptForThisSa.getPayCosts(), exceptForThisSa, player, true, 0, false),
                     exceptForThisSa, player));
         }
 
@@ -1726,6 +1726,7 @@ public class AiController {
             return future.get(game.getAITimeout(), TimeUnit.SECONDS);
         } catch (InterruptedException | ExecutionException | TimeoutException e) {
             try {
+                e.printStackTrace();
                 t.stop();
             } catch (UnsupportedOperationException ex) {
                 // Android and Java 20 dropped support to stop so sadly thread will keep running

forge-ai/src/main/java/forge/ai/ComputerUtil.java

@@ -938,10 +938,9 @@ public class ComputerUtil {
             }
         }
 
-        for (int ip = 0; ip < 6; ip++) { // priority 0 is the lowest, priority 5 the highest
+        for (int prio = 6; prio > 0; prio--) {
-            final int priority = 6 - ip;
             for (Card card : remaining) {
-                if (card.hasSVar("SacMe") && Integer.parseInt(card.getSVar("SacMe")) == priority) {
+                if (card.hasSVar("SacMe") && Integer.parseInt(card.getSVar("SacMe")) == prio) {
                     return card;
                 }
             }
@@ -1153,7 +1152,7 @@ public class ComputerUtil {
             if (card.getSVar("PlayMain1").equals("ALWAYS") || sa.getPayCosts().hasNoManaCost()) {
                 return true;
             } else if (card.getSVar("PlayMain1").equals("OPPONENTCREATURES")) {
-                //Only play these main1 when the opponent has creatures (stealing and giving them haste)
+                // Only play these main1 when the opponent has creatures (stealing and giving them haste)
                 if (!ai.getOpponents().getCreaturesInPlay().isEmpty()) {
                     return true;
                 }
@@ -1285,20 +1284,6 @@ public class ComputerUtil {
             }
         } // AntiBuffedBy
 
-        // Plane cards that give Haste (e.g. Sokenzan)
-        if (ai.getGame().getRules().hasAppliedVariant(GameType.Planechase)) {
-            for (Card c : ai.getGame().getActivePlanes()) {
-                for (StaticAbility s : c.getStaticAbilities()) {
-                    if (s.hasParam("AddKeyword")
-                            && s.getParam("AddKeyword").contains("Haste")
-                            && "Creature".equals(s.getParam("Affected"))
-                            && card.isCreature()) {
-                        return true;
-                    }
-                }
-            }
-        }
-
         final CardCollectionView vengevines = ai.getCardsIn(ZoneType.Graveyard, "Vengevine");
         if (!vengevines.isEmpty()) {
             final CardCollectionView creatures = ai.getCardsIn(ZoneType.Hand);
@@ -1337,8 +1322,8 @@ public class ComputerUtil {
             }
         }
 
-        final CardCollectionView buffed = ai.getCardsIn(ZoneType.Battlefield);
         boolean checkThreshold = sa.isSpell() && !ai.hasThreshold() && !source.isInZone(ZoneType.Graveyard);
+        final CardCollectionView buffed = ai.getCardsIn(ZoneType.Battlefield);
         for (Card buffedCard : buffed) {
             if (buffedCard.hasSVar("BuffedBy")) {
                 final String buffedby = buffedCard.getSVar("BuffedBy");
@@ -1458,16 +1443,15 @@ public class ComputerUtil {
             for (StaticAbility stAb : c.getStaticAbilities()) {
                 if (stAb.checkMode(StaticAbilityMode.Continuous) && stAb.hasParam("AddKeyword")
                         && stAb.getParam("AddKeyword").contains("Haste")) {
-
                     if (c.isEquipment() && c.getEquipping() == null) {
                         return true;
                     }
 
                     final String affected = stAb.getParam("Affected");
-                    if (affected.contains("Creature.YouCtrl")
+                    if (affected.startsWith("Creature") && (affected.contains("YouCtrl") || !affected.contains("."))) {
-                            || affected.contains("Other+YouCtrl")) {
                         return true;
-                    } else if (affected.contains("Creature.PairedWith") && !c.isPaired()) {
+                    }
+                    if (affected.contains("Creature.PairedWith") && !c.isPaired()) {
                         return true;
                     }
                 }
@@ -1482,8 +1466,7 @@ public class ComputerUtil {
                 }
 
                 final String valid = params.get("ValidCard");
-                if (valid.contains("Creature.YouCtrl")
+                if (valid.contains("Creature.YouCtrl") || valid.contains("Other+YouCtrl") ) {
-                        || valid.contains("Other+YouCtrl") ) {
 
                     final SpellAbility sa = t.getOverridingAbility();
                     if (sa != null && sa.getApi() == ApiType.Pump && sa.hasParam("KW")
@@ -3083,13 +3066,17 @@ public class ComputerUtil {
         return numInHand > 0 || numInDeck >= 3;
     }
 
-    public static CardCollection filterAITgts(SpellAbility sa, Player ai, CardCollection srcList, boolean alwaysStrict) {
+    // this function should be called by most API to give scripters the option of helping AI
+    public static CardCollection filterAITgts(SpellAbility sa, Player ai, CardCollection targetables, boolean alwaysStrict) {
+        // TODO support players
         final Card source = sa.getHostCard();
         if (source == null || !sa.hasParam("AITgts")) {
-            return srcList;
+            return targetables;
         }
 
-        CardCollection list;
+        // TODO randomize the order, just so human can't predict in advance which of two equal cards AI might pick
+
+        CardCollection filtered;
         String aiTgts = sa.getParam("AITgts");
         if (aiTgts.startsWith("BetterThan")) {
             int value = 0;
@@ -3109,15 +3096,28 @@ public class ComputerUtil {
                 value = ComputerUtilCard.evaluateCreature(source);
             }
             final int totalValue = value;
-            list = CardLists.filter(srcList, c -> ComputerUtilCard.evaluateCreature(c) > totalValue + 30);
+            filtered = CardLists.filter(targetables, c -> ComputerUtilCard.evaluateCreature(c) > totalValue + 30);
         } else {
-            list = CardLists.getValidCards(srcList, sa.getParam("AITgts"), sa.getActivatingPlayer(), source, sa);
+            filtered = CardLists.getValidCards(targetables, aiTgts, sa.getActivatingPlayer(), source, sa);
         }
 
-        if (!list.isEmpty() || sa.hasParam("AITgtsStrict") || alwaysStrict) {
+        if (sa.hasParam("AITgtsStrict") || alwaysStrict) {
-            return list;
+            return filtered;
         }
-        return srcList;
+        if (!filtered.isEmpty()) {
+            // try to fill up with other regular targets to increase chance of playing
+            for (Card tgt : targetables) {
+                if (filtered.size() >= sa.getMinTargets()) {
+                    break;
+                }
+                if (filtered.contains(tgt)) {
+                    continue;
+                }
+                filtered.add(tgt);
+            }
+            return filtered;
+        }
+        return targetables;
     }
 
     // Check if AI life is in danger/serious danger based on next expected combat

forge-ai/src/main/java/forge/ai/ComputerUtilAbility.java

@@ -3,6 +3,7 @@ package forge.ai;
 import java.util.Comparator;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Set;
 
 import com.google.common.collect.Lists;
 
@@ -25,6 +26,10 @@ import forge.game.spellability.OptionalCost;
 import forge.game.spellability.OptionalCostValue;
 import forge.game.spellability.SpellAbility;
 import forge.game.spellability.SpellAbilityStackInstance;
+import forge.game.staticability.StaticAbility;
+import forge.game.staticability.StaticAbilityMode;
+import forge.game.trigger.Trigger;
+import forge.game.trigger.TriggerType;
 import forge.game.zone.ZoneType;
 
 public class ComputerUtilAbility {
@@ -366,15 +371,32 @@ public class ComputerUtilAbility {
                     p -= 9;
                 }
                 // move snap-casted spells to front
-                if (source.isInZone(ZoneType.Graveyard)) {
+                if (source.isInZone(ZoneType.Graveyard) && source.mayPlay(sa.getMayPlay()) != null) {
-                    if (sa.getMayPlay() != null && source.mayPlay(sa.getMayPlay()) != null) {
                     p += 50;
                 }
-                }
                 // if the profile specifies it, deprioritize Storm spells in an attempt to build up storm count
                 if (source.hasKeyword(Keyword.STORM) && ai.getController() instanceof PlayerControllerAi) {
                     p -= (((PlayerControllerAi) ai.getController()).getAi().getIntProperty(AiProps.PRIORITY_REDUCTION_FOR_STORM_SPELLS));
                 }
+
+                for (Trigger trig : source.getTriggers()) {
+                    if (!"Battlefield".equals(trig.getParam("TriggerZones"))) {
+                        continue;
+                    }
+                    final TriggerType mode = trig.getMode();
+                    // benefit from Magecraft abilities
+                    if ((mode == TriggerType.SpellCast || mode == TriggerType.SpellCastOrCopy) && "You".equals(sa.getParam("ValidActivatingPlayer"))) {
+                        p += 1;
+                    }
+                }
+
+                for (StaticAbility sta : source.getStaticAbilities()) {
+                    final Set<StaticAbilityMode> mode = sta.getMode();
+                    // reduce cost to enable more plays
+                    if (mode.contains(StaticAbilityMode.ReduceCost) && "You".equals(sta.getParam("Activator"))) {
+                        p += 1;
+                    }
+                }
             }
 
             // use Surge and Prowl costs when able to

forge-ai/src/main/java/forge/ai/ComputerUtilCost.java

@@ -509,16 +509,16 @@ public class ComputerUtilCost {
      *
      * @param sa
      *            a {@link forge.game.spellability.SpellAbility} object.
-     * @param player
+     * @param payer
      *            a {@link forge.game.player.Player} object.
      * @return a boolean.
      */
-    public static boolean canPayCost(final SpellAbility sa, final Player player, final boolean effect) {
+    public static boolean canPayCost(final SpellAbility sa, final Player payer, final boolean effect) {
-        return canPayCost(sa.getPayCosts(), sa, player, effect);
+        return canPayCost(sa.getPayCosts(), sa, payer, effect);
     }
-    public static boolean canPayCost(final Cost cost, final SpellAbility sa, final Player player, final boolean effect) {
+    public static boolean canPayCost(final Cost cost, final SpellAbility sa, final Player payer, final boolean effect) {
         if (sa.getActivatingPlayer() == null) {
-            sa.setActivatingPlayer(player); // complaints on NPE had came before this line was added.
+            sa.setActivatingPlayer(payer); // complaints on NPE had came before this line was added.
         }
 
         // Check for stuff like Nether Void
@@ -527,14 +527,14 @@ public class ComputerUtilCost {
             boolean cannotBeCountered = !sa.isCounterableBy(null);
 
             if (sa instanceof Spell) {
-                for (Card c : player.getGame().getCardsIn(ZoneType.Battlefield)) {
+                for (Card c : payer.getGame().getCardsIn(ZoneType.Battlefield)) {
                     final String snem = c.getSVar("AI_SpellsNeedExtraMana");
                     if (!StringUtils.isBlank(snem)) {
                         if (cannotBeCountered && c.getName().equals("Nether Void")) {
                             continue;
                         }
                         String[] parts = TextUtil.split(snem, ' ');
-                        boolean meetsRestriction = parts.length == 1 || player.isValid(parts[1], c.getController(), c, sa);
+                        boolean meetsRestriction = parts.length == 1 || payer.isValid(parts[1], c.getController(), c, sa);
                         if(!meetsRestriction)
                             continue;
 
@@ -545,7 +545,7 @@ public class ComputerUtilCost {
                         }
                     }
                 }
-                for (Card c : player.getCardsIn(ZoneType.Command)) {
+                for (Card c : payer.getCardsIn(ZoneType.Command)) {
                     if (cannotBeCountered) {
                         continue;
                     }
@@ -567,7 +567,7 @@ public class ComputerUtilCost {
                         if (part.convertAmount() != null && part.convertAmount() == sa.getHostCard().getCurrentLoyalty()) {
                             // refuse to pay if opponent has no creature threats or
                             // 50% chance otherwise
-                            if (player.getOpponents().getCreaturesInPlay().isEmpty()
+                            if (payer.getOpponents().getCreaturesInPlay().isEmpty()
                                     || MyRandom.getRandom().nextFloat() < .5f) {
                                 return false;
                             }
@@ -591,7 +591,7 @@ public class ComputerUtilCost {
                             Cost wardCost = ComputerUtilCard.getTotalWardCost(tgt);
                             // don't use API converter since it might have special part logic not meant for Ward cost
                             SpellAbilityAi topAI = new SpellAbilityAi() {};
-                            if (!topAI.willPayCosts(player, sa, wardCost, sa.getHostCard())) {
+                            if (!topAI.willPayCosts(payer, sa, wardCost, sa.getHostCard())) {
                                 return false;
                             }
                             if (wardCost.hasManaCost()) {
@@ -606,7 +606,7 @@ public class ComputerUtilCost {
             if (sa.getHostCard().hasKeyword(Keyword.CASUALTY)) {
                 for (final CostPart part : cost.getCostParts()) {
                     if (part instanceof CostSacrifice) {
-                        CardCollection valid = CardLists.getValidCards(player.getCardsIn(ZoneType.Battlefield), part.getType().split(";"),
+                        CardCollection valid = CardLists.getValidCards(payer.getCardsIn(ZoneType.Battlefield), part.getType().split(";"),
                                 sa.getActivatingPlayer(), sa.getHostCard(), sa);
                         valid = CardLists.filter(valid, CardPredicates.hasSVar("AIDontSacToCasualty").negate());
                         if (valid.isEmpty()) {
@@ -618,8 +618,8 @@ public class ComputerUtilCost {
         }
 
         // TODO both of these call CostAdjustment.adjust, try to reuse instead
-        return ComputerUtilMana.canPayManaCost(cost, sa, player, extraManaNeeded, effect)
+        return ComputerUtilMana.canPayManaCost(cost, sa, payer, extraManaNeeded, effect)
-                && CostPayment.canPayAdditionalCosts(cost, sa, effect, player);
+                && CostPayment.canPayAdditionalCosts(cost, sa, effect, payer);
     }
 
     public static Set<String> getAvailableManaColors(Player ai, Card additionalLand) {

forge-ai/src/main/java/forge/ai/ComputerUtilMana.java

@@ -69,7 +69,7 @@ public class ComputerUtilMana {
         return payManaCost(cost, sa, ai, false, 0, true, effect);
     }
     private static boolean payManaCost(final Cost cost, final SpellAbility sa, final Player ai, final boolean test, final int extraMana, boolean checkPlayable, final boolean effect) {
-        ManaCostBeingPaid manaCost = calculateManaCost(cost, sa, test, extraMana, effect);
+        ManaCostBeingPaid manaCost = calculateManaCost(cost, sa, ai, test, extraMana, effect);
         return payManaCost(manaCost, sa, ai, test, checkPlayable, effect);
     }
 
@@ -77,7 +77,7 @@ public class ComputerUtilMana {
      * Return the number of colors used for payment for Converge
      */
     public static int getConvergeCount(final SpellAbility sa, final Player ai) {
-        ManaCostBeingPaid cost = calculateManaCost(sa.getPayCosts(), sa, true, 0, false);
+        ManaCostBeingPaid cost = calculateManaCost(sa.getPayCosts(), sa, ai, true, 0, false);
         if (payManaCost(cost, sa, ai, true, true, false)) {
             return cost.getSunburst();
         }
@@ -1291,7 +1291,7 @@ public class ComputerUtilMana {
      * @param extraMana extraMana
      * @return ManaCost
      */
-    public static ManaCostBeingPaid calculateManaCost(final Cost cost, final SpellAbility sa, final boolean test, final int extraMana, final boolean effect) {
+    public static ManaCostBeingPaid calculateManaCost(final Cost cost, final SpellAbility sa, final Player payer, final boolean test, final int extraMana, final boolean effect) {
         Card host = sa.getHostCard();
         Zone castFromBackup = null;
         if (test && sa.isSpell() && !host.isInZone(ZoneType.Stack)) {
@@ -1302,6 +1302,10 @@ public class ComputerUtilMana {
         Cost payCosts;
         if (test) {
             payCosts = CostAdjustment.adjust(cost, sa, effect);
+            // prevent asking Human when only predicting
+            if (!payer.getController().isAI()) {
+                sa.setMaxWaterbend(null);
+            }
         } else {
             // when not testing CostPayment already handled raise
             payCosts = cost;
@@ -1345,9 +1349,7 @@ public class ComputerUtilMana {
             }
         }
 
-        if (!effect) {
+        CostAdjustment.adjust(manaCost, sa, payer, null, test, effect);
-            CostAdjustment.adjust(manaCost, sa, null, test);
-        }
 
         if ("NumTimes".equals(sa.getParam("Announce"))) { // e.g. the Adversary cycle
             ManaCost mkCost = sa.getPayCosts().getTotalMana();
@@ -1773,15 +1775,18 @@ public class ComputerUtilMana {
 
     /**
      * Matches list of creatures to shards in mana cost for convoking.
+     *
      * @param cost      cost of convoked ability
      * @param list      creatures to be evaluated
-     * @param improvise
+     * @param artifacts
+     * @param creatures
      * @return map between creatures and shards to convoke
      */
-    public static Map<Card, ManaCostShard> getConvokeOrImproviseFromList(final ManaCost cost, List<Card> list, boolean improvise) {
+    public static Map<Card, ManaCostShard> getConvokeOrImproviseFromList(final ManaCost cost, List<Card> list, boolean artifacts, boolean creatures) {
         final Map<Card, ManaCostShard> convoke = new HashMap<>();
         Card convoked = null;
-        if (!improvise) {
+        if (creatures && !artifacts) {
+            // Run for convoke but not improvise or waterbending
             for (ManaCostShard toPay : cost) {
                 if (toPay.isSnow() || toPay.isColorless()) {
                     continue;

forge-ai/src/main/java/forge/ai/GameState.java

@@ -963,6 +963,8 @@ public abstract class GameState {
             spellDef = spellDef.substring(0, spellDef.indexOf("->")).trim();
         }
 
+        spellDef = spellDef.replace("^", ":"); // alternate marker for when : is the name of the card
+
         Card c = null;
 
         if (StringUtils.isNumeric(spellDef)) {

forge-ai/src/main/java/forge/ai/PlayerControllerAi.java

@@ -1225,7 +1225,7 @@ public class PlayerControllerAi extends PlayerController {
 
     @Override
     public boolean payCostToPreventEffect(Cost cost, SpellAbility sa, boolean alreadyPaid, FCollectionView<Player> allPayers) {
-        if (SpellApiToAi.Converter.get(sa).willPayUnlessCost(sa, player, cost, alreadyPaid, allPayers)) {
+        if (SpellApiToAi.Converter.get(sa).willPayUnlessCost(player, sa, cost, alreadyPaid, allPayers)) {
             if (!ComputerUtilCost.canPayCost(cost, sa, player, true)) {
                 return false;
             }
@@ -1382,7 +1382,7 @@ public class PlayerControllerAi extends PlayerController {
     }
 
     @Override
-    public Map<Card, ManaCostShard> chooseCardsForConvokeOrImprovise(SpellAbility sa, ManaCost manaCost, CardCollectionView untappedCards, boolean improvise) {
+    public Map<Card, ManaCostShard> chooseCardsForConvokeOrImprovise(SpellAbility sa, ManaCost manaCost, CardCollectionView untappedCards, boolean artifacts, boolean creatures, Integer maxReduction) {
         final Player ai = sa.getActivatingPlayer();
         final PhaseHandler ph = ai.getGame().getPhaseHandler();
         //Filter out mana sources that will interfere with payManaCost()
@@ -1390,9 +1390,10 @@ public class PlayerControllerAi extends PlayerController {
 
         // Filter out creatures if AI hasn't attacked yet
         if (ph.isPlayerTurn(ai) && ph.getPhase().isBefore(PhaseType.COMBAT_DECLARE_ATTACKERS)) {
-            if (improvise) {
+            if (!creatures) {
                 untapped = CardLists.filter(untapped, c -> !c.isCreature());
             } else {
+                // TODO AI needs to learn how to use Convoke or Waterbend
                 return new HashMap<>();
             }
         }
@@ -1406,13 +1407,16 @@ public class PlayerControllerAi extends PlayerController {
             if (!ai.getGame().getStack().isEmpty()) {
                 final List<GameObject> objects = ComputerUtil.predictThreatenedObjects(sa.getActivatingPlayer(), null);
                 for (Card c : blockers) {
-                    if (objects.contains(c) && (!improvise || c.isArtifact())) {
+                    if (objects.contains(c) && (creatures || c.isArtifact())) {
                         untapped.add(c);
                     }
+                    if (maxReduction != null && untapped.size() >= maxReduction) {
+                        break;
                     }
                 }
             }
-        return ComputerUtilMana.getConvokeOrImproviseFromList(manaCost, untapped, improvise);
+        }
+        return ComputerUtilMana.getConvokeOrImproviseFromList(manaCost, untapped, artifacts, creatures);
     }
 
     @Override
@@ -1582,7 +1586,7 @@ public class PlayerControllerAi extends PlayerController {
 
     @Override
     public List<OptionalCostValue> chooseOptionalCosts(SpellAbility chosen, List<OptionalCostValue> optionalCostValues) {
-        return SpellApiToAi.Converter.get(chosen).chooseOptionalCosts(chosen, player, optionalCostValues);
+        return SpellApiToAi.Converter.get(chosen).chooseOptionalCosts(player, chosen, optionalCostValues);
     }
 
     @Override

forge-ai/src/main/java/forge/ai/SpellAbilityAi.java

@@ -247,7 +247,7 @@ public abstract class SpellAbilityAi {
      */
     public AiAbilityDecision chkDrawbackWithSubs(Player aiPlayer, AbilitySub ab) {
         final AbilitySub subAb = ab.getSubAbility();
-        AiAbilityDecision decision = SpellApiToAi.Converter.get(ab).chkDrawback(ab, aiPlayer);
+        AiAbilityDecision decision = SpellApiToAi.Converter.get(ab).chkDrawback(aiPlayer, ab);
         if (!decision.willingToPlay()) {
             return decision;
         }
@@ -262,7 +262,7 @@ public abstract class SpellAbilityAi {
     /**
      * Handles the AI decision to play a sub-SpellAbility
      */
-    public AiAbilityDecision chkDrawback(final SpellAbility sa, final Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(final Player aiPlayer, final SpellAbility sa) {
         // sub-SpellAbility might use targets too
         if (sa.usesTargeting()) {
             // no Candidates, no adding to Stack
@@ -365,14 +365,14 @@ public abstract class SpellAbilityAi {
      * <p>
      * Evaluated costs are: life, discard, sacrifice and counter-removal
      */
-    protected boolean willPayCosts(final Player ai, final SpellAbility sa, final Cost cost, final Card source) {
+    protected boolean willPayCosts(final Player payer, final SpellAbility sa, final Cost cost, final Card source) {
-        if (!ComputerUtilCost.checkLifeCost(ai, cost, source, 4, sa)) {
+        if (!ComputerUtilCost.checkLifeCost(payer, cost, source, 4, sa)) {
             return false;
         }
-        if (!ComputerUtilCost.checkDiscardCost(ai, cost, source, sa)) {
+        if (!ComputerUtilCost.checkDiscardCost(payer, cost, source, sa)) {
             return false;
         }
-        if (!ComputerUtilCost.checkSacrificeCost(ai, cost, source, sa)) {
+        if (!ComputerUtilCost.checkSacrificeCost(payer, cost, source, sa)) {
             return false;
         }
         if (!ComputerUtilCost.checkRemoveCounterCost(cost, source, sa)) {
@@ -381,7 +381,7 @@ public abstract class SpellAbilityAi {
         return true;
     }
 
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final Card source = sa.getHostCard();
         final String aiLogic = sa.getParam("UnlessAI");
         boolean payNever = "Never".equals(aiLogic);
@@ -400,7 +400,7 @@ public abstract class SpellAbilityAi {
                 && (isMine || ComputerUtilCost.checkDiscardCost(payer, cost, source, sa));
     }
 
-    public List<OptionalCostValue> chooseOptionalCosts(SpellAbility chosen, Player player, List<OptionalCostValue> optionalCostValues) {
+    public List<OptionalCostValue> chooseOptionalCosts(Player payer, SpellAbility chosen, List<OptionalCostValue> optionalCostValues) {
         List<OptionalCostValue> chosenOptCosts = Lists.newArrayList();
         Cost costSoFar = chosen.getPayCosts().copy();
 
@@ -420,7 +420,7 @@ public abstract class SpellAbilityAi {
                 }
             }
 
-            if (ComputerUtilCost.canPayCost(fullCostSa, player, false)) {
+            if (ComputerUtilCost.canPayCost(fullCostSa, payer, false)) {
                 chosenOptCosts.add(opt);
                 costSoFar.add(opt.getCost());
             }

forge-ai/src/main/java/forge/ai/SpellApiToAi.java

@@ -24,6 +24,7 @@ public enum SpellApiToAi {
             .put(ApiType.AddPhase, AddPhaseAi.class)
             .put(ApiType.AddTurn, AddTurnAi.class)
             .put(ApiType.AdvanceCrank, AdvanceCrankAi.class)
+            .put(ApiType.Airbend, AirbendAi.class)
             .put(ApiType.AlterAttribute, AlterAttributeAi.class)
             .put(ApiType.Amass, AmassAi.class)
             .put(ApiType.Animate, AnimateAi.class)
@@ -86,6 +87,7 @@ public enum SpellApiToAi {
             .put(ApiType.DrainMana, DrainManaAi.class)
             .put(ApiType.Draw, DrawAi.class)
             .put(ApiType.EachDamage, DamageEachAi.class)
+            .put(ApiType.Earthbend, EarthbendAi.class)
             .put(ApiType.Effect, EffectAi.class)
             .put(ApiType.Encode, EncodeAi.class)
             .put(ApiType.Endure, EndureAi.class)
@@ -195,8 +197,7 @@ public enum SpellApiToAi {
             .put(ApiType.TimeTravel, TimeTravelAi.class)
             .put(ApiType.Token, TokenAi.class)
             .put(ApiType.TwoPiles, TwoPilesAi.class)
-            .put(ApiType.Unattach, CannotPlayAi.class)
+            .put(ApiType.Unattach, UnattachAi.class)
-            .put(ApiType.UnattachAll, UnattachAllAi.class)
             .put(ApiType.UnlockDoor, AlwaysPlayAi.class)
             .put(ApiType.Untap, UntapAi.class)
             .put(ApiType.UntapAll, UntapAllAi.class)

forge-ai/src/main/java/forge/ai/ability/ActivateAbilityAi.java

@@ -68,7 +68,7 @@ public class ActivateAbilityAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         final Card source = sa.getHostCard();
         if (!sa.usesTargeting()) {
             final List<Player> defined = AbilityUtils.getDefinedPlayers(source, sa.getParam("Defined"), sa);

forge-ai/src/main/java/forge/ai/ability/AirbendAi.java

@@ -0,0 +1,53 @@
+package forge.ai.ability;
+
+import forge.ai.*;
+import forge.game.card.Card;
+import forge.game.card.CardCollection;
+import forge.game.card.CardLists;
+import forge.game.combat.Combat;
+import forge.game.phase.PhaseHandler;
+import forge.game.phase.PhaseType;
+import forge.game.player.Player;
+import forge.game.spellability.SpellAbility;
+
+public class AirbendAi extends SpellAbilityAi {
+    @Override
+    protected AiAbilityDecision canPlay(Player aiPlayer, SpellAbility sa) {
+        // Check own cards that need saving, non-token, above CMC 2 so that it's hopefully worth saving this one
+        final Combat combat = aiPlayer.getGame().getCombat();
+        final CardCollection threatenedTgts = CardLists.filter(aiPlayer.getCreaturesInPlay(),
+                card -> !card.isToken() && card.getCMC() > 2 &&
+                        (ComputerUtil.predictThreatenedObjects(aiPlayer, null, true).contains(card)
+                        || (combat.isAttacking(card) && combat.isBlocked(card) && ComputerUtilCombat.combatantWouldBeDestroyed(aiPlayer, card, combat))));
+        if (!threatenedTgts.isEmpty()) {
+            Card bestSaved = ComputerUtilCard.getBestAI(threatenedTgts);
+            sa.getTargets().add(bestSaved);
+            return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
+        }
+
+        // Check opponent's cards that need bouncing (only in the AI's own turn, main phase 1, or at the end of opponent's
+        // turn, to get rid of potential blockers)
+        PhaseHandler ph = aiPlayer.getGame().getPhaseHandler();
+        if (ph.is(PhaseType.MAIN1, aiPlayer) || (ph.is(PhaseType.END_OF_TURN) && ph.getNextTurn() == aiPlayer)) {
+            final CardCollection opposingThreats = aiPlayer.getOpponents().getCreaturesInPlay();
+            if (!opposingThreats.isEmpty()) {
+                sa.getTargets().add(ComputerUtilCard.getBestAI(opposingThreats));
+                return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
+            }
+        }
+
+        // TODO: add logic to use it to remove threatening spells when the ability allows to target spells?
+
+        return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
+    }
+
+    @Override
+    protected AiAbilityDecision doTriggerNoCost(Player aiPlayer, SpellAbility sa, boolean mandatory) {
+        AiAbilityDecision decision = canPlay(aiPlayer, sa);
+        if (decision.willingToPlay() || mandatory) {
+            return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
+        }
+        return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
+    }
+
+}

forge-ai/src/main/java/forge/ai/ability/AnimateAi.java

@@ -234,7 +234,7 @@ public class AnimateAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         if (sa.usesTargeting()) {
             sa.resetTargets();
             return animateTgtAI(sa);
@@ -605,10 +605,10 @@ public class AnimateAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         if (sa.isKeyword(Keyword.RIOT)) {
             return !SpecialAiLogic.preferHasteForRiot(sa, payer);
         }
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/AssembleContraptionAi.java

@@ -93,9 +93,9 @@ public class AssembleContraptionAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         if(getDeck(aiPlayer, sa).isEmpty())
             return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
-        return super.chkDrawback(sa, aiPlayer);
+        return super.chkDrawback(aiPlayer, sa);
     }
 }

forge-ai/src/main/java/forge/ai/ability/AttachAi.java

@@ -968,7 +968,7 @@ public class AttachAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(final SpellAbility sa, final Player ai) {
+    public AiAbilityDecision chkDrawback(final Player ai, final SpellAbility sa) {
         if (sa.isTrigger() && sa.usesTargeting()) {
             CardCollection targetables = CardLists.getTargetableCards(ai.getCardsIn(ZoneType.Battlefield), sa);
             CardCollection source = AbilityUtils.getDefinedCards(sa.getHostCard(), sa.getParam("Object"), sa);

forge-ai/src/main/java/forge/ai/ability/BecomesBlockedAi.java

@@ -54,7 +54,7 @@ public class BecomesBlockedAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         // TODO - implement AI
         return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
     }

forge-ai/src/main/java/forge/ai/ability/CannotPlayAi.java

@@ -20,7 +20,7 @@ public class CannotPlayAi extends SpellAbilityAi {
      * @see forge.card.abilityfactory.SpellAiLogic#chkAIDrawback(java.util.Map, forge.card.spellability.SpellAbility, forge.game.player.Player)
      */
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
     }
 }

forge-ai/src/main/java/forge/ai/ability/ChangeCombatantsAi.java

@@ -34,7 +34,7 @@ public class ChangeCombatantsAi extends SpellAbilityAi {
      * @see forge.card.abilityfactory.SpellAiLogic#chkAIDrawback(java.util.Map, forge.card.spellability.SpellAbility, forge.game.player.Player)
      */
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         final String logic = sa.getParamOrDefault("AILogic", "");
 
         if (logic.equals("WeakestOppExceptCtrl")) {

forge-ai/src/main/java/forge/ai/ability/ChangeZoneAi.java

@@ -45,23 +45,23 @@ public class ChangeZoneAi extends SpellAbilityAi {
     // cards where multiple cards are fetched at once and they need to be coordinated
     private static CardCollection multipleCardsToChoose = new CardCollection();
 
-    protected boolean willPayCosts(Player ai, SpellAbility sa, Cost cost, Card source) {
+    protected boolean willPayCosts(Player payer, SpellAbility sa, Cost cost, Card source) {
         if (sa.isHidden()) {
-            if (!ComputerUtilCost.checkSacrificeCost(ai, cost, source, sa)
+            if (!ComputerUtilCost.checkSacrificeCost(payer, cost, source, sa)
                     && !"Battlefield".equals(sa.getParam("Destination")) && !source.isLand()) {
                 return false;
             }
 
-            if (!ComputerUtilCost.checkLifeCost(ai, cost, source, 4, sa)) {
+            if (!ComputerUtilCost.checkLifeCost(payer, cost, source, 4, sa)) {
                 return false;
             }
 
-            if (!ComputerUtilCost.checkDiscardCost(ai, cost, source, sa)) {
+            if (!ComputerUtilCost.checkDiscardCost(payer, cost, source, sa)) {
                 for (final CostPart part : cost.getCostParts()) {
                     if (part instanceof CostDiscard) {
                         CostDiscard cd = (CostDiscard) part;
                         // this is mainly for typecycling
-                        if (!cd.payCostFromSource() || !ComputerUtil.isWorseThanDraw(ai, source)) {
+                        if (!cd.payCostFromSource() || !ComputerUtil.isWorseThanDraw(payer, source)) {
                             return false;
                         }
                     }
@@ -80,7 +80,7 @@ public class ChangeZoneAi extends SpellAbilityAi {
                     }
                     int amt = part.getAbilityAmount(sa);
                     needed += amt;
-                    CardCollection toAdd = ComputerUtil.chooseExileFrom(ai, (CostExile) part, source, amt, sa, true);
+                    CardCollection toAdd = ComputerUtil.chooseExileFrom(payer, (CostExile) part, source, amt, sa, true);
                     if (toAdd != null) {
                         payingCards.addAll(toAdd);
                     }
@@ -91,7 +91,7 @@ public class ChangeZoneAi extends SpellAbilityAi {
             }
         }
 
-        return super.willPayCosts(ai, sa, cost, source);
+        return super.willPayCosts(payer, sa, cost, source);
     }
 
     @Override
@@ -198,13 +198,12 @@ public class ChangeZoneAi extends SpellAbilityAi {
      * <p>
      * changeZonePlayDrawbackAI.
      * </p>
-     * @param sa
-     *            a {@link forge.game.spellability.SpellAbility} object.
      *
+     * @param sa a {@link SpellAbility} object.
      * @return a boolean.
      */
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         if (sa.isHidden()) {
             return hiddenOriginPlayDrawbackAI(aiPlayer, sa);
         }
@@ -2105,7 +2104,7 @@ public class ChangeZoneAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final Card host = sa.getHostCard();
 
         int lifeLoss = 0;
@@ -2132,6 +2131,6 @@ public class ChangeZoneAi extends SpellAbilityAi {
             }
         }
 
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/ChangeZoneAllAi.java

@@ -1,7 +1,5 @@
 package forge.ai.ability;
 
-import forge.ai.AiAbilityDecision;
-import forge.ai.AiPlayDecision;
 import forge.ai.*;
 import forge.game.Game;
 import forge.game.ability.AbilityUtils;
@@ -239,15 +237,13 @@ public class ChangeZoneAllAi extends SpellAbilityAi {
      * <p>
      * changeZoneAllPlayDrawbackAI.
      * </p>
-     * @param sa
-     *            a {@link forge.game.spellability.SpellAbility} object.
-     * @param aiPlayer
-     *            a {@link forge.game.player.Player} object.
      *
+     * @param aiPlayer a {@link Player} object.
+     * @param sa       a {@link SpellAbility} object.
      * @return a boolean.
      */
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         // if putting cards from hand to library and parent is drawing cards
         // make sure this will actually do something:
 

forge-ai/src/main/java/forge/ai/ability/ChooseCardAi.java

@@ -134,7 +134,7 @@ public class ChooseCardAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         if (sa.hasParam("AILogic") && !checkAiLogic(ai, sa, sa.getParam("AILogic"))) {
             return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
         }

forge-ai/src/main/java/forge/ai/ability/ChooseDirectionAi.java

@@ -44,7 +44,7 @@ public class ChooseDirectionAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         return canPlay(ai, sa);
     }
 

forge-ai/src/main/java/forge/ai/ability/ChooseGenericAi.java

@@ -51,7 +51,7 @@ public class ChooseGenericAi extends SpellAbilityAi {
      * @see forge.card.abilityfactory.SpellAiLogic#chkAIDrawback(java.util.Map, forge.card.spellability.SpellAbility, forge.game.player.Player)
      */
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         AiAbilityDecision decision;
         if (sa.isTrigger()) {
             decision = doTriggerNoCost(aiPlayer, sa, sa.isMandatory());
@@ -99,7 +99,7 @@ public class ChooseGenericAi extends SpellAbilityAi {
                 String unlessCost = sp.getParam("UnlessCost");
                 sp.setActivatingPlayer(sa.getActivatingPlayer());
                 Cost unless = new Cost(unlessCost, false);
-                if (SpellApiToAi.Converter.get(sp).willPayUnlessCost(sp, player, unless, false, new FCollection<>(player))
+                if (SpellApiToAi.Converter.get(sp).willPayUnlessCost(player, sp, unless, false, new FCollection<>(player))
                         && ComputerUtilCost.canPayCost(unless, sp, player, true)) {
                     return sp;
                 }

forge-ai/src/main/java/forge/ai/ability/ChoosePlayerAi.java

@@ -22,7 +22,7 @@ public class ChoosePlayerAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         return canPlay(ai, sa);
     }
 

forge-ai/src/main/java/forge/ai/ability/CloneAi.java

@@ -76,7 +76,7 @@ public class CloneAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         // AI should only activate this during Human's turn
         boolean chance = true;
 

forge-ai/src/main/java/forge/ai/ability/ControlExchangeAi.java

@@ -54,7 +54,7 @@ public class ControlExchangeAi extends SpellAbilityAi {
                 return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
             }
         } else if (mandatory) {
-            AiAbilityDecision decision = chkDrawback(sa, aiPlayer);
+            AiAbilityDecision decision = chkDrawback(aiPlayer, sa);
             if (sa.isTargetNumberValid()) {
                 return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
             }
@@ -67,7 +67,7 @@ public class ControlExchangeAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         if (!sa.usesTargeting()) {
             return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
         }

forge-ai/src/main/java/forge/ai/ability/ControlGainAi.java

@@ -299,12 +299,12 @@ public class ControlGainAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, final Player ai) {
+    public AiAbilityDecision chkDrawback(final Player ai, SpellAbility sa) {
         final Game game = ai.getGame();
 
         // Special card logic that is processed elsewhere
         if (sa.hasParam("AILogic")) {
-            if (("DonateTargetPerm").equals(sa.getParam("AILogic"))) {
+            if ("DonateTargetPerm".equals(sa.getParam("AILogic"))) {
                 // Donate step 2 - target a donatable permanent.
                 return SpecialCardAi.Donate.considerDonatingPermanent(ai, sa);
             }
@@ -346,7 +346,7 @@ public class ControlGainAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         // Pay to gain Control
         if (sa.hasParam("UnlessSwitched")) {
             final Card host = sa.getHostCard();
@@ -360,6 +360,6 @@ public class ControlGainAi extends SpellAbilityAi {
             }
         }
 
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/CopySpellAbilityAi.java

@@ -64,7 +64,7 @@ public class CopySpellAbilityAi extends SpellAbilityAi {
             } else if (top.getApi() == ApiType.Mana) {
                 // would lead to Stack Overflow by trying to play this again
                 return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
-            } else if (top.getApi() == ApiType.DestroyAll || top.getApi() == ApiType.SacrificeAll || top.getApi() == ApiType.ChangeZoneAll || top.getApi() == ApiType.TapAll || top.getApi() == ApiType.UnattachAll) {
+            } else if (top.getApi() == ApiType.DestroyAll || top.getApi() == ApiType.SacrificeAll || top.getApi() == ApiType.ChangeZoneAll || top.getApi() == ApiType.TapAll) {
                 if (!top.usesTargeting() || top.getActivatingPlayer().equals(aiPlayer)) {
                     // If we activated a mass removal / mass tap / mass bounce / etc. spell, or if the opponent activated it but
                     // it can't be retargeted, no reason to copy this spell since it'll probably do the same thing and is useless as a copy
@@ -73,7 +73,7 @@ public class CopySpellAbilityAi extends SpellAbilityAi {
             } else if (top.hasParam("ConditionManaSpent") || top.getHostCard().hasSVar("AINoCopy")) {
                 // Mana spent is not copied, so these spells generally do nothing when copied.
                 return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
-            } else if (ComputerUtilCard.isCardRemAIDeck(top.getHostCard())) {
+            } else if (SpellApiToAi.Converter.get(top.getApi()) instanceof CannotPlayAi || ComputerUtilCard.isCardRemAIDeck(top.getHostCard())) {
                 // Don't try to copy anything you can't understand how to handle
                 return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
             }
@@ -121,7 +121,7 @@ public class CopySpellAbilityAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(final SpellAbility sa, final Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(final Player aiPlayer, final SpellAbility sa) {
         if ("ChainOfSmog".equals(sa.getParam("AILogic"))) {
             return SpecialCardAi.ChainOfSmog.consider(aiPlayer, sa);
         }
@@ -132,7 +132,7 @@ public class CopySpellAbilityAi extends SpellAbilityAi {
         AiAbilityDecision decision = canPlay(aiPlayer, sa);
         if (!decision.willingToPlay()) {
             if (sa.isMandatory()) {
-                return super.chkDrawback(sa, aiPlayer);
+                return super.chkDrawback(aiPlayer, sa);
             }
         }
         return decision;
@@ -156,7 +156,7 @@ public class CopySpellAbilityAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final String aiLogic = sa.getParam("UnlessAI");
         if ("Never".equals(aiLogic)) { return false; }
 
@@ -172,6 +172,6 @@ public class CopySpellAbilityAi extends SpellAbilityAi {
                 }
             }
         }
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/CounterAi.java

@@ -226,7 +226,7 @@ public class CounterAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         return doTriggerNoCost(aiPlayer, sa, true);
     }
 
@@ -345,7 +345,7 @@ public class CounterAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final Card source = sa.getHostCard();
         final Game game = source.getGame();
         List<SpellAbility> spells = AbilityUtils.getDefinedSpellAbilities(source, sa.getParamOrDefault("Defined", "Targeted"), sa);
@@ -388,6 +388,6 @@ public class CounterAi extends SpellAbilityAi {
             }
         }
 
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/CountersMoveAi.java

@@ -204,7 +204,7 @@ public class CountersMoveAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         if (sa.usesTargeting()) {
             sa.resetTargets();
             return moveTgtAI(ai, sa);

forge-ai/src/main/java/forge/ai/ability/CountersProliferateAi.java

@@ -93,7 +93,7 @@ public class CountersProliferateAi extends SpellAbilityAi {
      * @see forge.card.abilityfactory.SpellAiLogic#chkAIDrawback(java.util.Map, forge.card.spellability.SpellAbility, forge.game.player.Player)
      */
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         if ("Always".equals(sa.getParam("AILogic"))) {
             return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
         }

forge-ai/src/main/java/forge/ai/ability/CountersPutAi.java

@@ -21,6 +21,7 @@ import forge.game.player.PlayerPredicates;
 import forge.game.spellability.AbilitySub;
 import forge.game.spellability.SpellAbility;
 import forge.game.spellability.TargetRestrictions;
+import forge.game.staticability.StaticAbility;
 import forge.game.trigger.Trigger;
 import forge.game.trigger.TriggerType;
 import forge.game.zone.ZoneType;
@@ -43,11 +44,11 @@ public class CountersPutAi extends CountersAi {
      * forge.game.card.Card)
      */
     @Override
-    protected boolean willPayCosts(Player ai, SpellAbility sa, Cost cost, Card source) {
+    protected boolean willPayCosts(Player payer, SpellAbility sa, Cost cost, Card source) {
         final String type = sa.getParam("CounterType");
         final String aiLogic = sa.getParamOrDefault("AILogic", "");
 
-        if (!super.willPayCosts(ai, sa, cost, source)) {
+        if (!super.willPayCosts(payer, sa, cost, source)) {
             return false;
         }
 
@@ -105,7 +106,12 @@ public class CountersPutAi extends CountersAi {
                     }
                 }
             }
-            int maxLevel = Integer.parseInt(sa.getParam("MaxLevel"));
+            int maxLevel = 0;
+            for (StaticAbility st : source.getStaticAbilities()) {
+                if (st.toString().startsWith("LEVEL ")) {
+                    maxLevel = Math.max(maxLevel, Integer.parseInt(st.toString().substring(6, 7)));
+                }
+            }
             return source.getCounters(CounterEnumType.LEVEL) < maxLevel;
         }
 
@@ -663,7 +669,7 @@ public class CountersPutAi extends CountersAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(final SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, final SpellAbility sa) {
         final Game game = ai.getGame();
         Card choice = null;
         final String type = sa.getParam("CounterType");

forge-ai/src/main/java/forge/ai/ability/CountersPutAllAi.java

@@ -115,7 +115,7 @@ public class CountersPutAllAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         return canPlay(ai, sa);
     }
     /* (non-Javadoc)

forge-ai/src/main/java/forge/ai/ability/DamageAllAi.java

@@ -175,7 +175,7 @@ public class  DamageAllAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         final Card source = sa.getHostCard();
         final String validP = sa.getParamOrDefault("ValidPlayers", "");
 

forge-ai/src/main/java/forge/ai/ability/DamageDealAi.java

@@ -38,7 +38,7 @@ import java.util.Map;
 
 public class DamageDealAi extends DamageAiBase {
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         final SpellAbility root = sa.getRootAbility();
         final String damage = sa.getParam("NumDmg");
         Card source = sa.getHostCard();
@@ -1165,7 +1165,7 @@ public class DamageDealAi extends DamageAiBase {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid,
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid,
                                      FCollectionView<Player> payers) {
         if (!payer.canLoseLife() || payer.cantLoseForZeroOrLessLife()) {
             return false;
@@ -1185,6 +1185,6 @@ public class DamageDealAi extends DamageAiBase {
             }
         }
 
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/DamageEachAi.java

@@ -44,7 +44,7 @@ public class DamageEachAi extends DamageAiBase {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         // check AI life before playing this drawback?
         return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
     }

forge-ai/src/main/java/forge/ai/ability/DebuffAi.java

@@ -87,7 +87,7 @@ public class DebuffAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         if (!sa.usesTargeting()) {
             // TODO - copied from AF_Pump.pumpDrawbackAI() - what should be here?
         } else {

forge-ai/src/main/java/forge/ai/ability/DelayedTriggerAi.java

@@ -15,7 +15,7 @@ import forge.game.zone.ZoneType;
 public class DelayedTriggerAi extends SpellAbilityAi {
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         if ("Always".equals(sa.getParam("AILogic"))) {
             return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
         }

forge-ai/src/main/java/forge/ai/ability/DestroyAi.java

@@ -20,7 +20,7 @@ import forge.util.collect.FCollectionView;
 
 public class DestroyAi extends SpellAbilityAi {
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         return checkApiLogic(ai, sa);
     }
 
@@ -454,7 +454,7 @@ public class DestroyAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final Card host = sa.getHostCard();
         if (alreadyPaid) {
             return false;
@@ -467,6 +467,6 @@ public class DestroyAi extends SpellAbilityAi {
             }
         }
 
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/DestroyAllAi.java

@@ -32,7 +32,7 @@ public class DestroyAllAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         return doMassRemovalLogic(aiPlayer, sa);
     }
 
@@ -176,7 +176,7 @@ public class DestroyAllAi extends SpellAbilityAi {
     
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final Card source = sa.getHostCard();
         if (payers.size() > 1) {
             if (alreadyPaid) {
@@ -206,6 +206,6 @@ public class DestroyAllAi extends SpellAbilityAi {
             }
         }
 
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/DigAi.java

@@ -100,7 +100,7 @@ public class DigAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player aiPlayer) {
+    public AiAbilityDecision chkDrawback(Player aiPlayer, SpellAbility sa) {
         // TODO: improve this check in ways that may be specific to a subability
         return canPlay(aiPlayer, sa);
     }

forge-ai/src/main/java/forge/ai/ability/DiscardAi.java

@@ -196,7 +196,7 @@ public class DiscardAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         // Drawback AI improvements
         // if parent draws cards, make sure cards in hand + cards drawn > 0
         if (sa.usesTargeting()) {
@@ -219,7 +219,7 @@ public class DiscardAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final Card host = sa.getHostCard();
         final String aiLogic = sa.getParam("UnlessAI");
         if ("Never".equals(aiLogic)) { return false; }
@@ -268,6 +268,6 @@ public class DiscardAi extends SpellAbilityAi {
             }
         }
 
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/DrainManaAi.java

@@ -62,7 +62,7 @@ public class DrainManaAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         // AI cannot use this properly until he can use SAs during Humans turn
         final Card source = sa.getHostCard();
 

forge-ai/src/main/java/forge/ai/ability/DrawAi.java

@@ -87,24 +87,24 @@ public class DrawAi extends SpellAbilityAi {
      * forge.game.card.Card)
      */
     @Override
-    protected boolean willPayCosts(Player ai, SpellAbility sa, Cost cost, Card source) {
+    protected boolean willPayCosts(Player payer, SpellAbility sa, Cost cost, Card source) {
-        if (!ComputerUtilCost.checkCreatureSacrificeCost(ai, cost, source, sa)) {
+        if (!ComputerUtilCost.checkCreatureSacrificeCost(payer, cost, source, sa)) {
             return false;
         }
 
-        if (!ComputerUtilCost.checkLifeCost(ai, cost, source, 4, sa)) {
+        if (!ComputerUtilCost.checkLifeCost(payer, cost, source, 4, sa)) {
             return false;
         }
 
-        if (!ComputerUtilCost.checkDiscardCost(ai, cost, source, sa)) {
+        if (!ComputerUtilCost.checkDiscardCost(payer, cost, source, sa)) {
-            AiCostDecision aiDecisions = new AiCostDecision(ai, sa, false);
+            AiCostDecision aiDecisions = new AiCostDecision(payer, sa, false);
             for (final CostPart part : cost.getCostParts()) {
                 if (part instanceof CostDiscard) {
                     PaymentDecision decision = part.accept(aiDecisions);
                     if (null == decision)
                         return false;
                     for (Card discard : decision.cards) {
-                        if (!ComputerUtil.isWorseThanDraw(ai, discard)) {
+                        if (!ComputerUtil.isWorseThanDraw(payer, discard)) {
                             return false;
                         }
                     }
@@ -171,7 +171,7 @@ public class DrawAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         if (targetAI(ai, sa, sa.isTrigger() && sa.getHostCard().isInPlay())) {
             return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
         }
@@ -558,7 +558,7 @@ public class DrawAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final Card host = sa.getHostCard();
         final String aiLogic = sa.getParam("UnlessAI");
 
@@ -586,6 +586,6 @@ public class DrawAi extends SpellAbilityAi {
         }
         // TODO add logic for Discard + Draw Effects
 
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/EarthbendAi.java

@@ -0,0 +1,61 @@
+package forge.ai.ability;
+
+import forge.ai.*;
+import forge.game.card.Card;
+import forge.game.card.CardCollection;
+import forge.game.card.CardLists;
+import forge.game.cost.Cost;
+import forge.game.cost.CostPart;
+import forge.game.cost.CostSacrifice;
+import forge.game.player.Player;
+import forge.game.spellability.SpellAbility;
+
+public class EarthbendAi extends SpellAbilityAi {
+    @Override
+    protected AiAbilityDecision canPlay(Player aiPlayer, SpellAbility sa) {
+        CardCollection lands = aiPlayer.getLandsInPlay();
+        if (lands.isEmpty()) {
+            return new AiAbilityDecision(0, AiPlayDecision.AnotherTime);
+        }
+        CardCollection fetchLands = CardLists.filter(lands, c -> {
+                    for (final SpellAbility ability : c.getAllSpellAbilities()) {
+                        if (ability.isActivatedAbility()) {
+                            final Cost cost = ability.getPayCosts();
+                            for (final CostPart part : cost.getCostParts()) {
+                                if (!(part instanceof CostSacrifice)) {
+                                    continue;
+                                }
+                                CostSacrifice sacCost = (CostSacrifice) part;
+                                if (sacCost.payCostFromSource() && ComputerUtilCost.canPayCost(ability, c.getController(), false)) {
+                                    return true;
+                                }
+                            }
+                        }
+                    }
+                    return false;
+                });
+
+        Card tgtLand = null;
+
+        if (!fetchLands.isEmpty()) {
+            // Prioritize fetchlands as they can be reused later
+            tgtLand = ComputerUtilCard.getBestLandToAnimate(fetchLands);
+        } else {
+            tgtLand = ComputerUtilCard.getBestLandToAnimate(lands);
+        }
+
+        sa.getTargets().add(tgtLand);
+
+        return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
+    }
+
+    @Override
+    protected AiAbilityDecision doTriggerNoCost(Player aiPlayer, SpellAbility sa, boolean mandatory) {
+        AiAbilityDecision decision = canPlay(aiPlayer, sa);
+        if (decision.willingToPlay() || mandatory) {
+            return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
+        }
+        return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
+    }
+
+}

forge-ai/src/main/java/forge/ai/ability/EffectAi.java

@@ -640,7 +640,7 @@ public class EffectAi extends SpellAbilityAi {
     }
 
     @Override
-    public boolean willPayUnlessCost(SpellAbility sa, Player payer, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
+    public boolean willPayUnlessCost(Player payer, SpellAbility sa, Cost cost, boolean alreadyPaid, FCollectionView<Player> payers) {
         final String aiLogic = sa.getParam("UnlessAI");
         if ("WillAttack".equals(aiLogic)) {
             // TODO use AiController::getPredictedCombat
@@ -651,6 +651,6 @@ public class EffectAi extends SpellAbilityAi {
                 return false;
             }
         }
-        return super.willPayUnlessCost(sa, payer, cost, alreadyPaid, payers);
+        return super.willPayUnlessCost(payer, sa, cost, alreadyPaid, payers);
     }
 }

forge-ai/src/main/java/forge/ai/ability/EncodeAi.java

@@ -52,7 +52,7 @@ public final class EncodeAi extends SpellAbilityAi {
     }
 
     @Override
-    public AiAbilityDecision chkDrawback(SpellAbility sa, Player ai) {
+    public AiAbilityDecision chkDrawback(Player ai, SpellAbility sa) {
         return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
     }