Migre do Dice View v2 para a v3
Atualize imports, assets e opções de animação para o renderer exclusivamente físico.
Este artigo descreve a prévia V3 alpha, que usa apenas física e ainda não está publicada no npm. V2 ↗ Licenças ↗
A v3 preserva DiceResultViewer, display(), displayTimeline(), adaptadores, requests e temas da v2. A principal mudança é a apresentação: toda rolagem passa pelo motor físico próprio, sem Babylon.js ou Havok. Esta página se refere ao alpha 3.0.0-alpha.0 da revisão oficial ae00d9f, ainda não publicado no npm.
Antes de migrar, confira o arquivo de licença desta revisão V3 e a ressalva sobre o alpha. A V2 publicada antes da 3.0.0 permanece MIT; o arquivo da V3 descreve condições diferentes.
1. Atualize a dependência
npm install "git+https://github.com/erpg-app/Dice3DViwer.git#ae00d9f6cb9865378e59d49687c4588751532c5c"O commit contém dist/ e pode ser instalado diretamente. Quando houver um lançamento v3 no npm, substitua a referência Git pela versão publicada após validar a migração. Babylon.js e Havok podem ser removidos se eram usados só pelo Dice View.
2. Atualize os assets públicos
Copie node_modules/@erpg/dice3dview/dist/assets/dice-box/ novamente para public/assets/dice-box/. Você pode remover a pasta havok/: a v3 não lê WASM. Os manifests e modelos .babylon dos temas v2 seguem aceitos; os temas simbólicos incluídos na v3 trazem ainda glyph-orientation.json para orientar glifos.
3. Simplifique a configuração
// v2
new DiceResultViewer({ container: '#dice-stage', mode: 'kinematic' })
// v3: física é o único modo e já é o padrão
new DiceResultViewer({ container: '#dice-stage' })O import @erpg/dice3dview/external continua válido, mas na v3 aponta para o mesmo módulo que @erpg/dice3dview. Use o import raiz para novas integrações. O subpath @erpg/dice3dview/adapters continua disponível sem carregar o renderer.
| Configuração v2 | Comportamento na v3 |
|---|---|
mode: 'kinematic' |
Aceita por compatibilidade, avisa uma vez no console e executa física. Remova da UI e do código novo. |
duration |
Aceita e ignorada. Ajuste throwForce, gravity e settleTimeout para mudar o movimento. |
physicsWasmUrl |
Aceita e ignorada; não há WASM. |
shadowResolution |
Aceita e ignorada; a v3 usa sombras de contato. |
wallBounceChance |
Alias antigo de aggressiveThrowChance. |
timeline.effects.compound.showBadge e penetrate.showBadge |
Aceitos e ignorados; os dados pulsam na cor do efeito. |
DisplayMode agora é apenas 'physics'. O literal antigo 'kinematic' ainda é aceito em ViewerOptions, DisplayRequest e DisplayTimelineRequest, mas não restaura a animação cinemática. Os tipos dos adaptadores usam DisplayMode e já exigem 'physics' se você fornecer mode. Revise seus controles para não oferecer uma opção que não existe.
4. Confira as mudanças visuais
As faces resolvidas e os totais continuam vindo da aplicação. Na v2 física, o renderer guiava a orientação para a face pedida; na v3, simula livremente e aplica ao desenho uma simetria do poliedro que preserva a trajetória e mostra o resultado recebido. Com a mesma seed, dados e tamanho de palco, a animação é reproduzível.
Explosões e rerolagens da timeline passam a usar movimento físico; dados já parados continuam imóveis. Dados descartados perdem saturação, mas permanecem opacos. Para verificar uma integração, teste pelo menos uma rolagem comum, uma com discarded, uma explosão ou reroll, a troca de tema e o descarte da instância com dispose().
Depois da migração, consulte a API v3 para as novas opções skin, particles, glow e applyLook(). Para projetos que permanecem na v2, use a API v2.
Fonte técnica: guia de migração da biblioteca.