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
-
Creating a Loot Container
- Define guaranteed items and their ranges.
- Specify additional items, their ranges, and weights.
-
Rolling for Rewards
- Call
Roll
with the appropriate loot container. - Guaranteed rewards are added first.
- Additional rewards are determined based on weighted probabilities.
- Call
-
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.