3D Dice

https://fantasticdice.games/docs/intro
Admin
A high-performance 3D dice roller built with BabylonJS and AmmoJS, designed for easy integration...
Tokens:39,774
Snippets:331
Trust Score:6.2
Update:9 months ago
Show doc for...
Tokens:
Raw
### Advanced Roller Setup and Configuration

Source: https://fantasticdice.games/docs/addons/advRoller

This section details how to set up and configure the Advanced Roller, including installation, instantiation, and available configuration options.

```APIDOC
## Installation

Add the dice-ui module using:

```bash
npm install @3d-dice/dice-ui
```

## Setup

Create a new instance of the roller:

```javascript
import { AdvancedRoller } from '@3d-dice/dice-ui'

const Roller = new AdvancedRoller()
```

### Config Options

The `AdvancedRoller` constructor accepts a configuration object with the following options:

#### Parameters

- **target** (`string`: DOM node selector) - Optional - The target DOM node to inject the roller into. Defaults to `document.body`.
- **onSubmit** (`function`) - Optional - Callback triggered on form submit, after notation has been parsed. Defaults to a no-operation function.
- **onClear** (`function`) - Optional - Callback triggered when the form reset event is triggered. Defaults to a no-operation function.
- **onReroll** (`function`) - Optional - Callback triggered when FDP returns reroll results. Defaults to a no-operation function.
- **onResults** (`function`) - Optional - Callback triggered when there are no reroll results and the final result object has been parsed by FDP. Defaults to a no-operation function.

### Example Usage with Callbacks

```javascript
const Roller = new AdvancedRoller({
  target: '#roller-container',
  onSubmit: (notation) => {
    console.log('Submit callback:', notation);
    // diceBox.roll(notation);
  },
  onClear: () => {
    console.log('Clear callback');
    // diceBox.clear();
    // Display.clear();
  },
  onReroll: (rolls) => {
    console.log('Reroll callback:', rolls);
    // rolls.forEach(roll => diceBox.add(roll));
  },
  onResults: (results) => {
    console.log('Results callback:', results);
    // Display.showResults(results);
  }
});
```
```

--------------------------------

### Create a Dice Box instance

Source: https://fantasticdice.games/docs/usage/config

Create a new instance of the DiceBox class with configuration options. The `assetPath` is a mandatory configuration option, specifying the location of the Dice Box static assets. Ensure the path includes a trailing backslash.

```javascript
const diceBox = new DiceBox({
  assetPath: '/assets/dice-box/' // include the trailing backslash
})
```

--------------------------------

### Install Fantastic Dice Parser

Source: https://fantasticdice.games/docs/0.6/addons/parser

Instructions on how to install the @3d-dice/fdp library using npm. This is the primary method for integrating the parser into your project.

```bash
npm install @3d-dice/fdp  

```

--------------------------------

### Initialize Dice-Box and Roll Dice (JavaScript)

Source: https://fantasticdice.games/docs/usage/config

Demonstrates how to initialize the Dice-Box instance and initiate a dice roll. The `init` method returns a Promise, allowing for either `.then()` chaining or `await` usage. The `roll` method takes a notation string (e.g., '2d20') to specify the dice to roll.

```javascript
diceBox.init().then(() => {
  diceBox.roll('2d20');
});
```

```javascript
await diceBox.init();
diceBox.roll('2d20');
```

--------------------------------

### Setup Dice Parser Instance

Source: https://fantasticdice.games/docs/0.6/addons/parser

Demonstrates how to import and create a new instance of the DiceParser class from the @3d-dice/fdp library. This instance is then used to call parsing methods.

```javascript
import DiceParser from '@3d-dice/fdp'  

const DRP = new DiceParser()  

```

--------------------------------

### Setup DicePicker Instance

Source: https://fantasticdice.games/docs/addons/dicePicker

Demonstrates how to import and create a new instance of the DicePicker class from the @3d-dice/dice-ui module. This sets up the basic UI for dice selection.

