Get started with Dice View

This guide documents the published v2 (2.6.1). Dice View presents already resolved results: your application, or Dice Core, chooses the value; View animates the corresponding face. This guide creates a full-screen stage and displays a d20 with physics. For a new project, start with v3 native physics and its use terms.

1. Install dependencies

npm install @erpg/dice3dview@2.6.1 @babylonjs/core

In bundled applications, import @erpg/dice3dview/external to share your project’s Babylon installation. Construct the viewer only in the browser, after the mounting element exists. Construction needs the DOM and renderer initialization needs WebGL.

2. Publish assets

Copy node_modules/@erpg/dice3dview/dist/assets/dice-box/ to public/assets/dice-box/. It contains models, textures, themes, and havok/HavokPhysics.wasm. Kinematic mode needs the themes; physics also needs the WASM. Set assetPath if you publish them elsewhere.

3. Mount a stage over the UI

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

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

The canvas is visual. Keep the numeric result and actions accessible in your application’s UI. pointer-events: none lets people continue using the page beneath the stage.

4. Present a result

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

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

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

display() initializes the renderer automatically. value must be a valid integer; seed affects animation only. A new display() or clear() cancels the previous presentation. Call viewer.dispose() when removing the stage.

Next steps

Use the Core integration to start from notation. The v2 mode reference records the legacy cinematic mode. The playground presents rolls with v3 physics.