Terminal Dice Lab
Build a dice laboratory in Rust for the terminal: type dice expressions from tabletop games, such as 3d6+2, 4d6 keep the highest 3, or 2d20 drop the lowest, and roll them, or simulate them thousands of times to see the distribution of results as a text histogram, with the average and chances of reaching a target. A seed makes every experiment exactly repeatable. It's a good first Rust project: you'll learn parsing text into a small expression structure, enums and pattern matching, error handling with Result, seeded random numbers with the rand crate, collecting statistics, and command-line options with clap.
- Estimate
- ~7.5h
- Steps
- 5
- Completed by
- 0
- Proposed by
- codeseed.app
Cargo · clap · rand
Project roadmap
- 01
Define the dice expressions
~1hWrite README.md with the supported expressions: NdS (N dice with S sides), a + or - modifier, kh K and kl K to keep the highest or lowest K dice, dh and dl to drop, and several terms added together (such as 2d6+1d4+3), with limits (at most 100 dice and 1,000 sides). Show the commands roll EXPR and sim EXPR --runs N --seed S, and example output. Create the project with clap and rand. Done when: README.md defines the expressions and commands.
- 02
Parse expressions
~2hDefine an enum-based structure for expressions (a list of terms, each a dice group with its keep or drop rule, or a constant) and write a parser that turns a string into it, returning a Result with a clear error message and the position of the problem for invalid input. Done when: unit tests parse valid expressions correctly and reject invalid ones with helpful messages.
- 03
Roll the dice
~1.5hEvaluate an expression with a random number generator passed in as a parameter (a seeded StdRng for repeatability), returning the total and the individual dice, with dropped dice marked. The roll command prints something like 4d6kh3: [6, 5, 2, (1)] = 13. Done when: rolling with the same seed always gives the same results.
- 04
Simulate and summarize
~1.5hThe sim command rolls the expression N times (default 100,000), counts each total in a HashMap or a Vec, and prints the minimum, maximum, mean and standard deviation, a text histogram with percentages, and with --target T the chance of rolling at least T. Done when: simulating 2d6 shows 7 as the most common result, at about 16.7%.
- 05
Test it
~1.5hWrite tests: parsing (including every error case), evaluation with a fixed seed, keep and drop rules, totals always within the possible range, and simulation results close to the exact values for simple cases (such as 1d6 averaging 3.5). Run cargo clippy. Done when: cargo test passes, and clippy has no warnings.
Resources
Ready to build this?
Get a GitHub repo and start building. Your AI reviewer checks each step as you go.
Tech stack