• Studio

  • Studio API

  • Bots

  • Web API

  • Designer Resources

  • Host Resources

  • CREATE

    Examples

    Full Worlds

    Dress Up NPC

    Game Mechanics

    Edit

    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

    1. Opening the Store

      • Triggered by interacting with an NPC or UI element.
      • The store UI is initialized with available items and player data.
    2. Browsing Items

      • Players can view item details, including name, cost, and icon.
      • Owned items are marked, and unavailable items are greyed out.
    3. Purchasing an Item

      • Players select an item and confirm the purchase in a dialog.
      • A server request validates the transaction.
    4. 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.

    Updated about 1 month ago

    PocketWorlds Icon

    © 2025 Pocket Worlds. All rights reserved.