LootPlan - Random loot generation made easy

LootPlan is a lightweight portable ModuleScript I’ve created to solve any loot generation needs you may have. The module has example scripts, but most heavy documentation will be in this post.

The documentation is detailed to make sure nothing is missed, but you can probably get the jist of it by simply skimming over it, or looking at the code examples. The system is quite simple, with the module code only taking up 133 lines.


Classes

There are two classes of LootPlan; “single” and “multi”.
Each class is fundamentally different in the way it handles loot.
To create a LootPlan, require the module and give it a variable, then use LootPlan.new(“class”)

local LootPlan = require(game.ReplicatedStorage.LootPlan)
local Test = LootPlan.new("single")

"single" LootPlans

These LootPlans are great for any objects that can only have a single value. For example, you may want to create a mining game where different ores could spawn. Each ore could only have a single type, so you would use a “single” LootPlan.

To use LootPlans, you must add loot. In this case, “Loot” is simply a name with a rarity attached to it. Example code;

local LootPlan = require(game.ReplicatedStorage.LootPlan)
local OrePlan = LootPlan.new("single")

-- The first argument is the name, the second is the rarity
OrePlan:AddLoot("diamond",0.01)
OrePlan:AddLoot("gold",2)
OrePlan:AddLoot("iron",10)
OrePlan:AddLoot("stone",100)

To retrieve loot from the LootPlan, simply call “GetRandomLoot”

local OreType = OrePlan:GetRandomLoot()
print(OreType)

Rarity for “single” LootPlans is calculated relative to the total rarity values of all loot.
In this example, the combined rarity value is 112.01 (100+10+2+0.01)
That means the Iron ore has a true rarity of 10/112.01 = 8.927%
The diamond ore has a true rarity of 0.01/112.01 = 0.0089% (approx 1/11000)


"multi" LootPlans

This class of LootPlan is ideal for scenarios where you need multiple items at once. For example after killing a mob in an MMO, they have a loot table of items they may drop. Since there are multiple items, you use a “multi” LootPlan.

Unlike “single” LootPlans, this class returns a table of multiple items. When using the AddLoot function, there is an additional variable for the quantity of items to add.

Like before, we create a plan and add loot to it;

local LootPlan = require(game.ReplicatedStorage.LootPlan)
local DropPlan = LootPlan.new("multi")

-- The arguments follow the order (name, quantity, rarity)
DropPlan:AddLoot("wizard hat", 1, 0.1)
DropPlan:AddLoot("dagger", 1, 2) 
DropPlan:AddLoot("arrow", 5, 10) 
DropPlan:AddLoot("gold coin", 20, 80)

Similar to the other method, you call “GetRandomLoot()” to retrieve random loot.
This class has an extra argument for GetRandomLoot. The argument defines how many times the function runs. The more times it runs, the more items will be in the loot table. The quantity of items received also changes based on the quantity you set with AddLoot.

local Drops = DropPlan:GetRandomLoot(1)
for LootName,LootQuantity in pairs(Drops) do
    print(LootName,"=",LootQuantity)
end

The rarity for “multi” LootPlans work differently. Instead of being based on the combined rarity, it is simply a flat percentage out of 100. A item with a rarity of 50 will have a 50% chance of appearing in the loot table, regardless of the rarity of other items.


Other functions

LootPlans allow you to change/add/remove loot dynamically with low performance impact. This is useful for any scenario the rarity needs to change quickly, such as changing ore rarity based on depth.

ChangeLootRarity

-- "single" LootPlan
OrePlan:ChangeLootRarity("iron",20)

-- "multi" LootPlan
DropPlan:ChangeLootRarity("arrow", 5, 10, 20) -- (name, quantity, rarity, newRarity) 

ChangeLootQuantity

-- This function only applies to "multi" LootPlans
DropPlan:ChangeLootQuantity("wizard hat", 1, 0.1, 3) -- (name, quantity, rarity, newQuantity)

RemoveLoot

-- "single" LootPlan
OrePlan:RemoveLoot("iron")

-- "multi" LootPlan
DropPlan:RemoveLoot("dagger", 1, 2) -- (name, quantity, rarity)

The “multi” LootPlan functions above require the quantity and rarity to be provided. This is to correctly identify the right loot entry when there are multiple loot entries with the same name.

33 Likes

Very useful, it simplifies life a lot instead of having to keep creating lines and lines of code, I haven’t tested it in practice, but I’ve read everything, very cool, good job, thanks for sharing :slight_smile: