Skip to content

feat(TokenController): Rewrite for Jumpgate and Legacy games - #2361

Open
steverobertsuk wants to merge 31 commits into
Roll20:masterfrom
steverobertsuk:sr/tokencontroller-v5-0-0
Open

steverobertsuk wants to merge 31 commits into
Roll20:masterfrom
steverobertsuk:sr/tokencontroller-v5-0-0

Conversation

@steverobertsuk

@steverobertsuk steverobertsuk commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

5.0.1 (2026-11-01)

Features and a fix from user feedback. There are no breaking changes: new settings are off until you turn them on.

Fixed

  • Commands sent by other Mods (for example a ScriptCards --@tc| call) were refused with "Only the GM can use TokenController", because Roll20 sends them from the player "API". They are now accepted, and their replies are whispered to the GM.
  • !tc set <setting> <value> changed nothing: !tc runs version 4 commands, where set edits a route, so !tc set stopMarkers dead;red answered that there was no route called "stopMarkers". !tc set now changes a setting when the first word is a setting's name and no route has that name. Likewise !tc combat on and off switch combat, instead of toggling Combat Behaviour as version 4's !tc combat does.

Added

  • Stop Markers setting: a list of status markers separated by semicolons (for example dead;red). A patrolling token that gets one leaves its route, so dead guards stop marching after a fight; Stop Marker Action chooses whether it stays where it is or goes back to where it started. Marked tokens stop following, followers of a marked leader stop too, and marked tokens cannot be started. Markers are checked on every scheduler tick, even while patrols are paused for combat, so markers added by other Mods count.
  • --ids for start, stop, reset, lock, unlock and remove: act on the tokens with the given IDs (separated by semicolons, commas or spaces) instead of the selection, so other Mods can control tokens. remove --ids takes tokens off their routes and never removes a route.
  • Walls setting and per-route walls option: patrols can wait at, or turn back from, dynamic lighting walls (Jumpgate pathv2 and Legacy path drawings on the walls layer) and closed doors and windows, instead of walking through them. Open doors and windows let tokens through, and followers wait rather than cross a wall. A route set to ignore still walks through walls, for ghosts. Wall Check chooses whether a token's centre or its whole width must stay clear, and One-Way Walls and See-Through Walls whether those kinds block.
  • Bounce areas (bounce <name> and a Bounce Area button): tokens wander inside a selected closed drawing, travelling in straight lines and bouncing off its edges, and off walls, like a ball in Pong.

5.0.0 (2026-10-30)

A full rewrite by MidNiteShadow7 of Developesque's TokenController, which was reported as not working in Jumpgate and no longer supported.

Fixed

  • One-Click installs work again. Version 4.0.1 was published without its 4.0.1/ folder, so installing it failed; the 4.0.0/ folder had also been overwritten with later code. Both folders now hold the code that was released under those numbers.
  • Changing anything on a patrolling token (a bar, a marker, its name) no longer takes it off its route.
  • Back-and-forth (non-cycling) routes walk back exactly the way they came. Version 4 skipped the last and first steps on the way back, so tokens drifted further away on every lap.
  • Out-of-bounds checks use the token's centre and the page's current size. Version 4 treated the centre as the top-left corner and remembered each page's size the first time it was used, so tokens near the right or bottom edge, or on resized pages, could only move in some directions. Steps off the page are now skipped without the token losing its place on the route.
  • The cell size comes from each page's grid (including cell sizes other than 1 and Jumpgate grid offsets) instead of one global Pixels Per Unit setting.
  • Reset on a single path's row only resets that path's tokens, and puts tokens back on the layer they started on instead of always the token layer.
  • A fixed start on another page reports the problem instead of failing silently (the API cannot move tokens between pages).
  • !tc list without arguments no longer throws an error. Path names with spaces work everywhere, including the menu buttons and drafts.
  • Paths made only of waits or stealth toggles, such as the built-in S Blinker, can be added.
  • The usage guide handout is GM-only. Version 4 created it visible to every player and rewrote it on every restart.
  • Lock no longer takes over the red status marker or teleports locked tokens every tick.
  • Combat detection no longer misses the first creature added to the turn order, and is remembered across API restarts.
  • Followers no longer stack on top of the leader when it patrols, and a token can no longer be made to follow itself or follow in a circle.
  • Chat is no longer flooded: actions get a short whispered reply instead of the whole menu, and menus are not stored in the chat archive.
  • Errors are reported to the GM with a hint, and logged to the API console without stopping the sandbox.

