Home
Games
Marketplace
Compendium Character Vault Roll20 for iPad and Android
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

Mod:Script Index

From Roll20 Wiki

(Redirected from API Index)
Jump to: navigation, search
Wiki-Logo 75x49.png
Page Updated:
  2023-07-30
Pro.png
This page 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.
Octicons-terminal.png
This is related to Roll20 Mods, which require
Pro
info from the game's creator.
(formerly known as API "Scripts")
Main Page: Mod:Use Guide

The Mod:Script Index is a community-curated list of Mod Scripts that are available for use on Roll20.

Roll20 Mod
Use Mods

Mod Development

Reference

Cookbook

Pro
info Features

Feature Breakdown

General

Contribute & share your Mods
If you're interested in contributing to the Roll20 Mod Community Scripts & want yours to show up in the One-Click Install please follow the instructions in the README. Otherwise you can add yours to Short Community Scripts or make a new page for it.

Favorite Mod Lists of some users:

For Modss not found in the Mod One-Click Install see:

Contents

Mods available in One-Click Menu

Roll20 Mod
Mod Suggestions

Mods by Category

Debug

Other

This list resemble the list found in the Mod One-Click Install, but currently lists only Mods that have their own wiki pages, or are popular enough. There are lots of Mods that aren't listed Andreas J. (talk) Sept 2021

If your script are designed for use with a specific game system, ruleset, or specific Roll20 character sheet, please list the Mod under that game system, instead of listing under one of the more generic categories. When appropriate, Mod can be listed under more than one category.

Some great or popular Mods have their name highlighted in bold to stand out.

Mods by Category

Journal

Modss interacting primarily with things on the N Journal tab, such as Characters and Handouts.

Characters

Various scripts related to Character Sheets, and managing them.

  • CharSheet -- Allow players to create their own character sheets.
  • Welcome Package(Forum) -- API create and assigns character sheets to new people who join a game
  • PlayerCharacters(Forum) -- Player & Character Manager. List all Player Characters divided by Player for the GM, or all assigned Characters for a Player. Add Characters for GM and Players.
  • PublicSheet(Forum) -- Creates a "public" version of character sheets that players can't edit, which mirrors the actual character sheet.
  • Reporter(Forum) -- A script to poll the game and return info on Token/Character pairs, along with customized action tools.
  • Observer(Forum) -- Manages observer players, who are given the visibility (and control) of all player characters. This is useful for both podcasting views and local play on a single player screen.

Equipment

Most game systems have some form of equipment to make characters better. While scripts dealing with that equipment may necessarily be system-specific, there are scripts which handle equipment in a more general fashion.

  • Ammo -- Provides inventory management for ammunition stored in an attribute of a character. Can be used with any char sheet

Attributes

Manipulate one or more characters' attributes. Anything that is system-specific should be placed in the system's category below; this section is for system-agnostic attribute manipulation.

  • Ammo -- API for tracking ammo use & recovery.
  • ChatSetAttr -- Create, modify, and delete character attributes via chat commands or macros. ChatSetAttr can be embedded into normal macros.
  • GroupCheck -- A way to quickly roll a group check for everyone, and see who succeed
    • ApplyDamage(Forum) -- Supplementary API to GroupCheck, which enables to automatically apply damage to a group of characters, based on failed/succeeded GroupCheck rolls. Example: Damage of an AoE Spell, based on success/fail on saving throw
  • Conditions -- Track attribute-modifying conditions.
  • EasyExperience -- Make awarding experience easy and choose your experience progression.
  • LazyExperience(Forum) -- to record experience during a game. Inspired by EasyEx, biggest difference is that it has an option to reward experience directly.
  • Experience Tracker -- (Note: Old API, not updated since 2016) Automatic tracking of a D&D 5e-like experience system, as well as level up announcement in chat. !xp handles experience and announces level up.


Handouts

