cockatrice-custom-tokens/docs/advanced_concept.md

40 KiB
Raw Permalink Blame History

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

  1. Layout
  2. Add artwork and descriptions
  3. Automatically put TOML text on a card
  4. Topic files and alternative artwork
  5. Add a set
  6. Generate XML and build packages
  7. Manual customsets.zip replacement
  8. One-line installation and updates (Linux/macOS)
  9. Windows installation (PowerShell)
  10. Mock deployment
  11. Jenkins CI and publication
  12. Check your deck collection
  13. Servatrice configuration backup
  14. 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.

  1. Close Cockatrice and make a backup copy of your existing customsets/ folder.
  2. 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.
  3. Restart Cockatrice. Existing Command Zone entries keep the default artwork; choose Command 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.