Migrate from Dice View v2 to v3

V3 retains v2’s DiceResultViewer, display(), displayTimeline(), adapters, requests, and themes. Presentation changes most: every roll uses its own physics engine, without Babylon.js or Havok. This page covers the 3.0.0-alpha.0 of the official ae00d9f revision, which is not yet published on npm.

Before migrating, review the license file at this v3 revision and the alpha qualification. Versions published before 3.0.0 remain under MIT; the v3 file describes different conditions.

1. Update the dependency

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

The commit contains dist/ and can be installed directly. Once v3 is published on npm, replace the Git reference with a published version after validating the migration. Babylon.js and Havok can be removed if Dice View was their only consumer.

2. Refresh public assets

Copy node_modules/@erpg/dice3dview/dist/assets/dice-box/ to public/assets/dice-box/ again. You can remove havok/: v3 does not read WASM. V2 theme manifests and .babylon models remain supported; the symbolic themes bundled with v3 also contain glyph-orientation.json for upright glyphs.

3. Simplify the configuration

// v2
new DiceResultViewer({ container: '#dice-stage', mode: 'kinematic' })

// v3: physics is the only mode and the default
new DiceResultViewer({ container: '#dice-stage' })

The @erpg/dice3dview/external import still works, but in v3 it points to the same module as @erpg/dice3dview. Use the root import for new integrations. The @erpg/dice3dview/adapters subpath remains available without loading the renderer.

V2 configuration	V3 behavior
mode: 'kinematic'	Accepted for compatibility, warns once in the console, and runs physics. Remove it from new code and UI.
duration	Accepted and ignored. Tune throwForce, gravity, and settleTimeout to change motion.
physicsWasmUrl	Accepted and ignored; no WASM is used.
shadowResolution	Accepted and ignored; v3 uses contact shadows.
wallBounceChance	Deprecated alias for aggressiveThrowChance.
timeline.effects.compound.showBadge and penetrate.showBadge	Accepted and ignored; dice pulse in the effect color.

DisplayMode is now only 'physics'. The old 'kinematic' literal remains accepted in ViewerOptions, DisplayRequest, and DisplayTimelineRequest, but it does not restore cinematic animation. Adapter types use DisplayMode and already require 'physics' if you pass mode. Update your controls so they do not offer a nonexistent mode.

4. Check visual changes

Resolved faces and totals still come from the application. In v2’s physics mode, the renderer guided orientation toward the requested face; v3 simulates freely and applies a symmetry of the polyhedron to the drawing so the received result is visible without changing the path. With the same seed, dice, and stage size, the animation is reproducible.

Timeline explosions and rerolls now use physical motion; dice already at rest remain stationary. Discarded dice lose saturation but stay opaque. To verify an integration, test a normal roll, one with discarded, an explosion or reroll, theme switching, and cleanup with dispose().

After migrating, see the v3 API for the new skin, particles, glow, and applyLook() options. If you remain on v2, use the v2 API.

Technical source: library migration guide.