Skip to content

feat(InspirationTracker): Rewrite for Beacon sheets and additional tracking - #2379

Open
steverobertsuk wants to merge 28 commits into
Roll20:masterfrom
steverobertsuk:sr/inspirationtracker-v1
Open

steverobertsuk wants to merge 28 commits into
Roll20:masterfrom
steverobertsuk:sr/inspirationtracker-v1

Conversation

@steverobertsuk

@steverobertsuk steverobertsuk commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

1.0.0 (2026-11-19)

A rewrite by MidNiteShadow7 of Robin Kuiper's InspirationTracker, which was reported as not working with the D&D 2024 sheet.

Fixed

  • Inspiration on the D&D Fifth Edition (5E & 5.5E, 2024) sheet is now read and written. 0.1.4 looked for an inspiration attribute with findObjs, which cannot see Beacon sheets, so every toggle answered "Could not find attribute named: inspiration", markers added by hand never reached the sheet, and ticking the box on the sheet never showed the marker. The 2024 sheet is now read and written with getSheetItem and setSheetItem, and changes on the sheet are noticed through its store attribute.
  • A 2014 OGL character whose Inspiration box had never been ticked has no inspiration attribute yet; giving it inspiration now creates the attribute instead of failing.
  • Tokens on every page get the marker and the special effect, and the effect plays on the page the token is on.
  • The marker list was fixed in the code; it now comes from the game's own token marker sets.

Added

  • Player spending: players spend inspiration for characters they control with a Spend button or the Inspiration token action (!inspiration macro). The GM is told who spent it, with an Undo button. Clearing the box on a sheet or taking the marker off a token counts as a spend too.
  • Heroic Inspiration wording: characters on the 2024 rules say Heroic Inspiration, those on the 2014 rules say Inspiration, following each D&D 2024 sheet's rules setting. The Wording setting can force either.
  • Passing it on (2024 rules): a character who would gain Heroic Inspiration while having it can give it to a party member who does not have it.
  • Party overview (!inspiration party) with Give, Remove and Spend buttons, and party add / party remove to change who is in it. Players can be allowed to see it.
  • Points pools: set Tracking to Points pool to track inspiration as points that build up and are spent a few at a time, with give, remove and spend <points>, and Boost (boost <bonus>) to spend points for a bonus to a roll at the pool's cost per +1. The points are kept in the sheet's resource box that has the pool's name, or in a plain attribute, so pools work on any sheet; the Party card says which for each character. The GM can rename the default pool and add more (!inspiration pools), for hero points, luck and the like, used with --pool <name>.
  • Custom token markers: any marker from the game's marker sets, stored by tag, or None for no marker on tokens. The sheet's inspiration box and each points pool have a marker of their own; a pool starts with none.
  • give, remove, toggle, spend, undo, sync, status, set, reset, help and journal rebuild commands, and --ids to act on tokens or characters by ID.
  • Settings for who sees announcements, player spending, the player overview and passing on.
  • Help and Command Deck handouts, and menus, messages and handouts in 24 languages.
  • Chat cards laid out like the handouts: section headings, settings grouped by subject, buttons in even columns, and a block for each character with its buttons underneath.
  • Commands from other Mods, and an API: InspirationTracker.give, spend, remove, isInspired, points, givePoints, spendPoints and ObserveTokenChange.

Changed

  • The command is always !inspiration. A command name chosen in 0.1.x keeps working alongside it.
  • Settings live in state.InspirationTracker. The marker, special effect and effect type are copied from 0.1.x, whose state is left in place.

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

Version 1.0.0 is built from src/ like the other rewritten Mods, so this
brings in the same build setup: Rollup bundles src/ into
InspirationTracker.js and a matching <version>/ snapshot folder,
bump-version keeps package.json and script.json in step, and
sync-locales is the shared translation script, identical to the copy in
every other Mod.

Robin Kuiper's 0.1.2 and 0.1.4 folders are listed in .prettierignore so
they are never reformatted.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
0.1.4 read and wrote inspiration only as an `inspiration` attribute
found with findObjs. The D&D 2024 sheet is a Beacon sheet, whose values
are not attribute objects, so on that sheet every toggle answered
"Could not find attribute named: inspiration", markers added by hand
never reached the sheet, and ticking the box on the sheet never showed
the marker. The 2014 OGL sheet was fine.

Inspiration on the 2024 sheet is now read and written with
getSheetItem and setSheetItem. Changes made on the sheet arrive as a
change to its `store` attribute, but the "previous" value Roll20 passes
already holds the new value, so the Mod keeps the last value it saw for
each character and compares with that. Its own writes record the new
value first, so they are not announced twice. These were checked live
in Jumpgate.