```javascript
import { DicePicker } from '@3d-dice/dice-ui'  

const dicePicker = new DicePicker()
```

--------------------------------

### Setup Advanced Roller Instance

Source: https://fantasticdice.games/docs/addons/advRoller

Import the AdvancedRoller class from the @3d-dice/dice-ui package and create a new instance. This is the basic setup to initialize the roller component.

```javascript
import { AdvancedRoller } from '@3d-dice/dice-ui'  

const Roller = new AdvancedRoller()  
```

--------------------------------

### Install Dice-Box Module

Source: https://fantasticdice.games/docs/1.0.14/usage/config

Installs the core Dice-Box library from npm. This command should be run in your project's terminal.

```bash
npm install @3d-dice/dice-box
```

--------------------------------

### Theme Configuration Example

Source: https://fantasticdice.games/docs/1.0.14/themes

Example of how to configure mesh name and file path within a theme's configuration. This allows themes to reference shared 3D models located in a common assets folder.

```json
{
  "meshName": "gemstone",  
  "meshFile": "../../models/gemstone.json" 
}
```

--------------------------------

### Install Dice Parser Interface using npm

Source: https://fantasticdice.games/docs/1.0.14/addons/parser

Install the Dice Parser Interface library using npm. This is the first step to integrate the parser into your project. No specific inputs or outputs are required for installation.

```bash
npm install @3d-dice/dice-parser-interface  

```

--------------------------------

### GenesysDicePicker Installation

Source: https://fantasticdice.games/docs/addons/genesysDicePicker

Install the dice-ui module using npm.

```APIDOC
## Install

Add the dice-ui module using
```
npm install @3d-dice/dice-ui
```
```

--------------------------------

### Setup Advanced Roller Instance

Source: https://fantasticdice.games/docs/1.0.14/addons/advRoller

Demonstrates how to import and create a new instance of the Advanced Roller. This involves importing the class and instantiating it, optionally with configuration.

```javascript
import { AdvancedRoller } from '@3d-dice/dice-ui'  

const Roller = new AdvancedRoller()

```

--------------------------------

### GenesysDicePicker Setup

Source: https://fantasticdice.games/docs/addons/genesysDicePicker

Set up the GenesysDicePicker by creating a new instance.

```APIDOC
## Setup

Then create a new instance of the picker
```javascript
import { GenesysDicePicker } from '@3d-dice/dice-ui'

const dicePicker = new GenesysDicePicker()
```
```

--------------------------------

### Install Rock Theme Package

Source: https://fantasticdice.games/docs/themes/rock

This snippet shows how to install the Rock theme package using npm. Ensure you have Node.js and npm installed on your system.

```bash
npm install @3d-dice/theme-rock  

```

--------------------------------

### Setup Dice Picker Instance

Source: https://fantasticdice.games/docs/1.0.14/addons/dicePicker

Demonstrates how to import and create a new instance of the DicePicker class. This sets up the basic UI module for dice selection.

```javascript
import { DicePicker } from '@3d-dice/dice-ui'  

const dicePicker = new DicePicker()  
```

--------------------------------

### Configure Dice Box for unpkg CDN

Source: https://fantasticdice.games/docs/usage/config

Configure the assetPath and origin options when using the Dice Box ES module from the unpkg CDN. These settings ensure that the module can correctly locate its required assets, such as dice textures and models.

```javascript
  assetPath: "assets/",  
  origin: "https://unpkg.com/@3d-dice/dice-box@1.1.3/dist/"
```

--------------------------------

### Install FUI Module with npm

Source: https://fantasticdice.games/docs/0.6/addons/dicePicker

This command installs the FUI module, which includes the DicePicker component, using npm. This is the first step to incorporating the DicePicker into your project.

```bash
npm install @3d-dice/fui  
```

--------------------------------

### Import Dice Box as an ES Module via unpkg CDN

