User guide update (Card-Forge#9115)

Author: tool4ever

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/Custom-Music.md docs/Custom-Audio.mddocs/Custom-Music.md renamed to docs/Custom-Audio.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)