[Script, Update] Aura/Tint HealthColors API

The Aura/Tint HealthColors API version 2 has been updated and is available in the OneClick Installer. [2.2.0] – 2026-06-29 ·   Milestone Added Death Save Integration   (Optional) — an off-by-default feature that distinguishes   dying   (configurable marker, default   skull ),   stable   (green marker, 3 successes), and   dead   (Red X, 3 failures) for player characters at 0 HP. NPCs are unaffected and keep the standard dead Red X. Automatic death-save tracking for supported sheets, so a checked or updated death-save value updates the token marker without any macro or manual refresh. Death Save Integration now appears in both the interactive   !aura   GM menu and the read-only   !aura settings   snapshot, with   !aura deathsaves   commands for enabling, watching, and configuring markers. Marker validation now warns the GM when the configured dying or stable marker tag does not exist in the current campaign. Fixed Upgrading from the interim PC dying marker build now preserves existing dying-marker settings.

The Aura/Tint HealthColors API version 2 has been updated and is available in the OneClick Installer. [2.2.1] – 2026-07-03 Added Added   !aura deathsaves sync   to force an immediate death-save marker reconciliation for selected PCs after imports, sheet changes, or missed updates. Added a one-time GM warning when a watched PC's death saves are not stored as legacy attributes. This calls out the Experimental (Jumpgate) sandbox requirement for live Beacon/D&D 2024 death-save reads and explains the failure mode on the Default sandbox. Expanded   !aura deathsaves debug   so it now reports resolved watched-field values, sheet-item API availability, the selected character's legacy-attribute count, how many watched fields are stored as legacy attributes, and a Beacon/sandbox compatibility warning when none are. Documented the Experimental (Jumpgate) sandbox requirement for Beacon/D&D 2024 death-save syncing in the README, including the known silently-reverting Roll20 dropdown issue. Changed Refined the Death Save Integration introduced in 2.2.0 so watch, sync, and debug flows now use alias-aware field resolution ( succ / success ,   fail / failure ) before evaluating marker state, improving compatibility across sheet variants without changing the GM-facing configuration model. Added a lightweight 3-second polling pass for downed PCs so death-save markers stay current even on sheets that do not emit usable legacy   change:attribute   events. Updated the fallback resolver to prefer Jumpgate   getSheetItem   reads for non-legacy death-save fields, while retaining the chat-parser probe only as a legacy-sandbox fallback. Fixed Fixed D&D 2024 / Beacon death-save syncing when equivalent sheet field names differ from the configured defaults by resolving configured watches through alias-aware lookups and probing only the still-unresolved aliases. Fixed repeated Roll20 parser errors from fallback death-save probes by removing character-id references ( @{<id>|attr} ) and using safe character-name probes instead. Fixed repeated startup and sync errors caused by asking Roll20 for death-save field names the current game sheet does not define. The resolver now keeps a persisted game-wide field-name status cache ( state.HealthColors.dsFieldStatus ) so proven-good names are reused, rejected names are not retried, and the cache is cleared automatically when the GM reconfigures death-save fields or manually resyncs after a sheet change.

