Character Vault
Any Concept / Any System
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:Introduction"

From Roll20 Wiki

Jump to: navigation, search
m (Patreon and Tipeee Linking Rules for Community Script Contributors)
Line 1: Line 1:
<div style="background:#f0e2a1; border: 3px solid #dbc870; padding: 10px;">
{{HCbox| {{hc|articles/360037256714-API Here}} }}
''Roll20 is no longer maintaining this document on the community wiki. For the most up-to-date information please visit this page on our help center for assistance: [ Here].''</big>
{{pro only}}
{{pro only}}

Revision as of 12:54, 17 September 2021

Attention: This page is community-maintained. For the official Roll20 version of this page, go to Roll20's Help Center for assistance: Here .

Roll20 API Getting Started

Community Scripts



Go to the API:Use Guide-page for how to use/install existing APIs. This is an introduction to creating & modifying API Scripts.


API Script Creation - Introduction

The Roll20 API provides a powerful way to customize and enhance your game. You write scripts (little pieces of code) that tell Roll20 what to do during gameplay (for instance, move a piece, add a status marker to a token, or even roll dice). It's simple and straightforward to get started, but the possibilities are endless.

What do I need to get started?

Scripts for the Roll20 API are written in JavaScript. You only need a basic understanding of the language to get started, but if you want to learn more about JavaScript, this Codecademy course can help teach you.

How does it work?

You write scripts that listen to events that happen during the game. Scripts can check to make sure that rules are followed, change properties on objects and tokens, and even provide custom chat commands. The scripts you write run across the entire game, and affect things the GM does as well as all the players. Advanced scripts can also run independently, performing automatic actions such as moving a token on a patrol route or nudging players when their turn is taking too long.

To get started, your first stop should be the Use Guide.

Where can I find pre-made scripts?

The API Script community is fairly active with members creating and discussing scripts all the time. There are 3 basic places to look for new scripts:

  • The GitHubLogo.png on Github. This is where you'll find the current version of scripts that authors have submitted for inclusion in the repo.
  • The Roll20 API Scripts(Forum) This subforum is where scripts tend to show up first and where discussion happens about scripts that are being written or need changes. This is also where you can post and ask for help from the community in creating a script you've thought of, or finding a script to fill a need.
  • The Wiki's API Script Index. This is a good source of information about popular scripts, but it's not too well maintained nor does it describe all APIs that currently are avaiable in the one-click menu.. However, if you'd like to document some scripts you find useful, their authors would certainly appreciate it!

Contributing API Scripts to the Community

If you create a script that you'd like to offer to the rest of the Roll20 community, you can submit it to be included in the Roll20 API Script Repository. Having your script approved by the Roll20 staff and included in the repository will unlock the
API Scripter
forum tag for your account as will allow you to advertise via Patreon or Patreon-like sites (see below for more info). To find out what you need to do to correctly submit your script to the repository go to the Official Roll20 API Script Repo.

Check the following guides for how to submit content to Github.

Patreon and Tipeee Linking Rules for Community Scripts Contributors

For API script authors that are contributing to the Roll20 GitHubLogo.png, they are approved to advertise via subscription/donation service sites: Patreon and Tippee. Roll20 is not responsible for any payment transactions and cannot enforce any private arrangements.

In order to qualify, an API script author must first have their script contribution approved by the Roll20 staff and included into the Roll20 API Script Repo.

You will want to include your Patreon or Tipeee account information in the script.json file that should be included with your script submission on GitHub.

The json file should have one of these fields added to it if you wish to advertise with Patreon or Tipeee:

patreon: Place the URL for a Patreon campaign here, and it will appear under your script's description when selected. (e.g."<name>")
tipeee: Place the URL for a Tipeee here, and it will appear under your script's description when selected. (e.g. "<name>")

For more information, see

Linking to Patreon/Tipeee on the Roll20 Forums

Linking to Patreon or Tipeee on the Roll20 Forums are only permitted for pre-approved community members who have contributing either Character Sheets or API Scripts. If you wish to solicit users directly for funding you may do so privately, but no such links are permitted in a public forum without any contributed material.

Related Pages

  • Complete Guide to Macros & Rolls‎
    • q Text Chat - where the roll results appear, & info on the common chat commands
    • Dice Reference - Comprehensive list of how the Roll20 dice-rolling syntax works, and list the features available
    • Macros - How to create macros, and other info on how the Roll20 qText Chat works, like referencing stats on character sheets, roll queries, nesting macros & initiative
    • Roll Templates - a method of formatting roll results in the chat, with some extra functions
    • API(Pro Only) - API commands can be used in the qText Chat