Revision as of 18:53, 1 May 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 :-)