Personalize faces simbólicas

Este guia ensina a criar arte simbólica sobre as malhas já incluídas, usando os mapas reais da galeria. Ao final, cada resultado do Dice Core continua a chegar na face física correta; o tema muda apenas a representação visual.

1. Escolha o dado físico

O atlas é aplicado à geometria, não à regra do jogo. Os temas de exemplo oferecem:

Tema	Dado físico	Arte no atlas
fate	d6	−, vazio, +
vampire-v5-normal	d10	sucesso e crítico
vampire-v5-hunger	d10	sucesso, crítico, falha bestial e crítico descontrolado
assimilation	d6, d10, d12	Sucesso, Adaptação e Pressão

Comece por uma forma já disponível. Para formas novas, você precisará também de uma malha, collider e colliderFaceMap, conforme Crie um tema 3D.

2. Faça uma cópia dos dois atlas

Copie faces-light.svg e faces-dark.svg do tema mais parecido com o seu. Abra-os em um editor vetorial e mantenha viewBox="0 0 1024 1024", as posições das faces e a transparência. Substitua apenas os grupos de glifos. A versão light precisa contrastar com dados escuros; a dark, com dados claros. Não use o normal.webp numérico de default: ele gravaria números por baixo dos seus símbolos.

As ilhas não são uma tabela em sequência. Cada posição corresponde às coordenadas UV do modelo themes/default/default.json. Colocar o símbolo + na posição do valor 1 faz o dado exibir + quando a física entrega 1. Não mova uma ilha para “corrigir” o resultado; corrija a arte da posição original.

3. Descreva a correspondência no manifesto

Declare material.diffuseTexture para os dois SVGs, mantenha diceAvailable coerente com a geometria e use faceAtlas/faceMetadata para registrar a leitura de cada face. O exemplo Fate real usa esta correspondência:

Valor físico d6	Símbolo	Valor Fate
1–2	−	−1
3–4	vazio	0
5–6	+	+1

{
  "name": "My Fate dice",
  "systemName": "my-fate",
  "material": {
    "type": "color",
    "diffuseTexture": {
      "light": "faces-light.svg",
      "dark": "faces-dark.svg"
    },
    "diffuseLevel": 1
  },
  "diceAvailable": ["d6"],
  "faceAtlas": {
    "layoutId": "erpg-default-v1",
    "width": 1024,
    "height": 1024,
    "model": "../default/default.json"
  },
  "faceMetadata": {
    "schemaVersion": 1,
    "mappingId": "my-fate-faces-v1",
    "symbols": {
      "minus": { "label": "Menos (−1)" },
      "plus": { "label": "Mais (+1)" }
    },
    "dice": {
      "d6": {
        "1": { "label": "Menos", "symbols": ["minus"] },
        "2": { "label": "Menos", "symbols": ["minus"] },
        "3": { "label": "Vazio", "symbols": [] },
        "4": { "label": "Vazio", "symbols": [] },
        "5": { "label": "Mais", "symbols": ["plus"] },
        "6": { "label": "Mais", "symbols": ["plus"] }
      }
    }
  }
}

faceAtlas e faceMetadata são descritivos. Alterar a tabela não converte 1 em 5 nem muda a orientação do dado. Para outra regra, ajuste o Dice Core ou a transformação da aplicação e mantenha arte, metadados e valores físicos em acordo. O adaptador padrão Fate continua a escolher o tema fate; para usar my-fate, passe seu tema explicitamente aos dados que chegam ao View.

4. Confira cada face no 3D

Hospede a pasta como public/assets/dice-box/themes/my-fate/, com o manifesto e os dois SVGs. Instancie o viewer com assetPath: '/assets/dice-box/' e teste todos os valores físicos, um por vez:

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

for (const value of [1, 2, 3, 4, 5, 6]) {
  await viewer.display({
    id: `face-${value}`,
    dice: [{ id: 'sample', sides: 6, value, theme: 'my-fate', themeColor: '#315d9b' }],
    mode: 'physics'
  })
  // Confira a face visível antes da próxima iteração.
}

O código acima percorre as faces sequencialmente; para inspecionar manualmente, execute uma chamada de cada vez no seu ambiente. Repita com mode: 'physics' e com cores claras/escuras para avaliar ambos os atlas. Confira também se o valor mostrado ao usuário coincide com o valor semântico calculado pelo Core.

5. Publique a arte com sua origem

O manifesto dos temas incluídos contém artwork com autoria e licença. Faça o mesmo com os seus glifos. Use apenas arte que você pode publicar e redistribuir; os SVGs de Vampiro V5 e Assimilação presentes no pacote têm proveniência específica do projeto. Para artes oficiais de terceiros, hospede um tema externo quando apropriado e mantenha a autorização de uso documentada.

Leia a referência dos mapas para materiais, relevo e moeda, e use o editor de temas para testar o manifesto.