[Dicey-cvs] dicey/random Readme,NONE,1.1

[<mad...@us...>]

Update of /cvsroot/dicey/dicey/random
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1652

Added Files:
	Readme 
Log Message:
describes the API for the RNG and the interface to the dicey functions.


--- NEW FILE: Readme ---
This document purports to tell you how to use the r250 random number 
generator in your code.

The first thing that you need to do is to call r250_srand() and pass
it a seed value. If you do not call this function first then the
default seed will be used to initialize the system.

The other available functions are:

int r250_rand(void)
	this returns a random integer 0 <= k < 65536

int r250_randn(unsigned n)
	this returns a random integer 0 <= k < n

double r250_flat(void)
	this returns a random double 0 <= z < 1


There are two dicey related functions in the library: techroll and
combatroll. 

techroll takes 3 parameters: number of dice to roll, a list of the
available techs, and a list of the techs the player already has.

Both of the tech lists are formatted the same: tech1/tech2/tech3....

It is up to the calling program to ensure that the case and spelling
of the techs in both lists are the same.

The return is in string form to facilitate use in online forms. There
are at most 3 sections, but there will always be two sections of the
response. The first section is the number of successful rolls, the
second is the dice roll, and the third (which may be empty) is a list
of the techs received. The hits in the second section are denoted by
the asterisk character.

Here are a couple of examples:

techroll 3 "jet/rkt/ssb/lrg/ind/bmb" "ssb/lrg"
0:215:

Result: no new techs

techroll 3 "jet/rkt/ssb/lrg/ind/bmb" "ssb/lrg"
1:6*12:ind/

Result: 1 new tech, industry given

techroll 3 "jet/rkt/ssb/lrg/ind/bmb" "ssb/lrg"
2:6*26*:ind/jet/

Result: 2 new techs, industry and jet power given


Combatroll takes 2 arguments, the number of dice to roll and the
highest dice value that constitutes a hit. 

The return is in string form and consists of two parts separated by
the colon character. The first part is the number of hits and the
second is the dice roll. Hits in the second section are denoted by the
asterisk character.

Here are some examples:

combatroll 10 3
10:1*1*1*2*2*3*3*2*3*3*

Result: 10 hits

combatroll 10 3
4:1*1*6561*61*65

Result: 4 hits

combatroll 10 1
1:346421*2552

Result: 1 hit