Skip to content

feat(DeathTracker): Rewritten for Jumpgate, death saves from the D&D 2024 sheet, bloodied threshold, on-death actions - #2372

Open
steverobertsuk wants to merge 17 commits into
Roll20:masterfrom
steverobertsuk:sr/deathtracker-v1
Open

steverobertsuk wants to merge 17 commits into
Roll20:masterfrom
steverobertsuk:sr/deathtracker-v1

Conversation

@steverobertsuk

Copy link
Copy Markdown
Contributor

1.0.0 (2026-11-04)

A full rewrite by MidNiteShadow7 of Robin Kuiper's DeathTracker 0.1.8, which had not changed since 2018. Version 0.1 settings are carried over and !dead still works.

Fixed

  • Clearing a token's hit point bar marked it dead (an empty bar was read as 0). Empty bars, and bars that do not hold a number, are now left alone.
  • A token with no maximum hit points got a broken tint (#NaNNaNNaN). Tint now needs a maximum, and a linked bar with no maximum reads it from the linked attribute.
  • Tokens controlled by more than one player, or by "all", were wrongly treated as NPCs or PCs, because the whole controlledby list was checked as one player.
  • Only Roll20's old built-in markers could be chosen. Any marker in the game can now be used, including custom marker sets and the D&D 2024 sheet's condition markers, found by name or tag.
  • Changing the hit point bar said the sandbox had to be restarted. It does not, and the message is gone.
  • The "half dead" marker set to none wrote a junk status_none property onto tokens.
  • At full hit points the tint was set to transparent, wiping a tint the GM (or another Mod) had set. The token's own tint now comes back.
  • Settings typed in chat were stored without checking (bar|7, true as text). Bad values are now refused with a message.
  • One Mod's failing ObserveTokenChange handler stopped DeathTracker and every later handler. Handlers are now called one at a time, and failures are logged.

Added

  • Death saves for player characters, as in HealthColors: a PC at 0 is Dying; three successes make it Stable, three failures Dead. On the D&D 2024 sheet they are read from the sheet as boxes are ticked or saves rolled; on the 2014 sheet and others, from checkbox fields set in Settings. A DeathSaves token action (!deathtracker macro) covers sheets that cannot be read. Saves are counted from the drop to 0, because sheets keep old ticks; Clear sheet boxes clears them at the drop and on healing, and on the D&D 2024 sheet shows the death save boxes when a PC drops to 0 from the token bar (the sheet only shows them by itself after its own Damage box).
  • Who is a PC: player-controlled tokens or characters, or (by default) characters whose sheet is not an NPC sheet, plus Make PC / Make NPC per character.
  • Bloodied threshold setting (50% by default, 0.1's "half dead").
  • When a token dies (each off by default): move it to the GM layer or the Map layer, and remove it from the turn order, for NPCs or for everyone. Restore puts selected tokens back, into the turn order with the initiative they had.
  • Massive damage option for PCs.
  • Announcements to the GM and the PC's players when a PC goes down, becomes stable, dies or gets back up.
  • A chat menu, a settings card with buttons for every setting, status, check, stable, clear, restore, markers and --ids.
  • DeathTracker - Help and DeathTracker - Command Deck handouts, in 24 languages, with the DeathTracker icon in the Journal (also added to handouts from earlier versions).
  • One-Click options for every setting.
  • A public API: check, getStatus, onStatusChange, isManagingDeathSaves, ownersChanged, alongside 0.1's ObserveTokenChange.
  • Commands from other Mods (player "API") are accepted.

Changed

  • The main command is !deathtracker (also !dt); !dead, !dead config key|value and !dead reset still work.
  • Settings live in state.DeathTracker; 0.1's state.DEATHTRACKER is read once and left in place.
  • The PC Unconscious marker is now the Dying marker.
  • Who handles what, shared with HealthColors 2.5 and later: Settings chooses DeathTracker, HealthColors or Off for death saves (with the dying, stable and dead markers), health colours and hurt/heal effects (deathSavesBy, coloursBy, effectsBy). The choice is stored once (state.ModOwners), HealthColors' !aura menu shows and changes the same values, and a change in either Mod refreshes both. At first DeathTracker handles death saves and HealthColors the colours and effects; without HealthColors, DeathTracker handles all three.

DeathTracker 1.0 is built from ES modules in src/ into the single
DeathTracker.js the One-Click library serves, as the other rewritten
Mods are. The build writes the root script and its version snapshot
together, so the two cannot drift apart, and sync-locales is the shared
copy used by every Mod in this repository.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Version 0.1.8 had not changed since 2018. It read an empty hit point
bar as 0 and marked the token dead, divided by a blank maximum and
tinted tokens #NaNNaNNaN, ran playerIsGM on the whole controlledby list
so shared or "all" tokens were judged wrongly, only knew Roll20's old
built-in markers, wiped any tint the GM had set, stored settings typed
in chat without checking them, said a sandbox restart was needed when
the bar changed, and let one failing observer stop it.

Version 1.0 judges each token from the chosen bar as Healthy,
Bloodied (a setting, 50% by default), Dying, Stable or Dead, and only
removes markers it added itself. Player characters at 0 make death
saves: on the D&D 2024 sheet they are read from its "store" attribute,
which fires change:attribute on every tick or roll; other sheets use
checkbox fields, and a token-action macro covers sheets that cannot be
read. The 2024 sheet keeps old ticks after healing and only shows its
death save boxes after its own Damage box, so DeathTracker counts saves
from the drop to 0 and, unless told not to, clears the boxes and shows
them when a PC drops to 0 from the token bar.

A character is a PC when a player controls it or its sheet is not an
NPC sheet, and the GM can decide per character. The dead can be moved
to the GM or Map layer and out of the turn order, and Restore puts them
back with their initiative. Massive damage, announcements to the GM and
the PC's players, tint and hurt/heal effects (off when HealthColors is
installed), any marker in the game by name, a chat menu and settings
card, Help and Command Deck handouts and One-Click options for every
setting are included.

Settings are carried over from 0.1's state, `!dead` and `!dead config`
still work, and DeathTracker.ObserveTokenChange keeps working for
CombatMaster, LazyExperience and StatusInfo, alongside a new API
(check, getStatus, onStatusChange, isManagingDeathSaves).

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The stub stands in for the Roll20 sandbox as Jumpgate was seen to
behave in the test game, including the 2024 sheet's store attribute.
The suite covers every 0.1.8 defect, the status rules, death saves on
the 2024 and 2014 sheets (counting from the drop, clearing and showing
the boxes, a store with no death saves yet, the poll), PC detection,
markers, on-death actions and restore, massive damage, migration from
0.1.8, commands, One-Click options, observers and TokenMod.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Google's translate endpoint refused every request (HTTP 429), so the
menus, messages and handouts were translated by Claude instead.
check-locale.mjs confirms each file has the same keys, array lengths,
placeholders and command words as en-US, and no characters that would
break a Roll20 query. Official D&D terms were used where the translator
knew them; Bloodied, massive damage and some Roll20 interface words
were not checked against published books or Roll20's own translations.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The README covers the statuses, death saves on each sheet, who counts
as a PC, what happens when a token dies, every command and setting,
working with HealthColors and other Mods, and upgrading from 0.1. The
changelog lists the 0.1.8 defects fixed and Robin Kuiper's earlier
releases. DEVELOPERS, MOD_FILE_MAP and TESTING describe the modules,
state, the Jumpgate and 2024-sheet behaviour the code relies on, and
the live results from Mod Test Lab - DeathTracker.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Builds DeathTracker.js and its 1.0.0/ snapshot from src/, with all 24
languages.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
A PC whose tokens sit on more than one loaded page (for example the
battle map and the players' ribbon page) had every announcement - down
and dying, stable, died, back on their feet - sent once for each token,
because each linked token is judged on its own when the sheet changes.

Announcements are now keyed by the character the token represents, and
the same news for the same character within five seconds is skipped.
A test covers a PC with tokens on two pages.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
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>
DeathTracker and HealthColors 2.5 can both track death saves with the
dying, stable and dead markers, colour tokens by health and play hurt
and heal effects. Before, a new install simply turned DeathTracker's
tint and effects off when HealthColors was present, and HealthColors
stood aside on death saves, with no single place to choose.

Settings gains a "Who handles what" section (deathSavesBy, coloursBy,
effectsBy): DeathTracker, HealthColors or off for each. The choice is
kept once in state.ModOwners, which HealthColors reads and writes too,
so either Mod's menu changes it for both; a change refreshes
DeathTracker's tokens and asks HealthColors to refresh its own, and the
public API gains ownersChanged for the other direction. With
HealthColors installed DeathTracker starts with death saves and
HealthColors with colours and effects; alone, DeathTracker does all
three. The fresh-install tint and effects switch-off is gone.

When DeathTracker does not handle death saves it adds no dying, stable
or dead marker, reads no sheets and announces nothing, but still knows
each token's status for its menu, the bloodied marker and the on-death
actions. isManagingDeathSaves now also needs DeathTracker to be chosen.
The warning about both Mods tracking death saves is kept for
HealthColors before 2.5, which does not share the choice. Tests cover
the starting choice, changing it, refusing bad values and leaving death
saves to HealthColors.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The new section, settings, handout rows and API row, and the changed
HealthColors message and handout points, translated by Claude with each
file's existing terms. check-locale passes for every language.

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The README gains a Who Handles What section and the three settings, and
says how HealthColors 2.5 and older versions work alongside it. The
changelog, developer notes, file map and Mod Library description follow.
TESTING.md adds the checks and the live results from 9 November with
HealthColors 2.5.0 switched on in the test game. Prettier re-wrapped two
existing tables.

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

The Help and Command Deck handouts now use the plain DeathTracker 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 changelog and developer notes now say the handouts carry the DeathTracker icon.

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

Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
… 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 DeathTracker 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 1.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