Dice Roll package

Package Guides
1

Dice Roll

Description

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.

image
image1920Ă—1080 90.8 KB

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

image

dieRollDuration

The length in seconds of each die roll animation

dieRollDelay

The length in seconds of the delay between die rolls

notificationDuration

The length in seconds of the roll total notification animation

notificationDelay

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

defaultDie

The default die to roll if no dieTable argument is provided

defaultDieAmount

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

diceColor

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.

Arguments

calledBy

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.

diceTable

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.

displayAnimation

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…

isGlobal

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.

label

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.

modifier

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.

image
image593Ă—655 41 KB

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

attemptsDelay

The time players must wait between attempting this roll

difficulty

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

tiesWin

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

onRollSuccess

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

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

onRollFail

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:
https://launch.crayta.com/play/vwn6cx4f

2 Likes