WeightedLoot

Plug-and-play weighted loot for Roblox: merge item tables, compile pools, and roll with named luck presets.

Install (Wally)

Add to your project's wally.toml:

[dependencies]
WeightedLoot = "csynt/weighted-loot@0.1.0"

Then run:

wally install

Map the package in your Rojo default.project.json (Wally usually writes this into wally.lock for you):

"WeightedLoot": {
  "$path": "Packages/weighted-loot"
}

Quick start

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local WeightedLoot = require(ReplicatedStorage.Packages.WeightedLoot)

local Items = {
	Sword = { Weight = 50 },
	Shield = { Weight = 30 },
	RareGem = { Weight = 1 },
}

-- 1. Merge sources (optional if you only have one table)
local pool = WeightedLoot.format(Items)

-- 2. Compile once, reuse for every roll
local compiled = WeightedLoot.compile(pool, { mode = "rarity" })

-- 3. Roll with luck
local index, entry = WeightedLoot.roll(compiled, {
	luck = 1_000_000,
	curve = "RollLuck",
})

print(index, entry) -- e.g. 3, { Weight = 1, ... }

One-liner (format + compile)

local compiled = WeightedLoot.compileFormatted({ mode = "rarity" }, Items, BonusItems)
local index = WeightedLoot.rollIndex(compiled, { luck = 32_000_000, curve = "RollLuck" })

API

Compile options

• mode: "rarity" (default, weight = 1-in-N) or "frequency" (weight = relative chance)
• weightKey: field name to read weights from (default "Weight"; falls back to Rarity)

Roll options

• luck: multiplier (default 1)
• curve: "NoLuck", "RollLuck" (default for rarity mode), or "FrequencyLuck"
• rng: custom Random instance

Luck tuning

Edit RollLuck on the module export to rebalance high-luck rolls:

WeightedLoot.RollLuckConfig.playableSlope = 1.25

Preset names are listed in WeightedLoot.PRESET_NAMES.

Legacy lottery API

Older code using formatLottery, buildLottery, or getRandomItemFromLottery can keep using the same names — they are attached to the main export for backward compatibility.

Development

aftman install
wally install   # only needed if you add dev-dependencies
rojo serve

Publish to the Wally index by opening a PR on UpliftGames/wally-index after pushing a git tag that matches wally.toml version.