diceprob

README

diceprob

Go package for calculating combinations and probabilities for complex dice expressions.

Purpose

diceprob is a personal combinatorics and game design hobby turned into Golang package.

For decades I've been fascinated with game design and specifically dice as the randomizer element of those designs.

I spent years researching combinatorics and probabilities of dice as a personal hobby. Maybe that's weird. This package is based on prior work I've done on a Perl module Games::Dice::Probability. I'm updating it to be Golang and useful to me now.

The Math

There's a lot of math behind the scenes. I discuss it on my website.

Install

Install with:

go get github.com/jason-dour/diceprob

Dice Expression Syntax

• N
  • The number of dice in a single dice roll.
  • Can be any integer number.
• S
  • The number of sides on the dice in a single dice roll.
  • Can be any integer number, as well as F or f for Fudge/FATE dice.
• NdS
  • Roll N dice, each with same number of sides S.
  • Examples:
    • 1d6
    • 3d6
    • 1d4
    • 1d20
    • 3df
• midS
  • Roll 3 dice, each with same number of sides S, and return the middle value of the three values.
  • Examples:
    • mid20
    • mid10
    • midf
• [+ | - | * | /]
  • Math operators; will add/subtract/multiply/divide the left and right terms.
  • Example:
    • 2d6+1d4
• [0-9+]
  • Modifier; a fixed number.
  • Example:
    • 2d6+1
    • 3d6-4
• ( expression )
  • Grouping; you may use parentheses to enclose sub-expressions, to ensure proper calculation.
  • Example:
    • (1d6+2)*3

Usage

Everything is driven through the DiceProb type, and its methods.

Create a new instance by providing your dice expression:

d, err := diceprob.New("3d6")
if err != nil {
  panic(err)
}

Creating the instance will automatically parse the expression into an object tree.

repr.Println(d.ParsedExpression())

&diceprob.Expression{
  Left: &diceprob.Term{
    Left: &diceprob.Atom{
      RollExpr: &diceprob.DiceRoll("3d6"),
    },
  },
}

From there you can calculate the outcomes, distribution, probabilities, et al.

d.Calculate()

And call them for display or computation.

fmt.Printf("Expression: %s\n", d.InputExpression())
fmt.Printf("Bounds: %v..%v\n", d.Min(), d.Max())
fmt.Printf("Permutations: %v\n", d.Permutations())
fmt.Printf("Outcome Set: %s\n", strings.Join(*d.OutcomesString(), ","))
fmt.Printf("Distribution:\n  Outcome | Frequency | Probability\n")

for _, i := range *d.Outcomes() {
  fmt.Printf("  %-8d  %-8d    %.6g\n", i, (*d.Distribution())[i], (*d.Probabilities())[i])
}

Or you can just "roll" the dice expression and retrieve a value.

d.Roll()

Notes

• Memoize for speed?
  • "golang.org/x/tools/internal/memoize"

Documentation

Overview

Package diceprob - Calculating outcome distributions and probabilities for complicated dice expressions.

Index

• type Atom
  • func (a *Atom) Roll() int64
• type DiceProb
  • func New(s string) (*DiceProb, error)
  • func (d *DiceProb) Bounds() *[]int64
  • func (d *DiceProb) Calculate()
  • func (d *DiceProb) Distribution() *map[int64]int64
  • func (d *DiceProb) Expression() string
  • func (d *DiceProb) Max() int64
  • func (d *DiceProb) Min() int64
  • func (d *DiceProb) Outcomes() *[]int64
  • func (d *DiceProb) OutcomesString() *[]string
  • func (d *DiceProb) ParsedExpression() *Expression
  • func (d *DiceProb) Permutations() int64
  • func (d *DiceProb) Probabilities() *map[int64]float64
  • func (d *DiceProb) Roll() int64
• type DiceRoll
  • func (s *DiceRoll) Roll() int64
• type Expression
  • func (e *Expression) Distribution() *map[int64]int64
  • func (e *Expression) Roll() int64
  • func (e *Expression) String() string
• type OpAtom
• type OpTerm
• type Operator
  • func (o *Operator) Capture(s []string) error
  • func (o Operator) Roll(left, right int64) int64
• type Term
  • func (t *Term) Roll() int64

Types

type Atom