New in 1.0.0:

- Players spend inspiration for characters they control, with a Spend
  button on the announcement or an Inspiration token action
  (!inspiration macro). The GM is told who spent it, with an Undo
  button. Clearing the box on a sheet or taking the marker off a token
  counts as a spend too.
- Characters on the 2024 rules say Heroic Inspiration and those on the
  2014 rules say Inspiration, following each 2024 sheet's own rules
  setting; the Wording setting can force either.
- Under the 2024 rules, a character who would gain Heroic Inspiration
  while having it can give it to a party member who lacks it.
- A party overview with Give, Remove and Spend buttons, party add and
  remove, and an option for players to see it.
- Any marker from the game's marker sets, custom ones included, stored
  by tag. The 2024 sheet's own condition markers are left out.
- give, remove, toggle, spend, undo, sync, status, set, reset, help
  and journal rebuild, --ids for other Mods, and an API
  (InspirationTracker.give, spend, remove, isInspired and
  ObserveTokenChange).
- GM-only Help and Command Deck handouts.

A 2014 character whose box was never ticked has no attribute yet, so
giving it inspiration now creates the attribute instead of failing.
Markers and effects reach tokens on every page, and the effect plays on
the token's own page.

0.1.x settings carry over: the marker, the effect and its type, and a
command name the GM chose, which keeps working alongside !inspiration.
The old state is left in place so a downgrade still works. Text is in
English only for now; the other 23 languages fall back to it.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Menus, messages and both handouts are now in every language the
Language setting offers. Google Translate refused every request from
sync-locales for hours (HTTP 429), so the strings were translated by
Claude instead. Each locale has the same keys, array lengths and
{placeholders} as en-US.

Command words, setting names, "GM" (or the usual local term, such as
MJ or Mestre), "Mod" and the sheet product names stay as they are. The
token action keeps its fixed name, Inspiration. Heroic Inspiration uses
the official D&D term where one is known (Inspiration héroïque,
Heldenhafte Inspiration, Ispirazione eroica, Inspiración heroica,
Inspiração Heroica). Czech, Finnish, Greek, Hungarian, Polish and
Ukrainian put {term} after a colon so names and terms need no case
endings. None of the translations have been proofread by a native
speaker.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The stub loads the built bundle in a vm context and fakes the parts of
the API the Mod uses, including getSheetItem and setSheetItem. A 2024
character keeps its values in a `store` attribute, and setSheetItem
raises change:attribute with a "previous" value that already holds the
new one, as Roll20 does.

The 35 tests cover both sheets (and a 2024 sheet set to 2014 rules),
giving, removing, toggling and spending, undo, a double-clicked Spend,
passing on under the 2024 rules, changes made on the sheet or a token
marker, the party overview for the GM and for players, permissions,
custom markers, settings, the 0.1.x upgrade, One-Click useroptions, the
player macro, the API, and every locale's keys, placeholders and
handouts.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The README replaces Robin Kuiper's contact list and 0.1.4 notes with
installation, the two sheets, player spending, passing on, the party,
markers, every command and setting, the API for other Mods and what an
upgrade from 0.1.x keeps. Robin is credited as the original author.

