Package or API
Rollful is one roller with two ways in. roll('4d6kh3') in JavaScript and
GET /v1/roll?formula=4d6kh3 over HTTP run the same parser, the same keep rules and the same
random source, and return the same shape. Neither is a cut-down version of the other.
So the choice is not about capability. It is about where you want the roll to happen.
The package is the default in JavaScript
Section titled “The package is the default in JavaScript”If your code is JavaScript or TypeScript and the roll can happen where that code runs, use the package. It is faster — no round trip — and it has no rate limit, no dice budget per request, and no dependency on this service being up. A dice roller that stops working because someone else’s server is down is a worse dice roller.
That is most single-player cases: a character sheet in a browser, a bot rolling for its own command, a script.
The API is for everywhere else
Section titled “The API is for everywhere else”Reach for HTTP when one of these is true.
Your language has no OpenDice build. Python, PHP, Go, Ruby, Rust, a shell script. The API is the package’s grammar made available to all of them, and the response is plain JSON.
The roll must not happen on the client. Anything a player could edit, they can edit — including a local dice roller. A roll several people have to agree on has to happen somewhere none of them controls.
You want the roller to be someone else’s problem. No dependency to add, no version to keep current, no build to change.
What the API adds, and what it costs
Section titled “What the API adds, and what it costs”The API is a thin layer. It validates the request, applies its own bounds, and calls the same
roll(). It adds no rules and changes no results.
What it adds is that the roll happened somewhere the caller does not control. What it costs is a network hop, a rate limit that is a guard rather than a quota, and a dice budget per request that the package does not have.
Both are free and neither needs a key.
Using both
Section titled “Using both”Nothing stops you. A common shape is the package on the client for immediate feedback — a preview of the formula, a validation pass as someone types — and the API for the roll that counts. Since both produce the same result shape, the code that renders a roll does not need to know which one produced it.
Where to go next
Section titled “Where to go next”- Roll dice in JavaScript — the package, from installation.
- Roll dice over HTTP — the API, from a first request.
- What Rollful does not know — the limits of what a server-side roll actually proves.