From 919259f0429443f654962a0e2bb039a897b533a9 Mon Sep 17 00:00:00 2001 From: Christian Daniel Jensen Date: Tue, 3 Nov 2026 13:16:03 -0700 Subject: [PATCH] Document Continuumatrice Identity ATK HP and Armour data plus sorting --- doc/continuumatrice-card-fields.md | 69 ++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 doc/continuumatrice-card-fields.md diff --git a/doc/continuumatrice-card-fields.md b/doc/continuumatrice-card-fields.md new file mode 100644 index 000000000..b96ec6543 --- /dev/null +++ b/doc/continuumatrice-card-fields.md @@ -0,0 +1,69 @@ +# Continuumatrice CCG card fields and numeric sorting + +This document covers **static card-definition metadata** loaded from Continuumatrice XML v4. It does not change mutable game resources, damage, armour degradation, campaign state or server match mechanics. + +## Source mapping + +| Continuumatrice field | Native XML v4 property | Field in existing Continuum MSE game | Legacy import fallback | Sorting | +| --- | --- | --- | --- | --- | +| Identity | `identity` | `alias` | `alias` | Locale-aware text | +| Attack (ATK) | `attack` | `strength` | `strength`, or Attack side of `pt` | Numeric | +| Armour | `armour` | `armor` | `armor` | Numeric | +| Health (HP) | `health` | `health` | Health side of `pt` | Numeric | +| ATK/HP | Derived from Attack and Health | MSE `strength` + `health` | `pt` via the individual stat fallbacks | Attack numeric first, then Health numeric | + +**Identity** is the CCG's **card alias**. It must not be confused with `essence` (which is the distinct Essence resource/type identity). The `Name` column still contains the actual card name. + +The XML importer already supports arbitrary text properties under ``, so adding these properties does not require a schema version change. + +## Example + +```xml + + Example Character + Static card data demonstration only. + + Character + The Guardian + 10 + 3 + 12 + M + + EXAMPLE + 0 + +``` + +The table view displays ATK/HP as `10/12`, with separate **Attack**, **Armour**, and **Health** columns. If a card has no authored stats, the combined display remains blank. When one stat is omitted, the missing side is shown as `?`. + +The database's sort dropdown discovers model columns dynamically, so the new fields are available for ascending/descending sorting. Numeric fields use numeric comparisons; the combined ATK/HP column sorts by Attack first and Health second. The former `P/T` column position is retained internally for compatibility with existing saved table views. + +## Exporter compatibility + +The matching Magic Set Editor exporter change is in `Continuum-Universes-MSE-Templates`: + +- `card.alias` → `` +- `card.strength` → `` +- `card.armor` → `` +- `card.health` → `` + +The MSE internal field identifiers are **not renamed**: that would otherwise risk breaking existing `.mse-set` files, render scripts and card styles. + +Older XML exports with `strength`, `armor`, `alias`, or `pt` remain readable. Native properties take precedence whenever present; no automatic rewriting of existing files occurs. + +## Test checklist + +```bash +cmake --build build --target continuumatrice carddatabase_test model_contract_test --parallel 16 +ctest --test-dir build -R 'CardInfoTest.ContinuumIdentityAndStatsHaveNativeAndLegacyPropertyAccess|ModelContract.ContinuumCardStatsAreSortableAndLabeled' --output-on-failure +``` + +- [ ] Import an MSE-exported set and verify Identity, Attack, Armour, Health and ATK/HP columns. +- [ ] Check Attack `9` precedes `10` and Armour `2` precedes `10`. +- [ ] Check ATK/HP sorts on Attack then Health. +- [ ] Verify legacy fields are still readable and an empty field is not assumed to mean zero. +- [ ] Verify the card details pane displays the new names, including **Armour**. +- [ ] Verify the existing Essence filter still operates independently of the Alias/Identity property. + +**Status:** Source changes committed; native compilation, tests and MSE GUI export still need local runtime verification.