Source: https://fantasticdice.games/docs/usage/config

Import the Dice Box module directly as an ES module using the unpkg CDN. This method is suitable for projects that don't use a build system or for quick testing. Note that using the CDN may limit you to the default dice set.

```javascript
import DiceBox from "https://unpkg.com/@3d-dice/dice-box@1.1.3/dist/dice-box.es.min.js";
```

--------------------------------

### Genesys Results Module API

Source: https://fantasticdice.games/docs/addons/genesysResults

This section details the installation, setup, configuration, methods, styles, and tooltips for the Genesys Results module.

```APIDOC
## Genesys Results Module

### Description
This module takes the final result object as input and creates a modal popup window displaying the final roll result totals. It supplies symbols matching the dice face values and colorizes them to match the die that produced them. This module is for use with the Genesys dice theme and serves as an example for creating custom UI interfaces.

### Installation
Add the dice-ui module using npm:
```
npm install @3d-dice/dice-ui
```

### Setup
Create a new instance of the roller:
```javascript
import { GenesysResults } from '@3d-dice/dice-ui'

const Display = new GenesysResults()
```

### Configuration
The constructor accepts one argument:

#### Parameters
- **target** (`string` :dom node selector) - Optional - The target DOM node selector to inject the display results into. Defaults to `document.body`.

### Methods

#### `showResults(rollResults: object)`

##### Description
Takes roll results as input and generates a popup display.

#### `clear()`

##### Description
Hides the popup display with a CSS transition effect.

### Styles
All styles are scoped to `.genesysResults`.

#### CSS Classes
- `die-boost`
- `die-setback`
- `die-ability`
- `die-difficulty`
- `die-challenge`
- `die-proficiency`

**Note**: Empty faces with no value are not shown in the results.

### Tooltips
A simple tooltip is implemented to help identify the symbols on hover.
```

--------------------------------

### Install @3d-dice/dice-ui Module

Source: https://fantasticdice.games/docs/1.0.14/addons/displayResults

Installs the dice-ui module, which includes the DisplayResults component, using npm. This is a prerequisite for using the DisplayResults functionality.

```bash
npm install @3d-dice/dice-ui
```

--------------------------------

### Setup DicePicker Instance in JavaScript

Source: https://fantasticdice.games/docs/0.6/addons/dicePicker

This code demonstrates how to import and create a new instance of the DicePicker class from the '@3d-dice/fui' module. This instance can then be configured and used to manage dice selection.

```javascript
import { DicePicker } from '@3d-dice/fui'  
  
const dicePicker = new DicePicker()  
```

--------------------------------

### Install Rust Theme (npm)

Source: https://fantasticdice.games/docs/themes/rust

Installs the Rust theme package using npm. This command is used to add the theme to your project's dependencies.

```bash
npm install @3d-dice/theme-rust  

```

--------------------------------

### Parse Dice Notation from User Input

Source: https://fantasticdice.games/docs/1.0.14/addons/parser

An example of parsing dice notation from a user input field. It demonstrates how to get the notation string from an input element and pass it to the `parseNotation` method of the DiceParser instance. This requires HTML form elements and JavaScript event listeners.

```javascript
const form = document.getElementById("dice-to-roll")  
const notationInput = document.getElementById("input--notation")  
  
const submitForm = (e) => {  
  e.preventDefault();  
	const notation = DP.parseNotation(notationInput.value)  
}

form.addEventListener("submit", submitForm)  

```

--------------------------------

### Install @3d-dice/dice-ui Package

Source: https://fantasticdice.games/docs/1.0.14/addons/advRoller

This snippet shows how to install the dice-ui module using npm. It's a prerequisite for using the Advanced Roller component.

```bash
npm install @3d-dice/dice-ui  

```

--------------------------------

### GenesysDicePicker setNotation Example

Source: https://fantasticdice.games/docs/addons/genesysDicePicker

Example of how to use the `setNotation` method to set default values for dice rolls.

