battlerattle/shuffle-bag

Shuffle Bag for better random distribution

Shuffle Bag

Build status: , _(*1)

Scrutinizer: , _(*2)

Packagist: , _(*3)

This is a Shuffle Bag implementation, highly inspired by this nice article and its C# example., _(*4)

What is a Shuffle Bag?

A Shuffle Bag can be used for picking random items while reaching the targeted distribution after max. X picks, where X means the sum of all amounts the items were added., _(*5)

The Shuffle Bag could be used in games in order to provide a certain amount of randomness while having the guarantee to keep the game balanced at the same time., _(*6)

Installation

The easiest way to install this library is to use Composer Add the package "battlerattle/shuffle-bag" to your composer.json, _(*7)

{
    "require": {
        "battlerattle/shuffle-bag": "v1.0-beta"
    }
}

Example

Imagine you want 3 different items to be picked with a probability of 10%, 30% and 60%. Add those items 1, 3 and 6 times to your bag and after 10 picks you got the targeted distribution. Add those items 10, 30 and 60 times in order to get a better randomness, because you could get the first item 10 times in row by random, but after max. 100 picks, you reached the target distribution again., _(*8)

Usage

Here we implement the example as described above:, _(*9)

use BattleRattle\ShuffleBag\ArrayShuffleBag;

$bag = new ArrayShuffleBag();

// add your items with a certain probability
$bag->add('item 1', 1);
$bag->add('item 2', 3);
$bag->add('item 3', 6);

// pick a random item
$item = $bag->next();

In order to use the same bag over multiple requests, you need to store the bag in a persistent storage. Here we use the PersistentShuffleBag with Redis (Predis) as storage:, _(*10)

use BattleRattle\ShuffleBag\PersistentShuffleBag;
use BattleRattle\ShuffleBag\Storage\RedisStorage;
use Predis\Client;

$redisClient = new Client();
$storage = new RedisStorage($redisClient);
$bag = new PersistentShuffleBag($storage);

$bag->add('foo', 42);
$bag->add('bar', 1337);

$item = $bag->next();