Why every die comes back

Most dice libraries answer 4d6kh3 with a number. Rollful answers with four dice, a note of which three counted, and the number. That is a deliberate cost, and this page is the argument for paying it.

A total is a claim

14 is not a roll. It is the conclusion of a roll, with the roll removed.

A player who sees 14 has to take it on trust. A developer debugging a roll that came out wrong has nothing to inspect. And an interface built on totals cannot show anything except totals, which is why so many digital dice rollers feel flatter than the physical kind: the interest is in watching the dice land, and a total has already skipped to the end.

Returning [5, 4, 5, 3] alongside 14 costs a few dozen bytes and removes all three problems at once.

Which is why kept is not enough

The obvious way to report a keep rule is to send back the values that counted. kept does exactly that, and it is the field most people reach for first.

It loses information. Roll 6d6kh3 and get [5, 4, 5, 3, 6, 1]. The values that counted are [6, 5, 5] — but there were two 5s in that roll and only one survived, and nothing in [6, 5, 5] says which. Rendering from kept alone, you can print the survivors but you cannot point at the dice on the table.

keptFlags is aligned to results one for one, so it can:

results    [5,    4,     5,    3,     6,    1    ]
keptFlags  [true, false, true, false, true, false]

That alignment is the whole reason both fields exist. kept is a convenience for when you only want the numbers; keptFlags is what you need to show the roll as it happened.

The same reasoning, four more times

Once a result describes the roll rather than summarising it, several other fields follow.

results before kept. The order is the order the dice were thrown, not sorted. Sorting is a display decision, and a result that has already sorted itself cannot be un-sorted.

modifiers as well as modifier. A roll written 1d20 +1 -6 has a modifier of -5. That is correct, and it is not what was written. modifiers keeps [1, -6] so an interface can show the arithmetic rather than its conclusion.

Groups rather than one flat list. 1d8+1d4+3 is two kinds of die and a number, and they are different things. Flattening them into a single list of results would lose which die had how many sides.

A floor beside the die, not over it. 1d6min3 rolling a 1 could answer results: [3] and be arithmetically right. It answers [1, 3] instead, with the 1 marked dropped: the die is still on the record and the value it lost to is beside it. Writing the bound in as the face would hide the floor in exactly the roll where someone wants to see it working.

What it does not do

Reporting every die is about being legible, not about being provable. A response that shows its dice is easier to read and easier to debug than one that does not, but it is not evidence — the numbers still came from a server you did not run.

That distinction has its own page: What Rollful does not know.

Where to go next

• Show the working in a UI — putting this on a screen.
• Result fields — every field this argument produced.