Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jifish/ezdice
A really simple PHP library for parsing dice notation and rolling.
https://github.com/jifish/ezdice
dice dice-notation dice-roller die library php php7 php8
Last synced: 11 days ago
JSON representation
A really simple PHP library for parsing dice notation and rolling.
- Host: GitHub
- URL: https://github.com/jifish/ezdice
- Owner: JiFish
- License: mit
- Created: 2021-11-11T00:12:06.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2022-09-25T13:48:04.000Z (about 2 years ago)
- Last Synced: 2024-10-11T18:16:11.575Z (28 days ago)
- Topics: dice, dice-notation, dice-roller, die, library, php, php7, php8
- Language: PHP
- Homepage:
- Size: 17.6 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# EZDice
A really simple PHP library for parsing dice notation and rolling.
Works in PHP 7+.
## Why use EZDice?
EZDice was written because I wasn't happy with similar libraries. EZDice has the following advantages over other offerings:
- No Bloat. EZDice is one simple class with no dependences.
- Provides each die roll, not just the total.
- Forgiving parser designed for humans, not machines.
- Option to easily replace the RNG.
- MIT licenced, ensuring you can use it freely in any project.
## Usage
Here's a basic example
```
require 'ezdice.php';
$ezd = new ezdice\EZDice();
echo($ezd->roll('1d20+2d4'));
echo(' Rolls:');
foreach($ezd->getDiceStates() as $die) {
echo(' ['.$die['value'].'] ');
}
```
Example Output:
```
23 Rolls: [17] [4] [2]
```
## Installing with Composer
You don't have to use composer to include EZDice in your project, but you can:
`composer require jifish/ezdice`
## Methods
### roll($diceStr)
Parse **$diceStr** as dice notation, then roll those dice. Returns *(int)* total of all rolls and modifiers, or *false* if none were found.
The parser is very forgiving, ignoring whitespace and anything else it doesn't recognise. It is also case-insensitive. Dice notation is briefly documented below.
### getTotal()
Returns *(int)* that is the total of the last roll.
### getDiceStates()
Returns an *(array)* of dice that describes the state of the dice after the last roll. Each die is also an *(array)* with the following keys:
- **sides** - *(int)* the number of sides the die has
- **value** - *(int)* the value the die rolled
- **dropped** - *(bool)* *true* if this dice was dropped, otherwise *false*. Dropped dice aren't counted towards the total.
### getModifier()
Returns a *(string)* representing the total of all modifiers in the last roll. If there were no modifiers, or they cancelled out, an empty string is returned. You can cast this to an *(int)* if needed.
e.g. if you rolled `1d8+10+1d4-2` this method would return `+8`.
### strContainsDice($diceStr)
Parse **$diceStr** and returns true if it contains at least one dice roll, otherwise returns false. Useful for verifying user input. Modifiers without dice don't count.
## Dice Notation
- Dice notation is in the form (number of dice)**d**(dice sides). e.g. `2d10`.
- Additional dice can be chained with **+** and **-** operators. e.g. `2d10+1d6`.
- Modifiers can also be specified. e.g. `2d10-5`
- d% can be used as a shorthand for a percentile dice. `1d%` and `1d100` are equivalent.
- Append a roll with -L to drop the lowest dice in that group, or -H to drop the highest. Dropped dice are excluded from the total. e.g. `2d20-L` will roll 2 twenty sided dice and drop the lowest. You can also specify a number of dice to drop e.g. `6d6-H3` will drop the highest 3 rolls.
- No notation is currently provided for fudge dice. You can use `1d3-2` instead.
- Whitespace, and anything else not recognised as a dice or a modifier, is treated like a **+** operator. e.g. `foo10 1d4bar1d4 5` is equivalent to `5+1d4+1d4+10`, or simply `2d4+15`.
## Replacing the random number generator
By default *mt_rand()* is used as the RNG, which should be fine for most applications. If you want to change this, for example to normalise dice rolls, you can extend the class and override the method **getRandomNumber($max)**
```
class WeightedDice extends ezdice\EZDice {
protected function getRandomNumber($max) {
if (mt_rand(0,1)) return $max;
return mt_rand(1,$max);
}
}
```
## Legalese
Released under the MIT licence. Copyright (c) 2021 Joseph Fowler.