Troubleshoot Dice View

The canvas does not appear

1. Create DiceResultViewer on the client after container exists. The library needs the DOM, and initialization needs WebGL.
2. Give the container width and height. For an overlay, use position: fixed; inset: 0.
3. Import @erpg/dice3dview/style.css.
4. Check the console and the request for themes/default/theme.config.json.

A theme or model fails to load

Confirm that dist/assets/dice-box/ was copied to the path configured by assetPath. theme.config.json must return 200. Relative texture and meshFile paths begin at the theme folder. For externalThemes, check CORS. If you replaced files already loaded under the same name, dispose and recreate the viewer to invalidate templates.

Physics mode does not start

Check /assets/dice-box/havok/HavokPhysics.wasm or the explicit physicsWasmUrl. Prefer serving WASM as application/wasm. Try kinematic to isolate a Havok issue. Physics mode loads the runtime on demand.

A die is missing

display() accepts only d2, d4, d6, d8, d10, d12, d20, and d100 with values from 1 to the number of sides. createMixedDisplayRequest() omits unsupported generic shapes by default. Use unsupportedDice: 'error' to detect omission. d3 is shown on d6; generic dF has no representation, but the Fate profile uses a physical d6. Check maxDice too: each d100 takes two bodies.

A Promise rejects when another roll starts

This is expected cancellation. A new presentation, clear(), or dispose() rejects the previous Promise with DisplayCancelledError. Handle it with isDisplayCancelledError(error) and rethrow other errors.

Timeline playback skips phases

Check result.degraded. timeline.enabled: false, more than maxEvents, or an estimated duration above maxDurationMs cause a flat final-state presentation. An invalid journal, such as a missing ID, out-of-order sequence, or inconsistent explosion relationship, rejects before changing the scene. Read Semantic timeline.