The Roll20 Mod Script Sandbox runs a server-side virtual machine for each campaign. Scripts do not run on players’ computers. The sandbox keeps one campaign’s scripts from affecting another campaign, and it stops a script that would otherwise run forever.
Mod Script Sandbox v1.0 and v1.5 use this same model. v1.5 adds Beacon sheet access (getComputed, setComputed, performAction, and related character methods) as well as other functions. Which sandbox a game uses is separate from whether the tabletop is Jumpgate.
How it Works
If you’re curious in the technical details of how the sandbox functions, here’s a brief diagram:
User-written scripts ===> Mod Script Server ===> Campaign Sandbox <===> Real-Time Sync Server
The Mod Script Server listens for activity on your campaign. When someone is in the game, it starts a sandbox and loads that game’s Mod Scripts. When the game is empty, the sandbox stops. Saving and restarting the sandbox runs the scripts again, fires ready again, and drops pending setTimeout timers. The sandbox sends and receives data through the real-time sync server, which is how it responds to events and changes the game.
Every script in a game shares one global scope. A var or function at the top of one script is visible to the others, and two scripts that use the same name will overwrite each other. Wrap a script in an IIFE when its names should stay private. state is also shared across scripts and is kept between sessions. Campaign().nodeVersion is the Node.js version. There is no require, no DOM, and no console.log — use log(). An uncaught error can stop the sandbox for every script in the game; see Mod Scripts: Debugging.
Restrictions from Normal Javascript
While Roll20 scripts are Javascript, there are some restrictions you should be aware of if you’re used to programming Javascript for websites. Roll20 scripts are executed in a separate sandbox from the Roll20 site. This provides an additional layer of separation and security for our system and your players. This sandbox means that:
- You cannot make HTTP Requests (AJAX).
- You cannot load external scripts or libraries (for example jQuery). Underscore.js is already available as the
_global. See underscorejs.org. - The environment is Javascript, but it is not an environment in a browser, so there is no DOM, page elements, CSS,
document,window, etc.