API Scripts interacting with Handouts and Journal entries.

  • Supernotes(Forum) -- script pulls the contents from a token's GM Notes field.
    • If the token represents a character, you can optionally pull in the Bio or GM notes from the character. The user can decide whether to whisper the notes to the GM or broadcast them to all players.
    • Finally, there is the option to add a footer to notes whispered to the GM. This footer creates a chat button to give the option of sending the notes on to the players.
  • NoteLog(Forum) -- provides an easy interface to keeping notes for your players.
  • Search(Forum) -- provides full text searching across handouts and characters (including attributes). Search respects permissions on handouts and characters.


Chat

Main Page: Text Chat/API

Various APIs that primarily help you out by creating API commands & options that can be used in the q Text Chat.

  • ChatSetAttr -- Create, modify, and delete character attributes via chat commands or macros.
  • ChatTurnManager -- A script to simplify Turn Order Management, and move it into chat.
  • Check It Out(Forum) -- allows players to examine nearby objects(tokens) and learn more information about them by having a message appear in the chat. Can be set up with system-specific properties, such as automated Investigation skill checks that reveal more information based on the rolled result. Readme
  • Dialog(Forum) -- a script that makes chat a bit more fun and easier to parse, especially for games that don't use voice. It also makes it much easier to get the GM's attention in a busy game.sourcecode, by Keith
  • DiscreteWhisper -- multi-recipient whispers with asides and buttons
  • emas -- Provides player !emas and !as commands.(emote as)
  • ScriptCards -- A scripting language in a Mod Script. Used to produce nicely formatted output cards for attacks, spells, and other abilities. Successor to PowerCards
  • SuperNotes(Forum) Mod to pull descriptions from token/character descriptions, Bio, GM fields & more as an caht message. Later version comes with 10 different chat template options.
  • PowerCards -- Create nicely formatted output cards for attacks, spells, and other abilities.
  • Message of the Day -- Greets players that log in with the contents of a particular note.
  • Rollable Table Macros -- Use macros and chat commands with rollable tables
  • Changes how normal macros and API Script calls are processed:
    • MetaMacros -- Precompiler enabling C-style textual substitution macros in macro definitions.
    • Meta-Toolbox -- collection of meta scripts
      • SelectManager -- a way to preserve the portions of a message that are present in a user-generated message but lost in an api-generated message (the selected tokens, who sent the message, and the playerid).
    • Category:API Meta Scripts


Combat

Universal combat scripts assist in making combat flow more easily. This can mean anything from automatically handling initiative(t Turn Tracker), automating exchanges between combatants, or doing more comprehensive management. Scripts made for specific Game systems or Roll20 sheets are listed on D&D 5E & System_Specific

  • Group Initiative -- Adds the selected tokens to the turn order after rolling their initiative + configurable data.
  • TurnMarker1 -- provides a visual marker to show which token's turn it is & centers map on them.
  • CombatMaster(Forum) (by Victor B.) -- API for improving various aspects of combat. Automating condition duration in combat, Initiative improvement, and more.
  • autoButtons - automatically generate damage & healing buttons in chat after rolls are made, making it quick & easy to apply the damage & healing to other characters.
  • AddCustomTurn(Forum) (by Aaron)-- An easy way to add (and remove) custom turns which increment or decrement, and have auto delete features.
  • EncounterHelper -- Group tokens into encounters, making it easy to shown/hide/reset individual encounters on the same map, along with rolling initiative for them.
  • ChatTurnManager
    GitHubLogo.png -- A script to simplify Turn Order Management, and move it into chat.
  • Critical -- Quick method of determining the outcome of a critical hit.
  • Fumbler -- Quick method of determining the outcome of a fumble.
  • Initiative Tracker Plus -- Initiative and effect tracker with other features.
  • InitiativeMaster -- Standard, Group & Individual Initiative manager for Script:RoundMaster with many additional features
  • RoundMaster -- Generic Turn Order Tracker, Token status manager, and Effect macro system


Jukebox

The u Jukebox is the music player, and some APIs interact with it

Relevant:

Generators

Content generation can extend the reach of your campaign while minimizing the GM's prep time.

  • Dungeon Utils -- Generates random dungeons from wall and floor images.
  • namegen -- Generates random names of People, Towns/Cities, and Taverns
  • Terrain Generator -- Generate simple outdoor maps (forests, deserts, etc)

