Personalize dados e visuais na Dice View v3

Este guia cria um tema obsidian para os dados físicos da Dice View 3.0.0-alpha.0. Você vai alterar os mapas de face, publicar um theme.config.json, conferir os resultados no d20 e no d2 e, depois, aplicar uma skin e efeitos sem modificar os atlas. A v3 usa somente física; comece pela instalação desta revisão se ainda não tiver o viewer funcionando. Confira os termos da v3 antes de distribuir sua integração.

1. Publique os arquivos e copie os atlas

Copie node_modules/@erpg/dice3dview/dist/assets/dice-box/ para public/assets/dice-box/. Preserve themes/default/: ele contém o modelo, as texturas e a moeda usados como base. A v3 não precisa da pasta havok/ da v2. Crie themes/obsidian/ e copie para lá diffuse-light.webp, diffuse-dark.webp e normal.webp do tema padrão:

public/assets/dice-box/themes/
├── default/
│   ├── default.json
│   ├── diffuse-light.webp
│   ├── diffuse-dark.webp
│   ├── normal.webp
│   └── glyph-orientation.json
└── obsidian/
    ├── theme.config.json
    ├── diffuse-light.webp
    ├── diffuse-dark.webp
    └── normal.webp

Abra /assets/dice-box/themes/default/theme.config.json no navegador. Se a URL falhar, corrija a publicação dos assets antes de editar o tema. O assetPath padrão é /assets/dice-box/; você pode alterá-lo no construtor. A galeria de texturas mostra os atlas originais da V3 lado a lado e oferece a amostra especular histórica da V2.

2. Edite os mapas sem trocar as faces

Os atlas do modelo padrão usam uma tela de 1024 × 1024 pixels. Redesenhe os números em cada ilha UV, preservando posição, escala e transparência. diffuse-light.webp contém glifos claros para corpos escuros; diffuse-dark.webp, glifos escuros para corpos claros. O viewer escolhe a variante conforme o brilho de themeColor ou da skin. A imagem não é uma grade ordenada por resultado: mover o número para outra ilha pode exibir uma face diferente do value recebido.

Mapa	Função	Quando incluir
diffuse-light.webp e diffuse-dark.webp	Arte das faces para cores de corpo diferentes	Ao trocar números ou símbolos
normal.webp	Relevo no mesmo layout UV	Se o novo desenho precisar de relevo; atualize-o junto dos glifos
specularTexture	Mapa opcional que modula o reflexo	Se criar uma imagem especular própria; o tema padrão da v3 não a fornece

Use material.type: "color" para manter o corpo recolorível por themeColor e permitir a skin da v3. "standard" usa a arte de cor do próprio atlas e não recebe skin. Veja o contrato completo de materiais e caminhos.

3. Escreva o manifesto

Salve este JSON como themes/obsidian/theme.config.json. Sem meshFile, a v3 usa themes/default/default.json; por isso os mapas precisam manter as mesmas ilhas UV. Os caminhos das texturas partem da pasta obsidian/.

{
  "name": "Obsidian",
  "systemName": "obsidian",
  "material": {
    "type": "color",
    "diffuseTexture": {
      "light": "diffuse-light.webp",
      "dark": "diffuse-dark.webp"
    },
    "diffuseLevel": 1,
    "bumpTexture": "normal.webp",
    "bumpLevel": 0.5
  },
  "diceAvailable": ["d2", "d4", "d6", "d8", "d10", "d12", "d20", "d100"],
  "coin": {
    "front": { "value": 1, "texture": "../default/coin-1.svg" },
    "back": { "value": 2, "texture": "../default/coin-2.svg" },
    "colorize": true,
    "diameter": 1,
    "thickness": 0.12
  }
}

material e diceAvailable são obrigatórios. A moeda d2 é procedural: frente vale 1, verso vale 2, e a arte não muda esses valores. Se criar uma moeda colorida própria, troque os SVGs e use colorize: false; edgeColor define a borda. Para glifos cuja orientação precisa ser controlada, a v3 aceita faceAtlas.orientation apontando para um JSON de direções por face. O arquivo do tema padrão só pode ser reutilizado se você mantiver seu layout e a orientação da arte. Veja a estrutura de temas e a orientação.

Confira por HTTP o manifesto e cada imagem referenciada. Se criar seu próprio modelo, forneça malha visual dN, collider dN_collider e colliderFaceMap.dN coerentes para cada poliedro. Na v3, o collider também determina o corpo simulado; teste todas as faces antes de publicar.

4. Confira o tema em uma rolagem física

import { DiceResultViewer } from '@erpg/dice3dview'
import '@erpg/dice3dview/style.css'

