Drop Tables Kit: Weighted Loot Rolls with Pity Timer
README.md
Drop Tables Kit
What a defeated enemy, a broken crate or an opened chest drops, as swappable tables with weighted picks and a pity timer. Pure Luau, no dependencies, works in any game.
local Drops = require("dropTablesKit.api")
Drops.define("dungeon", {
chance = 0.25, -- a quarter of rolls drop something
pity = 6, -- after 6 dry rolls the next one always drops
kinds = { boss = 4, elite = 2, rat = 0.3 },
weights = { gold = 10, potion = 5, sword = 2, crown = 0.2 },
})
local item = Drops.roll("dungeon", "elite") -- "gold", "potion", ... or nil
Tables
A table is { chance, pity?, kinds?, weights, items?, label?, description?, lifetime? }:
chance: the base chance (0..1) that one roll drops anything.kinds: multipliers on the chance by what was defeated (boss = 1with a chance of 1 means always).weights: how likely each item is once something drops. Any item ids.pity: after this many rolls in a row with no drop, the next roll always drops (bad luck protection).items: optional draw order; otherwise the preset order, then any other items alphabetically.- Anything else (
lifetime,label,description) is yours to read back withget.
Shipped presets (Drops.TABLES)
Tuned for arena and twin-stick shooters, with power-up ids (spreadShot, rapidFire, piercing, homing, shield, speed, damage, magnet, bomb, extraLife):
| id | drops | pity |
|---|---|---|
generous | about a third of kills | 4 |
standard | about one kill in seven | 10 |
offense | weapons and the odd bomb only | 9 |
survival | shields, speed, magnets, lives | 10 |
stingy | one kill in twenty | 25 |
Use them as they are, copy and change them with define, or ignore them.
API
roll(tableId, kind?, rng?): one roll with chance, multipliers and pity. Returns an item id or nil.pick(tableId, rng?): a weighted pick with no chance and no pity (a chest that always gives something).define(id, table),get(id),has(id),ids(),items(id): manage and read tables.rate(tableId, kind?): expected drops per 100 rolls before pity;odds(tableId): each item's share.dryStreak(tableId),resetPity(tableId?): read and reset the pity counters (reset at the start of a run).seeded(seed): a deterministic 0..1 random source to pass asrng.
Roll on the host (or server) in multiplayer and send the result, so every player sees the same drop.
The test suite dropTablesKit checks the rates, the pity timer and custom items.