johnathanbostrom/elm-dice - version: 2.0.0

for more information visit the package's GitHub page

Package contains the following modules:

elm-dice

A Dice Roller Package based on elm/random that allows you to build customizable dice rolling functions in a readable way.

Rolling Dice

-- generator to roll 4 six sided dice, dropping the lowest
statGenerator =
    roll 4 D6
        |> dropLowest

Defining Dice

Represents a Die or pool of dice. Most common dice are built in, but you can also create your own.

-- a six sided die
D6

--a 5 sided die
DX 5

CustomDie

Represents a Die with the provided faces.

-- a die with even faces 2-8
evenDie =
    CustomDie "evens" [ 2, 4, 6, 8 ]

-- a die with more twos
moreTwos =
    CustomDie "evens" [ 2, 2, 2, 2, 2, 2, 2, 4, 6, 8 ]

WeightedDie

Respresents a Die with weighted values.

-- esentially the same as moreTwos above
moreTwos =
    CustomDie "evens"
        [ (70, 2)
        , (10, 4)
        , (10, 6)
        , (10, 8)
        ]

-- moreTwos could also be written as follows
moreTwos =
    CustomDie "evens"
        [ (7, 2)
        , (1, 4)
        , (1, 6)
        , (1, 8)
        ]

DicePool

Typically represents a dice pool composed with 'roll' and other helper functions.

-- a dice pool of 4 six sided dice
statDice =
    roll 4 D6
        |> dropLowest
        |> DicePool "4D6"

-- this can now be used with roll
roll 2 statDice

-- you can also use any Random.Generator RollResult with DicePool
threeToTwelveDie =
    Random.int 3 12
        |> toRollResultGenerator "3to12"
        |> DicePool "3to12"

Example App

type alias Model =
{ rolls : List RollResult
}

type Msg
    = RollDice
    | GotRollResults (List RollResult)

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        RollDice ->
            ( model
            , rollStats
            )

        GotRollResults newRolls ->
            ( { model | rolls = newRolls }
            , Cmd.none
            )

rollstats : Cmd Msg
rollstats =
    roll 4 D6
        |> dropLowest
        |> Random.generate GotRollResults

Example Output

1D6

-- generator
roll 1 D6

-- one possible output
{ description = "1D6"
, value = 4
, children = Empty
}

dropLowest

the dropLowest helper function computes the value of the Roll result without the lowest value of the child rolls.

--generator roll 4 D6 |> dropLowest

-- one possible output { description = "4D6" , value = 12 , children = RollResults [ { description = "D6", value = 6, children = Empty } , { description = "D6", value = 4, children = Empty } , { description = "D6", value = 2, children = Empty } , { description = "D6", value = 1, children = Empty } ] }

Exploding dice

"explodes" a RollResult. An exploding die will keep rolling as long as it satisfies the predicate. For instance, if you roll a 10 on the following D10, you will roll again and add the rolls together. If your reroll is another D10, you repeat this process.

-- define a ten sided die that "explodes" on a 10.
explodingD10 =
    roll 1 D10
        |> ExplodeIf (\r -> r == 10)
        |> DicePool "Exploding D10"

-- generator for rolling 3 exploding dice
    roll 3 explodingD10

-- one possible output
{ description = "3 Exploding D10"
, value = 42
, children =
    RollResults
        [ { description = "Exploding D10"
          , value = 27
          , children =
                [ { description = "D10", value = 7, children = Empty }
                , { description = "D10", value = 10, children = Empty }
                , { description = "D10", value = 10, children = Empty }
                ]
          }
        , { description = "Exploding D10"
          , value = 3
          , children =
            [ { description = "D10", value = 3, children = Empty } ]
          }
        , { description = "Exploding D10"
          , value = 12
          , children =
                [ { description = "D10", value = 2, children = Empty }
                , { description = "D10", value = 10, children = Empty }
                ]
          }
        ]
}

Count Successes

Count the number of dice that satisfy the predicate.

-- generator
roll 4 D10
    |> countSuccessesIf (\r -> r.value > 7)

-- one possible output

{ description = "4D10"
, value = 2
, children =
    RollResults
        [ { description = "D10", value = 8, children = Empty }
        , { description = "D10", value = 9, children = Empty }
        , { description = "D10", value = 2, children = Empty }
        , { description = "D10", value = 1, children = Empty }
        ]
}