jeirmeister/Cockatrice
1
0
Fork 0
mirror of https://github.com/Cockatrice/Cockatrice.git synced 2026-11-05 09:33:25 -08:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

[Docs] Add app logo to main page + cleanup (#7471)
Some checks failed
CodeQL / Analyze (cpp) (push) Has been cancelled
Details
CodeQL / Analyze (actions) (push) Has been cancelled
Details
Build Docker / Servatrice (arm) (push) Has been cancelled
Details
Build Docker / Servatrice (x86) (push) Has been cancelled
Details
Build Docker / Publish multi-platform Servatrice image (push) Has been cancelled
Details

Browse source 
* Add app logo to main page

* rename pages folder

* Add link + cleanup

* Cleanup file extension patterns

* Update Doxygen README.md
This commit is contained in:
tooomm 2026-10-10 23:48:37 +02:00 • committed by GitHub
parent efc7e7a079
commit 7fa6234eee
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
54 changed files with 252 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

135
doc/doxygen/pages/user_documentation/card_pictures/custom_card_pictures.md Normal file
View file

@ -0,0 +1,135 @@
@page custom_card_pictures Custom Card Pictures
There are four ways to make Cockatrice use custom artwork for your cards:
- Placing image files in the **CUSTOM pictures folder**.
- Providing a **custom card database** that points each printing at a picture URL via the `picurl` property.
- Writing your **own download URL templates**.
- Setting an **image override** for a single card from inside the deck editor.
Each of these is described below. If pictures are missing or wrong, see @ref fixing_card_pictures instead.
# Custom Pictures Folder (CUSTOM)
Any image file placed in the CUSTOM folder is used as the card picture, and no download is attempted for cards that
match a file there.
- The folder is `<pictures directory>/CUSTOM/`. The pictures directory is configured on the 'General' settings tab,
under 'Directories' → 'Pictures directory'.
- Any image format Qt can decode is accepted (PNG, JPG/JPEG, WebP, GIF, BMP, ...); the file extension is not filtered,
so even an extension-less file is picked up if the decoder recognizes its content.
- Files are indexed by their name, so you can organize them into subfolders freely.
- New or changed files are picked up automatically within a few seconds — no client restart is required.
The file name must match the card using one of the naming schemes below. Both `_` and `-` are accepted as separators,
and the file extension is ignored when matching:
| Scheme | Example file name |
| --------------------------- | ------------------------------------------------------- |
| Card Name | `Example Card.png` |
| Card Name + Set | `Example Card_DDL.png` |
| Card Name + Set + Collector | `Example Card_DDL_43.png` |
| Set + Collector + Card Name | `DDL_43_Example Card.png` |
| Card Name + Provider ID | `Example Card_0b23cdc8-d413-4fb1-8470-474221b10fe2.png` |
The name used for matching is the *corrected* card name. Correction removes the split-card separator ` // ` and the
characters reserved in Windows file names (`* < > : " \ ?` and control characters), and turns `/` into a space, so the
"Example // Card" card is matched by a file named `ExampleCard.png`, not `Example // Card.png`. Most other punctuation
(commas, apostrophes, `!`, ...) is left untouched.
\attention A file in the CUSTOM folder always wins over downloaded pictures, even if it is the wrong image. Delete the
file if you want to see the downloaded artwork again.
The naming conventions are the same as those recognized in the set-named subfolders and in `downloadedPics`, and are
documented for developers in @ref loading_card_pictures.
# Custom Card Database (picurl)
If you maintain your own card database (see the
[Custom Cards & Sets](https://github.com/Cockatrice/Cockatrice/wiki/Custom-Cards-&-Sets) wiki), each printing's `<set>`
tag can carry a `picurl` attribute containing a full URL for that printing's picture:
```xml
<set picurl="https://example.com/cards/example-card.jpg" ...>
```
Cockatrice tries this URL **before** the configured download URL templates, so it is the most direct way to provide
custom artwork for a specific printing.
- The URL should start with `http://` or `https://`; the scheme is not validated, so make sure it is absolute or the
download may silently fail.
- When you change a `picurl` for a card whose picture was already downloaded and cached, delete the stored images
(Storage tab → 'Delete Saved Images' / 'Delete Cached Images') so Cockatrice fetches the new URL.
# Custom Download URL Templates
The built-in download URLs are templates: Cockatrice replaces reference points in the URL with information about the
card and its printing. You can write your own templates in 'Cockatrice → Settings' (Ctrl + Shift + P by default), on
the 'Deck Editor' tab, in the 'URL Download Priority' section.
The following reference points are available:
| Reference point | Description | Example |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `!name!` | Card name | `Example Card` |
| `!name_lower!` | Card name, lower case | `example card` |
| `!corrected_name!` | Corrected card name | `ExampleCard` (instead of "Example // Card") |
| `!corrected_name_lower!` | Corrected card name, lower case | `examplecard` |
| `!sflang!` | Scryfall language code for the current client language; defaults to English when the language has no localized images | `en`, `zhs` |
| `!setcode!` / `!setcode_lower!` | Set code | `EXM` / `exm` |
| `!setname!` / `!setname_lower!` | Full set name | `Exemplary Set` / `exemplary set` |
| `!set:<property>!` | A property of this printing, e.g. `muid` (Gatherer multiverse ID), `uuid` (Scryfall UUID), `num` (collector number), `rarity` | `373549` |
| `!prop:<property>!` | A property of the card, e.g. `side` (front/back), `colors`, `cmc`, `coloridentity`, `type`, `pt`, and the format legality statuses | `front` |
The `!set:...!` and `!prop:...!` reference points support two modifiers:
- `_fill_with_<text>` pads the value with the given text, right-aligned, e.g. `!set:num_fill_with_000!` turns collector
number `1` into `001`. If the value is longer than the fill text, the template is skipped.
- `_substr_<start>_<length>` extracts a substring, e.g. `!set:num_substr_2_2!` takes two characters starting at the
third. If the substring would extend past the end of the value, the template is skipped.
Substituted values are URL-encoded. A template that asks for a property the card or printing does not have is skipped,
and the next template in the list is tried instead.
\attention Custom URLs should start with `http://` or `https://`. As with `picurl`, the scheme is not validated before
the URL is handed to QNetworkAccessManager, so use an absolute URL or the download may silently fail.
Some working examples:
```text
https://cards.scryfall.io/large/!prop:side!/!set:uuid_substr_0_1!/!set:uuid_substr_1_1!/!set:uuid!.jpg
https://api.scryfall.com/cards/!set:uuid!?format=image&face=!prop:side!
https://api.scryfall.com/cards/multiverse/!set:muid!?format=image
https://gatherer.wizards.com/Handlers/Image.ashx?multiverseid=!set:muid!&type=card
https://gatherer.wizards.com/Handlers/Image.ashx?name=!name!&type=card
```
See the [Custom Picture Download URLs](https://github.com/Cockatrice/Cockatrice/wiki/Custom-Picture-Download-URLs)
wiki for more examples and ideas.
\attention Keep in mind that templates using `!name!` or `!set:muid!` resolve by name or multiverse ID, not by the
exact printing. Only the Scryfall `!set:uuid!` templates always return the exact printing requested. See
@ref fixing_card_pictures for more on this.
# Image Overrides
The quickest way to give one card custom art is an image override: right-click the card in the deck editor's printing
selector and open the **Image Overrides** submenu of the context menu.
- **Load Custom Image...** — choose a picture file (the dialog suggests PNG, JPG/JPEG and WebP); it becomes that card's
artwork immediately.
- **One entry per alternate printing** of the card, labeled `<set> <collector number>` (hovering an entry previews that
printing's artwork). Selecting one makes the card use that exact printing's picture, so e.g. a basic land can be shown
with any of its artworks.
- **Clear Custom Image** — removes the stored override and returns the card to normal resolution. It is only available
while the card has a stored override.
Overrides are stored as `.png` files in `<pictures directory>/downloadedPics/`, under the "Naming scheme" configured on
the Storage settings page, and are matched the same way as downloaded images. Because local files are checked before any
URL is requested, an override always wins over downloaded artwork and `picurl` for that card. The override exists only on
the machine it was created on - it is not part of the deck file - so a card with a stored override shows normally on
another computer.
\attention If you also keep a matching file in the CUSTOM folder, that file is matched before the override. When you
change an override, use **Clear Custom Image** so the stored `.png` is replaced; manually deleting the file in
`downloadedPics/` has the same effect.

15
doc/doxygen/pages/user_documentation/deck_management/creating_decks.md Normal file
View file

@ -0,0 +1,15 @@
@page creating_decks Creating Decks
Creating a new deck is done using either the \ref editing_decks_classic or \ref editing_decks_visual.
They can be accessed either by clicking the "Create Deck" button in the TabHome screen, which will open the default deck
editor configured in the "User Interface" -> "Deck editor/storage settings" -> "Default deck editor type" setting, or
by selecting "Deck Editor" or "Visual Deck Editor" under the "Tabs" application menu located at the top.
# Further References
- See @ref editing_decks for information on how to modify the attributes and contents of a deck in the Deck Editor
widgets.
- See @ref exporting_decks for information on how to store and persist your deck either in-client or to external
services.
- See @ref importing_decks for information on how to import existing decks either in-client or from external services

6
doc/doxygen/pages/user_documentation/deck_management/editing_decks.md Normal file
View file

@ -0,0 +1,6 @@
@page editing_decks Editing Decks
- @subpage editing_decks_classic
- @subpage editing_decks_visual
- @subpage editing_decks_printings

54
doc/doxygen/pages/user_documentation/deck_management/editing_decks_classic.md Normal file
View file

@ -0,0 +1,54 @@
@page editing_decks_classic Classic Deck Editor
\image html classic_deck_editor.png width=900px
# Editing Basic Deck Information
Editing basic deck information is done through the deck dock widget (DeckEditorDeckDockWidget).
\image html deckeditordeckdockwidget.png
This widget allows editing:
- The name
- The comments
- The banner card, which is used to represent the deck in the visual deck storage
- The tags, which are used for filtering in the visual deck storage
# Adding Cards
Adding cards is done using the list of cards in the database presented in the list view on the left.
\image html classic_database_display.png
Cards can be added by either double-clicking an entry, pressing return with an entry selected to add it to the mainboard
or pressing ctrl/cmd + return to add it to the sideboard.
There are also buttons for these two functions on the right of the search bar above the list view.
\image html classic_database_display_add_buttons.png
# Modifying the Deck List
To modify or remove cards in the deck list, the tree list view in the deck dock widget can be used.
\image html deck_dock_deck_list.png
Just above the list, at the top right, there are four buttons to manipulate the currently selected card(s):
- Increment Card
- Decrement Card
- Remove Card
- Switch Card between Mainboard and Sideboard
\image html deck_dock_deck_list_buttons.png
Additionally, there is a combo box above the list, which may be used to change how cards are grouped in the list
display. This is only for visual display and does not affect how the list is saved.
\image html deck_dock_deck_list_group_by.png
# Modifying printings
For more information on modifying the printings in a deck see @ref editing_decks_printings

122
doc/doxygen/pages/user_documentation/deck_management/editing_decks_printings.md Normal file
View file

@ -0,0 +1,122 @@
@page editing_decks_printings Printing Selector
\image html printing_selector.png
# Purpose
The PrintingSelector allows editing the PrintingInfo associated with CardInfo%s contained in DeckList%s.
As described in PrintingInfo, a CardInfo can have different variations contained within the same or different CardSet%s.
PrintingSelector allows the user to choose a variation, as well as pinning a variation to be used as the preferred
printing in all cases where the 'default' or 'most preferred' image should be shown.
# Pre-requisites (User Interface)
To use the printing selector, ensure that you are using the Post-ProviderID change behavior (Checkbox as shown in the
image).
\image html printing_selector_pre_providerid.png
\attention This is the default behavior, unless you have explicitly changed it, in which case you will have seen a
warning as follows. Once again, checking this box will *disable* the new behavior and revert you to the legacy system
without the printing selector.
Disabling the printing selector:
\image html printing_selector_enable.png
Enabling the printing selector:
\image html printing_selector_disable.png
# Pre-requisites (Card Database)
The PrintingSelector requires each underlying CardInfo object to have a <set> entry with a *unique* providerID attribute
for each variation that should be displayed.
Here is an example, that first defines three sets, and then the 'Ace of Hearts' card with three variations.
```xml
<set rarity="common" uuid="00000000-0000-0000-0000-000000000033" num="51" muid="AH">PKR</set>
<set rarity="common" uuid="00000000-0000-0000-0001-000000000033" num="51" muid="AHSTD">STD</set>
<set rarity="common" uuid="00000000-0000-0000-0002-000000000033" num="51" muid="AHNBR">NBR</set>
```
```xml
<?xml version='1.0' encoding='UTF-8'?>
<cockatrice_carddatabase version="4">
<sets>
<set>
<name>PKR</name>
<longname>Cockatrice Poker</longname>
<settype>Custom</settype>
<releasedate>2025-11-15</releasedate>
</set>
<set>
<name>STD</name>
<longname>Standard Poker</longname>
<settype>core</settype>
<releasedate>2025-11-14</releasedate>
</set>
<set>
<name>NBR</name>
<longname>Numbers</longname>
<settype>core</settype>
<releasedate>2025-11-14</releasedate>
</set>
</sets>
<cards>
<card>
<name>Ace of Hearts</name>
<text>Ace of Hearts</text>
<prop>
<layout>normal</layout>
<side>front</side>
<type>Ace</type>
<maintype>Ace</maintype>
<manacost>14</manacost>
<cmc>14</cmc>
<colors>H</colors>
<coloridentity>H</coloridentity>
<format-standard>legal</format-standard>
</prop>
<reverse-related>Joker</reverse-related>
<token>0</token>
<tablerow>1</tablerow>
<cipt>0</cipt>
<upsidedown>0</upsidedown>
<set rarity="common" uuid="00000000-0000-0000-0000-000000000033" num="51" muid="AH">PKR</set>
<set rarity="common" uuid="00000000-0000-0000-0001-000000000033" num="51" muid="AHSTD">STD</set>
<set rarity="common" uuid="00000000-0000-0000-0002-000000000033" num="51" muid="AHNBR">NBR</set>
</card>
</cards>
</cockatrice_carddatabase>
```
# Using the Printing Selector
To use the PrintingSelector, first select a card in the DeckEditorDeckDockWidget:
\image html deck_dock_deck_list.png
You may add a variation to the mainboard by clicking the + and - buttons in the top row. The bottom row will add the
variation to your sideboard.
\image html printing_selector.png
You can also right-click a variation to pin it, which will move it to the top of the variation list for easy access and
additionally, use it as the default printing whenever the printing isn't explicitly specified (such as adding a card
from the database in the deck editor).
Only one printing may be pinned at a time.
Additionally, the PrintingSelector offers a navigation bar at the bottom to navigate through cards in your deck, as well
as an option to modify the variations of cards in bulk via the 'Bulk Selection' option.
\image html printing_selector_navigation.png
The search bar at the top may be used to filter the displayed variations and the cogwheel may be clicked to open up
additional settings.
\image html printing_selector_options.png

93
doc/doxygen/pages/user_documentation/deck_management/editing_decks_visual.md Normal file
View file

@ -0,0 +1,93 @@
@page editing_decks_visual Visual Deck Editor
\image html vde_overlap_layout_type_grouped.png width=1200px
# Editing Basic Deck Information
Editing basic deck information is done through the deck dock widget (DeckEditorDeckDockWidget).
\image html deckeditordeckdockwidget.png
This widget allows editing:
- The name
- The comments
- The banner card, which is used to represent the deck in the visual deck storage
- The tags, which are used for filtering in the visual deck storage
# Adding Cards
Adding cards is done by either using the "Quick search and add card" search bar at the top of the "Visual Deck View" tab
or by clicking on a picture of a card in the "Visual Database Display" tab.
See @ref visual_database_display for more information on how to utilize the visual database display.
# Modifying the Deck List
To modify or remove cards in the deck list, the tree list view in the deck dock widget can be used.
\image html deck_dock_deck_list.png
Just above the list, at the top right, there are four buttons to manipulate the currently selected card(s):
- Increment Card
- Decrement Card
- Remove Card
- Switch Card between Mainboard and Sideboard
\image html deck_dock_deck_list_buttons.png
Additionally, there is a combo box above the list, which may be used to change how cards are grouped in the list
display. This is only for visual display and does not affect how the list is saved.
\image html deck_dock_deck_list_group_by.png
# Modifying the visual deck layout
The visual deck editor displays cards visually, as opposed to simply in list form in the Deck Dock Widget. Each entry in
the deck list is represented by a picture. These entries are grouped together under their respective sub-groups.
Sub-groups may be collapsed (i.e. the pictures contained within them are hidden) by clicking on the name of the group in
the banner.
Cards may be displayed in a "Flat" layout, which displays each picture next to each other and ensures full
visibility for each card.
\image html vde_flat_layout_type_grouped.png width=1200px
or in an "Overlap" layout, which overlaps cards on top of each other (leaving the top 20% of
the card uncovered so names remain readable) and arranges them in stacks to save space and allow for an easy overview.
\image html vde_overlap_layout_type_grouped.png width=1200px
Additionally, it is possible to change how the cards in the deck list are grouped by selecting a different grouping
method from the combo box, either in the top left of the "Visual Deck View" tab or above the list view in the deck dock
widget.
Example - Cards grouped by suit/color:
\image html vde_flat_layout_color_grouped.png width=1200px
Furthermore, it is possible to change how the cards are sorted within the sub-group. This is done by clicking on the
button with the cogwheel icon next to the combo box that adjusts grouping in the top left of the "Visual Deck View" tab.
This presents a list of available sort criteria, which may be rearranged to change their priorities.
# Modifying printings
For more information on modifying the printings in a deck see @ref editing_decks_printings
# Deck Analytics
The visual deck editor offers a "Deck Analytics" tab, which displays information about:
- The mana curve
- The mana devotion
- The mana base
\image html vde_deck_analytics.png width=1200px
# Sample Hand
The visual deck editor offers a "Sample Hand" tab, which allows simulating drawing a configurable amount of cards from
the deck, which reduces the need to launch a single player game for testing purposes.
\image html vde_sample_hand.png width=1200px

151
doc/doxygen/pages/user_documentation/deck_management/exporting_decks.md Normal file
View file

@ -0,0 +1,151 @@
@page exporting_decks Exporting Decks
# Where to export?
There are two screens in the client which can be used to import decks, depending on the context.
- The deck editor tab
- The deck storage tab (not to be confused with the visual deck storage tab)
# The Deck Editor Tab
The deck editor tabs (Classic and Visual) offer three ways of export a deck:
- To a file on your local storage
- To your clipboard
- To an online service
## Local File Storage
To save a deck to a file on your local storage, select the "Save Deck" action in the "Deck Editor" or "Visual Deck
Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + S
to access this action.
Selecting this action will open a file picker dialog provided by your operating system. Simply enter a file name and
select a format (.cod is recommended) and confirm.
Just below the "Save Deck" action described above is the "Save Deck as..." option, which allows saving an existing file
under a different filename, which is useful for saving a different version or copy of a deck.
## From Clipboard
To save a deck to your clipboard, select the "Save deck to clipboard..." action in the "Deck Editor" or "Visual Deck
Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd +
Shift + C or Ctrl/Cmd + Shift + R to access this action.
Selecting this action will save the currently open deck list to your clipboard.
Saving the decklist without annotations will export the decklist, with each card being described in the following format
```
CARD_AMOUNT CARD_NAME (SET_SHORT_NAME) CARD_COLLECTOR_NUMBER
```
There is also the (no set info) option, which will simply export each card as
```
CARD_AMOUNT CARD_NAME
```
Mainboard and sideboard are delimited by a newline like so:
```
1 MainboardCard
1 OtherMainboardCard
1 SideboardCard
```
Saving the decklist as annotated will insert comments (marked with // in front of them).
It will first insert the name and any comments associated with the deck before separating each deck section into its own
newline delimited and annotated group.
Example: TODO: Adjust this to be non mtg based.
```
// Full Deck
// An example comment.
// 63 Maindeck
// 4 Ace
1 Ace of Clubs (PKR) 49
1 Ace of Diamonds (PKR) 50
1 Ace of Hearts (PKR) 51
1 Ace of Spades (PKR) 52
// 13 Face
1 Jack of Clubs (PKR) 53
1 Jack of Diamonds (PKR) 54
1 Jack of Hearts (PKR) 55
1 Jack of Spades (PKR) 56
1 King of Clubs (PKR) 57
1 King of Diamonds (PKR) 58
1 King of Spades (PKR) 60
1 Queen of Clubs (PKR) 61
1 Queen of Diamonds (PKR) 62
1 Queen of Hearts (PKR) 63
1 Queen of Spades (PKR) 64
2 King of Hearts (PKR) 59
// 44 Number
1 0 of Clubs (PKR) 1
1 0 of Diamonds (PKR) 2
1 0 of Hearts (PKR) 3
1 1 of Clubs (PKR) 11
1 1 of Diamonds (PKR) 12
1 1 of Hearts (PKR) 13
1 1 of Spades (PKR) 14
1 10 of Clubs (PKR) 5
1 10 of Diamonds (PKR) 6
1 10 of Hearts (PKR) 7
1 2 of Clubs (PKR) 17
1 2 of Diamonds (PKR) 18
1 2 of Hearts (PKR) 19
1 2 of Spades (PKR) 20
1 3 of Clubs (PKR) 21
1 3 of Diamonds (PKR) 22
1 3 of Hearts (PKR) 23
1 3 of Spades (PKR) 24
1 4 of Clubs (PKR) 25
1 4 of Diamonds (PKR) 26
1 4 of Hearts (PKR) 27
1 4 of Spades (PKR) 28
1 5 of Clubs (PKR) 29
1 5 of Diamonds (PKR) 30
1 5 of Hearts (PKR) 31
1 5 of Spades (PKR) 32
1 6 of Clubs (PKR) 33
1 6 of Diamonds (PKR) 34
1 6 of Hearts (PKR) 35
1 6 of Spades (PKR) 36
1 7 of Clubs (PKR) 37
1 7 of Diamonds (PKR) 38
1 7 of Hearts (PKR) 39
1 7 of Spades (PKR) 40
1 8 of Clubs (PKR) 41
1 8 of Diamonds (PKR) 42
1 8 of Hearts (PKR) 43
1 8 of Spades (PKR) 44
1 9 of Clubs (PKR) 45
1 9 of Diamonds (PKR) 46
1 9 of Hearts (PKR) 47
1 9 of Spades (PKR) 48
1 10 of Spades (PKR) 8
1 0 of Spades (PKR) 4
// 2 Joker
1 1 Joker (PKR) 10
1 2 Joker (PKR) 16
```
## From an online service
To export a deck to an online service, select the "Send deck to online service..." action in the "Deck Editor" or "
Visual Deck Editor" menu in the application menu bar at the top of the screen.
Selecting this action will open your browser with the selected service open and the deck list information from the
client supplied to it.
Currently supported services are DeckList and TappedOut.

62
doc/doxygen/pages/user_documentation/deck_management/importing_decks.md Normal file
View file

@ -0,0 +1,62 @@
@page importing_decks Importing Decks
# Where to import?
There are three screens in the client which can be used to import decks, depending on the context.
- The deck editor tab
- The pre-game lobby tab
- The deck storage tab (not to be confused with the visual deck storage tab)
# The Deck Editor Tab
The deck editor tabs (Classic and Visual) offer three ways of importing a deck:
- From a file on your local storage
- From your clipboard
- From an online service
## Local File Storage
To load a deck from a file on your local storage, select the "Load Deck" action in the "Deck Editor" or "Visual Deck
Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + O
to access this action.
Selecting this action will open a file picker dialog provided by your operating system. Simply select a supported file
here and it will be loaded.
Just below the "Load Deck" action described above is the "Load recent deck" option, which keeps a record of the last 10
loaded decks for quick access.
## From Clipboard
To load a deck from your clipboard, select the "Load deck from clipboard..." action in the "Deck Editor" or "Visual Deck
Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd +
Shift + V to access this action.
Selecting this action will open a new text editor dialog with the contents of your clipboard pasted inside it.
The import dialog expects each line to be a card with the following format:
TODO
Each card should be on a separate line and there should be no empty lines between cards. The first empty line between
two blocks of cards will be considered as the divider between mainboard and sideboard.
Selecting "Parse Set Name and Number (if available)" will automatically parse these options and attempt to resolve them
to valid provider IDs found in the card database. If this option is unselected, Cockatrice will import all cards as
versions without provider IDs, which means they will display to everyone according to their own user defined set
preferences, rather than being the same defined printing for everyone.
## From an online service
To load a deck from an online service, select the "Load deck from online service..." action in the "Deck Editor" or "
Visual Deck Editor" menu in the application menu bar at the top of the screen.
Selecting this action will open a dialog containing the contents of your clipboard pasted into it. If your clipboard
currently contains a supported URL, the dialog will accept it and close on its own, otherwise you may adjust the URL and
confirm.
The action will automatically import the deck from the online service without any other required user action.
Currently supported services are Archidekt, Deckstats, Moxfield, and TappedOut.

30
doc/doxygen/pages/user_documentation/index.md Normal file
View file

@ -0,0 +1,30 @@
@page user_reference User Reference
## Deck Management
- @subpage creating_decks
- @subpage importing_decks
- @subpage editing_decks
- @subpage exporting_decks
## Release Channels
- @subpage beta_release
## Settings
- @subpage settings_folder
## Card Pictures
- @subpage custom_card_pictures
## Troubleshooting
- @subpage fixing_card_pictures
- @subpage enabling_debug_logs
## Syntax Help
- @subpage search_syntax_help
- @subpage deck_search_syntax_help

54
doc/doxygen/pages/user_documentation/settings/beta.md Normal file
View file

@ -0,0 +1,54 @@
@page beta_release Beta Release
The beta version of Cockatrice features all the newest features before they make their way into the latest stable
release.
It allows us to test these features ahead of time and you to give feedback on them.
We release new betas very frequently and usually release a follow-up beta with a fix within a day or two if we break
anything. In contrast, stable releases are released much less frequently but ensured to be stable.
# What to Expect from the Beta
Using the beta and giving feedback on it helps us improve Cockatrice a lot.
We do not perform any automatic data collection so your voluntary feedback is the only way for us to get a sense of what
you enjoy, expect, or would like to change.
We highly appreciate your active participation and feedback.
That being said, some words of warning should be issued:
The beta release may contain unfinished features, bugs, or performance issues.
It is intended for testing and feedback and may be less stable than the default release.
We recommend using the beta only if you are comfortable encountering issues and helping us improve Cockatrice.
# Switching to the Beta
To switch to the Beta, navigate to your settings, using the Tab "Cockatrice → Settings" or Ctrl + Shift + P (default
shortcut).
Within the settings, in the first tab 'General', the first section 'Personal Settings' contains the setting 'Release
Channel'.
\image html release_channel_beta.png
Switch this to 'Beta'.
Afterwards, close your settings, and use the 'Help' tab to search for a client update. You should be prompted to install
the beta version.
# Switching back to Stable
Follow the same steps as above, but set Release Channel to 'Default'.
# Giving Feedback
If you encounter a bug or unexpected behavior while using the beta, please report it on:
- GitHub: https://github.com/Cockatrice/Cockatrice/issues
- Discord: https://discord.gg/4hNswvHeFd in #beta-testing
When reporting issues, please include:
- Your operating system
- The beta version number (found in 'Help → About Cockatrice')
- Steps to reproduce the problem, if possible

43
doc/doxygen/pages/user_documentation/settings/settings_folder.md Normal file
View file

@ -0,0 +1,43 @@
@page settings_folder Settings Folder and Backups
Cockatrice keeps all of its preferences in a settings folder on your computer, one `.ini` file per
group of settings (appearance, sound, decks, and so on). Open it from the main window via
Help → Open Settings Folder.
# The Per-File Migration
Older versions of Cockatrice stored every setting in a single `global.ini` file. The settings were
split into per-group `.ini` files so that unrelated groups no longer share one file. The first time
you start a version that uses the new layout, your settings are moved into the new files
automatically and nothing is lost. The old `global.ini` is kept next to the new files as
`global.ini.old`.
# Automatic Backups
Both migrations overwrite files in the settings folder in place, so before either one runs,
Cockatrice copies the whole folder to a timestamped backup folder:
```
<data folder>/settings-backup-20261002-193000/
```
The backup folder sits next to the settings folder, not inside it. Every backup is kept, so if
settings ever end up wrong you can compare against, or copy files back from, the earlier snapshot.
Backups are only created when a migration actually has work to do, so a normal start creates
nothing.
# Downgrading
Settings migrations only run forwards. If you ever go back to an older version of Cockatrice, that
version does not read the new per-group files, so it will start with default settings.
Before downgrading, copy your settings folder somewhere safe, for example:
- Linux: `~/.local/share/Cockatrice/settings/`
- macOS: `~/Library/Application Support/Cockatrice/settings/`
- Windows: `%LOCALAPPDATA%\Cockatrice\settings\`
Portable installs keep the settings folder in the `data` folder next to the executable.
Copying that folder back after downgrading restores your settings. The automatic backup folder from
the migration is there as a second copy of the same data if you need it.

142
doc/doxygen/pages/user_documentation/troubleshooting/enabling_debug_logs.md Normal file
View file

@ -0,0 +1,142 @@
@page enabling_debug_logs Enabling Debug Logs
Cockatrice ships with a "diagnostics mode" that prints detailed debug messages about what the client is doing. This is
extremely useful when asking for help, because it shows exactly what happened: which URL the card picture loader tried,
whether it found or missed a file on disk, whether a download succeeded or failed, which redirects were followed, and
much more. Each of these messages belongs to a category, and you can enable or disable categories individually.
Don't worry, this sounds more technical than it is. You only need to do two things: create one small text file, and tell
Cockatrice where it is. There are no installation steps and you can undo everything later (see [When you are
done](#when-you-are-done)).
# Step 1: Create the file
Open a plain text editor (Notepad on Windows, TextEdit on macOS, or any text editor on Linux) and paste the following
content:
```ini
[Rules]
# The default log level is info
*.debug = false
# Turn on debug level logs for the card picture loader and all its sub categories
card_picture_loader.* = true
```
Save the file with the exact name `qtlogging.ini` in a place you can find again, for example your Documents folder.
\attention The file name matters: it must be `qtlogging.ini`, not `qtlogging.ini.txt`. If your text editor adds a
`.txt` extension automatically, you need to stop it from doing so (see below). On macOS, TextEdit must be switched to
plain text mode first via 'Format → Make Plain Text'.
The file contains one rule per line. The `*.debug = false` rule turns off debug messages everywhere by default, and the
`card_picture_loader.* = true` line then re-enables them for the card picture loader. The `.*` at the end means "this
category and all of its sub categories". To enable a different category instead, just replace that line with the
category name of your choice, for example `card_database.loading = true` or `window_main.startup = true`.
# Step 2: Tell Cockatrice where the file is
Cockatrice does not know about the file yet. You have to point it there by setting an environment variable called
`QT_LOGGING_CONF` to the full location of your file. How to do this depends on your operating system:
**Windows**
1. Press the Windows key, type "environment variables", and open "Edit the system environment variables".
2. Click "Environment Variables...", then under "User variables" click "New...".
3. Set "Variable name" to `QT_LOGGING_CONF` and "Variable value" to the full path of your file, for example
`C:\Users\YourName\Documents\qtlogging.ini`.
4. Confirm all dialogs, then close and reopen Cockatrice.
Alternatively, if Cockatrice is installed in a folder you can write to, you can simply place the `qtlogging.ini` file
directly next to the Cockatrice executable (in the same folder as `cockatrice.exe`) and skip the environment variable
altogether. Note that this copy may be replaced when you update the client.
**macOS**
Open the Terminal app (it is in 'Applications → Utilities') and run the following two commands, replacing the path
with the full location of your file:
```shell
launchctl setenv QT_LOGGING_CONF /path/to/qtlogging.ini
open -a Cockatrice
```
You can also use `export QT_LOGGING_CONF=/path/to/qtlogging.ini` to set the variable for the current terminal session.
The setting stays active until you log out or restart your Mac. If you have multiple users on the same Mac, be aware
that this setting only applies to your user account.
**Linux**
For a quick test, open a terminal and start Cockatrice with the file on the command line, replacing the path with the
full location of your file:
```shell
QT_LOGGING_CONF=/path/to/qtlogging.ini cockatrice
```
If this works and you want it to apply every time you start Cockatrice, add the following line to your `~/.profile`
file and log in again:
```shell
export QT_LOGGING_CONF="/path/to/qtlogging.ini"
```
# Step 3: See the logs
Now that debug logging is enabled, open Cockatrice and trigger the behavior you are investigating, for example by
opening a deck, reloading the card database, or starting a game.
The easiest way to see the logs is to use the built-in log viewer inside Cockatrice itself: open 'Help → View Debug
Log'. A window appears that shows the log messages live and keeps the most recent entries. It even has a 'Copy to
clipboard' button so you can paste the output into a bug report or a Discord message. This works the same on every
operating system.
If you prefer to capture everything to a file instead, start Cockatrice with the `--debug-output` option:
```shell
cockatrice --debug-output
```
Cockatrice then writes the full log to a file called `qdebug.txt` in the folder it was started from.
# Which categories are available?
Every message Cockatrice logs belongs to a category. The following table lists the most useful ones for troubleshooting,
grouped by area. Enable a category by adding a line like `category = true` to your `qtlogging.ini` file (or use a `.*`
suffix, e.g. `card_picture_loader.*`, to include all sub categories).
| What you want to see | Categories |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Card picture loading (URLs, local file hits/misses, downloads, redirects) | `card_picture_loader.*` |
| Card database loading and parsing | `card_database`, `card_database.loading`, `card_database.loading.success_or_failure`, `cockatrice_xml.*` |
| Card database update (running Oracle, progress, exit status, errors) | `card_database.update` |
| Card, set, and deck information | `card_info`, `card_list`, `deck_loader` |
| Startup sequence and update checks | `window_main.startup.*`, `release_channel`, `spoiler_background_updater` |
| User interface and themes | `theme_manager`, `sound_engine`, `flow_layout`, `flow_widget.*`, `pixel_map_generator`, `card_info_picture_widget` |
| Networking and servers | `local_client`, `remote_client`, `tapped_out_interface`, `servers_settings` |
| In-game logic | `player`, `game_scene.*`, `card_zone.*`, `view_zone`, `game_event_handler` |
| Dialogs and tabs | `dlg_settings`, `dlg_update`, `dlg_tip_of_the_day`, `tab_game`, `tab_message`, `tab_supervisor` |
| Settings and shortcuts | `settings_cache`, `shortcuts_settings` |
| Deck and card filtering | `filter_string`, `deck_filter_string`, `syntax_help` |
For example, to investigate why a card database update seems to fail, enable the card database categories:
```ini
[Rules]
*.debug = false
card_database = true
card_database.loading = true
card_database.loading.success_or_failure = true
card_database.update = true
cockatrice_xml.* = true
```
# When you are done
To turn the diagnostics back off, just reverse what you did: remove the `QT_LOGGING_CONF` environment variable (or
unset it again via `launchctl unsetenv QT_LOGGING_CONF` on macOS) and/or delete the `qtlogging.ini` file, then restart
Cockatrice. Leaving it on is harmless, but the extra logging can make the client slightly slower.
For the full details on how Cockatrice logging works, including the complete list of categories, see @ref logging.

118
doc/doxygen/pages/user_documentation/troubleshooting/fixing_card_pictures.md Normal file
View file

@ -0,0 +1,118 @@
@page fixing_card_pictures Fixing Card Pictures
This guide collects the common causes for card pictures not showing up, showing the wrong printing, or showing the
card back instead of the artwork, and how to fix them.
Work through the steps in order. In most cases the problem is caused by an outdated client, misconfigured download
URLs, stale local images, or a corrupted cache.
# Update Your Client
Picture handling bugs are fixed on a regular basis, so the first thing to try is updating your client.
Use the update check in 'Help → Check for Updates' (or look for the update prompt shown on startup).
If a fix has not yet made it into the latest stable release, it may already be available in the beta release. The beta
ships very frequently and usually receives a follow-up fix within a day or two if something breaks.
See @subpage beta_release for instructions on how to switch to the beta channel.
# Check Your Download URLs
Card pictures are downloaded from a list of URL templates. Each template is tried in order until one produces a valid
image, so the order matters: URLs at the top of the list are tried first.
The list can be found in 'Cockatrice → Settings' (or Ctrl + Shift + P by default), on the 'Deck Editor' tab, in the
'URL Download Priority' section. Make sure 'Download card pictures on the fly' is enabled and that the list contains
valid URLs. If you suspect the list has been modified or corrupted, press 'Reset Download URLs' to restore the
defaults.
For information on how to add your own custom URL templates, see the 'How to add a custom URL' link in the same
settings section, or @ref custom_card_pictures for a full reference of the URL reference points, the CUSTOM
pictures folder, and custom card databases.
# Check Your Local Picture Folder
Before any network request is made, Cockatrice looks for local image files. If a matching file is found on disk it is
shown instead of anything downloaded, even if it is the wrong image.
The pictures directory is configured on the 'General' settings tab, under 'Directories' → 'Pictures directory'.
Cockatrice checks the following locations, in order:
- The custom pictures folder (recursively indexed by file name).
- `<pictures directory>/<set code>/<card file name>`
- `<pictures directory>/downloadedPics/<set code>/<card file name>`
- `<pictures directory>/downloadedPics/<card file name>` (for export naming schemes without a set folder)
A file only matches when its name without the extension equals one of the recognized scheme patterns exactly.
The following import naming schemes are recognized (using both `_` and `-` as separators). The canonical table with
concrete example file names is on @ref custom_card_pictures:
| Scheme | Pattern |
| --------------------------- | -------------------------- |
| Card Name + Provider ID | `{name}_{providerId}` |
| Card Name + Set + Collector | `{name}_{set}_{collector}` |
| Set + Collector + Card Name | `{set}_{collector}_{name}` |
| Card Name + Set | `{name}_{set}` |
| Card Name | `{name}` |
If a picture you downloaded or placed manually is wrong, stale, or corrupted, delete the offending file. Pay special
attention to the `downloadedPics` subfolder: this is where the filesystem caching method writes downloaded images, and
after a provider outage it can permanently contain the wrong printing until you delete it manually.
If a card persistently shows artwork you assigned yourself, you may have an **image override** set for it. Right-click
the card in the deck editor's printing selector and use 'Image Overrides' → 'Clear Custom Image' to remove it (or
delete the stored `.png` in `downloadedPics/`). See @ref custom_card_pictures for details.
See @ref loading_card_pictures for details on how local images are loaded.
# Clear Caches
Cockatrice caches card pictures in three places. All of them can be managed on the 'Storage' settings tab:
- **Network cache** — downloaded images stored on disk. Press 'Delete Cached Images' to clear it.
- **Filesystem / image backup** — downloaded images written directly to `downloadedPics`. Press 'Delete Saved Images'
to clear it.
- **In-memory (pixmap) cache** — images currently held in RAM. Press 'Clear In-Memory Images' to clear it.
If a provider outage caused the wrong pictures to be downloaded and cached, clearing the network cache (and the
'Delete Saved Images' button if you use the filesystem caching method) will force Cockatrice to download the correct
images again. The redirect cache TTL (also on the Storage tab) controls how long previously seen redirects for
download URLs are remembered; lowering it can help if a URL used to redirect somewhere else.
# Restart the Client
After updating the client, changing the download URLs, moving or deleting local image files, or clearing caches, it is
recommended to restart Cockatrice so that all changes are fully picked up.
# Check Logs
Before changing any settings, check the existing logs first. Rate limit errors and most download errors are already
logged at warn level, so you may find the cause without enabling debug mode.
Open 'Help → View Debug Log' and look for error or warning messages related to card picture loading. If you need more
detail than the default log level provides, see below.
# Enable Picture Loader Debug Logs
If the steps above did not solve the problem, you can turn on a "diagnostics mode" that prints what the picture loader
is actually doing: which URL it is trying, whether it found or missed a file on disk, whether the download succeeded or
failed, and which redirects it followed. This information is extremely useful when asking for help.
See @subpage enabling_debug_logs for a step-by-step guide on how to enable the logs, including instructions
for Windows, macOS, and Linux.
# Provider Accuracy
Cards in Cockatrice are identified by a provider ID, which is the Scryfall UUID of a specific printing. Decks store
this ID, which is why the exact printing a card was added as can be looked up again.
The Scryfall URL templates built into Cockatrice use this provider ID directly (`!set:uuid!`), so they always download
the exact printing that was requested.
The Gatherer URL templates, on the other hand, do **not** use the provider ID. They resolve pictures by multiverse ID
(`!set:muid!`) or by card name (`!name!`) only. As a result they may return a different printing than the one the
provider ID refers to, or no picture at all for cards Gatherer does not know. If you need pictures to match the exact
printing of a card, make sure the Scryfall URLs are at the top of your download URL priority list and consider removing
or demoting the Gatherer URLs.