Warning, /rolisteam/rolisteam-diceparser/HelpMe.md is written in an unsupported language. File is not indexed.

0001 [![Logo](https://raw.githubusercontent.com/Rolisteam/rolisteam/master/resources/logo/1000-rolisteam.png)](http://www.rolisteam.org)
0002 
0003 # Table of Contents
0004 
0005 * [DiceParser](#diceparser--what-is-it-)
0006 * [Roll a die](#how-to-roll-a-die)
0007 * [List of operator](#list-of-operator)
0008     * [Keep](#keep)
0009     * [Explode and Keep](#explode-and-keep)
0010     * [Keep Lower dice](#keep-lower-dice)
0011     * [Sort](#sort)
0012     * [Count](#count)
0013     * [Reroll](#reroll)
0014     * [Reroll until](#reroll-until)
0015     * [Explode](#explode)
0016     * [Add](#add)
0017     * [Occurence](#occurence)
0018     * [Backward Jump](#backward-jump)
0019     * [Paint](#paint)
0020     * [Merge](#merge)
0021     * [Filter](#filter)
0022     * [if](#if)
0023     * [Group](#group)
0024     * [Spread](#spread)
0025     * [Unique](#unique)
0026     * [All The same](#allsame)
0027     * [Value list](#Value-list)
0028     * [Switch/Case](#Switch-case)
0029     * [Comment (\#)](#comment-)
0030 * [Functions](#Functions)
0031 * [Managing the output](#the-output)
0032     * [Shortcuts](#shortcuts)
0033     * [Final Result](#final-result)
0034     * [Dice Result](#dice-result)
0035 * [Arithmetic](#arithmetic)
0036 * [Arithmetic and Dice](#arithmetic-and-dice)
0037 * [Validator](#validator)
0038     * [Scalar](#scalar)
0039     * [Boolean Condition](#boolean-condition)
0040     * [Operation Condition](#operation-condition)
0041     * [Composite Validator](#composite-validator)
0042 * [List operator](#list-operator)
0043     * [Text](#text-values)
0044     * [Number](#number-values)
0045     * [Change the odd](#change-the-odd)
0046 * [Miscellaneous examples](#examples)
0047 * [Best Practices](#best-practices)
0048 * [Platforms](#roll-dice-on-each-platform)
0049 * [Discord bot](#discord-bot)
0050 * [Bug report](#bug-report-and-new-features)
0051 
0052 # Documentation:
0053 
0054 ## DiceParser: What is it ?
0055 
0056 DiceParser is a software component dedicated to roll dice through simple commands. This software component is available on different platform.  
0057 Such as: discord bot, included in Rolisteam, on twitter etc.
0058 
0059 ## About examples in this documentation
0060 
0061 To make it clear, all examples in this documentation do not show the start up prefix.
0062 Please, remember to add the proper prefix given where you run dice command: Rolisteam, discord, IRC…
0063 If you don't know, try `!`.
0064 The prefix allows the system to identify your command.
0065 
0066 ## How to roll a die
0067 
0068 It is real simple. you have to call:
0069 ```
0070 1d6
0071 ```
0072 
0073 The first number is the count of dice you want to roll. The second number should be die's faces count.
0074 
0075 ### Examples
0076 
0077 ```
0078 1d6
0079 ```
0080 
0081 Roll one six sided die.
0082 
0083 ```
0084 1d10
0085 ```
0086 
0087 Roll one ten sided die.
0088 
0089 ```
0090 5d10
0091 ```
0092 
0093 Roll five ten sided die.
0094 
0095 ```
0096 777d6
0097 ```
0098 
0099 Roll 777 six sided die.
0100 
0101 Thanks of several operations and options, you can tune a bit your rolling command: see [List of operator](#list-of-operator).
0102 
0103 ### Roll dice in Range
0104 
0105 ```
0106 4d[-1..1]
0107 ```
0108 
0109 Rolling 4 dice with value between -1 to 1. (Fudge/Fate system)
0110 
0111 ```
0112 3d[0..9]
0113 ```
0114 Rolling 3 dice with 10 faces starting at 0.
0115 
0116 ```
0117 3d[-20..-9]
0118 ```
0119 Rolling 3 dice, values are between -20 and -9.
0120 
0121 
0122 ### Instruction: Roll two (or more) kinds of dice at once
0123 
0124 Adding (or any arithmetic operations) results from two (or more) kinds of dice is easy:
0125 
0126 ```
0127 1d10+1d8
0128  ```
0129 
0130 To display all results without making any operations with those results. Use `;` to mark several instructions.
0131 
0132 ```
0133 1d10;1d6 # 2 instructions
0134 ```
0135 
0136 or
0137 
0138 ```
0139 5d6;1d10;4d100;3d20  # 4 instructions
0140 ```
0141 
0142 
0143 ### Merge
0144 
0145 It is possible to merge every instruction inside a huge one.
0146 The operator merge is dedicated to that.
0147 It is useful when you need to manage all diceresult as the same result.
0148 
0149 For example, if you need to keep the higher dice between a d6 and d8.
0150 
0151 ```
0152 d6;d8mk1
0153 ```
0154 
0155 More details about k operator in [List of operator](#list-of-operator) .
0156 
0157 ### Computation between instructions
0158 
0159 Thanks to variable system, it is possible to reference the result of a specific instruction.
0160 - To reference the first instruction: `$1`
0161 - To reference the second instruction: `$2`
0162 - To reference the third instruction: `$3`
0163 etc…
0164 the number of instruction is not limited.
0165 
0166 ```
0167 8d10;$1c[>6];$1c1;$2-$3
0168 ```
0169 
0170 * The first instruction rolls 8 (10 sided) dice
0171 * The second instruction counts how many dice are higher than 6.
0172 * The third instruction counts how many dice are equal to 1.
0173 * The fourth instruction subtracts the result of the third instruction from the result of second one.
0174 
0175 
0176 ## List of operators
0177 
0178 * k: Keep
0179 * K: Explode and keep
0180 * kl: Keep lower
0181 * s: Sort
0182 * c: Count
0183 * r: Reroll
0184 * R: Reroll until
0185 * e: Explode
0186 * a: Reroll and add
0187 * @: Backward Jump
0188 * p: Paint dice
0189 * m: Merge
0190 * i: if
0191 * ;: Next instruction
0192 * g: Group
0193 * b: bind
0194 * \#: Comment
0195 
0196 ### Keep
0197 
0198 ```
0199 kX
0200 ```
0201 
0202 The option sorts the resulting die list and selects the X higher dice.
0203 
0204 ### Explode and Keep
0205 
0206 ```
0207 KX
0208 ```
0209 
0210 Dices explode if their value are at the die **maximum**, the option sorts the resulting die list, then it selects the X higher dice.
0211 
0212 #### Examples
0213 
0214 ```
0215 6d10K4
0216 ```
0217 
0218 Roll 6 10-sided dices, each 10 explodes. So the value of exploded dices is greater than 10.
0219 Result: 40 details: 23 [10,10,3],9,5,3,1,1
0220 
0221 Another way to write this command is:
0222 ```
0223 6d10e10k4
0224 ```
0225 This way allows you to change the explode threshold.
0226 
0227 
0228 In order to compute the number you want to keep, the k operator manages variable. You can't directly put the computation behind the k but you can refer to a previous computation.
0229 
0230 ```
0231 # Good
0232 5-3;10d10k$1 
0233 ```
0234 
0235 ```
0236 # BAD
0237 10d10k5-3
0238 ```
0239 
0240 ```
0241 # BAD
0242 10d10k(5-3)
0243 ```
0244 
0245 ### Keep Lower dice
0246 
0247 ```
0248 klX
0249 ```
0250 
0251 The option sorts the resulting die list, then it selects the X lowest dice.
0252 
0253 
0254 ### Sort
0255 
0256 ```
0257 3D10s
0258 ```
0259 
0260 The dice list is sorted in descending order.
0261 
0262 ```
0263 10d6sl
0264 ```
0265 
0266 It rolls 6 dice at 6 faces and then they are sorted in ascending order
0267 
0268 ### Count
0269 
0270 ```
0271 3D10c[Validator]
0272 ```
0273 
0274 Count how many dice respect the condition and display the number (See Validator for more details about syntax)
0275 
0276 ### Reroll
0277 
0278 ```
0279 3D10r[Validator]
0280 ```
0281 
0282 Reroll the die if the previous value fits the validator (See Validator for more details about syntax).
0283 
0284 ### Reroll until
0285 
0286 ```
0287 3D10R[Validator]
0288 ```
0289 
0290 Works like "Reroll", but continue to roll the dice until the condition is false.
0291 
0292 ### Explode
0293 
0294 ```
0295 3D10e[Validator]
0296 ```
0297 
0298 Explode while the value fits the Validator (See Validator for more details about syntax).
0299 
0300 ```
0301 3D10e(3)[Validator]
0302 ```
0303 
0304 Explode node can have a limit of how many times the die will explode.
0305 
0306 ```
0307 3D10e(1d10)[Validator]
0308 ```
0309 
0310 The limit is a expression.
0311 
0312 ### Examples
0313 
0314 ```
0315 3D10e10
0316 ```
0317 While dice value is equal to 10, the dice is rolled again and its result is added to the previous dice value.
0318 > Result: **49 details: 8, 12 [10,2], 29 [10,10,9]**
0319 
0320 ```
0321 3D10e[>8]
0322 ```
0323 While the dice value is greater than 8, the dice is rolled again and its result is added to the previous dice value.
0324 > Result: **35 details: 3, 27 [9,10,8], 5**
0325 
0326 ### Add
0327 
0328 ```
0329 3D10a[Validator]
0330 ```
0331 
0332 Reroll the die if its value fits the Validator and add the new value to the previous one. It does that only once.
0333 
0334 ### Occurrence
0335 
0336 ```
0337 10d10o
0338 ```
0339 
0340 Count and sort occurrences of each value.
0341 Result: `3x1,1x2,3x4,2x9,1x10 - [1,1,1,2,4,4,4,9,9,10]`
0342 
0343 ```
0344 10d10o2,7
0345 ```
0346 
0347 Count and sort occurrence when they occur at least 2 times, the value is 7 or more.
0348 Result: `2x8 - [1,2,3,5,6,7,8,8,9,10]`
0349 
0350 ```
0351 10d10o2[<6]
0352 ```
0353 
0354 Count and sort occurrence when they occur at least 2 times, the value should respect the validator (here less than 6).
0355 Result: `2x3,2x5 - [3,3,5,5,6,6,6,7,7,8]`
0356 
0357 
0358 #### Errors
0359 
0360 ```
0361 10d10o[<6]
0362 ```
0363 
0364 This command is triggering a warning. As occurrence operator can have 0 or 2 parameters. But only one validator is unsupported yet.
0365 
0366 
0367 
0368 ### Backward Jump
0369 
0370 This operator is dedicated to apply its next operator to the second to last result.
0371 For example:
0372 
0373 ```
0374 8D10c[>=7]+@c[=10]
0375 ```
0376 
0377 c[=10] in this command is counting the number of 10 in the result of 8D10, if you remove the @, it will try to count the number of 10 in the result of c[>=7]. The result of c[>=7] is a scalar number (1 or 2 ... (max value 8)); it is not dice list.
0378 
0379 ### Paint
0380 
0381 ```
0382 8D10p[1:blue]
0383 ```
0384 
0385 Paint the first die in the list in blue
0386 
0387 ```
0388 8d10p[2:blue]
0389 ```
0390 
0391 Paint the two first dice in the list in blue.
0392 
0393 https://gist.github.com/obiwankennedy/62101383d411e55d205e44df78aa5299
0394 
0395 
0396 The amount of color is depending on the client application of DiceParser.
0397 - With Rolisteam, you may set any Qt color's name or set the Hexcode of your color: #ff28AC.
0398 - The cli application supports few colors: black, white, blue, red, black, green, yellow.
0399 
0400 
0401 ### Filter
0402 
0403 Filter operator allows you to ignore some dice results given a validator.
0404 
0405 ```
0406 4d6f[!=6]
0407 ```
0408 
0409 Result:
0410 > total: 11 - details[5 2 6 4]
0411 
0412 the 6 is ignored.
0413 
0414 ### Merge
0415 
0416 Merge operator is used for gathering several dice rolls from different die type into one dice result and then you may apply any kind of operator.
0417 
0418 ```
0419 1d6;1d8mk1
0420 ```
0421 
0422 This command merges together the result from the d6 and the d8. Then, it applied the k operator on both result to keep the best.
0423 Be careful, this operator merges the instruction list. Instruction reference (such as $1 etc..) won't work after merge operator.
0424 
0425 ### Spead
0426 
0427 It makes exploded dice as new dice.
0428 The operator is trigged by *y*.
0429 
0430 ```
0431 4d6e6y6k3
0432 ```
0433 
0434 First Result: `10 [6, 4], 3, 3, 2`  
0435 Result after spead: `6, 4, 3, 2`  
0436 Final result: `6+4+3 = 13`  
0437 
0438 ### All the same
0439 
0440 This operator is temporary. It is dedicated to answer issue about Tunnels and Trolls system. It is why the marker operator is `t`.
0441 Dice explode when all dice has the same value.
0442 
0443 ```
0444 2d6t
0445 ```
0446 
0447 > # Explode twice because 2,1
0448 Result: 12 - details:[2d6t (5 [2,1,2] 7 [2,1,4])]
0449 
0450 > # Nothing happened
0451 Result: 10 - details:[2d6t (4 6)]
0452 
0453 
0454 ### Unique
0455 
0456 It makes exploded dice as new dice.
0457 
0458 ```
0459 4d6e6u
0460 ```
0461 Result: 6 4 3 3 2
0462 Final result: 6+4+3 = 13
0463 
0464 ### Value list
0465 
0466 Build your own value list and apply any dice operator.
0467 
0468 ```
0469 [10,25,43,8]k1
0470 ```
0471 
0472 Get a higher score from several instructions:
0473 
0474 ```
0475 1d10;2d6+9;1d20;[$1,$2,$3,$4]k1
0476 ```
0477 
0478 Each value is transformed into a die.
0479 
0480 ### Bind
0481 
0482 Bind works exactly as merge but it keeps instruction array untouched.
0483 
0484 ```
0485 !2d8;2d12b;$2k2;$2k2kl1;"your total is $3 with lowest: $4"
0486 ```
0487 
0488 Roll two 8-sided dice and two 12-sided dice then bind their results. using this final result, we keep the 2 higher dice and then we isolate the lowest of the two highest.
0489 At the end, we display the result inside a sentence.
0490 
0491 ### if
0492 
0493 If operator means to allow you to do one thing if some conditions are true.
0494 The if operator has 2 mandatory parameters:
0495 * The condition (see validator)
0496 * the instruction to do when it is true.
0497 
0498 There are also 2 optional parameters
0499 * the compare method
0500 * the instruction to do when it is false.
0501 
0502 > i*[]{}{}
0503 
0504 * \*: the compare method
0505 * []: the validator
0506 * {}: the true instruction
0507 * {}: the false instruction
0508 
0509 #### Compare method
0510 
0511 There are 4 different methods.
0512 * **On Each**: the condition is tested on each die from the previous part of the command. \[Default method\]
0513 * **On Each value** `?`: the condition is tested on each final value of die from the previous part of the command.
0514 * **All Of Them** `*`: All dice must fit the condition to trigger the true instruction. If all dice do not fit the condition the false instruction is run.
0515 * **One Of Them** `.`: at least one die must fit the condition to trigger the true instruction. If no dices fit the condition the false instruction is run.
0516 * **On Scalar** `:`: the condition is evaluated on the scalar result of the dice roll.
0517 
0518 #### Examples:
0519 
0520 ```
0521 1d6i[<4]{3}
0522 ```
0523 
0524 If the value of the die is less than 4, the die value is 3. (So 1, 2 , 3 become 3).
0525 
0526 ```
0527 4d6e6i[=4]{-4}
0528 ```
0529 
0530 If die has 4 as value, it removes it. \[Kuro System\]
0531 
0532 ```
0533 4d6i.[=6]{+1d6}
0534 ```
0535 
0536 if at least one die is equal to 6, then roll another d6 and add it to the result.
0537 
0538 ```
0539 4d6i*[=6]{+1d6}
0540 ```
0541 
0542 if all dice are equal to 6, then roll another d6 and add it to the result.
0543 
0544 ```
0545 2d10i:[>15]{"Success"}{"Fail"}
0546 ```
0547 
0548 if the sum of two dice is greater than 15, It displays "Success", otherwise it displays "Fail".
0549 
0550 ```
0551 2d10i:[>15]{"Success %1 "}{"Fail %1"}
0552 ```
0553 
0554 Same as above, but the final result is displayed beside Success or Fail.
0555 
0556 ```
0557  2d10i:[>15]{"Success %1 [%2]"}{"Fail %1 [%2]"}
0558 ```
0559 
0560 Same as above, but the result of each die is displayed inside square brackets.
0561 
0562 
0563 ### Group
0564 
0565 Group dices, then count the number of group (7th sea system).
0566 
0567 #### Complex output
0568 
0569 Group operator can take a parameter to active the complex output.
0570 This output will show each group and any left aside values if any.
0571 To active this output, it is required to add a `s` just after the `g`. See the example below:
0572 
0573 #### Example
0574 
0575 ```
0576 3d20g10
0577 ```
0578 
0579 This will roll 3 dices and then try to group them to make groups of 10. If you get `9 9 2`, you can only create one group whose value is more or equal to ten (`{9,2}`, the second `9` being "wasted").
0580 
0581 The `g` operator is allowed to re-order dices to create groups. When rolling `4d20g10`, if you get `7 4 3 6`, the result will be `2` (`{7,3}` and `{6,4}`).
0582 
0583 ```
0584 5d10gs10
0585 ```
0586 
0587 Then, the final output will be:
0588 ```
0589 2 ({7,3}, {6,4} - [2])
0590 ```
0591 
0592 `{7,3}` and `{6,4}` are group, and `[2]` is left aside.
0593 
0594 ### Switch case (S)
0595 
0596 Switch case operator allows you to transform number value into text.
0597 Its goal is to make that easier than using several if. As you may expect, its syntax is close to if.
0598 
0599 ```
0600 1d100S[<50]{"Low"}[>=50]{"Low"}
0601 ```
0602 
0603 You may also add a default option
0604 
0605 ```
0606 1d4S[=1]{"Low"}[=2]{"small"}[=3]{"medium"}{"big"}
0607 ```
0608 
0609 Exclusive mode:
0610 This mode is enabled when a `^` is following the `S`.
0611 ```
0612 1d100S^[<25]{"Low"}[<50]{"small"}[<75]{"medium"}[>=75]{"big"}
0613 ```
0614 
0615 ### Comment (\#)
0616 
0617 ```
0618 2D6 # Sword attack
0619 ```
0620 
0621 Display "Sword attack" and the result of the two dice.
0622 DiceParser ignores everything after the \#. The whole part is treated as one comment.
0623 So DiceParser can answer the question:
0624 
0625 ```
0626 1L[yes,no] # Am I evil ?
0627 ```
0628 
0629 > Am I evil ?
0630 yes
0631 
0632 
0633 ## Functions
0634 
0635 DiceParser provides function to deal with instructions.
0636 Some functions will come soon (e.g: max, min). It will allow to manage several commands at once.
0637 
0638 ### Repeat
0639 
0640 > repeat(1d10,5)
0641 
0642 Output:
0643 ```
0644 2 - Details [2]
0645 8 - Details [8]
0646 3 - Details [3]
0647 1 - Details [1]
0648 10 - Details [10]
0649 ```
0650 
0651 Attention! Be careful, `repeat` works badly with multiple instruction commands
0652 
0653 ## The output
0654 
0655 DiceParser provides features to let you control the command output.
0656 The final instruction must be a string instruction.
0657 String instruction starts with `"` and ends with `"`.
0658 
0659 Rolling:
0660 > `"result"`
0661 
0662 Output:
0663 `result`
0664 
0665 You can set string instruction inside if operator:
0666 
0667 > 1d6i:[>3]{"Success"}{"Fail"}
0668 
0669 Output:
0670 `Success` or `Fail`
0671 
0672 
0673 It offers a quick answer but sometimes you need to see the rolled values.
0674 DiceParser can replace some special tags in order to see values, computation result and whatever.
0675 
0676 ### Shortcuts
0677 
0678 There are 3 shortcut tags.
0679 
0680 * `%1`: last scalar result from each instruction.
0681 * `%2`: all dice results.
0682 * `%3`: last scalar result from the last instruction.
0683 
0684 The default output is `%1 details[%2]`.
0685 So, it shows the last scalar result of each instruction and dice result.
0686 
0687 `%1` and `%3` are equivalent when there is only one instruction (no \;).
0688 
0689 They are really useful but if you have many instructions that can become a bit messy.
0690 
0691 ### Final result
0692 
0693 It is also possible to set reference to the final value of specific instruction (the result should be a number or a string)
0694 
0695 - To reference the first instruction: `$1`
0696 - To reference the second instruction: `$2`
0697 - To reference the third instruction: `$3`
0698 
0699 There is no limit on instruction number.
0700 
0701 
0702 #### String as final result
0703 
0704 You can reference the sub result of a string result by adding `[x]` after the instruction reference.
0705 Let see an example, it will be easier to understand.
0706 
0707 ```
0708 2Lu[cats,dogs,rats,rabbits,bats,squirrels]
0709 ```
0710 
0711 The default result looks like this:
0712 
0713 > cats,bats
0714 
0715 Now we want to make a sentence with this text:
0716 
0717 ```
0718 2Lu[cats,dogs,rats,rabbits,bats,squirrels];"You love $1 and you are afraid of $1"
0719 ```
0720 
0721 As $1 refers to "**cats,bats**", it will show:
0722 
0723 > You love cats,bats and you are afraid of cats,bats
0724 
0725 
0726 So, it is not really useful. In order to make it a bit better, we must add some sub-indexes.
0727 
0728 ```
0729 2Lu[cats,dogs,rats,rabbits,bats,squirrels];"You love $1[0] and you are afraid of $1[1]"
0730 ```
0731 
0732 then we have a proper output.
0733 
0734 > You love cats and you are afraid of bats
0735 
0736 
0737 #### Let see some examples:
0738 
0739 ```
0740 8d10;$1c[>6];$1c1;$2-$3
0741 ```
0742 
0743 The default output displays: `45,4,0,4 details[4,3,10,7,2,2,7,10]`
0744 
0745 ```
0746 8d10;$1c[>6];$1c1;$2-$3i:[>0]{"%3 Success[%2]"}{i:[<0]{"Critical fail %3 [%2]"}{"Fail %3 [%2]"}}
0747 ```
0748 
0749 Here, some output example:
0750 * `4 Success[4,3,10,7,2,2,7,10]`
0751 * `Fail 0 [10,3,1,1,2,2,7,5]` (2 success - 2 fails = 0)
0752 * `Critical fail -2 [1,3,1,1,2,2,7,5]` (1 success - 3 fails = -2)
0753 
0754 In this example, the critical fail happens when there are more fails than success.
0755 In the next example, the critical fail happens when there was no success and a least one fail.
0756 
0757 ```
0758 8d10;$1c[>6];$1c1;$2-$3;$4i:[=0]{"Fail $4 [%2]"}{$4i:[>0]{"$2 Success[%2]"}{$2i:[=0]{"Critical Fail $4 [%2]"}{"Fail $4 [%2]"}}}
0759 ```
0760 
0761 Another example, to show how to combine string and dice result.
0762 
0763 ```
0764 1d6+1;1L[gold coins,spell scrolls,weapons];"You found $1 $2"
0765 ```
0766 
0767 > You found 5 gold coins
0768 
0769 
0770 
0771 ### Dice Result
0772 
0773 DiceParser provides tags to display dice result (and each rolled values from a specific instruction).
0774 
0775 To show dice values from a specific instruction, just add `@` followed by the instruction's number (e.g: `@1`)
0776 
0777 ```
0778 2d6;3d8;"Result $2 - d8:[@2] - d6:[@1]"
0779 ```
0780 
0781 The output:
0782 
0783 > Result 15 - d8:[7,4,4] - d6:[3,6]`
0784 
0785 
0786 ### New line
0787 
0788 You may need to display your result on several lines. It is really easy:
0789 
0790 ```
0791 1d100;1d10;"Attack: $1\nDamage: $2"
0792 ```
0793 
0794 This command will display:
0795 
0796 > Attack: 31
0797 Damage: 7
0798 
0799 ## Arithmetic
0800 
0801 Rolisteam Dice Parser is able to compute primary arithmetic operation such as: +, -, /, * and it also manages those operator priority and it can also manage parenthesis.
0802 
0803 ```
0804 8+8+8
0805 ```
0806 
0807 > Result: 24
0808 
0809 ```
0810 24-4
0811 ```
0812 
0813 > Result: 20
0814 
0815 ```
0816 (3+4)*2
0817 ```
0818 
0819 > Result: 14
0820 
0821 ```
0822 7/2
0823 ```
0824 
0825 > Result: 3.5
0826 
0827 ```
0828 (3+2D6)D10
0829 ```
0830 
0831 > Roll 2 dice and add 3 to the sum of those dice. Then the result is used for rolling dice.
0832 
0833 ```
0834 15|6
0835 ```
0836 
0837 > Result: 2
0838 
0839 ```
0840 15/6
0841 ```
0842 
0843 > Result: 2.5
0844 
0845 ## Arithmetic and Dice
0846 
0847 It is possible to use arithmetic operation on dice. Please pay attention that the default operation to translate a
0848 dice list to scalar is the sum. So if you roll `3d6`, the result will be a list with 3 values {2, 5 ,1}. Now, we
0849 change a bit the command `3d6+4`: It is resolved like this: {2, 5 ,1} = 8; 8+4 = 12. The final result is 12.
0850 
0851 ```
0852 3d6+4
0853 ```
0854 
0855 > Roll 3 dice; sum the result; and add 4
0856 
0857 ```
0858 10D10-2
0859 ```
0860 
0861 > Roll 10 dice; sum the result; and then subtract 2
0862 
0863 ```
0864 87-1D20
0865 ```
0866 
0867 > Subtract the result of 1 die to 87
0868 
0869 ```
0870 (6-4)D10
0871 ```
0872 
0873 > Subtract 4 to 6 and then roll two dice.
0874 
0875 ```
0876 1D10/2
0877 ```
0878 
0879 > Divide by 2 the result of 1 die.
0880 
0881 ```
0882 (2+2)**2
0883 ```
0884 > Result: 16
0885 
0886 ```
0887 1d10**2
0888 ```
0889 
0890 > Roll 1d10 then multiply the result by itself.
0891 
0892 ```
0893 15|2
0894 ```
0895 > Integer division of 15 by 2. Result: 7
0896 
0897 ```
0898 15/2
0899 ```
0900 > Division of 15 by 2. Result: 7.5
0901 
0902 ## Validator
0903 
0904 There are five kinds of Validator:
0905 
0906 * Scalar
0907 * Range
0908 * Boolean expression
0909 * Operation Condition
0910 * Composite
0911 
0912 Any operator which requires validator (such as `a,r,e,c`) can use those three kinds.
0913 
0914 ### Scalar
0915 
0916 The scalar value sets the validator on equality between the dice value and the validator
0917 
0918 ```
0919 4d10e10
0920 ```
0921 
0922 This command means: roll 4 dice and they explode on 10.
0923 
0924 ### Range
0925 
0926 The range is defined as two bounds. You have to use square brackets and the two bounds are separated by `..`.
0927 
0928 ```
0929 4d10c[8..10]
0930 1d[-1..8]
0931 ```
0932 
0933 ### Boolean Condition
0934 
0935 The command counts how many dice have values between >=8 and <=10.
0936 
0937 ```
0938 4d10c[>7]
0939 ```
0940 
0941 The command counts how many dice are aboved 7.
0942 
0943 #### Compare Operator
0944 
0945 The Rolisteam Dice Parser allows you to use several logic operators:
0946 * Equal: `=`
0947 * Greater or equal:  `>=`
0948 * Lesser or equal: `<=`
0949 * Lesser: `<`
0950 * Greater: `>`
0951 * Different: `!=`
0952 
0953 
0954 #### Compare methods
0955 
0956 As the `if` operator, you can specify the compare method.
0957 
0958 * **On Each**: the condition is tested on each die from the previous part of the command. \[Default method\]
0959 * **On Each value** `?`: the condition is tested on each final value of die from the previous part of the command.
0960 * **All Of Them** `*`: All dice must fit the condition to trigger the true instruction. If all dice do not fit the condition the false instruction is run.
0961 * **One Of Them** `.`: at least one die must fit the condition to trigger the true instruction. If no dices fit the condition the false instruction is run.
0962 * **On Scalar** `:`: the condition is evaluated on the scalar result of the dice roll.
0963 
0964 ##### Examples:
0965 
0966 ```
0967 1L[7,8,9]c[>6]
0968 ```
0969 
0970 This command will return 0 because, no die has been rolled, so the result of `1L[7,8,9]` is a final value.
0971 
0972 ```
0973 1L[7,8,9]c[?>6]
0974 ```
0975 
0976 Output: 1
0977 
0978 ```
0979 5d6e6sc[>=8]
0980 ```
0981 Output:
0982 
0983 > 0
0984 details: [8 [6,2] 2 1 1 1]
0985 
0986 
0987 ```
0988 5d6e6f[?>=16]
0989 ```
0990 
0991 Output:
0992 As the final sum is equal to 11. It's less than 16 so the filter is filtering everything.
0993 
0994 > 0
0995 details: [2 4 1 3 1]
0996 
0997 
0998 The final sum is higher than 16 so the whole result is accepted by the filter operator.
0999 
1000 > 23
1001 details: [3 6 3 5 6]
1002 
1003 
1004 ```
1005 5d6e6sc[:>=8]
1006 ```
1007 
1008 Output:
1009 > 1
1010 details: [8 [6,2] 2 1 1 1]
1011 
1012 ### Operation Condition
1013 
1014 This validator offers modulo as operation and a Boolean Condition to validate the value:
1015 
1016 ```
1017 4d10c[%2=0]
1018 ```
1019 
1020 Count how many even numbers have been rolled.
1021 
1022 
1023 ```
1024 4d10c[%2=1]
1025 ```
1026 
1027 Count how many odd numbers have been rolled.
1028 
1029 [modulo](https://en.wikipedia.org/wiki/Modulo_operation)
1030 
1031 ### Composite Validator
1032 
1033 Validator can be the result of several validator.
1034 
1035 ```
1036 4d10c[>4&%2=0]
1037 ```
1038 
1039 Count all dice greater than 4 and even [6,8,10].
1040 
1041 Composite Validator supports 3 logical operations:
1042 
1043 * AND : `&`
1044 * OR : `|`
1045 * Exclusive OR : `^`
1046 
1047 Composite Validator accepts as many validator as you need:
1048 
1049 ```
1050 !9d100c[=1|=3|=5|=7|=11|=13|=17|=19|=23|=29|=31|=37|=41|=43|=47|=53|=59|=61|=67|=71|=73|=79|=83|=89|=97]
1051 ```
1052 
1053 ## List operator
1054 
1055 * [Number](#number-values)
1056 * [Change the odd](#change-the-odd)
1057 
1058 ### Text values
1059 
1060 The L (or l) operator (meaning list) provides a way to pick up value from list.
1061 
1062 ```
1063 1L[sword,bow,knife,gun,shotgun]
1064 ```
1065 
1066 With comment
1067 
1068 ```
1069 1L[yes,no] # Am I evil ?
1070 ```
1071 
1072 > Am I evil ?
1073 yes
1074 
1075 ### Getting unique values
1076 
1077 The `u` parameter asks for unique values.
1078 
1079 ```
1080 2Lu[yes,no]
1081 ```
1082 
1083 This command can return `yes,no` or `no,yes`. The u make it impossible to return `yes,yes` or `no,no`
1084 
1085 ### Remove comma between values
1086 
1087 By default, results are displayed with a comma between each values. You can remove the comma with the parameter `n`
1088 
1089 ```
1090 2Ln[to,kyo]
1091 ```
1092 
1093 This command can return `toto`, `kyokyo`, `tokyo`, `kyoto`.
1094 
1095 ### Unique with no comma
1096 
1097 ```
1098 2Lun[to,kyo]
1099 ```
1100 
1101 or 
1102 
1103 ```
1104 2Lnu[to,kyo]
1105 ```
1106 
1107 Those commands can return `tokyo` or `kyoto`.
1108 
1109 ### Number values
1110 
1111 If the value is a number, it is treated as well and you can do computation on it or use any operator.
1112 
1113 ```
1114 1L[-1,0,1,2,3,4]+7
1115 ```
1116 
1117 ### Text and Number at the same time
1118 
1119 It is not recommended to use text and number in the same list operator.
1120 Currently, the behaviour changes given the result. If the chosen value is a number, you can do other computation, but otherwise, the result is displayed directly without any control on it.
1121 
1122 The behaviour will change in future release to base the decision on the data set. If the data set only contains numbers, then computation is possible. Otherwise, it will be treated as string result.
1123 
1124 
1125 ### Change the odd
1126 
1127 There are 2 main ways to control the odd on the pickup in the list.
1128 
1129 #### The ant method
1130 
1131 ```
1132 1L[2,2,3,3,3,3,4,4,4,5]
1133 ```
1134 
1135 or
1136 
1137 ```
1138 1L[arm,arm,leg,leg,chest,chest,chest,head]
1139 ```
1140 
1141 #### The lazy method
1142 
1143 By range:
1144 
1145 ```
1146 1L[1,2,3,4,5,6[6..10]]
1147 ```
1148 
1149 
1150 By weight:
1151 
1152 ```
1153 1L[1[2],2[2],3[4]]
1154 ```
1155 
1156 Several results:
1157 
1158 ```
1159 1
1160 3
1161 1
1162 2
1163 2
1164 1
1165 2
1166 3
1167 1
1168 2
1169 3
1170 2
1171 2
1172 3
1173 ```
1174 
1175 ## Examples
1176 
1177 ```
1178 3D100
1179 ```
1180 
1181 Roll 3 dice with 100 faces
1182 
1183 ```
1184 10D10e[=10]s
1185 ```
1186 
1187 Roll 10 dice with 10 faces, 10 explodes, and sort the result.
1188 
1189 ```
1190 100291D66666666s
1191 ```
1192 
1193 Roll 100291 dice with 66666666666 faces and sort result
1194 
1195 ```
1196 15D10c[>7]
1197 ```
1198 
1199 roll 15 dice with 10 faces and it counts number of dice which are above 7
1200 
1201 ```
1202 1D8+2D6+7
1203 ```
1204 
1205 roll 1 die with 8 faces and add the result to 2 dice with 6 faces and add 7.
1206 
1207 ```
1208 D25
1209 ```
1210 
1211 roll 1 die with 25 faces
1212 
1213 ```
1214 88-1D20
1215 ```
1216 
1217 88 minus the value of 1 die of 20 faces
1218 
1219 ```
1220 8+8+8
1221 ```
1222 
1223 compute: 24
1224 
1225 ```
1226 1L[sword,bow,knife,gun,shotgun]
1227 ```
1228 
1229 One of this word will be picked.
1230 
1231 ```
1232 8D10c[Validator1]-@c[validator2]
1233 ```
1234 
1235 Roll 8 dice with 10 faces then it counts how many dice respect the condition Validator1 and substract the number of dice which respect the validator2 and display the number (See Validator for more details about syntax)
1236 
1237 ```
1238 8D10c[>=6]-@c[=1]
1239 ```
1240 
1241 Old World in darkness system.
1242 
1243 ```
1244 8D10c[>=7]+@c[=10]
1245 ```
1246 
1247 Exalted 2nd edition system.
1248 
1249 
1250 ## Best Practices
1251 
1252 As DiceParser provides more and more features, you may find several ways to do the same thing. We want here to explain the difference between those several approaches. Then you will be able to use the right one.
1253 
1254 
1255 ### Roll several kind of dice and sum them
1256 
1257 **Bad**
1258 ```
1259 2d8;2d10m
1260 ```
1261 
1262 **Good**
1263 ```
1264 2d8+2d10
1265 ```
1266 
1267 The merge operator is useful when you want to use dice operator on all rolled dice.
1268 
1269 **Bad**
1270 ```
1271 1d20K1+1d10K1
1272 ```
1273 
1274 **Good**
1275 ```
1276 1d20+1d10
1277 ```
1278 
1279 The k operator to keep as many dice as you roll is pretty useless because it is the default behaviour.
1280 
1281 ## Platform specific documentation
1282 
1283 ### Roll dice on each platform
1284 
1285 | platform | start character(s)  | more information |
1286 |---|---|--- |
1287 | Rolisteam |```!```| [Documentation](http://wiki.rolisteam.org/index.php/En:Dice) |
1288 | Discord  |```!```| To install DiceParser on your server [http://www.rolisteam.org/discord.html](http://www.rolisteam.org/discord.html)  |
1289 | Twitter  | ```#roll```  | Twit any message starting with #roll following by dice command (e.g: ```#roll 2d6```) |
1290 | dice   | nothing | dice is a command line application to roll dice: ```dice "2d6"``` |
1291 
1292 
1293 ### Known Limitations
1294 
1295 | platform | descriptions |
1296 |---|---|
1297 | Rolisteam | no support for comments yet. Rolisteam is a big software. You may not have all the most recent feature from diceparser. |
1298 | Discord  | If the command takes too much time. It is canceled |
1299 | Twitter  | Result should be short. No aliases |
1300 | dice     |  |
1301 
1302 # Discord Bot
1303 
1304 Documentation of the bot is now inline with the bot.
1305 
1306 ## Prefix documentation
1307 
1308 > !help prefix
1309 
1310 ## Macro documentation
1311 
1312 > !help macro
1313 
1314 [Examples and More information](https://invent.kde.org/rolisteam/rolisteam-diceparser/-/blob/master/community_macro.md)
1315 
1316 ## Alias documentation
1317 
1318 > !help alias
1319 
1320 ## Conf documentation
1321 
1322 > !help conf
1323 
1324 ## Difference between Aliases and Macros
1325 
1326 Aliases is the feature of the bot, macro is a feature of the dice system behind the bot.
1327 Aliases is a way to run several commands at once.
1328 
1329 Macro is a way to run huge command by typing few letters. Macros may have parameters (such as dice number, threshold for success or whatever)
1330 
1331 # Bug report and new features
1332 
1333 Please fulfill a ticket in our [Bug tracker](https://invent.kde.org/kde/rolisteam-diceparser/issues/new) system.
1334 Or contact us on [discord](https://discordapp.com/invite/MrMrQwX) or any [other ways](http://www.rolisteam.org/contact.html)