Chance and Shop Encounter UI

Team 2 - Non-Battle Encounters Related tasks: #25 - Encounter UI and Player Interaction · #170 - Sprint 2 Chance and Shop UI/UX Improvements

Overview

The Chance and Shop Encounter UI presents Team 2's non-battle encounters as full-screen Scene2D overlays. The UI is responsible for displaying encounter information and collecting player input; encounter rules, player updates, purchases, and map progression remain in the underlying systems.

The interface provides two playable flows:

• Chance Encounter: display an event, allow one choice, show the returned outcome, and return to the map.
• Shop Encounter: display the player's gold and available card offers, handle purchase feedback, and return to the map.

The visual style uses a dark panel, warm gold highlights, large readable controls, and clear selected/available/unaffordable/sold states. The layout was enlarged after playtesting so that encounter information remains the main visual focus.

In Sprint 2, the temporary forest demo was removed. EVENT and SHOP map nodes now open their respective full-screen encounter displays independently, and completion updates the active RunState encounter before restoring the same generated map. The Shop also uses six Team 6 card artworks through the shared card service; battle card presentation is unchanged.

Player Flow

flowchart LR
    M[Map / RunState] -->|EVENT node| C[ChanceEncounterDisplay]
    M -->|SHOP node| S[ShopDisplay]
    C --> CH[Player chooses a response]
    CH --> R[ChanceEncounterSession resolves outcome]
    R --> O[UI displays outcome]
    O --> CE[Complete active encounter]
    S --> P[Purchase or leave]
    P --> SE[Complete active encounter]
    CE --> M
    SE --> M

The UI does not directly change health, gold, deck contents, stock, or map nodes. It sends the player's action to the encounter layer and renders the returned result.

Chance Encounter UI

ChanceEncounterDisplay shows:

• the encounter title and description;
• all choices in their configured order;
• a highlighted selected choice;
• the resolved outcome, including health and gold changes;
• a Continue button after a valid choice resolves.

After a choice is selected, the remaining choice buttons are disabled. The display then delegates to ChanceEncounterSession, which validates and applies the result through the Player boundary. Completion is emitted once when the player presses Continue.

Chance data used by the UI

Class	UI use
ChanceEncounter	Encounter ID, description, and available choices
ChanceChoice	Choice ID and player-facing text
ChanceOutcome	Health and currency result shown to the player
ChanceEncounterSession	Resolution and completion lifecycle

Chance UI Screenshots

Figure 1. The initial Chance Encounter presents the event description and two available responses before the player makes a choice.

Figure 2. After a response is selected, the chosen option is highlighted, other choices are disabled, and the returned health and gold outcome is displayed.

Shop Encounter UI

ShopDisplay shows:

• the player's current gold;
• card name, description, price, and remaining stock;
• Team 6 card artwork resolved through the shared CardService, with a fallback when art is unavailable;
• a purchase button for each offer;
• available, unaffordable, sold, and unavailable states;
• purchase success/failure feedback;
• a Leave Shop button.

The UI asks ShopEncounter to process a purchase. Transaction validation is handled by ShopService and the integration gateways. The display refreshes gold, stock, status text, and button state from the returned result.

Sprint 2 added six Shop-specific card textures (bandage, defend, expose, inner_focus, poison_dagger, and strike). ShopDisplay resolves the configured card texture through CardService, maps it to images/shop/cards/, scales it to fit the larger card area, and keeps an explicit unavailable placeholder for missing data or assets.

Shop item states

State	Meaning	UI behaviour
AVAILABLE	Card exists, stock remains, and the player can afford it	Purchase enabled
UNAFFORDABLE	The player does not have enough gold	Purchase disabled with feedback
SOLD	The offer has no remaining stock	Sold state displayed
UNAVAILABLE	The item or external transaction cannot be completed	Purchase disabled

Shop UI Screenshots