CHANGELOG records the 2024 sheet fix and the new features, with the
0.1.2 and 0.1.4 entries kept. DEVELOPERS explains how each sheet stores
inspiration (including the 2024 sheet's change events), the state, the
build and translations. MOD_FILE_MAP points to each part of the code,
and TESTING has the release checklist and names the Playwright spec.

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

The Help and Command Deck handouts now use the plain InspirationTracker 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 unknown marker hint now reads "one of your marker sets" with the right preposition (ממערכות), and the 2024 rules label names the characters (דמויות לפי כללי 2024) instead of a verb phrase with no subject.

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

The root script and the 1.0.0 snapshot are rebuilt without a version bump, as 1.0.0 is not released yet, and remain identical.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…ls 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 InspirationTracker 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>
…al icon

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

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

Some tables award inspiration as points that build up and are spent a few
at a time to raise a roll, and other games have hero points, luck and the
like. The Mod only knew the D&D sheets' inspiration box, which a character
has or does not have.

A Tracking setting now chooses between that box and a points pool. With a
pool, give, remove and spend take a number of points, and boost spends
points for a bonus to a roll at the pool's cost for each +1. A spend the
pool cannot cover is refused, and the GM gets the same Undo whisper.

The points are kept in the sheet's resource box that carries the pool's
name, such as an Other Resource box on the 2014 sheet, or in a plain
attribute when the sheet has no such box. The D&D 2024 sheet keeps its
resources inside its store, which a Mod cannot change safely, so its
characters always use the attribute.

There is one default pool. The GM can rename it and add more, each with
its own cost, maximum and marker, used with --pool.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The new pool menus, messages, help and handout section are translated
into the other 23 languages by Claude, keeping each locale's existing
terms. They are machine translations and have not been proofread.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The stub gains a 2014 resource box and a way to edit an attribute as a
person would, so the pool tests can check the box, the attribute
fallback, boost costs, limits, markers, extra pools and the API.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The README, changelog, testing guide and One-Click description now
explain pools, where their points are kept and the new commands, and no
longer describe the Mod as for D&D only.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The bundle and the 1.0.0 snapshot are rebuilt from the new source. The
version stays 1.0.0, as it has not been released.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The 2014 sheet keeps the value of a resource box as text ("52"), but the
Mod wrote a number into it. The sheet still displayed the value, yet the
stored data no longer matched what the sheet itself writes. This was found
while testing a points pool against a real D&D 5E (Classic) sheet.

Points are now written as text when they go into one of the sheet's own
boxes. The plain attribute used as the fallback still holds a number. The
pool tests start from a text value, as the sheet has it, and the developer
notes record the behaviour.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The bundle and the 1.0.0 snapshot are rebuilt so they carry the fix that
writes points to sheet resource boxes as text.

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

A points pool keeps its points in a sheet's resource box or in a plain
attribute, and nothing in chat said which. On the D&D 2024 sheet the
attribute is not shown anywhere, so a user had no way to find the number.
The Party card and a player's own card now say, under each name, the sheet
box or the attribute that holds the points, with a note that an attribute
is not shown on the character sheet.

The chat cards were also cramped: buttons wrapped wherever their labels
ended and a character's name, value and buttons shared one line. The cards
now use the section headings of the handouts, group the settings under the
Help handout's headings, set buttons in even columns and give each
character a block with its buttons underneath.

The Help handout text gains the kept-in sentence and a Bardic Inspiration
recipe: a pool with a maximum of 1 and its own marker.

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

The three card strings that say where points are kept, the Help handout
sentence about them and the Bardic Inspiration recipe are added to the 23
other languages, so the locale files stay in step with en-US. The
translations were written by Claude and have not been proofread.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
One test checks that the Party card names the sheet box for a 2014
character and the attribute for a 2024 one, and that a player's card leaves
the attribute note out when nothing of theirs is in an attribute. Another
follows the Bardic Inspiration recipe from the README, so the steps it
gives are known to work.

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

The README says where the cards show each character's points and gains a
Bardic Inspiration recipe, with what the Mod does not do for it. The
changelog, the hand tests and the developer notes follow the new card
layout.

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

The bundle and the 1.0.0 snapshot are rebuilt so they carry the kept-in
line, the handout-style cards and the Bardic Inspiration recipe.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
A points pool left its marker on a token for as long as the character had
any points, which for a pool is nearly always, and there was no way to turn
the marker off. The tracked pool also borrowed the Marker setting, so the
sheet's inspiration box and the pool could not be set apart.

The Marker setting now belongs to the sheet's inspiration box and can be
None. Every pool, the default one included, has a Marker of its own on the
Pools card, and starts with None, so a pool marks no tokens until the GM
chooses a marker for it. Two pools cannot share a marker, and switching
Tracking takes the old tracker's marker off before the new one goes on.
With no marker, a marker changed by hand means nothing to the Mod.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The Marker description, the pool marker hint and the Help handout's marker
paragraph are brought into line with en-US in the 23 other languages, and
the sentence saying a pool's marker always shows is dropped, as a pool now
starts with none. The translations were written by Claude and have not been
proofread.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The tests check that Marker set to None takes the marker off and puts none
on while inspiration still works, that a pool starts clear and shows a
marker once it is given one, that the Marker setting leaves a pool's marker
alone, and that two pools cannot share one. The pool tests that rely on a
marker now choose it first.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The README, changelog, hand tests and developer notes say that the Marker
setting is for the sheet's inspiration box, that each pool has its own
marker and starts with none, and how to choose None for either.

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

The bundle and the 1.0.0 snapshot are rebuilt so they carry the None marker
choice and the pools' own markers.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The changelog still carried 2026-11-04, the day the rewrite began. Version 1.0.0 is released on 2026-11-19, so the entry now says so.

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant