Roll20 Mod Scripts (formerly known as API Scripts) are powerful tools that allow Pro subscribers to do amazing things in their games using the power of Javascript. For example, you can run advanced calculations, unlock a huge library of chat commands and macros to manage tokens, and even build entire knowledge bases with map markers that link game handouts together. Learn more about Mods in our Help Center, and check out our Masterclass Video!
This blog features a new script from Keith Curtis that provides an interface for aligning, distributing, and scattering tokens easily. Read on to learn more.
Keith Curtis is a professional RPG illustrator and cartographer with an extensive range of publishing credits. He has played and worked with many systems, starting with the earliest days of the hobby. Formerly a Roll20 forum moderator, he now supports the community as a Forum Champion and Marketplace Creator, works as a Conversion Contractor for Roll20, and continues to freelance in the RPG industry.
Token Alignment, Distribution, Snapping, and More
The Align script is a visual alignment and positioning tool for the Roll20 VTT. It provides GMs and players with a convenient, clickable menu to precisely align, distribute, snap, stack, and scatter tokens — all without typing out macros or entering coordinates manually.
This script was built to provide fine control over token layout with safeguards like edge detection and undo support. Arrange a battlefield, a city block, or a grid of NPCs with a quick click or two. This script works with any version of the tabletop and doesn’t care which sheet you are using. It only knows tokens. It ignores paths.
Key Features
- Align Tokens: Line up tokens by left, right, top, bottom, center, or center-x / center-y axes.
- Distribute Tokens: Evenly distribute selected tokens along a horizontal or vertical axis.
- Distribute Spacing: Maintain even gaps between tokens horizontally or vertically.
- Snap to Grid: Align tokens to the grid with a specified number of empty grid spaces between them.
- Z-Index Stack: Reorder tokens visually from any corner, sending them front-to-back in order.
- Scatter Tokens: Randomly scatter tokens across the page or within a selected area, with optional grid snapping.
- Undo: Revert the last transformation per player with a single click.
- Interactive Menu: Clean, styled chat menu with buttons for each function.
- Edge Protection: Tokens won’t overflow off the page — After a confirmation dialog, the script auto-wraps or expands the page as needed.
How to Use
Type !align in chat to bring up the interactive menu. Then click any button to apply that action to your selected tokens.
You can also issue direct commands using the following syntax:
Align
!align --align|left
!align --align|right
…also: top, bottom, center, center-x, center-y
Distribute
!align --distribute|left
!align --distribute|right
…also: top, bottom, center, center-x, center-y
Distribute Spacing
!align --distributespacing|horizontal
!align --distributespacing|vertical
Snap to Grid
!align --snap|horizontal|1
Snaps tokens to the grid with 1 empty square between them horizontally. Works vertically too. input any non-negative number.
Stack Z-Index
!align --zindex|top-left
Stacks tokens front to back from the chosen corner. Options: top-left, top-right, bottom-left, bottom-right.
Scatter Tokens
Scatter tokens randomly on the page or within the selected token area.
With snapping:
!align --scatter|page|snap
!align --scatter|area|snap
Without snapping:
!align --scatter|page|nosnap
!align --scatter|area|nosnap
Undo
!align --undo
Reverts the last transformation you applied. This was the toughest to do. Depending on what other transformations you may have applied, this may fail or do unexpected things.
Help
Click the “?” button in the title bar of the menu to display the in-game help panel, which includes all the commands and their meanings.
One-Click Installation
- Open your game’s API Scripts page
- Click “Roll 20 Library” under “Mod Library” link
- In the Script Library dropdown, search for “Align”
- Click Add Script
- Scroll down and click Save Script
- Once installed, type !align in the chat of your game to open the menu
Let Keith know what you think about Align here!
Tell Us What You Need
Our Suggestions & Ideas forum is the best place to request and vote for tools and features that would improve your Roll20 experience. If you have ideas about how to make the tabletop better for your games, let us know by posting, commenting, and voting. Feel free to also join us on Discord, where you can hang out with other community members and connect directly with staff for brainstorming, troubleshooting, and announcements.