Dice Operations Plugin

This unofficial TaleSpire mod allows users to create dice related plugins more easily. The plugin allows you to subscrive to notification for various dice related events (both before and after the event), provides two virtual methods that can be overriden to change dice results before they are displayed, and provides a helper function to convert the convoluted dice results to a much more easily read format.

Install

Use R2ModMan or similar installer to install. Since this is a dependency plugin it will be installed automatically when needed. The user does not need to install this plugin.

Usage

Dice Notifications

There are three functions for managing notifications:

System.Guid AddNotification(EventCallbackDelegate) void RemoveNotification(System.Guid subscrition))

When a notification is added, a subscription guid is returned which can be used with the RemoveNotification methods to unsubscribe from any notifications associated with the subscription guid.

The following events are available:

LoadDiceInTrayCallback(DiceEvent diceEvent,RollId rollId,ref DiceRollDescriptor rollDescriptor,ref bool showResult)

SpawnDiceFromTrayCallback(DiceEvent diceEvent, RollId rollId, DiceRollDescriptor diceRollDescriptor, ref float3 pos, ref bool isGmRoll, ref bool showResult)

GatherDiceCallback(DiceEvent diceEvent, RollId rollId, ref Vector3 position)

RollDiceCallback(DiceEvent diceEvent, RollId rollId, ref float3 velocity)

ClearDiceCallback(DiceEvent diceEvent, RollId rollId)

DiceRollResultCallback(DiceEvent diceEvent, RollId rollId, ref Dice.RollResults rollResultData, ref ClientGuid sender)

DiceRollChatResultCallback(DiceEvent diceEvent, RollId rollId, ref RollResults diceResult, ref UIChatMessageManager.DiceResultsReference.ResultsOrigin origin, ref ClientGuid sender, ref bool hidden, UIChatMessageManager.IChatFocusable focus = null)

It is possible to either provide the callback as a lambda expression or as a callback method:

AddNotification((RollDiceCallback)((DiceEvent diceEvent, RollId rollId, ref float3 velocity) => { LoggingPlugin.LogDebug("Event: "+diceEvent+", RollId: "+rollId+", Velocity: "+velocity); }));

or

AddNotification((RollDiceCallback)rollCallback);
public void rollCallback(DiceEvent diceEvent, RollId rollId, ref float3 velocity)
{
   LoggingPlugin.LogDebug("Event: "+diceEvent+", RollId: "+rollId+", Velocity: "+velocity);
}

It should be noted that notification will trigger with a before and after event. Use the diceEvenet parameter to identify which event the callback is associated with.

DiceEvents is an enumeration of the following events:

DiceEvents.beforeLoadDiceInTray
DiceEvents.afterLoadDiceInTray
DiceEvents.beforeSpawnDiceFromTray
DiceEvents.afterSpawnDiceFromTray
DiceEvents.beforeGatherDice
DiceEvents.afterGatherDice
DiceEvents.beforeRollDice
DiceEvents.afterRollDice
DiceEvents.beforeDiceRollResult
DiceEvents.afterDiceRollResult
DiceEvents.beforeDiceRollChatResult
DiceEvents.afterDiceRollChatResult
DiceEvents.beforeClearDice
DiceEvents.afterClearDice

Each callback has different parameters that it provies but all callbacks have DiceEvent and RollId as the first two parameters.

Dice Methods

Dice operations can be do using the provided IEnumerator methods. The following methods are available:

IEnumerator SpawnTrayDice(float delay) IEnumerator GatherDice(RollId rollId, Vector3 pos, float delay) IEnumerator RollDice(RollId rollId, float delay) IEnumerator ClearDice(RollId rollId, float delay)

Where rollId is usually obtaine from one of the notifications (excluding either of the LoadDiceInTray which always some back with a default roll id).

These functions are intended to be run as Coroutines and thus something like:

_self.StartCoroutine(DiceOpsPlugin.SpawnTrayDice(0.5f));

Result Modification

Many of the parameters provided to the callback are ref parameters allowing the callback to modify these parameters. Typically the user will want to change these parameters is the "before" event to have the changed processed immediately but there may be cases were a change is the "after" event may be appropriate.

Dice Result Simplification

A helper method is provided to parse Dice.RollResults objects. The helper function returns an object which contains the roll formula, an array of all dice values in the same order as the roll formula, and a array of all totals.

Sample usage:

var simplifiedRoll = DiceOpsPlugin.RollSimplifier.ParseRollResults(rollResultData);

LoggingPlugin.LogInfo($"Roll Id: {rollResultData.RollId}");
LoggingPlugin.LogInfo($"Roll Formula: {simplifiedRoll.RollString}");
LoggingPlugin.LogInfo($"Roll Dice: [{string.Join(", ", simplifiedRoll.AllDiceValues)}]");
LoggingPlugin.LogInfo($"Roll Totals: [{string.Join(", ", simplifiedRoll.Totals)}]");

would return something like:

2025.11.11 17:59:07.712 - Info    - DiceOpsPlugin        - Roll Formula: 1d20+5 / 1d8+3+2d6+2
2025.11.11 17:59:07.713 - Info    - DiceOpsPlugin        - Roll Dice: [9, 3, 1, 2]
2025.11.11 17:59:07.714 - Info    - DiceOpsPlugin        - Roll Totals: [14, 11]

Notice that the totals property is also an array providing the total for each roll group.