Log inGet started
World

Drop Tables Kit: Weighted Loot Rolls with Pity Timer

Branchmain
Commit91ce3c958c

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 = 1 with 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 with get.

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):

iddropspity
generousabout a third of kills4
standardabout one kill in seven10
offenseweapons and the odd bomb only9
survivalshields, speed, magnets, lives10
stingyone kill in twenty25

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 as rng.

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.