Customize symbolic faces

This guide builds symbolic artwork on the bundled meshes using the real maps in the gallery. Dice Core results still land on the correct physical face; the theme changes only what players see.

1. Choose a physical die

The atlas belongs to geometry, not the game rule. Bundled examples provide:

Theme	Physical die	Atlas artwork
fate	d6	−, blank, +
vampire-v5-normal	d10	success and critical
vampire-v5-hunger	d10	success, critical, bestial failure, and messy critical
assimilation	d6, d10, d12	Success, Adaptation, and Pressure

Start with an available shape. A new shape also needs a mesh, collider, and colliderFaceMap, covered in Create a 3D theme.

2. Copy both atlases

Copy faces-light.svg and faces-dark.svg from the closest bundled theme. Open them in a vector editor and keep viewBox="0 0 1024 1024", face positions, and transparency. Replace glyph groups only. The light variant should contrast on dark dice; dark on light dice. Do not reuse the numeric normal.webp from default: it would engrave numerals beneath your new symbols.

The islands are not a sequential table. Each position corresponds to UV coordinates in themes/default/default.json. Placing + in value 1’s position makes the die show + when physics returns 1. Do not move an island to “fix” a result; correct the artwork in its original position.

3. Describe the mapping in the manifest

Point material.diffuseTexture at both SVGs, keep diceAvailable aligned with geometry, and record each face’s reading in faceAtlas/faceMetadata. The bundled Fate example uses this mapping:

Physical d6 value	Symbol	Fate value
1–2	−	−1
3–4	blank	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": "Minus (−1)" },
      "plus": { "label": "Plus (+1)" }
    },
    "dice": {
      "d6": {
        "1": { "label": "Minus", "symbols": ["minus"] },
        "2": { "label": "Minus", "symbols": ["minus"] },
        "3": { "label": "Blank", "symbols": [] },
        "4": { "label": "Blank", "symbols": [] },
        "5": { "label": "Plus", "symbols": ["plus"] },
        "6": { "label": "Plus", "symbols": ["plus"] }
      }
    }
  }
}

faceAtlas and faceMetadata are descriptive. Editing this table does not convert 1 into 5 or change the die’s orientation. For a different rule, change Dice Core or your application’s transformation and keep artwork, metadata, and physical values aligned. The standard Fate adapter still selects fate; pass my-fate explicitly on dice sent to View.

4. Check every face in 3D

Host the folder at public/assets/dice-box/themes/my-fate/, with the manifest and both SVGs. Set assetPath: '/assets/dice-box/' and test every physical value, one at a time:

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'
  })
  // Inspect the visible face before the next iteration.
}

The snippet runs sequentially; for manual inspection, execute one call at a time in your app. Repeat with mode: 'physics' and both light/dark colors to check both atlases. Also compare the displayed result with the semantic value calculated by Core.

5. Publish artwork with its provenance

Bundled manifests include artwork authorship and license metadata. Do the same for your glyphs. Publish only artwork you can redistribute; the bundled Vampire V5 and Assimilation SVGs have project-specific provenance. If you host third-party official artwork externally, keep the permission to use it documented.

Read Texture maps for materials, relief, and coin art, then use the theme editor to test your manifest.