The documentation is missing some possibilities of the DiceBag, especially the possibility to use the top n dice of a multiple roll as specified in CODE-324.
Only the syntax in my comment of the code ticket is needed to be documented, not the xdytz one.
Just to make sure that the right thing gets documented, can you reproduce the syntax that needs to be documented here?
In the dicebag.html file, there’s no mention of:
– roll(x,y) can be used to roll x dice, each having a result between 1 and y.
– roll(x,y,top(z)) can be used to roll x dice, taking the z best results, each having a result between 1 and y.
– roll(x,y,reroll(z)) can be used to roll x dice, each having a result between z+1 and y (basically it rolls between 1 and y and rerolls if less or equal to z).
reroll and top can be also combined in something like roll(4,6,top(3),reroll(1)) which takes the best 3 dices out of 4 d6 where ones are rerolled.
There’s also the list method that should be usable, and can also be used with [ ] but I don’t understand what it is used for, even looking at the code and testing.
The page you are referencing does not currently include any other syntax in that form, which is of course your point. The first line on that page says that you can "enter an expression in standard format". I assume that means the standard format found within the gaming industry, e.g. 4d6, 5d4, etc.
Was the circumstance that the roll() syntax works a matter of intent? Or coincidence? It is my opinion that not everything that PCGen will do, as an unintended artifact of the programming, needs to be documented. Lots of unintended "capabilities" have been cleaned up over the years.
Not saying we won't document this. Just want to make sure this last point is understood. Oh, and I would like confirmation that this syntax was in fact intended for this application instead of being coincidental.
I think it is an intent that the roll, top work that way because they are used in PCG characters file when defining the roll method, for example roll(4,6,top(3)). That’s probably also the case for the reroll for some character ability generation method.
There is a difference between the roll methods used in the gamemode files and the Dice Bag. The roll methods are set up by the Data Monkey creating a gamemode. The Dice Bag is intended to be used by a user who likely be more familiar with he xdy+z format of dice notation. Based on that, I would not assume that the roll() syntax was intended to be used with the dice Bag.