```APIDOC
`setNotation` example:
```javascript
dicePicker.setNotation({
  ability: {
    count: 0
  },
  boost: {
    count: 0
  },
  challenge: {
    count: 0
  },
  difficulty: {
    count: 0
  },
  proficiency: {
    count: 0
  },
  setback: {
    count: 0
  }
})
```
```

--------------------------------

### Setup Dice Parser Instance

Source: https://fantasticdice.games/docs/1.0.14/addons/parser

Set up a new instance of the DiceParser class. This involves importing the class and creating a new object. The `DP` instance will then be used to call parsing methods.

```javascript
import DiceParser from '@3d-dice/dice-parser-interface'  
  
const DP = new DiceParser()  

```

--------------------------------

### Setup Advanced Roller Instance in JavaScript

Source: https://fantasticdice.games/docs/0.6/addons/advRoller

This JavaScript code demonstrates how to set up a new instance of the AdvancedRoller. It requires importing the class from the '@3d-dice/fui' package.

```javascript
import { AdvancedRoller } from '@3d-dice/fui'  

const Roller = new AdvancedRoller()

```

--------------------------------

### Install dice-ui Module

Source: https://fantasticdice.games/docs/1.0.14/addons/boxControls

Installs the necessary dice-ui module using npm. This module provides the Box Controls functionality for interacting with Dice-Box configurations.

```bash
npm install @3d-dice/dice-ui  
```

--------------------------------

### Setup Box Controls Instance in JavaScript

Source: https://fantasticdice.games/docs/0.6/addons/boxControls

This code demonstrates how to import and instantiate the BoxControls class. The `onUpdate` callback function is crucial for receiving configuration updates and applying them to the Dice-Box instance.

```javascript
import { BoxControls } from '@3d-dice/fui'  
  
const Controls = new BoxControls({
  onUpdate: (updates) => {
    diceBox.updateConfig(updates)
  }
})

```

--------------------------------

### Setup DisplayResults Component

Source: https://fantasticdice.games/docs/0.6/addons/displayResults

Demonstrates how to import and create a new instance of the DisplayResults component from the '@3d-dice/fui' package. This component is used to render dice roll outcomes.

```javascript
import { DisplayResults } from '@3d-dice/fui'  
  
const Display = new DisplayResults()  

```

--------------------------------

### Install Genesys Theme using npm

Source: https://fantasticdice.games/docs/themes/genesys

This command installs the Genesys theme package for 3D Dice using npm. It is a prerequisite for using the symbol-based dice in your project.

```bash
npm install @3d-dice/theme-genesys  

```

--------------------------------

### Install FUI Module with npm

Source: https://fantasticdice.games/docs/0.6/addons/boxControls

This snippet shows how to add the FUI module to your project using npm. It is a prerequisite for using the Box Controls functionality.

```bash
npm install @3d-dice/fui  

```

--------------------------------

### Setup DisplayResults Instance with JavaScript

Source: https://fantasticdice.games/docs/1.0.14/addons/displayResults

Demonstrates how to import and create a new instance of the DisplayResults class from the @3d-dice/dice-ui package. This instance is used to manage and display dice roll results.

```javascript
import { DisplayResults } from '@3d-dice/dice-ui'

const Display = new DisplayResults()
```

--------------------------------

### Setup Genesys Results Component

Source: https://fantasticdice.games/docs/addons/genesysResults

This JavaScript code demonstrates how to import and instantiate the GenesysResults component from the @3d-dice/dice-ui library. The `GenesysResults` class is initialized to create a new instance of the roller UI.

```javascript
import { GenesysResults } from '@3d-dice/dice-ui'

const Display = new GenesysResults()
```

--------------------------------

### Setup Box Controls Instance

Source: https://fantasticdice.games/docs/1.0.14/addons/boxControls

Sets up a new instance of BoxControls and configures its onUpdate callback. The onUpdate function is designed to receive configuration updates and pass them to the Dice-Box's updateConfig method.

