Mod Scripts (formerly known as API Scripts) are a powerful tool in the Roll20 toolbox that allow you to do amazing things in your game using the power of Javascript. For example, you can run advanced calculations related to your favorite system, unlock a huge library of chat commands and macros to manage your tokens, and even build entire knowledge bases with map markers that link all of your game handouts together.
The Roll20 Mod Scripts system is unique in that it runs your own code on our servers. We took this approach because it allows us to make sure that your automations run all the time no matter who is in your game – whether it’s a full gaming group gathered with the GM and all the players, or just a player logging in between sessions to update their character. In addition, it gives the GM powerful control to unlock advanced capabilities for all players to do things they wouldn’t normally be able to in the interface.
Unfortunately, this system has languished a bit over the past few years. It hasn’t received frequent updates and some of the newer features that we’ve added to Roll20 recently aren’t fully supported by the Mod Scripts system. Overall, the system is really starting to show its age, with particular issues around logging, support for modern Javascript coding styles, and other issues being common complaints of our power users.
We’ve heard you, and we know how important this feature is to you. That’s why we’re pleased to announce that we’ve got a major update for the Mod Scripts system on the way! And today I’m going to preview what’s coming and share our plans for the future.
Modern Overhaul
First off, the entire Mod Scripts system has been rebuilt from the ground up in terms of the code itself. A lot of these changes are ones that you won’t directly see, but they were vital to bring the codebase up to our current standards and make sure that we can easily work on it going forward.
We’ve upgraded the underlying foundation from legacy code written a decade ago to modern ES6 Javascript. We’ve added extensive unit tests to help ensure that these changes are fully backward compatible (and that your existing Mod Scripts will continue to work just fine). This will also make it easier for us to continue to work on this system in the future with confidence as we add new functionality. We’ve also gone back through and changed out some of the libraries that we’re using behind the scenes to make sure we’re using ones that are actively maintained and receiving regular updates.
Better Logging
Let’s start talking about the changes that our resident scriptomancers will see on their end. Logging is a major part of script development, and previously we weren’t great about giving context to what was going on when there was an error thrown, which could make it difficult to debug a script. Now, whenever possible, output messages will list one or more context objects.
For example, when calling toBelow() with a character object, you might see this error:
ERROR: toBelow() must called with a Roll20 graphic, text, or path Object. Called with [Roll20 character -NM0tVij02hIfnoTdihc].
The additional bracketed info at the end will greatly help script authors figure out what needs to change to fix errors going forward.
Better Performance
We’ve greatly improved the performance of some of the most-used functions in our library. For example, toFront() and toBack() should now be a lot faster. We’ve also reworked the way that a lot of our validation and event handling worked internally which should lead to overall better performance in many types of scripts.
Supporting New Functionality
We’ve spent a lot of time making sure that we fully support some of the things that were missing from the Mod Scripts library that you could do in the VTT interface.
Our new Page Folders feature is now fully supported, and you can now create folders, change their order, place folders into other folders, and place pages into folders and set their order.
We’ve added several new functions for tokens on the tabletop, including the ability to make copies of existing tokens that are in your game, which offers some exciting new possibilities for making use of tokens from Marketplace asset packs. You can also now create a token based on the default token stored in a Character, as well as tokens based on cards in card decks, and rollable tables.
Overall there are more than a dozen new functions that your scripts can take advantage of to unlock even more capability in your Roll20 games.
Building for the Future
This major update is not only the first one for Mod Scripts in quite a while, it’s also the first step of our renewed commitment to making sure that the Mod Scripts ecosystem can thrive. We’ve got plans to support even more new functionality, improve the developer experience, and fix as many bugs as we can squash over the coming months.
We can’t wait to get this into your hands, and we anticipate making this available to everyone by the end of March. Look forward to a forum post in the near future with all of the technical details. Let’s see what you can build with these new tools for your next game session!
Try Mod Scripts with a Roll20 Pro subscription.