Revision as of 10:14, 9 March 2022

Page Updated:   2022-03-09

This is about a Roll20 feature exclusive to Pro-subscribers (and often to players in a Game created by a Pro-subscriber). If you'd like to use this feature, consider upgrading your account.

Use

Roll20 API Scripts are a collection of scripts that can expand the chat commands, tools, automation & features both GMs and players have access to inside a game.

Roll20 APIs are not accessible outside Roll20 games, nor are there any outward pointing endpoint to hook into. They are limited to work within each individual Campaign they are installed in, and are inactive if there are no people inside the game. Read more on API:Sandbox Model

API:Script Index is a curated lists of the available APIs to install, and gives a short description for each.

Install API

To add an API to your game, you need to select the "API Scripts" option in the Settings-menu found on a campaign's main page. Only a Campaign's Creator and GMs have access to this page.

You can either:

• select APIs from the drop-down menu to install
• or manually install a script. Click on the "New Script"-tab, give the API a name, paste the code into the editor, then press Save.

• How to Install API Scripts via 1-Click Install
• API forum^(Forum)

The Script Editor

Access the editor

The API Script Library, displaying an empty API Console at the bottom.

You will be presented with a page with several features:

• A list of tabs along the top. Your game can have multiple scripts for ease of organization. Note that all scripts will still run in the same context, meaning that you shouldn't have multiple scripts trying to overwrite the same values at the same time or you could get unintended results.
• A script code editor. You can use this editor, or edit your scripts in an external editor of choice and then paste them in here.
• Along the bottom is an "API Console" (see below).

Whenever you click the "Save Scripts" button, the sandbox for your game will be restarted (losing any in-memory data which hasn't been persisted in the state object or in Roll20 objects) and use the new script modifications you just made. This also applies if you add a new script, delete a script, or toggle a script to enable/disable it.

The API Console

The API Console is your "window" into your scripts. Since API Scripts run in a sandbox, you don't have direct access to them while they are running to view information on the script's results or errors. The API Console brings this information out of the sandbox so you can view it while you are editing your scripts.

All log() commands will show here, as well as any errors that are encountered during the execution of your scripts. For more information, see API:Debugging.

API Issues:

If the APIs in your game doesn't seem to work, press on the Restart API Sandbox, and it fixes the issue usually.

Popular APIs

• TokenMod
• ScriptCards
• GroupInit
• See All: API:Script Index

Creation

Main Page: API:Development

Simple API Example

Simple API with embedded explanation on what is going on, by The Aaron

// Register a function for the 'ready' event.  When it occurs, which happens only once
//   this function will get called.  This avoids getting events resulting from the
//   loading of all the game state into the API
on('ready',()=>{

  // Declare a function called myFunc.  This is using the "Fat Arrow" function syntax
  //   and the const declaration from Javascript ES6
  const myFunc = ()=>{
    sendChat('myFunc','myFunc was called!');
  };

  // Register a function for the 'chat:message' event.  This event occurs for all
  //   chat messages, so it's important to filter down to just the ones you care about
  on('chat:message',msg=>{
    //  First check the type is an API message.  API messages are not show shown in chat
    //    and begin with a ! in the first character of the message.
    //
    //  Next, make sure this is our API message.  The regular expression checks that the 
    //    command starts with "!call-my-func" and either ends or has a space, all case 
    //    insensitive.
    if('api'===msg.type && /^!call-my-func(\b\s|$)/i.test(msg.content)){
      myFunc();
    }
  });
});

Related Pages

• Macros -- about chat commands
  • Complete Guide to Macros & Rolls

External Tools for Roll20:

• Category:Web Browser Extensions
• Category:External Tools