```javascript
import { BoxControls } from '@3d-dice/dice-ui'  
  
const Controls = new BoxControls({
  onUpdate: (updates) => {
    diceBox.updateConfig(updates)
  }
})

```

--------------------------------

### Handle Form Submission for Dice Notation

Source: https://fantasticdice.games/docs/0.6/addons/parser

Example of attaching an event listener to a form to capture user input for dice notation. It then uses the DRP.parseNotation method to process the input.

```javascript
const form = document.getElementById("dice-to-roll")  
const notationInput = document.getElementById("input--notation")  

const submitForm = (e) => {  
  e.preventDefault();  
	const notation = DRP.parseNotation(notationInput.value)  
}

form.addEventListener("submit", submitForm)  

```

--------------------------------

### Handle Theme Configuration Loading with onThemeConfigLoaded

Source: https://fantasticdice.games/docs/1.0.14/usage/callbacks

The `onThemeConfigLoaded` callback is triggered after a theme configuration file is successfully fetched and parsed. It provides the parsed theme configuration data as an argument, facilitating theme setup.

```javascript
diceBox.onThemeConfigLoaded = (config) => console.log('theme config data', config)
```

--------------------------------

### Configure Advanced Roller with onClear Callback

Source: https://fantasticdice.games/docs/0.6/addons/advRoller

This JavaScript example shows the AdvancedRoller configuration including both onSubmit and onClear callbacks. The onClear callback is designed to clear the dice box and the display after the parser is cleared.

```javascript
const Roller = new AdvancedRoller({
  target: '#roller',
  onSubmit: (notation) => {
    diceBox.roll(notation)
  },
  onClear: () => {
    diceBox.clear()
    Display.clear()  // Display refers to Display Results module available in @3d-dice/fui
  }
})

```

--------------------------------

### Instantiate DiceBox with Configuration

Source: https://fantasticdice.games/docs/0.6/usage/config

This code demonstrates how to create a new instance of the DiceBox class. It requires a DOM selector for the target element and a configuration object. The `assetPath` is a mandatory configuration option.

```javascript
const diceBox = new DiceBox("#dice-box", {
  assetPath: '/assets/'
})

```

--------------------------------

### Initialize DiceBox and Roll Dice

Source: https://fantasticdice.games/docs/0.6/usage/config

This example shows the process of initializing the DiceBox instance and then performing a dice roll. The `init` method is asynchronous and can be handled with `.then()` or `async/await`. After initialization, the `roll` method can be called with a dice notation string.

```javascript
diceBox.init().then(() =>{
  diceBox.roll('2d20')
})

```

--------------------------------

### Setup Genesys Dice Picker Instance (JavaScript)

Source: https://fantasticdice.games/docs/addons/genesysDicePicker

Sets up a new instance of the GenesysDicePicker. This involves importing the class and creating a new object, optionally passing a configuration object for customization. The target DOM node and callback functions can be configured here.

```javascript
import { GenesysDicePicker } from '@3d-dice/dice-ui'  

const dicePicker = new GenesysDicePicker()
```

--------------------------------

### Example Parsed Notation JSON

Source: https://fantasticdice.games/docs/addons/parser

This is an example of the JSON output returned by the `parseNotation` method when given the input '4d6'. It details the die type, count, modifiers, and other structural information about the dice roll notation.

```json
{
  "die": {
    "type": "number",
    "value": 6
  },
  "count": {
    "type": "number",
    "value": 4
  },
  "type": "die",
  "mods": [],
  "root": true,
  "label": ""
}

```

--------------------------------

### Exploding Dice Roll Result Example

Source: https://fantasticdice.games/docs/0.6/usage/objects

Demonstrates the structure for a roll involving exploding dice, specifically '1d6' that explodes twice. The example highlights how `rollId` can be a decimal to associate chained rolls, showing the results and cumulative value.

