Dice-Box 3D Dice Roller

WorldOffScreen is an internal implementation used to manage a 3D BabylonJS world within a Web Worker via OffscreenCanvas. This allows for high-performance dice rendering that doesn't block the main UI thread.

When initializing WorldOffScreen, you must provide a canvas that has its control transferred to offscreen using canvas.transferControlToOffscreen(). The constructor accepts an options object which includes an onInitComplete callback.

Note: This class is part of the internal world implementation and is typically managed by the main @3d-dice/dice-box package rather than being instantiated directly by end-users.

// Example of the expected initialization pattern
const world = new WorldOffScreen({
  canvas: myCanvas.transferControlToOffscreen(),
  options: myDiceOptions,
  onInitComplete: (success) => {
    console.log('World initialized:', success);
  }
});

To use the on-screen canvas rendering, instantiate WorldOnscreen by passing a configuration object. The constructor accepts several lifecycle callbacks to handle initialization, theme loading, roll results, and die removal.

Key configuration requirements:

• canvas: The HTML canvas element to render into.
• width and height: Dimensions for the canvas.
• options: A sub-object containing dice-specific settings (e.g., assetPath, enableShadows, scale).

Available callbacks in the options object:

• onInitComplete: Called when the BabylonJS scene is ready.
• onThemeLoaded: Called when a theme has been successfully loaded.
• onRollResult: Called when a die stops moving and its value is determined.
• onRollComplete: Called when all dice in a roll have come to rest.
• onDieRemoved: Called when a die is removed from the scene.

const world = new WorldOnscreen({
  canvas: myCanvasElement,
  width: 800,
  height: 600,
  onInitComplete: () => console.log('Ready!'),
  onRollResult: ({ rollId, value }) => console.log(`Die ${rollId} rolled: ${value}`),
  options: {
    assetPath: '/assets/dice/',
    enableShadows: true,
    scale: 1
  }
});

The WorldFacade constructor accepts a configuration object. Below are the primary available keys:

You can monitor the lifecycle of dice rolls using callback functions passed in the configuration object:

• onBeforeRoll(parsedNotation): Triggered before dice are generated.
• onDieComplete(die): Triggered when an individual die finishes its roll. Returns the die object (excluding internal IDs).
• onRollComplete(results): Triggered when an entire roll collection is finished. Returns an array of roll group objects.
• onCollision(body0Id, body1Id, force): Triggered when two dice bodies collide.
• onThemeLoaded(themeConfig): Triggered when a theme is successfully loaded.
• onThemeConfigLoaded(themeConfig): Triggered when the theme configuration JSON is fetched.

const diceBox = new WorldFacade({
  onDieComplete: (die) => console.log(`Die ${die.id} rolled a ${die.value}`),
  onRollComplete: (results) => console.log('All rolls finished:', results),
  onCollision: (id1, id2, force) => console.log(`Collision between ${id1} and ${id2} with force ${force}`)
});

Dice-Box provides two primary ways to trigger dice rolls:

1. roll(notation, options): Clears the current dice box and performs a new roll. This is typically used for a fresh roll sequence.
2. add(notation, options): Adds new dice to the existing scene without clearing previous dice.

Notation Formats:

• String: '4d6', '2d10+3', 'd100', '1d20f' (fudge/fate).
• Object: { sides: 6, qty: 4, modifier: 2 }.
• Array: ['4d6', '2d10'].

Both methods return a Promise that resolves when the roll collection is complete (i.e., all dice have finished rolling).

// A fresh roll that clears the box
await diceBox.roll('2d20+5');

// Adding more dice to the current scene
await diceBox.add({ sides: 6, qty: 2, themeColor: '#ff0000' });

// Reroll specific dice (removes them and adds new ones)
await diceBox.reroll([{ sides: 6, qty: 1 }], { remove: true });