README

• 骰子
• DiceShaker
• 示例
• 贡献

骰子

单个骰子可以被创建并多次投掷。

创建骰子

通过将单个数字传递给构造函数创建标准数字 Dice

<?php

use daverichards00\DiceRoller\Dice;

// Create a d6 (Number range 1 - 6)
$d6 = new Dice(6);

// Create a d100 (Number range 1 - 100)
$d100 = new Dice(100);

// Or use a predefined constant
$d10 = new Dice(Dice::D10);

通过传递数字或字符串数组创建具有自定义面的 Dice

<?php

use daverichards00\DiceRoller\Dice;

// Create a Dice with custom selection of numbers:
$evenDice = new Dice([2, 2, 4, 4, 6, 6]);

// Create a Dice of strings, such as colours:
$colourDice = new Dice(['Red', 'Blue', 'Green']);

// ...or shapes:
$shapeDice = new Dice(['Triangle', 'Square', 'Circle', 'Cross']);

投掷

您可以投掷一个 Dice 并获取投掷的值

<?php

use daverichards00\DiceRoller\Dice;

$dice = new Dice(6);

// Separate calls:
$dice->roll();
$firstValue = $dice->getValue();

// ...or chained calls:
$secondValue = $dice->roll()->getValue();

自定义投掷器

您可以通过注入 daverichards00\DiceRoller\Roller\RollerInterface 的实现来自定义随机数生成。

有两个预设的投掷器

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\Roller;

// Create a d6 with the QuickRoller
// NOTE: QuickRoller is the default roller when one isn't specified
$dice = new Dice(6, new Roller\QuickRoller);

// ...is the same as:
$dice = new Dice(6);

// Create a d20 with the StrongRoller
// The StrongRoller could be used for cryptographic purposes
$dice = new Dice(20, new Roller\StrongRoller);

创建您自己的投掷器

您可以通过实现 RollerInterface 创建自己的投掷器。这要求您实现方法 public function roll(int $min, int $max): int，该方法接受两个整数，一个最小值和一个最大值，并返回一个在范围内（包含）的随机整数。以下是一个示例

<?php

use daverichards00\DiceRoller\Roller\RollerInterface;

class MyCustomRoller implements RollerInterface
{
    /**
     * @param int $min
     * @param int $max
     * @return int
     */
    public function roll(int $min, int $max): int
    {
        // NOTE: This is how the QuickRoller is implemented.
        return mt_rand($min, $max);
    }
}

// ...

// You can then inject this roller into the Dice object when instantiating:

use daverichards00\DiceRoller\Dice;

$dice = new Dice(6, new MyCustomRoller);

$dice->roll(); // This will now be using MyCustomRoller->roll() to select a random value.

历史

您可以看到投掷的历史

<?php

use daverichards00\DiceRoller\Dice;

$dice = new Dice(6);

// Enable the history (History is disabled by default)
$dice->enableHistory();

$dice->roll(5); // Roll the Dice 5 times

$values = $dice->getHistory(); // e.g. [3, 2, 5, 6, 2]

// History can be disabled
$dice->disableHistory();

// History can be cleared
$dice->clearHistory();

异常

最常见的异常是 \InvalidArgumentException 和 daverichards00\DiceRoller\Exception\DiceException。 DiceException 扩展 \RuntimeException，将在您期望抛出运行时异常时抛出。

DiceShaker

可以通过使用 DiceShaker 创建一组 Dice。

创建 DiceShaker

在创建 DiceShaker 时，您需要指定将使用的 Dice。这可以通过传递 Dice 对象数组来完成

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;

$diceShaker = new DiceShaker([
    new Dice(6),
    new Dice(20),
    new Dice('red'),
]);

也可以通过传递用于创建 Dice 实例的标量值数组来完成

<?php

use daverichards00\DiceRoller\DiceShaker;

$diceShaker = new DiceShaker([6, 20, 'red']);

或者，您可以传递单个 Dice/标量和一个数量

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;

$diceShaker = new DiceShaker(6, 5); // Creates 5 instances of 6-sided Dice.

$diceShaker = new DiceShaker(new Dice(6), 5); // Creates 5 instances of 6-sided Dice.

注意： 当传递 Dice 实例和数量时，传递的实例将作为第一个骰子添加，然后后续的骰子将是传递实例的克隆。

投掷

DiceShaker 中的所有 Dice 都可以投掷

<?php

use daverichards00\DiceRoller\DiceShaker;

$diceShaker = new DiceShaker(6, 5);

