Shop Encounter System - Sprint 2 Integration

Overview

Sprint 2 extends the Shop Encounter System from the original transaction framework into the shared Map -> Encounter -> Map runtime flow. The Shop-side integration creates an encounter inventory from the card catalogue and ensures a successful purchase is written to the PlayerDeck owned by the current RunState.

This work keeps Shop purchasing behind integration boundaries so that card lookup, deck mutation, validation, and rollback behaviour remain testable without coupling the Shop domain directly to UI code.

Sprint 2 Scope

• Generate a random Shop inventory for an encounter from the available card catalogue.
• Adapt CardService data for Shop inventory generation.
• Adapt the shared PlayerDeck for Shop purchases in the real encounter flow.
• Keep purchase validation and rollback behind transaction gateway interfaces.
• Add a regression test proving purchased cards remain in the same run-scoped deck after leaving and re-entering Shop.

Main Components

• ShopInventoryGenerator: produces the inventory offered by a Shop encounter.
• CardServiceCatalogAdapter: provides catalogue data from CardService to the Shop inventory generator.
• PlayerDeckAdapter: presents the shared PlayerDeck to the Shop integration layer.
• DeckGateway: defines the deck operations required by Shop purchasing.
• IntegratedShopTransactionGateway: connects Shop purchase validation to the integrated transaction flow.

Shared PlayerDeck Contract

The authoritative PlayerDeck is owned by RunState. Map, Encounter, and Battle use the same run-scoped deck instance.

During the Map -> Encounter flow, EncounterGameArea receives the PlayerDeck from RunState and uses PlayerDeckAdapter for the real Shop path. This means a card bought in Shop remains available after leaving and re-entering the encounter, rather than being stored in temporary local inventory state.

The current Sprint 2 contract allows duplicate cards and does not enforce a deck-size limit.

Shop Purchase Flow

1. The player enters a Shop encounter from the map.
2. ShopInventoryGenerator creates the offered inventory using CardServiceCatalogAdapter.
3. Shop validates the selected item and transaction request through the transaction gateway.
4. A successful purchase writes the card to the PlayerDeck owned by RunState through PlayerDeckAdapter.
5. The Shop reports completion through the encounter callback and returns to the same run.
6. Re-entering Shop reads the same run-scoped PlayerDeck, so the purchased card persists for the run.

Verification

The integration and regression coverage verifies that:

• Shop inventory can be generated from the card catalogue.
• a successful Shop purchase is recorded in the PlayerDeck owned by RunState;
• re-entering Shop retrieves the same run-scoped PlayerDeck;
• the purchased card remains in the deck; and
• the transaction gateway continues to validate a later purchase.

The following checks passed:

• .\gradlew.bat test --tests com.csse3200.game.encounters.integration.ShopSprint2IntegrationTest --rerun-tasks
• .\gradlew.bat spotlessCheck
• git diff --check

Related Pull Requests

• PR #177: Add random shop inventory and Card/Deck integration
• PR #216: Share player state across battle and encounters
• PR #222: Test Shop purchase persistence in shared RunState deck

Follow-up Work

Discount coverage can be added once the shared getShopDiscount() interface is available. End-to-end Shop purchase -> Save/Load persistence coverage should be added when the Team 5 Save/Load integration is available on the Team 2 branch.