dice

func (*Dice) Description ¶

func (d *Dice) Description() (desc string)

Description produces a human-readable description of the die roll specification represented by the Dice object.

func (*Dice) MaxRoll ¶

func (d *Dice) MaxRoll() (int, error)

MaxRoll is an alternative to Roll where instead of rolling the dice, it just assumes they all came up at their maximum possible values. This does NOT set up for subsequent critical rolls.

func (*Dice) MaxRollToConfirm ¶

func (d *Dice) MaxRollToConfirm(bonus int) (int, error)

MaxRollToConfirm is the analog to RollToConfirm but just assumes all dice come up with their maximum values rather than rolling anything.

func (*Dice) Roll ¶

func (d *Dice) Roll() (int, error)

Roll rolls the dice which this Dice instance represents. The result is returned as an integer value. Each time this is called, the dice are rerolled to get a new result. The Dice value’s internal state reflects the last call to this method.

func (*Dice) RollToConfirm ¶

func (d *Dice) RollToConfirm(confirm bool, threat int, bonus int) (int, error)

RollToConfirm rolls the dice specified in the Dice value, with support for making critical confirmation rolls.

If confirm is true, we're rolling to confirm a critical threat. In this case, the previous-rolled value is checked against the provided threat value. If that previous roll is less than the threat value, nothing further is done, and 0 is returned.

If the previous roll was ≥ threat, then we make another roll, adding the provided bonus modifier to that roll. This roll's total is returned, and becomes the new most-recent roll for this Dice value.

If threat is less than or equal to zero, the default threat of a natural maximum roll (e.g., 20 on a d20, or 10 on a d10) is used.

Calling d.RollToConfirm(false, 0, 0) is equivalent to calling d.Roll(). Confirm a critical roll by rolling again against the normal to-hit target.

func (*Dice) StructuredDescribeRoll ¶

func (d *Dice) StructuredDescribeRoll(options ...func(*sdrOptions)) ([]StructuredDescription, error)

StructuredDescribeRoll produces a detailed structured description of the result of rolling the Dice, in a way that a caller can format as they see fit.

If you wish to interpret the die roll in light of a rule which allows for a natural 1 to indicate automatic failure and a natural maximum die face (e.g., natural 20 on a d20) to indicate automatic success, then add a WithAutoSF option function call to the end of the argument list.

If this die roll included a bonus added to it for some reason (e.g., a confirmation bonus on dice rolled to confirm a critical threat), then add a WithRollBonus function call to the end of the argument list.

func (*DieRoller) DoRoll ¶

func (d *DieRoller) DoRoll(spec string) (string, []StructuredResult, error)

DoRoll rolls dice as described by the specification string. If this string is empty, it re-rolls the previously-used specification. Initially, "1d20" is assumed.

Returns the user-specified die-roll label (if any), the result of the roll, and an error if one occurred.

In this more comprehensive interface, the spec string is a string of the form

[<title>=] <expression> [|<options>...]

or

[<title>=] <chance>% [<success>[/<fail>]] [|<options>...]

where []s indicate optional parameters, the given words in angle brackets (<title>, etc) represent values to be placed into the string, and the other characters are to be taken literally.

The <title> (which, if given, is separated from the rest of the spec with an equals sign (“=”)) is optional and will be included as a comment in the result list to indicate what the purpose of the die roll was for.

Note that this module does not interpret the <title> value further, but by convention two special characters are significant to some clients:

‖ (U+2016) separates multiple titles in the <title> string
≡ (U+2261) separates the title text on the left with a color on the right.

This means that a <title> string of "monster≡blue‖damage≡red" will display a title for the die roll as two separate title values, "monster" in blue and "damage" in red.

<expression> can be anything that can be given as the description string to the New constructor (q.v.). At the end of the spec string there may be zero or more options, each beginning with a vertical bar (“|”).

These options may be any of the following:

| min <n>

The result will be at least <n>.

| max <n>

The result will be no more than <n>.

| c[<t>[±<b>]]

This indicates that the roll may need a critical confirmation roll to follow it. This will appear as an additional result in the list of results returned from the DoRoll and DoRollOnce methods. If the <t> parameter is given, a natural roll equal to or greater than <t> is assumed to be a critical threat. If a plus or minus sign followed by a number <b> is appended to the option, then this value is added to the confirmation die roll as a confirmation bonus. (The notation "±" here means either a "-" or "+" may appear at that position in the string.)

| dc <n>

This is a roll against a known difficulty class <n>. If the result is at least <n>, the roll is "successful".

| sf [<success>[/<fail>]]

Auto-success/fail: the roll, which must involve only a single die, will be considered successful if it's a natural maximum value (e.g., 20 on a d20 before modifiers are applied), or a failure if a natural 1 was rolled. Optionally, messages to report to the user to indicate what success and failure mean may be specified. Suitable defaults will be used or derived if one or both of those strings is not given.

| until <n>

Continue making die rolls, adding their results to the returned output, until a result of at least <n> is obtained.

| repeat <n>

Make <n> die rolls, reporting their results.

| maximized

Assume all dice roll at their maximum possible values. For example, the spec "3d6 | maximized" will always return the result 18, as if all three dice rolled sixes.

To prevent getting caught in an infinite loop, a maximum of 100 rolls will be made regardless of repeat and until options.