Maps & Drawing

Various APIs related to the Map that isn't related to Dynamic Lighting, nor focused on Tokens.

  • SmartAoE -- graphical interface for implementing AoE's on gridded maps to clearly show which squares are affected
  • Areas of Effect(Forum) -- let's players spawn AoE effects on the map(based on what GM made available.
  • DryErase(Forum) – An API that can stop players from drawing on the map.
  • Hexploration(Forum) -- Script allows the GM to conceal areas of a hex grid with individual opaque hexes. Then characters can explore the hexes to reveal them. Readme
  • MapLock -- Provides locking of graphics to prevent moving/resizing/rotating them. Also highlighting.
  • MapChange -- Provides an easy and user friendly way to move players between maps.
  • Radar(Forum) -- to simulate various types of radar, tremor sense etc. Includes options for DL.
  • Universal VTT Importer -- for importing DL settings and other info from maps created with the Universal VTT map format (.dd2vtt/.df2vtt/.Uvtt), as used by several map creator programs.
  • Page Navigator -- Easily move players from page to page, and allow players to move to pages by moving their tokens. Note: Version 2 have some known issues.
  • TruePageCopy -- Duplicate page graphics by chat command, or with the Duplicate Page button. (Partially obsolete since Roll20 implemented their update to Copying Pages in Q4 2020)


Dynamic Lighting

Dynamic Lighting is a Plus/Pro feature that changes what parts of the map are visible to the players as they move their tokens around. The light-blocking walls are achieved by paths on the walls layer, and tokens are used as point light sources. Scripts which modify either the light emitted by tokens or the walls which block the light belong in this category.

Not all APIs, or all their features work on both Updated DL and Legacy DL, you have to check them closer to know that.

  • DLTool(Forum) - A Dynamic Lighting Control Panel and Troubleshooter by keith
  • Door Knocker -- Script helps quickly open and close doors by controlling the dynamic lighting lines, as well as creating "windows"
  • DLEllipseDrawer -- Draw circles and ellipses on the dynamic lighting layer.
  • Dynamic Light Recorder -- Save dynamic lighting paths for map tiles and automatically regenerate later
  • LightCrumb (UDL version), by Aaron (not tested)
  • Move Lighting -- Move dynamic lighting polygon path objects between layers.
  • Walls -- Builds Dynamic Lighting walls with an exported .svg path file.
  • ShareVision -- Allows normal vision and darkvision to be shared.
  • ToggleDaylight(Forum) -- turn daylight mode on, off, or toggle it for LDL or UDL on the current page.
  • Script:UniversalVTTImporter For importing Dynamic Lighting lines & light sources to Roll20 from map creation programs that can export to Universal VTT-file format.

Following Mods no longer work as well as previous, since real Doors and Windows where introduce:

  • UDLWindows(Forum) -- API for creating "windows", i.e. DL lines that blocks movement, but doesn't block vision.
  • UDLPasswall(Forum) - Walls that block sight, but not movement


APIs that only works with Legacy

  • LightCrumbTrails(Forum) -- Produces lit, shared-vision breadcrumbs behind character tokens. This allows them to see where they've been on maps with dynamic lighting.
  • One-Way Dynamic Lighting(Forum) -- Allows you to set up dynamic lighting walls that allow you to see through one side, but not the other.
  • Torch -- A simple script for giving lights to tokens and turning off and on dynamic lighting.
    • UDL version in the works


Tokens

APIs that focus on interacting with tokens, or some aspect of them.

  • TokenMod -- An interface to adjusting properties of a token from a macro or the chat area. Very versatile and tons of options, and it can perform features of several other Token-related APIs.
  • Reporter(Forum) -- A script to poll the game and return info on Token/Character pairs, along with customized action tools.
  • SelectManager - can patch and extend token selection between APIs
  • Supernotes(Forum) -- script pulls the contents from a token's GM Notes field.
  • Clock Tokens
    GitHubLogo.png -- easy way to manage multi-sided tokens which are being used to represent progress clocks, or any other kind of incrementing timer or countdown.
  • Random Token Tinter -- will randomly assign (or remove) tints on tokens based on either a command-line list, a predefined Rollable Table, or a default rainbow (ROYGBV). See !!randtint --help for more.
  • TokenController(Forum) - Automate Token Movement for Patrols, following, roaming, and more
  • WeaponArcs(Forum) -- provides a means to add weapon arcs to tokens for visualization of range and targetable tokens
  • Faces(Forum) -- This is a short script that is designed to provide a quick visual interface for swapping token images and names. Great for any changeling. by Keith

Movement, Rotation, and Size

Scripts which are triggered by or change the location of tokens should generally be placed in this category.

  • Bump(Forum) - provides a way to invisibly manipulate tokens on the GM Layer from the Objects Layer, and vice versa.
  • TokenLock -- Allows GMs to selectively lock the movement of Player Tokens.
  • Carry Tokens(Forum) -- Allows tokens to "carry" and move other tokens, like dragging other characters or moving items.
  • Collision Detection -- Handles collisions between player-controlled tokens and a subset of path objects on the page
  • DupCharToken -- Duplicate a Character and Token, and add identifying number to Character and Token.
  • It's a Trap! -- Script for setting traps and detecting collisions with them at any point during movement. Has separate versions customised for specific games/sheets
  • KABOOM -- Creates explosion effects that move tokens away from or towards a point.
  • Marching Order -- Makes tokens follow each other in some specified order.
  • Measure -- Measure distances between multiple tokens, both from the corners and the center.
  • Random Rotate -- Allows the GM to easily rotate all selected tokens to a random angle.
  • Teleport -- Teleports tokens within a page or between pages either by chat menu or token movement by using teleport tokens on the GM layer.
  • Spawn Default Token(Forum) -- general idea is to automatically spawn the default token for a given "character" with various options for token qty, location/arrangement, and certain token properties such as size, side(for multi-sided tokens), light emission etc.
  • Token Fate -- Let fate decide! Randomly selects a token from the selected group.
  • Flip Tokens -- Flip graphics horizontally and/or vertically
  • SpinTokens -- Allows the GM to toggle spinning of selected tokens.
  • TokenController -- Allows GMs to quickly create patrol path shapes, assign tokens one or more paths, lock tokens in place, set tokens to follow each-other, and more. Uses complete menu system, no chat commands required.

Conditions, Status, Health

Tokens are used to represent player characters as well as non-player characters. Naturally, both occasionally get punched around a bit. Scripts in this category deal with the changing conditions of tokens, often but not necessarily as a result of combat.


Utility

Scripts in this category are a bit more meta, or does a variety of things, so they didn't fit neatly into any other category. These scripts assist with Roll20 itself more than they assist the game you're playing.

  • Calendar(Forum) by Steve -- Simple way to keep track of the current in-game date
  • Calendar (reworked)(Forum) by Julexar -- based on an older calendar-script by Kirsty
  • Campaign Survey(Forum) - helps you inventory the size of your campaign, by listing how many pages/characters/handouts/graphics/etc it has, how often each are used, etc.
  • Customizable Roll Listener -- Customizable responses to Mod or non Mod chat messages.
  • Hands Up(Forum) -- allows players to "raise their hand" to get GM's attention witha simple button that makes the players character flash.
  • Game Timer -- This is a simple script to court how long does player use the game room.
  • Lister(Forum) (by Keith) -- Mod that looks through your campaign and lists characters, handouts, pages, rollable tables and players. Can create handout with the report.
  • MetaMacros -- Precompiler enabling C-style textual substitution macros in macro definitions.
  • SelectManager -- a way to preserve the portions of a message that are present in a user-generated message but lost in an api-generated message (the selected tokens, who sent the message, and the playerid).
  • StatusInfo -- StatusInfo works nicely together with Tokenmod, DeathTracker, and InspirationTracker scripts. It shows condition descriptions whenever a statusmarker is set or when the command !condition is used, eg: !condition prone
  • Supernotes(Forum) -- script pulls the contents from a token's GM Notes field.
    • If the token represents a character, you can optionally pull in the Bio or GM notes from the character. The user can decide whether to whisper the notes to the GM or broadcast them to all players.
    • Finally, there is the option to add a footer to notes whispered to the GM. This footer creates a chat button to give the option of sending the notes on to the players.
  • NoteLog(Forum) -- provides an easy interface to keeping notes for your players.
  • Search(Forum) -- provides full text searching across handouts and characters (including attributes). Search respects permissions on handouts and characters.
  • RollStats(Forum) -- get roll statistics for your game and players
  • Triggered Cleanup -- ideal for Living Communities or West Marches style tables. Assists with the cleanup of tokens, optimizing the performance of other APIs through an API command.
  • Ongoing Cleanup -- ideal for long duration Campaign style tables. Assists with the cleanup of tokens, optimizing the performance of other APIs by deleting all tokens related to the character sheet linked to a token that is manually deleted.

