40 KiB
Advanced concepts and maintenance
Back to the installation guide
Detailed chapters for creating custom sets, building and publishing assets, understanding installer behavior, and checking decks. Run repository commands from the repository root; source and output paths below are relative to that root.
Chapters
- Layout
- Add artwork and descriptions
- Automatically put TOML text on a card
- Topic files and alternative artwork
- Add a set
- Generate XML and build packages
- Manual customsets.zip replacement
- One-line installation and updates (Linux/macOS)
- Windows installation (PowerShell)
- Mock deployment
- Jenkins CI and publication
- Check your deck collection
- Servatrice configuration backup
- License
Layout
sets/TKR/
set.toml Shared set metadata
command_zones.toml Individually named Command Zone tokens
reminders.toml Automatically typeset rules reminders
templates/reminders/ Original blank reminder templates
artwork/
command-zone/ Command Zone artwork variants
command-zone-default.png
command-zone-ajani.png
...
archives/customtokens.zip Legacy XML snapshot (not used by CI)
scripts/render_cards.py Pillow text layout on reminder templates
assets/fonts/ Bundled DejaVu Serif fonts and license
requirements-build.lock Pinned, hash-checked rendering dependency
scripts/generate_xml.py TOML validation and XML generation
scripts/build.py Generate XML and build ZIPs
scripts/publish.py CI payload validation and atomic publication
scripts/install.py Source for the generated one-line installer
tests/ Installer and publication safety tests
Jenkinsfile Jenkins build, archive, and publication pipeline
dist/ Generated ZIPs (ignored by Git)
deploy.sh Bash deployment preview
deploy.ps1 PowerShell deployment preview
AGENTS.md Contributor and agent instructions
Add artwork and descriptions
Edit sets/TKR/command_zones.toml or another topic TOML file, not XML. Put new images in sets/TKR/artwork/,
then append one [[tokens]] block per card. XML, artwork URLs, and installer
checksums are generated for you. For example, after adding Soldier.png:
[[tokens]]
id = "soldier-white" # Stable identity; keep this when renaming a card.
name = "Soldier"
artwork = "artwork/Soldier.png"
description = """
Vigilance
Your explanatory text can span several lines.
"""
type = "Creature — Soldier"
colors = "W"
power = 1
toughness = 1
Run python3 scripts/build.py to regenerate XML and ZIPs, then inspect
dist/sets/TKR/01.customtokens.xml. Commit the TOML and artwork. Do not commit
anything in dist/ or maintain another XML copy alongside the TOML.
The example is illustrative; no Soldier artwork is included in this repository.
Command Zone illustrations live in sets/TKR/artwork/command-zone/, with
command-zone-<subject>.png filenames (numbered suffixes distinguish variants).
There are twenty-seven separately named Command Zone tokens: default, Ajani, Chandra, Elesh Norn,
Garruk, Jace, Karn, Karona, two Liliana variants, Nicol Bolas, Nissa, Tamiyo, Teferi,
Ugin, Urza, Yawgmoth, Academy Ruins, Black Lotus, Boseiju (Who Endures), Cabal
Coffers, Gaea’s Cradle, Serra’s Sanctum, Tolarian Academy, and Valakut (the Molten
Pinnacle), Armageddon, and Dark Ritual. The original default remains named
Command Zone, with collector number 1 and its original UUID. The other 26 are
named Command Zone - <subject> (for example Command Zone - Garruk), each with
one artwork. This works around the inability to choose a token's printing in game.
They keep the former printing UUIDs and collector numbers, with the same shared
rules wording copied into each TOML entry. Apply wording changes to all entries.
Existing Command Zone deck entries continue to use the default token. Select a
Command Zone - <subject> entry when you want another artwork. If you saved a
deck during the temporary Command Zone - Default rename, change that entry back
to Command Zone; saved card names are not automatically rewritten.
The installer replaces the existing XML and installs the newly named image files;
old Command Zone_<UUID>.png files are left in place. The original default UUID
still identifies the default artwork. The checker recognizes both naming styles; neither counts as an actual
commander, and Spellbook excludes both from the playable card list.
Publication uses image basenames, so the default artwork URL is
https://assets.dandaedre.com/mtg/cards/command-zone-default.png.
Required token fields are id, name, artwork, and description. Artwork paths
are relative to the set directory and must name an existing PNG, JPEG, WebP, or
GIF under artwork/. Multiline descriptions preserve internal line breaks; outer
whitespace is trimmed. XML special characters such as & and < are escaped
for you. Use TOML strings for values such as "*" or "1+*".
| Optional token field | Default / purpose |
|---|---|
type |
"Token"; for example "Emblem" or "Creature — Soldier". |
colors |
""; copied to color identity unless overridden in properties. |
mana_cost |
""; mana value defaults to zero, override properties.cmc if needed. |
power, toughness |
Omitted unless supplied; integer or string. |
number |
The stable id; provide an integer/string for a specific collector number. |
uuid |
A deterministic UUID derived from set code and token ID. Override only to preserve an imported card identity. |
rarity |
"common". |
tablerow |
3; accepts 0 through 3. |
properties |
Additional Cockatrice <prop> values, or overrides of generated defaults. |
For advanced properties, add a table inside the current token block, before
starting the next [[tokens]] block:
[tokens.properties]
format-commander = "legal"
cmc = 0
Generated properties default to layout = "normal", side = "front", and
maintype equal to the part of type before —. Every entry is a token
(<token>1</token>). Names and IDs must be unique within a set, and names must
be usable as local artwork filenames (no slashes or control characters).
Artwork basenames and XML filenames must be unique across all sets because the
public hosting directories are flat. Unknown fields fail validation to catch typos.
Keep the set code and token IDs stable: generated UUIDs do not change when a card is renamed, its text/artwork changes, or entries are reordered. The existing Command Zone token retains its explicit imported UUID and collector number. Renaming installed cards or XML filenames may leave old local files behind; the installer does not automatically delete them.
Automatically put TOML text on a card
sets/TKR/reminders.toml contains seven distinct reminder tokens:
| Token | Rules covered |
|---|---|
| Reminder - Trigger Order | Priority, APNAP, trigger ordering, and resolution. |
| Reminder - Layers | Layers 1–7, layer 1/7 sublayers, timestamps, and dependencies. |
| Reminder - Replacement Effects | Who chooses, mandatory ordering, and rechecking the modified event. |
| Reminder - Priority and the Stack | Holding/passing priority, resolution, and responding. |
| Reminder - State-Based Actions | When checks happen, lethal damage, zero toughness, and the legend rule. |
| Reminder - Commander Zone Changes | Graveyard/exile choices, hand/library replacements, and commander tax. |
| Reminder - Combat Timing | Windows around attackers, blockers, and combat damage. |
Each has its own stable token ID, UUID, generated image, and editable text box.
These are separate cards, not alternative printings of one reminder. Each token's
description is the single source for both visible image text and Cockatrice XML text. The original blank images are preserved in
sets/TKR/templates/reminders/; only rendered cards are packaged and published.
To make another reminder, add a token with an output artwork path and a render table:
[[tokens]]
id = "my-reminder"
name = "My Reminder"
type = "Emblem"
artwork = "artwork/reminders/my-reminder.png" # Generated PNG, not an input file.
description = """
Your rules or reminder text here.
Use blank lines to separate paragraphs.
"""
[tokens.render]
template = "templates/reminders/reminder-larger.png"
title = "MY REMINDER" # Defaults to the card name.
box = [100, 155, 655, 1100] # Left, top, right, bottom in original image pixels.
font_size = 27 # Preferred body size; shrinks only as needed.
min_font_size = 23 # Fail the build instead of shrinking further/clipping.
title_size = 36
color = "#192b3b" # Optional dark blue ink.
footer = "Your short source or note"
Run the normal build, then open
dist/sets/TKR/artwork/reminders/my-reminder.png. Do not save that generated PNG
in the source artwork folder: the generator rejects overwriting a source image.
Templates must be inside the set's templates/ folder. Choose a box that stays
inside its blank panel; the narrower reminder.png needs a narrower box than
reminder-larger.png. Text is wrapped automatically, blank lines are preserved,
and excessively long text or words fail with an explicit error. This is plain
text, not Markdown. Rendering currently applies to a token's primary artwork;
existing alternative printings continue to use supplied images.
The renderer uses the bundled DejaVu Serif regular/bold faces with dark ink and a
small gold rule under the title. The license is in assets/fonts/LICENSE-DejaVu.txt.
Using these files avoids depending on whatever fonts a Jenkins worker happens to
have. Pillow is pinned and hash-locked; no runtime font downloads are needed.
The installer itself still requires no image-rendering packages.
The trigger-order reminder paraphrases CR 101.4, 117.4–117.5, 603.3–603.3b, and 605.4a. Layers summarizes 613.1–613.4 and 613.7–613.8; replacement effects summarizes 614.1, 614.4–614.6, and 616.1a–g. The additional cards cite 117.1–117.5 (priority), 704.3–704.5 and 702.12b (state-based actions), 903.8–903.9b (Commander), and 507–510, 509.1h, and 117 (combat). All were checked against the official Comprehensive Rules effective November 6, 2026. The source URL and date are also recorded in the TOML. This is a concise reminder, not a replacement for the full rules. Review the wording when those rules change; CI does not download or automatically rewrite rules text.
Topic files and alternative artwork
Each set can contain any number of topic files, such as command_zones.toml,
soldiers.toml, or something_else.toml. The generator reads all *.toml files
directly in the set directory, in filename order, and merges their [[tokens]]
entries into one XML. Subdirectories are for artwork, not token TOML files.
Declare [set] exactly once, conventionally in set.toml. Existing combined
files are still supported. Duplicate token names/IDs and printing numbers/UUIDs
are checked across all topic files.
To add another image for the same token, append an alternative to that token
before the next [[tokens]] block:
[[tokens.alternatives]]
id = "ajani"
artwork = "artwork/command-zone/command-zone-ajani.png"
Each alternative requires id and artwork; optional number, uuid, and
rarity override its defaults. Otherwise its collector number is
<token-id>-<alternative-id>, its UUID is derived from the set/token/alternative
IDs, and its rarity inherits the token's rarity. Keep these IDs stable when
renaming or moving topic files. Text and card properties are inherited from the
single parent token, so corrections only need to be made once. Use a separate
[[tokens]] entry if the name or rules text should differ.
Cockatrice XML represents alternatives as multiple <set> printing elements
inside one <card>. The generator still supports this representation for other cards. Command Zone
artworks currently use separate named tokens instead because token printing
selection is unavailable in game. The generator does not force a client's preferred printing.
The installer downloads all referenced alternatives as
pics/<SET_CODE>/<card name>_<printing UUID>.<extension>, which Cockatrice checks
before generic artwork filenames. Single-printing cards retain the simpler
<card name>.<extension> filename. Old generic files from previous installations
are not deleted, but the specific UUID filenames take precedence.
Add a set
Create sets/<SET_CODE>/set.toml and its artwork/ directory. Put metadata in
set.toml, then add token blocks in a sibling topic file as above:
[set]
code = "MYSET" # Must match the directory name.
name = "My custom tokens"
release_date = 2026-11-10
# type = "Custom" # Optional default.
# xml = "MYSET.xml" # Optional; defaults to <SET_CODE>.xml.
A set must contain at least one token. TKR explicitly keeps the published name
01.customtokens.xml so existing installations receive updates at the same path.
The generator validates all sets before replacing previous generated output;
invalid input leaves that output intact and causes the command/CI to fail.
Generate XML and build packages
Building requires Python 3.11+ and the pinned Pillow renderer. Set up the build
environment once (with uv installed), then activate it before the commands below:
uv venv --python python3 .venv
uv pip sync --python .venv/bin/python --require-hashes requirements-build.lock
. .venv/bin/activate
Without uv, use python3 -m venv .venv, then
.venv/bin/python -m pip install --require-hashes -r requirements-build.lock and
activate the environment. On Windows use .venv\Scripts\python.exe and the
appropriate activation command. The client installer still supports Python 3.8+
and does not require Pillow. To update the renderer deliberately, edit
requirements-build.txt and regenerate the lock with
uv pip compile requirements-build.txt --generate-hashes -o requirements-build.lock.
python3 scripts/build.py
This command reads every sets/*/*.toml, generates XML and stages artwork
under dist/sets/<SET_CODE>/, then creates dist/<SET_CODE>.zip. ZIPs contain
only generated XML and artwork, not TOML. Stable ordering, identities, and ZIP
timestamps make repeated builds reproducible. Removed generated files are cleared
on the next successful build. On Windows, use .venv\Scripts\python.exe scripts/build.py.
For XML generation alone or a check that generated output matches current sources:
python3 scripts/generate_xml.py
python3 scripts/generate_xml.py --check
CI runs the generator through the build command, checks generated output, prepares
the publication payload, and verifies the ZIPs, XML, artwork, and installer
manifest. Publication preparation/verification also rejects stale generated XML.
The existing archives/customtokens.zip is a legacy snapshot, not a source or a
current release artifact. New builds and the installer use the generated output.
Manual customsets.zip replacement
The build also creates dist/customsets.zip, archived by Jenkins and published at
https://assets.dandaedre.com/mtg/customsets.zip.
It contains all generated set XML files at the archive root, currently
01.customtokens.xml. It contains no artwork, TOML, installer, or extra TKR/
folder. The build and publisher verify its contents against generated XML.
- Close Cockatrice and make a backup copy of your existing
customsets/folder. - Download and extract the archive into the existing
customsets/directory. Replace matching XML filenames; do not keep an old renamed copy in the same folder, since Cockatrice may load both. Keep unrelated custom-set XML files. - Restart Cockatrice. Existing
Command Zoneentries keep the default artwork; chooseCommand Zone - <subject>when you want another illustration.
Typical destinations:
- Linux:
~/.local/share/Cockatrice/Cockatrice/customsets/ - Flatpak:
~/.var/app/io.github.Cockatrice.cockatrice/data/Cockatrice/Cockatrice/customsets/ - Windows:
%LOCALAPPDATA%\Cockatrice\Cockatrice\customsets\
Use your configured custom-set location if it differs. The final path should be
customsets/01.customtokens.xml, not customsets/customsets/01.customtokens.xml
or customsets/TKR/01.customtokens.xml. If the folder is missing, create it in
an already initialized Cockatrice data directory (containing settings/ or
cards.xml).
Manual extraction does not perform the installer's checks, confirmations, backups, or rollback. XML references the published artwork URLs, so image downloading must be enabled and online access available; use the installer to preinstall artwork for offline use. Old artwork files are not removed. The existing per-set ZIPs remain available as build artifacts with XML and artwork, in their original layout.
One-line installation and updates (Linux/macOS)
After Jenkins successfully publishes main, run as your normal user from an
interactive terminal, with Cockatrice closed:
curl --fail --show-error --silent --proto '=https' https://assets.dandaedre.com/mtg/install.sh | sh
The installer requires curl and Python 3.8+. It does not install Cockatrice
itself or use sudo. It looks for existing native/XDG, Flatpak, and macOS data
folders, including ~/.var/app/io.github.Cockatrice.cockatrice/data/Cockatrice/Cockatrice/
and the legacy io.cockatrice.Cockatrice path. The usual Linux destinations are:
- XML:
~/.local/share/Cockatrice/Cockatrice/customsets/01.customtokens.xml - Referenced artwork:
~/.local/share/Cockatrice/Cockatrice/pics/TKR/Command Zone_<printing UUID>.png
It honors customsets and pics overrides in the selected installation's
settings/paths.ini. With multiple possible installations it lists them and
requires a selection. With none, it aborts and asks you to install/launch Cockatrice
first. A missing destination folder within a recognized installation requires
approval before creation. It rejects symlinked paths and refuses root execution.
The installer follows this sequence: check installation → resolve any ambiguity with a prompt → confirm destinations → download to temporary storage → validate all files → confirm the exact file list → move files into place. It checks writable destination parents and available disk space before downloading assets. It never silently falls back to a different installation after a failure.
| Situation | Installer behavior |
|---|---|
| No Cockatrice data directory exists | Abort with instructions to install and launch Cockatrice; do not create a guessed installation. |
| Multiple possible data directories exist | List them and require a valid selection; an empty or invalid answer aborts. |
Selected installation lacks customsets/ or pics/ |
Ask permission to create the missing destination; create it only during the final installation step. |
| A path is unsafe, unwritable, or has insufficient free space | Abort with an error identifying the problem. |
| Download, checksum, or content validation fails | Abort before replacing installed files and clean up temporary downloads. |
| A copy or final move fails | Report the failure and attempt to restore all completed replacements. |
| Rollback cannot complete | Exit with an error and print the location of preserved recovery files. |
| Installation succeeds | Report success, remove temporary files, and ask you to restart Cockatrice. |
Errors and cancellations return a nonzero installer exit status. The plain
curl ... | sh pipeline has the separate download-status caveat described below.
For a portable or unusual data directory, specify the existing data directory,
not its customsets subfolder. --datadir is also accepted. Choose the folder
containing cards.xml or settings/, normally alongside decks/. For example:
/home/vky/.var/app/io.github.Cockatrice.cockatrice/data/Cockatrice/Cockatrice/
cards.xml (or settings/ must exist)
settings/
decks/
customsets/ (may be missing; created after confirmation)
pics/ (may be missing; created after confirmation)
Do not choose the outer .../data/ or .../data/Cockatrice/ directory.
The installer creates missing destination folders only during the final installation
step, after downloads validate and you approve the file list. settings/paths.ini
overrides still apply. Use --help for the same directory guidance.
curl --fail --show-error --silent --proto '=https' https://assets.dandaedre.com/mtg/install.sh | sh -s -- --data-dir /absolute/path/to/Cockatrice/data
Prompts read /dev/tty, so they work when the script arrives through a pipe. No
terminal, an invalid selection, or a declined prompt aborts. The script explains
its chosen locations, downloads the manifest and referenced XML/images into a
private temporary folder, checks sizes and SHA-256 hashes, validates XML and image
signatures, and then displays every create/replace operation for final approval.
Checksums detect corrupted or mixed-version downloads; they are supplied by the
same HTTPS host, not an independent signature. Unexpected redirects are rejected
through download/content validation rather than followed.
Installation copies verified files into temporary files beside their destinations, checks the copies, then atomically renames them into place. This also works when system temporary storage is on another filesystem. Images are installed before XML. Existing affected files are backed up for rollback; unrelated files are left alone. On failure it reports the file/error, attempts rollback, and preserves recovery files if rollback cannot finish. Successful runs remove temporary files. An installation lock prevents overlapping runs for the same data directory. After a forced termination, inspect any reported/stale lock and temporary recovery files before retrying; atomic replacement is per file, not a power-loss-safe transaction across the whole set.
Re-run the same command to update existing card sets. The installer fetches the current manifest and compares each destination's size and SHA-256. It skips identical files, downloads new or changed files, and replaces changed files at the same paths after confirmation. Existing set files are replaced, not appended or installed as duplicate copies. Keep the published XML filename, token IDs, and printing UUIDs stable when editing descriptions or artwork.
If everything matches, it reports “already up to date” without downloading card files or replacing them. To deliberately reinstall even identical files:
curl -fsS --proto '=https' https://assets.dandaedre.com/mtg/install.sh | sh -s -- --force
--force still performs every validation and confirmation and uses the same backup
and rollback protections. It can be combined with --data-dir. Updates do not
merge local edits: if a file differs from the published version, the displayed
replacement plan will overwrite it after approval. Restart Cockatrice after an
update to load the new XML and images. Removed upstream files are not automatically deleted.
The installer downloads only artwork referenced by the XML, rather than unused
historical image variants. A truncated shell download cannot execute the embedded
installer body until its full function definition has arrived.
To ensure a failed download also gives the overall command a failing exit status
in shells without pipefail, download before executing instead:
(sh_file=$(mktemp) && trap 'rm -f "$sh_file"' EXIT HUP INT TERM && curl --fail --show-error --silent --proto '=https' -o "$sh_file" https://assets.dandaedre.com/mtg/install.sh && sh "$sh_file")
For local validation without touching a real Cockatrice installation:
python3 -m unittest discover -s tests -v. The generated installer lives at
dist/publish/install.sh after python3 scripts/publish.py prepare; edit
scripts/install.py, not the generated shell script. Windows uses the same installer engine through install.ps1 (see below).
Windows installation (PowerShell)
Run from an interactive non-Administrator PowerShell console, with Cockatrice
closed. Requires Windows PowerShell 5.1+ (or PowerShell 7), Python 3.8+ accessible
as py.exe, python.exe, or python3.exe, and curl.exe. The script does not
install these dependencies or Cockatrice. Install and launch Cockatrice once first.
From this checkout:
.\install.ps1
.\install.ps1 -DataDir 'C:\path\to\Cockatrice\data'
.\install.ps1 -Force
After CI publishes the new launcher, download and run it with this one-liner:
$p = Join-Path $env:TEMP ([guid]::NewGuid().ToString() + '.ps1'); try { Invoke-WebRequest -UseBasicParsing 'https://assets.dandaedre.com/mtg/install.ps1' -OutFile $p -ErrorAction Stop; & $p } finally { if (Test-Path -LiteralPath $p) { Remove-Item -LiteralPath $p } }
Your PowerShell execution policy must permit running the downloaded script.
The installer does not change or bypass that policy. You may download and inspect
the script before running it instead. Use -Help to view launcher options.
Discovery checks %LOCALAPPDATA% and %APPDATA% for recognized
Cockatrice\Cockatrice and Cockatrice data folders. Multiple matches prompt for
selection; no match aborts explicitly. For portable installations, pass the actual
data folder with -DataDir. Configured settings/paths.ini customsets/pics paths
are respected. Missing destination folders require confirmation.
The shared Python engine displays destinations, stages downloads in a temporary
directory, validates sizes/SHA-256/content, and asks before replacing files. It
skips identical files unless -Force is used. Replaced files are backed up during
the operation and rolled back on failure; failed rollback preserves recovery
files and reports their location. Symlinks, junctions/reparse points, reserved
Windows filenames, and alternate data stream paths are rejected.
install.ps1 in the repository loads scripts/install.py; publication embeds the
same Python source into dist/publish/install.ps1 so the published file works
standalone. CI verifies and publishes both launchers with the same manifest.
Windows-specific runtime behavior still needs testing on a Windows machine;
Linux tests cover discovery, filename rejection, shared rollback and packaging.
Mock deployment
Bash:
./deploy.sh
PowerShell:
./deploy.ps1
Both commands locate sources relative to the script and print files that a future installer would deploy. They do not download, install, copy, or delete anything. These legacy previews remain mocks. Use the one-line installer above for actual installation and manual updates.
Jenkins CI and publication
Create a Gitea multibranch Pipeline for
git@git.dandaedre.com:idle-org/cockatrice-custom-tokens.git, using Jenkinsfile.
The default branch is main; only successful non-change-request builds of main
publish. Other branches run checks and archive artifacts, with an explicit
publication skip message. Concurrent builds of the publication job are disabled.
Do not configure duplicate jobs that publish to the same destinations.
The confirmed worker label is rust_nodocker. It must provide Git, Bash, and
Python 3.11+ with tomllib, venv, and pip. The pipeline verifies these tools,
creates .venv, and installs Pillow from requirements-build.lock with hash
verification. Network access to the configured Python package index is required
for that dependency step; uv is optional locally and is not required on Jenkins. No submodules, Git LFS, or tag-dependent build steps are needed.
Checkout uses the job's configured SCM credentials; no credential ID is embedded
in this repository. Publication uses the worker's filesystem permissions and
requires no additional Jenkins credential binding.
The worker must have the assets web root mounted at /mnt/assets, writable by
its Jenkins service account and readable by the web server. This matches the
reference pipeline's /mnt/assets/coverage to https://assets.dandaedre.com/coverage/
publication mapping. The publisher requires an existing actual mount and rejects
symlinked roots or destination paths; it never creates a missing mount. Its runtime
check must pass on the selected worker before the first publication can succeed.
New directories have mode 0755; published files have mode 0644. Existing shared
directory permissions and ownership remain the administrator's responsibility.
Stable files retain their basenames:
| Source | Destination | Public URL |
|---|---|---|
sets/*/artwork/* (supported images, including nested folders) |
/mnt/assets/mtg/cards/<filename> |
https://assets.dandaedre.com/mtg/cards/<filename> |
dist/sets/*/*.xml (generated from TOML) |
/mnt/assets/mtg/xml/<filename> |
https://assets.dandaedre.com/mtg/xml/<filename> |
The current XML URL is https://assets.dandaedre.com/mtg/xml/01.customtokens.xml.
PNG, JPEG, WebP, and GIF files are supported. Filenames must be unique across sets
within each destination category; collisions fail before publication. Artwork URLs
are generated from the TOML artwork filenames.
The pipeline starts with a clean workspace, checks the Bash mock, runs generation,
installer, rendering, and publication tests, renders reminder images and generates
XML from TOML, builds ZIPs, prepares
the public payload, and verifies every payload and ZIP
against the sources. It fingerprints and archives dist/*.zip,
dist/publish/cards/*, dist/publish/xml/*.xml, dist/publish/install.sh, dist/publish/install.ps1, and
dist/publish/manifest.json on every successful branch. The launchers and manifest are published at
https://assets.dandaedre.com/mtg/install.sh,
https://assets.dandaedre.com/mtg/install.ps1, and
https://assets.dandaedre.com/mtg/manifest.json. The XML-only customsets.zip
is also published at the mtg/ root. The manifest is generated from the
XML and local artwork, including hashes and Cockatrice destination filenames, and
is published last. An XML reference outside the assets host or missing local
artwork causes the build to fail.
It publishes images before XML using a temporary file and atomic rename for each
file. The complete multi-file update is not a transaction; a failure may leave
some files updated. Re-running a successful build safely replaces the same names.
Unrelated and obsolete remote files are never deleted.
Local equivalents (activate .venv and start with a clean generated dist/ directory):
bash -n deploy.sh
bash deploy.sh
python3 -m unittest discover -s tests -v
python3 scripts/build.py
python3 scripts/generate_xml.py --check
python3 scripts/publish.py prepare
python3 scripts/publish.py verify
prepare refuses to reuse an existing payload directory to prevent stale outputs.
Tests simulate publication in temporary directories; they do not write to the
real mount. Only Jenkins's publication stage should normally run:
python3 scripts/publish.py publish --web-root /mnt/assets
Configure Gitea push/branch/PR notifications using the installation's Jenkins base
URL plus /gitea-webhook/post and the existing Gitea Jenkins integration. Enable
branch discovery and the Checks integration providing publishChecks (as used by
the reference pipelines). Success, failure, and unstable reports use the stable
name Cockatrice assets CI. Check-reporting failures are logged without replacing
the original build result. Use the installation's configured checkout/checks
credentials; this project introduces no new credential IDs or secret values.
Pipeline syntax can be checked through the installation's Jenkins Declarative
Pipeline Linter (<JENKINS_URL>/pipeline-model-converter/validate). Groovy compilation
alone does not validate plugin availability or Declarative semantics. Publication
is not live until Jenkins parses this file and successfully builds main.
Check your deck collection
The read-only checklist scans Cockatrice .cod files recursively and displays
one row per deck, showing its saved Cockatrice name with the filename underneath
(blank names fall back to the filename stem), with color-coded checks for description, format, tags, banner
card, Command Zone token, and commander placement in a custom zone
for Commander decks. It does not modify decks.
Install the optional terminal-display dependencies into the existing build venv:
uv pip install --python .venv/bin/python --require-hashes -r requirements-tools.lock
.venv/bin/python scripts/check_decks.py
Without uv, use .venv/bin/python -m pip install --require-hashes -r requirements-tools.lock.
If you have no environment yet, create one with python3 -m venv .venv first.
Rich is optional tooling, separate from the Pillow build dependency; the CI tests
exercise deck analysis without needing Rich or access to your private decks.
By default, the script discovers native/XDG, Flatpak, and macOS Cockatrice data
folders (and LOCALAPPDATA on Windows), including the Flatpak deck directory
~/.var/app/io.github.Cockatrice.cockatrice/data/Cockatrice/Cockatrice/decks/
and the legacy io.cockatrice.Cockatrice path, honoring each settings/paths.ini decks
path. Multiple discovered collections are scanned together and duplicate files
are checked once. Explicit paths override discovery:
.venv/bin/python scripts/check_decks.py /path/to/decks
.venv/bin/python scripts/check_decks.py --show-complete
.venv/bin/python scripts/check_decks.py /path/to/one.cod /path/to/another.cod
.venv/bin/python scripts/check_decks.py --no-color
.venv/bin/python scripts/check_decks.py --json > /tmp/deck-checklist.json
.venv/bin/python scripts/check_decks.py --strict
The table uses green ✓ for present, red ✗ for missing, gray — for not
applicable, and yellow ? for an unknown check. Wider terminals include a
missing-items/notes column. Colors are automatically disabled for redirected
output; --no-color disables them explicitly. --json requires only Python's
standard library. Descriptions come from <comments>, tags from nonempty
<tags><tag> entries, and the banner from the nonempty <bannerCard> card name.
This checks metadata presence, not card legality or whether a banner printing
exists in your card database.
Commander/EDH/cEDH and Duel Commander/1v1 Commander labels are recognized without
case sensitivity. Add a custom exact format label using
--commander-format "My Commander Format" (repeatable). Commander decks pass the
token check when a card named Command Zone or Command Zone - <subject> with
a positive quantity appears in
any deck zone, including tokens or sideboard. Card-name comparison ignores case,
hyphens/underscores, and repeated whitespace. Merely having a commander card does
not satisfy this check. Existing tokens and commander custom zones are detected
even when format is blank; the missing Format check still needs attention.
The separate Cmdr. column requires a positive-quantity, nonempty card in a
Cockatrice custom zone named Commander or Command Zone (case, whitespace,
hyphens and underscores are normalized). Custom zones are nested beneath the
main or side board zone in .cod XML; a top-level zone, empty custom zone,
or the Command Zone reminder token alone does not satisfy this check. Multiple
commanders are supported. This verifies placement only, not card eligibility,
partner compatibility, or deck legality. A recognized custom zone makes the
Commander checks applicable even without a format. Without either a format or
such a zone, absent Commander requirements remain unknown. The checker never
moves cards automatically.
Commander Spellbook analysis
.venv/bin/python scripts/check_decks.py /path/to/deck.cod --spellbook
.venv/bin/python scripts/check_decks.py /path/to/deck.cod --spellbook --json > /tmp/analysis.json
--spellbook explicitly sends selected decks' card names and quantities to the
Commander Spellbook public API.
No account or key is needed. Normal checklist runs remain offline. Deck names,
descriptions, tags and local paths are not sent. Main-board cards (including
custom categories) and designated commanders are included separately; ordinary
sideboard cards and the tokens board are excluded. A commander in a custom zone
under the sideboard is included. Missing commanders or invalid quantities produce
an explicit error rather than a guessed analysis.
The colored output shows the API's estimated bracket label, included combo variant count and up to ten combo links. JSON includes returned combo categories (including near-combos) and bracket details. Results are limited to the first 100 combo variants; pagination is explicitly marked as partial. Estimates are not legality certification, and this service does not generate strategy tags or written deck descriptions. Decks remain unchanged.
Requests have a 30-second timeout and are spaced at least one second apart. Network, response and rate-limit errors are reported per deck and give exit status 2; no automatic retry occurs. Selecting a directory analyzes each valid deck with a designated commander, so select a single file for a focused request. CI uses mocked responses and does not upload decks.
Export for tag suggestions and analysis
Select a deck (or directory) and create a ready-to-paste prompt:
.venv/bin/python scripts/check_decks.py /path/to/deck.cod --export-analysis /tmp/deck-analysis.txt
Open the resulting text file and paste it into your preferred AI chat, or attach
it to a chat that accepts text files. It requests strategy/theme tags, a short
description, a banner suggestion, and analysis of the game plan, synergies, mana,
interaction and weaknesses. Review its suggestions before editing your decks.
No service account, API key, additional package, or network request is used.
For structured combo/bracket analysis through an API, use --spellbook above.
The export includes deck names, descriptions, existing tags/banner, checklist
results, and card names/quantities grouped by their exact nested zones. It omits
local file paths and printing identifiers. Review the content before sharing.
All selected decks are exported, even with --missing-only; select one .cod
file for a focused analysis. Existing destination files are never overwritten.
Unreadable XML or invalid card quantities abort the export before creating it.
The prompt asks the reviewer to flag uncertainty rather than invent card rules;
it does not include Oracle text or provide an authoritative legality check.
Malformed/unreadable decks are reported individually so the rest of the collection
can still be checked. Exit status is 0 for a successful report, 1 with
--strict when anything is incomplete, and 2 for file/parse/configuration errors
or no decks found. Complete decks are hidden from the checklist and JSON decks
list by default; use --show-complete to include them. --missing-only remains
an explicit alias for the default and cannot be combined with --show-complete.
This filters checklist rows, not summary counts, exit status, analysis exports,
or explicitly requested Spellbook analysis. Non-.cod files are ignored during directory scans.
Servatrice configuration backup
config/servatrice/README.md records sanitized snapshots of the local Servatrice configuration, the private backup location, and the completed manual upgrade to 3.1.2, validation, and rollback instructions. These files are for manual safekeeping only and are excluded from token publication and installation. No Servatrice deployment or database migration runs in CI.
License
See LICENSE for the repository license.