New major update: The Dice Roll Engine

Psicodelix Psicodelix

Today the version 0.4.0 (Doppleganger) has been released, which includes the long awaited advanced dice roll engine.

version 0.4.0

  • New feature: Dice Roll Engine
  • Removed Dice Roll Description Field property from Number Fields and Die Fields (obsolete by Dice roll engine)
  • Changed behaviour of Dice Roll and Dice Roll Description Text from Number Fields to use the new Dice roll engine
  • Added Dice Roll properties to Button control
  • Button text not showing properly. Fixed.
  • Error generating rulesets with previous versions of AcceptDrop. Fixed.

Dice Roll Engine

This new feature opens a new range of possibilities when creating complex game systems without writing LUA code, although it also has options for more advanced users.

WARNING! This release makes deep changes in previous dice roll mechanics of Ruleset Wizard. Keep this in mind before installing the new version:

  • This is a major update, so it could contain errors that affect the operation of your projects.
  • Make backup copies of your projects before opening them with the 0.4.0 version.
  • Dice roll properties has been reworked, so you may have to redo something to adapt it to the specifications of the new engine. Read the instructions for each control.
  • The Wizard will upgrade your controls’ properties to adapt them to the new version, but you should check every control that make use of dice rolls to verify that everything is okay.

How to use the new Dice Roll Engine

All dice roll properties are now grouped in a compound property named Dice Roll, so you’ll have to expand it to see and edit all its properties. This is because it is planned to add multiple options to this property in successive revisions:

The main property is Dice Roll string. Here you can type any valid type of dice roll supported by Fantasy Grounds, as explained on this page:

https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/996640101/Rolling+Dice

Please note that supported dice rolls are different from FGU to FGC. Complex dice types will work only in FGU, while in FGC will work only the simpler ones.

Referencing other fields

In addition to the options offered by Fantasy Grounds, you can reference other fields of the sheet to use their value in the calculation. To make reference to another field you have to specify its name between braces {}. For example, you may type:

d20 + {fortitude}

And when you roll the field the result will be a d20 roll plus the current value of the sheet’s fortitude field.

You can use field reference anywhere in the roll string, for example:

{dicepool}d6

This will roll a number of d6 equal to the current value of the dicepool field.

You can even use other references than numeric values. For example. you could have a stringcycler named operation with values ‘+’, ‘-‘ and use it in a dice expression like this:

d20 {operation} {field1}

And this will roll a d20 and add or subtract the current value of field1, depending on the value selected in operation field.

To reference the value of the field itself you can use the expression self:

d20 + {self}

You can also reference fields in nodes relative to the current using FG’s database node naming syntax. For example, you can get the field field1 from the parent window of the current as follows:

d20 + {...field1}

Moreover, you can use a special dynamic reference, in which the value of a field indicates the name of another field whose value you want to use in the calculation. To do this you use the double reference operator {{}}.
For example, you have a skill total field to which you want to add the bonus of an attribute selected by the player. You could use the following expression:

d20 + {{attribute}}

Let’s suppose that the attribute field has the STR value selected. In this case this will roll a d20 and add the current value of the STR field to it.

Additional properties

Int the Roll Description Text you can, optionally, indicate a description for the roll that will be showed in the chat. In this text you can use field reference too, so you could build a descrition text like this:

Skill Result for {skillname}

The Roll Type property sets the type of the roll when handling the result in the actions manager. We will see this in depth later on.

Using Dice rolls in controls

Actually, there are three controls in which you can use the Dice Roll engine: Number field, Die field and Button, with slight differences between them and with their form of use until now.

Dice Roll Description Field property is removed as it is no longer needed. Those projects in which it is being used should be updated to the new field reference method.

In Number fields the operation is the same as above, and the event used for the dice roll is the double click.

The operation of Die fields has some changes that you have to keep in mind to upgrade them to the new version. The Rollable property = True is still needed to make the field rollable with the Dice Roll engine, otherwise it can only be dragged.
The event used for the dice roll is the double click too.
Field to add to the roll Property is removed as well, as it is unnecessary. Those projects in which it is being used should be updated to the new field reference method.
Keep in mind that Dice roll string must consider that dice already entered in the control itself will go at the beginning of the string, so if you want to add a value to the roll of a Die field you should write something like this:

+ {fieldtoadd}

Starting with version 0.4.0 the Button control can be made rollable. If the Dice Roll string property is filled the control automatically launch a roll when clicking the button.

Advanced event trigger functions

For those advanced users who want to be able to write their own lua code in response to the roll event, the Wizard provides two event trigger functions: onBeforeDiceRoll and onAfterDiceRoll. These functions, if defined in the control, are called respectively before and after the dice roll. Here is an example of usage:

With these functions you will be able to modify the values of the fields used in the roll before or after the roll. You can even modify the whole dice roll string itself, by using the DiceRollString variable. Changing it in the onBeforeDiceRoll event function changes the final roll string that will be processed by the engine. For example:

function onBeforeDiceRoll()
    DiceRollString = string.gsub(DiceRollString, "d6", "d12");
end

This will cause the engine to process and throw d12s instead of d6s for the dice roll.

However you won’t be able to handle the result of the roll. For this you will have to use other mechanisms that we will discuss in future blog posts.