Mod:Use Guide
From Roll20 Wiki
Page Updated: 2024-05-03 |
Attention: This page is community-maintained. For the official Roll20 version of this article, see the Help Center for assistance: Here .
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 |
Roll20 Mod
Mod Suggestions
- Use & Install
- Script Index
- Short Community Scripts
- Meta Scripts
- D&D 5E
- Combat
- Character Sheet
- Dynamic Lighting
- Jukebox
- Maps
- Text Chat/Macros
- Tokens
- System Specific
- Mod Guides by Script
Debug
Other
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.
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
Contents |
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.
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
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 Mods
Roll20 Mod
Use Mods
- Use & Install
- Mod:Script Index & Suggestions
- Short Community Scripts
- Meta Scripts
- User Documentation
- Mod Scripts(Forum)
- Mod Update 2024🆕
- Macro Guide
Mod Development
Reference
- Objects
- Events
- Chat Events & Functions
- Utility Functions
- Function
- Roll20 object
- Token Markers
- Sandbox Model
- Debugging
Cookbook
Creation
Main Page: API:Development
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(); } }); });
Related Pages
- Macros -- about chat commands
External Tools for Roll20: