Personal tools

API:Basic Examples

From Roll20 Wiki

Jump to: navigation, search

Roll20 API

Getting Started


Reference


Cookbook (Examples)


Community Scripts

Here are 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.

Bloodied and Dead Status Markers

(Contributed by Ken Bauer)

This script automatically adds the Red marker to represent the "bloodied" state for any tokens that drop below half their health, and the "dead" marker for any that drop to 0 or less. It's assumed that health is stored in Bar 1.

on("change:graphic", function(obj) {
    if(obj.get("bar1_max") === "") return;
   
    if(obj.get("bar1_value") <= obj.get("bar1_max") / 2) {
        obj.set({
              status_redmarker: true
        });
    }
    else{
        obj.set({
            status_redmarker: false
        })
    }

    if(obj.get("bar1_value") <= 0) {
      obj.set({
         status_dead: true
      });
    }
    else {
      obj.set({
        status_dead: false
      });
    }
});

The Darkness is Closing In...

This script reduces the light radius of a token by 10% every time that token moves. Great for simulating "lamps running out of oil" or similar high-stress situations.

on("change:token", function(obj, prev) {
    //Only do this if we actually moved.
    if(obj.get("left") == prev["left"] && obj.get("top") == prev["top"]) return;
    obj.set({
        light_radius: Math.floor(obj.get("light_radius") * 0.90)
    });
});

sendChat as a Player or Character

(Contributed by Brian Shields)

This is a few lines you can use in a chat:message event script to ensure you're sending a message with sendChat accurately as either a Player or a Character, depending on who triggered the event.

on("chat:message", function(msg) {
    var message = '';
    // Determine the contents of `message'
 
    var characters = findObjs({_type: 'character'});
    var speaking;
    characters.forEach(function(chr) { if(chr.get('name') == msg.who) speaking = chr; });
 
    if(speaking) sendChat('character|'+speaking.id, message);
    else sendChat('player|'+msg.playerid, message);
});