Added

  • Works in Jumpgate and Legacy games; the engine is detected automatically. No longer needs HTML Builder.
  • Routes can be made from drawings on the map (Jumpgate pathv2 and Legacy path: lines, polygons, freehand, rectangles and ellipses).
  • Routes can be recorded by moving a token with buttons or by dragging it, following Roll20 waypoints. On square grids recordings become editable step codes.
  • Diagonal steps (UL, UR, DL, DR), steps without a number (one cell) and counted waits (W3) in step codes.
  • Square, hex (V and H), isometric, dimetric and gridless pages, with a calibrate command for maps whose grid does not line up.
  • Movement setting: one cell per step (smooth) or a whole step at once (as version 4).
  • Each route runs at its own interval exactly; version 4 rounded route intervals to multiples of the global tick.
  • Combat Detection setting (turn tracker, GM switch or both) and Combat Behaviour setting (pause, move each turn or keep moving), with Combat On/Off buttons.
  • Lock Mode setting: Roll20's own position lock, undoing moves, or holding still; and a Lock Marker setting.
  • Follow Mode setting: single file or formation. Leaders can be chosen with the Leader button or by name, so @{target} is no longer needed. Followers move with tokens dragged by hand, patrolling tokens and tokens moved by TokenMod.
  • Dragging a patrolling token carries the patrol on from there (or stops it, if preferred).
  • Pause All and Resume.
  • Rename, show and per-route option buttons; removing a route asks first.
  • Turn Tokens supports token art facing any direction.
  • Status card showing what the Mod is doing and how it sees the current page's grid.
  • Public API for other Mods: TokenController.ObserveTokenChange, start, stop, reset and routeOf. Moves are passed to Hexploration v2 so patrols reveal hexes.
  • Help and Command Deck handouts in the Journal.
  • 24 languages.

Changed

  • The main command is !tokencontroller. !tc and !token-control still accept every version 4 command.
  • A token follows one route at a time; starting another route replaces the first.
  • Version 4 state is migrated on startup: paths, patrols, locks, followers, unfinished drafts and settings are kept.
  • The default interval for new games is 2 seconds, moving one cell per step.

Signed-off-by: Steve Roberts steve@shadowcomputers.co.uk

script.json listed 4.0.1 as the current version, but no 4.0.1 folder
was ever added, so One-Click installs of it failed. The 4.0.0 folder
had also been overwritten with later 4.x code.

Restore 4.0.0/ to the code released as 4.0.0 (e53c26b) and add 4.0.1/
with the code released as 4.0.1 (72dcd80), so every listed version
installs what it says.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Version 5 is written as ES modules and bundled with Rollup, in line
with Hexploration and the other reworked Mods. Add the build, version
bump and locale sync scripts, Prettier settings, and the npm package
that runs them. The released version folders and the generated
script.json are excluded from formatting.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
TokenController was reported as not working with Jumpgate and is no
longer supported by its author. Rewrite it as version 5:

- One !tokencontroller command, with !tc and !token-control kept so
  version 4 macros still work.
- Routes from step codes, drawings (Jumpgate pathv2 and Legacy path)
  or recorded moves, run as loop, ping-pong or once.
- Square, hex, isometric, dimetric and gridless pages, using grid
  geometry measured in a Jumpgate game and the page grid offset.
