Changelog

4.2.0

Backwards-incompatible changes:

• Some DiceAST subclasses were removed. The DiceAST class hierarchy is considered an implementation detail and not a public API for the purposes of semantic versioning. However, the change is being noted here so any library consumers incorrectly casting to or using these subclasses can audit their code.

New user features:

• The rerollN() function now accepts any numerical expression for the first argument (max # of rerolls) e.g. 1d20.rerollN(2+3, =1) or 1d20.rerollN(1d6, =1)
• The rerollN() function can now be specified multiple times for fine-grained reroll control, e.g. 1d20.rerollN(2, =1).rerollN(1, =2, =3) rerolls either a "2" or "3" once but rerolls a "1" twice.
• More informative error messages if you omit something when specifying an extra on a roll
• Dice expressions are no longer case sensitive. Roll 1d20 or 1D20, whichever you prefer!
• Defining a success condition is no longer required when all you want to do is define a failure (negative success) condition
• New function explodeOnce() / !eo to perform an explode operation at most once.
• New function implode() / !i to act as the inverse of explode; when the comparison is met a new die is rolled and subtracted from the result. This continues until the comparison fails.
• New function implodeOnce() / !io to perform an implode operation at most once.
• New function compoundImplode() to perform an implode operation with compound semantics, causing a single die to be sent as output containing the final result of the implode operation.

New developer features:

• Builtin functions can be overridden by custom functions by registering a function with the same name
• Builtin functions can be removed
• Custom functions can be registered with the same timing as builtin functions
• Custom extras can be registered along with custom functions
• Custom functions can specify how multiples of the same function are executed when attached to the same roll
• Custom functions can specify how their arguments should look, and will be validated before being called
• XML documentation added to all classes, methods, and properties for better IntelliSense. Improving the XML documentation quality is still a work in progress, please leave suggestions in a new issue on GitHub!

Bugfixes:

• Fixed nullability annotation for DieResult.Data; this string can be nullable and has always defaulted to null

Deprecations:

• Dice.BuiltinFunctions and Dice.BuiltinMacros are deprecated; please use their counterparts in the Dice.Builtins namespace if you would like to directly call any of them from within your custom functions/macros. These two classes will be removed in the next major release.
• DiceErrorCode.InvalidSuccess is deprecated and no longer used by the library. This enum value will be removed in the next major release.
• Direct access to the DiceAST classes and the parser is deprecated; these will become inaccessible or transition to using a public interface instead of exposing the classes directly in the next major release. No deprecation notice is emitted while compiling for these deprecations.
• .NET Framework 4.5.2 support is deprecated; support will be dropped when .NET Framework 4.5.2 reaches end of support from Microsoft on April 26, 2022. Circumstances in the future may cause an earlier removal.

4.1.0

• Backwards-incompatible changes:
  • None
• New features:
  • The leading number denoting number of dice (before the "d") is optional and will default to 1 if not specified.
  • Nullability annotations have been added to public APIs, to assist developers in migrating their own applications using this library.
• Bugfixes:
  • None

The package as well as Dice.dll is signed with the following digital certificate fingerprint. This signature is only available on the official download from NuGet and is separate from the Strong-Name Key found in GitHub.

• E5F191DB201E9E3CF85B2A9E2408352057ABD731949C986E36F812CFD90728A7 (SHA-256)
• A87D3B543D551CCD330C23B31B653835A86569BC (SHA-1).

4.0.0

• Backwards-incompatible changes:
  • Nested rolls are fully resolved in RollResult.ToString(). For example, instead of ToString() reporting "(1d8)d6", it will now report the value rolled for the d8, e.g. "3d6".
  • RollerConfig.ExecuteMacro was removed.
• New features:
  • DiceRoller is now packaged for both .NET Standard 2.0 as well as .NET Framework 4.5.2. .NET Standard 2.0 supports .NET Framework 4.6.1+ and .NET Core 2.0.
  • Success/failure rolls can now be decorated with critical/fumbles. A critical success (a roll that is both a critical and a success) is worth 2 successes, and a critical failure (a roll that is both a fumble and a failure) is worth -2 successes. This expands support into game systems which use success-based rolls but have varying degrees of success beyond just +1 or -1.
    • Unless a success/failure roll is explicitly decorated with a critical/fumble, those rolls will not be marked as criticals or fumbles even if the max or min amount is rolled. This keeps default behavior with such rolls consistent with how they worked previously.
  • A new [numDice] macro was added, which returns the total number of dice rolled up to this point. This macro is available in all scenarios, including the stand-alone Roller.Roll; using the Play-by-Post helper is not required to use this macro.
  • A new property RollerConfig.RollDie was added to allow customizing the result of a die roll in a more friendly way. This property is a callback which receives the minimum and maximum value it can roll for a die, and should return a number within that range. By default, it will call RollerConfig.GetRandomBytes repeatedly until it gets a result it can transform into the output range without introducing any bias.
  • New APIs Roller.Max(), Roller.Min(), and Roller.Average() evaluate the dice expression and return the result as if all dice rolled their minimum, maximum, or average values.
• Bugfixes:
  • It is now possible to put an expression in parenthesis (a "nested roll") everywhere a number is expected. Previously, comparisons incorrectly rejected nested rolls.
• Dependency updates:
  • Updated Antlr4.Runtime.Standard from 4.7.1 to 4.7.2
  • Updated System.ValueTuple from 4.4.0 to 4.5.0
• Other:
  • The nuget package is now digitally signed with the certificate fingerprint a87d3b543d551ccd330c23b31b653835a86569bc. The same certificate is used to sign the .dll itself in addition to the package.

3.1.0

• New features:
  • Global functions can now show up inside math expressions without needing to wrap them in parenthesis. For example, -max(1, 2)+6 will return 4. They still cannot show up inside of a roll expression without additional parenthesis.
  • New API RollPost.HasDivergedFrom() to test whether two RollPosts have Diverged. (Two RollPosts diverge when one is not a prefix of the other)

3.0.2

• Updates:
  • Updated ANTLR runtime version from 4.7.0 to 4.7.1

• Bug fixes:
  • New installations will now properly install the correction version of dependencies. Before, a fresh install would install System.ValueTuple 4.3.0 when 4.3.1+ was required.
  • The .expand() function on multiplied group rolls, e.g. 2{3d6}.expand(), would show the last set of rolled dice each time instead of showing each set.

3.0.1

• Bug fixes:
  • Using DieResult methods to drop dice, mark as failures/successes, etc. stripped the Data property. The Data property is now retained in such cases.

3.0.0

• Backwards-incompatible changes:
  • DiceAST subclasses have their RollerConfig parameters swapped with RollData. This change is only breaking if you have implemented custom AST nodes. If you have not implemented custom AST nodes, no code changes need to be made to your project.
  • Grouped rolls now always aggregate their values. In other words, {4d6} will return a single number such as 20 rather than list all 4 individual die rolls. It is no longer necessary to nest groups in order to accomplish this. If you want all individual dice listed, either do not use a grouped roll, or use the new expand() function.

• New features:
  • RollerConfig.MacroRegistry can be used to associate macro callbacks to specific names instead of registering a global handler.
  • A new [DiceMacro] attribute is added to be used in conjunction with MacroRegistry.RegisterType.
  • Roller.Roll can now take an optional RollData object as a 3rd parameter. This can be used to add in custom functions or macros only valid for that roll (as opposed to global across multiple rolls as is the case for RollerConfig). Functions or macros defined here with the same name as global ones override the global ones.
  • A Metadata object can be passed as part of RollData and is passed as-is to the RollResult. This allows you to attach additional data to RollResults when serializing them to the database, which can be useful when reconstructing something pulled from the database.
  • A new expand function can be applied to grouped rolls which expands each group result into the individual dice rolled.

• Deprecated:
  • RollerConfig.ExecuteMacro is deprecated and will be removed in a future version. Use RollerConfig.MacroRegistry instead.

2.0.2

• Bugfixes:
  • Invalid dice expressions are now tracked in RollPost, so that fixing these expressions in an edit does not invalidate rolls that took place afterwards.
  • Turning a previously-rolled result into an invalid expression is now marked as a modified post.

2.0.1

• Bugfixes:
  • Errors when lexing the dice expression now throw an error instead of being silently ignored.

2.0.0

• Backwards-incompatible changes:
  • RollPost now roundtrips when serializing using default BinaryFormatter (so it is usable in .NET remoting now). A new serialization format has been added (exposed via Serialize and Deserialize convenience methods) for RollPost, RollResult, and DieResult that is meant for persistence. This still uses BinaryFormatter behind the scenes, it is recommended that you compress the output before storing in the database.
  • Unary negations cannot be stacked on a number. Previously an expression ----1 was valid (and evaluated to positive 1). Now, such an expression is no longer valid. This hides the implementation detail of negation being implemented as an operator rather than part of a number. To get the same result, parenthesis are now needed -(-(-(-1))). Existing rolls using the old method will now throw parse errors.
  • When evaluating macros, leading/trailing spaces are trimmed, and the Param string is exploded along the colon character as Name and Arguments. A future version will expose the ability to register a macro callback with a specific name, rather than having a handler listen to every macro.
• Allow subclasses of DiceAST outside of Dice.dll to override UnderlyingRollNode in preparation for the ability for outside assemblies to extend the parser (planned for a later 2.x version).
• Additional documentation comments, and fixing some inaccuracies in existing comments.
• Additional unit tests.
• Bugfixes:
  • Throw more informational exceptions rather than having an internal detail throw an exception (ArgumentNullException instead of NullReferenceException, InvalidOperationException with a more meaningful error message rather than ArgumentException on Dictionary.Add, etc.).
  • Fix roll macro argument parsing.
  • Expose Dice.Grammar.DiceErrorListener (was documented as public but not marked as such in the code).

1.1.0

• New Play-by-Post helper class RollPost, found in the Dice.PbP namespace.
  • Rolls can be serialized and saved to a database (or somewhere else, I don't judge) so that rolls within a post remain fixed between previews/edits.
  • Contains the ability to detect tampering of roll expressions within a post (deleting/modifying rolls). Adding new rolls at the end is ok, everything else causes validation errors.
  • A new [roll] macro which can be used to obtain results of previous rolls in the same post.
• DieResult and RollResult are now Serializable and Equatable.
• Group rolls can now be rerolled.
• New if() global function, which lets you test an expression against a comparison, and return one of two expressions depending on whether or not the comparison succeeded.

1.0.0

• Initial version