$diceShaker->roll(); // All 5 Dice will be rolled.

获取器

有许多方法可以获取和交互投掷骰子的值

<?php

use daverichards00\DiceRoller\DiceShaker;

$diceShaker = new DiceShaker(6, 5);
$diceShaker->roll();

// Get the number of Dice in the DiceShaker
echo $diceShaker->getDiceQuantity() . PHP_EOL;

// An alias of getDiceQuantity()
echo $diceShaker->getNumberOfDice() . PHP_EOL;

// Get an array of all the rolled Dice values.
var_dump($diceShaker->getValues());

// Get the value of a single rolled Dice. Will throw an exception if more than 1 Dice is selected.
echo $diceShaker->getValue() . PHP_EOL;

// Get the highest rolled value. Uses the max() function to select this.
echo $diceShaker->getHighestValue() . PHP_EOL;

// Get the lowest rolled value. Uses the min() function to select this.
echo $diceShaker->getLowestValue() . PHP_EOL;

//
// The below can only used when ALL the Dice in the DiceShaker are numeric, an exception would be thrown otherwise.
//

// Get the sum of all the Dice.
echo $diceShaker->getSumValue() . PHP_EOL;

// An alias of getSumValue()
echo $diceShaker->getTotalValue() . PHP_EOL;

// Get the mean of all the Dice.
echo $diceShaker->getMeanValue() . PHP_EOL;

// An alias of getMeanValue()
echo $diceShaker->getAverageValue() . PHP_EOL;

// Get the median of all the Dice.
echo $diceShaker->getMedianValue() . PHP_EOL;

选择器

选择器可用于对 DiceShaker 中的 Dice 子集执行操作或获取值。选择器可以通过工厂创建并传递给操作/获取器

<?php

use daverichards00\DiceRoller\DiceShaker;
use daverichards00\DiceRoller\Selector\DiceSelectorFactory as Select;

$diceShaker = new DiceShaker(6, 5);
$diceShaker->roll();

// Re-roll the highest 3 Dice:
$diceShaker->roll(
    Select::highest(3)
);

// Get the sum of the Dice with values less than 4:
echo $diceShaker->getSumValue(
    Select::lessThan(4)
);

// Get the quantity of 6s rolled:
echo $diceShaker->getNumberOfDice(
    Select::equalTo(6)
);

有各种选择器可用

<?php

use daverichards00\DiceRoller\Selector\DiceSelectorFactory as Select;

// Highest:
Select::highest(); // Select the Dice with the highest value.
Select::highest(3); // Select the 3 Dice with the highest values.

// Lowest:
Select::lowest(); // Select the Dice with the lowest value.
Select::lowest(3); // Select the 3 Dice with the lowest values.

// EqualTo:
Select::equalTo(6); // Select all Dice equal to 6.
Select::equalTo(6, true); // Select all dice strictly equal to 6; i.e. return values equal to int(6) but not string(6).

// greaterThan / greaterThanOrEqualTo:
Select::greaterThan(2); // Select all Dice with values > 2.
Select::greaterThanOrEqualTo(3); // Select all Dice with values >= 3.

// LessThan / lessThanOrEqualTo:
Select::lessThan(4); // Select all Dice with values < 4.
Select::lessThanOrEqualTo(3); // Select all Dice with values <= 3.

// In
Select::in([1, 3, 5]); // Select all Dice with values equal to 1, 3 or 5.
Select::in([1, 3, 5], true); // Select all Dice with values strictly equal to 1, 3 or 5.

// These
Select::these([$diceA, $diceB]); // Array of specific Dice instances to select.

// Random
Select::random(); // Select a Dice at random.
Select::random(3); // Select 3 Dice at random.

// All
Select::all(); // Select all Dice.

也可以使用自定义选择器，只要它们实现了接口：daverichards00\DiceRoller\Selector\DiceSelectorInterface

<?php

use daverichards00\DiceRoller\Selector\DiceSelectorInterface;

class MyCustomSelector implements DiceSelectorInterface
{
    // ...
}

use daverichards00\DiceRoller\DiceShaker;

$diceShaker = new DiceShaker(6, 5);
$diceShaker
    ->roll()
    ->getAverageValue(
        new MyCustomSelector
    );

操作

可以对 DiceShaker 中的 Dice 执行一些操作

<?php

use daverichards00\DiceRoller\DiceShaker;
use daverichards00\DiceRoller\Selector\DiceSelectorFactory as Select;

