Skip to content

feat(PageFX): Rewrite for Jumpgate - #2370

Open
steverobertsuk wants to merge 10 commits into
Roll20:masterfrom
steverobertsuk:sr/pagefx-v2
Open

steverobertsuk wants to merge 10 commits into
Roll20:masterfrom
steverobertsuk:sr/pagefx-v2

Conversation

@steverobertsuk

Copy link
Copy Markdown
Contributor

2.0.0 (2026-11-07)

A full rewrite by MidNiteShadow7 of Ada Lindberg's PageFX 1.3, which had not changed since 2017. Version 1 tokens keep working, and !pageFX on and !pageFX off still work.

Fixed

  • Effects only ran on the page with the player ribbon. Players moved to their own page (split party) saw nothing, because effects were spawned without a page and only ribbon-page tokens were started. Effects now run on every page with players on it, each drawn on its own page.
  • The area and page edges were worked out from the ribbon page, not the effect's own page.
  • Aura radii assumed 70 px cells (radius × 70 / scale), so areas were wrong on pages with a different snapping increment.
  • A NullFX area grew or shrank with the size of the PageFX token being checked, not its own.
  • Saved custom FX were spawned twice each time.
  • A random direction never worked for saved beam-like custom FX.
  • Bar values were used as text in the interval maths.
  • Moving or selecting a PageFX token restarted its timer.
  • Effects did not start when the sandbox started, only when the ribbon next moved.
  • A debug message was logged on every beam spawn.
  • Errors, such as a saved FX that could not be found, only reached the API console; the GM is now told.
  • Effects had no limit, which made games lag with fast effects. Each page now gets at most 30 spawns a second (a setting).

Added

  • Chat menus: a main menu of the effects on your page, a card per effect with buttons for every setting, a presets card, settings and status.
  • Effects made from any token: create, preset, fx, interval, direction, area, name, delete, and no-effect areas with null create.
  • Layers: one effect can spawn several things, each with its own timing.
  • Built-in FX in any type and colour, saved custom FX, and custom FX definitions pasted as JSON. Missing values in a definition are filled in, and PageFX saves its definitions as its own custom FX so Jumpgate draws them in colour.
  • Per-effect on/off, pause and intensity, plus pause all, resume all and global intensity.
  • 23 presets in four packs: weather, fire and heat, water, and magic. Other Mods can add more.
  • Triggers: start, stop, switch, fire or burst an effect each round or on a round, on a token's turn, or when a token enters or leaves an area, for player tokens, any token or named tokens, once or every time.
  • GM Page Preview setting: also run effects on the page a GM is looking at.
  • PageFX - Help and PageFX - Command Deck handouts, in 24 languages, and a Language option on the Mod's settings page.
  • Commands from other Mods are accepted, and a public API: start, stop, pause, resume, setIntensity, fire, create, remove, getEffect, listEffects, isRunning, registerPreset, listPresets and checkToken, alongside version 1's functions.
  • status, rescan (take over copied tokens and forget deleted ones) and journal rebuild.

Changed

  • The main command is !pagefx (!page-fx too). !pageFX on and !pageFX off now resume and pause every effect.
  • Settings live in state.PageFX, keyed by the effect token's ID. Version 1 tokens are taken over on the first start; their GM Notes, bars and interdiction marker drive them until they are changed from chat.
  • Random points are spread evenly over the area, where version 1 bunched them towards the middle.

PageFX becomes a multi-file project built into one Mod script, as the
other house Mods are. Rollup bundles src/ into PageFX.js and a
<version>/PageFX.js snapshot, the build and bump scripts manage the
version in package.json and script.json, and sync-locales keeps the
translations in step with en-US. Prettier and git attributes match the
other Mods.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Version 1.3 only ran effects on the page with the player ribbon, and
spawned them without a page, so players moved to their own page by a
split party saw nothing. Version 2 runs effects on every page with
players on it, each drawn on its own page, and looks every few seconds
for splits and turn order changes made by other Mods, which raise no
events.

Effects are now kept in state, keyed by the token that marks them, and
set from chat menus: a main menu, a card per effect with buttons and
prompts, layers, intensity, on/off and pause, and no-effect areas.
There are 23 presets in four packs, and triggers that start, stop or
fire an effect each round, on a token's turn, or when a token enters or
leaves an area.

Jumpgate draws inline FX definitions in white, so PageFX saves its own
definitions as custom FX and spawns them by ID, filling in every value
a definition leaves out. Legacy draws nothing for a negative particle
angle, so presets use 270 for up and other negative angles are made
positive.

It also fixes version 1's aura maths on pages whose cell is not 70 px,
NullFX areas sized by the wrong token, saved FX spawned twice, a random
direction that never worked for saved FX, a timer restart on every
token change, and the missing start after a sandbox restart. Each page
is capped at 30 spawns a second.

Version 1 tokens named PageFX and NullFX are taken over and keep their
GM Notes, bars and interdiction marker, and !pageFX on and off still
work. Help and Command Deck handouts are written in the GM's language.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
115 tests run the built bundle against a stubbed Roll20 API that
behaves as Jumpgate was seen to behave. They cover each version 1
defect that was fixed, the split party, areas on snap-1, snap-2 and hex
pages, the spawn cap, taking over version 1 tokens, every command and
menu, presets and their shared custom FX, round, turn, enter and leave
triggers, the public API and the handouts.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The README follows the in-game Help handout: effects, which pages run,
the presets, triggers, no-effect areas, commands, settings, the API
for other Mods, upgrading from version 1 and troubleshooting. The
changelog lists the version 1 defects fixed and Ada Lindberg's four
releases. DEVELOPERS, MOD_FILE_MAP and TESTING describe the modules,
state, custom FX handling, the Jumpgate and Legacy behaviour the code
relies on, and the live results, including the version 1 upgrade and
Legacy checks.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Google's translate endpoint refused or garbled the requests, so the
locales were written by Claude and checked for matching keys,
placeholders and untranslated command words. Command words and preset
IDs stay in English; preset names are translated. Afrikaans, the
Finnish word for "spawn", the Traditional Chinese terms and the Korean
particles would benefit from a native speaker's review.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Builds PageFX.js and its 2.0.0 snapshot, which are byte-identical.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The Help and Command Deck handouts now use the plain PageFX 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 2.0.0 snapshot are rebuilt without a version bump and remain identical.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
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 PageFX 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>
The built script and its 2.0.0 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