API do Dice View

Referência do contrato público de @erpg/dice3dview 2.6.1. O View é uma camada de apresentação; valores e regras vêm do chamador.

Entrypoints

Import	Uso
@erpg/dice3dview/external	Renderer para aplicação com bundler e Babylon compartilhado
@erpg/dice3dview/adapters	Conversores puros, sem renderer gráfico
@erpg/dice3dview/style.css	Estilos do canvas
@erpg/dice3dview	Build autocontido para compatibilidade e CDN

DiceResultViewer

Membro	Contrato	Efeito
canvas	HTMLCanvasElement	Canvas criado no construtor
constructor(options?)	ViewerOptions	Anexa canvas ao container
init()	Promise<this>	Inicializa renderer, tema e observação do tamanho; idempotente
display(request)	Promise<DisplayResult>	Apresenta faces resolvidas; inicializa se necessário
displayTimeline(request)	Promise<DisplayTimelineResult>	Executa journal semântico validado
clear()	void	Cancela apresentação e limpa cena
updateOptions(options)	Promise<void>	Mescla opções compatíveis
resize()	void	Recalcula palco, piso e paredes
dispose()	void	Libera recursos e remove canvas; idempotente

Após dispose(), crie outra instância. Uma apresentação nova ou clear() rejeita a Promise anterior com DisplayCancelledError.

display()

type DiceSides = 2 | 4 | 6 | 8 | 10 | 12 | 20 | 100
type DisplayMode = 'kinematic' | 'physics'

interface ResolvedDie {
  id: string
  sides: DiceSides
  value: number
  discarded?: boolean
  theme?: string
  themeColor?: string
}

interface DisplayRequest {
  id: string
  dice: readonly ResolvedDie[]
  seed?: string
  mode?: DisplayMode
}

interface DisplayResult {
  id: string
  dice: readonly ResolvedDie[]
  durationMs: number
}

id e dice não podem ser vazios. value deve ser inteiro finito entre 1 e sides; d2 aceita somente 1 ou 2. O seed padrão é request.id; mode, theme e themeColor usam os defaults do viewer; discarded usa false. ID de dado vazio recebe ${request.id}-die-${index}. O retorno contém clones normalizados e congelados. durationMs inclui inicialização lazy, tema e animação.

display() registra falhas gráficas, de asset ou físicas depois da validação e ainda devolve o resultado normalizado. Não recalcula faces.

displayTimeline()

O request contém id, dice: TimelineDieDefinition[] (cada definição com id, sides, tema e cor opcionais), events: DiceTimelineEvent[], seed? e mode?. Uma definição não contém value; os eventos carregam as faces. O retorno acrescenta eventCount, phaseCount e degraded ao DisplayResult. Falhas durante a execução são propagadas. Consulte Timeline semântica para cada evento.

Adaptadores

@erpg/dice3dview/adapters exporta createSystemDisplayRequest, createMixedDisplayRequest, toSystemResolvedDie, toSystemResolvedDice, toMixedResolvedDice, SYSTEM_THEME_PROFILES, getSystemThemeProfile e isSystemDiceProfileId.

createSystemDisplayRequest({ id, dice, seed?, mode?, keptIds?, themeColors? }) usa o profileId de cada dado para validar lados e aplicar tema/cor. keptIds aceita ID ou sourceDieId; os demais dados ficam descartados. IDs duplicados são rejeitados.

createMixedDisplayRequest({ id, dice, seed?, mode?, unsupportedDice?, theme?, themeColor?, keptIds?, themeColors? }) aceita a lista achatada de rollMixedDice().dice. Usa physicalValue ?? rawValue ?? value. Dados genéricos sem geometria são omitidos por padrão (unsupportedDice: 'omit'); 'error' rejeita. Perfis de sistemas são sempre validados. Se todos os dados forem omitidos, o adaptador rejeita.

Cancelamento

import { isDisplayCancelledError } from '@erpg/dice3dview/external'

try {
  await viewer.display(request)
} catch (error) {
  if (isDisplayCancelledError(error)) return
  throw error
}

Também são exportados DisplayCancelledError e DISPLAY_CANCELLED_CODE ('DISPLAY_CANCELLED'). Use o helper para reconhecer cancelamento inclusive entre bundles.

Veja Configuração para todas as opções e Integre Core e View para exemplos completos.