Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "API:Use Guide"

From Roll20 Wiki

Jump to: navigation, search
m (Move API Dev stuff to other pages)
m (Simple API Example)
Line 50: Line 50:
 
==Simple API Example==
 
==Simple API Example==
 
Simple API with embedded explanation on what is going on, by [[Aaron|The Aaron]]
 
Simple API with embedded explanation on what is going on, by [[Aaron|The Aaron]]
<predata-language="javascript">
+
<pre data-language="javascript">
 
// Register a function for the 'ready' event.  When it occurs, which happens only once
 
// 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
 
//  this function will get called.  This avoids getting events resulting from the

Revision as of 15:05, 13 January 2022

Attention: This page is community-maintained. For the official Roll20 version of this article, see the Help Center for assistance: Here .

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.

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

Contents

Install API

Game Settings Menu Options.jpg

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 an API (Nick Olivo)

The Script Editor

Access the editor




To edit your game scripts (as a
Pro
info user) , click on the API Scripts-option on the [[Game Details page for your game (the same place where options such as the "Chat Log" and "Copy/Extend Game" are located).


The API script Library

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 the information on Debugging scripts.

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

Creation

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

External Tools for Roll20: