rerollOnce: Difference between revisions
Jump to navigation
Jump to search
(Adding documentation for rerollOnce() function coming in 1.7) |
No edit summary |
||
| (3 intermediate revisions by 2 users 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= | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
rerollOnce(times, sides, minimum) | rerollOnce(times, sides, minimum) | ||
rerollOnce(times, sides, minimum, chooseHigher) | rerollOnce(times, sides, minimum, chooseHigher) | ||
</ | </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): | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[t: rerollOnce(2, 6, 3)] | [t: rerollOnce(2, 6, 3)] | ||
</ | </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: | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[t: rerollOnce(2, 6, 3, 1)] | [t: rerollOnce(2, 6, 3, 1)] | ||
</ | </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: | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[t: rerollOnce(2, 6, 3)] | [t: rerollOnce(2, 6, 3)] | ||
[getNewRolls()] | [getNewRolls()] | ||
</ | </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 23:59, 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):
May return
[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()]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.