0.4.2 Update – Handling Dice Rolls

Psicodelix Psicodelix

As promised version 0.4.2 is already here with a bunch of exciting new features added to the Dice Roll Engine.

version 0.4.2

  • Added DiceRollString variable to controls’ roll event to allow roll string modificaton in onBeforeDiceRoll function.
  • Changed Button text behaviour to add a click offset effect.
  • Added logo file to extensions.
  • Added logo icon to announcement message.
  • Fixed a crash with Window control names starting with numbers.
  • Main window remembers last Open/Save and Generate folders.
  • Properties ‘Targeting type’, ‘Use modifier stack’ and ‘Result handler function name’ added to Dice Roll structure.
  • Added support for handling dice roll results.
  • Ruleset Wizard Core project updated to add combat tab and attack and initiative rolls handling examples.

New properties

This is the look of the new Dice Roll structure, there are three new properties: ‘Targeting type’, ‘Use modifier stack’ and ‘Result handler function name’, we will discuss them later in this article.

DiceRollString variable

Since version 0.4.0 you have available two event functions related to the dice roll: onBeforeDiceRoll and onAfterDiceRoll. You can use them to create your own logic in response to the roll, but you couldn’t change the dice roll itself as defined in the control properties.

Now Ruleset Wizard exposes the new variable DiceRollString, with it you can modify the dice roll before it is processed by Fantasy Grounds.

For example, if you want to add 1d6 to the roll only under certain circumstances you could type in the control’s LUA code section the following:

function onBeforeDiceRoll()
    if condition then
        DiceRollString = DiceRollString .. " + 1d6";
    end
end;

This greatly expands the level of flexibility your rulesets can achieve.

Result handler function name

At some point in the development of a ruleset you will want to get the result of a roll and execute some kind of logic based on it. The onAfterDiceRoll function does not serve this purpose, as it is executed before you get the result of the roll.
Due to the Fantasy Grounds process model the result of the dice roll can only be obtained asynchronously, by using a handler function.
The Wizard simplifies this process for you, allowing you to declare a function name where that logic will be placed, and the Wizard creates all the necessary underlying configuration, but handling the roll requires the use of a substantial amount of lua programming.

If you set the Result handler function name property to any value, the engine will register a new dice roll handler, so when the roll result is ready it will call the function whose name has been indicated in it. Note that when this happens you must perform the entire post process of the roll, including displaying the result messages in the chat.
If you left it blank the engine will make the roll and will show the result, without further automation.

The Result handler function should have a signature like this:

function myHandler(rSource, rTarget, rRoll)

end

It receives three parameters:

  • rSource will contain data regarding to the source character of the roll.
  • rTarget will contain data regarding to the target (or targets), if any, of the roll.
  • rRoll will contain data regarding to the dice rolled and their results.

This is a simple example of usage:

function InitHandler(rSource, rTarget, rRoll)

    local rMessage = ActionsManager.createActionMessage(rSource, rRoll);
    Comm.deliverChatMessage(rMessage);    

    if (rSource) then
        local nTotal = ActionsManager.total(rRoll) + rRoll.nBonuses;
        rCreature = DB.findNode(rSource.sCTNode);
        rCreature.getChild("initresult").setValue(nTotal);
    end

end

Note that the InitHandler function is declared inside a global Script named RollHandlers. To call it we must use its full qualified name: RollHandlers.InitHandler. You can find more complex examples in the Ruleset Wizard Core sample project.

Use modifier stack

This property sets if the roll must use the values in the modifier stack to adjust the result.

Targeting type

This property tells the engine if the roll must use the CoreRPG combat tracker integrated targeting system to perform the roll, and it can get the following values:

  • Not set o none: The roll will not use targeting and will ignore any targets of the roll’s source.
  • all: The roll will use the targeting subsytem. It will make a single roll and will use the result for all the selected targets.
  • each: The roll will use the targeting subsytem. It will make a roll for each selected target, so each target will get its own result.

Final words

This is the most complex feature implemented so far in the Ruleset Wizard, and it will require some time until it is fully tuned. I will expand on the examples and documentation in subsequent articles and videos.

There are still features to be included, such as drag and drop support, but they will be included in later revisions.

In the meantime, the best starting point is the Ruleset Wizard Core project (you can find it in your Ruleset Wizard installation folder), which already has several advanced usage examples.