Figure 3. The initial Shop view displays the player's gold and three card offers with names, descriptions, prices, stock, availability, and purchase controls.

Figure 4. The Shop refreshes after purchase attempts, showing updated gold, sold offers, an unaffordable offer, disabled controls, and transaction feedback.

UI Implementation

Both displays extend UIComponent and use libGDX Scene2D Table, Label, and TextButton actors. The root table fills the stage, centres the encounter panel, blocks input to the world behind it, and uses a short fade animation when opening or closing.

EncounterGameArea now creates only the logical player state and the full-screen encounter UI. It selects Chance or Shop from the active map node, forwards completion through EncounterFlowController, records the result in RunState, and switches back to the Map screen. This keeps navigation outside the display classes and prevents the old Chance-to-Shop demo chain from reappearing.

The implementation separates visual responsibilities from game rules:

Component	Responsibility
ChanceEncounterDisplay	Chance layout, choice input, and outcome presentation
ShopDisplay	Shop layout, offer states, purchase input, and feedback
EncounterGameArea	Route the active EVENT or SHOP map node and return to the same map
ChanceEncounterSession	Apply a Chance result safely and complete once
ShopEncounter / ShopService	Validate purchases and maintain stock
EncounterFlowController	Prevent overlapping encounters and forward completion

Cross-Team Integration

Team 2 uses small gateway interfaces so the UI and encounter rules do not directly depend on another team's concrete classes.

Team	Boundary used by Team 2	Sprint 2 status
Team 4 - Map	RunState, MapScreen, and the encounter completion callback	EVENT and SHOP nodes are routed independently; completion updates the active node and restores the same map
Team 5 - Deck	DeckGateway / InventoryDeckAdapter	Shop rewards continue through the deck boundary without moving deck logic into the UI
Team 6 - Cards	Shared CardService / CardLibrary	Shop artwork is resolved from card definitions and rendered with six supplied Shop card assets
Team 7 - Player/Economy	PlayerStateGateway / ComponentPlayerStateAdapter	The UI reads player gold and renders returned health/currency results while the underlying services perform changes
Team 3 - Game Flow/UI	Screen ownership and navigation	The encounter screen owns the full-screen overlay and returns control to the Map after completion or leaving

Running the Sprint 2 UI Flow

From the repository's source directory:

./gradlew desktop:run

1. Start the game from the main menu.
2. Start or continue a run and enter an EVENT or SHOP node from the generated map.
3. For an EVENT, select a response, confirm that the returned outcome is displayed, and press Continue.
4. For a SHOP, inspect the card artwork, prices, stock and affordability states; purchase an available card or trigger failure feedback.
5. Press Leave Shop when finished.
6. Confirm that the encounter completes once and the same map is restored with its progress preserved.

The main-menu debug shortcut remains available. If no map node is active, it opens a standalone Shop preview rather than constructing the removed forest demo.

Testing and Validation

Automated coverage includes:

• Chance title and outcome formatting;
• valid, invalid, and duplicate Chance resolution;
• Shop available, unaffordable, sold, and unavailable states;
• successful purchases and failed transaction rollback;
• one active encounter at a time;
• stale and duplicate completion callbacks;
• independent EVENT-to-Chance and SHOP-to-Shop routing;
• Shop artwork path resolution through the shared card service;
• encounter completion and return to the existing map.

Verification commands:

./gradlew spotlessCheck test

The Sprint 1 sizing update in PR #109 passed all local tests and all four GitHub checks before being merged into Feature-2. The Sprint 2 integration in PR #205 passed 784 tests and manual checks of Chance, Shop, map return and the unchanged battle card UI before being merged into Feature-2-Sprint2.

Current Limitations and Reflection

