Dice Roll package

Dice Roll


A plug-and-play package to roll a defined set of dice and optionally display an animation, either locally or globally, before returning the sum of the roll.

How to install

  1. Install Dice Roll package from the community tab
  2. Drag the User Dice script folder onto the User template
  3. (optional) Drag the Dice Rolling Machine template into the game world and define the roll properties on the attached rollDiceOnInteractScript. Interact with the machine to activate the roll.
  4. (optional) Add the rollDiceOnInteractScript onto any entity and define the roll properties. Interact with the entity to activate the roll.

How to use

The User Dice script folder contains the diceUserScript which handles the roll logic and the diceRollWidget which displays the dice animation.

The diceUserScript has several properties to customize the roll animation



The length in seconds of each die roll animation


The length in seconds of the delay between die rolls


The length in seconds of the roll total notification animation


The length in seconds of the delay between the dice rolls and the roll total notification


The default die to roll if no dieTable argument is provided


The number of default dice to roll if no dieTable argument is provided


Pick the color of the dice being rolled because who doesn’t love some variety?

To initiate a roll, call the RollDice() function on the diceUserScript:

userEntity.diceUserScript:RollDice(self:GetEntity(), optionalArgs)

RollDice() accepts several arguments detailed below. Calling RollDice() with only the calledBy entity will roll defaultDieAmount of the defaultDie and display the dice roll animation to the local user. RollDice() sends the total of the roll (including the modifier, if provided) to a function RollResult() on the calling entity.



The entity calling RollDice(). After completing the roll and animation RollDice() sends a function RollResult(rollTotal, user) to the calledBy entity.

calledBy:SendToScripts("RollResult", rollTotal, self:GetEntity())

The calledBy entity will need to implement RollResult() to catch the roll value.


A table defining the amount of each die to roll in the following format

  d4 = 1,
  d6 = 1,
  d8 = 1,
  d12 = 1,
  d20 = 1

A value of 0 or a die left off the table will not be included in the roll. If no diceTable is provided the roll will fall back to the defaultDie and defaultDieAmount values on the diceUserScript.


A boolean value. true will play the dice animation, false will not show the animation and simply send the RollResult() callback. Defaults to true, but some rolls are secret…


A boolean value. true will show the animation to all users, false will only show the animation to the local user. A global roll will include the username of the user who initiated the roll in the dice roll animation label. Defaults to false.


A string displayed alongside the dice roll animation, e.g. “Damage amount”, “Dexterity save”, “Lute playing performance check”. A blank string or nil will not be displayed. Defaults to empty string.


A number to be added to or subtracted from the final dice roll total, because some characters are very strong, and some are very bad at picking locks. Defaults to 0.

The rollDiceOnInteractScript included in the package can be added to an entity and configured to handle a dice roll onInteract with that entity, or used as an example to create custom interactions.

The first several properties are passed to RollDice() and are defined above


The time players must wait between attempting this roll


The number to beat to trigger the onSuccess event. Set to 0 for all rolls to trigger the success event.


If true a roll tied with the difficulty will trigger a success, if false a tie will be a failure


Event called if the roll beats the defined difficulty. Sends the roll total and the user as arguments

self.properties.onRollSuccess:Send(rollTotal, user)


Event called if the roll is less than the defined difficulty. Sends the roll total and the user as arguments

self.properties.onRollFail:Send(rollTotal, user)

A few example implementations can be seen in the showcase here: