[New] SwapTokenPositions

SwapTokenPositions v1.0.0 SwapTokenPositions is a Roll20 Mod (API script) that allows GMs and players to quickly swap the positions of two selected tokens on the same page. It features customizable animation effects, persistent global settings, and clear chat feedback. Key Features Seamless Swapping : Select exactly two tokens and run `!swap-tokens` to switch their positions. Two Animation Styles : beams : Arcane beams cycle between tokens before the swap. transport : Vertical light columns and shimmer effects at both locations. Fully Customizable : Adjust duration (1-10s), beam types, and burst effects via command flags. Persistent GM Defaults : GMs can save their favourite configurations globally using the --save flag. Instant Swaps : Set FX to none for a silent, instantaneous relocation. Macro Support : Use --install-macro to automatically create a global "SwapTokens" macro. How to Use Basic Command `!swap-tokens` (Swaps the two currently selected tokens using your default settings) Customization Parameters `--duration <1-10>` : Seconds to play the animation. `--mode <beams|transport>` : The animation style. `--beam-fx <value>` : (Options: none, beam-magic, beam-fire, beam-frost, beam-holy, beam-death) `--burst-fx <value>` : (Options: none, burst-holy, burst-magic, explode-fire, burn-holy, etc.) Examples `!swap-tokens --mode transport` `!swap-tokens --duration 5 --beam-fx beam-fire --mode beams` `!swap-tokens --beam-fx none --burst-fx none (Instant swap)` GM Management Commands `--save` : Save current flags as the new defaults (e.g., !swap-tokens --duration 3 --save). `--show-settings` : View your current persistent defaults in chat. `--reset-settings` : Restore factory defaults. `--install-macro` : Automatically creates a global "SwapTokens" macro. `--help` : Opens the in-game help menu. Installation Copy the source code. Create a new script in your Campaign's API Settings. Paste the code, save, and you're ready to go! Download the source code via Dropbox . View the files in the roll20-api-scripts GitHub . The Roll20 One-Click installation is coming soon. View the introduction video .

Hi MidNiteShadow7! I have a player whose character has this ability. Does your script allow a player to swap positions with a token they do not control (another PC, for example)?

keithcurtis said: Hi MidNiteShadow7! I have a player whose character has this ability. Does your script allow a player to swap positions with a token they do not control (another PC, for example)? At the moment, it only moves tokens you can select. I need to check the mods' ability (still new to Roll20 & DnD) to use names and/or IDs. I was going to look to expand to that. Although the player cannot do it, the DM can do it for them using this mod.

If you set the script up to read token IDs, then it can be done with an @{target|token_id} in the macro.

keithcurtis said: If you set the script up to read token IDs, then it can be done with an @{target|token_id} in the macro. Thanks. I'll take a look and work on an update.

I have edited the OP  to add links to  the files in the GitHub pull request  and another to  view the introduction video  on YouTube .

Your videos are always a treat!

Neat!  That's certainly an epic video introduction!  =D  I left a few comments on your PR.  Nice addition!

The Aaron said: Neat!  That's certainly an epic video introduction!  =D  I left a few comments on your PR.  Nice addition! Thanks. I have made the changes to address those issues, and they are ready for review whenever you get a moment.

Looks good to me.  I think they usually do merges on Tuesdays, so it will likely get picked up next week.

The Aaron said: Looks good to me.  I think they usually do merges on Tuesdays, so it will likely get picked up next week. Great. Thank you for performing the checks and the advice. Appreciated. Enjoy your weekend.

The SwapTokenPositions script on the Roll20 API Script GitHub repository has now been added. Hopefully, it will appear in the One-Click installer in the next week or two.

v2 modular rewrite + new FX pipelines Added New staged FX pipeline with explicit origin, travel, and destination phases. New FX flags: --origin-fx , --travel-fx , --destination-fx . New timing flags: --origin-time , --travel-time , --destination-time , --swap-delay , --destination-delay . New travel visibility flag: --travel-mode with values normal and invisible . Preset system with portal , lightning , shadow , fire , magic , transport , and none . --instant flag to force immediate swap. Backward-compatibility parsing for legacy flags with deprecation warnings. Modular multi-file source structure under src/ . Local build tooling ( rollup ) to generate single-file artifacts for Roll20. Build banner metadata in generated output, including build timestamp. Explicit same-page validation for selected tokens before swap. Delayed pipeline safety checks that cancel gracefully if tokens disappear mid-sequence. Changed Refactored internal architecture from a monolithic file to source modules with a generated bundle. Replaced the v1 mode-centric flow ( --mode + repeated beam cycle) with a staged pipeline ( origin -> travel -> swap -> destination ) driven by stage FX and timing flags. Deprecated --mode (mapped for compatibility: beams -> --preset lightning , transport -> --preset transport ) --duration (replaced by --swap-delay ) --beam-fx (replaced by --travel-fx ) --burst-fx (replaced by --destination-fx ) The code can be viewed and downloaded from the Roll20 GitHub pull request or via Dropbox . I'll post when versions 1 and 2 are added to the One-Click Installer.

To track requests and bugs, I have created a tracker on GitHub for this mod:&nbsp; <a href="https://github.com/users/steverobertsuk/projects/4" rel="nofollow">https://github.com/users/steverobertsuk/projects/4</a> keithcurtis said: Hi MidNiteShadow7! I have a player whose character has this ability. Does your script allow a player to swap positions with a token they do not control (another PC, for example)? keithcurtis said: If you set the script up to read token IDs, then it can be done with an @{target|token_id} in the macro. I have added a GitHub Issue to track the request to handle token names and IDs to allow tokens not selectable by players to be moved if enabled by the GM. This will be part of the v2.1.0 release. The status of the feature can be tracked here:&nbsp;<a href="https://github.com/steverobertsuk/roll20-api-scripts/issues/15" rel="nofollow">https://github.com/steverobertsuk/roll20-api-scripts/issues/15</a>