Comece com o Dice View

Este guia documenta a V2 publicada (2.6.1). O Dice View apresenta resultados já resolvidos: a aplicação, ou o Dice Core, escolhe o valor; o View anima a face correspondente. Aqui, o palco cobre a tela e mostra um d20 no modo físico. Para novos projetos, consulte primeiro a V3 com física nativa e seus termos de uso.

1. Instale as dependências

npm install @erpg/[email protected] @babylonjs/core

Em aplicações com bundler, use @erpg/dice3dview/external para compartilhar o Babylon do projeto. O pacote exige DOM ao construir o viewer e WebGL ao iniciar o renderer; crie a instância somente no navegador, depois que o elemento de montagem existir.

2. Publique os assets

Copie node_modules/@erpg/dice3dview/dist/assets/dice-box/ para public/assets/dice-box/. A pasta inclui modelos, texturas, temas e havok/HavokPhysics.wasm. O modo cinemático usa os temas; o físico também usa o WASM. Se usar outro caminho público, ajuste assetPath.

3. Monte o palco sobre a interface

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

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

O canvas é visual. Deixe o resultado numérico e as ações acessíveis na interface da aplicação. pointer-events: none permite continuar usando a página sob o palco.

4. Apresente um resultado

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

display() inicializa o renderer automaticamente. value precisa ser um inteiro válido; seed afeta apenas a animação, nunca o resultado. Um novo display() ou clear() cancela a apresentação anterior. Chame viewer.dispose() ao desmontar a tela.

Próximos passos

Use a integração com o Core para partir de notação. A referência de modos da V2 registra o modo cinemático legado. O playground apresenta a rolagem com física na V3.