Dynamic Card Faces and Post‐Battle Card Rewards - UQcsse3200/2026-studio-3 GitHub Wiki

This page describes reusable card faces, rarity frames, their screen integration and the post-battle Card reward flow. It supplements the Card System documentation, which covers configuration, card identity, upgrades, deck lifecycle, combat and save/load. Those foundational systems are not repeated here. Source code and configuration remain authoritative.

• Architecture and integration contracts
• Card faces and frame assets
• Post-battle Card rewards
• Design decisions and validation-driven revisions
• Troubleshooting and extension boundaries
• Test Plan
• Known limitations

The presentation boundary consumes a ResolvedCard, not raw labels or gameplay state. An existing resolver produces the snapshot; CardWidget renders it; the surrounding screen decides whether the face can be clicked, dragged or acquired. The renderer never spends energy, changes ownership, marks discovery or calculates an upgrade.

The following UML class diagram shows selected contracts, not every field or inheritance relationship in the project. Composition denotes actors created and owned by the widget; arrows denote references or dependencies, not ownership of shared textures.

classDiagram
    class CardWidget {
        +CardWidget(ResolvedCard card, CardWidgetAssets assets)
        +setCard(ResolvedCard card) void
        +getCard() ResolvedCard
    }
    class CardWidgetAssets {
        +fromManagedResources(Skin skin, ResourceService resources) CardWidgetAssets
        +collectTexturePaths(Collection configs) String[]
        +hasAuthoredFrame(Rarity rarity) boolean
    }
    class FramedCardFace {
        +layout() void
    }
    class CardFrameLayout {
        <<record>>
        String texturePath
        boolean artworkAboveFrame
    }
    class CardTextFitter {
        ~fit(Label label, float maximumScale) void
    }
    class ResolvedCard {
        <<record>>
        String instanceId
        String cardId
    }
    CardWidget --> ResolvedCard : binds snapshot
    CardWidget --> CardWidgetAssets : shared assets
    CardWidget *-- FramedCardFace : authored rendering
    CardWidgetAssets --> CardFrameLayout : rarity registry
    FramedCardFace --> CardFrameLayout : placeholder geometry
    FramedCardFace ..> CardTextFitter : bounded typography

FramedCardFace, CardFrameLayout and CardTextFitter are package-private. Public screens depend on CardWidget and CardWidgetAssets; adding a view should not require access to frame internals. The generic fallback uses the same resolved snapshot.

Card faces combine a shared rarity frame, artwork and dynamic text. They display resolved cost, name, description and upgrade state, rather than text baked into the artwork. Type and target occupy separate placeholders. Rarity is communicated by the frame and is also written explicitly in Library details.

The following are the actual frame assets, not screenshots of rendered cards. Artwork and dynamic labels are inserted at runtime into their placeholders.

Common	Uncommon	Rare

These Library card-face captures show the frames populated with artwork and dynamic cost, name, type, description and target. The three rarities use the same rendering pipeline, with their own frame assets and placeholder layouts.

Warding Sweep — Common	Purify — Uncommon	Doom Sigil — Rare

The last three classes are package-private implementation details. Screens should construct CardWidget, not their own frame-specific renderer.

FramedCardFace centres a uniformly scaled face using min(allocatedWidth / 225, allocatedHeight / 456). Long descriptions cannot enlarge the frame. Reward choices allocate the same 225 × 456 face bounds, regardless of rarity or description length.

Descriptions use one wrapped label with one fitted font scale. The final line therefore has the same glyph size as the preceding lines. Cost, name, type and target are separately centred and fitted. Shrinking prevents overflow, but readability still needs checking at actual hand/tile sizes.

CardTextFitter first measures at the layout's maximum scale, then performs 12 binary-search steps if the whole wrapped block does not fit both width and height. It restores shared BitmapFont scale in finally and applies the result to the label. This avoids changing the appearance of other cards that use the same skin font. Fitting has no minimum readable scale guarantee: unusually verbose content still requires editorial or layout review.

Current artwork windows are opaque black. Rendering artwork behind them would hide it. artworkAboveFrame controls the draw order:

• Opaque window: frame → inset backdrop → artwork → labels.
• Transparent window: backdrop → artwork → frame → labels.

The inset artwork bounds protect borders and ornaments. Missing artwork hides only the illustration; missing frame assets select a generic rarity-coloured face in CardWidget. Some screen integrations retain a legacy fallback.

The Library uses discovery-controlled entry data before creating a face. Sorting and rendering do not unlock cards. UncommonCardLibraryWidget is a compatibility wrapper; standard CardWidget supports all three frames.

CardWidget is presentation-only and touch-disabled. Outer buttons or Clickable actors retain click, drag, targeting, selection tint and hover/tooltip responsibilities. Clickable.setVisualContent(...) takes a supplier so a drag preview gets a fresh actor: Scene2D actors cannot belong to two parents. Owned interactions retain their instanceId; Library, Shop and reward faces use read-only previews.

1. Add the PNG under images/cards/, without baked-in gameplay text.
2. Update the appropriate CardFrameLayout bounds for artwork, cost, name, type, description, target and upgrade marker.
3. Register its path/layout in CardWidgetAssets; no new rarity-specific widget is needed.
4. Set artworkAboveFrame according to the PNG's alpha, not its apparent colour.
5. Extend layout tests and inspect the face in the Library, battle hand and rewards.

Bounds use logical bottom-left coordinates. For a placeholder measured from the top-left of the current 2× PNG, convert with x = pixelX / 2 and y = (912 - pixelTop - pixelHeight) / 2. Changing an existing frame requires geometry review as well as replacing its image.

