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 ] New Feature: Token Page Management Video . 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. Update: Token Page Management Don't want to read a bunch of commands? Watch the demo video . The Align script now has a new section called Token Page . A Token Page is page in your campaign that contains deployed default tokens of all or most of the characters in your game. Token Pages are a feature of all Roll20-produced adventures and serve many purposes. Some examples: They provide a place where you can update many tokens at once. Say if you wanted to set all tokens to display bar1 below, you could easily create a macro that does this on all tokens and updates the default token with the Token-mod script. They allow you to visually organize groups and factions, related NPCs, or monster types within your game. They provide a place where you can quickly grab and copy related tokens, and then paste them onto another page. If you have a bunch of individualized tokens that represent a common character sheet, they can be stored here. Lets say you have ten town guards that represent the same base sheet, but each one has a different name and art. To use the new tokenpage commands, grab any group of tokens on the page, plus exactly one text label, and run the command !tokenpage --group. The tokens will all line up in a tight stager, and be surrounded by a box color of your choosing. The tokens are staggered so that they can be placed compactly and reduce the chance that nameplates will overlap and become unreadable. Here is an example: Before: After You can manage as many groups as you want on a page. The tokens are staggered by regular amounts, and the box is drawn to snap to 10 pixel values, regardless of the grid size, to make them easier to keep neat. The script will handle and adjust to tokens of different sizes: You can also define and update default label and container box styles. The new section: Token Page Does not work on Legacy Tabletop. This is because shapes are drawn differently between legacy and Jumpgate (modern Roll20). The Align functions continue to operate on either VTT engine. All Token Page functions use !tokenpage as the base command. Example: !tokenpage --group Arrange These commands organize tokens into structured groups with labeled bounding boxes. All use !tokenpage as the base command. --group: Groups all selected tokens into a single aligned row with a small vertical stagger. Automatically creates a bounding rectangle around the tokens and can optionally label the group. --xoffset|N: Applies an additional horizontal offset (in pixels) to all tokens in the new group. The button defaults to 10 px increments, which matches the setting behavior. --yoffset|N: Applies an additional vertical offset (in pixels) to all tokens in the new group. The button defaults to 10 px increments, which matches the setting behavior. Note: When a group is created, the script removes the most-overlapping previous container rectangle (if any), snaps the new box to the grid, and adds 10 pixels of padding between the box and tokens. Manual Commands The following options do not have a button, but can be input manually, or used in a macro. --label|TEXT: Adds or updates a label for the group. If no label object is selected, creates a new text label using the saved label style. Example: !tokenpage --group --label|Bandits --labelposition|above|below : Specifies whether the label appears above or below the bounding box for this group. Overrides the default label position. Define These commands define reusable defaults for boxes and labels, controlling how future token groups are displayed. --definebox: Select a rectangle to define the default box style (fill color, stroke color, opacity, and stroke width). Future boxes will use this style automatically. --definelabel: Select a text object to define the default label style (font, size, color, alignment, bold/italic). Future labels will use this style automatically. --definelabelpos|above|below: Sets the default label position (above or below the bounding box). Used whenever --labelposition is not specified. Here is an example taken from my own campaign: 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 to open the menu.
