#roll-dice #cli #rpg #random #dice #roll

bin+lib rollr

A lightweight CLI tool and Rust library to roll RPG dice (e.g. 2D20) or flip a coin.

2 unstable releases

Uses new Rust 2024

0.2.0 Apr 18, 2025
0.1.0 Apr 18, 2025

#2 in #roll

Download history 258/week @ 2025-04-16 13/week @ 2025-04-23

271 downloads per month

MIT license

10KB
143 lines

🎲 Rust Dice Roller

Crates.io Docs.rs CI

A small CLI tool to roll dice or flip a coin using Rust.

Features

  • Roll dice in RPG format (e.g., 2D20, 1D6)
  • Flip a coin with commands like flipcoin, flip, or f
  • Only allows valid dice types: D3, D4, D5, D6, D7, D8, D10, D12, D14, D16, D20, D24, D30, D50, D60, D100
  • Graceful fallback to default 1D6 if input is missing or malformed

🧠 Supported Input Formats

Input Behavior
(none) Defaults to rolling 1D6
D6 Interpreted as 1D6
2D20 Rolls two D20 dice
3d100 Case-insensitive β†’ 3D100
1 Interpreted as 1D6
1D Fallback β†’ 1D6
2D99 Invalid die type β†’ fallback to 2D6
fezfe Malformed β†’ fallback to 1D6

Dice types not included in the supported enum are automatically rejected and fallback to D6.

πŸ“š Library & CLI

This project is structured as a hybrid library + binary crate:

It provides:

  • A CLI entry point in src/main.rs,
  • Reusable modules:
    • dices.rs: handles parsing and validating dice expressions,
    • throw.rs: handles random dice rolls and coin flips.

πŸ“¦ As a library dependency

You can install it with:

cargo add rollr

Or manually add it to your Cargo.toml:

[dependencies]
rollr = "0.1.0"

If you’re using the crate locally (e.g. during development), reference it via a local path:

[dependencies]
rollr = { path = "../path/to/rollr" }

🧰 As a binary

You can also use rollr as a command-line tool without embedding it into another project.

πŸš€ Running from source:

cargo run -- 3D20
cargo run -- flip

πŸ“¦ Install locally (for global CLI use):

Install it as a binary:

cargo install rollr

Then use it from anywhere:

rollr 2D6
rollr flip

Don’t forget to add $HOME/.cargo/bin to your PATH if it’s not already.

Dependencies

~2.5–3.5MB
~61K SLoC