Latest revision as of 13:04, 3 May 2024

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

Roll20 Mod
Mod Suggestions

Mods by Category

Debug

Other

[edit] 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

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

See More:

pages.roll20.net/mods
Mod Update 2024 adds lots of improvements.

[edit] 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

[edit] Install Mod

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.

Pro

^{^info} Features

Feature Breakdown

How to Install an API (Nick Olivo)

[edit] The Script Editor

Access the editor

To edit your game scripts (as a

Pro

^{^info} user) , click on the Mod 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, 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.

[edit] 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.

[edit] Popular Mods

Roll20 Mod
Use Mods

Mod Development

Reference

Cookbook

[edit] Creation

Main Page: API:Development

[edit] Simple API Example

Simple script 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();
    }
  });
});

[edit] Related Pages

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

External Tools for Roll20:

@@ Line 1: / Line 1: @@
-{{apibox}}
+{{revdate}}{{HCbox| {{hc|articles/360037772773-API-Advanced-Use-Guide Here}} }}
+{{pro only}}
+{{Mod|page}}
+{{apiboxRec}}
+=Use=
+'''Roll20 Mods''' (API Scripts''') are a collection of scripts that can expand the [[Macro Guide|chat commands]], tools, automation & features both [[GM|GMs]] and [[players]] have access to inside a game.
-==The Script Editor==
-To edit your campaign scripts, go to the My Settings tab on the right sidebar, and scroll all the way down to the bottom. There you'll find a button titled "Manage API Scripts". Clicking that button will open up a dialog box with a script editor. You can create multiple scripts for your campaign, but they will all run in the same "environment", meaning that you shouldn't have multiple scripts trying to overwrite the same values or you could get unintended results.
-==Reactive Scripts: Listen to Events, Modify Objects==
-The first (and most simple type) of API usage is to react to changes on the tabletop, and then respond by making additional changes to the changed objects. This type of script is composed of a number of functions which listen to events that happen during the game. Then it will modify objects that are passed during those events, which will change what happens on the tabletop.
-The most basic script which would simply move any piece which moved an additional 5 feet (assuming default page settings) would be:
+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]]
-<pre data-language="javascript">
+'''[[Mod:Script Index]]''' is a curated lists of the available APIs to install, and gives a short description for each.
-on("change:graphic", function(obj) {
-  obj.set({
-    left: obj.get("left") + 70 < 0
-  });
-}
-</pre>
-As you can see, we created a simple function using on which will be executed anytime the <code>change:graphic</code> event is heard. The function is passed the graphic object <code>obj</code>. To make a change, we just modify <code>obj</code> using the <code>set</code> function -- whatever properties we change will be detected and changed on the tabletop.
+See More:
+* '''[https://pages.roll20.net/mods pages.roll20.net/mods]'''
+* [[Mod Update 2024]] adds lots of improvements.
+==Name Change==
-'''Important Note:''' You must use <code>set</code> and <code>get</code> to set and get current values on objects or your changes will not be saved. (See below for a listing of object types and their properties, as well as a listing of all events and what arguments each event is passed.)
-===A Note on Utility Functions===
+{{quote|After long-time planning and research, Roll20 is changing the name for APIs. '''Roll20 is renaming our "APIs" to "Mods"''' for a few reasons:
-Of course, the previous example isn't incredibly helpful because it always adds 70 pixels to the location of the token. But what if the user has changed their scale so that 5ft is 140 pixels? The Roll20 API provides several handy utility functions to help with this (and other) common scenarios. Let's modify our previous example to use the <code>distanceToPixelsfunction</code>, which will tell us how many pixels "five feet" (or inches, or meters, or whatever other distance type has been set) on the tabletop is.
-<pre data-language="javascript">
+) Calling the scripts [https://en.wikipedia.org/wiki/API APIs] is not technically accurate
-on("change:graphic", function(obj) {
+) Mods is a better descriptor of how the scripts are used in games
-  obj.set({
+) Players are more familiar with the term Mods
-    left: obj.get("left") + distanceToPixels(5);
-  });
-}
-</pre>
-Now if the current page is setup to use the default grid sizing, <code>distanceToPixels(5);</code> will still return 70 pixels, but if the page is setup to have a scale twice the size of normal, it would return 140.
+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.
-It's always a good idea to use utility functions whenever they're available to help keep your script from breaking if the settings of a page or a token change.
+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.
-==Proactive Scripts: Do Things Without User Intervention==
+The functionality is not changing for the scripts, only the name.|[https://app.roll20.net/forum/post/10967129/api-name-change-to-mod “API” Name Change to “Mod”], July 11th, 2022}}
-In addition to reacting to user events, you can also do things with the API automatically that aren't tied to a specific event from the players. For example, let's have a token that patrols back and forth on the map.
+__TOC__
+==Install Mod==
+{{:Mod:Install Menu}}
+==The Script Editor==
+[[File:Game-Management-API-scripts.png|thumbnail|left|350px|Access the editor]]
+<br><br><br>
+To edit your game scripts (as a {{Pro}} user) , click on the '''Mod 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).
+<br clear=all>
+[[File:API-script-library.png|right|thumbnail|500px|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 <code>state</code> 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==
+{{:API Console}}
+==Popular Mods==
+{{apibox}}
+* [[TokenMod]]
+* [[ScriptCards]]
+* [[GroupInit]]
+* [[ChatSetAttr]]
+* See All: '''[[Mod:Script Index]]'''
+=Creation=
+{{main|API:Development}}
+==Simple API Example==
+Simple script with embedded explanation on what is going on, by [[Aaron|The Aaron]]
 <pre data-language="javascript">
-on("ready", function() {
+// Register a function for the 'ready' event.  When it occurs, which happens only once
-   //Wait until the ready event fires so we know the campaign is completely loaded.
+//   this function will get called.  This avoids getting events resulting from the
-   //Get a reference to our patrolling token.
+//   loading of all the game state into the API
-   var patroltoken = _.findObjs({_type: "graphic", name: "Guard A"})[0]; //We know there is a token in the Campaign called "Guard A".
+on('ready',()=>{
-   var direction = -70; //Walk left 70 pixels.
-   var stepstaken = 0; //How many steps have we walked in the current direction?
+  // Declare a function called myFunc.  This is using the "Fat Arrow" function syntax
-   setInterval(function() {
+  //   and the const declaration from Javascript ES6
-     if(stepstaken > 5) {
+  const myFunc = ()=>{
-       //Switch directions!
+    sendChat('myFunc','myFunc was called!');
-       direction = direction * -1; //will "flip" the direction we're walking
+  };
-       stepstaken = 0; //reset steps back to 0.
-     }
+  // Register a function for the 'chat:message' event.  This event occurs for all
-     patroltoken.set("left", patroltoken.get("left") + direction); //walk!
+  //   chat messages, so it's important to filter down to just the ones you care about
-     stepstaken++;
+  on('chat:message',msg=>{
-   }, 5000); //take an action every 5 seconds
+    //  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();
+    }
+  });
 });
 </pre>
+==Related Pages==
+* [[Macros]] -- about chat commands
+** {{macro guide}}
+External Tools for Roll20:
+* [[:Category:Web Browser Extensions]]
+* [[:Category:External Tools]]
+[[Category:API|Use Guide]]
+[[Category:Pro]]

Roll20 Wiki

Navigation

Personal tools

Toolbox

Difference between revisions of "Mod:Use Guide"

From Roll20 Wiki