type Atom struct {
	Modifier      *int64      `parser:"@Modifier"`
	RollExpr      *DiceRoll   `parser:"| @DiceRoll"`
	SubExpression *Expression `parser:"| '(' @@ ')'"`
}

Atom - Smallest unit of an expression.

func (*Atom) Roll

func (a *Atom) Roll() int64

Roll - Roll a random value for the Atom; part of the recursive roll functions.

type DiceProb

type DiceProb struct {
	// contains filtered or unexported fields
}

DiceProb - Base data structure.

func New

func New(s string) (*DiceProb, error)

New - Create a new DiceProb instance.

func (*DiceProb) Bounds

func (d *DiceProb) Bounds() *[]int64

Bounds - Range min to max of outcome values for the expression's distribution.

func (*DiceProb) Calculate

func (d *DiceProb) Calculate()

Calculate - Calculate the Distribution and Probabilities for the ParsedExpression.

func (*DiceProb) Distribution

func (d *DiceProb) Distribution() *map[int64]int64

Distribution - Distribution of summed outcomes and their frequency.

func (*DiceProb) Expression

func (d *DiceProb) Expression() string

Expression - Return the original expression for the instance.

func (*DiceProb) Max

func (d *DiceProb) Max() int64

Max - Maximum outcome value for the expression's distribution.

func (*DiceProb) Min

func (d *DiceProb) Min() int64

Min - Minimum outcome value for the expression's distribution.

func (*DiceProb) Outcomes

func (d *DiceProb) Outcomes() *[]int64

Outcomes - Return list of outcomes for the expression.

func (*DiceProb) OutcomesString

func (d *DiceProb) OutcomesString() *[]string

OutcomesString - Return list of outcomes for the expression as strings.

func (*DiceProb) ParsedExpression

func (d *DiceProb) ParsedExpression() *Expression

ParsedExpression - Return the parsed expression for the instance.

func (*DiceProb) Permutations

func (d *DiceProb) Permutations() int64

Permutations - Total outcomes for the expression.

func (*DiceProb) Probabilities

func (d *DiceProb) Probabilities() *map[int64]float64

Probabilities - Probability of each outcome.

func (*DiceProb) Roll

func (d *DiceProb) Roll() int64

Roll - Perform a "roll" of the expression and return the outcome.

type DiceRoll

type DiceRoll string

DiceRoll - String representing a dice roll atomic expression.

func (*DiceRoll) Roll

func (s *DiceRoll) Roll() int64

Roll - Roll a random value for the DiceRoll; deepest of the recursive roll functions.

type Expression

type Expression struct {
	Left  *Term     `parser:"@@"`
	Right []*OpTerm `parser:"@@*"`
}

Expression - Top level parsing unit.

func (*Expression) Distribution

func (e *Expression) Distribution() *map[int64]int64

Distribution - Determine the outcomes' distribution for the Expression; top-level of the recursive distribution functions.

func (*Expression) Roll

func (e *Expression) Roll() int64

Roll - Roll a random value for the Expression; top-level of the recursive roll functions.

func (*Expression) String

func (e *Expression) String() string

String - Output the dice Expression as a string; top level of recursive output functions.

type OpAtom

type OpAtom struct {
	Operator Operator `parser:"@('*' | '/')"`
	Atom     *Atom    `parser:"@@"`
}

OpAtom - Expression Operator and Atom.

type OpTerm

type OpTerm struct {
	Operator Operator `parser:"@('+' | '-')"`
	Term     *Term    `parser:"@@"`
}

OpTerm - Expression Operator and Term.

type Operator

type Operator int

Operator type

const (
	OpMul Operator = iota
	OpDiv
	OpAdd
	OpSub
)

Operator constants

func (*Operator) Capture

func (o *Operator) Capture(s []string) error

Capture - Capture the costants while parsing.

func (Operator) Roll

func (o Operator) Roll(left, right int64) int64

Roll - Roll a random values around the Operator; part of the recursive roll functions.

type Term

type Term struct {
	Left  *Atom     `parser:"@@"`
	Right []*OpAtom `parser:"@@*"`
}

Term - Expression Term

func (*Term) Roll

func (t *Term) Roll() int64

Roll - Roll a random value for the Term; part of the recursive roll functions.