Loot Table Simulator

Project roadmap

1. 01

   Define the loot table format

   ~1h

   Write README.md with an example loot table file, which is a Lua file returning a table: a list of items, each with a name, a weight (a positive number) and a rarity (common, rare, epic or legendary), plus an optional chance of dropping nothing. Show the expected output of a simulation. Done when: README.md has a complete example table and output.

2. 02

   Load and validate the table

   ~1.5h

   Load the file with loadfile in an empty environment, so it can contain only data. Check every item: the name is a non-empty string and unique, the weight is a positive number, and the rarity is one of the allowed values. Report all problems at once with the item's position. Done when: a valid table loads, and a table with a negative weight and a duplicate name reports both.

3. 03

   Roll the table

   ~1.5h

   Implement weighted random selection: add up all weights, pick a random number between 0 and the total, and walk the items until the running sum passes it. Calculate each item's expected chance (its weight divided by the total). Add a --seed option so results can be repeated. Done when: rolling a table with weights 1 and 3 gives the second item about 75% of the time.

4. 04

   Simulate and report

   ~1.5h

   Add --rolls (default 10,000). Count each item's drops and print a table with the item, rarity, expected percentage, actual percentage and the difference, aligned with string.format and sorted by rarity then name. Add a summary per rarity. Done when: with 100,000 rolls, the actual percentages are within a fraction of a percent of the expected ones.

5. 05

   Answer the designer's question

   ~1h

   Add --until ITEM: simulate many players rolling until they get that item, and report the average, the median and the 90th percentile number of kills needed (90% of players got it by then). Compare the average with the theoretical value, 1 divided by the item's chance. Done when: the simulated average is close to the theoretical one for a rare item.

6. 06

   Test it

   ~1h

   Write tests with busted: validation rules, a table with a single item always returns it, a fixed seed gives the same results, and zero-weight or empty tables are refused. Package the tool with a rockspec so it installs with luarocks make. Done when: busted passes, and the tool installs as a command.

Resources

• DocsProgramming in Lua (first edition, free online)
• DocsLua 5.4 reference manual
• ArticleWeighted random selection explained
• DocsLuaRocks: creating a rock
• Docsbusted testing framework