https://github.com/randsum/randsum-ts

Ergonomic Dice Rolling with Strong Typescript Support
https://github.com/randsum/randsum-ts

dice dice-roller dice-rolling dice-rolling-simulator dice-rolls diceware javascript javascript-library npm-package npm-publish npmjs rollup types typescript typescript-library

Last synced: 3 months ago
JSON representation

Ergonomic Dice Rolling with Strong Typescript Support

• Host: GitHub
• URL: https://github.com/randsum/randsum-ts
• Owner: RANDSUM
• License: mit
• Created: 2018-03-07T04:09:21.000Z (about 7 years ago)
• Default Branch: main
• Last Pushed: 2025-01-27T23:00:27.000Z (4 months ago)
• Last Synced: 2025-01-27T23:30:01.791Z (4 months ago)
• Topics: dice, dice-roller, dice-rolling, dice-rolling-simulator, dice-rolls, diceware, javascript, javascript-library, npm-package, npm-publish, npmjs, rollup, types, typescript, typescript-library
• Language: TypeScript
• Homepage:
• Size: 3.37 MB
• Stars: 8
• Watchers: 2
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Security: SECURITY.md

Awesome Lists containing this project

README

        




  





randsum

The world's most flexible, powerful, and easy-to-use JS dice-roller.



  

    

  

  

    

  

  

    

  

  

    

  

  

    

  

  

    

  



## What is this?

It's a dice roller, used for generating rolls that you might use in popular Tabletop Role-playing Games.

```ts

// Let's Roll!

import { roll } from 'randsum'

// Roll a single D20

roll(20)

// Roll 4 D20

roll({ quantity: 4, sides: 20 })

// Roll 4 D6, drop the lowest

roll({ quantity: 4, sides: 6, modifiers: { drop: { lowest: true } } })

// Do the same, but with dice notation

roll('4d6L')

// Roll 4 Fudge dice

import { rollCustomFaces } from 'randsum'

rollCustomFaces({ quantity: 4, faces: ['+', '+', '-', '-', ' ', ' '] })

// Roll a single D20

import { D20 } from 'randsum'

D20.roll()

// Make a new 120 sided die and roll it

import { D } from 'randsum'

const D120 = new D(120)

D120.roll()

//'heads' or 'tails'?

import { CustomFacesD } from 'randsum'

const Coin = new CustomFacesD(['heads', 'tails'])

Coin.roll()

```

Written in 100% Typescript with strong attention paid to return types. You depend on `randsum` to give you what you expect - just not always the roll you want.

## Further Reading

[Getting Started](https://github.com/RANDSUM/randsum-ts/blob/main/GETTING_STARTED.md) - Installation and Documentation for using `randsum`

[Roll Dice Notation](https://github.com/RANDSUM/randsum-ts/blob/main/RANDSUM_DICE_NOTATION.md) - A guide for using [Dice Notation](https://en.wikipedia.org/wiki/Dice_notation) with `randsum`.

[Contributing](https://github.com/RANDSUM/randsum-ts/blob/main/CONTRIBUTING.md) - help make `randsum` better!

[Sophie's Dice Notation](https://sophiehoulden.com/dice/documentation/notation.html) - a great dice notation guide that helped me along the way

[\_why's poignant guide to ruby](https://poignant.guide/) - \_why not?

## Why did you make this?

Sometime around 2012, I decided I wanted to learn to program. I had installed ruby on the best laptop six-hundred dollars could buy, set to make a dice roller as an easy first project.

I spent an easy 30 minutes trying to figure out how to make `rand(n)` return `1...n` instead of `0...(n-1)`.

When I found the answer, I laughed and laughed. I've been chasing that high ever since.