Repository navigation
feat(HealthColors): Enhances aura control, UI, and integrations - #2353
Merged
Merged
Conversation
…o tokens Roll20's September 2026 update added Hex, Circle Border, Square Border and Hex Border auras alongside Circle and Square. HealthColors only knew Circle and Square, and its Aura 1 shape setting was display-only: it was shown in the menu but never written to a token. Add AURA_SHAPES with all six Roll20 shapes and their aura1_options API values, plus three HealthColors choices: Auto (Hex on hex-grid pages once the radius fills a grid cell, Circle otherwise, because Roll20 draws hex auras in whole cells and a smaller hex ring would be invisible), Auto Border (the outline versions) and Keep (never change a token's shape). normalizeShape now accepts a label, the API value or a spacing/punctuation variant, so "Circle Border", "circleborder" and "circle-border" all work, including from chat. In aura mode tokenSet now writes the resolved aura1_options, adds an alpha channel for the new opacity setting (!aura opacity <1-100>, default 100 = solid) and, with the new player lock (!aura lock, default on), turns off the token's "players can edit Aura 1" option. Switching to tint mode releases Aura 1 through releaseAura1: the ring is cleared, its shape returns to Circle unless Shape is Keep, and players can edit it again. Changing the radius, shape, opacity or lock repaints every token straight away, and the colour match used when clearing a ring allows for the alpha channel. Upgrading must not reshape auras set by hand: migrateAuraShapeState switches a stored shape that is still the old default Circle to Keep on first load. Any other stored shape was a deliberate choice and is now applied. New installs default to Auto. Add opacity and lock rows to the GM menu and settings snapshot, list the new shapes in the shape prompts, label aura radii in page units, describe Aura 1 colour and the Aura 2 settings as reference values that are never applied, and add the auraOpacity and auraLockPlayers One-Click options. script.json declares the new options, the extended shape lists and the aura1_options, aura1_square, playersedit_aura1 and page.grid_type properties. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Roll20 games can raise "Maximum Token Bubbles/Bars" to 4, but HealthColors only accepted bars 1 to 3 as the bar holding hit points. Accept bar 4 in !aura bar, the GM menu prompt and the auraBar One-Click option, and make the invalid-bar message explain that bar 4 needs the game setting raised to 4. script.json lists bar4 for auraBar and declares the graphic.bar4_value, bar4_max and bar4_link properties. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…ialog is saved Saving the token settings dialog can overwrite an aura that HealthColors applied while the dialog was open. Because the token's HP, size and bar linkage had not changed, handleToken treated the save as irrelevant and the health aura or tint was lost until the next HP change. Treat a change to the Aura 1 radius, colour, shape (aura1_options or aura1_square) or visibility, or to the tint in tint mode, as relevant, so HealthColors re-applies its colour. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
… HP marker HealthColors 1.7.1 registered with SmartAoE.ObserveTokenChange, but the v2.0.0 rewrite only kept the TokenMod hook. Roll20 does not report changes made by another script as token changes, so area damage or healing applied by SmartAoE left health colours and dead markers stale. Register handleTokenChange with every installed observer script (TokenMod and SmartAoE) through registerTokenObservers, and log which ones are observed at startup. Registration now happens once per sandbox start: checkInstall also runs after !aura reset, and registering again made every TokenMod change process twice, with double FX. When a token at 0 HP carries the zeroHPmarker of a SmartAoE AoE, let that marker stand: HealthColors adds no dead marker (the death sound still plays) and, with Death Save Integration, no dying marker, while stable and dead results still show. HealthColors never removes SmartAoE's marker. The markers are read from SmartAoE.ZeroHPMarkers() where available (SmartAoE 1.0.0, which also covers --instant AoEs that are deleted before their damage lands) and from SmartAoE's saved AoEs otherwise, and are remembered for the session. The rule is off when SmartAoE is not installed. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
!aura update threw an error when nothing was selected, or when a drawing rather than a token was selected, because it read msg.selected without checking it. Only update selected graphics that still exist. With none, whisper a reminder to select a token first; otherwise whisper how many tokens were updated and list their names, escaped for chat. The update and settings commands no longer trigger the "UPDATING TOKENS..." whisper. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
GMs had no in-game reference for HealthColors beyond the menu itself. Create a GM-only "HealthColors — Help & Reference" handout in the Journal. It has an overview, the command list (from the same list the script uses), aura shapes and appearance, colour palettes with swatches, an attribute reference (USECOLOR, USEBLOOD and USEHEAL), optional integrations (Death Save Integration, TokenMod and SmartAoE with whether each is detected, attribute scripts, One-Click options and the script API), tips and troubleshooting, and a "Current settings" table. Its body text inherits the journal's colour so it reads in both Roll20 light and dark mode. The handout is rebuilt each time the script loads and after every setting change. !aura handout rebuilds it on demand and whispers a link to it. script.json declares the handout properties used. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
The GM menu was one long right-aligned list of white-on-gradient buttons, the settings snapshot was a separate copy of the same layout, and there was no quick way to re-colour only the selected tokens. Build both from buildSettingsPanel, so the menu and the !aura settings snapshot always show the same settings in the same layout. The menu gains an action bar (Update Selected, Refresh All and Post Settings), titled sections (General, Tracking & markers, Nameplates as a GM/Players by PCs/NPCs grid, Aura 1 ring, Effects & sound, Death Save Integration and Reference values), aligned label and control rows, dark text on a light background, colour swatches on colour settings, long death-save field lists summarised with the full list as a tooltip, and a footer with Open Help and Rebuild Help buttons. Replace the old pill and button helpers (makePill, toggleBtn, nameBtn, boolPill, namePill and fxSettingStyle) with menuControl, menuToggle, menuName, menuSection, menuRow, menuNote and listSummary, and let the Beacon sandbox note take the menu's warning style. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
…ting checklist README: add the !aura handout, opacity, lock and update commands and the new shapes to the command table; add Help Handout, Aura Shapes & Appearance, Attribute Reference (now including USECOLOR) and Optional Integrations sections, with Death Save Integration moved under the latter alongside TokenMod, SmartAoE, attribute scripts, One-Click options and the script API; turn the palette list into a table with hex values; and extend Tips & Troubleshooting. TESTING.md: add checks for the redesigned menu and Update Selected, the help handout, bar 4, every aura shape including Auto and Keep, opacity, the player lock, the upgrade migration, the token settings dialog fix, the release of Aura 1 in tint mode, and the SmartAoE integration and 0 HP marker rule. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Bump the version to 2.4.0 in the script header, VERSION and UPDATED, and in script.json, adding 2.3.0 to the previous versions. Record the release in the changelog: the six aura shapes, opacity, player lock, bar 4, the redesigned GM menu and the help handout, the shape migration and other changes, and the SmartAoE, observer, !aura update and token settings dialog fixes. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Add HealthColors/2.4.0/HealthColors.js, a byte-identical copy of the root script at version 2.4.0, matching the per-version folders kept for earlier releases. Signed-off-by: Steve Roberts <steve@shadowcomputers.co.uk>
Alicekb
approved these changes
Oct 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This release expands token health visualisations with new aura controls, provides a redesigned GM settings menu for improved usability, and restores critical integration with SmartAoE, ensuring token colours and markers remain consistent. A comprehensive in-game help handout guides GMs through all features and troubleshooting.
Features
Hex,Circle Border,Square Border,Hex Border), plusAuto/Auto Border(dynamically selects shape based on page grid and radius) andKeep(preserves existing token shape).!aura opacityto set the Aura 1 health ring's transparency.!aura lockto prevent controlling players from accidentally editing Aura 1 when the script manages it.bar4as the health bar, accommodating campaigns with increased token bubble/bar limits.!auramenu with a clearer layout, grouped settings, action buttons (Update Selected,Refresh All,Post Settings), and colour swatches for visual settings.Improvements
Circleshape are migrated toKeepto prevent unintended changes.Fixes
zeroHPmarkerby not adding a duplicate dead or dying marker if SmartAoE has already applied its own.!aura updateRobustness:!aura updatenow gracefully handles selections without tokens, providing a clear message.Breaking Changes
None.
Signed-off-by: Steve Roberts steve@shadowcomputers.co.uk