Dice View API

Public contract for @erpg/dice3dview 2.6.1. View is a presentation layer; the caller supplies values and rules.

Entrypoints

Import	Use
@erpg/dice3dview/external	Renderer for bundled apps with shared Babylon
@erpg/dice3dview/adapters	Pure converters without graphics renderer
@erpg/dice3dview/style.css	Canvas styles
@erpg/dice3dview	Self-contained build for compatibility and CDN

DiceResultViewer

Member	Contract	Effect
canvas	HTMLCanvasElement	Canvas created in constructor
constructor(options?)	ViewerOptions	Attaches canvas to container
init()	Promise<this>	Initializes renderer, theme, and resize observer; idempotent
display(request)	Promise<DisplayResult>	Presents resolved faces; initializes if needed
displayTimeline(request)	Promise<DisplayTimelineResult>	Executes validated semantic journal
clear()	void	Cancels presentation and clears scene
updateOptions(options)	Promise<void>	Merges compatible options
resize()	void	Recalculates stage, floor, and walls
dispose()	void	Frees resources and removes canvas; idempotent

After dispose(), create a new instance. A new presentation or clear() rejects the previous Promise with DisplayCancelledError.

display()

type DiceSides = 2 | 4 | 6 | 8 | 10 | 12 | 20 | 100
type DisplayMode = 'kinematic' | 'physics'

interface ResolvedDie {
  id: string
  sides: DiceSides
  value: number
  discarded?: boolean
  theme?: string
  themeColor?: string
}

interface DisplayRequest {
  id: string
  dice: readonly ResolvedDie[]
  seed?: string
  mode?: DisplayMode
}

interface DisplayResult {
  id: string
  dice: readonly ResolvedDie[]
  durationMs: number
}

id and dice cannot be empty. value must be a finite integer from 1 to sides; d2 accepts only 1 or 2. seed defaults to request.id; mode, theme, and themeColor use viewer defaults; discarded defaults to false. An empty die ID becomes ${request.id}-die-${index}. The result contains normalized, frozen clones. durationMs includes lazy initialization, theme loading, and animation.

After validation, display() logs graphical, asset, or physics failures and still returns the normalized result. It never recalculates faces.

displayTimeline()

The request contains id, dice: TimelineDieDefinition[] (each with id, sides, optional theme/color), events: DiceTimelineEvent[], seed?, and mode?. Definitions have no value; events provide faces. Its result adds eventCount, phaseCount, and degraded to DisplayResult. Runtime failures propagate. See Semantic timeline for each event.

Adapters

@erpg/dice3dview/adapters exports createSystemDisplayRequest, createMixedDisplayRequest, toSystemResolvedDie, toSystemResolvedDice, toMixedResolvedDice, SYSTEM_THEME_PROFILES, getSystemThemeProfile, and isSystemDiceProfileId.

createSystemDisplayRequest({ id, dice, seed?, mode?, keptIds?, themeColors? }) validates sides with each die’s profileId and applies theme/color. keptIds accepts an ID or sourceDieId; other dice are shown as discarded. Duplicate IDs are rejected.

createMixedDisplayRequest({ id, dice, seed?, mode?, unsupportedDice?, theme?, themeColor?, keptIds?, themeColors? }) accepts the flat rollMixedDice().dice list. It uses physicalValue ?? rawValue ?? value. Unsupported generic shapes are omitted by default (unsupportedDice: 'omit'); 'error' rejects. System profiles are always validated. If all dice are omitted, the adapter rejects.

Cancellation

import { isDisplayCancelledError } from '@erpg/dice3dview/external'

try {
  await viewer.display(request)
} catch (error) {
  if (isDisplayCancelledError(error)) return
  throw error
}

DisplayCancelledError and DISPLAY_CANCELLED_CODE ('DISPLAY_CANCELLED') are also exported. Use the helper to recognize cancellation across bundles.

See Configuration for every option and Core integration for complete examples.