Revision as of 06:40, 25 August 2022

Page Updated:   2022-08-25

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.

This page is related to Roll20 Mods, which require Pro info from the game's creator. (formerly known as API "Scripts") Main Page: Mod:Use Guide

Use

Roll20 Mods (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 Mods 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.

Name Change

After long-time planning and research, Roll20 is changing the name for APIs. Roll20 is renaming our "APIs" to "Mods" for a few reasons: 1) Calling the scripts APIs is not technically accurate 2) Mods is a better descriptor of how the scripts are used in games 3) Players are more familiar with the term Mods Ultimately, we’re hoping this change will attract folks who found “APIs” intimidating even though they act as Mods. Basically, it’s like modding Skyrim but on Roll20. We’re gradually making the change since API is used in a lot of places, and it’s not something we will strictly enforce. Do you have videos, podcasts, or blogs about APIs? Rad! You don’t have to go back and change any wording to Mods unless that’s something you want to do. The functionality is not changing for the scripts, only the name.
   – “API” Name Change to “Mod”, July 11th, 2022

Install API

To add an Mod to your game, you need to select the "Mod 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 Mods from the drop-down menu to install
• or manually install a script. Click on the "New Script"-tab, give the script a name, paste the code into the editor, then press Save.

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

The Mod:Script Index gives a great overview of most available Mods by category, and Mod:Short Scripts include some smaller ones that aren't in the install menu but can be nice to have.

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