# dropTablesKit.api
Weighted drop tables with a pity timer, called by a game's kill, crate or chest handler (on the host in multiplayer).
- `roll(tableId, kind?, rng?)` rolls the table's chance (scaled by the `kinds` multiplier for what was defeated), counts dry streaks for the pity timer, and returns a weighted item id or nil.
- `pick` draws an item by weight alone; `define`, `get`, `has`, `ids`, `items` manage tables of any item ids.
- `rate` and `odds` read a table for menus and catalogs; `dryStreak` and `resetPity` read and reset the pity counters; `seeded` gives a deterministic random source.
Ships five twin-stick power-up presets: generous, standard, offense, survival, stingy.
# 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.
```luau
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`):
| 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 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.