three-dice-roll

Reusable Three.js dice components with deterministic end results.

The package exports:

• DiceComponent: full casino-style three-dice game scene
• SpinnerDiceComponent: one spinner-style die

The animations are authored, not physics-simulated. A result is chosen first, then the component animates toward a valid final orientation for that result.

Install

npm install three-dice-roll three

three is a peer dependency and must be installed by the consuming app.

Usage

Three dice

import { DiceComponent } from 'three-dice-roll';
import 'three-dice-roll/style.css';

const dice = new DiceComponent({
  container: document.getElementById('app'),
  result: [2, 5, 6],
  time: 10,
  startRoll: 1,
  rollDoneCallBack(results) {
    console.log(results);
  },
});

dice.setProps({
  result: [1, 1, 1],
  startRoll: 2,
});

Spinner die

import { SpinnerDiceComponent } from 'three-dice-roll';
import 'three-dice-roll/style.css';

const spinner = new SpinnerDiceComponent({
  container: document.getElementById('app'),
  result: 4,
  startRoll: 1,
  rollDoneCallBack(result) {
    console.log(result);
  },
});

API

DiceComponent

Wraps the full three-dice casino game scene:

• table stage
• plate
• dome
• roll button and hand art
• Three.js dice renderer and roll animation

Props:

• container?: HTMLElement
• result?: number[] | null
• rollDoneCallBack?: (results: number[]) => void
• startRoll?: boolean | number | string
• interactive?: boolean
• time?: number countdown duration in seconds before auto-roll
• countdownTickMs?: number countdown interval in milliseconds

Methods:

• setProps(nextProps)
• roll(result?)
• getResults()
• destroy()

SpinnerDiceComponent

Props:

• container?: HTMLElement
• result?: number | null
• rollDoneCallBack?: (result: number) => void
• startRoll?: boolean | number | string
• interactive?: boolean

Methods:

• setProps(nextProps)
• roll(result?)
• getResult()
• destroy()

Notes

• Ships ESM and CommonJS entrypoints
• Ships a Vite library build from dist/
• Requires a bundler that can compile ESM dependencies

Next.js

Use the components from a client component and import three-dice-roll/style.css once in that client boundary or in your app styles. There is a working example in examples/next-ts.

Local development

npm install
npm run dev
npm run build
npm run publish:dry-run