Skip to main content

Dice Rolls

Hephaistos fires off JavaScript events using the Custom Event API whenever dice rolls are triggered. As per the Custom Event API, details about the rolls are added to the detail field in the Event object that any event listeners will receive.

info

Definitions on this page use TypeScript to represent types.

hephaistos_on_roll​

This event fires off when the roll is triggered by a user.

Detail​

The detail field of the Event object will contain the following:

interface OnRoll {
    // A user-friendly name to describe the roll
    name: string,

    dice: DiceConfiguration,
    category: DiceRollCategory,
}

Remarks​

The .preventDefault() function can be called on this event to stop Hephaistos from calculating the roll's result and displaying it on the website.

Examples​

Attack Roll

{
    name: "Cestus Pistol, Advanced",
    dice: {
        d20: 1,
        add: 24,
        multiply: 1,
    },
    category: "Attack"
}

Damage Roll

{
    name: "Cestus Pistol, Advanced",
    dice: {
        d10: 1,
        add: 16,
        multiply: 1,
    },
    category: "Damage"
}

hephaistos_on_roll_result​

This event fires off when a roll's result has been calculated, but before it's been displayed.

Detail​

The detail field of the Event object will contain the following:

interface OnRollResult {
    // A user-friendly name to describe the roll
    name: string,

    dice: DiceConfiguration,
    category: DiceRollCategory,

    // The result of each rolled dice, in ascending order by the number of side each rolled dice had.
    // The final entry in the list will be the modifier to add, if any. Any multipliers are ignored for
    // this list. For example, rolling "2d4 + 3d6 + 14 x 2" may result in the following array:
    //         [ 1, 3, 2, 4, 5, 14 ]
    //          |---|  |-----|
    //           2d4     3d6
    diceResult : number[],

    // The final numer rolled, including any modifiers. In the example from above, this would be
    // (1 + 3 + 2 + 4 + 5 + 14) x 2 = 58
    finalResult : number,
}

Remarks​

The .preventDefault() function can be called on this event to stop Hephaistos displaying the result on the website.

Common Definitions​

DiceConfiguration​

interface DiceConfiguration {
    // These fields define the number of each type of dice to roll
    d1: number,
    d2: number,
    d3: number,
    d4: number,
    d6: number,
    d8: number,
    d10: number,
    d12: number,
    d20: number,
    d100: number,

    // An additional modifier to add to the rolled dice. This can be negative.
    add: number,

    // A number to multiply the final result by. This is mainly relevant for capital Starship Weapons.
    multiply: number,
}

Examples​

2d6 + 15

{
    d6: 2,
    add: 15,
    multiply: 1,
}

3d10 x 10

{
    d10: 3,
    multiply: 10,
}

1d4 + 2d12 + 4

{
    d4: 1
    d12: 2,
    add: 4,
    multiply: 1,
}

DiceRollCategory​

enum DiceRollCategory {
    Initiative = "Initiative",
    Skill = "Skill",
    Ability = "Ability",
    SavingThrow = "SavingThrow",
    Attack = "Attack",
    Damage = "Damage",
    CasterLevel = "CasterLevel",
    Custom = "Custom",
}

Example​

The following example code listens to the hephaistos_on_roll and hephaistos_on_roll_result events and logs the detail field to the console.

document.addEventListener("hephaistos_on_roll", (event) => {
    console.log(event.detail);
});


document.addEventListener("hephaistos_on_roll_result", (event) => {
    event.preventDefault(); // Stop Hephaistos from showing the roll result.
    console.log(event.detail);
});