- Combat detection from the turn tracker, a manual switch or both;
  lock modes (Roll20's lock, undo moves, hold still); single-file or
  formation following.
- Help and Command Deck handouts, settings as One-Click options, and
  messages in 24 languages (English for now, others to follow).
- Version 4 games are upgraded on startup, and the v4 usage guide,
  which players could see, is removed.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Cover the pure grid, route and state modules directly, and run the
built bundle in a Roll20 sandbox stub with a controllable clock to
exercise patrols, following, locks, combat, recording, drawings and
the version 4 upgrade. Grid tests include positions Roll20 snapped
tokens to in a Jumpgate game.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Add a README for GMs, a changelog covering every release, a developer
guide, a map of where each feature lives, and an in-game test plan
for Jumpgate and Legacy games.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Build the bundle and its 5.0.0 snapshot, and update script.json with
the new version, authors, options and the full list of earlier
versions.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
When Google Translate rate-limited a request (HTTP 429) the script
neither retried nor reported it, and kept the English text, so whole
locales were silently written as English copies. Retry rate limits and
server errors as well as timeouts, report every failure, and don't
cache a failed string so the next sync tries it again.

Format the written files with the project's Prettier settings rather
than the defaults, so synced locales pass the format check.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Machine-translate every English string into the 23 supported
languages, synced one locale at a time. Strings Google left in English
or got badly wrong (button labels, grid names and a few whole sentences
in Traditional Chinese) were translated by hand.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Show the Help handout's supported languages as a table of code, name
and native name, with each language's flag as a Twemoji image. An
image is used because Roll20 on Windows shows emoji flags as pairs of
letters, as ConditionTracker found.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Add each version's release date to the changelog, taken from when it
was committed. Note that the isometric and dimetric grid positions were
also measured in a Legacy game and match Jumpgate.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Rebuild the bundle and its 5.0.0 snapshot with the translations and
the new language table.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Date version 5.0.0 in the changelog by when its bundle was built, as
shown in the script's banner and startup message.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Commands that another Mod sends with sendChat, such as a ScriptCards
--@ call, reach the Mod from the player "API". playerIsGM() is false for
that player, so every such command was refused with "Only the GM can use
TokenController" and nothing could drive TokenController automatically.

Messages from the API player are now accepted, and their replies are
whispered to the GM.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Patrols kept walking after combat even when their tokens had been
killed. The new Stop Markers setting takes a list of status markers
separated by semicolons (for example dead;red). A patrolling token that
shows one leaves its route, and Stop Marker Action says whether it stays
where it is or goes back to where it started. Marked tokens also stop
following, followers of a marked leader stop too, and marked tokens
cannot be started. The GM is told who stopped.

The API raises no change events for markers that other Mods set, so the
markers are checked on every scheduler tick, even while patrols are
paused for combat, as well as straight away when a GM changes a token's
markers. Number badges are ignored and custom markers match by name.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Other Mods cannot select tokens, so ScriptCards and similar scripts had
no way to say which tokens a command was for. start, stop, reset, lock
and unlock now take --ids followed by token IDs separated by semicolons,
commas or spaces (--ids|ID1;ID2 also works), in place of the selection.

remove --ids is accepted too, as the feedback asked for it, but it only
takes the tokens off their routes: remove on its own deletes a route, so
an ID list can never delete one by mistake. IDs that are not tokens are
reported and skipped.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Roll20 only stops people dragging tokens through walls, not tokens that
the API moves, so patrols walked straight through dynamic lighting
walls. The new Walls setting checks every move against the page's walls
(pathv2 or path drawings on the walls layer) and its closed doors and
windows: ignore walks through as before, hold waits until the way is
clear (for example until a door opens) and turn sends the patrol back
the way it came. Followers wait rather than cross a wall.

Each route has its own walls option that overrides the setting, so a
ghost can still walk through walls. Wall Check chooses whether only the
token's centre or its whole width must stay clear, and One-Way Walls
and See-Through Walls choose whether those kinds block. Walls are read
once per page and read again whenever a wall, door or window changes.

The drawing properties used to make routes are now read by one helper
shared with the walls.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The new bounce command makes a route from a selected closed drawing
(polygon, rectangle, ellipse or freehand loop). Tokens started on it
travel in straight lines and bounce off the area's edges like a ball in
Pong, turning up to 20 degrees at random at each bounce so their paths
do not repeat. On a grid they step from cell to cell along their line
of travel; on gridless pages they move a cell's width along it.

Walls and closed doors are bounced off too, unless the route or the
Walls setting ignores them. Random start puts each token in a random
cell of the area, a token outside the area cannot be started, and one
dragged out of it heads back in. A Bounce Area button is added to the
menu and the Command Deck.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
… areas

Describe the new settings, the walls route option, bounce areas and
--ids in the README, including how other Mods such as ScriptCards can
send commands. Add the walls, bounce, Stop Marker and patrol state to
the developer guide and file map, and add live checks for each to the
testing guide.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…ands

Add a paragraph to the Help handout's Commands section: other Mods such
as ScriptCards can send the commands too, naming tokens with --ids
because they cannot select them, and replies go to the GM.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Translate the Stop Marker, --ids, walls and bounce area strings with
scripts/sync-locales.mjs, and the route option list in two strings that
now include walls.

Google left eight short strings in English (Czech, German, Greek,
Hebrew and Swedish), which are filled in by hand, and a few German
wall and marker choices are reworded as it read them as commands. Zero
width spaces that Google added are removed from every locale.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Bumps the version to 5.0.1 for commands from other Mods, Stop Markers,
--ids, walls and bounce areas. Like 5.0.0, it goes into the same pull
request, so 5.0.0 joins the previous versions and its snapshot folder
is left as it was.

The rebuilt script is copied to the new 5.0.1 folder. The changelog
gains a 5.0.1 section, the testing guide, developer notes and README
API example carry the new version, and script.json lists the new
features and that the Mod reads doors and windows.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…n 5 settings

!tc runs version 4 commands, where set edits a route and combat toggles
Combat Behaviour, so !tc set stopMarkers dead;red answered that there was
no route called stopMarkers, and !tc combat off switched patrols to
moving each turn. ScriptCards users are likely to type !tc.

set now passes through when its first word is a setting's name and no
route has that name, and combat on|off passes through to switch combat.
Version 4 macros keep their meaning: a route named after a setting is
still edited, and a bare !tc combat still toggles.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…n the Help handout and README

Add both to the version 4 command tables, next to the version 4 forms
they share a name with.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
… fix

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
… sync-locales

sync-locales used to re-send every string still identical to English on
each run. Many are meant to stay English, so Hex (V) and Hex (H) turned
into hexadecimal and CRL into a certificate revocation list. It also
needed hand-editing all 23 locale files before a reworded English string
would be translated again, and sent one request every 2 seconds.

- Only strings missing from a locale are translated by default.
  --untranslated brings back the old behaviour.
- --keys a.b,c.d translates the named keys again; unknown keys are an
  error.
- --dry-run lists what would be translated, per locale and key.
- --concurrency=N translates N locales at once (default 4); 429s and
  server errors are retried with back-off.
- Placeholder-only strings are not sent, a translation whose
  placeholders did not survive keeps the English, mask tokens are
  matched in any case, and files are formatted with the Mod's Prettier
  settings so unchanged lines stay unchanged.
- The estimate before confirming counts the strings to send.

The script is now the same file in every Mod. DEVELOPERS.md lists the
options.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…locales

Machine translation took the English button label "Resume" as the noun,
so the Command Deck and the chat menu offered a CV or a summary instead
of carrying on the paused patrols: CV (French), Cv (Dutch), Currículum
(Catalan), Resumé (Czech), Περίληψη (Greek), קורות חיים (Hebrew) and
Резюме (Russian and Ukrainian). These now use the verb for carrying on,
as the other locales already did.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…ions

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…in the Journal

The Help and Command Deck handouts now use the plain TokenController icon from Roll20's file store as their journal icon (the handout avatar). The icon is set when a handout is created and added to handouts from earlier versions, so existing games get it too.

Roll20 stores the avatar as max.webp with a number, so a handout counts as having the icon when its avatar contains the image's path. Only the webp files exist (thumb.png is a 404), so the URL uses thumb.webp. A test covers new handouts and handouts made before.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The root script and the 5.0.1 snapshot are rebuilt without a version bump and remain identical.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…the handout

Roll20 always stores a handout's journal icon as the full-size file, whatever size the Mod asks for, and shows that file at its natural size at the top of an open handout. The TokenController icon was a 1024 pixel upload, so it filled the handout above the text.

The icon now points at a 100 pixel copy of the same artwork. Handouts from earlier builds are matched on the image path, so they change to the small icon the next time the Mod starts.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…icon

The built script and its 5.0.1 copy carry the new icon path. The version number is unchanged.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants