Warning, /rolisteam/rolisteam/src/libraries/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)