```json
[
  {
    "qty": 3,
    "sides": 6,
    "mods": [
      {
        "type": 'explode',
        "target": null
      }
    ],
    "rolls": [
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 0,
        "theme": 'diceOfRolling',
        "value": 6
      },
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 0.1,
        "theme": 'diceOfRolling',
        "value": 6
      },
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 0.2,
        "theme": 'diceOfRolling',
        "value": 5
      }
    ],
    "id": 0,
    "value": 17
  }
]
```

--------------------------------

### Exploding Dice Roll Result Example (JSON)

Source: https://fantasticdice.games/docs/1.0.14/usage/objects

This example illustrates the structure of a roll result where dice can explode. The `rollId` of the exploding die is represented as a decimal to link it to the triggering die, showing multiple rolls stemming from a single initial roll.

```json
[
  {
    "qty": 3,
    "sides": 6,
    "mods": [
      {
        "type": 'explode',
        "target": null
      }
    ],
    "rolls": [
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 0,
        "theme": 'diceOfRolling',
        "themeColor": null,
        "value": 6
      },
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 0.1,
        "theme": 'diceOfRolling',
        "themeColor": null,
        "value": 6
      },
      {
        "sides": 6,
        "groupId": 0,
        "rollId": 0.2,
        "theme": 'diceOfRolling',
        "themeColor": null,
        "value": 5
      }
    ],
    "id": 0,
    "value": 17
  }
]
```

--------------------------------

### Get Roll Results

Source: https://fantasticdice.games/docs/1.0.14/usage/methods

Retrieves the results of all dice in the current scene. Dice that are still in the process of rolling will not have a value.

```APIDOC
## Get Roll Results

### Description
Get the results of all the dice in the scene at anytime. However, if dice are still rolling they will not have a value yet.

### Method
GET

### Endpoint
/websites/fantasticdice_games/rollresults

### Parameters
#### Query Parameters
None

### Request Example
```javascript
diceBox.getRollResults()
```

### Response
#### Success Response (200)
- **rollResults** (array) - An array of objects, where each object represents the result of a single die.

#### Response Example
```json
[
  {
    "value": 6,
    "color": "#FF0000"
  },
  {
    "value": 3,
    "color": "#0000FF"
  }
]
```
```

--------------------------------

### Listen for Results Available Custom Event

Source: https://fantasticdice.games/docs/addons/advRoller

Example of how to listen for the 'resultsAvailable' custom event. This event is dispatched when the final roll results are ready and can be accessed via event.details.

```javascript
document.addEventListener('resultsAvailable', (e) => console.log('roll results: ', e.detail))  
```

--------------------------------

### POST /show

Source: https://fantasticdice.games/docs/0.6/usage/methods

Shows the canvas element where the Dice-Box is rendered.

```APIDOC
## Show

### Description
This will show the canvas element that the Dice-Box is rendered to.

### Method
POST

### Endpoint
/show

### Parameters
No parameters required.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates that the canvas has been shown.

#### Response Example
```json
{
  "status": "shown"
}
```
```

--------------------------------

### Create DiceBox Instance

Source: https://fantasticdice.games/docs/1.0.14/usage/config

Creates a new instance of the DiceBox class, specifying a target DOM element selector and configuration options. The `assetPath` is a required configuration option.

```javascript
const diceBox = new DiceBox("#dice-box", {
  assetPath: '/assets/dice-box/' // include the trailing backslash
})
```

--------------------------------

### Import DiceBox Class in ES Module

Source: https://fantasticdice.games/docs/1.0.14/usage/config

Imports the DiceBox class from the installed library for use in an ES module environment. This is typically used within a build system.

```javascript
import DiceBox from '@3d-dice/dice-box'
```

--------------------------------

### JSON Output of Parsed Dice Notation

Source: https://fantasticdice.games/docs/0.6/addons/parser