The Aura/Tint HealthColors API version 2 has been updated and is available in the OneClick Installer. [2.3.0] – 2026-10-06 Added Selectable heal/hurt effects   —   !aura heal <effect>   and   !aura hurt <effect>   now accept a Roll20 built-in effect name (e.g.   glow-holy ,   explode-blood ,   splatter-blood ) or a custom FX name/id from the campaign's Effects menu, as well as the existing 6-digit hex colour.   !aura heal default   /   !aura hurt default   restore the shipped colours. ( #5 ) Added   !aura listfx   (and a   List FX   button in the GM menu) that lists the campaign's custom FX with their ids and one-click   Heal   /   Hurt   set buttons, plus a reference of the built-in   <type>-<colour>   effect names — restoring the   LISTFX   helper from the 1.7.1 forum build. Added a per-character   USEHEAL   attribute mirroring   USEBLOOD :   DEFAULT   (use the global setting),   OFF / NO   (no heal FX for that character), a hex colour, or a comma-separated list of built-in and/or custom effect names. The GM menu and   !aura settings   snapshot now show the chosen heal/hurt effect (colour swatch for hex values, the effect name otherwise). One-Click install options   — every setting (bar, aura/tint, palette, thresholds, PC/NPC toggles, nameplates, aura display values, FX, death sound, Death Save Integration) can now be set from the Roll20 One-Click install dialog via   useroptions . Options are applied on first install and whenever the dialog is saved again (tracked in   state.HealthColors.globalconfigCache.lastsaved ), so in-game   !aura   changes are not overwritten on every restart.   !aura reset   /   !aura reset-all   return to the One-Click values. script.json   now declares the objects and properties the script reads and writes at property level ( graphic.* ,   character.* ,   attribute.* ,   custfx.* ,   jukeboxtrack.* ,   Campaign.token_markers ). Changed USEBLOOD   now accepts Roll20 built-in effect names alongside custom FX names and hex colours.   OFF / NO   keep their long-standing meaning of disabling all HealthColors FX for that character and are now matched case-insensitively. Unknown effect names given to   !aura heal   /   !aura hurt   are rejected with a GM warning instead of being silently ignored, and the previous setting is kept. A configured custom FX that no longer exists (global setting or character attribute) now whispers the GM once per setting change rather than on every HP change; the API log still records every fallback. The warning names the setting or attribute to fix. Built-in effects are spawned by name with Roll20's own renderer, so they play at Roll20's fixed size and are not scaled by token size or damage amount. Custom FX and colour bursts keep the existing scaling. Updated the Death Save Integration sandbox guidance for Roll20's September 2026 rename: "Experimental" is now   Mod Script Sandbox v1.5   and "Default" is   v1.0 . The script now reads the running version from   Campaign().sandboxVersion , logs it at startup, reports it in   !aura deathsaves debug , and only shows the Beacon sheet note in the GM menu and the one-time GM whisper when the game is on v1.0 (or the version cannot be determined). Fixed Fixed newly placed tokens staying uncoloured until a setting was toggled (reported on the Roll20 forum with the 5e Shaped sheet, where HP max is calculated by the sheet after the token exists). A token change that only altered the health bar's max, its attribute link, or the token's character was treated as "nothing relevant changed" and skipped, and the   change:attribute   listener ignored changes to an attribute's max. Both paths now re-evaluate the token (silently, with no FX) so the aura or tint appears as soon as the bar becomes usable.

