Support "clamping totals"

[saif-ellafi]

Hello Steve,

Hope you are doing well. Some players are asking whether it would be possible to clamp a dice roll result by its total. This is needed by certain systems where a dice roll can have bonuses but have also a limit, for example rolling 2d6+2 but the maximum is 10.

I could only find out Clamping by die 2d6 C>3 but this will clamp on a die basis.

Would it be possible to have a total result clamping function? my instinct went for (2d6+2) C>10 but this did not work.

Thank you so much as always for this library!

[stevesea]

That feels like this issue exposes a problem I struggle with in the implementation -- it's not always clear to me when to operate on totals vs. individual results.

parens work for grouping things in order to force a certain order of operations. But, sometimes a user will want to treat the outcome as a 'total', other times they'll want to have individual results.

It wouldn't be too hard to introduce a 'CT' or similar syntax to specify clamping on the total.

But, maybe it'd be more general purpose (and give users more control) to to have some sort of wrapping notation that says "Discard individual rolls and operate on the total". Maybe curly braces? {2d6+2}C>10?

With my in-progress PR, I introduce support for comma-separators between different expressions. That could be a workaround:

❯ dart run --enable-asserts dicecli -o pretty '(2d6+2,2d8+2) C>10'
Building package executable... 
Built dicecli:dicecli.
((((2d6) + 2) , ((2d8) + 2)) c> 10) ===> RollSummary(total: 19, results: [9(val), 10(val⌈⌉)], discarded: [5(d6⛔︎), 2(d6⛔︎), 2(val⛔︎), 6(d8⛔︎), 4(d8⛔︎), 2(val⛔︎), 12(val⛔︎⌈⌉)])
  ((((2d6) + 2) , ((2d8) + 2)) c> 10) =clamp=> RollResult(total: 19, results: [9(val), 10(val⌈⌉)], discarded: [5(d6⛔︎), 2(d6⛔︎), 2(val⛔︎), 6(d8⛔︎), 4(d8⛔︎), 2(val⛔︎), 12(val⛔︎⌈⌉)])
      (((2d6) + 2) , ((2d8) + 2)) =comma=> RollResult(total: 21, results: [9(val), 12(val)], discarded: [5(d6⛔︎), 2(d6⛔︎), 2(val⛔︎), 6(d8⛔︎), 4(d8⛔︎), 2(val⛔︎)])
          ((2d6) + 2) =add=> RollResult(total: 9, results: [5(d6), 2(d6), 2(val)])
              (2d6) =rollDice=> RollResult(total: 7, results: [5(d6), 2(d6)])
          ((2d8) + 2) =add=> RollResult(total: 12, results: [6(d8), 4(d8), 2(val)])
              (2d8) =rollDice=> RollResult(total: 10, results: [6(d8), 4(d8)])

2d6+2 is a 9 (5+2+2)
2d8+2 is a 12 (6+4+2)

the comma syntax discards those rolls and changes the roll result to simply [9,12]
and the clamp changes the 12 to a 10 (and discards the 12)

---

(2d6+2,)kh C>10 -- uses the comma syntax, and the empty result is interpreted as '0'. I use 'keep high' to drop the zero. You might want to ensure you drop the zero in case there's other scoring syntax in the expression -- for example, '(2d6+2,) C>10 #f<=1' would always report a single failure due to the zero result.

This solution feels kinda gross. A surprising magic zero appears due to side effects of how I parse the expression. But, it works. 🤷

❯ dart run --enable-asserts dicecli -o pretty '(2d6+2,)kh C>10'
Building package executable... 
Built dicecli:dicecli.
(((((2d6) + 2) , ) kh ) c> 10) ===> RollSummary(total: 10, results: [10(val⌈⌉)], discarded: [0(val⛔︎), 5(d6⛔︎), 4(d6⛔︎), 2(val⛔︎), 11(val⛔︎⌈⌉)])
  (((((2d6) + 2) , ) kh ) c> 10) =clamp=> RollResult(total: 10, results: [10(val⌈⌉)], discarded: [0(val⛔︎), 5(d6⛔︎), 4(d6⛔︎), 2(val⛔︎), 11(val⛔︎⌈⌉)])
      ((((2d6) + 2) , ) kh ) =drop=> RollResult(total: 11, results: [11(val)], discarded: [0(val⛔︎), 5(d6⛔︎), 4(d6⛔︎), 2(val⛔︎)])
          (((2d6) + 2) , ) =comma=> RollResult(total: 11, results: [11(val), 0(val)], discarded: [5(d6⛔︎), 4(d6⛔︎), 2(val⛔︎)])
              ((2d6) + 2) =add=> RollResult(total: 11, results: [5(d6), 4(d6), 2(val)])
                  (2d6) =rollDice=> RollResult(total: 9, results: [5(d6), 4(d6)])

---

((2d6+2)*1) C>10

This one might work in the current release (without my PR).

How multiplication is implemented is that the left-hand and right-hand sides are totaled, then multiplied together. So multiplying by 1 could be a way to operate on the total.
I needed additional parens -- (2d6+2)*1 C>10 would clamp the 1, not the outcome of the multiplication.

output of that with my in-progress PR:

❯ dart run --enable-asserts dicecli -o pretty '((2d6+2)*1) C>10'
Building package executable... 
Built dicecli:dicecli.
((((2d6) + 2) * 1) c> 10) ===> RollSummary(total: 10, results: [10(val⌈⌉)], discarded: [5(d6⛔︎), 5(d6⛔︎), 2(val⛔︎), 1(val⛔︎), 12(val⛔︎⌈⌉)])
  ((((2d6) + 2) * 1) c> 10) =clamp=> RollResult(total: 10, results: [10(val⌈⌉)], discarded: [5(d6⛔︎), 5(d6⛔︎), 2(val⛔︎), 1(val⛔︎), 12(val⛔︎⌈⌉)])
      (((2d6) + 2) * 1) =multiply=> RollResult(total: 12, results: [12(val)], discarded: [5(d6⛔︎), 5(d6⛔︎), 2(val⛔︎), 1(val⛔︎)])
          ((2d6) + 2) =add=> RollResult(total: 12, results: [5(d6), 5(d6), 2(val)])
              (2d6) =rollDice=> RollResult(total: 10, results: [5(d6), 5(d6)])

[saif-ellafi]

Of all ideas, I personally liked CT the best. Is the clearest command that changes how Clamping behaves.
The commas would be syntax-clean, but it does not feel intuitive for this case.
Curly braces look good, but they require getting over the head as of how they're used. Would curly braces enable other functions in other operations? If Clamp remains the only thing, then even more reason to go for the CT, in my opinion.

PS: The multiply hack works!

Cheers

[stevesea]

I went with curly braces -- I think that'd be more generally useful than syntax specific for clamping.

{2d6+2} C>10