• Shop artwork now uses six Team 6 assets. The unavailable placeholder is retained only for missing card definitions or unloaded textures.
• The forest demo and hard-coded Chance-to-Shop chain were removed; EVENT and SHOP map nodes now enter and return independently.
• Temporary adapters are used because cross-team APIs changed during Sprint 1. This kept Chance and Shop rules testable while limiting later integration changes to adapter classes.
• The UI was initially implemented at a smaller size, then enlarged after visual review to improve readability and make non-battle encounters the focus of the screen.
• Shop artwork is intentionally isolated from the battle card UI, which was manually re-checked after the integration.
• The no-active-node debug path remains a standalone Shop preview and does not represent normal map progression.

Extending the UI

• Add a new Chance event through ChanceEncounterFactory; the display reads its choices dynamically.
• Add or update shop offers in core/assets/configs/shopItems.json.
• Add new Shop artwork under core/assets/images/shop/cards/ and expose its texture path through the shared card definition.
• Keep new PlayerDeck, CardService, Player and Map integrations behind the existing boundaries rather than rewriting the display classes.

Related Documentation

• Non-Battle Encounter Framework
• Shop Encounter System
• Map Graph System
• Player and Battle Deck
• Card Library API
• Economy System
• PR #50 - Initial Chance and Shop UI
• PR #69 - Encounter integration
• PR #109 - UI sizing update
• Issue #170 - Sprint 2 Chance and Shop UI/UX Improvements
• PR #205 - Sprint 2 polished Shop and encounter UI integration

Sprint 4: Confirmed Results and Event Preview (integration PR #471)

Status (15 October 2026): The implementation is on the upstream task branch and draft PR #471, based on Yihan's Event branch. It is not yet evidence of an integrated main playthrough. Owner: Guoqing Sun; related Team 2 feature #439, Event items #442 and Team 7 item definitions #447.

Player flow and UI boundary

• From the main menu, Demo Event opens a picker containing the configured Events and Random Event. Cancel returns to the menu. Selecting a named Event opens an isolated preview and returns to the menu on completion. This shortcut helps inspect screens but does not test a Map-to-Event journey.
• After a Chance choice is successfully applied, the existing Outcome remains visible under a scrollable Results panel. The panel can show confirmed cards, items, health, gold and other positive or negative entries together. Card preview artwork is used when managed assets exist; the result name and description remain readable without it. Quantities and explicit effect duration are separate.
• Continue closes the result and completes the encounter once. Close dismisses the panel and exposes the original Outcome/Continue control, without reapplying any change. Four-choice Shrine and Mine scenes use two rows at the virtual 1280 × 800 layout; existing two-choice scenes keep their layouts.
• A successful Shop purchase displays the receipt's confirmed acquisition; a rejected purchase displays no result. Dismissing the panel resumes the Shop and cannot charge or grant again.

The display implements Zixuan's AcquisitionView interface; AcquisitionPresentation guards against repeated or stale callbacks. ChanceAcquisitionResults uses committed before/after values, reward IDs and the selected choice's player-facing description. The UI never changes health, gold, inventory, deck or map progression itself. Yihan's Event branch supplies item rewards; Team 7 owns the final item definitions and effects.

Step	Owner	Result
Player chooses or purchases	Chance or Shop service	Validates and applies once
Service returns committed resolution or receipt	AcquisitionPresentation	Rejects duplicate or stale result
Presenter shows read-only entries	AcquisitionResultDisplay	Continue completes; Close resumes outcome

Evidence and pending acceptance

• PR #471 contains the implementation and focused tests for the picker, mixed results, Chance/Shop result lifecycle, four-choice layout and one-time Curse choice dispatch. GitHub Actions Java Format and Game Unit Tests both passed on commit 82d3410.
• Manual visual and end-to-end acceptance remains pending: inspect each configured Event at normal and narrow window sizes; complete a successful Shop purchase and a failed purchase; check Close/Continue and one-time reward behaviour; then enter Event and Shop from Map and return to the same run after the branches and Team 7 definitions are integrated. Record actual results and screenshots when performed.
• For integration notes and reproducible checks, see the Sprint 4 guide in this PR.