Clattr Bot

An experimental dice bot for Discord.

Features

Multiple Rolls: make multiple rolls on a single line, separated by a comma

Math: add, subtract, multiply and divide dice results and modifiers

Tag Your Rolls: label your rolls with tags, so the results will be marked

Keeping & Discarding Rolls: roll multiple dice and keep the lowest or highest

Exploding Dice: with optional target numbers for explosions

Wild Dice: supports Savage Worlds-style wild dice natively

Dice Pools: Clattr supports game systems that use dice pools with target numbers

Fate Dice: You can use fate dice too

Cleans Up its Mess: Clattr removes your roll message and tags you with the result - clattr, but no cluttr!

Nicely Formatted: Clattr puts its results first, roll details later for easy reading

Better Randomness: Clattr will give more 'random-feeling' results than some dice rollers, no streaks or runs (it uses the mersenne-twister PRNG algorithm, if you're curious)

Playing Cards: fully simulated playing card decks, for use in Savage Worlds initiative, your Deck of Many Things, or any other card-based game mechanic

Supported Games

D20/D&D: dice rolls, modifiers, rolling with advantage and disadvantage - everything you need for 2nd - 5th edition, Pathfinder, and other D20 games

WoD, nWoD, Exalted: and other Storyteller-based games, with clean easy syntax

Shadowrun: supports exploding dice

Fate: has special rules for fate dice

Savage Worlds: wild dice and playing card support, plus all the other dice features

Almost Everything Else: but if you can't use it with your favorite game, or it's kinda clunky, let me know

Quick Examples:

| Example | result | |------------------|--------| | !r d20 #hit | roll 1d20, with the tag 'hit' | | !r 2d20k1+3 | roll 2 d20s, keep the highest, and add 3 | | !r 4d20l2-1 | roll 4 d20s, keep the lowest 2, and subtract 3 | | !r 3d6! | roll 3 exploding d6s | | !r 3d6!5 | roll 3 exploding d6s that explode on 5 or 6 | | !r 3d6!m1 | roll 3 exploding d6s, but they only explode once | | !r 3d6!5m1 | roll 3 exploding d6s that explode once on 5 or 6 | | !r 3d6!5m1k2 | roll 3 exploding d6s that explode once on 5 or 6, keep the highest 2 | | !r 3p6t4 | roll a pool of 3d6, counting 4 or higher as a hit | | !r 3p6t4! | roll a pool of 3d6, counting 4 or higher as a hit, exploding on 6 | | !r 4f+3 | roll 4 fate dice, add 3 to the result | | !r w8+2 | roll a d8 with a d6 wild die, add 2 to the greater of the two | | !c 2 | draw 2 cards from the guild deck | | !c 2 foo | draw 2 cards from the deck named 'foo' | | !c shuffle | shuffle the guild deck | | !c shuffle foo | shuffle the guild deck | | !c list | list all decks in play | | !c remove foo | remove the deck named 'foo' from play |

Check out the wiki for full documentation, and the examples section for more usage examples.

Setup

Clattr is currently in testing and you probably shouldn't even be reading this. You can't install the "official" version because it's not hosted online. You'll have to run it on your own computer for now, or know someone who does. Will set up a server after completing the rest of its needed features.

1. download the source code: git clone https://github.com/nphyx/clattr-bot
2. change to the clattr-bot directory: cd clattr-bot
3. install packages: npm install .
4. follow standard Discord bot setup procedure [https://discordjs.guide/#/preparations/setting-up-a-bot-application]
5. get your bot token (use the guide above, and note that Clattr requires the 'manage messages' permission)
6. copy .env.example to .env and fill out the environment variables
7. run the bot, in Linux: npm start
8. start playing!

Roadmap

• coin tosses: you can simulate coin tosses with 1d2, but there's some code supporting coins specifically that just needs user interface and formatting
• advanced playing card rules: support for dealers, player hands, managed discard piles, and multi-pack decks is planned but unimplemented
• other cards: a lot of the playing cards code is reusable, but need to create lists of face cards, suits, etc. for other card systems (Tarot, etc)
• saving rolls for reuse (macros): planned, but needs lots of work

License

GPL 3.0 - see LICENSE.txt

Yes you're welcome to clone this, modify it, contribute changes, etc. If you're a random passer-by. If you choose to contribute, please write unit tests. Also, sorry for the mess, it's a WIP.