Timeline semântica

displayTimeline() recebe um journal já resolvido. Cada dado em dice define identidade, lados e tema; as faces surgem dos eventos roll e reroll. O View valida o journal inteiro antes de limpar a cena.

const result = await viewer.displayTimeline({
  id: 'explosao-1',
  mode: 'physics',
  dice: [
    { id: 'root', sides: 6 },
    { id: 'child', sides: 6 }
  ],
  events: [
    { sequence: 1, type: 'roll', subject: 'die', dieId: 'root', parentDieId: null, rollIndex: 1, sourceNodeId: 'n1', value: 6 },
    { sequence: 2, type: 'roll', subject: 'die', dieId: 'child', parentDieId: 'root', rollIndex: 1, sourceNodeId: 'n1', value: 4 },
    { sequence: 3, type: 'explode', subject: 'die', dieId: 'root', parentDieId: null, rollIndex: 1, sourceNodeId: 'n1', childDieId: 'child', value: 4, reason: 'explode' }
  ]
})

console.log(result.eventCount, result.phaseCount, result.degraded)

Tipos de evento

Todos os eventos têm sequence positiva e estritamente crescente, dieId, parentDieId, rollIndex e sourceNodeId; subject pode ser 'die'.

type	Campos próprios	Efeito apresentado
roll	value	Revela a primeira face do dado
reroll	from, to, reason	Muda a face após nova rolagem; reason é reroll, reroll-once, unique ou unique-once
explode	childDieId, value, reason	Introduz um dado filho; reason é explode, compound ou penetrate
transform	from, to, reason	Ajuste semântico; reason é minimum, maximum, penetrate ou compound
include	contribution	Inclui a contribuição do dado
exclude	reason	Marca descarte; reason é drop, keep ou compound-absorbed
classify	outcome	Destaca success, failure, neutral, critical-success ou critical-failure

O validador verifica IDs, referências, rolls iniciais, linhagem, ciclos e transições. Não fabrique uma timeline a partir de valores finais sem reconstruir essas relações. Quando o Core fornece um journal, passe dados e eventos correspondentes juntos.

compound e penetrate podem produzir valores sem face física correspondente. O View mantém a face válida e mostra o ajuste por badge; não fabrica uma nova face. minimum e maximum ajustam o estado sem uma coreografia própria.

Efeitos configuráveis

await viewer.updateOptions({
  timeline: {
    maxDurationMs: 16_000,
    effects: {
      explode: { origin: 'source', burstHeight: 1.6, spread: 0.8 },
      reroll: { style: 'hop', hopHeight: 2.2 },
      criticalSuccess: { pulses: 2 },
      compound: { showBadge: true }
    }
  }
})

Cada efeito aceita enabled, delayMs, durationMs, intensity (0..1) e color. Há controles para explode, compound, penetrate, reroll, unique, keep, drop, success, failure, neutral, criticalSuccess e criticalFailure. reroll/unique aceitam estilo hop, edge ou spin; explode aceita origem source ou edge; efeitos críticos aceitam pulses; compound/penetrate aceitam showBadge. O merge de updateOptions() é profundo por efeito.

timeline.enabled começa em true; maxEvents em 500, maxDurationMs em 12000 e phaseGapMs em 180. Se a timeline estiver desativada ou exceder o orçamento, o View apresenta o estado final de forma plana e retorna degraded: true. Desligar um efeito remove sua coreografia, sem modificar a face ou o resultado.

Sincronize a UI com a cena

const viewer = new DiceResultViewer({
  container: '#dice-stage',
  onTimelineProgress(progress) {
    renderSubtotal(progress.dice)
    console.log(progress.stage, progress.completedEventSequences)
  }
})

O snapshot imutável informa stage (initial, phase, complete), phaseIndex, phaseCount, phaseId, effect, revealedDieIds, dados visíveis { id, value, discarded } e sequências concluídas. Em physics, um filho de explosão pode ser liberado assim que o pai estabilizar, antes dos outros dados da fase. Na apresentação plana degradada, só há initial e complete. Exceções no callback são isoladas.

displayTimeline() retorna dice, durationMs, eventCount, phaseCount e degraded. Diferente de display(), falhas gráficas, de asset ou físicas são propagadas; uma execução parcial não é reportada como sucesso.