dice

README

Dice

Simple dice rolling for Go.

dice offers three basic methods for rolling dice:

dice.Roll()

,

dice.RollP()

, and

dice.RollD6()

The first function receives a single string parameter which describes the dice roll. For example, send 3d6 to roll three 6-sided dice, 1d20+1 to roll one 20-sided die and add 1 to the result, 1.5d6-1 to roll one and a half 6-sided rolls and subtract one from the result. Half-dice are taken to be a single die of half the normal faces. That is, 1.5d6-1 rolls one 6-sided die, one 3-sided die, and subtracts 1 from the sum of both dice.

The second function receives all the parameters of the dice roll separately (think of the P as "parameters", "pieces", or "parts"). The parameters are: number (the number of dice to roll), faces (how many sides, or faces, each die has), adder (any static quantity to add to the roll's total), and half (a boolean value indicating whether a half-die should be rolled in addition to the dice specified in the number parameter). The equivalent to dice.Roll("1.5d6-1") is dice.RollP(1,6,-1,true).

The third function receives a number and rolls that many 6-sided dice. The last rolled die is considered a "wild" die. A wild die coming up 6 causes an additional die to be rolled. This additional die is also a wild die, which means that if it comes up 6, the process continues, until a non-6 die is rolled.

All three functions return a DiceRoll object:

type DiceRoll struct {
    NumberOfDice int
    DieFaces     int
    Adder        int
    Half         bool
    Rolls        []int
    RawTotal     int
    Total        int
}

DiceRoll objects have a method Description() which returns a description like the one used to roll with dice.Roll().

Additionally, a throwdice runnable is included, which can take any number of dice roll descriptions as command-line arguments and prints the result for each. It will use the D6 system if passed the -d6 flag. It will also read from stdin if no command-line arguments are given, stopping on EOF or "exit" or "quit" (case insensitive). Note that in D6 mode, descriptions are merely numbers, specifically the number of 6-sided dice to roll.

(Yes, it's all very simple and not extremely useful... it's mostly an exercise on Go on my part.)

Documentation

Overview

Package dice provides simple dice-rolling methods allowing rolling of many varieties.

Three methods are exported: Roll(), RollP(), and RollD6(). Roll() receives a textual description of the dice roll (e.g. "3d6+1"), while RollP() receives each parameter separately. RollP() is faster, since it involves no parsing. RollD6() receives the number of 6-sided dice to roll using the D6 system (see README for an explanation).

Index

• Constants
• type DiceRoll
  • func NewSebaoDiceRoll(A, B, C int) *DiceRoll
  • func Roll(description string) (*DiceRoll, error)
  • func RollD6(number int) *DiceRoll
  • func RollP(number, faces, adder int, half bool) *DiceRoll
  • func (dr *DiceRoll) Description() string

Examples

• DiceRoll.Description
• DiceRoll.Description (Text)

Constants

const (
	BUFFER_SIZE = 1024

	USE_DEV_RANDOM = false
)

Types

type DiceRoll

type DiceRoll struct {
	NumberOfDice int
	DieFaces     int
	Adder        int
	Half         bool
	Rolls        []int
	RawTotal     int
	Total        int
}

DiceRoll represents the result of a single dice roll.

NumberOfDice       # how many dice are rolled
DieFaces           # how many sides on each dice
Adder              # static quantity to add to the total of the dice roll
Half               # whether a half-die is rolled (in addition to
                         the number of dice specified in NumberOfDice)
Rolls              # the individual dice rolls
RawTotal           # the total of all the Rolls, the half-die (if any), and Adder
Total              # The maximum of RawTotal and 1

Note that RawTotal can be negative (due to a negative Adder), but Total is never less than 1

func NewSebaoDiceRoll

func NewSebaoDiceRoll(A, B, C int) *DiceRoll

static dice init with ABC

func Roll

func Roll(description string) (*DiceRoll, error)

Roll() generates a new dice roll based on parameters obtained from parsing the passed string.

The expected format is <NumDice>d<DieFaces>[Adder], where NumDice is the number of dice to roll, DieFaces is how many sides per die, and Adder is a static quantity to add to the total. Adder must start with "+" or "-", and NumDice may end with ".5" to indicate a half die.

func RollD6

func RollD6(number int) *DiceRoll

RollD6() generates a new DiceRoll based on the D6 system.

The number of dice specified is rolled, the last die being a "wild" die. "Wild" dice trigger an additional "wild" die to be rolled when coming up "6".

func RollP

func RollP(number, faces, adder int, half bool) *DiceRoll

RollP() generates a new DiceRoll based on the specified parameters.

func (*DiceRoll) Description

func (dr *DiceRoll) Description() string

Description returns a textual description of the dice roll. It uses the same format expected by Roll()

Example

dice := RollP(3, 6, -1, false)
fmt.Println(dice.Description())
dice = RollP(2, 6, 0, true)
fmt.Println(dice.Description())

Output:
3d6-1
2.5d6

Example (Text)

dice, _ := Roll("3d6-2")
fmt.Println(dice.Description())
fmt.Println(dice.NumberOfDice)
fmt.Println(dice.DieFaces)
fmt.Println(dice.Adder)

Output:
3d6-2
3
6
-2