Anywhere in the string you may introduce a combination specifier in curly braces as “{<a>/<b>/<c>/...}”. This will repeat the overall die roll expression once for each of the values <a>, <b>, <c>, etc., substituting each in turn for the braced list. If multiple specifiers appear, they’ll all repeat so you get the Cartesian product of all the sets of values. This allows, for example, multiple attack rolls in a single click. For example, “Attack=d20+{17/12/7}” would roll three attack rolls: d20+17, d20+12, and d20+7.

In the second form for the spec string, <chance> gives the percentage chance of something occurring, causing percentile dice to be rolled. The result will be a the integer value 1 if the d100 roll was less than or equal to <chance>, or 0 otherwise. By default, the result is reported in the detailed description as “success” or “fail”. If a success label is given in the die‐roll string, that is reported in case of a successful roll, and “did not <success>” otherwise. If an explicit fail label is also given, that is used for unsuccessful rolls instead. As a special case, if <success> is “miss” then <fail> is assumed to be “hit” and vice versa.

For percentile rolls, only the until, repeat, and maximized global options may be used. Permutations (“{...}”) are also disallowed with percentile rolls.

This method returns values title, resultSet, and error representing the results of rolling the dice. The title is the title specified in the dice string, or an empty string if one was not given. The resultSet is a slice of StructuredResult structures, one for each roll of the dice that was performed.

Example die-roll specifications:

"d20"             Roll 1d20.
"3d6"             Roll 3d6 (3 six-sided dice, adding their values).
"15d6+15"         Roll 15d6, add 15 to their sum.
"1d10+5*10"       Roll 1d10, add 5, then multiply the result by 10.
"1/2 d6"          Roll 1d6, divide result by 2 (truncating toward zero).
"2d10+3d6+12"     Roll 2d10, 3d6, add their results and add 12 to the sum.
"d20+15|c"        Roll d20+15, automatically rolling to confirm on a natural 20.
"d20+15|c19+2"    Roll d20+15, rolling to confirm on natural 19 or 20 with +2 bonus.
"d%"              Roll percentile dice, giving result 1-100.
"40%"             Roll percentile dice, giving result 1 with 40% probability.
"d20+12|max20"    Roll d20+12 but any result > 20 is capped at 20.
"d20 best of 2"   Roll d20 twice, discarding the worse result.
"d20+4|dc 10"     Roll d20+4, signalling success if the result is 10 or greater.
"3d6 fire+1d4 acid+2 bonus"
                  Roll 3d6+1d4+2. In the structured results, it will show the values
                  rolled for the 3d6 fire, 1d4 acid, and 2 bonus individually.
"40% hit"         Reports success ("hit") with a 40% probability; otherwise reports
                  failure ("miss").
"13% red/blue"    Reports success ("red") with a 13% probability; otherwise reports
                  failure ("blue").
"2d10+3|until 19" Repeatedly rolls 2d10+3, adding each result to the set of die rolls
                  returned, until a roll totals at least 19.

func (*DieRoller) DoRollOnce ¶

func (d *DieRoller) DoRollOnce(spec string) (string, StructuredResult, error)

DoRollOnce is just like the DoRoll method but adds the constraint that there may only be one result returned, in the same way the RollOnce function differs from the Roll() function.

func (*DieRoller) ExplainSecretRoll ¶ added in v5.2.0

func (d *DieRoller) ExplainSecretRoll(spec, notice string) (string, StructuredResult, error)

ExplainSecretRoll takes a dieroll spec as DoRoll does, along with a string explaining why the roll is secret. It returns the same result data as DoRoll, including a broken-out description of the dieroll spec, except that no actual die roll is made and no results are reported.

The ResultSuppressed field of the returned StructuredResult value is set to true to indicate that there is no actual result contained in the returned data.

This is used to send a "receipt" back to the requester of a die roll that their request for the roll was sent on to another party (typically the GM) who will be the only person to see the actual results (which must be obtained by a separate roll to the DoRoll method).

func (*DieRoller) IsNatural1 ¶

func (d *DieRoller) IsNatural1() (result bool)

IsNatural1 returns true if the DieRoller has been rolled already, and contains but a single die in its specification, and that die was rolled as a natural 1.

It returns false if that was not true, even if that was for reasons that it could not possibly be true (no die was rolled, the die-roll spec contained multiple dice, etc.)

func (*DieRoller) IsNaturalMax ¶

func (d *DieRoller) IsNaturalMax() (result bool)

IsNaturalMax returns true if the DieRoller has been rolled already, and contains but a single die in its specification, and that die was rolled to the maximum possible value (i.e., a 20 on a d20).

It returns false if that was not true, even if that was for reasons that it could not possibly be true (no die was rolled, the die-roll spec contained multiple dice, etc.)

func (*DieRoller) RandFloat64 ¶

func (d *DieRoller) RandFloat64() float64

RandFloat64 generates a pseudorandom number in the range [0.0, 1.0) using the same random number generator as used for die rolls. This means that it affects the outcome of subsequent die rolls just as other die rolls do.

func (*DieRoller) RandIntn ¶

func (d *DieRoller) RandIntn(n int) int

RandIntn generates a pseudorandom integer in the range [0, n) using the same random number generator as used for die rolls. This means that it affects the outcome of subsequent die rolls just as other die rolls do.

func (StructuredDescriptionSet) Text ¶

func (sr StructuredDescriptionSet) Text() (string, error)

Text produces a simple plain-text rendering of the information in a StructuredDescription slice. This is useful for showing the full details of a die roll to a human, or a log file, etc., if fancier formatting isn't needed.