Viewer configuration
Every public DiceResultViewer option, its default, callbacks, and update limits.
This article documents the published v2. For the current physics preview, see the v3 guide. V3 ↗ Licenses ↗
Pass options to new DiceResultViewer(options) and, when compatible, to await viewer.updateOptions(options). The public type is ViewerOptions. The defaults below match package 2.6.1.
Core and themes
| Option | Default | Use |
|---|---|---|
id |
dice-canvas-${Date.now()} |
Canvas ID |
container |
null |
Selector or HTMLElement; an existing element is required in practice |
assetPath |
/assets/dice-box/ |
Public asset root |
origin |
Page origin | Origin for built-in assets |
mode |
kinematic |
kinematic or physics |
theme |
default |
Default theme |
preloadThemes |
[] |
Themes loaded by init() |
externalThemes |
{} |
Theme name to base folder URL map |
themeColor |
#2e8555 |
Default surface color |
maxDice |
120 |
Visual body limit; d100 counts as two |
Scene and entry
| Option | Default | Use |
|---|---|---|
enableShadows |
true |
Shadows |
shadowTransparency |
0.8 |
Shadow-map transparency (0..1) |
shadowResolution |
1024 |
Positive integer shadow-map resolution |
lightIntensity |
1 |
Lighting multiplier |
antialias |
true |
Engine antialiasing |
scale |
5 |
Object scale |
duration |
1100 ms |
Base kinematic duration |
delay |
10 ms |
Release gap per visual body |
wallPadding |
0.25 |
Playable-area inset |
spawnSpacing |
1.72 |
Requested portal spacing |
spawnHeightStep |
0 |
Optional vertical offset |
spawnOverscan |
0.15 |
Extra offscreen margin as a fraction of body radius |
Effective duration has a 250 ms minimum plus release delays. Packing can create later waves when one edge has no room.
Physics
| Option | Default | Use |
|---|---|---|
gravity |
1.3 |
Multiplier on −9.81 |
mass |
1.08 |
Base mass |
startingHeight |
7.6 |
Release plane; effective height is internally capped |
spinForce |
5.8 |
Spin scaling |
throwForce |
6.4 |
Throw strength |
aggressiveThrowChance |
0.12 |
Per-presentation chance of higher energy (0..1) |
wallBounceChance |
deprecated alias | Use aggressiveThrowChance; no collision guarantee |
colliderScale |
1.02 |
Polyhedron collider scaling |
friction |
0.54 |
Floor and die friction |
restitution |
0.29 |
Floor and die bounce |
linearDamping |
0.10 |
Initial linear damping |
angularDamping |
0.08 |
Angular damping after impact |
settleTimeout |
4200 ms |
Safety window; never determines value |
physicsWasmUrl |
'' |
Explicit Havok WASM URL |
Timeline
timeline.enabled defaults to true, maxEvents to 500, maxDurationMs to 12000, and phaseGapMs to 180. All effects start enabled: explode, compound, penetrate, reroll, unique, keep, drop, success, failure, neutral, criticalSuccess, and criticalFailure. Each accepts enabled, delayMs, durationMs, intensity (0..1), and color. Specific fields and examples are in Semantic timeline.
Callbacks
| Option | Argument | When |
|---|---|---|
onCollision |
{ action: 'collision', body0Id?, body1Id?, force } |
Contact in physics mode |
onThemeConfigLoaded |
ResolvedThemeConfig |
Configuration resolved outside cache |
onThemeLoaded |
ResolvedThemeConfig |
Theme used in a presentation |
onTimelineProgress |
TimelineProgressEvent |
initial, phase, or complete snapshot |
Updating and validation
updateOptions() merges options and performs a deep merge for each timeline effect. Changes to container, id, antialias, shadowResolution, gravity, physicsWasmUrl, or an already loaded asset root/definition require a new instance. preloadThemes is used only during init().
Invalid modes, non-finite values, incoherent limits, non-function callbacks, and invalid basic theme or coin structures are rejected. An invalid update keeps the previous valid options. See API for methods and contracts.