## ringmaster / dicecalc

DiceCalc

Requires

- php: >=5.4

Requires (Dev)

- friendsofphp/php-cs-fixer: @stable
- jakub-onderka/php-parallel-lint: ^0.9.2
- pdepend/pdepend: @stable
- phploc/phploc: @stable
- phpmd/phpmd: @stable
- phpunit/phpunit: @stable
- sebastian/phpcpd: @stable
- sebastian/phpdcd: @stable
- squizlabs/php_codesniffer: @stable

This package is **not** auto-updated.

Last update: 2023-03-19 19:30:34 UTC

# README

## Project status

## How to use

- Create a new Calc class, and pass the dice expression to the constructor::
- $calc = new Calc($expression);
- Output the interpretation of the roll::
- echo $calc->infix();
- Output the result of the roll::
- echo $calc();

## Dice Expressions

The basic expression is to use a "d" followed by the number of sides of the die to roll.

*Examples:*

- d6
- roll a six-sided die
- d20
- roll a twenty-sided die
- d%
- roll a percentile (1-100) die
- df
- roll a fudge (-1, 0, 1) die

To roll multiple of the same sided die, prefix the die type with a multiplier number.

*Examples:*

- 3d6
- roll d6 three times, sum the result
- 2d20
- roll d20 twice, sum the result
- 6df
- roll six fudge dice, sum the result

Basic math operations are possible as expressions.

*Examples:*

- 4+4
- Add 4+4
- 4*5
- Multiply 4*5
- 4+4*5
- Multiply 4*5, then add 4 (order of operations is obeyed)
- (4+4)*5
- Add 4+4, then multiply by 5

Math on sets of numbers.

*Examples:*

- 2*[3,4]
- Multiply 2*3 and 2*4, resulting in a set [6,8]
- [1,2]*[3,4]
- Multiply these sets together, resulting in a nested set [[3,4],[6,8]]

Any combination of dice or constants in an expressions.

*Examples:*

- 2d6+4
- roll 2d6, sum the dice and add 4
- 3d8-5
- roll 3d8, sum the dice and subtract 5
- 2d4+d6
- roll 2d4 and d6, sum all the dice

Evaluate whether a result meets a certain condition or target number.

*Examples:*

- 4+4 > 7
- returns true, because 4+4 is greater than 7
- 5d6 > 5
- returns true, because 5d6 is always greater than 5
- d20+4 > 12
- simulates a d20 system skill value of 4 compared to a target number of 12

Produce a set of rolls by surrounding the roll with brackets and prefixing with a multiplier.

*Examples:*

- 6[3d6]
- produces a set of 6 numbers created by rolling 3d6
- 4[d%]
- produces a set of 4 numbers created by rolling percentile

Roll a custom die by specifying the dice sides in brackets after the "d".

*Examples:*

- d[1,2,2,3,3,4]
- Roll a six-sided die with custom numeric faces
- d[red,green,blue]
- Roll a three-sided die with colored faces

Keep only the dice in an individual roll that meet specific conditions by applying the "k" postfix.

*Examples:*

- 5d6 keep > 4
- Role five six-sided dice, keep only the dice that are greater than 4, sum the kept dice
- 5d6k>4
- same as above
- 6d8 keep < 4
- Roll six eight-sided dice, keep only the dice that are less than 4, sum the kept dice
- 6d8k<4
- same as above

Keep only the dice that are the lowest or highest values rolled.

*Examples:*

- 4d6 highest 3
- Roll 4d6, keep only the highest 3 dice
- 4d6h3
- same as above
- 2s20 lowest 1
- Roll 2d20, keep only the lowest die
- 2d20l1
- same as above

Reroll dice that do not meet certain conditions.

*Examples:*

- 3d6 reroll < 3
- Roll 3d6, reroll any die that is less than 3
- 3d6r<3
- same as above
- 2d% reroll < 40
- Roll 2d%, reroll any die that is less than 40
- 2d%r<40
- same as above

Our stupid way of rolling D&D character stats.

*Examples:*

- 4d6r<3h3
- Roll 4d6, reroll any die that is less than 3, keep the highest 3 dice, sum the kept dice

Produce open-ended dice using the "o" prefix.

*Examples:*

- 4d6o=6
- Roll 4d6. When any die lands on 6, roll that die again and add the result to that die. Sum all die totals.

A stupid example nobody would ever use, I hope:

- 3d6r<4o=6k>6
- Roll 3d6. Reroll any die less than 4. When any die is a 6, reroll and add the new value to the original one. Sum the die totals of only those dice that are greater than 6.

## Future Enhancements

- Better group handling
- Better custom die handling
- Variable replacements (To handle rolls like: d20 + $str_bonus > $target )
- Range violation exceptions (d6k<0)
- Non-text output method