README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

> ... iacta alea est 
> 
> -- <cite>[Gaius Julius Caesar][1]</cite>

[1]:https://en.wikipedia.org/wiki/Alea_iacta_est

# alea

R package for casting dice, including dice for [Dungeons & Dragons](http://dnd.wizards.com/) and special dice like the [Sicherman dice](https://en.wikipedia.org/wiki/Sicherman_dice).

## Overview

`alea` consists of one main function `cast_dice()` with parameters for different situations (see below) and several dice like `d4()`, `d20()`, `sicherman()` which can be used without additional parameters. The interface for the main function is `cast_dice(sides = 1:6, n_tries = 1, sum = FALSE)`.

* `sides`: can either be an integer value (maximum value on a standard dice) or a vector of sides. `6` and `1:6` both result in casting a 6-sided dice.
* `n_tries`: how often the dice should be cast.
* `sum`: whether the result of casting the dice should be summed.

## Installation

You can install alea from github with:

```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("expectopatronum/alea")
```

Load the package:

```{r load-package}
library(alea)
```

## Other packages

Since casting dice is a rather important and easily programmed task, there exist a few other R package. I made a list of the ones I found and tried a few examples [here](misc/package_comparison.md).

## Examples

These examples show the usage of some of the dice in the package.

```{r seed}
set.seed(24) # this seed was randomly chosen by casting a d60
```

```{r ex1}
cast_dice()
```
```{r ex2}
cast_dice(20, 3)
```

```{r ex3}
cast_dice(c(2, 4, 6, 8, 10))
```

```{r ex4}
d20()
```

```{r ex5}
d6(4, TRUE)
```