ReferênciaV2 estável

Configuração do viewer

Todas as opções públicas do DiceResultViewer, seus defaults, callbacks e limites de atualização.

Este artigo documenta a V2 publicada. Para a prévia atual com física, veja o guia V3. V3 ↗ Licenças ↗

As opções são passadas a new DiceResultViewer(options) e, quando compatíveis, a await viewer.updateOptions(options). O tipo público é ViewerOptions. Os valores abaixo correspondem ao pacote 2.6.1.

Núcleo e temas

Opção	Default	Uso
`id`	`dice-canvas-${Date.now()}`	ID do canvas
`container`	`null`	Seletor ou `HTMLElement`; elemento existente é obrigatório na prática
`assetPath`	`/assets/dice-box/`	Raiz pública dos assets
`origin`	origem da página	Origem para assets internos
`mode`	`kinematic`	`kinematic` ou `physics`
`theme`	`default`	Tema padrão
`preloadThemes`	`[]`	Temas carregados por `init()`
`externalThemes`	`{}`	Mapa de nome para URL base da pasta do tema
`themeColor`	`#2e8555`	Cor padrão da superfície
`maxDice`	`120`	Limite de corpos visuais; d100 conta como dois

Cena e entrada

Opção	Default	Uso
`enableShadows`	`true`	Sombras
`shadowTransparency`	`0.8`	Intensidade/transparência do shadow map (`0..1`)
`shadowResolution`	`1024`	Resolução inteira positiva do shadow map
`lightIntensity`	`1`	Multiplicador da iluminação
`antialias`	`true`	Antialias da engine
`scale`	`5`	Escala dos objetos
`duration`	`1100` ms	Duração cinemática base
`delay`	`10` ms	Intervalo de liberação por corpo
`wallPadding`	`0.25`	Recuo interno da área útil
`spawnSpacing`	`1.72`	Separação solicitada no portal
`spawnHeightStep`	`0`	Offset vertical opcional
`spawnOverscan`	`0.15`	Margem extra fora da projeção, em fração do raio

duration efetivo tem mínimo de 250 ms, além dos atrasos de liberação. O packing pode criar novas ondas quando não há espaço na borda.

Física

Opção	Default	Uso
`gravity`	`1.3`	Multiplicador de `−9.81`
`mass`	`1.08`	Massa base
`startingHeight`	`7.6`	Plano de liberação; altura efetiva limitada internamente
`spinForce`	`5.8`	Escala do giro
`throwForce`	`6.4`	Intensidade do arremesso
`aggressiveThrowChance`	`0.12`	Chance por apresentação de energia maior (`0..1`)
`wallBounceChance`	alias obsoleto	Use `aggressiveThrowChance`; não garante colisão
`colliderScale`	`1.02`	Escala de collider dos poliedros
`friction`	`0.54`	Fricção do piso e dados
`restitution`	`0.29`	Elasticidade do piso e dados
`linearDamping`	`0.10`	Amortecimento linear inicial
`angularDamping`	`0.08`	Amortecimento angular após impacto
`settleTimeout`	`4200` ms	Janela de segurança; não escolhe o valor
`physicsWasmUrl`	`''`	URL explícita do WASM Havok

Timeline

timeline.enabled começa em true, maxEvents em 500, maxDurationMs em 12000 e phaseGapMs em 180. Todos os efeitos começam ativos: explode, compound, penetrate, reroll, unique, keep, drop, success, failure, neutral, criticalSuccess e criticalFailure. Cada um aceita enabled, delayMs, durationMs, intensity (0..1) e color. Campos específicos e exemplos estão em Timeline semântica.

Callbacks

Opção	Argumento	Momento
`onCollision`	`{ action: 'collision', body0Id?, body1Id?, force }`	Contato no modo físico
`onThemeConfigLoaded`	`ResolvedThemeConfig`	Configuração resolvida fora do cache
`onThemeLoaded`	`ResolvedThemeConfig`	Tema usado na apresentação
`onTimelineProgress`	`TimelineProgressEvent`	Snapshot de `initial`, `phase` ou `complete`

Atualização e validação

updateOptions() mescla opções e faz merge profundo por efeito de timeline. Mudanças em container, id, antialias, shadowResolution, gravity, physicsWasmUrl ou na raiz/definição de assets já carregados exigem uma nova instância. preloadThemes só é consumido durante init().

Modos inválidos, números não finitos, limites incoerentes, callbacks que não são funções e estruturas mínimas inválidas de tema ou moeda são rejeitados. Uma atualização inválida mantém as opções válidas anteriores. Confira a API para métodos e contratos.