• Studio

  • Studio API

  • Bots

  • Web API

  • Designer Resources

  • Host Resources

  • CREATE

    Examples

    Full Worlds

    Dress Up NPC

    Game Mechanics

    Edit

    Loot Mechanics

    This document provides an overview of the loot mechanics implemented in the game, detailing how loot is defined, managed, and distributed.

    Overview

    The loot system governs the distribution of rewards in the game, such as currency, clothing items, and collections. It ensures a balance between guaranteed and randomized rewards, enhancing the player’s engagement and sense of accomplishment.

    Key features include:

    • Guaranteed loot rewards for specific actions or milestones.
    • Randomized additional loot to introduce variety.
    • Weighted probability for additional rewards.
    • Integration with other gameplay systems, such as quests and events.

    Core Concepts

    1. Loot Containers

    Loot containers serve as the primary structure for defining and managing rewards. Each container specifies guaranteed rewards and additional items with probabilities.

    Loot Container Attributes

    • Guaranteed Loot List (_guaranteedLootList): Items guaranteed to be included in the reward.
    • Guaranteed Loot Ranges (_guaranteedLootRanges): Quantity ranges for each guaranteed item.
    • Additional Loot Count Range (_additionalLootCountRange): Number of additional items to include, selected randomly.
    • Additional Loot List (_additionalLootList): Items eligible for random inclusion.
    • Additional Loot Ranges (_additionalLootRanges): Quantity ranges for each additional item.
    • Additional Loot Weights (_additionalLootWeights): Probabilities for selecting each additional item.

    Key Functions

    • GetGuaranteedLootList: Retrieves the guaranteed loot items.
    • GetGuaranteedLootRanges: Retrieves the quantity ranges for guaranteed loot.
    • GetAdditionalLootCountRange: Retrieves the range for the number of additional items.
    • GetAdditionalLootList: Retrieves the additional loot items.
    • GetAdditionalLootWeights: Retrieves the weights for additional items.

    2. Loot Items

    Loot items represent the individual rewards within the loot system. They can include:

    • Currency: In-game currency rewards.
    • Clothing: Individual clothing items.
    • Collections: Bundles of themed clothing items.

    Reward Template Logic

    The reward template determines the type of item distributed. Key logic includes:

    • Prioritizing specific reward templates (e.g., clothing over currency).
    • Returning nil if no reward template is defined.

    3. Loot Manager

    The LootManager.lua handles the primary logic for distributing rewards, ensuring that all conditions and probabilities are adhered to.

    Responsibilities

    • Calculating guaranteed rewards.
    • Determining additional rewards based on weights.
    • Returning a finalized list of rewards.

    Key Functions

    • GetRandomAmount: Generates a random quantity within a specified range.
    • Roll: The main function to generate a list of rewards from a loot container.
    • AddRewardToList: Adds rewards to a list, merging stackable items if applicable.
    • GetRewardInList: Finds and updates existing rewards in a list.

    Workflow

    1. Creating a Loot Container

      • Define guaranteed items and their ranges.
      • Specify additional items, their ranges, and weights.
    2. Rolling for Rewards

      • Call Roll with the appropriate loot container.
      • Guaranteed rewards are added first.
      • Additional rewards are determined based on weighted probabilities.
    3. Distributing Rewards

      • The final reward list is passed to the relevant gameplay system (e.g., quest completion or event rewards).

    Example Implementation

    Example Loot Container

    local lootContainer = {
      _guaranteedLootList = {currencyReward, clothingItem},
      _guaranteedLootRanges = {Vector3.new(10, 20), Vector3.new(1, 1)},
      _additionalLootCountRange = Vector3.new(1, 3),
      _additionalLootList = {extraClothing, rareItem},
      _additionalLootRanges = {Vector3.new(1, 2), Vector3.new(0, 1)},
      _additionalLootWeights = {75, 25},
    }
    

    Rolling for Rewards

    local rewards = LootManager.Roll(lootContainer)
    for _, reward in ipairs(rewards) do
      print("Reward:", reward.Template.Id, "Amount:", reward.Amount)
    end
    

    Key Events

    Guaranteed Loot

    Ensures players always receive core rewards, maintaining predictability for critical gameplay moments.

    Additional Loot

    Adds excitement and variability, using weights and ranges to balance rarity and accessibility.

    Updated about 1 month ago

    PocketWorlds Icon

    © 2025 Pocket Worlds. All rights reserved.