Get started with Dice View v3

This guide displays an already resolved d20 result. Dice View v3 always uses physics: the cinematic mode has been discontinued. Your application decides the value; the viewer simulates and draws the dice. To start from notation such as 1d20+5, resolve it with Dice Core.

Version status: v3 is 3.0.0-alpha.0 on the official v3-lite-engine branch. As of September 2026, the npm latest tag is still 2.6.1. The branch includes a separate license file at this revision, distinct from v2’s MIT license; read the terms and alpha qualification before integrating it.

1. Install the v3 revision

Pin the tested commit so that alpha branch changes do not reach your project unexpectedly:

npm install "git+https://github.com/erpg-app/Dice3DViwer.git#ae00d9f6cb9865378e59d49687c4588751532c5c"

Do not install @erpg/dice3dview@latest expecting v3: that still installs v2. V3 needs neither Babylon.js nor Havok nor WebAssembly. Keep those dependencies if another feature in your project uses them.

2. Publish the assets

Copy node_modules/@erpg/dice3dview/dist/assets/dice-box/ to public/assets/dice-box/. Its themes/ folder contains models, atlases, textures, and manifests. For example, /assets/dice-box/themes/default/theme.config.json must load from your public site.

V3 has no havok/HavokPhysics.wasm. If you host the themes elsewhere, set assetPath accordingly.

3. Mount a visual stage

<div id="dice-stage" aria-hidden="true"></div>

#dice-stage {
  position: fixed;
  inset: 0;
  overflow: hidden;
  pointer-events: none;
  z-index: 100;
}

Keep the roll value and total in accessible elements of your interface. The canvas provides only the visual presentation.

4. Display the d20

Create the instance in the browser, after the element exists in the DOM. Explicit init() reports WebGL or asset failures before the first roll; display() also initializes automatically when needed.

import { DiceResultViewer, isDisplayCancelledError } from '@erpg/dice3dview'
import '@erpg/dice3dview/style.css'

const viewer = new DiceResultViewer({
  container: '#dice-stage',
  assetPath: '/assets/dice-box/',
  theme: 'default',
  themeColor: '#e60049'
})

await viewer.init()

try {
  const result = await viewer.display({
    id: 'attack-1',
    seed: 'attack-1',
    dice: [{ id: 'd20-1', sides: 20, value: 17 }]
  })
  console.log(result.dice, result.durationMs)
} catch (error) {
  if (!isDisplayCancelledError(error)) throw error
}

The d20 appears over the page and stops on face 17. seed reproduces the visual trajectory; it never draws or changes value. Call viewer.dispose() when the stage is removed.

Next steps

Follow the v3 customization guide to create atlases, themes, and looks. See the v3 API for displayTimeline(), skins, particles, glow, and physics options. If your project already uses v2, follow the v3 migration guide. The v2 documentation remains available for the MIT version on npm.

Technical source: v3 revision README.

For product context, explore ERPG.APP, where 3D dice appear over character sheets, and Mini Kraken BOT, which brings RPG rolls and a tabletop Activity into Discord. These case studies describe the products; check each project’s integration before assuming a particular library version.