After victory, the player chooses one reward type: Gold, Item or Card. Gold and Item complete directly. Choosing Card commits that route and displays a fixed offer of up to three distinct eligible cards. Selecting one adds exactly one fresh base-level copy to the persistent deck. Opening the card selection itself adds nothing.

Defeat does not generate victory rewards. The optional owned-card upgrade interface is separate from reward acquisition, not a fourth reward type; its confirmation is independent of the Gold/Item/Card claim.

This capture shows the Card route after it has been opened: three distinct candidates with matching face dimensions, despite different description lengths. Inner Focus, Purify and Poison Dagger are all Uncommon in this example, so they share the blue frame. Their type ribbons and target footers still differ. Selecting one candidate grants only that card, not all three.

Implementations: source/core/src/main/com/csse3200/game/rewards

Generation dependencies can be injected for a controlled test or another reward consumer:

RewardService rewards = new RewardService(
    new RewardGenerator(new Random(1)),
    cardService,
    acquisitionPool,
    new Random(2));
List<RewardOption> fixedOptions = rewards.generateRewardOptions();

The two random sources control existing Gold/Item generation and Card sampling separately. Seeded reproducibility is a test aid, not the production reward policy. Retain the returned options for the whole choice instead of generating them again on each click or redraw.

The pool is shared eligibility policy, not a shared draw pile. Shop, applicable Events and victory rewards use it independently. Acquisition does not remove a definition. The current policy includes all 26 production definitions; sampling is uniform, without rarity weighting, discovery requirements or exclusion of already-owned cards. A one- or two-card pool produces a smaller offer; an empty pool omits Card but retains Gold/Item. Policy changes require loading a new pool/service, not merely editing JSON during play.

sequenceDiagram
    participant UI as RewardDisplay
    participant Rewards as RewardService
    participant Discovery as CardDiscoveryService
    participant Deck as Persistent PlayerDeck
    participant Save as Map autosave
    UI->>Rewards: Generate options once
    Rewards-->>UI: Gold, Item and fixed Card offer
    Note over UI,Discovery: Hidden offers do not mark cards seen
    UI->>UI: Choose Card and remove other reward choices
    UI->>UI: Build base-preview faces
    UI->>Discovery: Record displayed candidates as seen
    UI->>Rewards: Claim fixed offer with selected cardId
    Rewards->>Rewards: Validate membership and eligibility
    alt Selected card is valid
        Rewards->>Deck: Add one fresh base instance
        Rewards-->>UI: Claim succeeded
        UI->>UI: Emit rewardClaimed and return event
        Note over UI,Save: Existing screen flow returns to Map
        Save->>Deck: Flush pending autosave including acquired copy
    else Validation rejects the claim
        Rewards-->>UI: Throw validation exception
        UI->>UI: Keep fixed choices and allow retry
    end

All displayed card candidates become discovered, including those not selected. Generating hidden candidates does not reveal them; choosing Gold/Item does not reveal them.

RewardDisplay generates once and guards in-progress, repeated, successful and disposed callbacks. Completion is emitted only after a successful claim. Exceptions keep the screen open for retry. The pending Map autosave is flushed after returning, so the acquired copy is included and remains available in the next battle.

Boundary: the service validates/applies claims but has no claimed-offer ledger. Calling it twice directly can grant twice. Another UI must provide equivalent claim guards. Pending card selection is not persisted across quitting mid-reward. The existing entity-only claimReward(entity, option) path rejects Card rewards because they require persistent RunState.

For another reward consumer, generate once, keep the fixed offer, discover only displayed candidates, and guard completion around:

rewardService.claimRunReward(runState, selectedOption, chosenCardId);

This creates a new owned copy; it must not insert the synthetic preview instance.

Successful completion emits rewardClaimed and the existing return event only after the service call succeeds. These are notifications, not requests to grant the reward again. The retry path is not a general transaction rollback: consumers must not assume that an arbitrary exception after an external mutation can safely be retried without inspecting the mutation boundary.

These revisions respond to concrete layout and lifecycle failures. Reusing interaction containers instead of adding another hover/drag system keeps visual changes from redefining input behaviour. Future revisions should preserve these contracts and add tests for the observed failure, rather than only adding another screenshot.

Verify dynamic card faces, all three rarity frames, existing screen integrations and the exclusive post-battle Card reward flow. The main risks are text-driven size changes, hidden artwork, incorrect resolved values, broken interaction payloads, duplicate reward claims and loss of an acquired copy after save/load. Foundational card-system tests remain regression dependencies rather than a second specification of the whole card system.

Use Java 21 and the Gradle wrapper from source/. Automated tests use JUnit 5 with the project's headless/mocked rendering support; real-asset tests also inspect managed textures. Use seeded randomness for repeatable reward offers and temporary save directories for persistence tests. Discovery checks need isolated progress: previously discovered cards remain seen across restarts and recompilation. Do not clear normal player progress to test locked entries.

For manual checks, record the commit, window resolution and UI scale. Include Common, Uncommon and Rare cards, short and long names/descriptions, all configured types/targets, and a base/upgraded pair such as Strike and Strike+. Inspect both the normal window and a smaller supported window; Library-sized readability alone does not establish hand-sized readability.

Test sources are under core/src/test. These suites are executable evidence of specific contracts, not a claim that every manual scenario below has passed.

Use controlled fixtures or a development save to obtain the required cards and offers. Tests that force a particular offer must not change production eligibility or randomness.

Missing-resource and claim-failure conditions are exercised with controlled automated fixtures; do not delete production assets or damage real saves to simulate them. Quitting midway through an unclaimed reward is outside the current persistence guarantee, not a successful recovery case.