At 19:01 2005.10.01, Byngl wrote:

>That'll get you to the definition of the function, but won't be

>entirely helpful. What you need to look at is

>src/java/pcgen/util/DiceExpression.jj. This file defines the grammar

>used to parse the dice expressions. It gets run through javaCC (Java

>Compiler Compiler). The .jj file is credited to binkley, so if you'd

>like more info, he'd be the one to contact.

>

>Byngl

Here's what I can tell about the roll function:

We can invoke the function multiple ways. What the function do is based on the number and type of the parameters.

The type can be integer, array of integer or string.

The roll functions appear to be all defined in \src\java\pcgen\util\DiceExpressionFunctions.java and they all call RollingMethods.roll in \src\java\pcgen\core\RollingMethods.java

When using the roll function, numbers are treated as integer, list of coma separate integer enclosed in [] are treated as array of integers, characters enclosed in "" are treated as strings. I do not know for sure how a string without the "" is interpreted but I think the parser somehow tries to convert it to integer before feed the functions (e.g.. 3d6 without the "" would be seen as 3 or 6 or 36, 5+1 would probably be 6).

The possible ways to call the roll functions are:

General note: all the roll function returns the total of all rolls performed

roll(times,sides) times => integer, number of time to roll

sides => integer, type of dice to roll

e.g. roll(3,6) == 3d6

roll(sides) sides => integer, type of dice to roll

e.g. roll(6) == 1d6

note: this is one form that do not call

RollingMethods.roll but call Globals.getRandomInt

directly instead

roll(times,sides,[keep])

times => integer, number of time to roll

sides => integer, type of dice to roll

[keep] => array of integer, index of the dice

we want to keep. The dices are sorted

from the lower result (index = 1) to

the largest result (index = times)

e.g. roll(4,6,[2,3,4]) == 4d6, keep the three best

roll(times,[sides]) times => integer, number of time to roll

[sides] => array of integer, possible dice to choose

from randomly

e.g. roll(4,[4,6]) == roll four times, each time you

randomly choose a d4 or a d6

note: this is one form that do not call

RollingMethods.roll but call Globals.getRandomInt

directly instead.

Whoever code this called it bizarre dice

rolling with good reason.

roll(times,[sides],[keep])

times => integer, number of time to roll

[sides] => array of integer, possible dice to choose

[keep] => array of integer, index of the dice

we want to keep. The dices are sorted

from the lower result (index = 1) to

the largest result (index = times)

e.g. roll(4,[4,6],[3,4])

== roll four times, each time you randomly

choose a d4 or a d6, and you keep only the

two best results

note: this is one form that do not call

RollingMethods.roll but call Globals.getRandomInt

directly instead.

Whoever code this called it bizarre dice

rolling with good reason.

roll("djep") "djep" => string, djep expression that gets fed to the

djep parser

e.g. roll("3d6") == 3d6

And the last but certainly not the least clear

roll(times,sides,modifier,keep,reroll_value)

times => integer, number of time to roll

sides => integer, type of dice to roll

modifier => integer, value that gets added to the total

after all the rolls are done

keep => integer, number of dices to keep, the lower

values are dropped

reroll_value => integer, if the result is not greater

then reroll_value, roll again (multiple

times is necessary)

e.g. roll(4,6,10,3,2)

== roll 4d6, reroll any 1 or 2, keep the 3

highest values, and add 10 to the total

Well, this is a bit ugly and it doesn't allow us to do everything we need. So I ask for three FREQ.

1) Please, put all the existing way to call roll in the documentation before we

forget. I really don't want to do this again (my nose is bleeding!)

2) Two new form of rolls (really, we don't nearly have enough of them)

roll(times,"djep")

roll(times,"djep",[keep])

times => integer, number of time to roll

"djep" => string, djep expression that gets fed to the

djep parser

[keep] => array of integer, index of the dice

we want to keep. The dices are sorted

from the lower result (index = 1) to

the largest result (index = times)

e.g. roll(3,"1d5+1") == evaluate the djep expression

1d5+1 three times and return the total

e.g. roll(4,"1d5+1",[2,3,4])

== evaluate the djep expression 1d5+1 four

times and return the sum of the three

highest values

maybe roll(times,"djep",keep) could also be done

times => integer, number of time to roll

"djep" => string, djep expression that gets fed to the

djep parser

keep => integer, number of dices to keep, the lower

values are dropped

e.g. roll(4,"1d5+1",3)

== evaluate the djep expression 1d5+1 four

times and keep the three highest values

I'm not sure though since it add complexity and if we have to choose, I prefer we keep the more versatile [keep] version. I think we should be OK with only three form that use "djep".

3) We deprecate all the forms that do not use djep. Let's face it, roll("3d6")

or roll(3,"d6") are way clearer then roll(3,6). The djep expressions allow

us to do way more.

Well, that's about it.

-----------------------------------------------------------

Éric "Space Monkey" Beaudoin

Founding Member of the Hidden-in-the-Trench Club

Release Monkey and Syntax Watchdog

>> In space, no one can hear you sleep.

>> Camels to can climb trees (and sometime eat them).

<mailto:

beaudoer@...>