$diceShaker = new DiceShaker(6, 5);

// Dice can be rolled.
$diceShaker->roll(); // Roll all Dice by default.
$diceShaker->roll(Select::random()); // Roll Dice selected by a selector (In this case, a Dice chosen at random).
$diceShaker->roll(Select::all(), 2); // Roll all the Dice twice.

// Dice can be kept.
$diceShaker->keep(Select::greaterThan(3)); // Only Dice with a value greater than 3 will be left in the DiceShaker after this.

// Dice can be discarded.
$diceShaker->discard(Select::Lowest()); // The lowest Dice will be removed from the DiceShaker after this.

异常

\daverichards00\DiceRoller\Exception\DiceShakerException 扩展 \RuntimeException，如果在 DiceShaker 中没有 Dice 时尝试执行操作，或尝试使用仅数字的获取器时存在非数字 Dice，则将抛出异常。

示例

2d6

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;

// In a single line:
$value = (new DiceShaker(Dice::D6, 2))->roll()->getTotalValue();

// Or, reuse the shaker multiple times:
$shaker = new DiceShaker(Dice::D6, 2);

$value1 = $shaker->roll()->getTotalValue();
$value2 = $shaker->roll()->getTotalValue();
$value3 = $shaker->roll()->getTotalValue();

2d6 + 1d8

<?php

use daverichards00\DiceRoller\DiceShaker;

$shaker = new DiceShaker([6, 6, 8]);

$value = $shaker->roll()->getTotalValue();

4d6-L

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;
use daverichards00\DiceRoller\Selector\DiceSelectorFactory as Select;

$shaker = new DiceShaker(Dice::D6, 4);

// Calculating the total of the highest 3 Dice
$value = $shaker
    ->roll()
    ->getTotalValue(Select::highest(3));

// Or, Remove the lowest Dice from the Shaker before calculating the total.
// NB: This will remove the lowest Dice from this DiceShaker instance permanently.
$value = $shaker
    ->roll()
    ->discard(Select::lowest())
    ->getTotalValue();

d% (百分比)

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;

// Use a d100
$dice = new Dice(100);
$value = $dice->roll()->getValue();

// Or, simulate using a "tens" d10 and a standard d10 dice.
$shaker = new DiceShaker([Dice::TENS_D10, Dice::D10]);
$value = $shaker->roll()->getTotalValue() + 1;

// Or, simulate using 2d10
$shaker = new DiceShaker(Dice::D10, 2);
$shaker->roll();
$value = ($shaker->getValues()[0] * 10) + $shaker->getValues()[1] + 1;

注意： 在最后两个示例中，我们向结果添加 1 以改变范围从 0-99 到 1-100。从编程的角度来看，这比将 0 视为 100 并仍然产生 1 和 100 之间均匀随机的数字更容易。

3 x (2d6+4)

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;

$shaker = new DiceShaker(Dice::D6, 2);

$value  = $shaker->roll()->getTotalValue() + 4;
$value += $shaker->roll()->getTotalValue() + 4;
$value += $shaker->roll()->getTotalValue() + 4;

8d10k6 或 8d10+H6 或 8d10-L2

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;
use daverichards00\DiceRoller\Selector\DiceSelectorFactory as Select;

$shaker = new DiceShaker(Dice::D10, 8);

$value = $shaker->roll()->getTotalValue(Select::highest(6));

从 6d10 中获取大于等于 8 个结果

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;
use daverichards00\DiceRoller\Selector\DiceSelectorFactory as Select;

$shaker = new DiceShaker(Dice::D10, 6);

$value = $shaker->roll()->getNumberOfDice(Select::greaterThanOrEqualTo(8));

4dF (Fudge)

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;

// Numerical:
$shaker = new DiceShaker(Dice::DF, 4);
$value = $shaker->roll()->getTotalValue();

// Or, for visual representation:
$shaker = new DiceShaker(["-", "", "+"], 4);
$values = $shaker->roll()->getValues();

D66 或 d6x10+d6

<?php

use daverichards00\DiceRoller\Dice;
use daverichards00\DiceRoller\DiceShaker;

$shaker = new DiceShaker(Dice::D6, 2);
$shaker->roll();

$value = ($shaker->getValues()[0] * 10) + $shaker->getValues()[1];

贡献

如果您认为我遗漏了任何内容或有任何改进可用性或功能的方法，请随时告诉我。了解人们如何使用或希望使用此包将是非常好的。如果我认为这将是有用的，我将非常乐意更新和扩展此项目 :)