{"id":"xsyrei/weighted-loot","name":"weighted-loot","scope":"xsyrei","platform":"roblox","description":"Plug-and-play weighted loot tables with luck curve presets","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"c40b14794ca4dd1e8500c1c37cfbae5135baa6c4b83c798ba0b0cf303dbf034a","likes":0,"downloads":0,"install":"forest install xsyrei/weighted-loot","url":"https://forest.dev/p/roblox/xsyrei/weighted-loot","files":"https://api.forest.dev/ai/package/roblox/xsyrei/weighted-loot/files","readme":"# WeightedLoot\n\nPlug-and-play weighted loot for Roblox: merge item tables, compile pools, and roll with named luck presets.\n\n## Install (Wally)\n\nAdd to your project's `wally.toml`:\n\n```toml\n[dependencies]\nWeightedLoot = \"csynt/weighted-loot@0.1.0\"\n```\n\nThen run:\n\n```sh\nwally install\n```\n\nMap the package in your Rojo `default.project.json` (Wally usually writes this into `wally.lock` for you):\n\n```json\n\"WeightedLoot\": {\n  \"$path\": \"Packages/weighted-loot\"\n}\n```\n\n## Quick start\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal WeightedLoot = require(ReplicatedStorage.Packages.WeightedLoot)\n\nlocal Items = {\n\tSword = { Weight = 50 },\n\tShield = { Weight = 30 },\n\tRareGem = { Weight = 1 },\n}\n\n-- 1. Merge sources (optional if you only have one table)\nlocal pool = WeightedLoot.format(Items)\n\n-- 2. Compile once, reuse for every roll\nlocal compiled = WeightedLoot.compile(pool, { mode = \"rarity\" })\n\n-- 3. Roll with luck\nlocal index, entry = WeightedLoot.roll(compiled, {\n\tluck = 1_000_000,\n\tcurve = \"RollLuck\",\n})\n\nprint(index, entry) -- e.g. 3, { Weight = 1, ... }\n```\n\n### One-liner (format + compile)\n\n```lua\nlocal compiled = WeightedLoot.compileFormatted({ mode = \"rarity\" }, Items, BonusItems)\nlocal index = WeightedLoot.rollIndex(compiled, { luck = 32_000_000, curve = \"RollLuck\" })\n```\n\n## API\n\n| Function | Description |\n| --- | --- |\n| `format(...)` | Merge string-keyed loot tables into one pool |\n| `compile(pool, opts?)` | Build a reusable compiled table |\n| `compileFormatted(opts?, ...)` | `format` + `compile` in one step |\n| `roll(compiled, opts?)` | Returns `index, entry` |\n| `rollIndex(compiled, opts?)` | Returns winning index only |\n| `getEffectiveRollWeight(compiled, index, luck?, curve?)` | Debug roll weight for one entry |\n| `getEffectiveRarity(nominalWeight, luck?, curve?)` | Debug effective 1-in-N rarity |\n\n### Compile options\n\n- `mode`: `\"rarity\"` (default, weight = 1-in-N) or `\"frequency\"` (weight = relative chance)\n- `weightKey`: field name to read weights from (default `\"Weight\"`; falls back to `Rarity`)\n\n### Roll options\n\n- `luck`: multiplier (default `1`)\n- `curve`: `\"NoLuck\"`, `\"RollLuck\"` (default for rarity mode), or `\"FrequencyLuck\"`\n- `rng`: custom `Random` instance\n\n### Luck tuning\n\nEdit `RollLuck` on the module export to rebalance high-luck rolls:\n\n```lua\nWeightedLoot.RollLuckConfig.playableSlope = 1.25\n```\n\nPreset names are listed in `WeightedLoot.PRESET_NAMES`.\n\n## Legacy lottery API\n\nOlder code using `formatLottery`, `buildLottery`, or `getRandomItemFromLottery` can keep using the same names — they are attached to the main export for backward compatibility.\n\n## Development\n\n```sh\naftman install\nwally install   # only needed if you add dev-dependencies\nrojo serve\n```\n\nPublish to the Wally index by opening a PR on [UpliftGames/wally-index](https://github.com/UpliftGames/wally-index) after pushing a git tag that matches `wally.toml` version.\n","readmeTruncated":false}