Themes and assets

A theme controls polyhedron materials, textures, and the d2 coin’s appearance. It does not alter values or rules. Each die can select its own theme and color within a presentation. Explore the five bundled looks in the texture gallery before making your own.

Public assets

Host the package’s dist/assets/dice-box/ directory at a public URL. The default is /assets/dice-box/:

public/assets/dice-box/
├── havok/HavokPhysics.wasm
└── themes/
    ├── default/
    ├── default-v2/
    ├── vampire-v5-normal/
    ├── vampire-v5-hunger/
    ├── assimilation/
    └── fate/

default uses numbers. Vampire, Assimilation, and Fate themes draw symbols on numeric physical faces. Daggerheart Hope/Fear profiles use default-v2.

Select a theme and color

const viewer = new DiceResultViewer({
  container: '#dice-stage',
  assetPath: '/assets/dice-box/',
  theme: 'default',
  themeColor: '#e60049',
  preloadThemes: ['default-v2']
})

await viewer.display({
  id: 'colors-1',
  dice: [
    { id: 'pink', sides: 20, value: 18, themeColor: '#e60049' },
    { id: 'blue', sides: 6, value: 4, themeColor: '#315d9b' }
  ]
})

Per-die theme and themeColor override viewer defaults. For color materials, themeColor defines the surface base; for standard, the texture supplies the main color. preloadThemes is consumed by init().

External theme

const viewer = new DiceResultViewer({
  container: '#dice-stage',
  externalThemes: {
    bronze: 'https://static.example.com/dice/bronze'
  }
})

await viewer.display({
  id: 'bronze-1',
  dice: [{ id: 'd20', sides: 20, value: 18, theme: 'bronze' }]
})

The URL must point to a folder containing theme.config.json; enable CORS across origins. Relative textures start at that folder. meshFile is relative too. Without meshFile, View uses the default model.

Cache and updates

View caches configurations by name, models by URL, and materials by theme, color, and discarded state. onThemeConfigLoaded reports a configuration loaded outside the cache; onThemeLoaded fires once per theme used in a presentation. updateOptions() can change compatible visual settings. To replace an already loaded theme definition or asset root, dispose the viewer and create another instance.

Read Texture maps for diffuse, normal, specular, and coin art. Follow Create a 3D theme to build and publish the folder, or Customize symbolic faces to replace numerals with glyphs. The theme editor provides an interactive preview.