An example of the JSON output generated by the `parseNotation` method when processing a '4d6' input. It details the die type, count, and modifiers.

```json
{
  "die": {
    "type": "number",
    "value": 6
  },
  "count": {
    "type": "number",
    "value": 4
  },
  "type": "die",
  "mods": [],
  "root": true,
  "label": ''
}

```

--------------------------------

### Configure Advanced Roller with onSubmit Callback

Source: https://fantasticdice.games/docs/addons/advRoller

Instantiate the AdvancedRoller with configuration options, specifically the onSubmit callback. This callback is executed after the dice notation is parsed by FDP and receives the notation object, typically used to initiate the dice roll with another module like Dice-Box.

```javascript
const Roller = new AdvancedRoller({
  target: '#roller',
  onSubmit: (notation) => {
    diceBox.roll(notation)
  }
})
```

--------------------------------

### Handle 'resultsAvailable' Custom Event

Source: https://fantasticdice.games/docs/1.0.14/addons/advRoller

This example shows how to listen for the 'resultsAvailable' custom event dispatched by the Advanced Roller. The final parsed results are accessible via `event.detail`.

```javascript
document.addEventListener('resultsAvailable', (e) => console.log('roll results: ', e.detail))

```

--------------------------------

### Get Dice Roll Results - JavaScript

Source: https://fantasticdice.games/docs/0.6/usage/methods

Retrieves the results of all dice in the scene. If dice are still rolling, their values will not be available. This function returns an array of roll result objects.

```javascript
diceBox.getRollResults()
```

--------------------------------

### Advanced Roller with onClear Callback

Source: https://fantasticdice.games/docs/1.0.14/addons/advRoller

This example configures the Advanced Roller with `onSubmit` and `onClear` callbacks. The `onClear` callback is invoked after the roller's internal state is cleared, allowing for associated UI elements like the dice-box and display to be reset.

```javascript
const Roller = new AdvancedRoller({
  target: '#roller',
  onSubmit: (notation) => {
    diceBox.roll(notation)
  },
  onClear: () => {
    diceBox.clear()
    Display.clear()  // Display refers to Display Results module available in @3d-dice/dice-ui
  }
})

```

--------------------------------

### Dice Roll Input Object Example

Source: https://fantasticdice.games/docs/0.6/addons/parser

This object represents the input for a dice roll operation, specifying dice quantity, sides, and any modifiers like rerolls. It is the format expected by the `dice-box` library.

```javascript
[
  {
    qty: 4,
    sides: 6,
    mods: [
      {
        type: "reroll",
        target: {
          type: "target",
          mod: null,
          value: {
            type: "number",
            value: 1
          }
        }
      }
    ],
    rolls: [
      {
        sides: 6,
        groupId: 0,
        rollId: 0,
        theme: "diceOfRolling",
        value: 1
      },
      {
        sides: 6,
        groupId: 0,
        rollId: 1,
        theme: "diceOfRolling",
        value: 4
      },
      {
        sides: 6,
        groupId: 0,
        rollId: 2,
        theme: "diceOfRolling",
        value: 3
      },
      {
        sides: 6,
        groupId: 0,
        rollId: "0.1",
        theme: "diceOfRolling",
        value: 2
      }
    ],
    groupId: 0,
    value: 10
  }
]

```

--------------------------------

### onThemeConfigLoaded Callback

Source: https://fantasticdice.games/docs/usage/callbacks

This callback is triggered after a theme config file has been successfully fetched and parsed. It contains the theme config data as an argument parameter.

```APIDOC
## onThemeConfigLoaded

### Description
This callback is triggered after a theme config file has been successfully fetched and parsed. It contains the theme config data as an argument parameter.

### Method
Callback

### Endpoint
N/A

### Parameters
#### Callback Arguments
- **config** (object) - The loaded theme configuration data.

### Request Example
```javascript
diceBox.onThemeConfigLoaded = (config) => console.log('theme config data', config)
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```
Tokens:
Raw