API do Dice Core

Entrypoints públicos

O pacote raiz @erpg/dicecore reexporta toda a API. Para carregar apenas o necessário:

Import	Conteúdo
@erpg/dicecore/core	Engine, compilação, validação, rolagens genéricas, limites e erros
@erpg/dicecore/systems	Todos os sistemas e lote misto
@erpg/dicecore/systems/fate	Fate
@erpg/dicecore/systems/vampire-v5	Vampiro V5
@erpg/dicecore/systems/assimilation	Assimilação
@erpg/dicecore/systems/daggerheart	Daggerheart
@erpg/dicecore/systems/mixed	Lotes mistos

Imports internos fora desses exports não pertencem ao contrato.

Compilação e inspeção

Função	Retorno	Uso
compileRpgDice(input, options?)	RollPlan	Normaliza e compila uma fórmula reutilizável
inspectRpgDiceNotation(input, options?)	DiceNotationInspection	Valida e estima custo sem rolar; não lança para notação inválida
verifyRpgDiceNotation(input, options?)	boolean	Validação booleana
normalizeRpgDiceNotation(input)	string	Expande atalhos e remove comentários

RollPlan tem schemaVersion: 3, planFingerprint, normalizedNotation, rollCount, groups e cost. Um plano desserializado é revalidado pelo engine antes de executar; não trate sua estrutura como AST editável.

import { compileRpgDice, inspectRpgDiceNotation, rollRpgDice } from '@erpg/dicecore/core'
const inspection = inspectRpgDiceNotation('4d6kh3')
if (inspection.isValid) {
  const plan = compileRpgDice('4d6kh3')
  console.log(inspection.cost.totalStaticDice)
  console.log(rollRpgDice(plan).total)
} else {
  console.error(inspection.error.code)
}

Execução e projeções

Função	Retorno
rollRpgDice(inputOrPlan, options?)	DiceRollResult completo
rollRpgDiceDetails(inputOrPlan, options?)	DiceRollDetails com dados, sem grupos/eventos/output
rollRpgDiceSummary(inputOrPlan, options?)	DiceRollSummary sem dados/grupos/eventos/output
rollMixedDice(notation, options?)	MixedRollResult discriminado por segmento

No resultado completo, total é numérico; output é texto de conveniência; dice, groups e events são arrays raiz; rolls referencia intervalos nesses arrays. pool é null sem target. stats contabiliza rolls, dados iniciais/gerados, chamadas RNG, passos, eventos, grupos e itens de resultado. Os DTOs são somente leitura e JSON-safe.

Campo de ResolvedDie	Interpretação
id, parentDieId	Identidade local e vínculo de explosão
sides, rawValue	Tipo de dado e primeira face
value	Valor após transformações
included, contribution	Participação e contribuição para o total
states	Modificadores/classificações aplicados

Para animação, consuma o journal events: roll, reroll, explode, transform, include, exclude e classify. Um filho explosivo tem evento roll antes do evento explode que o vincula ao pai. Monte dependências por IDs. Consulte Dice View para integração visual.

Opções, seed e replay

RollOptions aceita limits e ou seed: string | number / randomAlgorithm: 'mt19937' | 'xoshiro128ss' ou replay. Seed e replay não podem coexistir. MT19937 é padrão. Sem seed, o Core exige crypto.getRandomValues; não usa Math.random. ReplayDescriptor registra algoritmo, versões, perfil matemático decimal12-v1, material de seed e fingerprint do plano. Mudar a fórmula causa REPLAY_PLAN_MISMATCH.

const first = rollRpgDice('2d20kh1')
const repeated = rollRpgDice(first.input, { replay: first.replay })

Engine e sistemas

createDiceEngine({ limits, cache, randomAlgorithm, freezeResults }) cria configuração isolada. O engine expõe compile, inspect, normalize, roll, rollDetails, rollSummary, verify, clearCache e getCacheStats. cache: false desabilita cache; opções de cache são maxInputEntries, maxProgramEntries e maxProgramNodes. freezeResults aceita never (padrão), development ou always.

createSystemRoller(engine) vincula rollFateDice, rollVampireV5, rollAssimilation, rollDaggerheart e rollMixedDice ao mesmo engine. As APIs semânticas estão documentadas em Fate, Vampiro, Assimilação e Daggerheart. Cada dado semântico tem sourceDieId, profileId, dieKind, faceKey e symbols. detail: 'compact' resume somente o baseRoll interno.

Limites e erros

DICE_LIMIT_PRESETS fornece browser, trustedServer e untrustedServer. Por padrão, o Core limita entrada a 4.096 caracteres, profundidade AST a 64, nós a 10.000, rolls a 100, dados iniciais a 10.000, dados gerados a 20.000 e RNG a 100.000 chamadas. Também há limites para eventos, lados, seed, passos, grupos, itens e output. Limites por chamada só podem reduzir o teto do engine.

DiceRollError traz code, span, input, details e toJSON(). Use isDiceRollError(); para transporte JSON, valide com isDiceRollErrorData() e restaure com DiceRollError.fromJSON(). Códigos comuns: INVALID_NOTATION, UNSUPPORTED_NOTATION, NON_TERMINATING_MODIFIER, IMPOSSIBLE_UNIQUE, INVALID_SYSTEM_INPUT, RNG_UNAVAILABLE e REPLAY_PLAN_MISMATCH.

import { DiceRollError, isDiceRollError, isDiceRollErrorData } from '@erpg/dicecore/core'
try {
  rollRpgDice('7d6u')
} catch (error: unknown) {
  if (isDiceRollError(error)) console.error(error.code, error.span)
}
const received: unknown = JSON.parse(payload)
if (isDiceRollErrorData(received)) throw DiceRollError.fromJSON(received)

Teste os exemplos

Testar 2d20kh1 · Testar 5d10>=8f=1