User guide update (#9115)

CONTRIBUTING.md

@@ -57,6 +57,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:

docs/AI.md

@@ -7,6 +7,9 @@ The AI is:
 - Poor to Ok in control 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.
 
 # AI Matches from Command Line

docs/Advanced-Search.md

@@ -1,9 +1,19 @@
 # Advanced Search
 
-Forge implements many ways to help you find the cards you want in your ever growing collection. One of them uses a [Scryfall-like syntax](https://scryfall.com/docs/syntax) in the collection search bar.
+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".

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.

docs/Card-scripting-API/AbilityFactory.md

@@ -295,6 +295,8 @@ Parameters:
 
 ### ControlExchange
 
+### ControlPlayer
+
 ### ControlSpell
 
 ## Copy*

docs/Creating-a-custom-Card.md

@@ -173,3 +173,57 @@ The sinmlest method for creating an effect on your card is to find another card
 >./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

@@ -260,6 +260,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.
 
+## 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/Frequently-Asked-Questions.md

@@ -6,13 +6,18 @@ https://discord.com/channels/267367946135928833/1095026912927154176
 * Search the help posts in 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?
 
-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.
+
+Also use the mentioned measure if your match or deckeditor won't start - it would help in 90% of the cases.
 
 ## I think I found a bug in Forge. What do I do?
 
@@ -24,7 +29,7 @@ For starters, please take note of (1) what you had in play, (2) what your oppone
 
 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.
 
-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.
 
@@ -46,7 +51,17 @@ 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)
+
+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?
 
@@ -56,7 +71,7 @@ Take a look through the /res/cardsfolder folder. This is where all the card data
 
 ## 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?
 
@@ -71,7 +86,3 @@ If you have an effect that generated you some mana, and you don't know where it
 ## 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/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/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,8 +1,6 @@
-# User Guide
+# Downloads
 
-## Downloads
-
-### Snapshots
+## Snapshots
 
 * Snapshots are automated daily builds of the source code.
 * They contain the latest bug fixes, features and cards.
@@ -16,7 +14,7 @@
 
 <https://github.com/user-attachments/assets/7a0c7bb8-7cf9-4800-8091-bcc30ff2f4d8>
 
-### Releases
+## Releases
 
 * "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.
@@ -27,7 +25,7 @@
 
 * Grab the installer file that ends in .jar
 
-## System Requirements
+# System Requirements
 
 **Forge Requires Java** to run, please make sure you have Java installed on your machine prior to attempting to run.
 
@@ -47,11 +45,13 @@ 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.)
 
-## Install and Run
+If you plan to eventually download all card images make sure you have several gigabytes of free drive space.
+
+# Install and Run
 
 > Warning: Do **NOT** owerwrite an existing installation. Always unpack/install the package in a new folder to avoid problems!
 
-### 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.
 
@@ -67,16 +67,16 @@ Sometimes double-clicking will open the jar file in a different program.
 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 Linux systems (file permission related).
 
-### Manual Extraction (tar.bz2)
+## Manual Extraction (tar.bz2)
 
-#### Desktop Windows
+### 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
+### 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.
@@ -87,12 +87,39 @@ This might be different in OSX or Linux systems (file permission related).
     * 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
+### Android
 
 * Sideload/Install "forge...apk"
 * Run Forge
 
-### Play Adventure Mode on Desktop
+# 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.
@@ -101,9 +128,69 @@ This might be different in OSX or Linux systems (file permission related).
     * check you're up to date with your version.
     * check in the settings that the "Selector Mode" is set to `Default`
 
-## Gameplay
+# Gameplay
 
-### Full Control
+## Targeting Arrows
+When hovering over items on the stack, arrows will be displayed between that item and all of its targets (both cards and players).
+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.
 
+## Card Zoomer
+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.
+
+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.
+
+Split cards (name contains "//") are rotated 90 degrees for easier viewing.
+
+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.
+
+The standard flip graphic (the two rotated arrows) is displayed if the card can be flipped or transformed.
+
+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).  
+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 yielding per ability if you auto-yield to Hellrider's triggered ability once, all triggers from other Hellrider cards will be automatically auto-yielded to as well. When yielding per card, you will need to auto-yield to each Hellrider separately.
+
+  Note that in when auto-yielding per ability, auto-yields will NOT be automatically cleared between games in a match, which should speed the game up. When auto-yielding per card, auto-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 will still be given a chance to declare blockers if your opponent attacks, but after that the rest of your opponent's turn will now be skipped properly.
+
+  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.\nUseful for certain corner cases or if you want to challenge yourself with the Comprehensive Rules:\ne.g. the opposite cost order is needed if activating an animated "Halo Fountain" that's also tapped.
+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

@@ -10,20 +10,19 @@
   - [Advanced search](Advanced-Search.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)
-    - [Equipments and Items](Adventure/Equipments-and-Items.md)
-    - [Keyboard Shortcuts](Keyboard-Shortcuts.md)
-    - [Controller Support](Adventure/GAMEPAD.md)
-    - [Console and Cheats](Adventure/Console-and-Cheats.md)
 
-  - [Modding and content creation](Adventure/Modding.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)
 
+  - [Modding & content creation](Adventure/Modding.md)
     - [Create Enemies](Adventure/Create-Enemies.md)
     - [Create Rewards](Adventure/Create-Rewards.md)
     - [Create Maps](Adventure/Create-new-Maps.md)
@@ -45,22 +44,23 @@
   - [Restrictions / Conditions](Card-scripting-API/Restrictions.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](Development/Snapshots-and-Releases.md)
