Team 7 · Issue #159

Card upgrades attach to an individual copy of a card, not to a card type. A deck holding three Strikes can have one of them upgraded while the other two stay at base values. Each copy is identified by its CardInstance.instanceId.

The feature splits into three layers:

This page covers the interaction layer and the committer that connects it to the deck. The selection model never touches the deck; the display hands the chosen instance IDs to a CardUpgradeCommitter, and DeckUpgradeCommitter is the implementation that writes them to PlayerDeck.

For camps, encounters, rewards, or anywhere else that should let the player upgrade cards.

PlayerDeck deck = runState.getOrCreatePlayerDeck(cardService);

CardUpgradeDisplay upgradeDisplay =
    new CardUpgradeDisplay(deck, cardService, new DeckUpgradeCommitter(deck), false);
ui.addComponent(upgradeDisplay);   // must happen before open()

// later, from your own button or event:
upgradeDisplay.open(1);            // let the player upgrade up to 1 card

Things to know

• Add the component to an entity before calling open. The overlay is built in create(); calling open earlier throws IllegalStateException.
• open(maxUpgrades) sets the limit for that opening. maxUpgrades below 1 throws IllegalArgumentException. Each caller chooses its own limit.
• Every open rereads the deck and starts a fresh selection. Cards already upgraded are never shown, and closing without confirming discards the selection.
• The display does not limit how often it is opened. If your screen allows one upgrade per visit, enforce that yourself — for example, disable your button after the first open.
• Use one PlayerDeck for both the display and the committer, so the cards shown are the cards upgraded.
• If ServiceLocator.getCardLibrary() is null on your screen, build one locally: new CardLibrary(CardConfigLoader.loadCards()). This is the case on EndBattleScreen, because BattleScreen.dispose() calls ServiceLocator.clear().

classDiagram
    class CardUpgradeSelection {
        -List~CardInstance~ deck
        -CardService cardService
        -int maxSelections
        -List~UpgradeOption~ options
        -LinkedHashSet~String~ selected
        -Set~String~ selectableIds
        +getCardUpgradeOption() List~UpgradeOption~
        +isSelected(String) boolean
        +canSelect(String) boolean
        +toggle(String) boolean
        +canConfirm() boolean
        +remainingSelectable() int
        +getSelectedInstanceIds() List~String~
        +reset() void
    }

    class UpgradeOption {
        <<record>>
        +String instanceId
        +ResolvedCard current
        +ResolvedCard preview
    }

    class CardUpgradeDisplay {
        -PlayerDeck playerDeck
        -CardService cardService
        -CardUpgradeCommitter committer
        -boolean showOpenButton
        -CardUpgradeSelection selection
        -Map~String, Table~ tilesByInstanceIds
        +open(int) void
        -rebuildGrid() void
        -refresh() void
        -createTile(UpgradeOption) Table
    }

    class CardUpgradeCommitter {
        <<interface>>
        +commitUpgrades(List~String~) void
    }

    class DeckUpgradeCommitter {
        -PlayerDeck deck
        +commitUpgrades(List~String~) void
    }

    class LoggingCardUpgradeCommitter {
        +commitUpgrades(List~String~) void
    }

    class PlayerDeck {
        +getCards() List~CardInstance~
        +upgradeCard(String) boolean
    }

    class UIComponent
    class CardResolver
    class ResolvedCard
    class CardInstance
    class CardService

    CardUpgradeDisplay --|> UIComponent
    DeckUpgradeCommitter ..|> CardUpgradeCommitter
    LoggingCardUpgradeCommitter ..|> CardUpgradeCommitter
    CardUpgradeSelection *-- UpgradeOption
    CardUpgradeDisplay --> CardUpgradeSelection : creates on open
    CardUpgradeDisplay --> CardUpgradeCommitter
    CardUpgradeDisplay --> PlayerDeck : reads
    DeckUpgradeCommitter --> PlayerDeck : writes
    CardUpgradeSelection --> CardResolver
    CardUpgradeSelection --> CardService
    CardResolver --> ResolvedCard
    CardResolver --> CardInstance
    UpgradeOption --> ResolvedCard