const viewer = new DiceResultViewer({
  container: '#dice-stage',
  assetPath: '/assets/dice-box/',
  theme: 'obsidian',
  themeColor: '#251c34'
})

await viewer.display({
  id: 'teste-obsidian',
  dice: [
    { id: 'd20', sides: 20, value: 18 },
    { id: 'moeda', sides: 2, value: 1 }
  ]
})

O viewer apresenta os valores já definidos pela aplicação. Repita o teste para os formatos declarados em diceAvailable, compare a face visível com value e experimente uma cor clara para conferir o atlas dark. Se mudar um manifesto já carregado com o mesmo nome, descarte a instância com viewer.dispose() e crie outra para renovar caches de materiais e modelo.

5. Aplique uma skin sobre a cor

A skin da v3 é uma imagem projetada no corpo por mapeamento triplanar. Ela independe das ilhas UV; os números do atlas color permanecem sobre a imagem. A alteração passa a valer na próxima apresentação:

await viewer.updateOptions({
  themeColor: '#284b9b',
  skin: {
    texture: '/textures/marble.webp',
    blend: 'multiply',
    opacity: 0.85,
    scale: 1.3,
    labels: 'auto'
  }
})

await viewer.display({
  id: 'teste-marmore',
  dice: [{ id: 'd6', sides: 6, value: 4 }]
})

blend aceita normal, multiply, screen e overlay; opacity vai de 0 a 1, scale de 0.05 a 20, e labels aceita auto, light ou dark. A textura aceita URL HTTP(S), data: e blob:. Em outra origem, habilite CORS. Para voltar à superfície do tema, chame await viewer.updateOptions({ skin: null }). Consulte a API de skin.

6. Adicione partículas e brilho

Partículas e brilho podem mudar imediatamente, inclusive com dados já visíveis. Comece com um preset e ajuste os momentos da rolagem:

await viewer.updateOptions({
  particles: {
    preset: 'sparkle',
    intensity: 1.2,
    color: '#ea5b93',
    moments: { ground: false }
  },
  glow: { color: '#ea5b93', intensity: 0.8, light: true, pulse: false }
})

Também é possível criar um emissor próprio, sem preset. Este exemplo limita o impacto a d20 cujo resultado seja o maior valor:

await viewer.updateOptions({
  particles: {
    effect: {
      impact: {
        amount: 24,
        life: [0.2, 0.6],
        size: [0.08, 0.2],
        speed: [1, 3],
        colors: ['#ffffff', '#ea5b93aa', '#ea5b9300'],
        when: { sides: [20], faces: 'max' }
      }
    }
  }
})

particles: null e glow: null desligam os respectivos efeitos. Veja presets, momentos, condições e limites na API v3.

7. Salve o visual separadamente do tema

O estúdio de skins e temas oferece as 18 superfícies do workshop original (mármore, madeira, pedra e outras), 15 visuais prontos e edição de cada emissor de partículas. Você pode ajustar rastro, impacto, colisão, repouso, aura, explosão e crítico, inclusive força, velocidade, faces, lados, chance e intervalo de ativação. A prévia usa a V3 real; exporte e importe o dice-look.json para continuar o trabalho.

Um arquivo .dice-look.json reúne cor, skin, partículas e brilho. Ele não inclui o theme.config.json, o modelo nem os atlas: continue distribuindo a pasta obsidian/ e escolhendo theme: 'obsidian' no viewer.

import { createDiceLook } from '@erpg/dice3dview'

const look = createDiceLook({
  name: 'Obsidian Marble',
  themeColor: '#284b9b',
  skin: { texture: '/textures/marble.webp', blend: 'multiply', opacity: 0.85 },
  particles: { preset: 'sparkle', intensity: 1.2 },
  glow: { color: '#ea5b93', intensity: 0.8 }
})

const json = JSON.stringify(look, null, 2) // salve como obsidian-marble.dice-look.json
await viewer.applyLook(look)

createDiceLook() acrescenta format: "dice3dview-look" e version: 1 e valida os campos. applyLook() valida o arquivo antes de aplicá-lo. Uma URL de skin ainda precisa estar disponível quando você abrir o visual em outro lugar; use uma URL pública ou data: para um arquivo independente. Veja o contrato do visual.

Compatibilidade com a v2

Os manifests, modelos e mapas da v2 mantêm seu formato na v3. Faça uma rolagem física de cada formato ao migrar, sobretudo se o tema traz um collider próprio. faceAtlas.orientation é um recurso opcional da v3; skins, partículas, brilho e arquivos de visual são recursos desta integração v3 e devem ser configurados no código que carrega a v3. A v2 publicada no npm continua documentada separadamente, assim como a migração v2 → v3. As versões acompanham licenças diferentes.

Fontes desta revisão: temas, API e migração.