+  - [Snapshots & Releases](Development/Snapshots-and-Releases.md)
   - [Android Builds](Development/Android-Builds.md)
   - [Dev Mode](Development/DevMode.md)
   - [Ownership](Development/ownership.md)
   - [Docker Container](docker-setup.md)
 
-- [Customization and Themes](Themes.md)
-  - Skins
-  - Sounds
-  - [Music](Custom-Music.md)
+- Customization & Themes
+  - [Skins](Skins.md)
+  - [Sounds & Music](Custom-Audio.md)
   - [Card Images](Card-Images.md)
   - [File Formats](File-Formats.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)

forge-game/src/main/java/forge/game/ability/effects/EarthbendEffect.java

@@ -31,7 +31,7 @@ public class EarthbendEffect extends SpellAbilityEffect {
 
         sb.append(amount).append(". (Target land you control becomes a 0/0 creature with haste that's still a land. Put  ");
         sb.append(Lang.nounWithNumeral(amount, "+1/+1 counter"));
-        sb.append(" on it. When it dies or is exiled, return it to the battlefield tapped.)");
+        sb.append(" on it. When it dies or is exiled, return it to the battlefield tapped under your control.)");
 
         return sb.toString();
     }
@@ -74,7 +74,7 @@ public class EarthbendEffect extends SpellAbilityEffect {
     protected void buildTrigger(SpellAbility sa, Card c, String sbTrig, String zone) {
         final Card source = sa.getHostCard();
         final Game game = source.getGame();
-        String trigSA = "DB$ ChangeZone | Defined$ DelayTriggerRemembered | Origin$ " + zone + " | Destination$ Battlefield | Tapped$ True";
+        String trigSA = "DB$ ChangeZone | Defined$ DelayTriggerRemembered | Origin$ " + zone + " | Destination$ Battlefield | Tapped$ True | GainControl$ You";
 
         final Trigger trig = TriggerHandler.parseTrigger(sbTrig, CardCopyService.getLKICopy(source), sa.isIntrinsic());
         final SpellAbility newSa = AbilityFactory.getAbility(trigSA, sa.getHostCard());

forge-gui-desktop/src/main/java/forge/screens/home/settings/VSubmenuPreferences.java

@@ -438,6 +438,9 @@ public enum VSubmenuPreferences implements IVSubmenu<CSubmenuPreferences> {
         pnlPrefs.add(cbpSwitchStates, comboBoxConstraints);
         pnlPrefs.add(new NoteLabel(localizer.getMessage("nlSwitchStates")), descriptionConstraints);
 
+        pnlPrefs.add(cbSROptimize, titleConstraints);
+        pnlPrefs.add(new NoteLabel(localizer.getMessage("nlSrOptimize")), descriptionConstraints);
+
         // Sound options
         pnlPrefs.add(new SectionLabel(localizer.getMessage("SoundOptions")), sectionConstraints + ", gaptop 2%");
 
@@ -455,8 +458,7 @@ public enum VSubmenuPreferences implements IVSubmenu<CSubmenuPreferences> {
 
         pnlPrefs.add(cbAltSoundSystem, titleConstraints);
         pnlPrefs.add(new NoteLabel(localizer.getMessage("nlAltSoundSystem")), descriptionConstraints);
-        pnlPrefs.add(cbSROptimize, titleConstraints);
-        pnlPrefs.add(new NoteLabel(localizer.getMessage("nlSrOptimize")), descriptionConstraints);
+
         // Keyboard shortcuts
         pnlPrefs.add(new SectionLabel(localizer.getMessage("KeyboardShortcuts")), sectionConstraints);
 

forge-gui/forge.profile.properties.example

@@ -77,7 +77,7 @@ cardPicsDir=
 cardPicsSubDirs=
 
 # This is the top level directory that forge will use for storing and
-# locating decklists. The default value (for all plaforms) is:
+# locating decklists. The default value (for all platforms) is:
 #   <the userDir defined above>/decks/
 decksDir=
 

forge-gui/release-files/INSTALLATION.txt

@@ -1,4 +1,4 @@
-The Forge archive includes a docs folder and we ask that you spend a few minutes reading this as it contains some information that may prove useful. You can open the .md (markdown) files with any plain Editor.
+The Forge archive includes a docs folder and we ask that you spend a few minutes reading this as it contains some information that may prove useful. You can open the .md (markdown) files with any plain Editor - or just browse it online from our GitHub wiki.
 
 The archive format used for the Forge distribution is ".tar.bz2". There are utilities for Windows, Mac OS and the various *nix's that can be used to extract/decompress these ".tar.bz2" archives. We recommend that you extract/decompress the Forge archive into a new and unused folder.
 

forge-gui/res/cardsfolder/l/leech_fanatic.txt

@@ -2,5 +2,5 @@ Name:Leech Fanatic
 ManaCost:1 B
 Types:Creature Human Warlock
 PT:2/2
-S:Mode$ Continuous | Affected$ Card.Self | AddKeyword$ Lifelink | Condition$ PlayerTurn | Description$ During your turn, CARDNAME has first strike.
+S:Mode$ Continuous | Affected$ Card.Self | AddKeyword$ Lifelink | Condition$ PlayerTurn | Description$ During your turn, CARDNAME has lifelink.
 Oracle:During your turn, Leech Fanatic has lifelink.

forge-gui/server.preferences.example

@@ -1,5 +1,4 @@
-# Forge server port. Values under 1024 won't work on Mac OSX or on the various
-# *nixes.
+# Forge server port. Values under 1024 won't work on Mac OSX or on the various *nixes.
 NET_PORT=36743
 #This determines if Forge should attempt to open a port automatically, on supported routers, using UPnP
 UPnP=ASK # ASK, ALWAYS, NEVER