Page Updated:   2022-02-17

The Cookbook provides some examples of simple scripts that can help you get started. Feel free to take them and modify them for use in your own campaigns. There's also an API Scripts^(Forum) where you can discuss API Scripting and share your scripts with the community.

Token Status Manager

(Contributed by Eric Dalquist)

This script automatically adds status markers based on the bar values. The script can be configured to track any of the three bars, set any of the status markers for any ratio between 0 and 1. The script can manage multiple bars/tokens in a single instance. The example below watches bar 1 and sets the red marker when the value is <= 50% and then sets the dead marker when the value is <= 0.

/**
 * Set various token markers based on bar cur/max ratios
 * 
 * The CONFIG array can have any number of configuration objects. These objects
 * are processed in order.
 * 
 * barId - The ID of the bar to look at the values for [1, 2, 3]
 * barRatio - The ratio of bar value to max value that triggers setting the status marker [0 - 1]
 * status - The name of the status marker to toggle [redmarker, bluemarker, greenmarker, brownmarker, purplemarker, dead]
 * whenLow - The state of the marker when the bar value is <= the ratio [true, false]
 */
var CONFIG = [
    {barId: 1, barRatio: .5, status: "redmarker", whenLow: true},
    {barId: 1, barRatio: 0, status: "dead", whenLow: true}];


on("change:token", function(obj) {
    CONFIG.forEach(function(opts) {
        var maxValue = parseInt(obj.get("bar" + opts.barId + "_max"));
        var curValue = parseInt(obj.get("bar" + opts.barId + "_value"));
        log(opts.barId + ": " + curValue + "/" + maxValue);
    
        if (!isNaN(maxValue) && !isNaN(curValue)) {
            var markerName = "status_" + opts.status;
            if (curValue <= (maxValue * opts.barRatio)) {
                obj.set(markerName, opts.whenLow);
            }
            else {
                obj.set(markerName, !opts.whenLow);
            }
        }
    });
});

For the most recent revision see: statusmanager-js

Temp HP Manager

(Contributed by Eric Dalquist)

Automatically manages temporary hitpoints. If one of the token bars is used to track temp hp this script can automatically deduct HP from the temp value before they are removed from the main HP bar.

/**
 * Automatically removes temp HP if they exist.
 * 
 * When a token has its HP reduced the script checks to see if there are any
 * temp HP available. If it does those are removed first and the real HP is
 * updated to reflect the temp HP absorbing the hit.
 * 
 * TEMP_BAR_ID - The bar used to track temp HP [1, 2, 3]
 * HP_BAR_ID - The bar used top track real HP [1, 2, 3]
 */ 
var TEMP_BAR_ID = 2;
var HP_BAR_ID = 1;
 
on("change:token", function(obj, prev) {
    var prevHpValStr = prev["bar" + HP_BAR_ID + "_value"];
    var prevHpVal = parseInt(prevHpValStr);
    if (isNaN(prevHpVal)) {
        log("WARN: Previos bar " + HP_BAR_ID + " does not contain a number: '" + prevHpValStr + "'");
        return;
    }
    
    var hpValStr = obj.get("bar" + HP_BAR_ID + "_value");
    var hpVal = parseInt(hpValStr);
    if (isNaN(hpVal)) {
        log("WARN: Bar " + HP_BAR_ID + " does not contain a number: '" + hpValStr + "'");
        return;
    }
    
    if (prevHpVal > hpVal) {
        var tmpHpVal = parseInt(obj.get("bar" + TEMP_BAR_ID + "_value"));
        log(prevHpVal + " - " + hpVal + " - " + tmpHpVal);
        if (!isNaN(tmpHpVal)) {
            var hpChange = prevHpVal - hpVal;
            var remainingTmp = tmpHpVal - hpChange;
            if (remainingTmp > 0) {
                obj.set("bar" + TEMP_BAR_ID + "_value", remainingTmp);
                obj.set("bar" + HP_BAR_ID + "_value", prevHpVal);
            }
            else {
                var remainingHp = prevHpVal + remainingTmp;
                obj.set("bar" + TEMP_BAR_ID + "_value", 0);
                obj.set("bar" + HP_BAR_ID + "_value", remainingHp);
            }
        }
    }
});

For the most recent revision see: temphp-js

Patrolling Token

on("ready", function() {
   //Wait until the ready event fires so we know the campaign is completely loaded.
   //Get a reference to our patrolling token.
   var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //We know there is a token in the Campaign called "Guard A".
   var direction = -70; //Walk left 70 pixels.
   var stepstaken = 0; //How many steps have we walked in the current direction?
   setInterval(function() {
     if(stepstaken > 3) {
       //Switch directions!
       direction = direction * -1; //will "flip" the direction we're walking
       stepstaken = 0; //reset steps back to 0.
     }
     patroltoken.set("left", patroltoken.get("left") + direction); //walk!
     stepstaken++;
   }, 5000); //take an action every 5 seconds
});