Revision as of 07:39, 20 May 2013

This is a work in progress please keep that in mind.

In this guide I will attempt to explain what the API is, using examples give the user a basic idea of how to use the API, and lay down some best practices for its use. This guide is not here to teach you basic programming concepts; but it will cover some “advanced” ideas that will be necessary for your code to not interfere with other scripts.

What is the API?

What we as the community refer to as the API is actually a complicated scripting system of many different parts.

Here is some terminology I will for each part of what we call the API:

• The Environment or Sandbox – You can think of this as a virtual machine that runs the code you enter into the scripting window.
• The API (Application programming interface) – The actual API is a JavaScript library that gives access to the inner workings of Roll20.
• Roll20 Object - The objects that make up the Roll20 app can all be accessed using the API. The campaign is a object and so is that elf token and the character sheet its attached to.

Prior Knowledge

To understand this guide I expect you to have a basic understanding of general programming, without this there is no point in reading any more of this guide.

To start learning about general programming and more specifically JavaScript please check out codecademy.

If at any point in this guide you don't understand something and it hasn't been explained it is because it is a simple programming concept and you should follow the link above to learn more.

Requirements

To do anything with the API at this time you must be a mentor level supporter and the campaign must be on the dev server.

At the time of writing the current script editor for the API is a little buggy so it is general considered a good idea to use an external editor then copy and paste you scripts into the script editor, some good editors include:

• Notepad++
• Sublime
• Programmer's Notepad

Part One: Events

The most fundamental part of the API is its events. Events give you the ability to execute code when something happens in Roll20.

Probably the most used event is "ready", it is called when the campaign has finished loading and is ready for use. The "ready" event is often used as an entry point for scripts as it is always called unless something stops the campaign from loading, and once called you know that all Roll20 objects that existed at the time of the campaign loading are accessible.

Here is an example of using the "ready" event to make a simple "Hello World" script:

on("ready", function() {
  log("Hello World!");
});

First off we have the on function it is part of the API and takes two parameters, a string with the name of the event you wish to hook and a handle function. In this example we write the handle function in line but the following code would work just as well.

var hello = function() {
    log("Hello World!");
};

on("ready", hello);

Then we have the log function, this prints to the "API Output Console" below the script editor and it takes a string of what to print.

So when run we get the output:

Spinning up new sandbox...
"Hello World!"