We submitted this update, and it should be in the OneClick installer soon. You can download the most recent update directly from GitHub: <a href="https://github.com/steverobertsuk/roll20-api-scripts/releases/download/HealthColors-v2.4.0/HealthColors_v2.4.0.zip" rel="nofollow">https://github.com/steverobertsuk/roll20-api-scripts/releases/download/HealthColors-v2.4.0/HealthColors_v2.4.0.zip</a> [2.4.0] – 2026-10-25 Added All six Roll20 aura shapes — Roll20's September 2026 update added Hex, Circle Border, Square Border and Hex Border auras alongside Circle and Square. !aura a1shape (and the GM menu prompt) now offers all six, plus three HealthColors choices: Auto (Hex on hex-grid pages once the radius is at least one grid cell, Circle otherwise — Roll20 draws hex auras in whole cells, so a smaller radius would be invisible), Auto Border (the outline versions) and Keep (never change a token's shape). Two-word shapes can be typed with or without the space or with - / _ ( Circle Border , circleborder , circle-border ). !aura opacity &lt;1-100&gt; (menu: Aura 1 Opacity % ) makes the Aura 1 health ring see-through by adding an alpha channel to its colour (e.g. #ffff0080 at 50 %). Default 100 keeps the existing solid ring. !aura lock (menu: Lock Aura 1 (players) , default on) turns off the token's players can edit Aura 1 option while HealthColors manages the ring, so controlling players can't change it by accident. The health bar can now be bar 4 ( !aura bar 4 , One-Click auraBar = bar4 ) for games that set Maximum Token Bubbles/Bars to 4. One-Click options auraOpacity and auraLockPlayers ; Aura1Shape and Aura2Shape list the new shapes. Redesigned GM menu ( !aura ): an action bar with Update Selected ( !aura update ), Refresh All and Post Settings ; settings grouped into titled sections (General, Tracking &amp; markers, Nameplates as a GM/Players × PCs/NPCs grid, Aura 1 ring, Effects &amp; sound, Death Save Integration, Reference values); aligned label/control rows; dark text on a light background instead of white-on-gradient; colour swatches on colour settings; long death-save field lists summarised ("3 fields") with the full list as a tooltip; and a footer with Open Help / Rebuild Help. The !aura settings snapshot is built from the same code, so it always matches the menu. Help handout — a GM-only HealthColors — Help &amp; Reference handout is created in the Journal. It has a command list (from the same list the script uses), aura shapes &amp; appearance, colour palettes with swatches, an attribute reference ( USECOLOR / USEBLOOD / USEHEAL ), optional integrations (Death Save Integration, TokenMod, attribute scripts, One-Click options, the script API), tips &amp; troubleshooting and a Current settings table. It is rebuilt each time the script loads and after every setting change. !aura handout rebuilds it on demand, and a new Help row in the GM menu has Open Handout and Rebuild buttons. Its colours read in both Roll20 light and dark mode. Changed The Aura 1 shape setting is now applied to tokens. Before 2.4.0 it was only shown in the menu. In aura mode HealthColors now writes the token's aura1_options (Roll20 keeps aura1_square in sync). New installs default to Auto . Upgrade migration: an existing game whose Aura 1 Shape is still the old default Circle is switched to Keep on first load, so upgrading never reshapes auras set by hand. Any other stored shape was a deliberate choice and is now applied. Switching to tint mode releases Aura 1: the ring is cleared, its shape returns to Roll20's default Circle (unless Shape is Keep ) and players can edit it again. Changing the Aura 1 radius, shape, opacity or player lock now refreshes every token straight away instead of waiting for the next HP change. Aura 1 Color and the Aura 2 Radius/Shape/Color rows are now labelled Reference values (not applied to tokens) in the menu, settings snapshot, README and One-Click descriptions. Aura 2 Shape accepts any of the six Roll20 shapes. README: new Help Handout , Attribute Reference (now including USECOLOR ) and Optional Integrations sections (Death Save Integration moved under it, plus TokenMod, attribute scripts, One-Click and the script API); the palette list is now a table with hex values, and Tips &amp; Troubleshooting covers the 2.4.0 changes. Aura radii are labelled in page units rather than feet, since Roll20 measures auras in the page's own units. script.json declares the extra properties now used: graphic.aura1_options , graphic.aura1_square , graphic.playersedit_aura1 , graphic.bar4_* and page.grid_type . Fixed Restored the SmartAoE integration that was dropped in the v2.0.0 rewrite. HealthColors 1.7.1 registered with SmartAoE.ObserveTokenChange ; v2 only kept TokenMod's hook, so area damage or healing applied by SmartAoE (which Roll20 does not report as a token change) left health colours and dead markers stale. HealthColors now hooks into SmartAoE when it is installed, logs which scripts it observes at startup, and the help handout shows whether TokenMod and SmartAoE are detected. SmartAoE's 0 HP marker takes precedence (including --instant AoEs, via SmartAoE 1.0.0's ZeroHPMarkers() ; found in live testing that instant AoEs are deleted before their damage lands): when a token at 0 HP carries the zeroHPmarker of a SmartAoE AoE, HealthColors adds no dead marker (the death sound still plays) and, with Death Save Integration, no dying marker; stable/dead death-save results still show. HealthColors never removes SmartAoE's marker. The rule is off when SmartAoE isn't installed. !aura update with nothing selected (or with a drawing selected) no longer throws an error; it whispers a reminder to select a token, and lists the tokens it updated. Fixed TokenMod changes being processed twice (double FX) after !aura reset : the observer was registered again each time the install check ran. Observers are now registered once per sandbox start. Fixed the health aura or tint being lost after the token settings dialog is saved. Saving the dialog can overwrite an aura HealthColors applied while it was open; because HP, size and bar linkage hadn't changed, the token was skipped. Changes to the Aura 1 radius, colour, shape ( aura1_options / aura1_square ) and visibility, or the tint, now make HealthColors re-apply its colour.