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.

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.

Reading API documentation

Many icons are used in the API documentation. Hovering over these icons will give a tooltip indicating what the icon means. This library follows Semantic Versioning conventions. As such, backwards-incompatible changes will not be introduced into the public API on minor or point releases. The API documentation here documents both the public API as well as the internal (private) API, as it is intended to be useful for developers working on the library itself as well. Public API methods are marked with either public () or protected () lock icons, whereas internal API methods are marked with internal () or private () lock icons. Internal API may change in backwards-incompatible ways across minor or point releases. If you are using Reflection to access the internal API from code which consumes this library, it is your responsibility to test all updates before applying them.

The public API (with exception of the Dice.Grammar namespace) is CLS compliant and will work with any programming language targeting .NET, whereas the internal API requires using C#.

See also

• Dice namespace
• Dice.AST namespace
• Dice.Grammar namespace
• Dice.PbP namespace