Revision as of 10:59, 28 August 2013

Whenever you're writing programs (from the simplest to the most advanced), inevitable you will encounter mistakes (often called "bugs") that cause the program to malfunction. Due to the Roll20 API's sandboxed nature, it can be a little difficult to tell exactly what's going on. So here are a few tips you can use to help diagnose problems with your scripts.

"Caveman" Debugging

Since you don't have direct access to the environment where the scripts are being run, you can rely on copious amounts of log calls to tell what's going on with your program. For example, if you're not sure why a token isn't moving correctly and you want to gain some insight into the values that are being tossed around, you might do:

on("change:graphic:left", function(obj) {
   //What's the object's left valeu coming into this?
   log(obj.get("left"));
   obj.set("left", obj.get("left") + 70);
   //What's it now?
   log(obj.get("left"));
   //You can also debug whole objects to see a list of their current attributes
   log(obj);
});

You'll find the output of your log commands in the API Console, which is on the Scripts Editor page for your Campaign.

Error Locks

The Roll20 API will automatically recover from small errors in your script by restarting your script as-needed. However, if the API detects a serious error that it can't recover from, rather than just restarting your script over and over again only to have it continue to error out, it will put an "error lock" on your Campaign which causes your API Scripts not to run until the error is resolved. If your scripts have been error locked, you'll see a message like this one on the Scripts Editor page:

Don't fret! Just make changes to your scripts to try and solve the problem, then click the "Save Script" button. When you do that, the error lock will be "cleared" and the API will attempt to run your scripts again. If there is another error, the error lock will be re-applied. You can repeat this process as often as needed to get the error fixed, the API won't ever keep you from clearing your error locks because you've failed too many times :-)

Common Errors

Some commonly encountered errors include:

myvar is not defined

on("ready", function() {
    var myVar;
    log(myvar);
});

While the error message says "not defined," what's actually happened is that the variable is not declared. One of the most common causes of this is a typo in the name of one of your variables, such as missing a capital letter.

Cannot read property 'myProperty' or Cannot call method 'myMethod'

on("ready", function() {
    var myVar;
    log(myVar.myProperty);
    log(myVar.myMethod());
});

myVar is not defined, so the script cannot figure out how to deal with you trying to access a property of myVar. This is likely due to one of:

• You tried to find an object, but the result was undefined. Perform some error-checking to make sure your variable is defined before accessing its properties.
• Your variable is being conditionally defined (with a series of if statements or something similar), and none of your conditions matched, so your variable sat there declared, but never defined. Make sure you have conditions for all possibilities, or make a default option, or perform error-checking to make sure your variable is defined before accessing its properties.

Unexpected token

You are either missing a character or have one too many characters. This can result from forgetting a comma between a list of properties in an object or elements in an array, or having one too many or too few closing parentheses at the end of a complicated nested method call.

_displayname returns undefined, while get("_displayname") returns a name

Most of the properties in the Roll20 objects need to be accessed via the get and set methods. When using get/set, you may omit the leading underscore on read-only properties.