Shop Encounter System

Overview

The Shop Encounter System handles shop items, prices, stock, purchase validation, and purchase results for Team 2's non-battle encounter feature.

This system provides the core transaction logic for shop encounters. It makes sure that a purchase only succeeds when the item exists, the item data is valid, the item has stock, and the player has enough gold.

Main Classes

• ShopItem: Stores shop item data, including item ID, card ID, display name, price, and stock.
• ShopConfig: Stores the shop item list loaded from config data.
• ShopService: Handles shop item lookup, validation, stock checks, and transaction-safe purchases.
• PurchaseResult: Represents the result of a purchase attempt, including success or failure reason.
• ShopEncounter: Connects the shop flow to the non-battle encounter/map callback framework.
• ShopDisplay: A prototype UI component used to test the shop flow.

Shop Item Data

Shop item data is stored in core/assets/configs/shopItems.json.

Each shop item contains:

• id: the shop item ID
• cardId: the card ID added to the player's deck or card collection after purchase
• name: the display name shown to the player
• price: the gold cost
• stock: how many times the item can be bought

Current Sprint 1 shop card IDs:

• strike
• defend
• poison_dagger
• expose
• inner_focus
• bandage

Purchase Flow

1. The player selects a shop item.
2. ShopService checks whether the item exists.
3. ShopService checks whether the item data is valid.
4. ShopService checks whether the item has stock.
5. ShopService checks whether the player inventory is valid.
6. ShopService checks whether the player has enough gold.
7. If all checks pass, the player pays gold and receives the card.
8. The shop item stock is reduced.
9. A PurchaseResult is returned to describe the purchase result.

Transaction Safety

The purchase flow is designed to avoid inconsistent transactions.

If a purchase fails, the shop system should not deduct gold, add a card, or reduce stock.

This prevents cases such as:

• gold being deducted but no card being added
• stock being reduced when the purchase fails
• an invalid item being purchased
• an out-of-stock item being purchased

Purchase Results

PurchaseResult is used to return the result of a purchase attempt.

Possible outcomes include:

• purchase available
• purchase success
• item not found
• invalid item
• out of stock
• invalid inventory
• insufficient gold
• transaction failed

Encounter Integration

ShopEncounter connects the shop system with the non-battle encounter framework.

When the shop encounter finishes, it calls the encounter callback to report whether the encounter was completed successfully.

Integration With Other Teams

The shop system stores a cardId for each shop item.

For Sprint 1, the shop can pass this cardId as a string to the PlayerDeck/Card API.

Expected future methods from Team 5:

• canAddCard(cardId)
• addCard(cardId)

The purchased card should be added to the player's permanent PlayerDeck or card collection, not directly to the BattleDeck.

For Sprint 1, the shop system does not require a deck-size limit or duplicate-card limit.

Testing

Unit tests cover:

• successful purchases
• insufficient gold
• out-of-stock items
• invalid items
• unknown item IDs
• transaction failure
• stock changes after purchase
• no gold/card/stock changes after failed purchases
• encounter callback behaviour when the shop encounter completes

The following checks were run successfully:

• .\gradlew.bat format
• .\gradlew.bat :core:test

Related Pull Request

Shop system framework PR: #40 - [Team 2] Add shop encounter transaction framework (#6)