Manage Roll

This page explains how to perform dice rolls using a script, how to present sub-rolls to the user, and how to interact with the results. Several examples of roll construction are presented here.

Among the different ways to build a roll, the most recommended one is using the RollBuilder.

---

Simple Roll

A simple roll consists of performing a dice roll triggered by a button through a script. This action can be done without a complex script.

Required Components

For this script, you will need:

• an icon that acts as a button (roll1_button),
• a text input containing the dice expression (roll1_value).

The script performs the following actions:

1. retrieves the components by their ID,
2. creates a function that prepares the roll using the provided expression (for example: 1d20),
3. connects this function to the “click” event of the button.

const initSimpleRoll = function (sheet, id_roll_button, id_roll_value) {
    // 1 
    let roll_button = sheet.get(id_roll_button);
    let roll_value = sheet.get(id_roll_value);
    // 2
    const roll = function () {
        log("START : simple roll cliked");
        // creer le jet
        let roll = new RollBuilder(sheet);
            // configuer le jet
            roll = roll.expression(roll_value.value());
            roll = roll.visibility("all");
            roll = roll.title("Simple Roll");
            // lancer le jet
            roll.roll();
            log("END : simple roll clicked");
    }
    // 3 
    roll_button.on("click", roll);
}

Add an Action to a Roll

In many game systems, player actions consist of multiple rolls. For example, an attack may require a first roll to determine if the target is hit, and a second roll to calculate the damage.

You can add sub-actions to your rolls. These actions appear as small white buttons below the result of the main roll.

View Composition

For this example, you will need:

• two text inputs containing the expressions of the main and sub-rolls (roll2_value and roll2_action_value),
• one button to trigger the first roll (roll2_button).

The corresponding script:

1. retrieves the components by their IDs,
2. creates a function that performs the sub-action when it is clicked,
3. prepares the first roll and attaches the action to it,
4. connects everything to the click event on the button.

const initActionRoll = function (sheet, id_roll_button, id_roll_value, id_roll_action_value) {
    // 1
    let roll_button = sheet.get(id_roll_button);
    let roll_value = sheet.get(id_roll_value);
    let roll_action_value = sheet.get(id_roll_action_value);
    // 2  
    const rollAction = function (result) {
        log("START : action roll cliked");
        let roll_action = new RollBuilder(sheet);
        roll_action = roll_action.expression(roll_action_value.value());
        roll_action = roll_action.visibility("all");
        roll_action = roll_action.title("Action Roll");
        roll_action.roll();
        log("END : action roll clicked");
    }
    // 3
    const roll = function () {
        log("START : roll cliked");
        let roll = new RollBuilder(sheet);
        roll = roll.expression(roll_value.value());
        roll = roll.visibility("all");
        roll = roll.title("Roll");
        roll = roll.addAction("Action name", rollAction);
        roll.roll();
        log("END : roll clicked");
    }
    // 4
    roll_button.on("click", roll);
}

This allows you to add multiple actions to your rolls.  

For each additional action, simply create a new function (''rollAction1'', ''rollAction2'', etc.) with the desired behavior and add it to the main roll.

The ''results'' argument passed to an action function contains the result of the parent roll.  

This allows you to detect specific cases such as critical hits and adjust the behavior accordingly.

Automatic Action

An automatic action is a secondary effect that triggers as soon as a roll is completed. It can be used, for example, to:

• automatically record the result of a roll on the sheet,
• update a resource such as mana or health points.

Building the View

For this example, you will need:

• a button to trigger the roll (roll3_button),
• a text input containing the roll expression (roll3_value),
• a component where the result will be displayed (roll3_mark).

The associated script:

1. retrieves the components by their IDs,
2. creates a function that writes the roll result automatically in the designated component,
3. creates a function that is triggered when the button is clicked,
4. links both functions together to execute the automatic action.

const initAutoAction = function(sheet,id_roll_button, id_roll_value, id_roll_mark){
    // 1 
    let roll_button = sheet.get(id_roll_button);
    let roll_value = sheet.get(id_roll_value);
    let roll_mark = sheet.get(id_roll_mark);
    //2
    const autoAction = function (result) {
        log("START : action roll cliked");
        roll_mark.value(result.total);
    }
    // 3
    const roll = function () {
        log("START : roll cliked");
        let roll = new RollBuilder(sheet);
        roll = roll.expression(roll_value.value());
        roll = roll.visibility("all");
        roll = roll.title("Roll");
        // renseigner la fonction automatique
        roll = roll.onRoll(autoAction);
        roll.roll();
        log("END : roll clicked")
    }
    //4 
    roll_button.on("click", roll);
}

This approach allows you to add many automation features to your character sheet.  

You can also combine regular and automatic actions, or even nest actions inside other actions to create complex game mechanics.