Cards & Roll Tables

Mods specifically for interacting with Cards & Roll Tables.

  • Cards
    • Dealer(Forum) -- Deals and takes cards from players, can specify selection by deck (by Keith)
    • PeekCards(Forum) -- See what you played face down, but don't let others peek at them.
    • DealInit(Forum) -- Deals initiative cards for Savage Worlds
    • SummonCards(Forum) -- allows dealing cards from a deck to the table easily, particularly to predefined patterns/locations
  • Roll tables

Import/Export

Mods for importing content to Roll20, or for exporting content between games.

  • Table Export -- A script for exporting Rollable Tables between accounts.

Maps

D&D 5E

Many Mods( beyond the ones listed here) are made with Dungeons & Dragons 5th Edition in mind, or have specific commands tailored to work with the popular D&D 5E by Roll20-character sheet. In the one-click menu, most Mods made for 5E should have a name starting with D&D 5E. 5E is the system that have most system-specific Mods by a large margin. Several generic Mods have configuration settings tailored for the 5E sheets, such as GroupInitiative and GroupCheck.

  • Rest & Resource Management
    • 5E Rest in Style -- This script for the "D&D 5E by Roll20" character sheet, solves the error prone task of updating your sheet when resting.
      • Using !long-rest and !short-rest commands will update your sheet, and report to you everything it is doing.
    • Rest and Recovery(Forum) -- Short & Long Rest automation, by Keith
    • ShortRest -- Automating recovery of various resource during Short Rest
    • CashMaster -- for managing you currencies
  • Spells & Special Abilities
    • SpellMaster -- a high-performance total-replacement for the Spells page of the D&D 5E by Roll20-sheet, with several additional key features that go beyond the default spells page.
    • WildShape(Forum) -- Managing Druid Wildshape, changing token image, setting HP and temporary stats, etc.
    • Hunter's Mark
    • 5E Paladin Aura(Forum) -- Managing the proximity bonuses given by Paladins by notifying users in chat when a bonus should be applied.
    • Concentration -- Concentration keeps track of characters concentration, and reminds to do a concentration check.


System Toolbox

Scripts that deal with specific rules of a game system should be listed in a sub-heading here. If the appropriate game system is not listed, feel free to create the appropriate heading. Scripts under each system below may be designed for any use (in other words, had they been system-agnostic, they might fit under any of the sub-headings in the sections above).

It's A Trap! have several game-specific versions.

13th Age

  • 13th Age Official Character Sheet Companion -- Enhances the Official 13th Age Character Sheet with quick Escalation Die tracking, automatic recovery tracking, token setup, and automatic staggered and down icons.

