API
After downloading the package via NuGet, you can use the following API in order to roll dice and view those dice results. All relevant classes are found the Dice namespace, which you can quickly access by adding using Dice; at the top of your files.
Contents
Rolling dice
To roll dice, use the Roller.Roll method. This method is static and is the main entry point to using the library.
Getting results
The Roller.Roll method returns a RollResult object, which contains the final roll value as well as the dice rolled. Generally, this is enough information to view and display results, however more fine-grained information can be obtained by walking through the roll tree. For example, in the dice expression (1d8)d6, a 1d8 is rolled, and then that many d6s are rolled. However, the RollResult will only contain the values of the d6s, it won't contain the value of the d8. You could figure it out by looking at the number of d6s there are, but it is also possible to directly inspect the d8 by walking the dice abstract syntax tree.
Play-by-Post
For posts which contain one or more dice rolls, use the RollPost class. This class can be serialized using BinaryFormatter and persisted to a database, and deserialized later. Doing so lets you keep the rolled values in the post the same, rather than needing to re-roll them each time. Macro values are persisted as well, so it will save the [WIS-mod] at the time of the post, even if the character's Wisdom has since went up. The class also contains a Validate() method which performs basic anti-cheat detection.
Configuring the roller
To configure roller settings, set the various properties on Roller.DefaultConfig. This lets you change the various dice limits as well as what is used to resolve macros.
Adding functions
To add functions, make use of the FunctionRegistry.RegisterType or FunctionRegistry.RegisterFunction methods. The first method (RegisterType) makes it easy to register numerous functions all at once.
See also
- Dice namespace
- Dice.AST namespace
- Dice.Grammar namespace
- Dice.PbP namespace
