Store Mechanics Document
This document provides a detailed overview of the store mechanics implemented in the game, explaining how items are displayed, purchased, and managed.
Overview
The store system allows players to purchase items such as clothing, rewards, and other in-game assets. It integrates with the inventory and currency systems to ensure seamless transactions and player engagement.
Key features include:
- Displaying store items with detailed information.
- Currency-based purchasing with validation.
- UI for browsing, selecting, and buying items.
- Reward delivery for purchased items.
Core Concepts
1. Store Item Templates
Store item templates define the attributes and costs of items available for purchase.
Attributes
- ID (
_id
): Unique identifier for the store item. - Display Data (
_displayData
): Visual representation, including name and image. - Cost (
_cost
): Price of the item in the specified currency. - Currency Cost Template (
_currencyCostTemplate
): Defines the type of currency required. - Reward Template (
_clothingCollectionRewardTemplate
): Specifies the rewards for purchasing the item.
Key Functions
GetId
: Retrieves the item ID.GetCost
: Returns the cost of the item.GetCurrencyCostTemplate
: Retrieves the currency type.
2. Item Store
The ItemStore.lua
module manages the logic for purchasing items and validating transactions.
Responsibilities
- Handling player purchase requests.
- Validating player ownership and currency.
- Deducting currency and awarding items.
- Saving updated player data.
Key Functions
RequestPurchaseItem
: Sends a purchase request to the server.OnPurchaseItemRequest
: Handles server-side purchase validation.OnPurchaseItemResponse
: Processes the server's response to a purchase.
Error Codes
- None (0): No error.
- NotEnoughCurrency (1): Insufficient currency.
- AlreadyOwned (2): Player already owns the item.
- ItemNotFound (3): Item does not exist.
- UnknownError (4): An unexpected error occurred.
3. UI Item Store
The UIItemStore.lua
script manages the visual and interactive aspects of the store.
Responsibilities
- Displaying available items and their details.
- Handling item selection and purchase confirmation.
- Updating the UI with player currency and ownership status.
Key Functions
Refresh
: Updates the store UI with current items and player currency.CreateStoreEntry
: Creates UI elements for individual store items.OnClickedItem
: Handles the purchase confirmation dialog.OnPurchasedItem
: Displays rewards and refreshes the store after purchase.
Workflow
-
Opening the Store
- Triggered by interacting with an NPC or UI element.
- The store UI is initialized with available items and player data.
-
Browsing Items
- Players can view item details, including name, cost, and icon.
- Owned items are marked, and unavailable items are greyed out.
-
Purchasing an Item
- Players select an item and confirm the purchase in a dialog.
- A server request validates the transaction.
-
Delivering Rewards
- Upon successful purchase, rewards are delivered to the player’s inventory.
- The UI updates to reflect the new ownership and currency balance.
Example Implementation
Example Store Item Template
local storeItemTemplate = {
_id = "item_001",
_displayData = displayTemplate,
_cost = 100,
_currencyCostTemplate = currencyTemplate,
_clothingCollectionRewardTemplate = rewardTemplate,
}
Requesting a Purchase
ItemStore.RequestPurchaseItem("item_001", function(response)
if response.Success then
print("Purchase successful!")
else
print("Purchase failed with error code:", response.Code)
end
end)
Key Events
OnPurchaseItemRequest
Triggered when a player requests to purchase an item.
OnPurchaseItemResponse
Handles the server’s response to a purchase request.
OnClickedItem
Handles the player’s interaction with a store item.
Refresh
Updates the store UI with current data.