AD&D2e

  • RPGMaster - set of APIs made for AD&D 2E sheet
    • RPGMaster Suite -- The RPGMaster Suite loader. Load this Mod to load the whole RPGMaster suite of Mods.
    • CommandMaster -- Manages the initialisation of a Campaign to use the RPGMaster APIs, communication and command syntax updates between the APIs and, most importantly for the DM, easy menu-driven setup of Tokens and Character Sheets to work with the APIs.
    • RoundMaster -- provides functions to manage tokens and entries in the Turn Order Tracker, and add statuses and effects to tokens, along with additional features such as Area of Effect display and Effect Macros that can be run when statuses are added, on or removed from a token.
    • InitiativeMaster -- supports initiative for RPGs using the Turn Order and the Tracker window.
    • AttackMaster -- provides functions to manage weapons, armour & shields, including taking weapons in hand and using them to attack.
    • MagicMaster -- provides functions to manage all types of magic, including Wizard & Priest spell use and effects; Character, NPC & Monster Powers; and discovery, looting, use and cursing of Magic Items.
    • RPGMaster Library -- The RPG version and Character Sheet version specific data & ruleset library for other RPGMaster APIs, which also provides some useful Roll Templates and API-callable library functions for character sheet table management, database management and other useful stuff. In future, multiple versions of this library may exist for multiple RPGs, but for now it is just AD&D2e.

Ars Magica

Chronique Oubliées

  • COFantasy -- Combats, Skills and Spells support

Cypher System

  • Cypher System Sheet -- Enables the applying of stat cost, recovery roll advance, auto calculation of PC state and damage track in the Cypher System Sheet, from the roll template or sheet buttons, for both the "English" and "French" versions.
  • Cypher Systems by Roll20 Companion -- Enables the applying to characters of Stats costs and Recovery rolls advancement from the chat roll template, as well as applying Damage to NPCs.

D6 System

The "D6 System" includes a number of games from West End Games which utilize the same (or very similar) game mechanics. Scripts which are more specific to a single game than the system as a whole should be categorized there.

  • Wild Dice -- Implements the Wild Dice rolling mechanic, used in "Star Wars D6", "D6 Adventure", "D6 Fantasy", and "D6 Space"

Earthdawn

  • Earthdawn (FASA Official) -- A companion to the Earthdawn (FASA Official) and 1879 (FASA Official) character sheets, this provides many features such as automatically creating token actions and helping with accounting, calculating Target Numbers and checking for number of successes, Etc.

Exalted

FATE

  • Fate Dots -- Provides numbered multi dots for Fate stress boxes.

HERO Systems

This includes Champions, Star HERO, Fantasy HERO, Traveller HERO, etc.

Numenera

Pathfinder

Pathfinder 2nd Edition

Savage Worlds

  • Script:Savage Worlds - Raise Count -- Counts raises on a roll against a given target number
  • Savage Worlds Raise Roller -- Rolls for extra or wildcard and then shows a list of target numbers that are success or success with raises.
  • TokenMod: Changes token properties This enables macros to modify tokens, and even apply Wounds or change rotation.
  • Savage Worlds Status Changer: Want to remove the Stunned state and apply the Distracted and Vulnerable states with one command? Want to do that for 5 tokens with one command? This enables macros to set token status indicators like shaken, vulnerable, and prone. These can be set manually by clicking on the token, clicking the indicator button, scrolling the menu, and clicking on the status indicator, but with macro control you could set them by name or set them for several Extras at the same time.
  • DealInit(Forum) Want to quickly handle initiative for players with Quick or Level Headed? Roll20 API Script to Deal Initiative for Savage Worlds Games. DealInit supports Savage Worlds style card based inititive by dealing cards to the Turn Order and sorting the order by suit. It does not, however, utilize the Roll20 deck system. Instead it manages an internal array of cards that are reshuffled when the deck runs out or a joker is drawn. It also checks character attributes for any SW Inititative Edges and handles them appropriately.

APIs Not in the Install menu:

  • Bennies: to ease dealing Savage Worlds Bennies to players. You can also use it to grant Conviction, count Mass Battle tokens, or keep track of Social Conflict Influence.
  • Import Stat Block -- NOT WORKING, APRIL 2020 This saves a lot time creating Character Sheets for NPCs and creatures from the bestiary. All you have to do is copy a stat block from a PDF or other source into the GM Notes section of a token, then type "!SW-Import" into the q Chat tab and it will create the Character sheet for you.


