rerollOnce: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
m (Conversion script moved page rerollOnce to RerollOnce without leaving a redirect: Converting page title to first-letter uppercase)
No edit summary
 
(One intermediate revision by one other user not shown)
Line 5: Line 5:
Generates random numbers to emulate dice rolls; returns a dice roll similar to {{func|roll}} with the difference being that each die rolled that is lower than the {{code|minimum}} parameter is rerolled and replaced by the new value.  An option can allow the higher of the two values to be chosen instead.  Differs from {{func|reroll}} in that new values lower than {{code|minimum}} are allowed, and are not rerolled indefinitely.
Generates random numbers to emulate dice rolls; returns a dice roll similar to {{func|roll}} with the difference being that each die rolled that is lower than the {{code|minimum}} parameter is rerolled and replaced by the new value.  An option can allow the higher of the two values to be chosen instead.  Differs from {{func|reroll}} in that new values lower than {{code|minimum}} are allowed, and are not rerolled indefinitely.
|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
rerollOnce(times, sides, minimum)
rerollOnce(times, sides, minimum)
rerollOnce(times, sides, minimum, chooseHigher)
rerollOnce(times, sides, minimum, chooseHigher)
</source>
</syntaxhighlight>
'''Parameters'''
'''Parameters'''
{{param|times|The number of times to roll the dice.}}
{{param|times|The number of times to roll the dice.}}
Line 17: Line 17:
|examples=
|examples=
Roll two six-sided dice, rerolling any dice rolled lower than 3 (and keeping the new values):
Roll two six-sided dice, rerolling any dice rolled lower than 3 (and keeping the new values):
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[t: rerollOnce(2, 6, 3)]
[t: rerollOnce(2, 6, 3)]
</source>
</syntaxhighlight>


Roll two six-sided dice, rerolling any dice rolled lower than 3, and choose the higher of the two values:
Roll two six-sided dice, rerolling any dice rolled lower than 3, and choose the higher of the two values:
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[t: rerollOnce(2, 6, 3, 1)]
[t: rerollOnce(2, 6, 3, 1)]
</source>
</syntaxhighlight>


Note that if multiple dice are rolled ({{code|times > 1}}), each die is rolled in sequence, and immediately rerolled if necessary.  For example:
Note that if multiple dice are rolled ({{code|times > 1}}), each die is rolled in sequence, and immediately rerolled if necessary.  For example:
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[t: rerollOnce(2, 6, 3)]
[t: rerollOnce(2, 6, 3)]
[getNewRolls()]
[getNewRolls()]
</source>
</syntaxhighlight>
May return {{code|5 [2, 1, 2, 4]}} - the first die produced a 2, which was rerolled and replaced by a 1.  The second die also produced a 2, and was rerolled and replaced by a 4.  The total returned is then {{code|5}}.  If {{code|chooseHigher}} was set to true, the first 2 would not have been replaced by a lower value, so the total returned would instead have been {{code|6}} for the same sequence of rolls.
May return {{code|5 [2, 1, 2, 4]}} - the first die produced a 2, which was rerolled and replaced by a 1.  The second die also produced a 2, and was rerolled and replaced by a 4.  The total returned is then {{code|5}}.  If {{code|chooseHigher}} was set to true, the first 2 would not have been replaced by a lower value, so the total returned would instead have been {{code|6}} for the same sequence of rolls.
|also=
|also=

Latest revision as of 22:11, 14 March 2023

rerollOnce() Function

Introduced in version 1.7
Generates random numbers to emulate dice rolls; returns a dice roll similar to roll() with the difference being that each die rolled that is lower than the minimum parameter is rerolled and replaced by the new value. An option can allow the higher of the two values to be chosen instead. Differs from reroll() in that new values lower than minimum are allowed, and are not rerolled indefinitely.

Usage

rerollOnce(times, sides, minimum)
rerollOnce(times, sides, minimum, chooseHigher)

Parameters

  • times - The number of times to roll the dice.
  • sides - The number of sides the dice possess.
  • minimum - The lowest number a dice rolled can return without being rerolled.
  • chooseHigher - Whether the original die may be preserved if it was higher than the rerolled value. Defaults to false.

Examples

Roll two six-sided dice, rerolling any dice rolled lower than 3 (and keeping the new values):
[t: rerollOnce(2, 6, 3)]

Roll two six-sided dice, rerolling any dice rolled lower than 3, and choose the higher of the two values:

[t: rerollOnce(2, 6, 3, 1)]

Note that if multiple dice are rolled (times > 1), each die is rolled in sequence, and immediately rerolled if necessary. For example:

[t: rerollOnce(2, 6, 3)]
[getNewRolls()]
May return 5 [2, 1, 2, 4] - the first die produced a 2, which was rerolled and replaced by a 1. The second die also produced a 2, and was rerolled and replaced by a 4. The total returned is then 5. If chooseHigher was set to true, the first 2 would not have been replaced by a lower value, so the total returned would instead have been 6 for the same sequence of rolls.

See Also

For another method of rolling dice, see Dice Expressions.