README
¶
diceroller
Easy to use package for any kind of dice rolling. Can perform complex dice rolling expressions in a single function call.
Supports DnD 5e rolls.
Installation
go get github.com/skyestalimit/diceroller
Usage
Rolling command line style using RollArgs
A RollArg is simply a string representing a dice rolling expression, such as 1d6, 1d8-1, 4d4+4 or 10d10.
- A valid RollArg matches either of these formats:
XdY,XdY+Z,XdY-Z. - It can be a roll attribute such as
crit,adv,half,droplow. - It can be a separator, to signal the start of a new dice rolling expression, such as
roll. - See the
ParseRollArgsfunction documentation for more details.
To perform the dice rolling expression 1d6:
PerformRollArgsAndSum("1d6")
To perform the dice rolling expression 2d6+4 + 1d8:
PerformRollArgsAndSum("2d6+4", "1d8")
You can also call the function PerformRollArgs instead to receive more detailed results, see the Viewing Results section.
Rolling multiple dice rolling expressions using RollArgs
You can build multiple dice rolling expressions, which can be summed separately, using RollArgs, roll attributes or separators.
Performing these RollArgs adv, d20, roll, 1d4, half, 2d6+1, roll, 2d6 at once would result in the rolling expressions adv d20, 1d4, half 2d6+1 and 2d6 being rolled separately, with their own roll attributes applied and separate sums. Of course, they all can be summed together as well.
Rolling library style using DiceRolls
A DiceRoll is not necessarily a single dice roll, but a single dice rolling expression, such as 2d6.
In the end, all the rolls made with this package are made using DiceRolls internally. You can build your own or get them from the RollArg parser.
Building a DiceRoll
To build a DiceRoll, use the constructor to validate your values. For the dice rolling expression 2d6+1:
NewDiceRoll(2, 6, 1, true)
You can set its attributes later or use NewDiceRollWithAttribs instead.
Building DiceRolls using the RollArg parser
Refer to the ParseRollArgs documentation for more details about RollArgs.
You can use the parser to build a DiceRoll from one or multiple RollArgs. They will be return grouped in one or many rollingExpression.
To build a DiceRoll for the dice rolling expression 2d6+1:
ParseRollArgs("2d6+1")
Rolling DiceRolls
For simple dice rolling expressions, such as 1d6, 1d8-1, 4d4+4 or 10d10, you only need a single DiceRoll.
For more complex dice rolling expressions, such as 2d6+4 + 1d8, you need multiple DiceRolls and sum them.
diceRoll2d6plus1, _ := NewDiceRoll(2, 6, 4, true)
diceRoll1d8, _ := NewDiceRoll(1, 8, 0, true)
PerformRollsAndSum(*diceRoll2d6plus1, *diceRoll1d8)
You can also call the function PerformRolls instead to receive a more detailed results, see the Viewing Results section.
Viewing Results
For more details about the results, DiceRollResult or RollingExpressionResult slices can be returned instead of a sum. An error slice is also returned containing an error for each invalid DiceRolls or RollArgs. Refer to each struct documentation for more details.
You can sum the results of a DiceRollResult array by passing it to:
func DiceRollResultsSum(results []DiceRollResult) (sum int)
You can sum the results of a RollingExpressionResult array by passing it to:
func RollingExpressionResultSum(results ...RollingExpressionResult) (sum int)
Documentation
¶
Overview ¶
Package diceroller generates either a sum or DiceRollResults out of RollArgs or DiceRolls. It's just that simple so get rolling!
Index ¶
- func DiceRollResultsSum(results ...DiceRollResult) (sum int)
- func ParseRollArgs(rollArgs ...string) (rollingExpressions []rollingExpression, errors []error)
- func PerformRollArgsAndSum(rollArgs ...string) int
- func PerformRollsAndSum(diceRolls ...DiceRoll) int
- func RollingExpressionResultSum(results ...RollingExpressionResult) (sum int)
- type DiceRoll
- type DiceRollResult
- type RollingExpressionResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DiceRollResultsSum ¶
func DiceRollResultsSum(results ...DiceRollResult) (sum int)
Returns the total sum of a DiceRollResult array.
func ParseRollArgs ¶
Parses a RollArg array. Returns a DiceRoll array for valid RollArgs, an error array for invalid ones.
A valid RollArg matches either the DiceRoll format or a rollAttribute string.
DiceRoll format: [X]dY[+|-]Z. In other words XdY or dY followed by + or - Z. Valid DiceRoll examples: "5d6", "d20", "4d4+1", "10d10", "1d6-1", "1D8".
RollArgs will be converted into DiceRolls and grouped together in rolling expressions. A new rolling expression starts when a rollAttribute is parsed after a sequence of DiceRolls.
For example:
- 5d6 1d6 10d10 would return one rolling expression containing all three RollArgs as DiceRolls.
- adv d20+5 half spell 8d8 would return two rolling expressions: "adv 1d20+5" and "half spell 8d8".
- 5d6 roll 4d6 roll 3d6 would return three rolling expressions: "5d6", "4d6" and "3d6".
rollAttribute string list:
- roll, hit, dmg : separators, starts a new rolling expressions
DnD rollAttribute string list:
- crit: Critical, doubles all dice ammount
- spell: Spell, DiceRollResults.String() prints the sum and the sum halved for saves
- half: Halves the sums, for resistances and such
- adv: Advantage, rolls each dice twice and drops the lowest
- dis: Disadvantage, rolls each dice twice and drops the highest
- drophigh: Drop High, drops the highest result of a DiceRoll
- droplow: Drop Low, drops the lowest result of a DiceRoll
func PerformRollArgsAndSum ¶ added in v0.2.1
Straightforward rolling using RollArgs. Returns the sum, invalid RollArgs are worth 0.
func PerformRollsAndSum ¶ added in v0.1.2
Performs an array of DiceRoll. Returns the sum, invalid DiceRolls are worth 0.
func RollingExpressionResultSum ¶ added in v1.1.0
func RollingExpressionResultSum(results ...RollingExpressionResult) (sum int)
Sums multiple RollingExpressionResult.
Types ¶
type DiceRoll ¶
type DiceRoll struct {
DiceAmmount int // Ammount of dice to be rolled
DiceSize int // Size, or number of faces, of the dice to be rolled
Modifier int // Value to be applied to the sum of rolled dices
Plus bool // Determines if the result of the roll is to be added or substracted
Attribs attributes // Contains rollAttributes affecting the rolls
}
A DiceRoll represents a dice rolling expression, such as 1d6 or 2d8+1.
func NewDiceRoll ¶
DiceRoll constructor, validates values.
func NewDiceRollWithAttribs ¶ added in v1.1.0
func NewDiceRollWithAttribs(diceAmmount int, diceSize int, modifier int, plus bool, attribs attributes) (*DiceRoll, error)
DiceRoll constructor with rollAttributes, validates values.
type DiceRollResult ¶
type DiceRollResult struct {
Dice []int // Individual dice roll result
Sum int // Sum of Dice
AdvDisDropped []int // Dropped advantage/disadvantage dice
HighDropped []int // Dropped high dice
LowDropped []int // Dropped low dice
// contains filtered or unexported fields
}
A DiceRollResult contains the results of performing a DiceRoll
func PerformRolls ¶
func PerformRolls(diceRolls ...DiceRoll) (results []DiceRollResult, diceErrs []error)
Performs an array of DiceRoll. Returns a DiceRollResult array for valid DiceRolls and an error array for invalid ones.
func (DiceRollResult) String ¶
func (result DiceRollResult) String() string
Human readable DiceRollResult string.
type RollingExpressionResult ¶ added in v1.1.0
type RollingExpressionResult struct {
Results []DiceRollResult
Sum int
}
Results of performing a rollingExpression.
func PerformRollArgs ¶ added in v0.2.1
func PerformRollArgs(rollArgs ...string) ([]RollingExpressionResult, []error)
Performs an array of RollArgs. Returns a DiceRollResult array for valid RollArgs and an error array for invalid ones.
func (RollingExpressionResult) String ¶ added in v1.1.0
func (rollExpr RollingExpressionResult) String() string
Formatted result output.
Source Files