The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Game-PseudoRand-0.01
River stage zero No dependents
++
/ Game::PseudoRand

NAME

Game::PseudoRand - pseudo random distribution functions

SYNOPSIS

  use Game::PseudoRand qw(prd_step prd_table);

  ( $coinflip, undef ) = prd_step( start => 0.25, step => 0.41675 );

  ( $randfn, undef ) = 
    prd_table( start => 0.12, table => [ 0.05, 0.05, 0.1, 0.1 ] );

  $coinflip->() and say "heads";

DESCRIPTION

This module creates Pseudo Random Distribution random functions. For example one may construct a function that returns true 25% of the time but with a rather different distribution than from a typical random function: typically a distribution with much lower odds of long runs of hits or misses.

FUNCTION GENERATING FUNCTIONS

These return a pair of functions, the first being the random check, and the second a function that will reset the internal state back to the starting values. If something goes wrong an exception will be thrown.

Random values are assumed to be in the same range as the rand builtin accepts, or

  0.0 <= r < 1.0
prd_step start => odds step => step-odds ...

Increases the starting odds by step-odds each miss, resets to reset or start odds on hit. Optional keys rand (custom random function, should use same return range as builtin rand does) and reset (odds to reset to, if different from the start odds).

(Players may quickly realize and become annoyed by things that always miss on the first try, so maybe only make start slightly lower than the reset value when imposing a first use penalty. On the other hand, beginner's luck can be a thing.)

prd_table start => odds table => table ...

Increases the odds by the value given in table at the rotating index index on miss; resets to reset or start on hit, and also resets the index to 0 on hit. Optional keys index (custom starting index, default is 0) and as for the previous function rand and reset.

Unlike prd_step the table allows for non-linear odds changes, and will wrap around back to the beginning instead of always (eventually) adding up to a value greater than 100% (assuming a positive step value); this means prd_table can permit longer runs of misses, depending on the table used.

The table is copied so cannot be fiddled with afterwards (not directly nor easily, anyways).

STATISTICS 101

  prd_step( start => 0.25, step => 0.41675 )

was above claimed without evidence to be (roughly) a coinflip; what this tests for is whether a random value is below 0.25, 0.66, and then 1.08. This means the distribution will be quite a bit different from the output of a random function:

  $ cd eg
  $ ./trial | ./runstats | r-fu table
  50.0351

       1      2      3
  125308 250439 124604

So no more than three flips without the result changing to a different value; an unbiased roll instead may show (increasingly rare but not absent) runs of 10, 20, or even more flips without a change in value:

  $ perl -E'say rand()>0.5?1:0 for 1..1e6'|./runstats|r-fu table

       1      2      3      4      5      6      7      8      9
  250244 124873  62288  31391  15578   7803   3954   1910   1018
      10     11     12     13     14     15     16     17     18
     468    252    136     54     34     18      6      3      2

The main point of this module is to reduce this variance, but probably not so far as done for the example coinflip, and most likely in the context of a game where too much variance is bad (luck is too much of a factor).

BUGS

Please report any bugs or feature requests to bug-game-pseudorand at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Game-PseudoRand.

Patches might best be applied towards:

https://github.com/thrig/Game-PseudoRand

SEE ALSO

https://github.com/thrig/ministry-of-silly-vaults/ contains a discussion and example code under the pseudo-random-dist directory.

Various alternative random modules to the (bad, but fast) builtin rand call exist on CPAN, e.g. Math::Random::PCG32, among others.

https://github.com/thrig/r-fu/ is the command line bridge to R used in the shell statistics commands, above.

AUTHOR

thrig - Jeremy Mates (cpan:JMATES) <jmates at cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2019 by Jeremy Mates

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause