Get started with Dice Core

Requirements and installation

The package ships ESM, CommonJS, and TypeScript declarations. It requires Node.js 22+ or an ES2022 browser with globalThis.crypto.getRandomValues. It has no runtime dependencies. The published npm 3.7.1 artifact includes MIT; see the license comparison for the mismatch with the current source checkout.

npm install @erpg/dicecore

Make your first roll

The /core entrypoint loads the generic engine only. Without a seed, Core uses cryptographic entropy; with one, the same formula and library version reproduce the result.

import { rollRpgDice } from '@erpg/dicecore/core'

const result = rollRpgDice('2d6+3', { seed: 'session-42' })
console.log(result.total)
console.log(result.dice)
console.log(result.output)

The result includes dice, groups, events, rolls, pool, replay, and stats. In 4d6kh3, the discarded die stays in dice; inspect included and contribution rather than summing value yourself.

Replay an execution

replay records the algorithm, version, and seed material without revealing the original seed text. It is bound to the formula’s plan.

const first = rollRpgDice('4d6kh3')
const again = rollRpgDice(first.input, { replay: first.replay })

Next steps

• Browse the notation reference for every roll type.
• Try examples in the playground.
• See the API for inspection, limits, and results.
• Use the Dice View v3 physics preview or the stable v2 integration to display a roll in 3D.

Try the examples

Try 2d6+3 · Try 4d6kh3

See it in real RPG products

Mini Kraken BOT brings dice commands and character sheets into Discord, with a tabletop Activity for the voice channel. ERPG.APP shows character sheets and tabletop tools with 3D dice over the interface. These cases show two places where a structured roll can serve players.