"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 value 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 Mod (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 Mod (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
Below are some more commonly encountered errors:
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()
, you should omit the leading underscore on read-only properties.