CardUpgradeSelection has no libGDX or deck dependency; it works on a plain List<CardInstance>. The display reads the deck to build a selection, and only the committer writes to it.

stateDiagram-v2
    [*] --> NotCreated
    NotCreated --> Closed : added to entity (create)
    NotCreated --> NotCreated : open(n) throws IllegalStateException

    Closed --> Open : open(n) — rereads deck, fresh selection

    state Open {
        [*] --> NoneSelected
        NoneSelected --> SomeSelected : toggle eligible card
        SomeSelected --> NoneSelected : toggle last selected card off
        SomeSelected --> SomeSelected : toggle, still below cap
        SomeSelected --> AtCap : toggle, reaches cap
        AtCap --> SomeSelected : toggle a selected card off
        AtCap --> AtCap : unselected tiles disabled
    }

    Open --> Closed : Close — selection discarded
    SomeSelected --> Closed : Confirm — commitUpgrades(ids)
    AtCap --> Closed : Confirm — commitUpgrades(ids)

With open(1), the first toggle goes straight from NoneSelected to AtCap. If the deck has no upgradable copies, the overlay stays in NoneSelected with an empty grid.

Holds all selection rules. Plain Java, no libGDX dependency.

Constructor: CardUpgradeSelection(List<CardInstance> deck, CardService cardService, int maxSelections). Throws IllegalArgumentException on a null deck, null card service, or a cap below 1.

record UpgradeOption(String instanceId, ResolvedCard current, ResolvedCard preview)

current and preview are the same copy resolved at base and upgraded level, which is what lets the UI show "Deal 6 damage." → "Deal 12 damage." without knowing anything about card data.

void commitUpgrades(List<String> instanceIds)

The seam between choosing and applying.

PlayerDeck.upgradeCard returns false and changes nothing if the copy is already upgraded, has no upgrade defined, or is not in the deck.

A copy is upgradable when its card has an upgrade block (config.upgrade != null) and the copy is not already upgraded. That single check decides both what the UI displays and what may be selected — there is no separate "can display" and "can upgrade" check to drift apart.

buildUpgradeOptions() is the only place that evaluates it. Everything downstream just asks whether an instance ID is in the options.

An earlier version keyed everything on deck index. That had two problems:

• Tile position is not deck index. The overlay only shows eligible cards, so the fourth tile might be deck index 8. Mixing the two up upgrades the wrong card.
• Indices shift when the deck changes. Applying several upgrades by index needed a descending sort so earlier changes didn't move later entries.

Instance IDs are stable and unique per copy, so both problems disappear. The descending sort was removed on purpose.

CardUpgradeSelectionTest — 12 unit tests. The rules were deliberately kept free of libGDX so they test without a headless GDX harness; UIComponent.skin is a static field initialised from Gdx.files at class load, so anything extending UIComponent drags one in.

PlayerDeckTest covers upgradeCard: upgrading only the targeted copy, refusing a second upgrade, and rejecting unknown, null or empty IDs.

./gradlew :core:test --tests "*CardUpgradeSelectionTest*"

• CardUpgradeDisplay contains only rendering and event wiring.
• DeckUpgradeCommitter only loops over PlayerDeck.upgradeCard, which PlayerDeckTest covers.

To verify manually:

1. Win a battle and click Upgrade. The overlay lists each upgradable copy showing base → upgraded values.
2. Select two. The cap is reached and the other tiles dim. Clicking a selected card deselects it and re-enables them.
3. Confirm is disabled at zero selections and shows the count.
4. Confirm, then reopen. The upgraded copies are gone.
5. Start the next battle and play an upgraded Strike. It deals 12 damage, not 6.

Should rewards offer card upgrades? If so, the reward only needs to carry how many cards may be upgraded and pass that to open(n). The player decides which.

• Card Data Model
• Player & Battle Deck
• Reward System
• Card Effect Resolution