Visual Effects

With these functions, you can display on-screen effects and animations.

Due to the number of available customization options, these are more complicated APIs. To help show how to use this library effectively, examples are provided at the bottom of the page.

Effect.ShowOpposedDiceRoll

instigator = ...

target = ...

label_instigator = ...

label_target = ...

log_key = ...

rounds = ...

instigator (Creature) - creature to display on the left side of the die roll
target (Creature) - creature to display on the right side of the die roll
label_instigator (string) - optional - description for left-side roll; default is "Total"
label_target (string) - optional - description for right-side roll; default is "Total"
log_key (string) - optional - if non-nil, log combat text with this key; default is nil
rounds (array of DiceRound) - list of rounds to display, see below for layout

Displays an animation for a six-sided dice (D6) roll between two opposing characters. Die values and labels can be customized. Multiple rounds may be provided; they will be displayed in order. Note that if the player has combat animations disabled, this animation is also hidden.

struct

DiceRound

DiceList

instigator_dice

describes the individual die faces on the instigator's side

DiceList

target_dice

describes the individual die faces on the target's side

struct

DiceList

boolean

hostile

optional, if true, use red dice, if false, use white dice

array of number

...

d6 die faces (range 1-6) in order of display

Example

An example usage of ShowOpposedDiceRoll, demonstrating all possible parameters. Note that several parameters are optional; refer to the above layout documentation for details.

local my_instigator = Player -- Remember, Player is a Creature
local my_target = Creature("CR_SQ01_Alchemist")

Effect.ShowOpposedDiceRoll {
    instigator          = my_instigator,
    target              = my_target,
    label_instigator    = "Attack",
    label_target        = "Defense",

    -- For this string table key, the grammar contexts 'attacker', 'defender', 'predator' and
    -- 'prey' are available. 'attacker'/'predator' is the instigator, 'defender'/'prey' the target.
    log_key             = "ATTACK_HIT",

    -- At least 1 DieRound is required, but you can provide as many more as you want.
    rounds = {
        {
            -- List the individual D6 dice values as array elements, in the order they should be shown.
            -- Here, the instigator rolls six dice total, with each possible die face from 1 to 6.
            -- The target rolls two dice total, each with a value of 3.
            instigator_dice = { 1, 2, 3, 4, 5, 6 },
            target_dice = { 3, 3, hostile = true },
        },
        {
            -- Any DieList can be tagged with 'hostile = true' to change the die face colors.
            instigator_dice = { 6, 5, 4, 3, 2, 1, hostile = true },
            target_dice = { 1, 2, 3, 4, 5, 6 },
        }
    }
}

The first round of the above example might be displayed as follows:

Note how Jar'la's dice are colored red, due to the 'hostile' flag in the die list.

Example​

Example