Shadowrun

5E

  • Shadowrun 5th Edition -- API helper for the "Shadowrun 5th Edition"-sheet by Cassie
  • SR-RollExtender -- Deals with Shadowrun specific rules like glitches and extended rolls. For the "Shadowrun: 5th Edition (Advanced)" sheet.
  • SR-NextPass -- GM aid to handle moving on to the next initiative pass

Star Wars

Scripts for the various Star Wars systems.


Starfinder

Trail of Cthulhu

  • GUMSHOE -- A point-spending script for GUMSHOE games. Integrates with supporting character sheets.


Warhammer Fantasy Roleplay

2E

  • WFRP 2E Actions (Havoc) -- Functions and Roll Templates in support of the Warhammer Fantasy Roleplay 2E Sheet by Paul "Havoc" Stein

4E

  • WFRP4e -- Oops!, Critical Hit Location, and Critical Hit result support for Warhammer Fantasy 4th Edition.

Other


Library/Meta Scripts

Library scripts are generally not intended to be used alone or directly by the user. These scripts will not do anything for your campaign directly, but rather they create functions to be used by other Mods.

Mods installed from the one-click menu should automatically install any Library scripts that are needed for them to work, or warn about needing additional Mods installed.

What Are Meta-Scripts?

Main Page: API:Meta Scripts

Meta-scripts are scripts that offer a level of "pre-processing" to other scripts by giving the user ways to change the message before other scripts receive it. To understand what a metascript can do and how they can help, it helps to start with understanding the different message types.

In a Roll20 game, you have simple messages... these are things that you type into the chat input and they hit the chat output pane. They can be plain text or Roll Templates, whispered or public, and they can include Inline Rolls ( [[1d10]] ), character attribute calls ( @{character|attribute} ), or Roll Queries( ?{What?|Option1|Option2} ).

You also have Mod/API messages... these are prepended with an exclamation point, and they do not (in and of themselves) hit the chat pane. They can also include inline rolls, sheet calls, or roll queries. At this point it pays to think of the message as a thing -- an object -- with certain describable properties. One property is the text that was entered into the chat input (sometimes called the command line or the message content). These message objects get handed to the scripts you have installed to see if any script needs to take an action. The scripts hand the same message object off, one script to the next. Typically, each script is looking to see if it needs to do anything with the message by the message handle (the part of the command line that immediately follows the exclamation point). 

!thehandle --arg1 --arg2

The scripts are processed (usually) in install-order, handing the message over in a chain until there are no more scripts to inspect the message to see if they should take action. For standard scripts (e.g. non metascripts), the destination script designated by the handle is typically the end of the line. You want TokenMod to pick up your call to !token-mod, and you want ChatSetAttr to pick up the call to !setattrs. The message will continue on through the rest of the scripts in the queue; it's just likely that none of them will have anything to do with it.

Until recently, that was the end of the discussion.

Then The Aaron discovered a quirk of script ordering that would let a script shin-kick its way to the front of the chain of scripts waiting to handle the message in order. In other words, no matter if you installed one of these shin-kicking scripts later in your script library, it would still get the message first. That discovery gave birth to metascripts.

