Comece com o Dice View v3

Este guia mostra um resultado já resolvido em um d20. O Dice View v3 sempre usa física: o modo cinemático foi descontinuado. A aplicação decide o valor; o viewer simula e desenha os dados. Para partir de uma expressão como 1d20+5, use o Dice Core para resolver a notação.

Estado da versão: a v3 está em 3.0.0-alpha.0 na branch oficial v3-lite-engine. Em setembro de 2026, o latest do npm ainda é 2.6.1. A branch vem acompanhada de um arquivo de licença próprio nesta revisão, diferente da MIT da v2; confira os termos e a ressalva sobre o alpha antes de integrá-la.

1. Instale a revisão da v3

Fixe o commit testado no seu projeto para não receber mudanças inesperadas do alpha:

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

Não instale @erpg/dice3dview@latest esperando a v3: esse comando ainda instala a v2. A v3 não precisa de Babylon.js, Havok nem WebAssembly. Se outro recurso do projeto os usa, mantenha as dependências dele.

2. Publique os assets

Copie node_modules/@erpg/dice3dview/dist/assets/dice-box/ para public/assets/dice-box/. A pasta contém themes/, com modelos, atlas, texturas e manifests. O caminho público deve responder, por exemplo, em /assets/dice-box/themes/default/theme.config.json.

Na v3 não existe havok/HavokPhysics.wasm. Se publicar os temas em outro caminho, passe esse caminho em assetPath.

3. Crie um palco visual

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

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

Mantenha o valor e o total da rolagem em elementos acessíveis da interface. O canvas é apenas a apresentação visual.

4. Apresente o d20

Crie a instância no navegador, depois de o elemento existir no DOM. init() permite detectar falhas de WebGL ou de assets antes da primeira rolagem; display() também inicializa automaticamente, se necessário.

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: 'ataque-1',
    seed: 'ataque-1',
    dice: [{ id: 'd20-1', sides: 20, value: 17 }]
  })
  console.log(result.dice, result.durationMs)
} catch (error) {
  if (!isDisplayCancelledError(error)) throw error
}

O d20 aparece por cima da página e para na face 17. seed reproduz a trajetória visual; não sorteia nem altera value. Ao desmontar a tela, chame viewer.dispose().

Próximos passos

Siga o guia de personalização V3 para criar atlas, temas e visuais. Consulte a API V3 para displayTimeline(), skins, partículas, brilho e opções de física. Se seu projeto já usa a V2, siga a migração para V3. A documentação V2 continua disponível para a versão MIT publicada no npm.

Fonte técnica: README da revisão v3.

Para ver esses conceitos em produtos, explore o ERPG.APP, com dados 3D sobre fichas, e o Mini Kraken BOT, com rolagens e uma mesa como Activity no Discord. Os cases descrevem os produtos; confira a integração de cada projeto antes de pressupor uma versão específica da biblioteca.