Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Create a free account

[Script] Align – Token Alignment, Distribution, Snapping, and More

June 27 (1 month ago)

Edited June 27 (1 month ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

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 Classic or Jumpgate and doesn't care which sheet you are using. It only knows tokens. It ignores paths.

[Quick Video Demo]

[Code(Until in the one-click repo)


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.


Installation

This will be on One-Click soon, or you can pick up the code immediately from here.

Manual Instalation:

  1. Open your game’s API Scripts page.
  2. Click "New Script"
  3. Paste the Align script and name it.
  4. Save the script.
  5. Once installed, type !align in the chat to open the menu.

One-Click Installation (Coming soon, but Recommended)

  1. Open your game’s API Scripts page.
  2. Click "Roll 20 Library" under "Mod Library" link.
  3. In the Script Library dropdown, search for “Align”.
  4. Click Add Script.
  5. Scroll down and click Save Script.
  6. Once installed, type !align in the chat to open the menu.
June 27 (4 weeks ago)
Gold
Forum Champion

That's powerful and interesting. Thanks for contributing your code to the Community.

Done this kind of work 1000's of times by-hand, and I don't mind it (placing tokens around a map, or organizing a Tokens Page for a campaign). But having a Mod script to help will be great once I get used to it. 

June 27 (4 weeks ago)
Andrew R.
Pro
Sheet Author

Snazzy! I'll try it with my 13th Age & The One Ring games.

June 28 (4 weeks ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

Thanks folks!

Let me know if you need more options supported.

June 28 (4 weeks ago)

I love this! One of the things I wish Roll20 had is more support for tabletop war-games. Namely, some sort of tools for managing tokens in formations. This mod will help a lot for the occasional mass-combat events in my campaign.

One thing I might suggest is to add a tool for rotating all the tokens to the same facing, so that they’re not only all lined up, but all facing in the same direction. (At least in cases where the graphics have uniform orientation to start with.) Also maybe a tool for rotating the whole selection around either a centerpoint or one of the corners.

June 28 (4 weeks ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

I think The Aaron has a script that might do that. I'll ping him.

June 28 (4 weeks ago)
The Aaron
Roll20 Production Team
API Scripter

I have a script that might be part of what you want with positioning all the tokens in a unit shape.  It builds as close to a square as it can though it doesn't account for token size variations (always intended to work on that..)

MarshalTokens: https://app.roll20.net/forum/permalink/10360535/

You can use TokenMod to set the facing all the same, so with the above script and TokenMod, something like this would get you a unit facing whatever the same direction:

!token-mod --set rotation|0
!marshal-tokens

You could then group the tokens and selecting them will let you rotate or move them as a group.   


June 28 (4 weeks ago)

Thanks!