Metascripts use the shin-kicking technique to get to the head of the line, but they don't look for a particular handle of their own. They don't aim to be the end-destination of the message. Instead, they are looking for text triggers within the command line that tell them to take particular actions on the message before they hand it off (to the queue of regular scripts waiting to see if they should handle the message). In effect, they offer a universal level of "pre-processing" to other scripts without needing the coding infrastructure duplicated by each individual scripter. {{Meta Metascripts can alter the command line of the message, alter other properties of the message, or fire other scripts, all with the goal of getting the message into a particular shape by the time that the intended-destination script would pick it up.

Meta Scripts

Script:APILogic - can conditionally include/exclude parts of a command line using comparison logic. APILogic(Forum)

Script:Muler - can store and retrieve variables from mule tables, offering rollable or static access.

  • It can bypass HTML character replacement requirements for roll queries, and with ZeroFrame can operate recursively over new meta-constructions.

Plugger - offers a way to run script commands at meta-speed, making it easy to plug-in small, single-job code snippets or to execute full calls to other scripts.

  • Optionally, Plugger can return some result from the plugged-in code to the command line (see this discussion(Forum) about converting a range script to a Plugger plugin to return a range modifier).

API:Meta-Toolbox
APIs to patch other API commands
Meta-Toolbox Scripts

created by Timmaugh

Related APIs

Script:SelectManager - There is a quirk of Roll20 that when a script sends a chat call to another script (we call this an 'API generated message'), the tabletop's selected tokens are not maintained with the new message.

  • SelectManager returns those to the API generated message. It also allows you to "virtually" select tokens, replacing what is actually selected on the tabletop, or adding to that set. It can also iterate a command on a per-token basis, returning individual information to each token's command line.

Script:Fetch - extends the things that can be returned from tokens, characters, etc., including a default value.

  • It offers the ability to designate a default value in case the thing asked for isn't found, and offers a standardized framework to access a repeating attribute without having to know its position on the character sheet ahead of time. Aside from retrieving information by token or character name, Fetch can also use the selected token, the speaker, or a token from the Turn Tracker.

MathOps - provides an inline math parser, offering more functions than are available in a typical inline roll.

Script:ZeroFrame - brings a script framework to scripts that are built to work with it... allowing the user to loop over their installed metascripts and set the order for an individual pass over the loop or for all passes.

  • For instance, sometimes you might need to run a Fetch construction before you base APILogic off of what you return. Other times, you might need to run the APILogic comparisons before you know what you need to Fetch. ZeroFrame also allows you to defer inline rolls (only resolving them after all required meta-processing has completed), to defer other meta-constructions, and to output a simple message (hitting the chat window) and skipping the waiting queue of API scripts.
  • That ability means you can utilize metascript constructs in what you want to be a normal message. So even though you don't have a destination script in mind, you can still use APILogic to conditionally construct your line, or you can use Muler to return a variable, or you can Fetch a token property that isn't available with the typical Roll20 syntax, or you can use Plugger to get the range between two tokens... and then output that to a roll template in the chat window.

Visit the Meta Toolbox page for an overview of the them, with further links to each. The Meta Script Toolbox(Forum)-thread is also a good visit.

  • InsertArg(Forum) -- script preamp, siege engine, menu maker, command line constructor


Mods needing manual install

Some Mods aren't available in the One-Click Install in Roll20, but the code might be hosted elsewhere and need to be manually installed into your game. This is an attempt to list prominent ones.

See Also: Mod:Short Community Scripts

Roll20 repo, but not in menu

This is a list of Mod that are still hosted in Roll20's Mod script repository, but for one reason or other isn't available in the One-Click install.

  • Battle Royale(Forum) -- Instantly create a GM-less PvP experience! Even handles doors, invisibility etc.
  • Creature Gen -- Generate combat ready tokens from PRD and D20PFSRD statblocks (Obsolete - no longer supported)

Mods hosted elsewhere

Other notable Mods, that aren't available in the one-click install. Some are larger Mods, and others just smaller snippets. Needs to be installed manually.

Map & Token

Other

Special Thanks

In Summer 2022, API where renamed as Mods, and the work to update the various pages started. The Index had continued to be updated sporadically.

In early 2021, Andreas J. did a major revision of the page, reorganizing with better categories, add several newer and popular APIs to the list, and added relevant forum/wiki/documentation links to most listed APIs, so it would be easier to learn about them.

The category cleanup on the API index is something I intend to bring to the API 1-click Install, as the One-Click Menu is currently pretty hard to browser, as something like half of the APIs are categorized under "Utility", and there would be a benefit for all D&D5E-specific API to be in a separate category from the other game-specific APIs. -Andreas J. (talk) October 2021

Roll20 wants to give special thanks to Brian Shields and Aaron C. M. for their contributions to the community and creation of the API Script Index (in 2014).

Retrieved from "https://wiki.roll20.net/index.php?title=Mod:Script_Index&oldid=33229"